deepcode-hku 1.0.9__tar.gz → 1.2.0__tar.gz

{deepcode_hku-1.0.9/deepcode_hku.egg-info → deepcode_hku-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepcode-hku
-Version: 1.0.9
+Version: 1.2.0
 Summary: AI Research Engine - Transform research papers into working code automatically
 Home-page: https://github.com/HKUDS/DeepCode
 Author: DeepCodeTeam
@@ -200,6 +200,7 @@ Dynamic: summary
 - [🏗️ Architecture](#️-architecture)
 - [📊 Experimental Results](#-experimental-results)
 - [🚀 Quick Start](#-quick-start)
+- [🤖 nanobot Integration (Feishu Chatbot)](#-nanobot-integration-feishu-chatbot)
 - [💡 Examples](#-examples)
   - [🎬 Live Demonstrations](#-live-demonstrations)
 - [⭐ Star History](#-star-history)
@@ -210,7 +211,35 @@ Dynamic: summary
 
 ## 📰 News
 
-🎨 **[2025-02] New Web UI Experience Upgrade!**
+🎉 **[2025-02] DeepCode + nanobot Integration — Chat with DeepCode via Feishu Bot!**
+
+<div align="center">
+<table><tr>
+<td align="center"><a href="https://github.com/HKUDS/DeepCode"><img src="./assets/logo.png" alt="DeepCode" height="60"/></a></td>
+<td align="center"><h2>✦</h2></td>
+<td align="center"><a href="https://github.com/HKUDS/nanobot"><img src="./assets/nanobot.png" alt="nanobot" height="60"/></a></td>
+</tr></table>
+</div>
+
+- [nanobot](https://github.com/HKUDS/nanobot) now connects to DeepCode — send messages in **Feishu** and get auto-generated code back
+- Supports **Paper-to-Code** and **Chat-to-Code**, plus real-time task tracking, all from your chat app
+- One-command deploy: `./nanobot/run_nanobot.sh` → **[Setup Guide →](#-nanobot-integration-feishu-chatbot)**
+
+<div align="center">
+<table width="100%"><tr>
+<td width="50%" align="center">
+  <img src="./assets/IMG_8098.jpeg" alt="Feishu Chat Example 1" width="95%" style="border-radius: 10px; box-shadow: 0 4px 15px rgba(0,0,0,0.2);"/>
+</td>
+<td width="50%" align="center">
+  <img src="./assets/IMG_8099.jpeg" alt="Feishu Chat Example 2" width="95%" style="border-radius: 10px; box-shadow: 0 4px 15px rgba(0,0,0,0.2);"/>
+</td>
+</tr></table>
+<sub><em>Feishu Bot in Action — Natural language → Full code generation with setup instructions</em></sub>
+</div>
+
+---
+
+🎉 **[2025-02] New Web UI Experience Upgrade!**
 
 - 🔄 **User-in-Loop Interaction**: Support real-time user interaction during workflows - AI asks clarifying questions directly in the chat
 - 💬 **Inline Interaction Design**: Interaction prompts appear naturally within the chat flow for a seamless experience
@@ -226,7 +255,7 @@ Dynamic: summary
 
 ---
 
-🎉 **[2025-10] 🎉 [2025-10-28] DeepCode Achieves SOTA on PaperBench!**
+🎉 **[2025-10-28] DeepCode Achieves SOTA on PaperBench!**
 
 DeepCode sets new benchmarks on OpenAI's PaperBench Code-Dev across all categories:
 
@@ -629,6 +658,8 @@ sudo apt-get install -y nodejs
 
 ### 📦 **Step 1: Installation**
 
+Choose one of the following installation methods:
+
 #### ⚡ **Direct Installation (Recommended)**
 
 ```bash
@@ -638,29 +669,6 @@ pip install deepcode-hku
 # 🔑 Download configuration files
 curl -O https://raw.githubusercontent.com/HKUDS/DeepCode/main/mcp_agent.config.yaml
 curl -O https://raw.githubusercontent.com/HKUDS/DeepCode/main/mcp_agent.secrets.yaml
-
-# 🔑 Configure API keys (required)
-# Edit mcp_agent.secrets.yaml with your API keys and base_url:
-# - openai: api_key, base_url (for OpenAI/custom endpoints)
-# - anthropic: api_key (for Claude models)
-# - google: api_key (for Gemini models)
-
-# 🤖 Select your preferred LLM provider (optional)
-# Edit mcp_agent.config.yaml to choose your LLM (line ~106):
-# - llm_provider: "google"    # Use Google Gemini models
-# - llm_provider: "anthropic" # Use Anthropic Claude models
-# - llm_provider: "openai"    # Use OpenAI/compatible models
-# Note: If not set or unavailable, will automatically fallback to first available provider
-
-# 🔑 Configure search API keys for web search (optional)
-# Edit mcp_agent.config.yaml to set your API keys:
-# - For Brave Search: Set BRAVE_API_KEY: "your_key_here" in brave.env section (line ~28)
-# - For Bocha-MCP: Set BOCHA_API_KEY: "your_key_here" in bocha-mcp.env section (line ~74)
-
-# 📄 Configure document segmentation (optional)
-# Edit mcp_agent.config.yaml to control document processing:
-# - enabled: true/false (whether to use intelligent document segmentation)
-# - size_threshold_chars: 50000 (document size threshold to trigger segmentation)
 ```
 
 #### 🔧 **Development Installation (From Source)**
@@ -671,79 +679,91 @@ curl -O https://raw.githubusercontent.com/HKUDS/DeepCode/main/mcp_agent.secrets.
 ##### 🔥 **Using UV (Recommended for Development)**
 
 ```bash
-# 🔽 Clone the repository
 git clone https://github.com/HKUDS/DeepCode.git
 cd DeepCode/
 
-# 📦 Install UV package manager
 curl -LsSf https://astral.sh/uv/install.sh | sh
-
-# 🔧 Install dependencies with UV
 uv venv --python=3.13
 source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 uv pip install -r requirements.txt
 
-# 🔑 Configure API keys (required)
-# Edit mcp_agent.secrets.yaml with your API keys and base_url:
-# - openai: api_key, base_url (for OpenAI/custom endpoints)
-# - anthropic: api_key (for Claude models)
-# - google: api_key (for Gemini models)
-
-# 🤖 Select your preferred LLM provider (optional)
-# Edit mcp_agent.config.yaml to choose your LLM (line ~106):
-# - llm_provider: "google"    # Use Google Gemini models
-# - llm_provider: "anthropic" # Use Anthropic Claude models
-# - llm_provider: "openai"    # Use OpenAI/compatible models
-# Note: If not set or unavailable, will automatically fallback to first available provider
-
-# 🔑 Configure search API keys for web search (optional)
-# Edit mcp_agent.config.yaml to set your API keys:
-# - For Brave Search: Set BRAVE_API_KEY: "your_key_here" in brave.env section (line ~28)
-# - For Bocha-MCP: Set BOCHA_API_KEY: "your_key_here" in bocha-mcp.env section (line ~74)
-
-# 📄 Configure document segmentation (optional)
-# Edit mcp_agent.config.yaml to control document processing:
-# - enabled: true/false (whether to use intelligent document segmentation)
-# - size_threshold_chars: 50000 (document size threshold to trigger segmentation)
+# Install frontend dependencies
+npm install --prefix new_ui/frontend
 ```
 
 ##### 🐍 **Using Traditional pip**
 
 ```bash
-# 🔽 Clone the repository
 git clone https://github.com/HKUDS/DeepCode.git
 cd DeepCode/
 
-# 📦 Install dependencies
 pip install -r requirements.txt
 
-# 🔑 Configure API keys (required)
-# Edit mcp_agent.secrets.yaml with your API keys and base_url:
-# - openai: api_key, base_url (for OpenAI/custom endpoints)
-# - anthropic: api_key (for Claude models)
-# - google: api_key (for Gemini models)
-
-# 🤖 Select your preferred LLM provider (optional)
-# Edit mcp_agent.config.yaml to choose your LLM (line ~106):
-# - llm_provider: "google"    # Use Google Gemini models
-# - llm_provider: "anthropic" # Use Anthropic Claude models
-# - llm_provider: "openai"    # Use OpenAI/compatible models
-# Note: If not set or unavailable, will automatically fallback to first available provider
-
-# 🔑 Configure search API keys for web search (optional)
-# Edit mcp_agent.config.yaml to set your API keys:
-# - For Brave Search: Set BRAVE_API_KEY: "your_key_here" in brave.env section (line ~28)
-# - For Bocha-MCP: Set BOCHA_API_KEY: "your_key_here" in bocha-mcp.env section (line ~74)
-
-# 📄 Configure document segmentation (optional)
-# Edit mcp_agent.config.yaml to control document processing:
-# - enabled: true/false (whether to use intelligent document segmentation)
-# - size_threshold_chars: 50000 (document size threshold to trigger segmentation)
+# Install frontend dependencies
+npm install --prefix new_ui/frontend
 ```
 
 </details>
 
-#### 🪟 **Windows Users: Additional MCP Server Configuration**
+### 🔧 **Step 2: Configuration**
+
+> The following configuration applies to **all installation methods** (pip, UV, source, and Docker).
+
+#### 🔑 API Keys *(required)*
+
+Edit `mcp_agent.secrets.yaml` with your API keys:
+
+```yaml
+# At least ONE provider API key is required
+openai:
+  api_key: "your_openai_api_key"
+  base_url: "https://openrouter.ai/api/v1"  # Optional: for OpenRouter or custom endpoints
+
+anthropic:
+  api_key: "your_anthropic_api_key"  # For Claude models
+
+google:
+  api_key: "your_google_api_key"     # For Gemini models
+```
+
+#### 🤖 LLM Provider *(optional)*
+
+Edit `mcp_agent.config.yaml` to choose your preferred LLM provider (line ~106):
+
+```yaml
+# Options: "google", "anthropic", "openai"
+# If not set or unavailable, will automatically fallback to first available provider
+llm_provider: "google"
+```
+
+#### 🔍 Search API Keys *(optional)*
+
+Configure web search in `mcp_agent.config.yaml`:
+
+```yaml
+# For Brave Search (default) — set in brave.env section (line ~28)
+brave:
+  env:
+    BRAVE_API_KEY: "your_brave_api_key_here"
+
+# For Bocha-MCP (alternative) — set in bocha-mcp.env section (line ~74)
+bocha-mcp:
+  env:
+    BOCHA_API_KEY: "your_bocha_api_key_here"
+```
+
+#### 📄 Document Segmentation *(optional)*
+
+Control document processing in `mcp_agent.config.yaml`:
+
+```yaml
+document_segmentation:
+  enabled: true          # true/false — whether to use intelligent document segmentation
+  size_threshold_chars: 50000  # Document size threshold to trigger segmentation
+```
+
+<details>
+<summary><strong>🪟 Windows Users: Additional MCP Server Configuration</strong></summary>
 
 If you're using Windows, you may need to configure MCP servers manually in `mcp_agent.config.yaml`:
 
@@ -771,7 +791,10 @@ mcp:
 
 > **Note**: Replace the path with your actual global node_modules path from step 2.
 
-#### 🔍 **Search Server Configuration (Optional)**
+</details>
+
+<details>
+<summary><strong>🔍 Search Server Configuration (Optional)</strong></summary>
 
 DeepCode supports multiple search servers for web search functionality. You can configure your preferred option in `mcp_agent.config.yaml`:
 
@@ -782,17 +805,10 @@ default_search_server: "brave"
 ```
 
 **Available Options:**
-- **🔍 Brave Search** (`"brave"`):
-  - Default option with high-quality search results
-  - Requires BRAVE_API_KEY configuration
-  - Recommended for most users
-
-- **🌐 Bocha-MCP** (`"bocha-mcp"`):
-  - Alternative search server option
-  - Requires BOCHA_API_KEY configuration
-  - Uses local Python server implementation
+- **🔍 Brave Search** (`"brave"`): Default option with high-quality search results. Requires `BRAVE_API_KEY`. Recommended for most users.
+- **🌐 Bocha-MCP** (`"bocha-mcp"`): Alternative search server. Requires `BOCHA_API_KEY`. Uses local Python server implementation.
 
-**API Key Configuration in mcp_agent.config.yaml:**
+**Full MCP server configuration in mcp_agent.config.yaml:**
 ```yaml
 # For Brave Search (default) - around line 28
 brave:
@@ -812,87 +828,266 @@ bocha-mcp:
 
 > **💡 Tip**: Both search servers require API key configuration. Choose the one that best fits your API access and requirements.
 
-### ⚡ **Step 2: Launch Application**
+</details>
+
+### ⚡ **Step 3: Launch Application**
+
+Choose your preferred launch method:
+
+<table width="100%">
+<tr>
+<th width="33%">🐳 Docker (Recommended)</th>
+<th width="33%">🚀 Local (<code>deepcode</code> command)</th>
+<th width="33%">🛠️ Other Methods</th>
+</tr>
+<tr><td>
 
-#### 🚀 **Using `deepcode` Command (Recommended)**
+No Python/Node needed — everything in container.
 
 ```bash
-# 🌐 Launch the new React-based web interface
-deepcode
+git clone https://github.com/HKUDS/DeepCode.git
+cd DeepCode/
+cp mcp_agent.secrets.yaml.example \
+   mcp_agent.secrets.yaml
+# Edit secrets with your API keys
 
-# Frontend: http://localhost:5173
-# Backend API: http://localhost:8000
-# Press Ctrl+C to stop all services
+./deepcode_docker/run_docker.sh
+# Access → http://localhost:8000
 ```
-<div align="center">
-  <img src="https://img.shields.io/badge/Frontend-localhost:5173-00d4ff?style=flat-square&logo=react&logoColor=white" alt="Frontend" />
-  <img src="https://img.shields.io/badge/Backend-localhost:8000-4ecdc4?style=flat-square&logo=fastapi&logoColor=white" alt="Backend" />
-</div>
 
-> **📦 Auto Install**: On first run, dependencies are automatically installed (`pip install` for backend, `npm install` for frontend)
+</td><td>
 
-> **✨ Features**: User-in-Loop interaction, real-time progress tracking, inline chat interaction
+Auto-installs deps on first run.
 
-#### 🛠️ **Alternative Launch Methods**
+```bash
+deepcode
+# Frontend → http://localhost:5173
+# Backend  → http://localhost:8000
+# Ctrl+C to stop
+```
 
-<table>
-<tr>
-<td><strong>🍎 macOS / 🐧 Linux</strong></td>
-<td><strong>🪟 Windows</strong></td>
-</tr>
-<tr>
-<td>
+Features: User-in-Loop, real-time progress, inline chat.
+
+</td><td>
 
 ```bash
-# Using run.sh
+# macOS / Linux
 ./run.sh
+# or: python deepcode.py
 
-# Or using Python directly
-python deepcode.py
-```
-
-</td>
-<td>
-
-```cmd
-# Using run.bat
+# Windows
 run.bat
+# or: python deepcode.py
 
-# Or using Python directly
-python deepcode.py
+# Classic Streamlit UI
+deepcode --classic
+
+# CLI mode
+deepcode --cli
+# or: python cli/main_cli.py
 ```
 
-</td>
-</tr>
+</td></tr>
 </table>
 
+<details>
+<summary><strong>🐳 Docker Management Commands</strong></summary>
+
 ```bash
-# Classic Streamlit UI (all platforms)
-deepcode --classic
+./deepcode_docker/run_docker.sh stop      # Stop
+./deepcode_docker/run_docker.sh restart   # Restart (no rebuild needed for config changes)
+./deepcode_docker/run_docker.sh --build   # Force rebuild
+./deepcode_docker/run_docker.sh logs      # Real-time logs
+./deepcode_docker/run_docker.sh status    # Health check
+./deepcode_docker/run_docker.sh clean     # Remove containers & images
 ```
-<div align="center">
-  <img src="https://img.shields.io/badge/Classic_UI-localhost:8501-00d4ff?style=flat-square&logo=streamlit&logoColor=white" alt="Classic UI" />
-</div>
 
-##### 🖥️ **CLI Interface** (Advanced Users)
+Or with Docker Compose directly:
 ```bash
-# Using UV
-uv run python cli/main_cli.py
-# Or using traditional Python
-python cli/main_cli.py
+docker compose -f deepcode_docker/docker-compose.yml up --build   # Build & start
+docker compose -f deepcode_docker/docker-compose.yml down         # Stop
+docker compose -f deepcode_docker/docker-compose.yml logs -f      # Logs
 ```
+
+> **💡** Config files are mounted as volumes — edit and restart, no rebuild needed.
+> **💡** Windows users: run `docker compose` commands directly if shell scripts aren't available.
+
+</details>
+
+### 🎯 **Step 4: Generate Code**
+
+1. **📄 Input** — Upload a research paper, type requirements, or paste a URL
+2. **🤖 Processing** — The multi-agent system analyzes, plans, and generates
+3. **⚡ Output** — Receive production-ready code with tests and documentation
+
+---
+
+### 🔧 **Troubleshooting**
+
+<details>
+<summary><strong>❓ Common Issues & Solutions</strong></summary>
+
+| Problem | Cause | Fix |
+|---|---|---|
+| Docker build fails with `tsc: not found` | Corrupted build cache | `docker builder prune -f` then rebuild with `--no-cache` |
+| `error during connect` / `cannot find the file` | Docker Desktop not running | Start Docker Desktop, wait until ready, retry |
+| Frontend blank page | Corrupted `node_modules` | `cd new_ui/frontend && rm -rf node_modules && npm install` |
+| `ERR_CONNECTION_REFUSED` | Wrong port / backend not running | Docker: `http://localhost:8000`. Local: `http://localhost:5173` |
+| `npm install` → `Could not read package.json` | Wrong directory | Use `npm install --prefix new_ui/frontend` |
+| Windows: MCP servers not working | Need absolute paths | See [Windows MCP Configuration](#-step-2-configuration) above |
+
+</details>
+
+  ---
+
+## 🤖 nanobot Integration (Feishu Chatbot)
+
+> Chat with DeepCode from **Feishu** — powered by [nanobot](https://github.com/HKUDS/nanobot).
+
+<div align="center">
+
+```mermaid
+flowchart LR
+    subgraph Clients["💬 Chat Platforms"]
+        direction TB
+        F["<b>Feishu</b><br/>WebSocket"]
+        T["<b>Telegram</b><br/>Polling"]
+        D["<b>Discord</b><br/>Gateway"]
+    end
+
+    subgraph Gateway["🐈 nanobot Gateway"]
+        direction TB
+        A["Agent Loop<br/><i>LLM + Tool Calls</i>"]
+    end
+
+    subgraph Engine["🧠 DeepCode Engine"]
+        direction TB
+        P2C["Paper → Code"]
+        C2C["Chat → Code"]
+        TRK["Task Tracking"]
+    end
+
+    F & T & D <-->|"messages"| A
+    A -->|"HTTP API"| P2C & C2C & TRK
+    A -.->|"LLM API"| LLM["☁️ OpenRouter"]
+
+    style Clients fill:#1a1a2e,stroke:#00d9ff,color:#fff
+    style Gateway fill:#1a1a2e,stroke:#4ecdc4,color:#fff
+    style Engine fill:#1a1a2e,stroke:#ff6b6b,color:#fff
+    style LLM fill:#1a1a2e,stroke:#9b59b6,color:#fff
+```
+
+</div>
+
 <div align="center">
-  <img src="https://img.shields.io/badge/Mode-Interactive_Terminal-9b59b6?style=flat-square&logo=terminal&logoColor=white" alt="CLI Mode" />
+<table><tr>
+<td align="center"><a href="https://github.com/HKUDS/DeepCode"><img src="./assets/logo.png" alt="DeepCode" height="55"/></a></td>
+<td align="center"><h2>✦</h2></td>
+<td align="center"><a href="https://github.com/HKUDS/nanobot"><img src="./assets/nanobot.png" alt="nanobot" height="55"/></a></td>
+</tr></table>
 </div>
 
-### 🎯 **Step 3: Generate Code**
+Both services run inside the same **Docker Compose** network. Prerequisites: **Docker Desktop** + **OpenRouter API Key** ([get one](https://openrouter.ai/keys)) + **Feishu App**.
+
+---
 
-1. **📄 Input**: Upload your research paper, provide requirements, or paste a URL
-2. **🤖 Processing**: Watch the multi-agent system analyze and plan
-3. **⚡ Output**: Receive production-ready code with tests and documentation
+### Step 1 · Create a Feishu Bot
 
+<details open>
+<summary><b>Feishu / Lark</b> (Recommended — WebSocket, no public IP needed)</summary>
 
-  ---
+1. Go to [Feishu Open Platform](https://open.feishu.cn/app) → **Create Custom App**
+2. Enable **Bot** capability in App Features
+3. Add permissions: `im:message` · `im:message:send_as_bot`
+4. Event Subscription → select **Long Connection** → add `im.message.receive_v1`
+5. Note your **App ID** (`cli_xxx`) and **App Secret** → Publish the app
+
+> **Note**: Feishu requires an active WebSocket connection before you can save "Long Connection" mode. Start nanobot first (Step 3), then come back to configure Event Subscription.
+
+</details>
+
+### Step 2 · Configure
+
+```bash
+cp nanobot_config.json.example nanobot_config.json
+```
+
+Edit `nanobot_config.json` — fill in the 3 required fields:
+
+```jsonc
+{
+  "channels": {
+    "feishu": {
+      "enabled": true,
+      "appId": "cli_xxx",              // ← Feishu App ID
+      "appSecret": "xxx",              // ← Feishu App Secret
+      "allowFrom": []                  // [] = allow all users
+    }
+  },
+  "providers": {
+    "openrouter": {
+      "apiKey": "sk-or-v1-xxx"         // ← OpenRouter API Key
+    }
+  },
+  "agents": {
+    "defaults": {
+      "model": "anthropic/claude-sonnet-4-20250514"
+    }
+  }
+}
+```
+
+> **Model choice**: Any model on [openrouter.ai/models](https://openrouter.ai/models). Use `anthropic/claude-sonnet-4-20250514` for English, `minimax/minimax-m2.1` for Chinese.
+
+---
+
+### Step 3 · Launch
+
+Make sure `mcp_agent.secrets.yaml` has your DeepCode API keys (see [Configuration](#-step-2-configuration)), then:
+
+```bash
+./nanobot/run_nanobot.sh -d          # Start both DeepCode + nanobot in background
+```
+
+The script checks Docker, validates configs, builds images (first run only), and starts both containers.
+
+```
+✓ DeepCode API:  http://localhost:8000
+✓ Nanobot:       http://localhost:18790
+```
+
+Now open Feishu → find your bot → send a message!
+
+<details>
+<summary><b>Management Commands</b></summary>
+
+```bash
+./nanobot/run_nanobot.sh              # Start (foreground)
+./nanobot/run_nanobot.sh -d           # Start (background)
+./nanobot/run_nanobot.sh stop         # Stop all services
+./nanobot/run_nanobot.sh restart      # Restart (config changes take effect immediately)
+./nanobot/run_nanobot.sh --build      # Force rebuild Docker images
+./nanobot/run_nanobot.sh logs         # View real-time logs
+./nanobot/run_nanobot.sh status       # Health check
+./nanobot/run_nanobot.sh clean        # Remove containers & images
+```
+
+</details>
+
+<details>
+<summary><b>Troubleshooting</b></summary>
+
+| Problem | Fix |
+|---|---|
+| Feishu bot doesn't respond | Check logs (`./nanobot/run_nanobot.sh logs`), verify `appId`/`appSecret`, ensure app is published with Long Connection mode |
+| Can't connect to DeepCode | Verify `deepcode` container is healthy: `curl http://localhost:8000/health` |
+| Wrong language output | Switch model — `minimax-m2.1` defaults to Chinese, use Claude/GPT for English |
+| Config not taking effect | Just restart: `./nanobot/run_nanobot.sh restart` (no rebuild needed) |
+| Clear chat history | Send `/clear` in chat, or: `docker exec nanobot sh -c 'rm -rf /root/.nanobot/sessions/*.jsonl'` |
+
+</details>
+
+---
 
 ## 💡 Examples