gns3-server/PROJECT_CONTEXT.md

GNS3 Server - Project Context for Claude Code

This document provides project context information for the Claude Code AI assistant to work more efficiently.

---

Project Overview

Project Name: GNS3 Server Description: Network simulation server supporting the GNS3 network virtualization platform Primary Language: Python Current Branch: feature/ai-copilot-bridge Main Branch: master

---

Project Structure

gns3server/
├── agent/                          # AI Copilot related modules
│   └── gns3_copilot/              # GNS3-Copilot AI Assistant
│       ├── agent/                  # LangGraph Agent implementation
│       ├── tools_v2/               # Tool collection (device config, display commands, etc.)
│       ├── utils/                  # Utility functions and helper modules
│       ├── gns3_client/            # GNS3 API client
│       ├── prompts/                # AI prompt templates
│       ├── agent_service.py        # Agent service layer
│       └── project_agent_manager.py # Project Agent manager
│
├── api/                            # API routes
│   └── routes/controller/          # Controller API
│       └── chat.py                 # AI Chat API endpoint
│
├── controller/                     # Core controller
│   ├── project.py                  # Project management
│   └── ...
│
├── schemas/                        # Pydantic data models
│   └── controller/
│       └── chat.py                 # Chat API Schema
│
├── db/                             # Database module
│   └── tasks.py                    # Database tasks
│
└── docs/                           # Documentation
    └── gns3-copilot/               # AI Copilot documentation

---

Key Module Descriptions

1. AI Copilot Data Flow

Tool Layer → Agent Layer → Service Layer → API Layer → Frontend

Tool Output Format: All tools return dict or list[dict], automatically serialized to JSON in the Service layer

Key Files:

