research-automation 0.2.0
Scientific research automation framework powered by Claude Code
Requires Python: >=3.11
Keywords: research, automation, scientific-computing, claude, ai-assisted, paper-writing, experiment-tracking

<p align="center">
  <h1 align="center">Research Automation</h1>
  <p align="center">
    End-to-end scientific research automation powered by Claude Code and multi-agent orchestration.
  </p>
</p>

<p align="center">
  <a href="https://github.com/lucafusarbassini/research-automation/actions/workflows/ci.yml"><img src="https://github.com/lucafusarbassini/research-automation/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+">
  <a href="https://github.com/lucafusarbassini/research-automation/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
  <a href="https://lucafusarbassini.github.io/research-automation/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-brightgreen.svg" alt="Docs"></a>
</p>

<p align="center">
  <!-- Replace with an actual screenshot or demo GIF -->
  <img src="https://via.placeholder.com/800x400?text=research+start+%E2%80%94+demo+coming+soon" alt="Demo" width="700">
</p>

---

Research Automation turns a research idea into reproducible code, validated results, and a publication-ready LaTeX paper -- all from your terminal. A master agent breaks your goal into subtasks and dispatches them to specialized sub-agents (researcher, coder, reviewer, falsifier, writer, cleaner) that execute inside a Docker-isolated environment with 70+ MCP integrations auto-discovered on demand.

## Prerequisites

