EvoScientist/README.md

EvoScientist

🔥 News

TODO

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

Overview

TODO

📖 Contents

• ⛏️ Installation
• ⚡ Quick Start
  • CLI Inference
  • Script Inference
  • Web Interface
• 📊 Evaluation
• 📝 Citation
• 📚 Acknowledgments
• 📦 Codebase Contributors
• 📜 License

⛏️ 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 .

⚡ Quick Start

CLI Inference

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

python -m EvoScientist

Optional arguments:

TODO

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

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

📦 Codebase Contributors

Yougang Lyu

Xi Zhang

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

📜 License

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