dinos
0303c6d43d
* feat(cli): add --version / -V flag Uses importlib.metadata to read the version from the installed package. * chore: improve bug report and feature request issue templates - Bug report: replace web-app steps with CLI-oriented examples, add error output section, add Python version and LLM provider fields - Feature request: add note directing niche features to EvoSkills, set default label * chore: add documentation issue template and issue chooser config - Add documentation template for reporting missing or unclear docs - Add config.yml to disable blank issues and link to EvoSkills and Discord as contact options * chore: add PR template and improve CONTRIBUTING.md - Add PR template with type-of-change checkboxes, issue linking for new features, and CI checklist - CONTRIBUTING.md: add development setup, PR workflow, and code style sections; fix wording; make Discord link clickable
112 lines
4.2 KiB
Markdown
112 lines
4.2 KiB
Markdown
# Contributing to EvoScientist
|
|
|
|
We appreciate your interest and the time you spend helping improve EvoScientist. Please read the following guidelines before contributing.
|
|
|
|
## How you can contribute
|
|
|
|
- **Report bugs and request features:** open an issue using the provided templates. Make sure to use the correct template and labels.
|
|
- **Propose design changes:** use issues or discussion threads to outline the problem, alternatives, and trade-offs before implementing.
|
|
- **Contribute code or docs:** submit PRs that address an open issue. They must have a clear rationale and tests where applicable.
|
|
|
|
## What we are looking for in PRs
|
|
|
|
We aim to keep EvoScientist focused on core functionality that benefits the majority of users. PRs should only include:
|
|
|
|
- Bug fixes / improvements to existing features
|
|
- New features that were proposed in an issue and agreed upon with maintainers
|
|
- Documentation updates and examples
|
|
- Meaningful additions to the test suite
|
|
|
|
If you want to add a niche or specialized workflow, consider contributing to the [EvoSkills repository](https://github.com/EvoScientist/EvoSkills) instead.
|
|
|
|
## Development setup
|
|
|
|
1. **Fork and clone** the repository:
|
|
```bash
|
|
git clone https://github.com/<your-username>/EvoScientist.git
|
|
cd EvoScientist
|
|
```
|
|
|
|
2. **Install dependencies** (requires [uv](https://docs.astral.sh/uv/)):
|
|
```bash
|
|
uv sync --dev
|
|
```
|
|
|
|
3. **Run the test suite** (no API keys needed):
|
|
```bash
|
|
uv run pytest
|
|
```
|
|
|
|
4. **Run the linter:**
|
|
```bash
|
|
uv run ruff check .
|
|
```
|
|
|
|
## Submitting a pull request
|
|
|
|
1. Create a branch from `main` with a descriptive name (e.g. `fix/session-crash`, `feat/export-csv`).
|
|
2. Make your changes, keeping commits focused and well-described.
|
|
3. Ensure `uv run ruff check .` and `uv run pytest` pass locally — these also run in CI.
|
|
4. Open a PR against `main` and fill in the PR template.
|
|
5. A maintainer will review your PR. Please be responsive to feedback.
|
|
|
|
## Code style
|
|
|
|
- We use [Ruff](https://docs.astral.sh/ruff/) for linting. Run `uv run ruff check .` before pushing.
|
|
- Follow the existing code patterns and conventions in the area you're modifying.
|
|
- Keep changes minimal and focused on the task at hand.
|
|
|
|
---
|
|
|
|
## Project overview
|
|
|
|
EvoScientist is a multi-agent AI system for automated scientific experimentation and discovery. It orchestrates specialized sub-agents that plan experiments, search literature, write code, debug, analyze data, and draft reports.
|
|
|
|
| Fact | Value |
|
|
|------|-------|
|
|
| Language | Python 3.11+ |
|
|
| License | Apache 2.0 |
|
|
| Framework | [DeepAgents](https://github.com/langchain-ai/deepagents) + [LangChain](https://python.langchain.com/) + [LangGraph](https://langchain-ai.github.io/langgraph/) |
|
|
| Default model | `claude-sonnet-4-6` (Anthropic) |
|
|
| Tests | ~890 across 36 files, no API keys needed |
|
|
| Config file | `~/.config/evoscientist/config.yaml` |
|
|
|
|
### Sub-Agents (defined in `EvoScientist/subagent.yaml`)
|
|
|
|
| Agent | Purpose |
|
|
|-------|---------|
|
|
| `planner-agent` | Creates and updates experimental plans (no web search, no implementation) |
|
|
| `research-agent` | Web research for methods, baselines, and datasets (Tavily search) |
|
|
| `code-agent` | Implements experiment code and runnable scripts |
|
|
| `debug-agent` | Reproduces failures, identifies root causes, applies minimal fixes |
|
|
| `data-analysis-agent` | Computes metrics, creates plots, summarizes insights |
|
|
| `writing-agent` | Drafts paper-ready Markdown experiment reports |
|
|
|
|
### Data flow
|
|
|
|
```txt
|
|
User Input (CLI / TUI / 10 Channel Integrations)
|
|
|
|
|
CLI (cli/) / TUI (cli/tui_*) / Channel Server (channels/)
|
|
|
|
|
Main Agent (EvoScientist.py) -- create_deep_agent()
|
|
+-- System Prompt (prompts.py)
|
|
+-- Chat Model (llm/ -- multi-provider)
|
|
+-- Middleware: Memory (middleware/memory.py)
|
|
+-- Backend: CompositeBackend (backends.py)
|
|
| / --> CustomSandboxBackend (workspace read/write + execute)
|
|
| /skills/ --> MergedReadOnlyBackend (user > built-in)
|
|
| /memory/ --> FilesystemBackend (persistent cross-session)
|
|
+-- MCP Tools (mcp/ -- optional, cached by config signature)
|
|
|
|
|
task tool --> Delegates to Sub-Agents
|
|
|
|
|
Stream Events --> Emitter --> Tracker --> State --> Rich Display / TUI
|
|
```
|
|
|
|
---
|
|
|
|
## Need help?
|
|
|
|
Reach us on [Discord](https://discord.gg/AZ9ZMXkunY) or WeChat (linked in README).
|