Naga Agent

# NagaAgent 3.1       --- **🐍 Intelligent Dialogue Assistant | Multi-Platform Support | Rich Ecosystem | Easy to Extend** [Features](#-core-features) • [Quick Start](#-quick-start) • [Installation Guide](#-detailed-installation-guide) • [API Documentation](#-restful-api-service) • [Configuration Instructions](#-configuration-instructions) • [Changelog](#-changelog) • [Update History](CHANGELOG.md) --- ### 🎯 Project Highlights ✅ **🧠 Intelligent Memory**: GRAG knowledge graph memory system based on Neo4j ✅ **🔧 Rich Ecosystem**: Supports various MCP services and Agent systems ✅ **🎤 Voice Interaction**: OpenAI compatible streaming voice synthesis service ✅ **🖥️ Modern Interface**: Standalone dialog message rendering system based on PyQt5 ✅ **🌐 Complete API**: FastAPI RESTful API and streaming output ✅ **📱 System Tray**: Full background operation and auto-start support ✅ **🔍 Intelligent Agent**: Dynamic service discovery and hot-plug management ✅ **🛡️ Secure and Reliable**: Session isolation and permission management ✅ **🤖 Multi-Agent Collaboration**: AgentManager independent system supports multi-agent collaboration ✅ **🌳 Deep Thinking**: Multi-branch thinking engine based on genetic algorithms ✅ **🔄 Configuration Hot Update**: Real-time configuration changes without restarting the application ✅ **💾 Persistent Context**: Automatically restores historical dialogue context after restart --- ## 🚀 Quick Start ### 📋 System Requirements - **Operating System**: Windows 10/11, macOS 10.15+, Linux - **Python**: 3.10+ (recommended 3.11) - **Memory**: Recommended 4GB or more - **Storage**: Recommended 2GB or more of available space ### 🔧 One-Click Installation <details> <summary><strong>Windows Users</strong></summary> ```powershell # Clone the project git clone https://github.com/Xxiii8322766509/NagaAgent.git cd NagaAgent # One-click configuration .\setup.ps1 ``` </details> <details> <summary><strong>macOS Users</strong></summary> ```bash # Clone the project git clone https://github.com/Xxiii8322766509/NagaAgent.git cd NagaAgent # One-click configuration chmod +x setup_mac.sh ./setup_mac.sh ``` </details> <details> <summary><strong>Linux Users</strong></summary> ```bash # Clone the project git clone https://github.com/Xxiii8322766509/NagaAgent.git cd NagaAgent # Create a virtual environment python3 -m venv .venv source .venv/bin/activate # Install dependencies pip install -r requirements.txt ``` </details> ### 🗄️ Start Neo4j Service ```bash # Start Neo4j container docker run -d \ --restart always \ --publish=7474:7474 \ --publish=7687:7687 \ --env NEO4J_AUTH=neo4j/your_password \ --volume=neo4j_data:/data \ neo4j:latest ``` > **Port Conflict Resolution**: If the port is occupied, you can use other ports: > ```bash > --publish=8474:7474 --publish=8687:7687 > ``` ### ⚙️ Configuration File 1. Copy the configuration template: ```bash cp config.json.example config.json ``` 2. Edit the configuration file to set the API key and other parameters. ### 🚀 Start the Application <details> <summary><strong>Windows Startup Method</strong></summary> ```powershell # Normal mode .\start.bat # Tray mode (recommended) .\start_with_tray.bat ``` </details> <details> <summary><strong>macOS Startup Method</strong></summary> ```bash ./start_mac.sh ``` </details> <details> <summary><strong>Linux Startup Method</strong></summary> ```bash ./start.sh ``` </details> After starting, the following will automatically launch: - 🖥️ PyQt5 graphical interface - 🌐 RESTful API server - 🎤 Voice interaction service - 🧠 GRAG knowledge graph memory system - 🔄 Configuration hot update system --- ## 🛠️ Detailed Installation Guide ### 🔍 Environment Check After installation, run the environment check: ```bash python check_env.py ``` ### 📦 Dependency Description The main dependencies of the project include: | Category | Dependency | Purpose | |----------|------------|---------| | **Core Framework** | `openai`, `mcp`, `fastapi` | AI dialogue and API services | | **Search Tool** | `langchain-community` | SearXNG search integration | | **GUI** | `PyQt5`, `pygame` | Graphical user interface | | **Voice Processing** | `edge-tts`, `pyaudio`, `sounddevice` | Voice synthesis and recognition | | **Knowledge Graph** | `py2neo`, `pyvis`, `matplotlib` | Neo4j graph database operations | | **Browser Automation** | `playwright` | Web operation automation | | **MCP Tools** | `jmcomic`, `fastmcp` | Various extension tools | | **System Control** | `pycaw`, `screen-brightness-control` | System function control | | **Communication Protocol** | `paho-mqtt`, `websockets` | MQTT and WebSocket communication | | **Data Processing** | `numpy`, `pandas`, `scikit-learn` | Data processing and machine learning | | **Document Processing** | `python-docx` | Word document processing | ### ⚠️ Common Problem Solutions <details> <summary><strong>Windows Installation Issues</strong></summary> **Missing C++ Build Tools:** ```powershell # Download and install Microsoft Visual C++ Build Tools # https://visualstudio.microsoft.com/visual-cpp-build-tools/ ``` **Numpy Warning and Program Crash:** ```powershell # After installing Visual Studio, execute in Developer Command Prompt uv pip uninstall numpy uv sync --no-cache --reinstall ``` **Permission Issues:** ```powershell # Run PowerShell as Administrator Set-ExecutionPolicy RemoteSigned -Scope CurrentUser ``` </details> <details> <summary><strong>macOS Installation Issues</strong></summary> **Python Version Too Low:** ```bash brew install python@3.11 echo 'export PATH="/usr/local/opt/python@3.11/bin:$PATH"' >> ~/.zshrc ``` **PyAudio Installation Failure:** ```bash brew install portaudio pip install pyaudio ``` **Permission Issues:** ```bash chmod +x *.sh ``` </details> <details> <summary><strong>Linux Installation Issues</strong></summary> **System Dependencies:** ```bash # Ubuntu/Debian sudo apt update sudo apt install python3-dev portaudio19-dev # CentOS/RHEL sudo yum install python3-devel portaudio-devel ``` **Docker Permissions:** ```bash sudo usermod -aG docker $USER newgrp docker ``` </details> --- ## ⚙️ Configuration Instructions ### 🔄 Configuration Hot Update System NagaAgent 3.1 introduces a powerful configuration hot update system that supports real-time configuration changes without restarting the application. #### Core Features - **Real-time Updates**: Configuration changes take effect immediately without restarting. - **Configuration Snapshot**: Supports saving and restoring configurations. - **Automatic Monitoring**: Automatically detects changes in configuration files. - **Module Reloading**: Supports dynamic module reloading. - **Error Handling**: Comprehensive exception handling mechanism. #### Usage Example ```python from config_manager import update_config, get_config_snapshot # Update configuration success = update_config({ "system": {"debug": True}, "api": {"temperature": 0.8} }) # Get configuration snapshot snapshot = get_config_snapshot() # Restore configuration restore_config_snapshot(snapshot) ``` #### Detailed Documentation - 📖 [Configuration Hot Update User Guide](CONFIG_HOT_RELOAD_GUIDE.md) - 📊 [Configuration Hot Update Test Report](CONFIG_HOT_RELOAD_TEST_REPORT.md) ### API Configuration Modify the `api` section in the `config.json` file: ```json { "api": { "api_key": "your-api-key-here", "base_url": "https://api.deepseek.com/v1", "model": "deepseek-chat", "temperature": 0.7, "max_tokens": 10000, "max_history_rounds": 10, "persistent_context": true, "context_load_days": 3, "context_parse_logs": true } } ``` #### Persistent Context Configuration Description - **persistent_context**: Whether to enable the persistent context feature (default: true) - **context_load_days**: Load historical dialogues from the last few days of log files (default: 3 days) - **context_parse_logs**: Whether to parse context from log files (default: true) ### API Server Configuration ```json { "api_server": { "enabled": true, "host": "127.0.0.1", "port": 8000, "auto_start": true, "docs_enabled": true } } ``` ### Online Search Configuration ```json { "online_search": { "searxng_url": "https://searxng.pylindex.top", "engines": ["google"], "num_results": 5 } } ``` ### GRAG Knowledge Graph Memory System Configuration ```json { "grag": { "enabled": true, "auto_extract": true, "context_length": 5, "similarity_threshold": 0.6, "neo4j_uri": "neo4j://127.0.0.1:7687", "neo4j_user": "neo4j", "neo4j_password": "your_password", "neo4j_database": "neo4j" } } ``` ### Obtaining API Key 1. Visit the official website of the corresponding LLM service provider (e.g., DeepSeek, OpenAI, etc.) 2. Register an account and create an API key. 3. Fill in the key in the `api.api_key` field of the `config.json` file. --- ## 🌟 Core Features ### 🧠 Intelligent Dialogue System - **Multi-Model Support**: Compatible with mainstream LLM providers such as OpenAI, DeepSeek, Anthropic, etc. - **Context Memory**: Intelligently maintains dialogue history, supporting multi-turn dialogue context. - **Streaming Output**: Real-time display of AI replies, enhancing interaction experience. - **Tool Invocation**: Automatically parses and executes tool invocation instructions returned by LLM. - **Deep Thinking**: Multi-branch thinking engine based on genetic algorithms, providing higher quality answers. ### 🔍 Online Search System - **SearXNG Integration**: Privacy-protecting search engine based on SearXNG. - **Multi-Engine Support**: Supports various search engines like Google, Bing, etc. - **Intelligent Result Processing**: Automatically formats search results, providing AI-friendly information display. - **Flexible Configuration**: Configurable search engine list, result quantity, and other parameters. ### 🔄 Configuration Hot Update System - **Real-time Configuration Updates**: Configuration changes take effect immediately without restarting the application. - **Configuration Change Notifications**: Comprehensive listener mechanism supports configuration change callbacks. - **Module Reloading**: Supports dynamic module management and hot-plugging. - **Configuration Monitor**: Automatic file change detection and reloading. - **Configuration Snapshot**: Secure configuration saving and restoration functionality. - **Error Handling**: Comprehensive exception handling mechanism to ensure system stability. ### 🔧 MCP Service Ecosystem - **Dynamic Service Discovery**: Automatically scans and registers all MCP services. - **Plug and Play**: New services can be added without restarting the system. - **Service Management**: Unified service pool query and management interface. - **Multi-Service Collaboration**: Supports multiple Agents working together. ### 🗺️ GRAG Knowledge Graph - **Quintuple Extraction**: Automatically extracts entity-relation-attribute from dialogues. - **Intelligent Retrieval**: Context recall mechanism based on similarity. - **Visual Display**: Supports visual display of knowledge graphs. - **Historical Import**: Compatible with batch import of old dialogue records. ### 🎤 Voice Interaction System - **Streaming Synthesis**: Real-time voice synthesis based on Edge-TTS. - **Intelligent Sentence Segmentation**: Automatically identifies sentence boundaries to optimize playback experience. - **Asynchronous Processing**: Text display and audio playback are completely separated. - **Multi-Engine Support**: Compatible with various TTS engines. ### 🖥️ User Interface - **Modern GUI**: Beautiful graphical interface based on PyQt5. - **Independent Dialog Box**: Each dialogue is an independent dialog box component, adopting a right-angle design with automatic height adjustment. - **Tool Invocation Dialog Box**: A dialog box specifically designed for tool invocation, without username labels, maintaining a clean UI style. - **Transparent Background**: The main chat area uses a transparent background, keeping the dialog box's original style. - **Markdown Support**: Full Markdown syntax support and code highlighting. - **Theme Customization**: Supports customization of interface themes, transparency, etc. - **Responsive Design**: Adapts to different screen sizes. - **Streaming Updates**: Real-time streaming message updates and automatic scrolling. ### 🌐 API Service - **RESTful API**: Complete HTTP API interface. - **Streaming Support**: Server-Sent Events streaming output. - **Automatic Documentation**: Interactive API documentation (Swagger). - **Cross-Origin Support**: Complete CORS configuration. ### 📱 System Tray - **Background Operation**: Supports minimizing to the system tray. - **Auto-Hide**: Automatically hides the console window after startup. - **Quick Operations**: Tray icon right-click menu. - **Auto-Start**: Supports auto-start functionality via registry. ### 🔍 Intelligent Agent System - **AgentManager**: Independent Agent registration and invocation system. - **Configuration Management**: Unified Agent configuration and dynamic loading. - **Session Isolation**: Complete isolation of multi-user sessions and TTL management. - **Placeholder Replacement**: Supports placeholders for Agent configuration, environment variables, time information, etc. - **Lifecycle Management**: Complete Agent lifecycle management and hot-plugging. - **Multi-Agent Collaboration**: Supports multiple Agents working together and task allocation. --- ## 🏗️ Technical Architecture <div align="center"> ```mermaid graph TB A[User Interface] --> B[PyQt5 GUI] A --> C[Web API] A --> D[Voice Interaction] B --> E[Dialogue Core] C --> E D --> E E --> F[Tool Invocation Loop] F --> G[MCP Service Manager] F --> H[Agent Manager] G --> I[Various MCP Services] H --> J[Various Agents] E --> K[GRAG Memory System] K --> L[Neo4j Graph Database] E --> M[Configuration Management] M --> N[config.py] M --> O[config_manager.py] I --> O[Files/Codes/Browsers, etc.] J --> P[Specialized Task Processing] ``` </div> ### 📊 Core Modules | Module | Function | Tech Stack | |--------|----------|------------| | **Dialogue Core** | Handles user input and AI responses | Python, OpenAI API | | **MCP Services** | Tool invocation and service management | MCP Protocol | | **Agent System** | Specialized task processing | Multi-model support | | **Memory System** | Knowledge graph and context | Neo4j, Py2neo | | **User Interface** | Graphical interactive interface | PyQt5, Markdown | | **API Service** | HTTP interface service | FastAPI, Uvicorn | | **Voice System** | Voice synthesis and recognition | Edge-TTS, PyAudio | | **Configuration Management** | Configuration hot updates and module reloading | ConfigManager, JSON | --- ## 🗂️ Directory Structure ``` NagaAgent3.1/ ├── main.py # Main entry point ├── config.py # Global configuration ├── config.json.example # Configuration file template ├── config_manager.py # Configuration hot update manager ├── conversation_core.py # Dialogue core (including tool invocation loop main logic) ├── apiserver/ # API server module │ ├── api_server.py # FastAPI server │ ├── start_server.py # Startup script │ ├── message_manager.py # Message manager │ └── README.md # API documentation ├── mcpserver/ # MCP services and Agent system │ ├── mcp_manager.py # MCP service management │ ├── mcp_registry.py # Agent registration and schema metadata │ ├── agent_manager.py # Agent manager (independent system) │ ├── agent_xxx/ # Various custom Agents │ │ └── agent-manifest.json # Agent configuration file │ ├── agent_comic_downloader/ # Comic download Agent │ ├── agent_device_switch/ # Device control Agent │ ├── agent_memory/ # Memory management Agent │ ├── agent_naga_portal/ # Naga portal Agent │ ├── agent_playwright_master/ # Browser automation Agent │ ├── agent_weather_time/ # Weather time Agent │ └── Office-Word-MCP-Server-main/ # Word document processing Agent ├── thinking/ # Deep thinking engine │ ├── tree_thinking.py # Core thinking engine │ ├── difficulty_judge.py # Problem difficulty assessment │ ├── genetic_pruning.py # Genetic algorithm pruning │ ├── preference_filter.py # User preference filtering │ └── thinking_node.py # Thinking node structure ├── summer_memory/ # GRAG knowledge graph memory system │ ├── memory_manager.py # Memory manager │ ├── quintuple_extractor.py # Quintuple extractor │ ├── quintuple_graph.py # Neo4j graph operations │ ├── quintuple_rag_query.py # Memory query │ └── quintuple_visualize_v2.py # Graph visualization ├── voice/ # Voice interaction system │ ├── tts_handler.py # TTS handler │ ├── voice_integration.py # Voice integration │ ├── server.py # Voice server │ └── start_voice_service.py # Voice service startup script ├── ui/ # Frontend UI │ ├── pyqt_chat_window.py # PyQt chat window │ ├── response_utils.py # Response parsing tools │ ├── message_renderer.py # Message renderer │ ├── elegant_settings_widget.py # Settings component │ └── tray/ # System tray module │ ├── console_tray.py # Console tray functionality │ ├── auto_start.py # Auto-start management │ └── README.md # Tray usage instructions ├── mqtt_tool/ # MQTT tools ├── logs/ # Logs (including historical txt dialogues) ├── data/neo4j/ # Neo4j database files ├── requirements.txt # Project dependencies ├── pyproject.toml # Project configuration ├── CONFIG_HOT_RELOAD_GUIDE.md # Configuration hot update user guide ├── CONFIG_HOT_RELOAD_TEST_REPORT.md # Configuration hot update test report ├── setup.ps1 # Windows configuration script ├── start.bat # Windows startup script ├── start_with_tray.bat # Windows tray startup script ├── setup_mac.sh # Mac configuration script ├── start_mac.sh # Mac startup script ├── check_env.py # Cross-platform environment check └── README.md # Project description ``` --- ## 🔧 Tool Invocation Loop Mechanism ### System Overview NagaAgent supports two types of tool invocations: - **MCP Service Invocation**: Invokes MCP-type Agents through `agentType: mcp`. - **Agent Service Invocation**: Invokes Agent-type Agents through `agentType: agent`. ### Tool Invocation Format #### MCP Service Invocation Format ```json { "agentType": "mcp", "service_name": "MCP Service Name", "tool_name": "Tool Name", "parameter_name": "parameter_value" } ``` #### Agent Service Invocation Format ```json { "agentType": "agent", "agent_name": "Agent Name", "prompt": "Task Content" } ``` ### Tool Invocation Process 1. **LLM Outputs JSON Format**: LLM outputs a tool invocation request based on user needs. 2. **Automatically Parse agentType**: The system first parses the agentType field to determine the invocation type. 3. **Route to Corresponding Manager**: - `mcp` type → Routed to MCPManager for processing. - `agent` type → Routed to AgentManager for processing. 4. **Execute Tool Invocation**: Calls the corresponding service to perform the specific task. 5. **Return Result to LLM**: Returns the tool execution result to LLM. 6. **Loop Processing**: Repeats steps 2-5 until LLM outputs plain text or no tool invocation. ### Configuration Parameters ```python # Tool invocation loop configuration in config.py MAX_handoff_LOOP_STREAM = 5 # Maximum tool invocation loop count in streaming mode MAX_handoff_LOOP_NON_STREAM = 5 # Maximum tool invocation loop count in non-streaming mode SHOW_handoff_OUTPUT = False # Whether to display tool invocation output ``` --- ## 🌐 Multi-Agent and MCP Services ### Dynamic Service Pool Query Functionality #### Core Query Methods ```python from mcpserver.mcp_registry import ( get_all_services_info, # Get all service information get_service_info, # Get details of a single service query_services_by_capability, # Search services by capability get_service_statistics, # Get statistical information get_available_tools # Get service tool list ) ``` #### API Endpoints - `GET /mcp/services` - Get the list of all services and statistical information. - `GET /mcp/services/{service_name}` - Get details of a specified service. - `GET /mcp/services/search/{capability}` - Search services by capability. - `GET /mcp/services/{service_name}/tools` - Get the service tool list. - `GET /mcp/statistics` - Get service statistical information. ### Typical Usage Example ```python # Read file content await s.mcp.handoff( service_name="file", task={"action": "read", "path": "test.txt"} ) # Run Python code await s.mcp.handoff( service_name="coder", task={"action": "run", "file": "main.py"} ) ``` --- ## 🤖 AgentManager Independent System ### System Overview AgentManager is an independent Agent registration and invocation system that supports dynamically loading Agent definitions from configuration files, providing a unified invocation interface and complete lifecycle management. ### Core Features #### 1. Configuration Management - **Dynamic Configuration Loading**: Automatically scans and loads Agent configuration files from the `agent_configs/` directory. - **Configuration Validation**: Automatically validates the integrity and validity of Agent configurations. - **Hot Reload**: Supports reloading configurations at runtime without restarting the system. - **Environment Variable Support**: Supports loading sensitive configurations from environment variables and `.env` files. #### 2. Session Management - **Multi-Session Support**: Each Agent supports multiple independent session contexts. - **History Maintenance**: Automatically maintains dialogue history, supporting context recall. - **Session Expiration**: Automatically cleans up expired session data to save memory. - **Session Isolation**: Complete isolation of sessions for different users and different Agents. #### 3. Intelligent Placeholder Replacement Supports various types of placeholder replacements: **Agent Configuration Placeholders**: - `{{AgentName}}` - Agent name - `{{Description}}` - Description information - `{{ModelId}}` - Model ID - `{{Temperature}}` - Temperature parameter - `{{MaxTokens}}` - Maximum output token count - `{{ModelProvider}}` - Model provider **Environment Variable Placeholders**: - `{{ENV_VAR_NAME}}` - System environment variable **Time Placeholders**: - `{{CurrentTime}}` - Current time (HH:MM:SS) - `{{CurrentDate}}` - Current date (YYYY-MM-DD) - `{{CurrentDateTime}}` - Complete time (YYYY-MM-DD HH:MM:SS) ### Configuration File Format #### Example Agent Configuration File ```json { "ExampleAgent": { "model_id": "deepseek-chat", "name": "Example Assistant", "base_name": "ExampleAgent", "system_prompt": "You are {{AgentName}}, a professional {{Description}}.\n\nCurrent time: {{CurrentDateTime}}\nModel: {{ModelId}}\nTemperature: {{Temperature}}\n\nPlease respond in Chinese, maintaining a professional and friendly attitude.", "max_output_tokens": 8192, "temperature": 0.7, "description": "Intelligent assistant, good at answering various questions", "model_provider": "openai", "api_base_url": "https://api.deepseek.com/v1", "api_key": "{{DEEPSEEK_API_KEY}}" } } ``` ### Usage Example #### Basic Invocation ```python from mcpserver.agent_manager import get_agent_manager # Get AgentManager instance agent_manager = get_agent_manager() # Invoke Agent result = await agent_manager.call_agent( agent_name="ExampleAgent", prompt="Please help me analyze this data", session_id="user_123" ) ``` #### Convenient Function Invocation ```python from mcpserver.agent_manager import call_agent, list_agents, get_agent_info # Convenient invocation result = await call_agent("ExampleAgent", "Hello") # Get Agent list agents = list_agents() ``` --- ## 📋 Agent Manifest Standardization ### Standardization Specification All Agents must use a standardized `agent-manifest.json` configuration file to ensure consistency and maintainability. #### Required Fields - `name`: Unique identifier for the Agent - `displayName`: Display name - `version`: Version number (x.y.z format) - `description`: Function description - `author`: Author or module name - `agentType`: Agent type (mcp/agent) - `entryPoint`: Entry point configuration (module and class) ### Creating a New Agent #### Creating an MCP Type Agent 1. Create a new Agent directory under `mcpserver/`. 2. Copy `AGENT_MANIFEST_TEMPLATE.json` to the Agent directory. 3. Modify the manifest file content. 4. Create the Agent implementation class. 5. Restart the system to automatically register. #### Creating an Agent Type Agent 1. Create a configuration file in the `agent_configs/` directory. 2. Define the Agent configuration (model, prompt, etc.). 3. Configure environment variables (API keys, etc.). 4. Restart the system to automatically load. --- ## 🖥️ System Tray Functionality ### Functional Features - **Console Tray**: Hides the terminal window to the system tray, supporting auto-hide. - **Taskbar Hiding**: Completely hides the console window from the taskbar. - **Tray Icon**: Displays the application icon in the system tray, supporting right-click menu. - **Auto-Start Management**: Supports auto-start functionality via registry. - **Tray Messages**: Supports status notifications and message prompts. ### Usage Method #### Tray Mode Startup ```bash # Windows .\start_with_tray.bat ``` #### Tray Menu Functions - **Show Console**: Restore the console window display from the tray. - **Hide Console**: Hide the console window to the tray. - **Auto-Start on Boot**: Toggle auto-start status. - **Exit**: Completely exit the application. ### Technical Implementation - **Window Hook**: Listens for the console window's close event and intercepts the close operation. - **Window Style**: Uses `WS_EX_TOOLWINDOW` style to prevent the window from displaying in the taskbar. - **Auto-Hide**: Automatically hides the console window 3 seconds after startup. - **Tray Integration**: Implements system tray functionality using PyQt5. ### Notes 1. **Permission Requirements**: The auto-start feature requires administrator privileges. 2. **Dependency Installation**: The `PyQt5` library needs to be installed. 3. **Icon File**: By default, `ui/window_icon.png` is used as the tray icon. 4. **Startup Method**: Use `start_with_tray.bat` to enable tray functionality. --- ## 🌐 RESTful API Service NagaAgent includes a complete RESTful API server that automatically starts when launched, supporting all dialogue functions: ### API Interface Description - **Base Address**: `http://127.0.0.1:8000` (configurable in config.py) - **Interactive Documentation**: `http://127.0.0.1:8000/docs` - **OpenAPI Specification**: `http://127.0.0.1:8000/openapi.json` ### Main Interfaces #### Health Check ```bash GET /health ``` #### Dialogue Interface ```bash # Normal dialogue POST /chat { "message": "Hello, Naga", "session_id": "optional-session-id" } # Streaming dialogue (Server-Sent Events) POST /chat/stream { "message": "Please introduce the development history of artificial intelligence." } ``` #### System Management Interface ```bash # Get system information GET /system/info # Toggle developer mode POST /system/devmode # Get memory statistics GET /memory/stats ``` ## MCP Service Agent Upgrade Instructions - All MCP services (such as file, code, browser, application launch, system control, weather, etc.) have been upgraded to a standard Agent style: - All inherit from `agents.Agent`, with `name`, `instructions` attributes, and `handle_handoff` asynchronous method. - All variables are managed uniformly through `config.py` to avoid repeated definitions. - All comments are in Chinese, with file/class/function comments on one line and variable comments on the right side. - Supports multi-agent collaboration, with ControllerAgent intelligently allocating tasks to BrowserAgent, ContentAgent, etc. - The registration center `mcp_registry.py` automatically discovers and registers all Agent instances that implement `handle_handoff`, supporting hot-plugging. - Automatically outputs the names and descriptions of all registered agents during registration for debugging convenience. - Simplified Agent types: only supports `mcp` and `agent` types. - The handoff mechanism is entirely dispatched through the `handle_handoff` asynchronous method, compatible with both JSON and handoff formats. - Adding/removing agents only requires adding/removing Python files, without restarting the main program. - For detailed interfaces and parameters, please refer to the comments in each Agent's code and the `config.py` configuration. ## Changelog - The tool invocation format has been optimized to a pure JSON format, making it more concise and standardized. Specific examples are as follows: ``` { "agentType": "mcp", "service_name": "MCP Service Name", "tool_name": "Tool Name", "parameter_name": "parameter_value" } ``` --- ## 📝 Frontend UI and Response Adaptation - **All backend returns are structured JSON**: The frontend automatically adapts to various return formats through the `ui/response_utils.py`'s `extract_message` method. - **Priority Display Logic**: Prioritizes displaying `data.content`, then `message`, and finally returns as is, compatible with all Agents. - **Automatic Line Break Adaptation**: The PyQt frontend automatically converts all `\n` and `\\n` line breaks to `<br>`, ensuring multi-line content displays seamlessly. - **UI Animation**: When switching the sidebar, the sidebar width, main chat area width, and input box height all use synchronized animations. - **Theme Customization**: UI animations, themes, nicknames, transparency, etc., can all be flexibly configured in `config.py` and `pyqt_chat_window.py`. --- ## 🔊 Streaming Voice Interaction - **Supports Voice Input**: Streaming recognition, automatically converting to text. - **Supports Voice Output**: Streaming synthesis, outputting while playing. - **Completely Asynchronous Processing**: Reconstructed voice integration system, fully separating text display and audio playback. - **Eliminates Duplicate Playback**: Removed the issue of duplicate playback of streaming segmentation and final text. - **Frontend Immediate Display**: The frontend immediately displays text without waiting for audio processing to complete. - **Dependencies and Configuration**: See `voice/voice_config.py` and related sections in the README. --- ## 🌳 Deep Thinking Engine NagaAgent 3.1 introduces a multi-branch thinking engine based on genetic algorithms, providing higher quality AI responses. ### Core Features - **Multi-Branch Parallel Thinking**: Automatically generates multiple different types of thinking routes based on problem difficulty. - **Problem Difficulty Assessment**: Comprehensive judgment of complexity based on text length, keywords, sentence structure, etc. - **User Preference System**: Supports custom preference configurations, weighting scores for thinking routes. - **Genetic Algorithm Pruning**: Evaluates the fitness of thinking routes, performs crossover fusion, and retains elites. - **Concurrent Thread Pool**: Separates thinking from API calls, enhancing concurrent performance. - **Extensible Architecture**: Supports custom branch types, scoring weights, and evolutionary strategies. ### Thinking Branch Types - **Logical Branch**: Focuses on logical reasoning and factual analysis. - **Creative Branch**: Emphasizes creative thinking and unique insights. - **Analytical Branch**: In-depth analysis and multi-angle thinking. - **Practical Branch**: Focuses on practical applications and operability. - **Philosophical Branch**: Explores deeper meanings and value considerations. ### Usage Example ```python from thinking import TreeThinkingEngine # Initialize the engine engine = TreeThinkingEngine(api_client=your_api_client, memory_manager=your_memory_manager) # Enable deep thinking result = await engine.think_deeply("Please analyze the future development trends of artificial intelligence.") print(result["answer"]) # Output the comprehensive final answer ``` --- ## 📝 Other Highlights - **Dynamic Memory Weight Adjustment**: Supports AI/human marking as important, with weights/threshholds/cleanup strategies all managed uniformly in `config.py`. - **Automated Topic Classification**: Topic classification, recall, weight enhancement, cleanup, etc., are all automated. - **Retrieval Logs Automatically Recorded**: Adjustable parameters, GRAG configuration examples can be found in `config.py`. - **Historical Dialogue Compatibility Upgrade**: Supports one-click import of old txt dialogue content into the GRAG knowledge graph memory system. - **Tool Invocation Loop Automatic Execution Mechanism**: Supports multi-round recursive calls, with maximum loop counts configurable. - **All Agent Registration Metadata Centralized in `mcpserver/mcp_registry.py`**: Main flow and manager are simplified, making expansion and maintenance easier. - **Automatic Registration/Hot-Plug Agent Mechanism**: Adding/removing Agents only requires adding/removing Python files, without restarting the main program. - **Agent Manifest Standardization**: Unified `agent-manifest.json` format, supporting complete field validation and type checking. - **Dynamic Service Pool Query**: The system automatically discovers and registers services by scanning `agent-manifest.json`, without manually configuring a static service list. - **AgentManager Independent System**: Supports loading Agent configurations, session management, message assembly, and LLM invocation, providing complete Agent lifecycle management. - **Intelligent Placeholder Replacement**: Supports various placeholders for Agent configurations, environment variables, time information, etc., enabling dynamic prompt generation. - **Complete Message Sequence Construction**: Automatically assembles system messages, historical messages, and user messages to ensure the integrity of dialogue context. - **Multi-Model Provider Support**: Supports multiple LLM providers such as OpenAI, DeepSeek, Anthropic, etc., with each Agent configurable independently. - **Session Isolation and TTL Management**: Supports multi-user multi-session isolation, automatically cleaning up expired session data. - **Unified Tool Invocation Interface**: MCP and Agent-type services are invoked through a unified JSON format, supporting mixed invocation scenarios. - **Configuration Hot Update System**: Complete functionality for real-time configuration changes, configuration snapshots, module reloading, and automatic monitoring. --- ## 📋 Changelog ### v3.1.0 (2024-08-17) #### 🚀 New Features - **Deep Thinking Engine**: Multi-branch thinking system based on genetic algorithms. - **AgentManager**: Independent Agent registration and invocation system. - **Modular UI Rendering**: New message rendering system supporting name + message box layout. - **MQTT Communication Support**: New MQTT tool module added. - **Word Document Processing**: Integrated Office Word MCP service. - **Comic Download Agent**: New comic download functionality Agent. - **Configuration Hot Update System**: Real-time configuration changes without restarting the application. #### 🔧 Feature Improvements - **Voice Service Upgrade**: OpenAI compatible TTS service, supporting multiple audio formats. - **System Tray Enhancements**: Complete background operation and auto-start support. - **Configuration Management Optimization**: Unified configuration file structure and environment variable support. - **Configuration Hot Update**: Supports real-time configuration changes and module reloading. - **Dependency Management**: Modernized dependency management using pyproject.toml. - **Agent Hot-Plugging**: Supports dynamic loading and unloading of Agents at runtime. #### 🐛 Bug Fixes - **Memory Leak**: Fixed memory leak issue in session management. - **Concurrent Processing**: Improved stability of multi-threaded concurrent processing. - **Configuration Validation**: Enhanced validation and error handling of configuration files. - **Configuration Hot Update**: Fixed configuration snapshot serialization and update delay issues. - **UI Responsiveness**: Optimized the responsiveness of the UI interface and user experience. #### 📚 Documentation Updates - Improved README documentation for all modules. - Updated installation and configuration guides. - Added API interface documentation. - Included troubleshooting guide. - Added user guide and test report for the configuration hot update system. --- ## 🆙 Historical Dialogue Compatibility Upgrade - **Supports one-click import of old txt dialogue content into the GRAG knowledge graph memory system**: Compatible with all new features such as topics, hierarchy, quintuple, etc. - **Activation Command**: ``` # Summer Garden System Compatibility Upgrade ``` - **The system will automatically traverse all txt logs in the logs directory**: Lists all historical dialogue content and numbers them, outputting to the terminal and `summer_memory/history_dialogs.json`. - **Users can view the numbered list and choose the import method**: - Import all: ``` python summer_memory/main.py import all ``` - Selective import (e.g., entries 1, 3, 5-8): ``` python summer_memory/main.py import 1,3,5-8 ``` - **Compatibility process automatically avoids duplicates**: Content already in the database will not be imported again, supporting resuming from breakpoints. - **All compatible content is automatically categorized and layered by AI**: Fully consistent with the new system. - **Detailed progress, results, and exceptions are all reported**: Safe and efficient. --- ## 🔧 Latest Updates (v3.0.5) ### System Tray Functionality Enhancements - **Console Tray Functionality**: Achieves true "minimize to tray" functionality. - **Window Hook**: Listens for the console window's close event and intercepts the close operation. - **Taskbar Hiding**: Uses `WS_EX_TOOLWINDOW` style to prevent the window from displaying in the taskbar. - **Auto-Hide**: Automatically hides the console window 3 seconds after startup. - **Tray Messages**: Supports tray message notifications and status prompts. ### MCP Tool Dependencies - **New Dependencies**: Added `jmcomic` and `fastmcp` dependencies to `requirements.txt`. - **Virtual Environment Installation**: Ensure dependencies are installed in the virtual environment. - **Dependency Verification**: Provides a script to verify dependency installation. ### Technical Improvements - **Window Monitoring**: Added a window status monitoring thread to detect window display/hide status in real-time. - **Style Management**: Saves and restores the original window style to ensure functional stability. - **Error Handling**: Enhanced error handling mechanisms for window operations and tray functionality. --- ## ❓ Frequently Asked Questions ### Environment Check ```bash python check_env.py ``` ### Windows Environment - **Python version/dependencies/virtual environment/browser driver issues**: See `setup.ps1` and this README. - **IDE reports import errors**: Restart and select the correct interpreter. - **Voice dependency installation fails**: First install C++ Build Tools. - **MCP tool dependency missing**: Run `pip install jmcomic fastmcp`. ### macOS Environment - **Python version too low**: `brew install python@3.11`. - **PyAudio installation fails**: `brew install portaudio && pip install pyaudio`. - **Permission issues**: `chmod +x *.sh`. ### API Server Issues - **Port Occupied**: Modify `config.py`'s `API_SERVER_PORT`. - **Proxy Interference**: Temporarily disable the proxy `unset ALL_PROXY http_proxy https_proxy`. - **Missing Dependencies**: Ensure FastAPI and Uvicorn are installed `pip install fastapi uvicorn[standard]`. - **Cannot Access**: Check firewall settings to ensure the port is not blocked. ### Tool Invocation Issues - **Too Many Tool Invocation Loops**: Adjust `MAX_handoff_LOOP_STREAM` and `MAX_handoff_LOOP_NON_STREAM` in `config.py`. - **Tool Invocation Fails**: Check if the MCP service is running properly and review log output. - **Format Error**: Ensure LLM output strictly follows JSON format. ### GRAG Memory System Issues - **Neo4j Connection Failed**: Check if the Neo4j service is running and confirm connection parameters are correct. - **Memory Query Returns No Results**: Check if the quintuple is correctly extracted and stored. - **Performance Issues**: Adjust GRAG-related parameters in `config.py`. ### System Tray Issues - **Tray Icon Not Displaying**: Check if the icon file exists and confirm PyQt5 is installed correctly. - **Console Tray Not Working**: Ensure you start with `start_with_tray.bat`. - **Auto-Start Fails**: Confirm administrator privileges and check registry permissions. - **Window Minimization Issues**: Check if tray integration is correct and confirm event handling functions. ### AgentManager Issues - **Agent Configuration Loading Fails**: Check if the JSON files in the `agent_configs/` directory are correctly formatted. - **API Call Fails**: Confirm API key configuration is correct and check network connection. - **Session History Lost**: Check session TTL configuration to ensure sessions are not expired. - **Placeholder Replacement Fails**: Confirm environment variables are set correctly. - **High Memory Usage**: Adjust `max_history_rounds` parameter to reduce the number of historical messages. ### Configuration Hot Update Issues - **Configuration Update Fails**: Check if the config.json file format is correct and confirm file permissions. - **Configuration Snapshot Restoration Fails**: Ensure snapshot data is complete and check for JSON serialization issues. - **Module Reloading Fails**: Confirm the module has a `reload_config` method and check module dependencies. - **Configuration Monitor Not Working**: Ensure you start the monitor using `start_config_watcher()`. - **Configuration File Corrupted**: Restore using backup files or regenerate the configuration file. ### General Issues - **Browser Cannot Start**: Check Playwright installation and network. - **Theme Tree/Index/Parameters/Keys are all managed uniformly in `config.py`.** - **Chat Input `#devmode` enters developer mode**: Subsequent dialogues will not be written to GRAG memory, only for tool invocation testing. ### Best Practices #### Agent Configuration Best Practices 1. **Use Environment Variables**: Sensitive information like API keys should use environment variables. 2. **Set Parameters Reasonably**: Adjust temperature and max_output_tokens according to task requirements. 3. **Optimize Prompts**: Use placeholders for dynamic content to enhance flexibility. 4. **Session Management**: Set session TTL reasonably to avoid memory leaks. #### Performance Optimization Suggestions 1. **Cache Configuration**: Enable configuration caching to reduce file read overhead. 2. **Concurrency Control**: Reasonably control the number of concurrent Agent calls. 3. **Resource Cleanup**: Regularly clean up expired sessions and temporary data. 4. **Monitor Logs**: Enable debug mode to monitor system performance. 5. **Configuration Hot Update**: Use batch updates to reduce reload frequency and avoid frequent configuration changes. #### Security Recommendations 1. **API Key Management**: Use environment variables or key management services. 2. **Input Validation**: Validate and sanitize user inputs. 3. **Error Handling**: Avoid leaking sensitive information in error messages. 4. **Access Control**: Implement appropriate access control mechanisms. 5. **Configuration Backup**: Regularly back up configuration files and use configuration snapshot functionality. --- ## 🤝 Contribution Guidelines We welcome all forms of contributions! Please read the following guidelines: ### 📋 How to Contribute - **Report Issues**: Use GitHub Issues to submit bug reports. - **Feature Suggestions**: Propose new feature requests and suggestions. - **Code Contributions**: Submit Pull Requests to improve the code. - **Documentation Improvements**: Enhance project documentation and usage instructions. ### 📝 Development Standards - Follow PEP 8 coding style. - Add appropriate comments and documentation. - Ensure code tests pass. - Update relevant documentation. ### 📞 Contact Information - **Issues**: [GitHub Issues](https://github.com/Xxiii8322766509/NagaAgent/issues) - **Discussions**: [GitHub Discussions](https://github.com/Xxiii8322766509/NagaAgent/discussions) --- ## 🙏 Acknowledgments Thanks to the following open-source projects and contributors: - **[OpenAI](https://openai.com/)** - Provides powerful AI models. - **[Neo4j](https://neo4j.com/)** - Graph database support. - **[PyQt5](https://riverbankcomputing.com/software/pyqt/)** - GUI framework. - **[FastAPI](https://fastapi.tiangolo.com/)** - Modern web framework. - **[MCP](https://modelcontextprotocol.io/)** - Model context protocol. - All contributors and community members. --- ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. <div align="center"> --- **⭐ If this project has been helpful to you, please consider giving us a Star!** </div>