diff --git a/.env.example b/.env.example index 927ff2d..834887c 100644 --- a/.env.example +++ b/.env.example @@ -1,8 +1,10 @@ -# API Keys for Deep Research Agent Example -# Copy this file to .env and fill in your actual API keys +# EvoScientist — cp .env.example .env && fill in your keys -# Anthropic API Key (for Claude Sonnet 4) -ANTHROPIC_API_KEY=your_anthropic_api_key_here +# LLM provider (pick at least one) +ANTHROPIC_API_KEY= # console.anthropic.com +OPENAI_API_KEY= # platform.openai.com +GOOGLE_API_KEY= # aistudio.google.com/api-keys +NVIDIA_API_KEY= # build.nvidia.com -# Tavily API Key (for web search) -TAVILY_API_KEY=your_tavily_api_key_here \ No newline at end of file +# Web search (optional) +TAVILY_API_KEY= # app.tavily.com diff --git a/.github/assets/EvoScientist_cli_help.png b/.github/assets/EvoScientist_cli_help.png index 1d9c1d2..48d0a95 100644 Binary files a/.github/assets/EvoScientist_cli_help.png and b/.github/assets/EvoScientist_cli_help.png differ diff --git a/.github/assets/EvoScientist_team.png b/.github/assets/EvoScientist_team.png new file mode 100644 index 0000000..cbd7ac4 Binary files /dev/null and b/.github/assets/EvoScientist_team.png differ diff --git a/README.md b/README.md index 2e29079..98adf78 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,3 @@ -
@@ -27,246 +26,216 @@
+--- +
-Typing SVG +Typing SVG
+
+ +**English | [简体中文](./README.zh-CN.md)** + +
+ +***EvoScientist aims to harness vibe research by enabling self-evolving AI scientists that autonomously explore, generate insights, and iteratively improve. +It is designed to be opinionated and ready to use out of the box, offering a living research system that grows alongside evolving agent skills, toolsets, and memory bases. +Going beyond traditional human-in-the-loop systems, EvoScientist introduces an AI-in-human’s-loop paradigm, where AI acts as a research buddy that co-evolves with human researchers and internalises scholarly taste and scientific judgement.*** + +

Unified Control, Different Surfaces

