gns3-server/docs/gns3-copilot/template-based-configuration-roadmap.md

This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.

Template-Based System with HITL - Future Roadmap

Status: 💡 Proposed Target Version: Next Release Last Updated: 2026-03-20

Overview

This document outlines the plan for implementing template-based systems with Human-in-the-Loop (HITL) confirmations for both device configuration and node creation in GNS3 AI Copilot.

Scope & Positioning

This system focuses on baseline configuration and topology provisioning - getting from zero to a manageable state. Once devices are connected and have basic IP/routing configuration, modern network management tools can take over for production-grade configuration management.

┌─────────────────────────────────────────────────────────────┐
│ Phase 1: Environment Preparation (This System)              │
│ ─────────────────────────────────────────────────────────── │
│ • Create topology (nodes + links)                           │
│ • Baseline IP configuration                                 │
│ • Enable routing protocols (OSPF/BGP)                       │
│ • Management access (SSH/HTTPS/NETCONF)                     │
│ • Basic security (ACLs, passwords)                          │
│ ─────────────────────────────────────────────────────────── │
│ Result: Manageable network ready for production tools       │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ Phase 2: Production Configuration (External Tools)          │
│ ─────────────────────────────────────────────────────────── │
│ • Terraform (Infrastructure as Code)                        │
│ • REST API (Modern device management)                       │
│ • NETCONF/YANG (Standardized configuration)                 │
│ • Network Controllers (SDN, APIC, etc.)                     │
│ • Monitoring & Observability                                │
└─────────────────────────────────────────────────────────────┘

Use Cases for This System:

• Rapid lab provisioning (training, testing, CI/CD)
• Network simulation and research
• Proof-of-concept deployments
• Disaster recovery drills
• Initial topology setup before handoff to automation tools

Not In Scope (handled by other tools):

• Fine-grained configuration management
• Compliance and policy enforcement
• Continuous configuration drift management
• Production-grade change management
• Advanced telemetry and monitoring

Motivation

Current Configuration Challenges

The current implementation requires AI to generate complete configuration commands for every device, which:

• Consumes excessive tokens: Each device configuration is generated independently (~150 tokens/device × 10 devices = 1500 tokens)
• Lacks user control: Configurations are executed immediately without human review
• No reusability: Similar configurations must be regenerated from scratch
• Higher error risk: Direct execution without preview or confirmation

Current Node Creation Challenges

Similarly, creating multiple nodes has significant inefficiencies:

• Token waste: Each node creation requires ~50 tokens for tool calls (100 nodes = 5000 tokens)
• Slow execution: Nodes are created serially or with limited parallelism
• No batch operations: Cannot create groups of related nodes efficiently
• Manual positioning: Each node must be positioned individually

Proposed Solution

Implement a unified template-based HITL workflow for both configuration and node creation:

1. AI generates template → Human reviews and confirms
2. AI generates parameters (optional) → Human reviews and confirms
3. Local execution → Results displayed

Expected Benefits:

• 98-99% token savings for large-scale operations (1000+ devices/nodes)
• 90%+ time savings through parallel execution and batch operations
• Full user control with preview and confirmation at every step
• Template reusability across similar operations

---

Architecture Design

Workflow Diagram

User Request: "Configure OSPF on all routers"
                    ↓
┌─────────────────────────────────────────────────────────────┐
│ Step 1: AI Generates Jinja2 Template                         │
│                                                              │
│ Output:                                                      │
│ {                                                            │
│   "template_content": "router ospf {{ pid }}\n...",         │
│   "description": "OSPF basic configuration",                │
│   "params_schema": {                                         │
│     "process_id": "int - OSPF process ID",                  │
│     "networks": "List[Dict] - network list",                │
│     "area": "str - area ID"                                 │
│   }                                                          │
│ }                                                            │
└─────────────────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────────────────┐
│ 🔵 HITL Checkpoint 1: Template Review                       │
│                                                              │
│ User sees:                                                  │
│ - Template content (Jinja2 syntax)                          │
│ - Parameter schema                                          │
│ - Example rendered output                                   │
│                                                              │
│ Options: [✓ Confirm] [✏️ Modify] [❌ Cancel]                 │
└─────────────────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────────────────┐
│ Step 2: AI Generates Parameters                             │
│                                                              │
│ Output:                                                      │
│ {                                                            │
│   "project_id": "uuid-xxx",                                  │
│   "device_params": [                                         │
│     {                                                        │
│       "device_name": "R1",                                   │
│       "process_id": 1,                                       │
│       "networks": [{"ip": "192.168.1.0", "mask": "0.0.0.255"}], │
│       "area": "0"                                            │
│     },                                                       │
│     ... // More devices                                      │
│   ]                                                          │
│ }                                                            │
└─────────────────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────────────────┐
│ 🔵 HITL Checkpoint 2: Parameter Review                      │
│                                                              │
│ User sees:                                                  │
│ - Parameter preview per device                              │
│ - Rendered configuration commands                           │
│ - Summary of changes                                         │
│                                                              │
│ Options: [✓ Execute] [✏️ Modify] [👁️ Preview] [❌ Cancel]    │
└─────────────────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────────────────┐
│ Step 3: Local Rendering & Execution                         │
│                                                              │
│ Process:                                                     │
│ 1. Render template with parameters (0 tokens)               │
│ 2. Call existing ExecuteMultipleDeviceConfigCommands        │
│ 3. Return execution results                                  │
└─────────────────────────────────────────────────────────────┘

Token Consumption Comparison

Scenario: Configure OSPF on 10 Cisco Routers

Approach	Token Usage	Breakdown
Current Method	~1500 tokens	150 tokens/device × 10 devices
Template Method	~400 tokens	Template: 150 + Parameters: 250
Savings	73%	1100 tokens saved

Scenario: Configure VLANs on 20 Switches

Approach	Token Usage	Breakdown
Current Method	~1600 tokens	80 tokens/switch × 20 switches
Template Method	~400 tokens	Template: 100 + Parameters: 300
Savings	75%	1200 tokens saved

🔥 Scenario: Large-Scale Topology - 500+ Routers

This is where the template-based approach truly shines for rapid environment provisioning.

Approach	Token Usage	Execution Time	Breakdown
Current Method (AI)	~75,000 tokens	~25 minutes	150 tokens/device × 500 devices, serial execution
Template + AI	~5,000 tokens	~10 minutes	Template once + AI generates params, but slow
Template + Rules (Direct)	~400 tokens	~3 minutes	Template once + rule engine (0 tokens) + parallel execution
Savings	99.5%	88%	Game-changing for large deployments

Key Insight: For environments with hundreds or thousands of nodes, the direct execution mode (skipping AI) becomes critical for rapid topology preparation.

---

Core Components

System Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                         GNS3 Web UI / CLI                          │
└──────────────────────────────┬──────────────────────────────────────┘
                               │ HTTP/WebSocket
                               ↓
┌─────────────────────────────────────────────────────────────────────┐
│                       GNS3 Server (FastAPI)                         │
│                                                                      │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │
│  │ Chat API    │  │ Template API │  │  SSE Progress Stream      │  │
│  │ (existing)  │  │ (new)        │  │  (new)                    │  │
│  └──────┬──────┘  └──────┬───────┘  └──────────┬───────────────┘  │
│         │                │                     │                   │
│         └────────────────┴─────────────────────┘                   │
│                               │                                     │
└───────────────────────────────┼─────────────────────────────────────┘
                                │
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│                   AI Copilot Agent (LangGraph)                      │
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │              HITL Workflow Orchestrator                       │  │
│  │  ┌──────────┐    ┌──────────┐    ┌──────────┐               │  │
│  │  │ Generate │ →  │ Generate │ →  │ Execute  │               │  │
│  │  │ Template │    │ Params   │    │ Config   │               │  │
│  │  └────┬─────┘    └────┬─────┘    └────┬─────┘               │  │
│  │       │               │               │                      │  │
│  │  🔵 HITL Checkpoints (LangGraph Interrupts)                 │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                      │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                    Core Modules                               │  │
│  │  ┌──────────────┐  ┌─────────────┐  ┌──────────────────┐    │  │
│  │  │   Template   │  │   Session   │  │   Rule Engine    │    │  │
│  │  │   Renderer   │  │   Manager   │  │  (Direct Mode)   │    │  │
│  │  └──────────────┘  └─────────────┘  └──────────────────┘    │  │
│  └──────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘
                                │
                                ↓
