Metadata-Version: 2.4
Name: EvoScientist
Version: 0.0.1b2
Summary: EvoScientist: Towards Self-Evolving AI Scientists for End-to-End Scientific Discovery
Author: Xi Zhang
Maintainer: Xi Zhang
License-Expression: MIT
Project-URL: Homepage, https://github.com/EvoScientist/EvoScientist
Project-URL: Bug Tracker, https://github.com/EvoScientist/EvoScientist/issues
Project-URL: Documentation, https://github.com/EvoScientist/EvoScientist#readme
Keywords: ai-scientific,scientific-discovery,self-evolving,ai-scientists,end-to-end
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: deepagents>=0.4.4
Requires-Dist: langchain>=1.2.10
Requires-Dist: langchain-anthropic>=1.3.3
Requires-Dist: langchain-openai>=0.3
Requires-Dist: langchain-nvidia-ai-endpoints>=0.3
Requires-Dist: langchain-google-genai>=4.2
Requires-Dist: langchain-ollama>=1.0
Requires-Dist: tavily-python>=0.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=14.0
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: questionary>=2.0.1
Requires-Dist: typer>=0.12
Requires-Dist: python-dotenv>=1.0
Requires-Dist: langgraph-cli[inmem]>=0.4
Requires-Dist: langgraph-checkpoint-sqlite>=3.0.0
Requires-Dist: httpx>=0.27
Requires-Dist: markdownify>=0.14
Requires-Dist: nest-asyncio>=1.6
Requires-Dist: langchain-mcp-adapters>=0.1
Requires-Dist: textual>=0.80
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=21.0; extra == "telegram"
Provides-Extra: discord
Requires-Dist: discord.py>=2.3; extra == "discord"
Provides-Extra: slack
Requires-Dist: slack-sdk>=3.27; extra == "slack"
Requires-Dist: aiohttp>=3.9; extra == "slack"
Provides-Extra: wechat
Requires-Dist: pycryptodome>=3.20; extra == "wechat"
Provides-Extra: qq
Requires-Dist: qq-botpy>=1.0; extra == "qq"
Provides-Extra: all-channels
Requires-Dist: python-telegram-bot>=21.0; extra == "all-channels"
Requires-Dist: discord.py>=2.3; extra == "all-channels"
Requires-Dist: aiohttp>=3.9; extra == "all-channels"
Requires-Dist: slack-sdk>=3.27; extra == "all-channels"
Requires-Dist: pycryptodome>=3.20; extra == "all-channels"
Requires-Dist: qq-botpy>=1.0; extra == "all-channels"
Dynamic: license-file

<div align="center">
    <picture>
      <source media="(prefers-color-scheme: light)" srcset=".github/assets/logo-dark.svg">
      <source media="(prefers-color-scheme: dark)" srcset=".github/assets/logo-light.svg">
      <img alt="EvoScientist Logo" src=".github/assets/logo-dark.svg" width="80%">
    </picture>
</div>

<div align="center">
<a href="https://pypi.org/project/EvoScientist/"><picture>
  <source media="(prefers-color-scheme: light)" srcset=".github/assets/badge-pypi-light.svg">
  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/badge-pypi-dark.svg">
  <img alt="PyPI v0.0.1" src=".github/assets/badge-pypi-light.svg" height="28">
</picture></a><a href="https://evoscientist.ai/"><picture>
  <source media="(prefers-color-scheme: light)" srcset=".github/assets/badge-website-light.svg">
  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/badge-website-dark.svg">
  <img alt="Website" src=".github/assets/badge-website-light.svg" height="28">
</picture></a><a href="https://github.com/langchain-ai/deepagents"><picture>
  <source media="(prefers-color-scheme: light)" srcset=".github/assets/badge-framework-light.svg">
  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/badge-framework-dark.svg">
  <img alt="Framework DeepAgents" src=".github/assets/badge-framework-light.svg" height="28">
</picture></a><a href="https://github.com/EvoScientist/EvoScientist/blob/main/LICENSE"><picture>
  <source media="(prefers-color-scheme: light)" srcset=".github/assets/badge-license-light.svg">
  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/badge-license-dark.svg">
  <img alt="License MIT" src=".github/assets/badge-license-light.svg" height="28">
</picture></a>
</div>

---

<div align="center">
<a href="https://github.com/EvoScientist/EvoScientist"><img src="https://readme-typing-svg.demolab.com?font=Sans-Serif&pause=1000&color=64B5F6&center=true&vCenter=true&width=435&lines=Towards+Self-Evolving+AI+Scientists;Harness+Vibe+Research" alt="Typing SVG" /></a>
</div>

<div align="center">

