deepcode-hku 1.0.8__tar.gz → 1.1.0__tar.gz

{deepcode_hku-1.0.8/deepcode_hku.egg-info → deepcode_hku-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepcode-hku
-Version: 1.0.8
+Version: 1.1.0
 Summary: AI Research Engine - Transform research papers into working code automatically
 Home-page: https://github.com/HKUDS/DeepCode
 Author: DeepCodeTeam
@@ -24,15 +24,21 @@ Requires-Dist: aiohttp>=3.8.0
 Requires-Dist: anthropic
 Requires-Dist: asyncio-mqtt
 Requires-Dist: docling
+Requires-Dist: fastapi>=0.104.0
 Requires-Dist: google-genai
 Requires-Dist: mcp-agent
 Requires-Dist: mcp-server-git
 Requires-Dist: nest_asyncio
 Requires-Dist: openai
 Requires-Dist: pathlib2
+Requires-Dist: pydantic-settings>=2.0.0
 Requires-Dist: PyPDF2>=2.0.0
+Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: PyYAML>=6.0
 Requires-Dist: reportlab>=3.5.0
 Requires-Dist: streamlit
+Requires-Dist: uvicorn>=0.24.0
+Requires-Dist: websockets>=12.0
 Dynamic: author
 Dynamic: classifier
 Dynamic: description
@@ -81,8 +87,9 @@ Dynamic: summary
 </p> -->
 <p>
   <a href="https://github.com/HKUDS/DeepCode/stargazers"><img src='https://img.shields.io/github/stars/HKUDS/DeepCode?color=00d9ff&style=for-the-badge&logo=star&logoColor=white&labelColor=1a1a2e' /></a>
+  <a href='https://arxiv.org/abs/2512.07921'><img src="https://img.shields.io/badge/Paper-arXiv-orange?style=for-the-badge&logo=arxiv&logoColor=white&labelColor=1a1a2e"></a>
   <img src="https://img.shields.io/badge/🐍Python-3.13-4ecdc4?style=for-the-badge&logo=python&logoColor=white&labelColor=1a1a2e">
-  <a href="https://pypi.org/project/deepcode-hku/"><img src="https://img.shields.io/pypi/v/deepcode-hku.svg?style=for-the-badge&logo=pypi&logoColor=white&labelColor=1a1a2e&color=ff6b6b"></a>
+  <!-- <a href="https://pypi.org/project/deepcode-hku/"><img src="https://img.shields.io/pypi/v/deepcode-hku.svg?style=for-the-badge&logo=pypi&logoColor=white&labelColor=1a1a2e&color=ff6b6b"></a> -->
 </p>
 <p>
   <a href="https://discord.gg/yF2MmDJyGJ"><img src="https://img.shields.io/badge/💬Discord-Community-7289da?style=for-the-badge&logo=discord&logoColor=white&labelColor=1a1a2e"></a>
@@ -203,6 +210,22 @@ Dynamic: summary
 
 ## 📰 News
 
+🎨 **[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
+- 🚀 **One-Click Launch**: Simply run `deepcode` to start the new UI (cross-platform: Windows/macOS/Linux)
+- 🔧 **Improved Process Management**: Enhanced service start/stop mechanism with automatic port cleanup
+- 📡 **WebSocket Real-time Communication**: Fixed message loss issues, ensuring proper interaction state synchronization
+
+<div align="center">
+  <img src="./assets/NewUI.png" alt="DeepCode New UI" width="85%" style="border-radius: 12px; box-shadow: 0 4px 20px rgba(0,0,0,0.15);" />
+  <br/>
+  <sub><em>DeepCode New Web UI - Modern React-based Interface</em></sub>
+</div>
+
+---
+
 🎉 **[2025-10] 🎉 [2025-10-28] DeepCode Achieves SOTA on PaperBench!**
 
 DeepCode sets new benchmarks on OpenAI's PaperBench Code-Dev across all categories:
@@ -570,10 +593,44 @@ Implementation Generation • Testing • Documentation
 
 ## 🚀 Quick Start
 
+### 📋 **Prerequisites**
+
+Before installing DeepCode, ensure you have the following:
 
+| Requirement | Version | Purpose |
+|-------------|---------|---------|
+| **Python** | 3.9+ | Core runtime |
+| **Node.js** | 18+ | New UI frontend |
+| **npm** | 8+ | Package management |
+
+```bash
+# Check your versions
+python --version   # Should be 3.9+
+node --version     # Should be 18+
+npm --version      # Should be 8+
+```
+
+<details>
+<summary><strong>📥 Install Node.js (if not installed)</strong></summary>
+
+```bash
+# macOS (using Homebrew)
+brew install node
+
+# Ubuntu/Debian
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# Windows
+# Download from https://nodejs.org/
+```
+
+</details>
 
 ### 📦 **Step 1: Installation**
 
+Choose one of the following installation methods:
+
 #### ⚡ **Direct Installation (Recommended)**
 
 ```bash
@@ -583,29 +640,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)**
@@ -616,79 +650,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`:
 
@@ -716,7 +762,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`:
 
@@ -727,17 +776,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:
@@ -757,49 +799,196 @@ 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**
+
+#### 🐳 **Docker** (Recommended — Easiest Setup)
+
+No need to install Python, Node.js, or any dependencies — everything runs inside the container.
+
+**Prerequisites:** Install [Docker Desktop](https://www.docker.com/products/docker-desktop) (includes Docker Engine + Docker Compose).
+
+```bash
+# 1. Clone the repository (if not already done)
+git clone https://github.com/HKUDS/DeepCode.git
+cd DeepCode/
+
+# 2. Configure your API keys (see Step 2: Configuration above)
+cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml
+# Edit mcp_agent.secrets.yaml with your API keys
+
+# 3. Start with one command
+./deepcode_docker/run_docker.sh        # Build & start (auto-builds on first run)
 
-#### 🚀 **Using Installed Package (Recommended)**
+# Access at http://localhost:8000
+```
+
+**Management Commands:**
+```bash
+./deepcode_docker/run_docker.sh stop         # Stop the service
+./deepcode_docker/run_docker.sh restart      # Restart (after config changes, no rebuild needed)
+./deepcode_docker/run_docker.sh --build      # Rebuild (after code changes)
+./deepcode_docker/run_docker.sh logs         # View real-time logs
+./deepcode_docker/run_docker.sh status       # Check service status
+./deepcode_docker/run_docker.sh clean        # Remove containers and images
+```
 
+Or use Docker Compose directly:
 ```bash
-# 🌐 Launch web interface directly
+docker compose -f deepcode_docker/docker-compose.yml up --build   # Build and start
+docker compose -f deepcode_docker/docker-compose.yml up -d        # Start in background
+docker compose -f deepcode_docker/docker-compose.yml down         # Stop
+docker compose -f deepcode_docker/docker-compose.yml logs -f      # View logs
+```
+
+> **💡 Config changes don't need rebuild**: `mcp_agent.config.yaml` and `mcp_agent.secrets.yaml` are mounted as volumes — just edit them and run `./deepcode_docker/run_docker.sh restart`.
+>
+> **💡 Windows users**: Run `docker compose -f deepcode_docker/docker-compose.yml up --build` directly if the shell script is not available.
+
+#### 🚀 **Using `deepcode` Command** (Local Installation)
+
+```bash
+# 🌐 Launch the new React-based web interface
 deepcode
 
-# The application will automatically start at http://localhost:8501
+# Frontend: http://localhost:5173
+# Backend API: http://localhost:8000
+# Press Ctrl+C to stop all services
 ```
+<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)
 
-#### 🛠️ **Using Source Code**
+> **✨ Features**: User-in-Loop interaction, real-time progress tracking, inline chat interaction
 
-Choose your preferred interface:
+#### 🛠️ **Alternative Launch Methods**
+
+<table>
+<tr>
+<td><strong>🍎 macOS / 🐧 Linux</strong></td>
+<td><strong>🪟 Windows</strong></td>
+</tr>
+<tr>
+<td>
 
-##### 🌐 **Web Interface** (Recommended)
 ```bash
-# Using UV
-uv run streamlit run ui/streamlit_app.py
-# Or using traditional Python
-streamlit run ui/streamlit_app.py
+# Using run.sh
+./run.sh
+
+# Or using Python directly
+python deepcode.py
+```
+
+</td>
+<td>
+
+```cmd
+# Using run.bat
+run.bat
+
+# Or using Python directly
+python deepcode.py
+```
+
+</td>
+</tr>
+</table>
+
+```bash
+# Classic Streamlit UI (all platforms)
+deepcode --classic
 ```
 <div align="center">
-  <img src="https://img.shields.io/badge/Access-localhost:8501-00d4ff?style=flat-square&logo=streamlit&logoColor=white" alt="Web Access" />
+  <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)
 ```bash
-# Using UV
-uv run python cli/main_cli.py
-# Or using traditional Python
+# CLI via Docker (no local Python needed)
+./deepcode_docker/run_docker.sh cli
+
+# Or: deepcode --cli
+
+# CLI locally (requires Python environment)
 python cli/main_cli.py
 ```
 <div align="center">
   <img src="https://img.shields.io/badge/Mode-Interactive_Terminal-9b59b6?style=flat-square&logo=terminal&logoColor=white" alt="CLI Mode" />
 </div>
 
-### 🎯 **Step 3: Generate Code**
+### 🎯 **Step 4: Generate Code**
 
 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
 
+---
+
+### 🔧 **Troubleshooting**
+
+<details>
+<summary><strong>❓ Common Issues & Solutions</strong></summary>
+
+#### 🐳 Docker build fails with `tsc: not found`
+
+```
+node_modules/.bin/tsc: line 1: ../typescript/bin/tsc: not found
+```
+
+**Cause**: Corrupted Docker build cache.
+
+**Fix**: Clear the cache and rebuild:
+```bash
+docker builder prune -f
+docker compose -f deepcode_docker/docker-compose.yml build --no-cache
+docker compose -f deepcode_docker/docker-compose.yml up -d
+```
+
+#### 🐳 Docker command returns `error during connect` / `cannot find the file specified`
+
+**Cause**: Docker Desktop is not running.
+
+**Fix**: Start **Docker Desktop** from the Start menu (Windows) or Applications (macOS), wait until it's fully ready, then retry.
+
+#### 🌐 Frontend displays abnormally or shows a blank page
+
+**Cause**: Corrupted `node_modules` — frontend dependencies are incomplete.
+
+**Fix**: Reinstall frontend dependencies:
+```bash
+cd new_ui/frontend
+rm -rf node_modules
+npm install
+```
+
+Then rebuild (for Docker) or restart (for local mode).
+
+#### 🌐 Browser shows `ERR_CONNECTION_REFUSED` or JSON response instead of UI
+
+**Cause**: Accessing the wrong port or backend not running.
+
+**Fix**:
+- **Docker mode** (`deepcode`): Access **http://localhost:8000**. Make sure the container is running: `docker ps`
+- **Local mode** (`deepcode --local`): Access **http://localhost:5173** (not 8000). Port 5173 is the frontend dev server.
+
+#### 📦 `npm install` fails with `Could not read package.json`
+
+**Cause**: Running `npm install` in the project root instead of the frontend directory.
+
+**Fix**: Run it in the correct directory:
+```bash
+npm install --prefix new_ui/frontend
+```
+
+#### 🪟 Windows: MCP servers not working
+
+See the [Windows MCP Server Configuration](#-step-2-configuration) section above for setting up absolute paths.
+
+</details>
 
   ---
 
@@ -925,8 +1114,32 @@ We're continuously enhancing DeepCode with exciting new features:
 
 ---
 
+<div align="left">
+
+### 📖 **Citation**
+
+
+If you find DeepCode useful in your research or applications, please kindly cite:
+
+```
+@misc{li2025deepcodeopenagenticcoding,
+      title={DeepCode: Open Agentic Coding},
+      author={Zongwei Li and Zhonghang Li and Zirui Guo and Xubin Ren and Chao Huang},
+      year={2025},
+      eprint={2512.07921},
+      archivePrefix={arXiv},
+      primaryClass={cs.SE},
+      url={https://arxiv.org/abs/2512.07921},
+}
+```
+
+---
+
+
 ### 📄 **License**
 
+<div align="center">
+
 <img src="https://img.shields.io/badge/License-MIT-4ecdc4?style=for-the-badge&logo=opensourceinitiative&logoColor=white" alt="MIT License">
 
 **MIT License** - Copyright (c) 2025 Data Intelligence Lab, The University of Hong Kong
@@ -934,7 +1147,6 @@ We're continuously enhancing DeepCode with exciting new features:
 ---
 
 
-
 <img src="https://visitor-badge.laobi.icu/badge?page_id=deepcode.readme&style=for-the-badge&color=00d4ff" alt="Visitors">
 
 </div>