┌─────────────────────────────────────────────────────────────────────┐
│                      GNS3 Controller & Compute                      │
│  ┌────────────┐  ┌────────────┐  ┌──────────────────────────┐     │
│  │   Node     │  │   Link     │  │    Nornir + Netmiko      │     │
│  │ Management │  │ Management │  │    (Config Execution)    │     │
│  └────────────┘  └────────────┘  └──────────────────────────┘     │
└─────────────────────────────────────────────────────────────────────┘

HITL State Transition Diagram

                    ┌─────────────┐
                    │    IDLE     │
                    └──────┬──────┘
                           │ User Request
                           ↓
                    ┌─────────────┐
                    │  GENERATING │
                    │  TEMPLATE   │
                    └──────┬──────┘
                           │ AI Complete
                           ↓
                    ┌─────────────────────────────────┐
                    │      🔵 TEMPLATE_REVIEW        │
                    │      (LangGraph Interrupt)      │
                    │                                 │
                    │  User sees:                     │
                    │  - Template content             │
                    │  - Parameter schema             │
                    │  - Example output               │
                    │                                 │
                    │  Actions:                       │
                    │  [Confirm] [Modify] [Cancel]    │
                    └─────┬───────────────┬───────────┘
                          │               │
                Confirm   │               │ Cancel
                          │               ↓
                    ┌──────┴──────┐   ┌────────┐
                    │ GENERATING  │   │  END   │
                    │  PARAMS     │   └────────┘
                    └──────┬──────┘
                           │ AI Complete OR
                           │ Rule Engine
                           ↓
                    ┌─────────────────────────────────┐
                    │      🔵 PARAMS_REVIEW          │
                    │      (LangGraph Interrupt)      │
                    │                                 │
                    │  User sees:                     │
                    │  - Device list                  │
                    │  - Parameters per device        │
                    │  - Rendered configs             │
                    │                                 │
                    │  Actions:                       │
                    │  [Execute] [Modify] [Cancel]    │
                    └─────┬───────────────┬───────────┘
                          │               │
                Execute   │               │ Cancel
                          │               ↓
                    ┌──────┴──────┐   ┌────────┐
                    │  EXECUTING  │   │  END   │
                    │  (0 tokens) │   └────────┘
                    └──────┬──────┘
                           │ Complete
                           ↓
                    ┌─────────────┐
                    │  COMPLETED  │
                    └─────────────┘

Component Overview

1. LangChain Tools (3 new tools)

GenerateConfigTemplate

• Purpose: Generate Jinja2 templates for human review
• Input: project_id, device_type, requirement
• Output: template_content, description, params_schema, rendered_example
• Token Cost: ~150-200 tokens

GenerateTemplateParams

• Purpose: Generate parameters for confirmed templates
• Input: project_id, confirmed_template, topology_context
• Output: device_params array with rendered previews
• Token Cost: ~50-100 tokens/device (or 0 with rule engine)

ExecuteTemplateBasedConfig

• Purpose: Execute configuration from templates (local rendering)
• Input: project_id, confirmed_template, confirmed_params
• Output: execution results per device
• Token Cost: 0 tokens (pure local execution)

2. Template Renderer Module

Key Features:

• Jinja2-based configuration rendering
• Preserves network config indentation
• Supports conditionals, loops, filters
• Zero token consumption (local execution)

Supported Template Features:

# Variables
hostname {{ hostname }}

# Loops
{% for interface in interfaces %}
interface {{ interface.name }}
 ip address {{ interface.ip }} {{ interface.mask }}
{% endfor %}

# Conditionals
{% if ospf_enabled %}
router ospf {{ process_id }}
 network {{ networks }} area {{ area }}
{% endif %}

# Filters
{{ ip | ip_network }}  # Custom filter for IP operations

3. Session State Management

Stores:

• Confirmed templates (awaiting params)
• Template metadata (schema, description)
• Session history (for audit trail)
• User modification tracking

Lifecycle:

1. Created when template generated
2. Updated when user confirms/modifies
3. Cleared after execution or cancellation
4. TTL: 24 hours (auto-cleanup)

4. LangGraph Workflow Integration

Interrupt Mechanism:

# LangGraph interrupt points for HITL
@interrupt
def template_review_checkpoint(state):
    """Pause and wait for user confirmation."""
    return {
        "type": "template_review",
        "data": state["generated_template"]
    }

@interrupt
def params_review_checkpoint(state):
    """Pause and wait for user confirmation."""
    return {
        "type": "params_review",
        "data": state["generated_params"]
    }

State Management:

• State persisted across interrupts
• User can modify state before resuming
• Full audit trail of all transitions

---

UI/UX Design

Template Review Interface

┌────────────────────────────────────────────────────────────────┐
│ 📋 AI-Generated Configuration Template                         │
│ ────────────────────────────────────────────────────────────── │
│                                                                 │
│ Device Type: Cisco IOS                                          │
│ Description: OSPF basic configuration                          │
│                                                                 │
│ Template Content:                                               │
│ ┌─────────────────────────────────────────────────────────┐   │
│ │ router ospf {{ process_id }}                             │   │
│ │ {% for network in networks %}                            │   │
│ │  network {{ network.ip }} {{ network.mask }} area {{ area }} │   │
│ │ {% endfor %}                                             │   │
│ └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│ Parameter Schema:                                               │
│ • process_id: int - OSPF process ID                            │
│ • networks: List[Dict] - Network configurations                │
│   - ip: str - Network address                                  │
│   - mask: str - Wildcard mask                                  │
│ • area: str - OSPF area ID                                     │
│                                                                 │
│ Example Output:                                                 │
│ ┌─────────────────────────────────────────────────────────┐   │
│ │ router ospf 1                                            │   │
│ │  network 192.168.1.0 0.0.0.255 area 0                    │   │
│ │  network 10.0.0.0 0.255.255.255 area 0                   │   │
│ └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│ [✓ Confirm & Continue]  [✏️ Request Modification]  [❌ Cancel]  │
└────────────────────────────────────────────────────────────────┘

Parameter Review Interface

┌────────────────────────────────────────────────────────────────┐
│ 📊 Configuration Parameters Preview                            │
│ ────────────────────────────────────────────────────────────── │
│                                                                 │
│ Total Devices: 3                                               │
│ Template: OSPF basic configuration                             │
│                                                                 │
│ ┌─────────────────────────────────────────────────────────┐   │
│ │ Device: R1                                               │   │
│ │ ─────────────────────────────────────────────────────── │   │
│ │ • process_id: 1                                          │   │
│ │ • area: 0                                                │   │
│ │ • networks:                                              │   │
│ │   - 192.168.1.0/24 → area 0                             │   │
│ │   - 10.0.0.0/8 → area 0                                 │   │
│ │                                                          │   │
│ │ Rendered Configuration:                                  │   │
│ │ router ospf 1                                           │   │
│ │  network 192.168.1.0 0.0.0.255 area 0                   │   │
│ │  network 10.0.0.0 0.255.255.255 area 0                  │   │
│ └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│ ┌─────────────────────────────────────────────────────────┐   │
│ │ Device: R2                                               │   │
│ │ ...                                                      │   │
│ └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│ [✓ Execute Configuration]  [✏️ Modify Parameters]               │
│ [👁️ Preview All]  [❌ Cancel]                                  │
└────────────────────────────────────────────────────────────────┘

---

API Design & Data Flow

REST API Endpoints

POST /api/v3/projects/{project_id}/templates/config
  ├─ Request: { "device_type": "cisco_ios", "requirement": "Configure OSPF" }
  └─ Response: { "template_id": "uuid", "template_content": "...", "params_schema": {...} }

PUT /api/v3/projects/{project_id}/templates/{template_id}/confirm
  ├─ Request: { "action": "confirm" | "modify", "modifications": {...} }
  └─ Response: { "status": "confirmed", "next_step": "generate_params" }

POST /api/v3/projects/{project_id}/templates/{template_id}/params
  ├─ Request: { "mode": "ai" | "direct" }
  └─ Response: { "device_params": [...], "preview": {...} }

