Naga Agent

# NagaAgent 2.2beta > Intelligent dialogue assistant, supporting multiple MCP services, streaming voice interaction, topic tree retrieval, and an extremely concise code style. --- ## ⚡ Quick Start 1. Clone the project ```powershell git clone [project address] cd NagaAgent ``` 2. One-click configuration ```powershell .\setup.ps1 ``` - Automatically create a virtual environment and install dependencies - Check/download Chinese vector model - Configure LLM that supports toolcall, recommended DeepSeekV3 3. Start ```powershell .\start.bat ``` --- ## 🖥️ System Requirements - Windows 10/11 - Python 3.13+ - PowerShell 5.1+ --- ## 🛠️ Dependency Installation and Environment Configuration - All dependencies are listed in `requirements.txt` - If installation fails for `greenlet`, `pyaudio`, etc., first install [Microsoft Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/), check C++ build tools, and restart the command line before running `pip install -r requirements.txt` - Browser automation requires `playwright`, and for the first use, run `python -m playwright install chromium` - Dependency installation command: ```powershell python -m venv .venv .venv\Scripts\Activate pip install -r requirements.txt python -m playwright install chromium ``` --- ## 🌟 Main Features - **Unified management of global variables/paths/keys in `config.py`**, supporting .env and environment variables, with all variables being unique and without duplicate definitions - Streaming dialogue with DeepSeek, supporting context recall and topic tree fragment retrieval - Faiss vector database, HNSW+PQ hybrid indexing, asynchronous acceleration, dynamic depth adjustment, dynamic weight adjustment, and automatic cleanup - MCP service integration, Agent Handoff intelligent distribution, supporting custom filters and callbacks - **Multi-Agent capability expansion: plug-and-play agents for browsers, files, code, etc., all agents can be uniformly called through the handoff mechanism** - Extremely concise code, with all comments in Chinese, decoupled components for easy expansion - PyQt5 animations and UI, supporting PNG sequence frames, with very fast loading animations - Automatic management of logs/retrieval/indexing/topics/parameters - Dynamic adjustment of memory weights, supporting AI/human marking of important content, with weight/threshold/cleanup strategies all managed in `config.py` - **All front-end UI is decoupled from the back-end, with the front-end only needing to parse back-end JSON, automatically adapting to various return structures like message/data.content** - **Automatic adaptation of line breaks in the front-end, whether the back-end returns `\n` or `\\n`, the PyQt interface can display correctly** - **All Agent handoff schemas and registration metadata are centralized in `mcpserver/mcp_registry.py`, with a very simple main process and manager, making expansion and maintenance easier. Only one place needs to be maintained to batch register/expand all Agent services.** - **Automatic registration/hot-plugging Agent mechanism, adding/removing Agents only requires adding/removing py files, no need to restart the main program** --- ## 🗂️ Directory Structure ``` NagaAgent/ ├── main.py # Main entry point ├── config.py # Global configuration ├── conversation_core.py # Core dialogue (including main logic for compatibility mode) ├── mcp_manager.py # MCP service management ├── requirements.txt # Dependencies ├── summer/ # Faiss and vector related │ ├── memory_manager.py # Main module for memory management │ ├── summer_faiss.py # Faiss related operations │ ├── faiss_index.py # Faiss index management │ ├── embedding.py # Vector encoding │ ├── memory_flow/ # Memory hierarchy related │ └── summer_upgrade/ # Compatibility upgrade related scripts │ └── compat_txt_to_faiss.py # Main script for historical dialogue compatibility ├── logs/ # Logs (including historical txt dialogues) │ ├── 2025-04-27.txt │ ├── 2025-05-05.txt │ ├── ... │ └── faiss/ # Faiss index and metadata ├── voice/ # Voice related │ ├── voice_config.py │ └── voice_handler.py ├── ui/ # Front-end UI │ ├── pyqt_chat_window.py # PyQt chat window │ └── response_utils.py # General response parsing tool for the front-end ├── models/ # Vector models, etc. ├── README.md # Project description └── ... ``` --- ## 🌐 Multi-Agent and MCP Services - **All Agent registrations, schemas, and descriptions are centralized in `mcpserver/mcp_registry.py`, allowing for batch management and extremely simple expansion** - Supports various Agents such as browsers, files, and code, all of which can be uniformly called through the handoff mechanism - Agent capabilities are plug-and-play, with automatic registration/hot-plugging, no need to restart the main program - Typical usage examples: ```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"} ) ``` --- ## 📝 Front-end UI and Response Adaptation - **All back-end returns are structured JSON, and the front-end automatically adapts to various return formats through the `ui/response_utils.py`'s `extract_message` method** - Prioritizes displaying `data.content`, then `message`, and finally returns as is, compatible with all Agents - The PyQt front-end automatically converts all `\n` and `\\n` line breaks to `<br>`, ensuring multi-line content displays without issues - 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) and voice output (streaming synthesis, playing while outputting) - Dependencies and configurations are detailed in `voice/voice_config.py` and related sections of the README --- ## 📝 Other Highlights - Memory weights, forgetting thresholds, redundancy removal, short-term/long-term memory capacity, etc., are all uniformly managed in `config.py` for flexible adjustments - Topic classification, recall, weight enhancement, cleanup, etc., are all automated, with AI/human marking of important content, ensuring important content is not cleaned within a year - Retrieval logs are automatically recorded, with adjustable parameters; examples of Faiss configuration can be found in `config.py` - The chat window's background transparency, username, topic tree recall, streaming output, sidebar animations, etc., are all customizable - Supports one-click import of historical dialogues into the AI multi-layer memory system, compatible with all new features such as topics, hierarchy, and embedding - Multi-Agent step-by-step pipeline automatic execution mechanism, supporting automatic parsing of plan structures and multi-step execution --- For detailed functionality/API/extension descriptions, see the comments and code in each module, with all variables being unique, comments in Chinese, and extremely concise. ## 🆙 Historical Dialogue Compatibility Upgrade - Supports one-click import of old version txt dialogue content into the AI multi-layer memory system, compatible with all new features such as topics, hierarchy, and embedding. - Activation command: ``` # Summer system compatibility upgrade ``` - The system will automatically traverse all txt logs in the logs directory, list all historical dialogue content with numbering, and output to the terminal and `summer/summer_upgrade/history_dialogs.json`. - Users can view the numbered list and choose the import method: - Import all: ``` python summer/summer_upgrade/compat_txt_to_faiss.py import all ``` - Selective import (e.g., items 1, 3, 5-8): ``` python summer/summer_upgrade/compat_txt_to_faiss.py import 1,3,5-8 ``` - The compatibility process automatically checks for duplicates, ensuring that already stored content is not imported again, and supports resuming from breakpoints. - All compatible content undergoes AI automatic topic classification and hierarchy, fully consistent with the new system. - Detailed progress, results, and exceptions are provided for feedback, ensuring safety and efficiency. ## 📚 Directory Structure ``` NagaAgent/ ├── main.py # Main entry point ├── config.py # Global configuration ├── conversation_core.py # Core dialogue (including main logic for compatibility mode) ├── mcp_manager.py # MCP service management ├── requirements.txt # Dependencies ├── summer/ # Faiss and vector related │ ├── memory_manager.py # Main module for memory management │ ├── summer_faiss.py # Faiss related operations │ ├── faiss_index.py # Faiss index management │ ├── embedding.py # Vector encoding │ ├── memory_flow/ # Memory hierarchy related │ └── summer_upgrade/ # Compatibility upgrade related scripts │ └── compat_txt_to_faiss.py # Main script for historical dialogue compatibility ├── logs/ # Logs (including historical txt dialogues) │ ├── 2025-04-27.txt │ ├── 2025-05-05.txt │ ├── ... │ └── faiss/ # Faiss index and metadata ├── voice/ # Voice related │ ├── voice_config.py │ └── voice_handler.py ├── ui/ # Front-end UI │ └── pyqt_chat_window.py # PyQt chat window ├── models/ # Vector models, etc. ├── README.md # Project description └── ... ``` ## ❓ Frequently Asked Questions - For issues related to Python version/dependencies/virtual environment/browser drivers, see `setup.ps1` and this README - If the IDE reports import errors, restart and select the correct interpreter - If voice dependencies fail to install, first install C++ Build Tools - If the browser fails to start, check the playwright installation and network - All topic trees/indexes/parameters/keys are uniformly managed in `config.py` ## 📝 Development Mode - Enter developer mode by typing `#devmode` in the chat input, subsequent dialogues will not be written to Faiss and will only be used for MCP testing ## 📝 License MIT License --- For detailed functionality/API/extension descriptions, see the comments and code in each module, with all variables being unique, comments in Chinese, and extremely concise. ## Chat Window Customization 1. The chat window background transparency is uniformly controlled by `config.BG_ALPHA`, with a value range of 0 to 1, defaulting to 0.4. 2. The username is automatically recognized as the computer name, variable `config.USER_NAME`, and can be customized by directly modifying this variable. ## Intelligent Historical Recall Mechanism 1. By default, historical dialogues are retrieved by topic fragments, which is very fast and highly relevant. 2. If fragments cannot be found, it automatically falls back to traverse all topic fragments for fuzzy retrieval (faiss_fuzzy_recall), allowing for topic jumps to recall history. 3. `faiss_fuzzy_recall` can be called directly, returning the globally most relevant history. 4. The fallback logic is integrated into the main process, requiring no manual switching. ## ⚡️ Brand New Streaming Output Mechanism - AI replies support full-link streaming output between front-end and back-end, displaying as they are generated, providing an extremely smooth experience. - The back-end uses async generators to yield segmented content, while the front-end Worker thread streams signals in real-time to the dialogue box. - Completely free of terminal print pollution, supporting large texts without lag. - If dependency package conflicts occur, it is recommended to thoroughly clean the global PYTHONPATH and environment variables, using only the virtual environment. ## Sidebar and Main Chat Area Animation Optimization Description - When switching the sidebar, the sidebar width, main chat area width, and input box height all use synchronized animations to enhance visual smoothness. - The input box hides using height animations, automatically clearing focus after the animation ends to avoid input method residue. - Thread processing includes automatic release to prevent memory leaks. - Related animation effects can be customized in the `toggle_full_img` method of `ui/pyqt_chat_window.py`. ### Usage Instructions - Click the sidebar to toggle the character illustration expansion/collapse, and the main chat area and input box will automatically adjust and hide/recover. - Animation duration, easing curves, etc., can be adjusted according to the source code parameters as needed. ## Multi-Agent Step-by-Step Pipeline Automatic Execution Mechanism The system supports automatic parsing and sequential execution of each step when the LLM outputs a plan structure: - Each step can contain an action structure, specifying the agent and params parameters - The system automatically calls the corresponding agent, supporting context passing between multiple steps - Real-time feedback of each step's execution results, with a summary after all are completed - Other steps without actions only output descriptions and do not execute automatically Example plan structure: ```json { "plan": { "goal": "Complete a complex multi-step task", "steps": [ {"desc": "Description of the first step", "action": {"agent": "file", "params": {"action": "read", "path": "test.txt"}}}, {"desc": "Description of the second step", "action": {"agent": "coder", "params": {"action": "edit", "file": "test.py", "code": "print('hello')"}}} ] } } ``` For custom Agent or plan protocol extensions, please refer to `mcpserver/agent_xxx/` and `mcp_registry.py`.