**English | [简体中文](./README.zh-CN.md)**

</div>

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

<!-- <h3>Unified Control, Different Surfaces</h3>
[TODO: Add a Demo to demonstrate the different interfaces (TUI, mobile) and how they connect to the same underlying proxy system.] -->
<!-- <a href="https://github.com/EvoScientist/EvoScientist">
<img width="100%" src="https://github.com/EvoScientist/EvoScientist/tree/main/.github/assets/EvoScientist_demo.gif?raw=true"></a> -->

## ✨ Features
- **🤖 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 — one agent session.
- **🔌 MCP & Skills** — Plug in MCP servers or install skills from GitHub on the fly.

## 🎯 ᯓ➤ Roadmap
- [x] 🖥️ TUI powered by Rich and Textual
- [x] 📻 EvoMemory v1.0 shipped
- [x] ⚒️ 200+ predefined skills built in
- [ ] 📑 Technical report on the way
- [ ] 📺 Demo and tutorial in the works
- [ ] 📊 Benchmark suite to be released
- [ ] ⏰ Scheduled tasks for the core system planned
- [ ] 🧩 More built-in skills and integrations ahead

## 🔥 News
- **[27 Feb 2026]** ⛳ EvoScientist officially debuts!

## 📖 Table of Contents

- [📦 Installation](#-installation)
- [🔑 Configuration](#-configuration)
- [⚡ Quick Start](#-quick-start)
- [🔌 MCP Integration](#-mcp-integration)
- [📱 Channels](#-channels)
- [📚 Acknowledgments](#-acknowledgments)
- [🌍 Project Roles](#-project-roles)
- [🤝 Contributing](#-contributing)

## 📦 Installation

> [!TIP]
> Requires **Python 3.11+**. We recommend [**uv**](https://docs.astral.sh/uv/) or **conda** for dependency management and virtual environments.

<details>
<summary> 🪛 Install uv (if you don't have it)</summary>

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

</details>

### Quick Install

```bash
uv tool install EvoScientist
```

Or install into the current environment instead:

```bash
uv pip install EvoScientist
```

### Development Install

```bash
git clone https://github.com/EvoScientist/EvoScientist.git
cd EvoScientist
uv sync --dev
```

<details>
<summary> Using conda</summary>

```bash
conda create -n EvoSci python=3.11 -y
conda activate EvoSci
pip install -e ".[dev]"
```

</details>

<details>
<summary> Using PyPi</summary>

```bash
pip install EvoScientist          # quick install
pip install -e ".[dev]"           # development install
```

</details>

<details>
<summary> Optional: Channel dependencies</summary>

Messaging channel integrations require extra dependencies. Install only what you need:

```bash
uv pip install "EvoScientist[telegram]"     # Telegram
uv pip install "EvoScientist[discord]"      # Discord
uv pip install "EvoScientist[slack]"        # Slack
uv pip install "EvoScientist[wechat]"       # WeChat
uv pip install "EvoScientist[qq]"           # QQ
uv pip install "EvoScientist[all-channels]" # everything
```

</details>

<details>
<summary> Upgrade to the latest code base </summary>

```bash
git pull && uv sync --dev
```

</details>

<p align="right"><a href="#top">🔝Back to top</a></p>

## 🔑 Configuration

The easiest way to configure API keys is the interactive wizard:

```bash
EvoSci onboard
```

It walks you through provider selection, key validation, model choice, and workspace setup.

<details>
<summary> 📟 Manual configuration via environment variables </summary>

Set at least one LLM provider key and (optionally) a search key:

```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

# Web search (optional)
export TAVILY_API_KEY="tvly-..."    # app.tavily.com
```

Or use `EvoSci config set` to persist keys in `~/.config/evoscientist/config.yaml`.

Alternatively, copy the example `.env` file for project-level configuration:

```bash
cp .env.example .env  # then fill in your keys
```

> ⚠️ Never commit `.env` files with real keys. It is already in `.gitignore`.

</details>

<p align="right"><a href="#top">🔝Back to top</a></p>

## ⚡ Quick Start

```bash
EvoSci  # or EvoScientist — interactive mode
```

![demo](.github/assets/EvoScientist_cli.png)

> Run `EvoSci -h` for all CLI options.

![cli help](.github/assets/EvoScientist_cli_help.png)

<details>
<summary>Common examples</summary>

```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
```

</details>

<details>
<summary>In-session commands</summary>

| 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 <src>` | Install skill from path or GitHub |
| `/mcp` | List MCP servers and tool routing |
| `/exit` | Quit |

</details>

<details>
<summary>Script Inference</summary>

```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)
```

</details>

<p align="right"><a href="#top">🔝Back to top</a></p>

## 🔌 MCP Integration

Add external tools via [MCP](https://modelcontextprotocol.io/) servers with a single command:

```bash
# Usage
EvoSci mcp add <name> <command> [-- args...]

# Example
EvoSci mcp add sequential-thinking npx -- -y @modelcontextprotocol/server-sequential-thinking
```

> [!TIP]
> For command options, config fields, tool routing, wildcard filtering, and troubleshooting, see the **[MCP Integration Guide](https://github.com/EvoScientist/EvoScientist/tree/main/EvoScientist/mcp#model-context-protocol-integration)**.

<p align="right"><a href="#top">🔝Back to top</a></p>

## 📱 Channels

Connect messaging platforms so they share the same agent session as the CLI:

```bash
# Usage
EvoSci channel setup <channel>

# Example
EvoSci channel setup telegram
```

Multiple channels can run concurrently — comma-separate names in the config:

```yaml
channel_enabled: "telegram,discord,slack"
```

The channel can also be started interactively with `/channel` in the CLI session.

> [!TIP]
> For per-channel setup guides, capability matrix, architecture details, and troubleshooting, see the **[Channel Integration Guide](https://github.com/EvoScientist/EvoScientist/tree/main/EvoScientist/channels#channels)**.

<p align="right"><a href="#top">🔝Back to top</a></p>

## 📚 Acknowledgments

This project builds upon the following outstanding open-source works:

- [**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.

<p align="right"><a href="#top">🔝Back to top</a></p>

## 🌍 Project Roles

<table>
  <tbody>
    <tr>
      <td align="center">
        <a href="https://x-izhang.github.io/">
          <img src="https://x-izhang.github.io/author/xi-zhang/avatar_hu13660783057866068725.jpg"
               width="100" height="100"
               style="object-fit: cover; border-radius: 20%;" alt="Xi Zhang"/>
          <br />
          <sub><b>Xi Zhang</b><sup>†</sup></sub>
        </a>
      </td>
      <td align="center">
        <a href="https://muxincg2004.github.io/">
          <img src="https://muxincg2004.github.io/resume_avatar.jpg"
               width="100" height="100"
               style="object-fit: cover; border-radius: 20%;" alt="Ziheng Zhang"/>
          <br />
          <sub><b>Ziheng Zhang</b><sup>‡</sup></sub>
        </a>
      </td>
      <td align="center">
        <a href="https://din0s.me/">
          <img src="https://din0s.me/images/pk.jpg"
               width="100" height="100"
               style="object-fit: cover; border-radius: 20%;" alt="Dinos Papakostas"/>
          <br />
          <sub><b>Dinos Papakostas</b><sup>‡1</sup></sub>
        </a>
      </td>
      <td align="center">
        <a href="https://youganglyu.github.io/">
          <img src="https://youganglyu.github.io/images/profile.png"
               width="100" height="100"
               style="object-fit: cover; border-radius: 20%;" alt="Yougang Lyu"/>
          <br />
          <sub><b>Yougang Lyu</b><sup>§</sup></sub>
        </a>
      </td>
      <td align="center">
        <a href="https://xiaohuiyan.github.io/">
          <img src="https://xiaohuiyan.github.io/img/me.jpg"
               width="100" height="100"
               style="object-fit: cover; border-radius: 20%;" alt="Xiaohui Yan"/>
          <br />
          <sub><b>Xiaohui Yan</b><sup>§</sup></sub>
        </a>
      </td>
    </tr>
  </tbody>
</table>

#### Collaborators

Jan Piotrowski, Wiktor Cupiał, Yuyue Zhao, Xinhao Yi, Jakub Kaliski, Jakub Filipiuk, Shuyu Guo, Andreas Sauter, Jacopo Urbani, Zaiqiao Meng, Lun Zhou

> <sup>†</sup>Project Lead & Engineering Lead <sup>‡</sup>Core Developer <sup>§</sup>Project Correspondent

> *Xiaoyi DeepResearch Team* and the wider open-source community contribute to this project.

For any enquiries or collaboration opportunities, please contact: [**EvoScientist.ai@gmail.com**](mailto:evoscientist.ai@gmail.com)

<p align="right"><a href="#top">🔝Back to top</a></p>

## 🤝 Contributing

<img align="right" alt="EvoScientist Team" src=".github/assets/EvoScientist_team.png" width="20%" />

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)

<p align="right"><a href="#top">🔝Back to top</a></p>

## 📜 License

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

<p align="right"><a href="#top">🔝Back to top</a></p>

---

<p align="center">
  Initiated and led by <a href="https://github.com/x-izhang">Xi Zhang</a>, built with the open-source community.
</p>