POST /api/v3/projects/{project_id}/templates/{template_id}/execute
  ├─ Request: { "confirmed_params": [...] }
  └─ Response: { "execution_id": "uuid", "status": "executing" }

GET /api/v3/projects/{project_id}/templates/{template_id}/status
  └─ Response: { "status": "completed", "progress": 100, "results": [...] }

DELETE /api/v3/projects/{project_id}/templates/{template_id}
  └─ Response: { "status": "cancelled" }

SSE Progress Stream

// Server-Sent Events for real-time progress
// Endpoint: GET /api/v3/projects/{project_id}/templates/{template_id}/stream

// Event Types:
event: template_generated
data: {"template_id": "uuid", "content": "..."}

event: params_generated
data: {"total_devices": 100, "params": [...]}

event: execution_progress
data: {
  "type": "batch_complete",
  "batch": 5,
  "total_batches": 10,
  "progress": 50,
  "success": 48,
  "failed": 2,
  "current_device": "R50"
}

event: execution_complete
data: {
  "total_devices": 100,
  "success": 98,
  "failed": 2,
  "duration_sec": 180
}

Data Flow Diagram

User Request
    ↓
┌─────────────────────────────────────────────────────────────┐
│ 1. API Layer (FastAPI)                                      │
│    - Validates request                                      │
│    - Creates session state                                  │
│    - Returns template_id                                    │
└──────────────────────┬──────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. AI Agent (LangGraph)                                     │
│    - Generate template (LLM call)                           │
│    - Store in session manager                              │
│    - Trigger interrupt 🔵                                   │
└──────────────────────┬──────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. HITL Checkpoint (Frontend Display)                       │
│    - Show template to user                                  │
│    - Wait for user action                                   │
│    - [Confirm] [Modify] [Cancel]                            │
└──────────────────────┬──────────────────────────────────────┘
                       ↓ (User confirms)
┌─────────────────────────────────────────────────────────────┐
│ 4. AI Agent (LangGraph Resumes)                             │
│    Path A: Generate params (LLM) ~5000 tokens              │
│    Path B: Rule engine (0 tokens) ⚡                         │
│    - Trigger interrupt 🔵                                   │
└──────────────────────┬──────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. HITL Checkpoint (Frontend Display)                       │
│    - Show parameters to user                                │
│    - Render configuration preview                          │
│    - [Execute] [Modify] [Cancel]                            │
└──────────────────────┬──────────────────────────────────────┘
                       ↓ (User executes)
┌─────────────────────────────────────────────────────────────┐
│ 6. Execution Engine (Local, 0 tokens)                       │
│    - Render templates (Jinja2)                              │
│    - Batch execution (Nornir + Netmiko)                    │
│    - Stream progress via SSE                                │
└──────────────────────┬──────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────────┐
│ 7. Result Aggregation                                       │
│    - Collect results from all devices                      │
│    - Generate summary report                               │
│    - Clean up session state                                │
└──────────────────────┬──────────────────────────────────────┘
                       ↓
                  Return to User

Error Handling Flow

┌─────────────────────────────────────────────────────────────┐
│ Error Detection at Each Stage                               │
└─────────────────────────────────────────────────────────────┘

Template Generation Error:
    ├─ Invalid Jinja2 syntax → [AI Retry] + [Show Error Context]
    ├─ Incomplete template → [Request Clarification]
    └─ LLM timeout → [Retry] + [Fallback to template library]

Parameter Generation Error:
    ├─ Missing device data → [Fetch from topology]
    ├─ Invalid parameter values → [Validation Error] → [User Correction]
    └─ Rule engine failure → [Fallback to AI generation]

Execution Error:
    ├─ Device unreachable → [Retry 3x] → [Mark as failed] → [Continue]
    ├─ Invalid command → [Show error] → [Suggest fix] → [User decision]
    └─ Authentication failure → [Pause] → [Request credentials]

Error Recovery Strategies:
    ├─ Automatic retry (transient errors)
    ├─ Partial success handling (continue with remaining devices)
    ├─ Rollback support (undo partial changes)
    └─ User notification (SSE + UI alerts)

Template Lifecycle Management

┌─────────────────────────────────────────────────────────────┐
│                      Template Lifecycle                      │
└─────────────────────────────────────────────────────────────┘

1. DRAFT
   ├─ Created by AI
   ├─ Stored in session (temporary)
   └─ User reviews and modifies

2. CONFIRMED
   ├─ User approved template
   ├─ Stored in template library (persistent)
   └─ Ready for parameter generation

3. ACTIVE
   ├─ Parameters generated
   ├─ Ready for execution
   └─ Can be cloned for similar tasks

4. EXECUTED
   ├─ Configuration applied
   ├─ Results recorded
   └─ Move to archive

5. ARCHIVED
   ├─ Historical record
   ├─ Analytics data
   └─ Cleanup after 90 days

Version Control:
    ├─ Each save creates new version
    ├─ Semantic versioning (v1.0, v1.1, v2.0)
    ├─ Diff view between versions
    └─ Rollback to previous version

---

🔥 Large-Scale Topology Support (1000+ Nodes)

Overview

One of the most powerful use cases for the template-based configuration system is rapid provisioning of large-scale network topologies. This section details optimizations for environments with hundreds to thousands of nodes.

Challenge: Traditional AI Approach at Scale

Problem: Configure 1000 routers with OSPF

Traditional AI Approach:
- AI generates config for each router: 150 tokens × 1000 = 150,000 tokens
- Serial or limited parallel execution: ~30-50 minutes
- High cost, slow execution, poor scalability

Solution: Direct Execution Mode

The key innovation is allowing users to modify and directly execute templates without requiring AI re-analysis:

Template-Based Direct Execution:
1. AI generates template once: ~150 tokens
2. User reviews and modifies if needed
3. User clicks "⚡ Confirm & Execute"
4. Rule engine generates params for 1000 devices: 0 tokens
5. Parallel execution (50-100 concurrent): ~5 minutes
6. Total: 150 tokens, 5 minutes

Enhanced HITL Workflow for Scale

┌─────────────────────────────────────────────────────────────┐
│ Step 1: AI Generates Template (Once)                         │
│                                                              │
│ User: "Configure OSPF on all 1000 routers"                   │
│                                                              │
│ AI generates template: ~150 tokens                           │
│ router ospf {{ process_id }}                                 │
│ {% for network in networks %}                                │
│  network {{ network.ip }} {{ network.mask }} area {{ area }} │
│ {% endfor %}                                                 │
└─────────────────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────────────────┐
│ 🔵 HITL Checkpoint 1: Template Review                        │
│                                                              │
│ User can:                                                    │
│ - Review template syntax                                     │
│ - Modify template directly                                  │
│ - See preview with sample data                               │
│                                                              │
│ Actions: [✓ Confirm & Continue]  [⚡ Confirm & Execute*]     │
│          [✏️ Modify]  [❌ Cancel]                             │
│                                                              │
│ * "Confirm & Execute" = Skip AI, go to rule engine           │
└─────────────────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────────────────┐
│ Step 2A: Rule Engine (0 tokens) OR Step 2B: AI (5000 tokens)│
│                                                              │
│ If user chose "⚡ Confirm & Execute":                        │
│   → Rule engine analyzes template                            │
│   → Extracts device names from topology                      │
│   → Auto-assigns IPs and parameters                          │
│   → Generates 1000 device param sets: 0 tokens               │
│                                                              │
│ If user chose "✓ Confirm & Continue":                       │
│   → AI analyzes template                                     │
│   → Generates parameters: ~5000 tokens                       │
└─────────────────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────────────────┐
│ 🔵 HITL Checkpoint 2: Parameter Review                       │
│                                                              │
│ For 1000 devices, show SUMMARY:                              │
│ - Total devices: 1000                                        │
│ - Configuration patterns: 3 unique patterns                 │
│ - Sample configs (first 3 devices)                           │
│ - IP addressing scheme used                                  │
│                                                              │
│ Actions: [⚡ Execute All*]  [✓ Review & Modify]  [❌ Cancel] │
│                                                              │
│ * "Execute All" = Start parallel execution                   │
└─────────────────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────────────────┐
│ Step 3: Parallel Batch Execution                             │
│                                                              │
│ Configuration execution:                                     │
│ - Batch size: 50 devices (configurable)                      │
│ - Batches: 20 total (1000 / 50)                              │
│ - Parallel execution within each batch                       │
│ - Real-time progress updates via SSE                         │
│ - Estimated time: 3-5 minutes                                │
│                                                              │
│ Progress updates:                                             │
│ Batch 1/20: Configuring devices 1-50...                      │
│ Batch 2/20: Configuring devices 51-100...                    │
│ ...                                                          │
│ Complete: 998 success, 2 failed                              │
└─────────────────────────────────────────────────────────────┘