• agent/gns3_copilot/tools_v2/*.py - Tool implementations
• agent/gns3_copilot/agent_service.py:460-473 - Event conversion logic
• agent/gns3_copilot/utils/parse_tool_content.py - Tool result parsing

2. SSE Event Types

Type	Description
content	AI text streaming output
tool_call	LLM tool invocation (progressive parameters)
tool_start	Tool execution started
tool_end	Tool execution completed (output as JSON)
error	Error message
done	Stream ended

3. Important Tools

Tool Name	File	Function
ExecuteMultipleDeviceCommands	display_tools_nornir.py	Read-only diagnostic commands
ExecuteMultipleDeviceConfigCommands	config_tools_nornir.py	Configuration commands
VPCSMultiCommands	vpcs_tools_telnetlib3.py	VPCS virtual PC commands
GNS3TemplateTool	gns3_get_node_temp.py	Get GNS3 templates
GNS3CreateNodeTool	gns3_create_node.py	Create nodes

---

Code Standards

Static Code Analysis (Flake8)

The project uses flake8 for static code analysis. You must run checks before committing code.

Running Flake8

# Activate virtual environment
source venv/bin/activate

# Check a single file
flake8 path/to/file.py

# Check the entire project
flake8 gns3server/

# Check a specific directory
flake8 gns3server/utils/

Common Flake8 Error Codes

Code	Description	Example
F401	Module imported but unused	import os never used
F841	Local variable assigned but never used	x = 1 not used later
F824	global declaration never assigned	global _bar never assigned in scope
E501	Line too long (>79 characters)	Single line exceeds 79 characters

Fix Examples

# F401: Remove unused imports
# Bad
import os  # Never used
# Good: Delete this line

# F841: Mark as intentionally unused
# Bad
def foo():
    x = 1  # Never used

# Good: Use or mark as intentionally unused
def foo():
    x = 1
    _ = x  # Mark as intentionally unused

# F824: Remove unnecessary global declaration
# Bad
def foo():
    global _fernet  # Never assigned in this scope

# Good: Remove global statement (if only reading)
def foo():
    # Just read the global variable, no global declaration needed
    pass

# E501: Break long lines
# Bad
raise RuntimeError("Encryption not initialized. Call init_encryption() first.")

# Good
raise RuntimeError(
    "Encryption not initialized. Call init_encryption() first."
)

Ruff (Alternative)

Ruff is a faster Python linter that can replace flake8, isort, black, and more.

# Install
pip install ruff

# Usage
ruff check gns3server/          # Check code
ruff check --fix gns3server/    # Auto-fix
ruff format gns3server/         # Format code

Python Code Style

# 1. Type annotations
def process_data(input_data: dict[str, Any]) -> list[dict[str, Any]]:
    pass

# 2. Error handling
try:
    result = tool.invoke(args)
except Exception as e:
    logger.error("Tool failed: %s", e, exc_info=True)
    return {"error": str(e)}

# 3. JSON serialization
if not isinstance(output, str):
    output = json.dumps(output, ensure_ascii=False, indent=2)

Import Order

# 1. Standard library
import asyncio
import json
import logging

# 2. Third-party libraries
from langchain.tools import BaseTool
from pydantic import BaseModel

# 3. Local modules
from gns3server.agent.gns3_copilot.agent import agent_builder
from gns3server.controller import Controller

Copyright Header

# SPDX-License-Identifier: GPL-3.0-or-later
#
# GNS3-Copilot - AI-powered Network Lab Assistant for GNS3
#
# Copyright (C) 2025 Yue Guobin (岳国宾)
# Author: Yue Guobin (岳国宾)
#
# Project Home: https://github.com/yueguobin/gns3-copilot

---

Git Commit Standards

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Type Categories

Type	Description	Example
feat	New feature	feat(copilot): add user authentication
fix	Bug fix	fix(api): correct JSON serialization
docs	Documentation update	docs: update API design doc
refactor	Refactoring	refactor(agent): simplify state management
chore	Build/toolchain	chore: update dependencies

Example

fix(copilot): serialize tool output to standard JSON format

Changed tool output serialization in AgentService._convert_event_to_chunk()
from str() to json.dumps() to ensure structured data is properly formatted.

Changes:
- Added json import to agent_service.py
- Modified on_tool_end event handling

Benefits:
- Frontend can parse tool results with JSON.parse()
- Chinese characters are preserved (not escaped)

Co-Authored-By: YueGuobin <yueguobin@outlook.com>

IMPORTANT: Use Your Own Git Account for Commits

When creating git commits, ALWAYS use your own git account information for authorship.

Before committing, verify your git configuration:

# Check current git user configuration
git config user.name
git config user.email

# If incorrect, set your own information
git config user.name "Your Name"
git config user.email "your.email@example.com"

For this project, the current configured user is:

Name:  YueGuobin
Email: yueguobin@outlook.com

You may use Co-Authored-By to credit contributors, but the Author field should always be your own account:

git commit -m "feat: add new feature

Co-Authored-By: ContributorName <contributor@example.com>"

---

Development Notes

1. When Modifying Tool Output Format

Must update the following locations:

• agent/gns3_copilot/tools_v2/*.py - Tool implementation
• agent/gns3_copilot/agent_service.py - Event conversion
• docs/gns3-copilot/ai-chat-api-design.md - API documentation

2. Data Serialization Principles

• Tool Layer: Return Python dict/list
• Service Layer: Use json.dumps() for serialization
• API Layer: Use Pydantic validation then serialize to SSE

3. Logging

logger.info("Operation started: project_id=%s", project_id)
logger.debug("Detailed info: data=%s", data)
logger.error("Error occurred: %s", error, exc_info=True)

4. Security Considerations

• Prohibit dangerous commands (reload, erase startup-config, etc.)
• Use filter_forbidden_commands() to filter commands
• Validate user input (project_id format, etc.)

---

Common Commands

# Run tests
pytest tests/

# Static code analysis (must run before committing)
source venv/bin/activate
flake8 gns3server/

# Check a single file
flake8 path/to/file.py

# Syntax check
python3 -m py_compile gns3server/agent/gns3_copilot/agent_service.py

# Check git status
git status

# View git history
git log --oneline -15

# View file modification history
git blame file.py -L 100,120

# Commit code (verify your git user info first!)
git config user.name && git config user.email
git add files...
git commit -m "type(scope): description"

---

Related Documentation

• AI Chat API Design
• Command Security Policy
• LLM Model Configuration
• Context Window Management

---

Document Maintenance: Please update this document promptly when project structure or development standards change.