feat: lite deep researcher implementation

Author: He Tao

.env.example

@@ -0,0 +1,8 @@
+# Application Settings
+DEBUG=True
+APP_ENV=development
+
+# Add other environment variables as needed
+TAVILY_API_KEY=tvly-xxx
+# JINA_API_KEY=jina_xxx # Optional, default is None
+

.github/workflows/lint.yml

@@ -0,0 +1,28 @@
+name: Lint Check
+
+on:
+  push:
+    branches: [ 'main' ]
+  pull_request:
+    branches: [ '*' ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Install the latest version of uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        version: "latest"
+
+    - name: Install dependencies
+      run: |
+        uv venv --python 3.12
+        uv pip install -e ".[dev]"
+
+    - name: Run linters
+      run: |
+        source .venv/bin/activate
+        make lint

.github/workflows/test.yml

@@ -0,0 +1,29 @@
+name: Test Cases Check
+
+on:
+  push:
+    branches: [ 'main' ]
+  pull_request:
+    branches: [ '*' ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Install the latest version of uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        version: "latest"
+
+    - name: Install dependencies
+      run: |
+        uv venv --python 3.12
+        uv pip install -e ".[dev]"
+        uv pip install -e ".[test]"
+
+    - name: Run test cases
+      run: |
+        source .venv/bin/activate
+        TAVILY_API_KEY=mock-key make test

.gitignore

@@ -0,0 +1,21 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.coverage
+agent_history.gif
+static/browser_history/*.gif
+
+# Virtual environments
+.venv
+
+# Environment variables
+.env
+
+# user conf
+conf.yaml
+
+.idea/

.python-version

@@ -0,0 +1 @@
+3.12

.vscode/launch.json

@@ -0,0 +1,38 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python: 当前文件",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "justMyCode": true
+        },
+        {
+            "name": "Python: main.py",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${workspaceFolder}/main.py",
+            "console": "integratedTerminal",
+            "justMyCode": false,
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}"
+            },
+            "args": [
+                "--debug", "--max_plan_iterations", "1", "--max_step_num", "3"
+            ]
+        },
+        {
+            "name": "Python: llm.py",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${workspaceFolder}/src/llms/llm.py",
+            "console": "integratedTerminal",
+            "justMyCode": true,
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}"
+            }
+        }
+    ]
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 lite-deep-researcher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,19 @@
+.PHONY: lint format install-dev serve test coverage
+
+install-dev:
+	uv pip install -e ".[dev]" && uv pip install -e ".[test]"
+
+format:
+	uv run black --preview .
+
+lint:
+	uv run black --check .
+
+serve:
+	uv run server.py
+
+test:
+	uv run pytest tests/
+
+coverage:
+	uv run pytest --cov=src tests/ --cov-report=term-missing

README.md

@@ -0,0 +1,141 @@
+# lite-deep-researcher
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> Come from Open Source, Back to Open Source
+
+lite-deep-researcher is a community-driven AI automation framework that builds upon the incredible work of the open source community. Our goal is to combine language models with specialized tools for tasks like web search, crawling, and Python code execution, while giving back to the community that made this possible.
+
+## Quick Start
+
+```bash
+# Clone the repository
+git clone https://github.com/hetaoBackend/lite-deep-researcher.git
+cd lite-deep-researcher
+
+# Install dependencies, uv will take care of the python interpreter and venv creation
+uv sync
+
+# Configure .env
+cp .env.example .env
+
+# Configure config.yaml
+cp config.yaml.example config.yaml
+
+# Run the project
+uv run main.py
+```
+
+## Development
+
+### Testing
+
+Run the test suite:
+
+```bash
+# Run all tests
+make test
+
+# Run specific test file
+pytest tests/integration/test_workflow.py
+
+# Run with coverage
+make coverage
+```
+
+### Code Quality
+
+```bash
+# Run linting
+make lint
+
+# Format code
+make format
+```
+
+## Architecture
+
+lite-deep-researcher implements a modular multi-agent system architecture designed for automated research and code analysis. The system is built on LangGraph, enabling a flexible state-based workflow where components communicate through a well-defined message passing system.
+
+![Architecture Diagram](./assets/architecture.png)
+
+The system employs a streamlined workflow with the following components:
+
+1. **Coordinator**: The entry point that manages the workflow lifecycle
+   - Initiates the research process based on user input
+   - Delegates tasks to the planner when appropriate
+   - Acts as the primary interface between the user and the system
+
+2. **Planner**: Strategic component for task decomposition and planning
+   - Analyzes research objectives and creates structured execution plans
+   - Determines if enough context is available or if more research is needed
+   - Manages the research flow and decides when to generate the final report
+
+3. **Research Team**: A collection of specialized agents that execute the plan:
+   - **Researcher**: Conducts web searches and information gathering using tools like Tavily and web crawling
+   - **Coder**: Handles code analysis, execution, and technical tasks using Python REPL and Bash tools
+   Each agent has access to specific tools optimized for their role and operates within the LangGraph framework
+
+4. **Reporter**: Final stage processor for research outputs
+   - Aggregates findings from the research team
+   - Processes and structures the collected information
+   - Generates comprehensive research reports
+
+## Examples
+
+The following examples demonstrate the capabilities of lite-deep-researcher:
+
+### Research Reports
+
+1. **What is MCP?** - A comprehensive analysis of the term "MCP" across multiple contexts
+   - Explores Model Context Protocol in AI, Monocalcium Phosphate in chemistry, and Micro-channel Plate in electronics
+   - [View full report](examples/what_is_mcp.md)
+
+2. **Bitcoin Price Fluctuations** - Analysis of recent Bitcoin price movements
+   - Examines market trends, regulatory influences, and technical indicators
+   - Provides recommendations based on historical data
+   - [View full report](examples/bitcoin_price_fluctuation.md)
+
+3. **What is LLM?** - An in-depth exploration of Large Language Models
+   - Discusses architecture, training, applications, and ethical considerations
+   - [View full report](examples/what_is_llm.md)
+
+To run these examples or create your own research reports, you can use the following commands:
+
+```bash
+# Run with a specific query
+uv run main.py "What factors are influencing AI adoption in healthcare?"
+
+# Run with custom planning parameters
+uv run main.py --max_plan_iterations 3 "How does quantum computing impact cryptography?"
+
+# Or run interactively
+uv run main.py
+
+# View all available options
+uv run main.py --help
+```
+
+### Command Line Arguments
+
+The application supports several command-line arguments to customize its behavior:
+
+- **query**: The research query to process (can be multiple words)
+- **--max_plan_iterations**: Maximum number of planning cycles (default: 1)
+- **--max_step_num**: Maximum number of steps in a research plan (default: 3)
+- **--debug**: Enable detailed debug logging
+
+## License
+
+This project is open source and available under the [MIT License](LICENSE).
+
+## Acknowledgments
+
+Special thanks to all the open source projects and contributors that make lite-deep-researcher possible. We stand on the shoulders of giants.
+
+In particular, we want to express our deep appreciation for:
+- [LangChain](https://github.com/langchain-ai/langchain) for their exceptional framework that powers our LLM interactions and chains
+- [LangGraph](https://github.com/langchain-ai/langgraph) for enabling our sophisticated multi-agent orchestration
+
+These amazing projects form the foundation of lite-deep-researcher and demonstrate the power of open source collaboration.