Rule Engine: Intelligent Parameter Generation

Concept: Use rule-based logic instead of AI for generating parameters in large topologies.

How It Works:

Input: Template + Topology (1000 devices)
         ↓
    Rule Engine (0 tokens)
         ↓
    Device Analysis
    ├─ Extract numbering from names (R1 → 1, R2 → 2, ...)
    ├─ Group by device type (routers, switches, firewalls)
    ├─ Apply addressing scheme (sequential, VLAN-based, hierarchical)
    └─ Generate parameters for each device
         ↓
Output: 1000 device parameter sets (< 1 second)

Addressing Schemes:

1. Sequential (Default)
   R1: 192.168.1.0/24
   R2: 192.168.2.0/24
   ...
   R1000: 192.168.1000.0/24

2. VLAN-Based
   VLAN 100: 10.0.100.0/24
   VLAN 101: 10.0.101.0/24
   ...

3. Hierarchical
   Core routers: 10.0.0.0/24
   Distribution: 10.1.0.0/16
   Access switches: 10.100.0.0/16

4. Device Type Based
   Routers: 192.168.0.0/16
   Switches: 192.169.0.0/16
   Firewalls: 192.170.0.0/16

Batch Parallel Execution

Dynamic Batching Strategy:

Device Count    Batch Size    Concurrency    Estimated Time
────────────────────────────────────────────────────────────
1-10            10            10             < 30 seconds
11-50           20            20             < 1 minute
51-100          30            30             1-2 minutes
101-500         50            50             2-5 minutes
500+            100           100            3-8 minutes

Execution Flow:

┌─────────────────────────────────────────────────────────────┐
│ Batch 1: Devices 1-100                                       │
│ ├─ Render 100 configs (Jinja2, local)                        │
│ ├─ Execute in parallel (Nornir + Netmiko)                   │
│ ├─ Collect results                                           │
│ └─ Stream progress: "Batch 1/10 complete, 35% done"         │
├─────────────────────────────────────────────────────────────┤
│ Batch 2: Devices 101-200                                     │
│ └─ ...                                                       │
├─────────────────────────────────────────────────────────────┤
│ ...                                                          │
├─────────────────────────────────────────────────────────────┤
│ Batch 10: Devices 901-1000                                   │
│ └─ Complete: 997 success, 3 failed                          │
└─────────────────────────────────────────────────────────────┘

Configuration Summary for Large Topologies

Challenge: Showing 1000 device configurations is impractical.

Solution: Intelligent summaries with pattern analysis.

┌─────────────────────────────────────────────────────────────┐
│ Configuration Summary: 1000 Devices                          │
├─────────────────────────────────────────────────────────────┤
│ Total Devices:        1,000                                  │
│ Unique Patterns:      3                                     │
│ Total Config Lines:   ~15,000                               │
│ Estimated Time:       ~5 minutes                            │
├─────────────────────────────────────────────────────────────┤
│ Pattern Analysis:                                              │
│ • Pattern A (650 devices): Standard OSPF config             │
│ • Pattern B (300 devices): OSPF + BGP                       │
│ • Pattern C (50 devices):  OSPF + BGP + MPLS                │
├─────────────────────────────────────────────────────────────┤
│ Sample Configurations (first 3):                             │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Device: R1 (Pattern A)                                  │ │
│ │ router ospf 1                                          │ │
│ │  network 192.168.1.0 0.0.0.255 area 0                  │ │
│ │  network 10.1.1.1 0.0.0.0 area 0                       │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Device: R2 (Pattern A)                                  │ │
│ │ [Similar to R1, different IPs]                          │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ...                                                          │
└─────────────────────────────────────────────────────────────┘

Performance Benchmarks

Scenario: 1000 Router OSPF Configuration

Metric	Traditional AI	Template + AI	Template + Direct
Token Consumption	150,000	5,000	400
Execution Time	30-50 min	10-15 min	3-5 min
Cost (at $10/M tokens)	$1.50	$0.05	$0.004
User Control	Low	Medium	High
Parallel Execution	Limited	Yes	Yes (100 concurrent)

Scenario: 5000 Switch VLAN Configuration

Metric	Traditional AI	Template + Direct
Token Consumption	400,000	400
Execution Time	2-3 hours	15-20 min
Cost	$4.00	$0.004
Scalability	Poor	Excellent

Addressing Schemes for Large Topologies

The rule engine supports multiple automatic addressing schemes:

# 1. Sequential Addressing (Default)
# R1: 192.168.1.0/24, R2: 192.168.2.0/24, ..., R1000: 192.168.1000.0/24

# 2. VLAN-Based Addressing
# VLAN 100: 10.0.100.0/24, VLAN 101: 10.0.101.0/24, ...

# 3. Hierarchical Addressing
# Core routers: 10.0.0.0/24
# Distribution routers: 10.1.0.0/16
# Access switches: 10.100.0.0/16

# 4. Device Type Based
# Routers: 192.168.0.0/16
# Switches: 192.169.0.0/16
# Firewalls: 192.170.0.0/16

Error Handling for Scale

For 1000+ devices, some failures are inevitable. The system provides:

{
    "total_devices": 1000,
    "summary": {
        "success": 987,
        "failed": 13,
        "skipped": 0
    },
    "failed_devices": [
        {
            "device_name": "R456",
            "error": "Connection timeout",
            "retry_available": true
        },
        ...
    ],
    "retry_suggestions": {
        "auto_retry": True,
        "retry_batch_size": 10,
        "exponential_backoff": True
    }
}

Use Cases for Large-Scale Support

1. Network Training Labs: Provision 1000+ device labs for student training
2. CI/CD Testing: Automated topology setup for testing network automation scripts
3. Disaster Recovery Drills: Rapid deployment of large backup topologies
4. Network Simulation: Research environments with thousands of nodes
5. Data Center Fabric: Configure spine-leaf topologies with hundreds of leaf switches

---

🔥🔥 Node Creation Templates (Batch Topology Provisioning)

Overview

Just as configuration templates enable rapid device configuration, node creation templates enable rapid topology provisioning. This is particularly valuable for:

• Training labs: Provision 100+ device labs in minutes
• Testing environments: Quickly spin up complex test topologies
• Data center simulation: Create spine-leaf fabrics with hundreds of nodes
• Network research: Deploy large-scale simulation topologies

Current vs. Template-Based Node Creation

Scenario: Create 100 Routers

Current Method:

AI calls create_node tool 100 times:
- Token cost: 50 tokens/node × 100 = 5000 tokens
- Execution time: 5-10 minutes (serial/limited parallel)
- No batch operations
- Manual positioning required

Template Method:

1. AI generates node creation template: ~100 tokens
2. User reviews and confirms template
3. Rule engine creates nodes in parallel batches: 0 tokens
4. Total: 100 tokens, 30-60 seconds

Savings: 98% tokens, 90% time

Node Creation Workflow

User Request: "Create a data center topology with 2 core routers,
              10 aggregation switches, and 100 access switches"
                    ↓