+[TODO: Add a Demo to demonstrate the different interfaces (TUI, mobile) and how they connect to the same underlying proxy system.] + + +## ✨ Features +> [!NOTE] +> - **🤖 Multi-Agent Team** — 6 sub-agents (plan, research, code, debug, analyze, write) working in concert. +> - **🧠 Persistent Memory** — Context, preferences, and findings survive across sessions. +> - **🔬 Scientific Workflow** — Intake → plan → execute → evaluate → write → verify. +> - **🌐 Multi-Provider** — Anthropic, OpenAI, Google, NVIDIA — one config to switch. +> - **📱 Multi-Channel** — CLI as the hub; Telegram, Discord, Slack, Feishu, WeChat, and more feed into one agent session. +> - **🔌 MCP & Skills** — Plug in MCP servers or install skills from GitHub on the fly. ## 🔥 News -> TODO -- **[27 Sep 2025]** ⛳ Our preprint is now live on [arXiv] — check it out for details. +- **[27 Feb 2026]** ⛳ EvoScientist officially debuts! -## Overview -> TODO +## 📖 Table of Contents -## 📖 Contents -- [🤖 Supported Models](#-supported-models) -- [⛏️ Installation](#️-installation) -- [🔑 API Key Configuration](#-api-key-configuration) +- [📦 Installation](#-installation) +- [🔑 Configuration](#-configuration) - [⚡ Quick Start](#-quick-start) - - [CLI Inference](#cli-inference) - - [Script Inference](#script-inference) - - [Web Interface](#web-interface) -- [💬 Channels](#-channels) - [🔌 MCP Integration](#-mcp-integration) -- [📊 Evaluation](#-evaluation) -- [📝 Citation](#-citation) +- [📱 Channels](#-channels) - [📚 Acknowledgments](#-acknowledgments) -- [📦 EvoScientist Team](#-evoscientist-team) -- [📜 License](#-license) +- [🏛️ EvoScientist Team](#-evoscientist-team) +- [🤝 Contributing](#-contributing) -## 🤖 Supported Models +## 📦 Installation -| Provider | Short Name | Model ID | -|----------|-----------|----------| -| Anthropic | `claude-opus-4-6` | `claude-opus-4-6` | -| Anthropic | `claude-opus-4-5` | `claude-opus-4-5-20251101` | -| Anthropic | `claude-sonnet-4-5` | `claude-sonnet-4-5-20250929` | -| Anthropic | `claude-haiku-4-5` | `claude-haiku-4-5-20251001` | -| OpenAI | `gpt-4o` | `gpt-4o` | -| OpenAI | `gpt-4o-mini` | `gpt-4o-mini` | -| OpenAI | `o1` | `o1` | -| OpenAI | `o1-mini` | `o1-mini` | -| Google | `gemini-3-pro` | `gemini-3-pro-preview` | -| Google | `gemini-3-flash` | `gemini-3-flash-preview` | -| Google | `gemini-2.5-pro` | `gemini-2.5-pro` | -| Google | `gemini-2.5-flash` | `gemini-2.5-flash` | -| Google | `gemini-2.5-flash-lite` | `gemini-2.5-flash-lite` | -| NVIDIA | `glm4.7` | `z-ai/glm4.7` | -| NVIDIA | `deepseek-v3.1` | `deepseek-ai/deepseek-v3.1-terminus` | -| NVIDIA | `nemotron-nano` | `nvidia/nemotron-3-nano-30b-a3b` | +> [!NOTE] +> Requires **Python 3.11+**. A virtual environment is recommended. -You can also use any full model ID directly — the provider will be inferred automatically. +### Quick Install -## ⛏️ Installation - -> [!TIP] -> Use [`uv`](https://pypi.org/project/uv) for installation — it's faster and more reliable than `pip`. -### For Development - -```Shell -# Create and activate a conda environment -conda create -n EvoSci python=3.11 -y -conda activate EvoSci - -# Install in development (editable) mode +```bash pip install EvoScientist -# or -pip install -e . ``` -### Option 1: -Install the latest version directly from GitHub for quick setup: -> TODO -### Option 2: -If you plan to modify the code or contribute to the project, you can clone the repository and install it in editable mode: +### Development Install -> TODO +```bash +git clone https://github.com/EvoScientist/EvoScientist.git +cd EvoScientist +pip install -e ".[dev]" +```
- 🔄 Upgrade to the latest code base +Using conda -```Shell -git pull -uv pip install -e . +```bash +conda create -n EvoSci python=3.11 -y +conda activate EvoSci +pip install -e ".[dev]" ```
-## 🔑 API Key Configuration +
+Upgrade to latest -EvoScientist requires API keys for LLM inference and web search. You can configure them in three ways: +```bash +git pull && pip install -e ".[dev]" +``` -### Option A: Interactive Setup Wizard (Recommended) +
-```Shell +## 🔑 Configuration + +The easiest way to configure API keys is the interactive wizard: + +```bash EvoSci onboard ``` -The wizard guides you through selecting a provider, entering API keys, choosing a model, and configuring workspace settings. Keys are validated automatically. +It walks you through provider selection, key validation, model choice, and workspace setup. -### Option B: Environment Variables (Global) +
+Manual configuration via environment variables -Set keys directly in your terminal session. Add these to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) to persist across sessions: +Set at least one LLM provider key and (optionally) a search key: -```Shell -export ANTHROPIC_API_KEY="your_anthropic_api_key_here" -export TAVILY_API_KEY="your_tavily_api_key_here" +```bash +# Pick one LLM provider +export ANTHROPIC_API_KEY="sk-..." # Claude — console.anthropic.com +export OPENAI_API_KEY="sk-..." # GPT — platform.openai.com +export GOOGLE_API_KEY="AI..." # Gemini — aistudio.google.com/api-keys +export NVIDIA_API_KEY="nvapi-..." # NIM — build.nvidia.com -# Optional: OpenAI, Google, or NVIDIA provider -export OPENAI_API_KEY="your_openai_api_key_here" -export GOOGLE_API_KEY="your_google_api_key_here" -export NVIDIA_API_KEY="your_nvidia_api_key_here" +# Web search (optional) +export TAVILY_API_KEY="tvly-..." # app.tavily.com ``` -### Option C: `.env` File (Project-level) +Or use `EvoSci config set` to persist keys in `~/.config/evoscientist/config.yaml`. -Create a `.env` file in the project root. This keeps keys scoped to the project and out of your shell history: +Alternatively, copy the example `.env` file for project-level configuration: -```Shell -cp .env.example .env -``` - -Then edit `.env` and fill in your keys: - -``` -ANTHROPIC_API_KEY=your_anthropic_api_key_here -TAVILY_API_KEY=your_tavily_api_key_here +```bash +cp .env.example .env # then fill in your keys ``` > [!WARNING] -> Never commit `.env` files containing real API keys to version control. The `.env` file is already included in `.gitignore`. +> Never commit `.env` files with real keys. It is already in `.gitignore`. -| Key | Required | Description | -|-----|----------|-------------| -| `ANTHROPIC_API_KEY` | For Anthropic | Anthropic API key for Claude ([console.anthropic.com](https://console.anthropic.com/)) | -| `GOOGLE_API_KEY` | For Google | Google API key for Gemini models ([aistudio.google.com](https://aistudio.google.com/api-keys)) | -| `OPENAI_API_KEY` | For OpenAI | OpenAI API key for GPT models ([platform.openai.com](https://platform.openai.com/)) | -| `NVIDIA_API_KEY` | For NVIDIA | NVIDIA API key for NIM models ([build.nvidia.com](https://build.nvidia.com/)) | -| `TAVILY_API_KEY` | Yes | Tavily API key for web search ([app.tavily.com](https://app.tavily.com/)) | +
## ⚡ Quick Start -### CLI Inference -You can perform inference directly from the command line using our CLI tool: +```bash +EvoSci # or EvoScientist — interactive mode +``` ![demo](.github/assets/EvoScientist_cli.png) -```Shell -python -m EvoScientist -``` -or -```Shell -EvoSci # or EvoScientist -``` -**Optional arguments:** +> Run `EvoSci -h` for all CLI options. +![cli help](.github/assets/EvoScientist_cli_help.png) + +
+Common examples + +```bash +EvoSci -p "your question" # single-shot mode +EvoSci -m run # isolated per-session workspace +EvoSci --ui textual # alternative TUI backend +EvoSci serve # headless mode — channels only, no interactive prompt ``` ---mode Workspace mode: 'daemon' (persistent) or 'run' (isolated per-session) --n, --name Name for the run directory (requires --mode run; duplicates get _1, _2, …) ---workdir Override workspace directory for this session ---use-cwd Use current working directory as workspace ---thread-id Resume a conversation thread ---no-thinking Disable thinking display ---ui UI backend: rich (default) or textual (beta) --p, --prompt Single-shot mode: execute query and exit + +
+ +
+In-session commands + +| Command | Description | +| ------- | ----------- | +| `/new` | Start a new session | +| `/current` | Show thread ID and workspace path | +| `/channel` | Start a messaging channel | +| `/skills` | List installed skills | +| `/install-skill ` | Install skill from path or GitHub | +| `/mcp` | List MCP servers and tool routing | +| `/exit` | Quit | + +
+ +
+Script Inference + +```python +from EvoScientist import EvoScientist_agent +from langchain_core.messages import HumanMessage +from EvoScientist.utils import format_messages + +thread = {"configurable": {"thread_id": "1"}} +last_len = 0 + +for state in EvoScientist_agent.stream( + {"messages": [HumanMessage(content="Hi?")]}, + config=thread, + stream_mode="values", +): + msgs = state["messages"] + if len(msgs) > last_len: + format_messages(msgs[last_len:]) + last_len = len(msgs) +``` + +
+ +## 🔌 MCP Integration + +Add external tools via [MCP](https://modelcontextprotocol.io/) servers with a single command: + +```bash +# Usage +EvoSci mcp add [-- args...] + +# Example +EvoSci mcp add sequential-thinking npx -- -y @modelcontextprotocol/server-sequential-thinking ``` > [!NOTE] -> In `--ui textual` mode, the built-in TUI commands are: -> `/help`, `/current`, `/new`, `/clear`, `/threads`, `/resume `, `/delete `, `/exit`. +> For command options, config fields, tool routing, wildcard filtering, and troubleshooting, see the **[MCP Integration Guide](./EvoScientist/mcp)**. -![demo](.github/assets/EvoScientist_cli_help.png) +## 📱 Channels -**Configuration commands:** - -```Shell -EvoSci onboard # Interactive setup wizard -EvoSci onboard --skip-validation # Skip API key validation -EvoSci config # List all configuration values -EvoSci config get # Get a single value -EvoSci config set # Set a single value -EvoSci config reset --yes # Reset to defaults -EvoSci config path # Show config file path -``` - -**Interactive Commands:** - -| Command | Description | -|---------|-------------| -| `/exit` | Quit the session | -| `/new` | Start a new session (new workspace + thread) | -| `/current` | Show current thread ID and workspace path | -| `/channel` | Start iMessage channel (shares agent session) | -| `/skills` | List installed user skills | -| `/install-skill ` | Install a skill from local path or GitHub | -| `/uninstall-skill ` | Uninstall a user-installed skill | -| `/mcp` | List configured MCP servers and tool routing | - -**Skill Installation Examples:** +Connect messaging platforms so they share the same agent session as the CLI: ```bash -# Install from local path -/install-skill ./my-skill +# Usage +EvoSci channel setup -# Install from GitHub URL -/install-skill https://github.com/owner/repo/tree/main/skill-name - -# Install from GitHub shorthand -/install-skill owner/repo@skill-name -``` - -### Channels - -EvoScientist integrates with 10 messaging platforms, allowing you to control the agent remotely from any chat app. All channels share the same agent core — messages from any platform go through the same processing pipeline. - -| Channel | Transport | Public IP Required | Install Extra | -|:--------|:----------|:------------------:|:--------------| -| Telegram | Long Polling | No | `pip install evoscientist[telegram]` | -| Discord | WebSocket | No | `pip install evoscientist[discord]` | -| Slack | Socket Mode | No | `pip install evoscientist[slack]` | -| Feishu / Lark | HTTP Webhook | Yes | `pip install evoscientist[feishu]` | -| WeChat (WeCom / MP) | HTTP Webhook | Yes | `pip install evoscientist[wechat]` | -| DingTalk | WebSocket Stream | No | `pip install evoscientist[dingtalk]` | -| QQ | WebSocket | No | `pip install evoscientist[qq]` | -| Signal | JSON-RPC | No | `pip install evoscientist[signal]` | -| Email | IMAP + SMTP | No | `pip install evoscientist[email]` | -| iMessage | JSON-RPC (stdio) | No | macOS only, requires [imsg](https://github.com/anthropics/imsg) CLI | - -**Quick start:** - -```bash -# 1. Install channel dependencies -pip install evoscientist[telegram] # or discord, slack, feishu, etc. - -# 2. Configure via wizard or CLI -EvoSci onboard # interactive setup -# or -EvoSci config set channel_enabled telegram -EvoSci config set telegram_bot_token "123456:ABC-xxx" - -# 3. Start -EvoSci serve # agent + all enabled channels +# Example +EvoSci channel setup telegram ``` Multiple channels can run concurrently — comma-separate names in the config: @@ -280,114 +249,18 @@ The channel can also be started interactively with `/channel` in the CLI session > [!NOTE] > For per-channel setup guides, capability matrix, architecture details, and troubleshooting, see the **[Channel Integration Guide](./EvoScientist/channels)**. -### Runtime Directories - -By default, the **workspace root** is the current working directory. Sub-directories -are created automatically: - -``` -/ - memory/ # shared MEMORY.md (persistent across sessions) - skills/ # user-installed skills - runs/ # per-session workspaces (run mode only) -``` - -Use `--workdir` to set a different workspace root, or configure it via -`EvoSci config set default_workdir /path/to/workspace`. - -Override individual paths via environment variables: - -| Variable | Default | Description | -|----------|---------|-------------| -| `EVOSCIENTIST_WORKSPACE_DIR` | current directory | Root workspace directory | -| `EVOSCIENTIST_RUNS_DIR` | `/runs` | Per-session run directories | -| `EVOSCIENTIST_MEMORY_DIR` | `/memory` | Shared memory storage | -| `EVOSCIENTIST_SKILLS_DIR` | `/skills` | User-installed skills | - -### Script Inference -```python -from EvoScientist import EvoScientist_agent -from langchain_core.messages import HumanMessage -from EvoScientist.utils import format_messages - -thread = {"configurable": {"thread_id": "1"}} -question = "Hi?" -last_len = 0 - -for state in EvoScientist_agent.stream( - {"messages": [HumanMessage(content=question)]}, - config=thread, - stream_mode="values", -): - msgs = state["messages"] - if len(msgs) > last_len: - format_messages(msgs[last_len:]) - last_len = len(msgs) -``` - -
- Output - -```json - -╭─────────────────────────────────────────────────── 🧑 Human ────────────────────────────────────────────────────╮ -│ Hi? │ -╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ -╭───────────────────────────────────────────────────── 📝 AI ─────────────────────────────────────────────────────╮ -│ Hi! I'm here to help you with experimental research tasks. I can assist with: │ -│ │ -│ - **Planning experiments** - designing stages, success criteria, and workflows │ -│ - **Running experiments** - implementing baselines, training models, analyzing results │ -│ - **Research** - finding papers, methods, datasets, and baselines │ -│ - **Analysis** - computing metrics, creating visualizations, interpreting results │ -│ - **Writing** - drafting experimental reports and documentation │ -│ │ -│ What would you like to work on today? │ -╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ -``` - -
- -### Web Interface - -> TODO - - -## 🔌 MCP Integration - -EvoScientist connects to external systems via [MCP](https://modelcontextprotocol.io/) servers. Supports `stdio`, `http`, `streamable_http`, `sse`, and `websocket` transports. - -```bash -# Add a server from the terminal -EvoSci mcp add sequential-thinking npx -- -y @modelcontextprotocol/server-sequential-thinking - -# Or from inside an agent session -/mcp add sequential-thinking npx -- -y @modelcontextprotocol/server-sequential-thinking -``` - -> [!NOTE] -> For command options, config fields, tool routing, wildcard filtering, and troubleshooting, see the **[MCP Integration Guide](./EvoScientist/mcp)**. - -## 📊 Evaluation - -> TODO - -## 📝 Citation - -If you find our paper and code useful in your research and applications, please cite using this BibTeX: - -> TODO - ## 📚 Acknowledgments This project builds upon the following outstanding open-source works: -- [**Deep Agents**](https://github.com/langchain-ai/deepagents) — A framework for building AI agents that can interact with various tools and environments. -- [**Deep Agents UI**](https://github.com/langchain-ai/deep-agents-ui) — A user interface for visualising and managing Deep Agents. +- [**LangChain**](https://github.com/langchain-ai/langchain) — A framework for building agents and LLM-powered applications. +- [**DeepAgents**](https://github.com/langchain-ai/deepagents) — The batteries-included agent harness. We thank the authors for their valuable contributions to the open-source community. -## 📦 EvoScientist Team +

