Metadata-Version: 2.4
Name: gns3-copilot
Version: 0.2.7
Summary: AI-powered network automation assistant for GNS3
Author: Guobin Yue
Maintainer: Guobin Yue
License-Expression: MIT
Project-URL: Homepage, https://github.com/yueguobin/gns3-copilot
Project-URL: Repository, https://github.com/yueguobin/gns3-copilot
Project-URL: Documentation, https://github.com/yueguobin/gns3-copilot/blob/master/README.md
Project-URL: Bug Reports, https://github.com/yueguobin/gns3-copilot/issues
Keywords: gns3,network-automation,ai,langchain,nornir,netmiko,networking,automation,copilot
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: System :: Networking
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain>=1.1.0
Requires-Dist: langchain-core>=1.0.5
Requires-Dist: langgraph>=1.0.0
Requires-Dist: langgraph-cli>=0.4.4
Requires-Dist: langgraph-cli[inmem]>=0.4.4
Requires-Dist: langgraph-checkpoint-sqlite>=1.0.0
Requires-Dist: langchain-openai>=1.0.0
Requires-Dist: langchain-anthropic>=1.0.0
Requires-Dist: langchain-google-genai>=1.0.0
Requires-Dist: langchain-aws>=1.0.0
Requires-Dist: langchain-ollama>=1.0.0
Requires-Dist: langchain-deepseek>=1.0.0
Requires-Dist: langchain-xai>=1.0.0
Requires-Dist: netmiko>=4.6.0
Requires-Dist: nornir>=3.5.0
Requires-Dist: nornir-netmiko>=1.0.1
Requires-Dist: nornir-utils>=0.2.0
Requires-Dist: nornir-salt>=0.22.5
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: requests>=2.32.5
Requires-Dist: urllib3>=2.5.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: PyJWT>=2.10.1
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: telnetlib3>=2.0.8
Requires-Dist: streamlit>=1.32.0
Requires-Dist: soundfile>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: mypy>=0.800; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: bandit>=1.7.0; extra == "dev"
Requires-Dist: safety>=2.0.0; extra == "dev"
Dynamic: license-file

# GNS3 Copilot