┌─────────────────────────────────────────────────────────────┐
│ Step 1: AI Generates Node Creation Template                  │
│                                                              │
│ AI Output:                                                   │
│ {                                                            │
│   "node_groups": [                                          │
│     {                                                        │
│       "node_type": "cisco_iosv",                            │
│       "count": 2,                                           │
│       "name_pattern": "Core-R{{ id }}",                     │
│       "properties": {"ram": 4096, "cpus": 2},              │
│       "position": {"y": 100, "x_spacing": 600}             │
│     },                                                       │
│     {                                                        │
│       "node_type": "cisco_iosv_l2",                         │
│       "count": 10,                                          │
│       "name_pattern": "Agg-SW{{ id }}",                    │
│       "position": {"grid": "2x5", "y": 300}                 │
│     },                                                       │
│     {                                                        │
│       "node_type": "cisco_iosv_l2",                         │
│       "count": 100,                                         │
│       "name_pattern": "Acc-SW{{ id }}",                    │
│       "position": {"grid": "10x10", "y": 600}               │
│     }                                                       │
│   ],                                                         │
│   "layout": "auto_spine_leaf",                               │
│   "resource_limits": {"max_ram_mb": 120000}                  │
│ }                                                            │
└─────────────────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────────────────┐
│ 🔵 HITL Checkpoint: Node Template Review                    │
│                                                              │
│ User sees:                                                  │
│ • Total nodes: 112                                           │
│ • Group breakdown:                                           │
│   - 2x Core routers (Core-R1, Core-R2)                      │
│   - 10x Aggregation switches (Agg-SW1 - Agg-SW10)          │
│   - 100x Access switches (Acc-SW1 - Acc-SW100)             │
│ • Resource requirements:                                     │
│   - RAM: ~120 GB                                             │
│   - vCPUs: 112                                               │
│ • Layout preview (visual diagram)                            │
│                                                              │
│ Actions: [⚡ Batch Create]  [✏️ Modify]  [❌ Cancel]         │
└─────────────────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────────────────┐
│ Step 2: Parallel Batch Node Creation (0 tokens)             │
│                                                              │
│ Process:                                                     │
│ - Validate resources                                         │
│ - Create nodes in parallel batches (20-50 concurrent)        │
│ - Auto-position nodes using layout strategy                 │
│ - Real-time progress streaming                               │
│                                                              │
│ Progress:                                                    │
│ Batch 1/6: Creating 20 nodes...                             │
│ Batch 2/6: Creating 20 nodes...                             │
│ ...                                                          │
│ Complete: 112/112 nodes created successfully                 │
└─────────────────────────────────────────────────────────────┘

Node Template Schema

Concept: Define groups of similar nodes with positioning and auto-linking.

Schema Structure:

NodeCreationTemplate
├─ node_groups: List[NodeGroup]
│   ├─ node_type: "cisco_iosv" | "vpcs" | ...
│   ├─ count: 100
│   ├─ name_pattern: "R{{ id }}"  → R1, R2, ..., R100
│   ├─ properties: {ram, cpus, adapters}
│   └─ position: {strategy, grid, spacing}
├─ layout: "auto_grid" | "auto_spine_leaf" | "auto_star" | ...
├─ auto_link: AutoLinkConfig
│   └─ links: List[LinkPattern]
└─ resource_limits: {max_ram_mb, max_vcpus}

Example: Spine-Leaf Topology

{
  "node_groups": [
    {
      "name": "spine",
      "node_type": "cisco_iosv",
      "count": 4,
      "name_pattern": "Spine{{ id }}",
      "position": {"y": 100, "x_spacing": 400}
    },
    {
      "name": "leaf",
      "node_type": "cisco_iosv_l2",
      "count": 48,
      "name_pattern": "Leaf{{ id }}",
      "position": {"grid": "6x8", "y": 400}
    }
  ],
  "auto_link": {
    "links": [
      {
        "from": "spine",
        "to": "leaf",
        "strategy": "mesh"  # Each spine to all leafs
      }
    ]
  }
}

Result: 4 spine + 48 leaf + 192 links (4×48)
Time: ~2-3 minutes

Automatic Layout Strategies

┌─────────────────────────────────────────────────────────────┐
│ 1. Grid Layout (auto_grid)                                  │
│                                                              │
│   [1]  [2]  [3]  [4]  [5]                                   │
│   [6]  [7]  [8]  [9]  [10]                                  │
│   [11] [12] [13] [14] [15]                                  │
│                                                              │
│   Best for: Uniform node types, regular topologies         │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ 2. Spine-Leaf (auto_spine_leaf)                             │
│                                                              │
│   [Spine1]--------[Spine2]                                  │
│      |  |  |  |      |  |  |  |                             │
│   [Leaf1..Leaf48]  [Leaf49..Leaf96]                         │
│                                                              │
│   Best for: Data center fabrics                             │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ 3. Star (auto_star)                                         │
│                                                              │
│              [Core]                                         │
│            /  |  |  \                                       │
│        [Edge1..Edge20]                                      │
│                                                              │
│   Best for: Hub-and-spoke topologies                        │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ 4. Hierarchical (manual)                                    │
│                                                              │
│   [Core1]     [Core2]                                       │
│      |            |                                         │
│   [Agg1..Agg10]                                            │
│      /    |   |    \                                        │
│  [Acc1..Acc100]                                            │
│                                                              │
│   Best for: Enterprise campus networks                      │
└─────────────────────────────────────────────────────────────┘

Auto-Linking Strategies

Link Pattern Strategies:

┌─────────────────────────────────────────────────────────────┐
│ 1. Mesh (Full Mesh)                                         │
│                                                              │
│   [A] ←→ [B]                                                │
│    ↑ ↖  ↑ ↗                                                │
│    |  \ |  |                                                │
│   [D] ←→ [C]                                                │
│                                                              │
│   Every node connects to every other node                   │
│   Links: n×(n-1)/2                                          │
│   Best for: High availability, small groups                │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ 2. Paired (One-to-One)                                      │
│                                                              │
│   [Group A: A1, A2, A3...]                                  │
│         ↓  ↓  ↓                                            │
│   [Group B: B1, B2, B3...]                                  │
│                                                              │
│   A1→B1, A2→B2, A3→B3, ...                                 │
│   Links: min(count_A, count_B)                              │
│   Best for: Point-to-point connections                     │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ 3. Linear (Chain)                                           │
│                                                              │
│   [A1]→[A2]→[A3]→[A4]→...→[An]                             │
│                                                              │
│   Sequential connection                                     │
│   Links: n-1                                                │
│   Best for: Ring topologies, daisy-chains                  │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ 4. One-to-Many (Star)                                       │
│                                                              │
│         [Center]                                            │
│       /  |  |  \                                            │
│     [E1][E2][E3][E4]...                                      │
│                                                              │
│   Center connects to all edge nodes                         │
│   Links: count_edge                                         │
│   Best for: Hub-and-spoke                                   │
└─────────────────────────────────────────────────────────────┘

Performance Benchmarks

Scenario: 100 Router Lab

Metric	Current Method	Template Method
Token Consumption	5,000	100
Execution Time	5-10 min	30-60 sec
User Control	Low	High (preview before create)
Positioning	Manual	Automatic

Scenario: 500 Switch Data Center

Metric	Current Method	Template Method
Token Consumption	25,000	150
Execution Time	25-30 min	2-3 min
Links Created	Manual	Auto (mesh, spine-leaf)

Scenario: 1000 Node Training Lab

Metric	Current Method	Template Method
Token Consumption	50,000	200
Execution Time	50-60 min	4-6 min
Scalability	Poor	Excellent

Complete Example: Enterprise Data Center

# User Request
"""
Create an enterprise data center topology:
- 4 spine routers (high-end)
- 20 leaf switches (10G)
- 200 access switches (1G)
- 500 servers (VPCS)

Use spine-leaf architecture with full mesh connectivity.
All servers connect to access switches in pairs.
"""

# Generated Template
{
    "node_groups": [
        {
            "name": "spine",
            "node_type": "cisco_iosv",
            "count": 4,
            "name_pattern": "Spine-R{{ id }}",
            "properties": {
                "ram": 4096,
                "cpus": 2,
                "adapters": 8
            },
            "position": {
                "strategy": "hierarchical",
                "y": 100,
                "x_spacing": 600
            }
        },
        {
            "name": "leaf",
            "node_type": "cisco_iosv_l2",
            "count": 20,
            "name_pattern": "Leaf-SW{{ id }}",
            "properties": {
                "ram": 2048,
                "cpus": 1,
                "adapters": 16
            },
            "position": {
                "strategy": "grid",
                "grid_rows": 4,
                "grid_cols": 5,
                "y": 400,
                "x_spacing": 300,
                "y_spacing": 200
            }
        },
        {
            "name": "access",
            "node_type": "cisco_iosv_l2",
            "count": 200,
            "name_pattern": "Acc-SW{{ id }}",
            "properties": {
                "ram": 1024,
                "cpus": 1,
                "adapters": 4
            },
            "position": {
                "strategy": "grid",
                "grid_rows": 10,
                "grid_cols": 20,
                "y": 800,
                "x_spacing": 120,
                "y_spacing": 100
            }
        },
        {
            "name": "server",
            "node_type": "vpcs",
            "count": 500,
            "name_pattern": "Server-{{ id }}",
            "properties": {},
            "position": {
                "strategy": "grid",
                "grid_rows": 20,
                "grid_cols": 25,
                "y": 1200,
                "x_spacing": 60,
                "y_spacing": 60
            }
        }
    ],
    "auto_link": {
        "links": [
            {
                "from_group": "spine",
                "to_group": "leaf",
                "strategy": "mesh"
            },
            {
                "from_group": "leaf",
                "to_group": "access",
                "strategy": "paired",
                "count": 10
            },
            {
                "from_group": "access",
                "to_group": "server",
                "strategy": "paired",
                "count": 2
            }
        ]
    },
    "layout": "auto_spine_leaf",
    "resource_limits": {
        "max_ram_mb": 750000,
        "max_vcpus": 724
    }
}

