EvoScientist

🔥 News

TODO

• [27 Sep 2025] ⛳ Our preprint is now live on [arXiv] — check it out for details.

Overview

TODO

📖 Contents

• 🤖 Supported Models
• ⛏️ Installation
• 🔑 API Key Configuration
• ⚡ Quick Start
  • CLI Inference
  • Script Inference
  • Web Interface
• 🔌 MCP Integration
• 📊 Evaluation
• 📝 Citation
• 📚 Acknowledgments
• 📦 EvoScientist Team
• 📜 License

🤖 Supported Models

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

You can also use any full model ID directly — the provider will be inferred automatically.

⛏️ Installation

Tip

Use uv for installation — it's faster and more reliable than pip.

For Development

# Create and activate a conda environment
conda create -n EvoSci python=3.11 -y
conda activate EvoSci

# Install in development (editable) mode
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:

TODO

🔄 Upgrade to the latest code base

git pull
uv pip install -e .

🔑 API Key Configuration

EvoScientist requires API keys for LLM inference and web search. You can configure them in three ways:

Option A: Interactive Setup Wizard (Recommended)

EvoSci onboard

The wizard guides you through selecting a provider, entering API keys, choosing a model, and configuring workspace settings. Keys are validated automatically.

Option B: Environment Variables (Global)

Set keys directly in your terminal session. Add these to your shell profile (~/.bashrc, ~/.zshrc, etc.) to persist across sessions:

export ANTHROPIC_API_KEY="your_anthropic_api_key_here"
export TAVILY_API_KEY="your_tavily_api_key_here"

# 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"

Option C: .env File (Project-level)

Create a .env file in the project root. This keeps keys scoped to the project and out of your shell history:

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

Warning

Never commit .env files containing real API keys to version control. The .env file is already included in .gitignore.

Key	Required	Description
ANTHROPIC_API_KEY	For Anthropic	Anthropic API key for Claude (console.anthropic.com)
GOOGLE_API_KEY	For Google	Google API key for Gemini models (aistudio.google.com)
OPENAI_API_KEY	For OpenAI	OpenAI API key for GPT models (platform.openai.com)
NVIDIA_API_KEY	For NVIDIA	NVIDIA API key for NIM models (build.nvidia.com)
TAVILY_API_KEY	Yes	Tavily API key for web search (app.tavily.com)

⚡ Quick Start

CLI Inference

You can perform inference directly from the command line using our CLI tool:

python -m EvoScientist 

or

EvoSci # or EvoScientist

Optional arguments:

--mode <mode>      Workspace mode: 'daemon' (persistent) or 'run' (isolated per-session)
-n, --name <name>  Name for the run directory (requires --mode run; duplicates get _1, _2, …)
--workdir <path>   Override workspace directory for this session
--use-cwd          Use current working directory as workspace
--thread-id <id>   Resume a conversation thread
--no-thinking      Disable thinking display
-p, --prompt <q>   Single-shot mode: execute query and exit

Configuration commands:

EvoSci onboard                # Interactive setup wizard
EvoSci onboard --skip-validation  # Skip API key validation
EvoSci config                 # List all configuration values
EvoSci config get <key>       # Get a single value
EvoSci config set <key> <val> # 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)
/thread	Show current thread ID and workspace path
/channel	Start iMessage channel (shares agent session)
/skills	List installed user skills
/install-skill <source>	Install a skill from local path or GitHub
/uninstall-skill <name>	Uninstall a user-installed skill
/mcp	List configured MCP servers and tool routing

Skill Installation Examples:

# Install from local path
/install-skill ./my-skill

# 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

iMessage Channel

EvoScientist can be controlled remotely via iMessage. The channel shares the same agent and conversation thread as the CLI — messages from your phone go through the same session.

# Enable during onboard
EvoSci onboard        # Step 7 configures iMessage

# Or enable manually
EvoSci config set imessage_enabled true
EvoSci config set imessage_allowed_senders "+1234567890"

The channel can also be started manually with /channel in the interactive CLI.

Features:

• Thinking content and todo lists are forwarded to iMessage as intermediate messages
• Media files (images, PDFs) are auto-sent when the agent writes (write_file) or reads (read_file) them — no extra commands needed

Runtime Directories

By default, the workspace root is the current working directory. Sub-directories are created automatically:

<cwd>/
  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	<workspace>/runs	Per-session run directories
EVOSCIENTIST_MEMORY_DIR	<workspace>/memory	Shared memory storage
EVOSCIENTIST_SKILLS_DIR	<workspace>/skills	User-installed skills

Script Inference

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

╭─────────────────────────────────────────────────── 🧑 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 servers. Supports stdio, http, streamable_http, sse, and websocket transports.

# 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.

📊 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 — A framework for building AI agents that can interact with various tools and environments.
• Deep Agents UI — A user interface for visualising and managing Deep Agents.

We thank the authors for their valuable contributions to the open-source community.

📦 EvoScientist Team

Xi Zhang†

Yougang Lyu

Dinos Papakostas

Ziheng Zhang

^† Project Leader

For any enquiries or collaboration opportunities, please contact: EvoScientist.ai@gmail.com

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.