🔝Back to top

+ +## 🏛️ EvoScientist Team @@ -407,7 +280,7 @@ We thank the authors for their valuable contributions to the open-source communi width="100" height="100" style="object-fit: cover; border-radius: 20%;" alt="Yougang Lyu"/>
- Yougang Lyu + Yougang Lyu§
@@ -416,7 +289,7 @@ We thank the authors for their valuable contributions to the open-source communi width="100" height="100" style="object-fit: cover; border-radius: 20%;" alt="Dinos Papakostas"/>
- Dinos Papakostas + Dinos Papakostas‡ 		@@ -425,17 +298,43 @@ We thank the authors for their valuable contributions to the open-source communi width="100" height="100" style="object-fit: cover; border-radius: 20%;" alt="Ziheng Zhang"/>
- Ziheng Zhang + Ziheng Zhang‡
-† Project Leader +> † Project Leader § Research Contributor ‡ Core Developer For any enquiries or collaboration opportunities, please contact: [**EvoScientist.ai@gmail.com**](mailto:evoscientist.ai@gmail.com) +

🔝Back to top

+ +## 🤝 Contributing + +EvoScientist Logo + +We welcome contributions from developers and researchers at all levels. Please refer to our [Contributing Guidelines](./CONTRIBUTING.md) to get started and help make EvoScientist more accessible. + +### ❤️ Thanks go to these awesome contributors: + +[![EvoScientist contributors](https://contrib.rocks/image?repo=EvoScientist/EvoScientist)](https://github.com/EvoScientist/EvoScientist/graphs/contributors) + +### 📈 Star History + +[![Star History Chart](https://api.star-history.com/svg?repos=EvoScientist/EvoScientist&type=date&legend=top-left)](https://www.star-history.com/#EvoScientist/EvoScientist&type=date&legend=top-left) + +

🔝Back to top

+ ## 📜 License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details. + +

🔝Back to top

+ +--- + +

+ Made with ❤️ by the EvoScientist team and the open source community for the AI scientist community. +

\ No newline at end of file diff --git a/langgraph.json b/langgraph.json deleted file mode 100644 index 76a5a92..0000000 --- a/langgraph.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "dependencies": ["."], - "graphs": { - "EvoScientist": "./langgraph_dev.py:EvoScientist_agent" - }, - "env": ".env", - "config": { - "recursion_limit": 500 - } -} \ No newline at end of file diff --git a/langgraph_dev.py b/langgraph_dev.py deleted file mode 100644 index d07fb3c..0000000 --- a/langgraph_dev.py +++ /dev/null @@ -1,7 +0,0 @@ -"""Entry point for ``langgraph dev``. - -langgraph.json references ``./langgraph_dev.py:EvoScientist_agent``. -Actual construction lives in ``EvoScientist/EvoScientist.py``. -""" - -from EvoScientist.EvoScientist import EvoScientist_agent, create_cli_agent # noqa: F401