# Execution Result
{
    "total_nodes": 724,
    "created": 724,
    "failed": 0,
    "duration_sec": 285,  # ~4.75 minutes
    "links_created": 4280,  # Auto-created
    "groups": [
        {"name": "spine", "created": 4, "failed": 0},
        {"name": "leaf", "created": 20, "failed": 0},
        {"name": "access", "created": 200, "failed": 0},
        {"name": "server", "created": 500, "failed": 0}
    ]
}

Combined Workflow: Node Creation + Configuration

The real power comes from combining both template systems:

1. Create topology with node templates
   - 724 nodes created in ~5 minutes
   - 4280 links auto-created

2. Configure devices with config templates
   - Generate OSPF/BGP templates
   - Configure 724 devices in ~5 minutes

Total: 724-node data center
  - Created and configured in ~10 minutes
  - Token cost: ~400 (vs ~100,000 with AI-only approach)
  - 99.6% token savings

---

🔥🔥🔥 Link Creation Templates (Batch Topology Connectivity)

Overview

Just as node and configuration templates enable rapid provisioning, link creation templates enable rapid connectivity setup. This completes the template trilogy for complete topology automation.

Current vs. Template-Based Link Creation

Scenario: Create Full-Mesh Network (100 Routers)

Current Method:

AI calls create_link tool 4950 times (100×99/2):
- Token cost: 30 tokens/link × 4950 = ~150,000 tokens
- Execution time: 30-40 minutes (serial/limited parallel)
- Manual port management
- Error-prone

Template Method:

1. AI generates link template: ~200 tokens
2. User reviews link patterns and topology preview
3. Rule engine creates links in parallel batches: 0 tokens
4. Total: 200 tokens, 2-3 minutes

Savings: 99.9% tokens, 95% time

Link Creation Workflow

User Request: "Create full-mesh connectivity between all routers"
                    ↓
┌─────────────────────────────────────────────────────────────┐
│ Step 1: AI Generates Link Creation Template                 │
│                                                              │
│ AI Output:                                                   │
│ {                                                            │
│   "link_patterns": [                                        │
│     {                                                        │
│       "from_nodes": {"tag": "router"},                      │
│       "to_nodes": {"tag": "router"},                        │
│       "strategy": "full_mesh",                              │
│       "port_allocation": "round_robin"                       │
│     }                                                       │
│   ],                                                         │
│   "total_links": 4950                                       │
│ }                                                            │
└─────────────────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────────────────┐
│ 🔵 HITL Checkpoint: Link Template Review                    │
│                                                              │
│ User sees:                                                  │
│ • Total links: 4,950                                         │
│ • Topology type: Full Mesh                                  │
│ • Port allocation strategy: Round-robin                     │
│ • Topology preview (visual graph)                            │
│ • Port utilization estimates                                 │
│                                                              │
│ Sample links (first 10):                                     │
│ • R1:Gi0/0 → R2:Gi0/0                                       │
│ • R1:Gi0/1 → R3:Gi0/0                                       │
│ • ...                                                        │
│                                                              │
│ Actions: [⚡ Batch Create]  [👁️ Detailed Preview]  [✏️ Modify] │
└─────────────────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────────────────┐
│ Step 2: Detailed Preview (Optional)                          │
│                                                              │
│ • Port assignment per node                                   │
│ • Bandwidth calculations                                     │
│ • Redundancy analysis                                        │
│ • Link naming scheme                                         │
│                                                              │
│ [⚡ Confirm Create All]  [🔧 Adjust Ports]  [⬅️ Back]        │
└─────────────────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────────────────┐
│ Step 3: Parallel Batch Link Creation (0 tokens)             │
│                                                              │
│ Process:                                                     │
│ - Validate port availability                                  │
│ - Allocate ports using strategy                             │
│ - Create links in parallel batches (50-100 concurrent)       │
│ - Handle conflicts automatically                              │
│ - Real-time progress streaming                               │
│                                                              │
│ Progress:                                                    │
│ Batch 1/50: Creating 99 links...                            │
│ Batch 2/50: Creating 99 links...                            │
│ ...                                                          │
│ Complete: 4,950/4,950 links created successfully              │
└─────────────────────────────────────────────────────────────┘

Link Template Schema (Simplified)

class LinkCreationTemplate(BaseModel):
    """Template for batch link creation."""

    # Link patterns
    link_patterns: List[LinkPattern]

    # Port allocation strategy
    port_allocation: PortAllocationStrategy


class LinkPattern(BaseModel):
    """Pattern for creating links between node groups."""

    from_nodes: NodeSelector  # Source nodes
    to_nodes: NodeSelector    # Destination nodes

    strategy: Literal[
        "one_to_one",        # 1:1 pairing
        "one_to_many",       # Star topology
        "many_to_many",      # Full mesh
        "sequential",        # Linear chain
        "ring"              # Ring topology
    ]

    port_allocation: PortAllocationStrategy


class NodeSelector(BaseModel):
    """Select nodes for linking."""

    selector_type: Literal["group", "name_pattern", "tag", "all"]
    group_name: Optional[str]
    name_pattern: Optional[str]  # "R*", "Core-*"
    tag: Optional[str]


class PortAllocationStrategy(BaseModel):
    """How to allocate ports for links."""

    strategy: Literal[
        "round_robin",       # Distribute evenly
        "sequential",        # Use in order
        "optimized",         # Smart allocation
        "auto"               # Automatic selection
    ]

    on_conflict: Literal[
        "skip",              # Skip if port unavailable
        "use_next",          # Use next available port
        "fail"               # Fail on conflict
    ] = "use_next"

Common Topology Patterns

The system includes pre-built topology patterns:

1. Spine-Leaf (Data Center)

Pattern: Full mesh between spine and leaf layers

Example: 4 Spine × 48 Leaf
- Links: 4 × 48 = 192 links
- Each spine: 48 downlinks
- Each leaf: 4 uplinks

2. Three-Tier Hierarchical

Core ↔ Aggregation ↔ Access

Example: 2 Core × 10 Agg × 100 Access
- Core-Agg: Full mesh (2×10 = 20 links)
- Agg-Access: Paired (10×10 = 100 links)
- Total: 120 links

3. Ring Topology

Sequential connection with wrap-around

Example: 10 routers in ring
- Links: 10 (each node connects to 2 neighbors)
- Pattern: R1→R2→R3→...→R10→R1

4. Full Mesh

All nodes connected to all nodes

Example: 10 routers
- Links: 45 (10×9/2)
- Every node connects to every other node

5. Star Topology

Center node connects to all edge nodes

Example: 1 Core + 20 Edge
- Links: 20
- Center degree: 20
- Edge degree: 1

Performance Benchmarks

Scenario: Spine-Leaf Data Center (8 Spine × 100 Leaf)

Metric	Current Method	Template Method
Token Consumption	30,000	200
Execution Time	15-20 min	2-3 min
Links Created	Manual	Auto (800 links)
Port Management	Manual	Auto (round-robin)

Scenario: Full Mesh (100 Routers)

Metric	Current Method	Template Method
Token Consumption	150,000	200
Execution Time	30-40 min	2-3 min
Links Created	4,950	4,950
Error Rate	High (manual)	Low (validated)