[![CI - QA & Testing](https://github.com/yueguobin/gns3-copilot/actions/workflows/ci.yaml/badge.svg)](https://github.com/yueguobin/gns3-copilot/actions/workflows/ci.yaml)
[![CD - Production Release](https://github.com/yueguobin/gns3-copilot/actions/workflows/cd.yaml/badge.svg)](https://github.com/yueguobin/gns3-copilot/actions/workflows/cd.yaml)
[![codecov](https://codecov.io/gh/yueguobin/gns3-copilot/branch/Development/graph/badge.svg?token=7FDUCM547W)](https://codecov.io/gh/yueguobin/gns3-copilot)
[![PyPI version](https://img.shields.io/pypi/v/gns3-copilot)](https://pypi.org/project/gns3-copilot/)
[![PyPI downloads](https://static.pepy.tech/badge/gns3-copilot)](https://pepy.tech/project/gns3-copilot)
![License](https://img.shields.io/badge/license-MIT-green.svg) 
[![platform](https://img.shields.io/badge/platform-linux%20%7C%20windows%20%7C%20macOS-lightgrey)](https://shields.io/)

An AI-powered network automation assistant designed specifically for GNS3 network simulator, providing intelligent network device management and automated operations.

## Project Overview

GNS3 Copilot is a powerful network automation tool that integrates multiple AI models and network automation frameworks. It can interact with users through natural language and perform tasks such as network device configuration, topology management, and fault diagnosis.

<img src="https://raw.githubusercontent.com/yueguobin/gns3-copilot/refs/heads/master/demo.gif" alt="GNS3 Copilot Function demonstration" width="1280"/>

### Core Features

- 🤖 **AI-Powered Chat Interface**: Supports natural language interaction, understands network automation requirements
- 🔧 **Device Configuration Management**: Batch configuration of network devices, supports multiple vendor devices (currently tested with Cisco IOSv image only)
- 📊 **Topology Management**: Automatically create, modify, and manage GNS3 network topologies
- 🎨 **Topology Visualization**: SVG drawing support for automatic network topology graphics generation with area annotation and connection line drawing
- 🔍 **Network Diagnostics**: Intelligent network troubleshooting and performance monitoring
- 🌐 **LLM Support**: Integrated DeepSeek AI model for natural language processing



## Technical Architecture

- [System Architecture](docs/architecture/system-architecture.md) - Comprehensive system architecture overview with 7-layer design
- [Core Framework Design](docs/architecture/core-framework-design.md) - Detailed LangGraph and LangChain framework design
- [Architecture Documentation Index](docs/architecture/) - All architecture diagrams and design documents

## Documentation

### User Documentation
- [FAQ](docs/user/FAQ.md) - Frequently asked questions and troubleshooting guide
- [LLM Quick Configuration Guide](docs/user/llm-quick-configuration-guide.md) - Quick setup guide for LLM providers

### Development Documentation
- [Manual Testing Guide](docs/development/testing/manual_testing_guide.md) - Comprehensive manual testing instructions
- [Test Coverage Report](docs/development/testing/TEST_COVERAGE_REPORT.md) - Automated test coverage statistics
- [Auto Commit Usage Guide](docs/development/automation/auto-commit-usage-guide.md) - Git commit message automation guide
- [Auto Documentation Automation Guide](docs/development/automation/auto-doc-automation-guide.md) - Automated documentation updates
- [Backend Evolution Plan](docs/development/evolution/GNS3-Copilot%20Backend%20Evolution%20Plan.md) - Project evolution roadmap

### Technical Documentation
- [GNS3 Drawing SVG Format Guide](docs/technical/gns3-drawing-svg-format-guide.md) - GNS3 drawing format and color scheme


The Final Concept: Multi-Agent System Architecture and Dynamic Context Manager (Based on Current Understanding)

 **Multi-Agent Role Assignment**

This system employs distinct agents, each specializing in a specific function:

- **Planning Agent:** Responsible for **identifying user intent** and **formulating the detailed task plan**.
    
- **Execution Agent:** Responsible for **executing specific device operations** step-by-step according to the plan.
    
- **Supervision Agent:** Responsible for **continuous monitoring** and evaluation of the Execution Agent's results. If issues are found, it requests the Execution Agent to **retry** or notifies the **Expert Agent** to intervene.
    
- **Expert Agent:** Responsible for addressing complex problems discovered by the Supervision Agent, providing **guidance**, **correcting the plan**, or **proposing solutions**.
    

 **System Workflow**

The process operates in a closed-loop structure, ensuring reliability and self-correction:

1. **User Input Request**
    
    - The user initiates the system by submitting a task or request.
        
2. **Planning Agent: Intent Recognition & Plan Formulation**
    
    - The Planning Agent analyzes the request, understands the objective, and generates a sequence of execution steps.
        
3. **Execution Agent: Execute Plan Steps**
    
    - The Execution Agent takes the planned steps and performs the corresponding concrete operations.
        
4. **Supervision Agent: Real-time Monitoring & Evaluation**
    
    - The Supervision Agent continuously checks the outcome of each execution step.
        
    - **Issue Detected** $\rightarrow$ Requests the Execution Agent to **Retry** OR **Notifies the Expert Agent**.
        
5. **Expert Agent: Intervention & Guidance/Correction**
    
    - The Expert Agent intervenes when complex problems are reported.
        
    - It provides guidance $\rightarrow$ **Corrects the Plan** (loops back to Step 2) OR **Proposes a Solution** (loops back to Step 3).
        
6. **Return Final Work Result**
    
    - Once all steps are successfully completed and verified, the final result is delivered to the user.

## 🤝 Contributing

We welcome contributions from the community! To keep the project stable, please follow our branching strategy:

- **Target Branch**: Always submit your Pull Requests to the `Development` branch (not `master`).

- **Feature Branches**: Create a new branch for each feature or bug fix: `git checkout -b feature/your-feature-name Development`.

- **Workflow**: Fork -> Branch -> Commit -> Push -> Pull Request to `Development`.


## Installation Guide

### Environment Requirements

- Python 3.10+
- GNS3 Server (running on http://localhost:3080 or remote host)
- Supported operating systems: Windows, macOS, Linux

### Installation Steps

1. **Create virtual environment**
```bash
python -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows
```

1. **Install GNS3 Copilot**
```bash
pip install gns3-copilot
```
or
```bash
pip install git+https://github.com/yueguobin/gns3-copilot
```
1. **Start GNS3 Server**
Ensure GNS3 Server is running and can be accessed via its API interface: `http://x.x.x.x:3080`

1. **Launch the application**
```bash
gns3-copilot
```

## Usage Guide

### Startup

```bash
# Basic startup, default port 8501
gns3-copilot

# Specify custom port
gns3-copilot --server.port 8080

# Specify address and port
gns3-copilot --server.address 0.0.0.0 --server.port 8080

# Run in headless mode
gns3-copilot --server.headless true

# Get help
gns3-copilot --help

```

### Configure on Settings Page

GNS3 Copilot configuration is managed through a Streamlit interface, with all settings saved in the `.env` file in the project root directory. If the `.env` file doesn't exist on first run, the system will automatically create it.

#### 🔧 Main Configuration Content

##### 1. GNS3 Server Configuration
- **GNS3 Server Host**: GNS3 server host address (e.g., 127.0.0.1)
- **GNS3 Server URL**: Complete GNS3 server URL (e.g., http://127.0.0.1:3080)
- **API Version**: GNS3 API version (supports v2 and v3)
- **GNS3 Server Username**: GNS3 server username (required only for API v3)
- **GNS3 Server Password**: GNS3 server password (required only for API v3)

##### 2. LLM Model Configuration

**🌟 Recommended Models:**
- **Best:** `deepseek-chat` (via DeepSeek API) or `deepseek/deepseek-v3.2` (via OpenRouter)
- **Other Recommended:** `x-ai/grok-3`, `anthropic/claude-sonnet-4`, `z-ai/glm-4.7`

**Note:** These models have been tested and verified to provide excellent performance for network automation tasks.

- **Model Provider**: Model provider (supports: openai, anthropic, deepseek, xai, openrouter, etc.)
- **Model Name**: Specific model name (e.g., deepseek-chat, gpt-4o-mini, etc.)
- **Model API Key**: Model API key
- **Base URL**: Base URL for model service (required when using third-party platforms like OpenRouter)
- **Temperature**: Model temperature parameter (controls output randomness, range 0.0-1.0)

##### 3. Voice Features Configuration (Experimental)
- **Voice Features**: Voice features toggle (enable/disable TTS/STT functionality)
- **TTS API Key**: Text-to-speech service API key
- **TTS Model**: TTS model selection (supports: tts-1, tts-1-hd, gpt-4o-mini-tts)
- **TTS Voice**: Voice character selection (supports: alloy, ash, ballad, etc.)
- **TTS Speed**: Voice playback speed (range: 0.25-4.0)
- **TTS Base URL**: TTS service base URL
- **STT API Key**: Speech-to-text service API key
- **STT Model**: STT model selection (supports: whisper-1, gpt-4o-transcribe, etc.)
- **STT Language**: Recognition language code (e.g., en, zh, ja)
- **STT Temperature**: Recognition temperature parameter (controls randomness, range 0.0-1.0)
- **STT Response Format**: Output format (supports: json, text, srt, etc.)
- **STT Base URL**: STT service base URL

##### 4. Other Settings
- **Linux Console Username**: Linux console username (for Debian devices in GNS3)
- **Linux Console Password**: Linux console password

## Security Considerations

1. **API Key Protection**:
   - Do not commit `.env` file to version control
   - Regularly rotate API keys
   - Use principle of least privilege

## License

This project uses MIT License - see [LICENSE](LICENSE) file for details.

## Acknowledgements

This project was inspired by the following resources, which provided the foundation for Python programming, network automation, and AI applications:

- **《网络工程师的 Python 之路》** - Network engineering automation with Python
- **《网络工程师的 AI 之路》** - AI applications for network engineering

Special thanks to these resources for their technical inspiration and guidance.

## Contact

- Project Homepage: https://github.com/yueguobin/gns3-copilot
- Issue Reporting: https://github.com/yueguobin/gns3-copilot/issues

---