| Requirement | Minimum version | Setup guide |
|-------------|----------------|-------------|
| **Python** | 3.11+ | [python.org/downloads](https://www.python.org/downloads/) |
| **Node.js** | 20+ | [nodejs.org](https://nodejs.org/) |
| **Docker** | 24+ | [docs.docker.com/get-docker](https://docs.docker.com/get-docker/) |
| **Git** | 2.40+ | [git-scm.com](https://git-scm.com/) |
| **Claude API key** | -- | [console.anthropic.com](https://console.anthropic.com/) |
| **GitHub SSH key** | -- | [docs.github.com/authentication](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) |

> Docker is optional for local-only usage but strongly recommended for overnight autonomous runs.

## Quick Start

```bash
# 1. Install
pip install research-automation

# 2. Create a new project (interactive onboarding)
research init my-experiment

# 3. Launch an interactive research session
cd my-experiment
research start
```

That's it. The onboarding wizard will ask for your research goal, compute preferences, and notification settings, then scaffold a fully configured project.

## Features

### Multi-Agent Orchestration

A hierarchical swarm of specialized Claude agents collaborates on your research. The **master agent** parses every request and routes it to the right sub-agent:

| Agent | Role |
|-------|------|
| **Researcher** | Literature search, paper retrieval, background synthesis |
| **Coder** | Implementation, experiments, data processing |
| **Reviewer** | Code review, improvement suggestions |
| **Falsifier** | Attacks results, finds flaws, enforces Popperian falsification |
| **Writer** | Paper sections, documentation, reports |
| **Cleaner** | Refactoring, optimization, code hygiene |

Token budgets are automatically distributed across agents and monitored throughout the session.

### Vector Memory & Knowledge Accumulation

Every insight, decision, and finding is persisted to a growing **Encyclopedia** backed by HNSW vector search (via claude-flow). Agents query memory semantically so knowledge compounds across sessions instead of being lost.

```bash
research memory "effect of learning rate on convergence"
```

### Paper Pipeline

A complete LaTeX publication workflow ships with every project:

- Structured `main.tex` template with standard sections
- BibTeX citation management
- Automatic figure reference checking
- Style analysis and transfer (sentence length, passive voice, hedging metrics)
- One-command compilation: `research paper build`

### Overnight Autonomous Mode

Queue a task list and let the system work unattended:

```bash
research overnight --iterations 30
```

The system executes your TODO list iteratively, checkpoints progress after every subtask, and stops when the completion signal is detected or the iteration cap is reached. Supports both claude-flow swarm orchestration and a raw-loop fallback.

### Auto-Debug Loop

When a command fails, the auto-debug module captures the error, analyses the traceback, proposes a fix, applies it, and retries -- all without manual intervention. Every fix and its outcome are logged for reproducibility.

### 3-Tier Model Routing

Requests are automatically routed to the most cost-effective model:

| Tier | Model | Used for |
|------|-------|----------|
| Booster | Claude Haiku | Formatting, lookups, classification |
| Workhorse | Claude Sonnet | Code writing, analysis, general tasks |
| Oracle | Claude Opus | Architecture, validation, paper writing |

### Browser Automation

Headless browser sessions for web scraping, screenshot capture, and PDF generation. Delegates to a Puppeteer MCP server when available; falls back to lightweight HTTP tools otherwise.

### Cross-Repository Coordination

Link multiple repositories, run coordinated commits, and enforce permission boundaries across projects -- useful for mono-repo experiments that span data pipelines and model code.

### Voice Prompting

Transcribe audio instructions, detect language, and structure them into actionable prompts that feed directly into the agent pipeline.

### Interactive Dashboard

A Rich-powered TUI that shows live progress, TODO status, session history, and resource utilization at a glance.

### Figure Gallery

Automatically scans, catalogs, and organizes experiment figures by run ID and format for quick review and paper inclusion.

### Security & Reproducibility

- Credential isolation via `.env` files (never committed)
- Docker containerization for safe, reproducible execution
- Full audit logging in `state/audit.log`
- Git checkpoint after every subtask

## Installation

### From PyPI (recommended)

```bash
pip install research-automation
```

### With ML extras

```bash
pip install "research-automation[ml]"     # numpy, pandas, scipy, scikit-learn, matplotlib
pip install "research-automation[all]"    # + chromadb, sentence-transformers, torch, jupyter
```

### Docker

```bash
docker build -t research-automation docker/
docker run -it -v $(pwd):/workspace research-automation
```

### From source

```bash
git clone https://github.com/lucafusarbassini/research-automation.git
cd research-automation
pip install -e ".[dev]"
```

## Configuration

After running `research init`, your project contains `config/settings.yml`:

```yaml
project:
  name: "my-experiment"
  type: "ml-research"

compute:
  type: "local-gpu"       # local-cpu | local-gpu | cloud | cluster
  gpu: "RTX 4090"

notifications:
  enabled: true
  method: "slack"          # email | slack | none

preferences:
  auto_commit: true
  checkpoint_interval: 30  # minutes
  max_overnight_iterations: 20
```

Reconfigure any section interactively:

```bash
research config notifications
research config compute
```

### API Keys

Store credentials in a `.env` file at the project root (auto-loaded, never committed):

```
ANTHROPIC_API_KEY=sk-ant-...
GITHUB_TOKEN=ghp_...
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `research init <name>` | Scaffold a new research project with interactive onboarding |
| `research start` | Launch an interactive Claude Code session |
| `research overnight` | Run autonomous overnight mode with configurable iterations |
| `research status` | Show current TODO, progress, and resource metrics |
| `research config [section]` | View or update project settings |
| `research paper <action>` | Paper pipeline: `build`, `check`, `update`, `modernize` |
| `research memory <query>` | Semantic search across vector memory |
| `research agents` | Show active swarm agent status |
| `research metrics` | Display token usage, cost, and system resource stats |
| `research list-sessions` | List all past and active sessions |
| `research --version` | Print version |

Run `research <command> --help` for full option details.

## Architecture

```
research-automation/
|
|-- cli/                        # Typer CLI entry points
|   |-- main.py                 #   research command definitions
|   |-- dashboard.py            #   Rich TUI dashboard
|   +-- gallery.py              #   Figure gallery viewer
|
|-- core/                       # Python library modules
|   |-- agents.py               #   Agent definitions & routing
|   |-- auto_debug.py           #   Auto-debug loop
|   |-- autonomous.py           #   Overnight autonomous runner
|   |-- browser.py              #   Headless browser integration
|   |-- claude_flow.py          #   claude-flow bridge (swarm, memory, metrics)
|   |-- cross_repo.py           #   Multi-repo coordination
|   |-- knowledge.py            #   Encyclopedia & keyword search
|   |-- mcps.py                 #   MCP discovery & management (70+ integrations)
|   |-- meta_rules.py           #   Automatic meta-rule capture
|   |-- model_router.py         #   3-tier model routing
|   |-- notifications.py        #   Email / Slack notifications
|   |-- onboarding.py           #   Project setup wizard
|   |-- paper.py                #   LaTeX compilation & citation management
|   |-- reproducibility.py      #   Reproducibility tracking
|   |-- resources.py            #   System resource monitoring
|   |-- security.py             #   Credential & permission guards
|   |-- session.py              #   Session lifecycle management
|   |-- style_transfer.py       #   Academic writing style analysis
|   |-- tokens.py               #   Token budget tracking
|   |-- verification.py         #   Result verification
|   +-- voice.py                #   Voice transcription & prompt structuring
|
|-- templates/                  # Scaffolded into every new project
|   |-- .claude/                #   Agent definitions, hooks, skills
|   |-- paper/                  #   LaTeX template, Makefile, references.bib
|   |-- knowledge/              #   GOAL.md, ENCYCLOPEDIA.md, CONSTRAINTS.md
|   |-- config/                 #   settings.yml, mcp-nucleus.json, claude-flow.json
|   +-- .github/workflows/      #   CI: tests, linting, paper build
|
|-- docker/                     # Dockerfile & docker-compose
|-- scripts/                    # Shell helpers (setup, overnight, interactive)
|-- defaults/                   # Philosophy, code style, prompt library, MCP catalog
+-- tests/                      # Pytest suite (40+ test modules)
```

### How it works

```
You --> research start --> Master Agent --> Sub-agents (researcher, coder, ...)
                              |                    |
                         claude-flow          Vector Memory
                         (swarm, MCP)         (HNSW index)
                              |                    |
                         Docker sandbox     knowledge/ENCYCLOPEDIA.md
```

1. `research init` scaffolds a project from templates and runs interactive onboarding.
2. `research start` launches a Claude Code session governed by the master agent.
3. The master agent reads your goal, plans subtasks, and dispatches them to specialized sub-agents.
4. Each sub-agent executes inside the project environment, commits results, and updates shared memory.
5. The falsifier agent validates outputs before anything is marked complete.
6. `research overnight` repeats this cycle unattended until the task list is done.

## Contributing

Contributions are welcome. To get started:

```bash
git clone https://github.com/lucafusarbassini/research-automation.git
cd research-automation
pip install -e ".[dev]"
python -m pytest tests/ -v
```

Please ensure all tests pass and code follows the project style (Black, isort, mypy) before submitting a pull request.

See the [Contributing Guide](CONTRIBUTING.md) for full details.

## Acknowledgments

This project was inspired by and builds upon the work of several open-source projects and communities:

- [claude-flow](https://github.com/ruvnet/claude-flow) by ruvnet -- Multi-agent orchestration patterns, HNSW vector memory, and swarm coordination. The project's agent bridge (`core/claude_flow.py`) integrates directly with claude-flow when available.
- [MCP Servers](https://github.com/modelcontextprotocol/servers) by the Model Context Protocol team -- Official MCP server implementations (filesystem, git, memory, fetch, GitHub, Puppeteer, and others) used as the foundation for the 70+ MCP integrations configured in this project.
- [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) by punkpeye -- Comprehensive catalog of MCP servers that guided the selection and tiering of integrations in the MCP nucleus configuration.
- [arxiv-mcp-server](https://github.com/blazickjp/arxiv-mcp-server) by blazickjp -- ArXiv paper search MCP server used for literature discovery in the researcher agent pipeline.
- [Claude Code Tutorial](https://lamanno-epfl.github.io/tutorial_claude_code/) by the La Manno Lab (EPFL) -- Research workflow patterns and paper-writing guidance that informed the project's academic automation design.
- [claude-code-tips](https://github.com/ykdojo/claude-code-tips) by ykdojo -- Practical Claude Code best practices that shaped the agent instruction protocols and progressive prompting strategy.
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) by Anthropic -- The core AI coding agent that powers all sub-agent execution in this system.

## License

[MIT](LICENSE)