Scenario: Large-Scale Data Center

Topology:

• 8 Spine routers
• 100 Leaf switches (48-port each)
• 2000 Servers
• Redundant connections

Link Creation:

• Spine-Leaf: 8 × 100 = 800 links
• Leaf-Server: 2000 × 2 = 4000 links
• Total: 4,800 links

Metric	Current Method	Template Method
Token Consumption	~150,000	300
Execution Time	45-60 min	5-8 min
Savings	-	99.8% tokens, 90% time

Intelligent Port Allocation

The system includes smart port allocation algorithms:

# Example: Optimized allocation for multi-adapter switches

Strategy: "optimized"

Considerations:
- Port speed matching (10G ports for spine-leaf, 1G for servers)
- Physical adapter separation (redundancy across modules)
- Load balancing (distribute connections evenly)
- Future expansion planning (reserve ports)

Result:
- Spine-Leaf: Use 10G ports on adapter 0-3
- Leaf-Server: Use 1G ports on adapter 4-7
- Redundant paths: Use different physical adapters

Combined Workflow: Complete Topology Provisioning

Step 1: Node Creation Template
  - 2108 nodes created in ~4 minutes
  - Token cost: ~200

Step 2: Link Creation Template
  - 20,780 links created in ~6 minutes
  - Token cost: ~300

Step 3: Configuration Template
  - 2108 devices configured in ~5 minutes
  - Token cost: ~200

TOTAL: Large Data Center
  - 2,108 nodes + 20,780 links
  - Created, linked, and configured in ~15 minutes
  - Token cost: ~700 (vs ~250,000 with AI-only)
  - 99.7% token savings

Use Cases

1. Data Center Fabric: Spine-Leaf with thousands of links
2. ISP Backbone: Full-mesh core routers
3. Campus Network: Three-tier hierarchical
4. Ring Topology: Metropolitan area networks
5. Research Networks: Custom experimental topologies

---

Implementation Phases

Phase 1: Core MVP (Minimum Viable Product)

Status: 📋 Planned Estimated Effort: 3-5 days

Tasks:

1. ✅ Create ConfigTemplateRenderer class
2. ✅ Create TemplateSessionManager class
3. ✅ Implement GenerateConfigTemplate tool
4. ✅ Implement GenerateTemplateParams tool
5. ✅ Implement ExecuteTemplateBasedConfig tool
6. ✅ Create config_templates/ package structure
7. ✅ Update system prompts with template workflow
8. ✅ Basic error handling and validation

Deliverables:

• Working three-step HITL workflow
• Template rendering for Cisco IOS devices
• Basic CLI/API responses
• Unit tests for core components

Phase 2: Enhanced User Experience & Direct Execution

Status: 💡 Proposed Estimated Effort: 2-3 days

Tasks:

1. Enhanced UI for template/parameter review
2. Configuration preview functionality
3. Template modification and retry logic
4. 🔥 Direct execution mode (skip AI, use rule engine)
5. Progress indicators for multi-device configs
6. Improved error messages and recovery

Deliverables:

• User-friendly review interfaces
• Preview-before-execute capability
• Rule-based parameter generation (0 token cost)
• User documentation

Phase 2.5: Node Creation Templates

Status: 💡 Proposed Estimated Effort: 2-3 days

Tasks:

1. 🔥🔥 Implement GenerateNodeTemplate tool
2. 🔥🔥 Implement ExecuteBatchNodeCreation tool
3. 🔥🔥 Create NodeCreationTemplate schema
4. 🔥🔥 Implement automatic positioning algorithms
5. 🔥🔥 Implement auto-linking functionality
6. Resource validation before creation

Deliverables:

• Batch node creation with 0 token cost
• Auto-positioning (grid, spine-leaf, star, mesh)
• Auto-linking (mesh, paired, linear)
• Progress streaming for large batches

Phase 2.75: Link Creation Templates

Status: 💡 Proposed Estimated Effort: 2-3 days

Tasks:

1. 🔥🔥🔥 Implement GenerateLinkTemplate tool
2. 🔥🔥🔥 Implement ExecuteBatchLinkCreation tool
3. 🔥🔥🔥 Create LinkCreationTemplate schema
4. 🔥🔥🔥 Implement topology pattern library (Spine-Leaf, Ring, Mesh, Star, etc.)
5. 🔥🔥🔥 Implement intelligent port allocation algorithms
6. Port availability validation and conflict handling

Deliverables:

• Batch link creation with 0 token cost
• 5+ pre-built topology patterns
• Smart port allocation (round-robin, optimized)
• Port conflict detection and auto-resolution
• Progress streaming for thousands of links

Phase 3: Template Library & Large-Scale Support

Status: 💡 Proposed Estimated Effort: 2-3 days

Tasks:

1. Template persistence and storage
2. Pre-built template library (OSPF, BGP, VLAN, NAT, etc.)
3. 🔥 Batch parallel execution (dynamic batching for 100+ devices)
4. 🔥 Rule engine enhancements (intelligent parameter generation)
5. 🔥 Real-time progress streaming via SSE
6. Template versioning and history

Deliverables:

• 20+ pre-built templates
• Support for 1000+ device configurations
• Parallel execution with 50-100 concurrent connections
• Template management API

Phase 4: Advanced Features & Optimization

Status: 💡 Proposed Estimated Effort: 3-4 days

Tasks:

1. Multi-vendor template support (Huawei, H3C, Juniper)
2. 🔥 Intelligent addressing schemes (sequential, VLAN-based, hierarchical)
3. 🔥 Configuration summary generation (pattern analysis for large topologies)
4. Configuration diff and comparison
5. Template analytics and usage statistics
6. 🔥 Performance optimization (caching, connection pooling)

Deliverables:

• Multi-vendor template ecosystem
• Optimized for 10,000+ node topologies
• Advanced configuration management
• Analytics dashboard

---

Technical Considerations

Jinja2 Configuration

Key Settings for Network Configs:

Environment Configuration:
├─ trim_l_blocks=True       # Remove block left whitespace
├─ trim_r_blocks=True       # Remove block right whitespace
├─ lstrip_blocks=True       # Strip leading whitespace
├─ autoescape=False         # Don't escape config commands
└─ Custom Filters
   ├─ to_cidr: Convert IP+mask to CIDR
   ├─ ip_network: Parse IP network
   └─ Wildcard to CIDR conversion

Supported Template Features:

• Variables: {{ hostname }}
• Loops: {% for interface in interfaces %}...{% endfor %}
• Conditionals: {% if ospf_enabled %}...{% endif %}
• Filters: {{ ip | to_cidr }}
• Comments: {# This is a comment #}

Security Considerations

Template Validation:

┌─────────────────────────────────────────────────────────────┐
│ Template Security Checks                                    │
├─────────────────────────────────────────────────────────────┤
│ 1. Syntax Validation                                        │
│    ├─ Parse Jinja2 syntax                                   │
│    ├─ Check for undefined variables                         │
│    └─ Validate template structure                           │
│                                                              │
│ 2. Sandbox Enforcement                                      │
│    ├─ Disable dangerous built-ins (eval, exec, import)      │
│    ├─ Limit template complexity (max loops, recursion)      │
│    └─ Restrict available filters                            │
│                                                              │
│ 3. Content Security                                         │
│    ├─ Scan for command injection attempts                   │
│    ├─ Validate against forbidden commands list              │
│    └─ Audit logging for all templates                       │
└─────────────────────────────────────────────────────────────┘

Parameter Validation:

Validation Layers:
├─ Type Checking
│  └─ int, str, List[Dict], etc.
├─ Range Validation
│  ├─ IP addresses (valid format)
│  ├─ VLAN IDs (1-4094)
│  └─ Port numbers (1-65535)
├─ Device-Specific Validation
│  └─ Check device capabilities
└─ Business Logic Validation
   └─ Network-specific rules

Error Handling Strategy

Error Categories:

┌─────────────────────────────────────────────────────────────┐
│ Error Types & Recovery Strategies                           │
├─────────────────────────────────────────────────────────────┤
│ 1. TemplateSyntaxError                                      │
│    ├─ Cause: Invalid Jinja2 syntax                          │
│    ├─ Detection: Pre-rendering validation                   │
│    └─ Recovery: [Show error] → [User fixes] → [Retry]      │
│                                                              │
│ 2. ParameterValidationError                                 │
│    ├─ Cause: Wrong type/value/range                         │
│    ├─ Detection: Pre-execution validation                   │
│    └─ Recovery: [Highlight errors] → [User corrects]        │
│                                                              │
│ 3. RenderingError                                           │
│    ├─ Cause: Runtime rendering failure                      │
│    ├─ Detection: During template render                     │
│    └─ Recovery: [Show context] → [User modifies params]     │
│                                                              │
│ 4. ExecutionError                                           │
│    ├─ Cause: Device connection/command failure              │
│    ├─ Detection: During config execution                    │
│    └─ Recovery: [Retry] → [Skip] → [Continue others]        │
└─────────────────────────────────────────────────────────────┘

Error Response Format:

{
  "error": "ParameterValidationError",
  "message": "Invalid IP address format for device R1",
  "details": {
    "device": "R1",
    "parameter": "interface.ip",
    "value": "999.999.999.999",
    "expected": "Valid IPv4 address (e.g., 192.168.1.1)"
  },
  "suggestions": [
    "Verify IP address format",
    "Check for typos in address",
    "Ensure address is in correct range"
  ]
}

---

Testing Strategy

Unit Tests

Template Rendering Tests:

Test Cases:
├─ Simple Variables
│  └─ Input: "hostname {{ name }}" + {name: "R1"}
│     Output: ["hostname R1"]
│
├─ Loops
│  └─ Input: "{% for n in nets %}network {{ n }}\n{% endfor %}"
│          + {nets: ["192.168.1.0", "192.168.2.0"]}
│     Output: ["network 192.168.1.0", "network 192.168.2.0"]
│
├─ Conditionals
│  └─ Input: "{% if ospf %}router ospf 1\n{% endif %}"
│          + {ospf: true}
│     Output: ["router ospf 1"]
│
└─ Nested Structures
   └─ Input: Complex multi-level config
      Output: Properly indented commands

Rule Engine Tests:

Test Cases:
├─ Device Number Extraction
│  ├─ "R1" → 1
│  ├─ "Router-100" → 100
│  └─ "DeviceX" → fallback to index
│
├─ IP Address Generation
│  ├─ Sequential: 192.168.1.0, 192.168.2.0, ...
│  ├─ VLAN-based: 10.0.100.0, 10.0.101.0, ...
│  └─ Hierarchical: Correct prefix assignment
│
└─ Parameter Validation
   ├─ Type checking
   ├─ Range validation
   └─ Device-specific constraints

Integration Tests

Full HITL Workflow:

Test Scenario:
┌─────────────────────────────────────────────────────────────┐
│ 1. Template Generation                                      │
│    ├─ Input: "Configure OSPF on 10 routers"                │
│    ├─ Expected: Valid Jinja2 template with schema          │
│    └─ Verify: Template syntax, parameter completeness      │
│                                                              │
│ 2. Parameter Generation (AI mode)                          │
│    ├─ Input: Template + topology context                   │
│    ├─ Expected: 10 device parameter sets                   │
│    └─ Verify: Correct IP assignment, device mapping        │
│                                                              │
│ 3. Parameter Generation (Direct mode)                      │
│    ├─ Input: Template + topology (100 devices)             │
│    ├─ Expected: 100 parameter sets (0 tokens)              │
│    └─ Verify: Rule engine logic, addressing schemes        │
│                                                              │
│ 4. Execution                                                │
│    ├─ Input: Template + parameters                         │
│    ├─ Expected: Successful configuration on all devices    │
│    └─ Verify: Config applied, execution results            │
└─────────────────────────────────────────────────────────────┘

End-to-End Tests

Large-Scale Topology Test:

Scenario: 1000 Router OSPF Configuration

Setup:
├─ Create GNS3 project with 1000 routers
├─ Deploy in test environment
└─ Verify connectivity

Execution:
├─ Generate template (~150 tokens)
├─ Generate params (rule engine, 0 tokens)
├─ Execute in batches of 100
└─ Monitor progress via SSE

Validation:
├─ Verify all 1000 devices configured
├─ Check OSPF process running on each
├─ Verify IP addressing correctness
├─ Measure execution time (< 8 minutes)
└─ Verify token consumption (~400 total)

Cleanup:
└─ Remove test project

Performance Tests:

Benchmarks:
├─ 10 devices: < 30 seconds
├─ 50 devices: < 1 minute
├─ 100 devices: 1-2 minutes
├─ 500 devices: 2-5 minutes
└─ 1000 devices: 3-8 minutes

Metrics:
├─ Token usage (target: 99%+ reduction)
├─ Execution time (vs. baseline)
├─ Memory usage
└─ Concurrent connection handling

---

Success Metrics

Token Savings

• Target: 70%+ reduction in token usage for multi-device configurations
• Measurement: Compare token usage before/after for same tasks

User Adoption

• Target: 60%+ of configuration tasks use template workflow
• Measurement: Track tool usage statistics

Error Reduction

• Target: 50%+ reduction in configuration errors
• Measurement: Compare error rates before/after HITL

User Satisfaction

• Target: 4.5+ star rating (5-star scale)
• Measurement: Post-task user surveys

---

Risks and Mitigations

Risk	Impact	Mitigation
AI generates invalid Jinja2 syntax	High	Add template validation, provide syntax feedback
Users find HITL workflow too slow	Medium	Add "quick confirm" option, template reuse
Template reuse causes stale configs	Medium	Template versioning, checksum validation
Multi-vendor complexity	High	Phase 1: Cisco only, Phase 4: expand
Session state management bugs	Medium	Comprehensive testing, state cleanup

---

Open Questions

1. Template Storage: Should templates be stored per-user or shared globally?
2. Template Validation: How strict should template validation be?
3. Backward Compatibility: Should existing direct-config tools remain available?
4. Template Sharing: Should users be able to share templates in a marketplace?
5. Performance: How to handle template rendering for 100+ devices?

---

Dependencies

Required Python Packages

jinja2>=3.1.0
langchain>=0.1.0
langgraph>=0.0.20

Integration Points

• gns3server/agent/gns3_copilot/tools_v2/config_tools_nornir.py (existing)
• gns3server/agent/gns3_copilot/prompts/lab_automation_assistant_prompt.py (update)
• gns3server/agent/gns3_copilot/gns3_client/gns3_topology_reader.py (existing)
• gns3server/agent/gns3_copilot/utils/command_filter.py (existing)

---

Timeline

Sprint 1: Foundation (Week 1-2)

• Core rendering engine
• Three LangChain tools
• Basic session management
• System prompt updates

Sprint 2: User Experience (Week 3)

• Review interfaces
• Preview functionality
• Error handling
• Documentation

Sprint 3: Enhancement (Week 4-5)

• Template library
• Caching mechanisms
• Multi-vendor support
• Testing and QA

Sprint 4: Polish (Week 6)

• Performance optimization
• Bug fixes
• User feedback integration
• Release preparation

---

References

• Jinja2 Documentation
• LangGraph Documentation
• Existing Config Tools
• Command Security

---

Changelog

Date	Version	Changes
2026-03-20	0.6	Clarified system scope and positioning - focuses on baseline configuration (0→1), with handoff to production tools (Terraform/REST API/NETCONF) for advanced configuration (1→N)
2026-03-20	0.5	Major documentation refactor - Reduced code content by ~60%, added comprehensive diagrams: System architecture, HITL state transitions, API design, data flow, error handling, template lifecycle; Enhanced section on testing strategy; Improved visual documentation
2026-03-20	0.4	Added link creation templates section with topology patterns (Spine-Leaf, Ring, Mesh, Star), intelligent port allocation, performance benchmarks for large-scale connectivity
2026-03-20	0.3	Added node creation templates section with batch topology provisioning, auto-linking, automatic positioning; Combined node creation + configuration workflows for rapid 1000+ node data center deployment
2026-03-20	0.2	Added large-scale topology support section (1000+ nodes), direct execution mode, batch parallel execution, rule engine optimizations
2026-03-20	0.1	Initial roadmap document created

---

Document Status: 💡 Proposed - Awaiting Implementation Next Review: After Phase 1 completion

---

For questions or feedback about this roadmap, please open an issue or contact the AI Copilot team.