# AutoResearch: AI/ML Research Agents from Idea to Paper-Ready Evidence

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/evomap-autoresearch
Generated for open source discovery and AI-assisted research.

AutoResearch is an open-source agent workflow designed for AI and machine learning research. It automates the entire research process, from generating ideas and planning experiments to execution, analysis, and independent evaluation. This project helps researchers produce paper-ready evidence efficiently and with traceable provenance.

GitHub: https://github.com/EvoMap/AutoResearch
OSRepos URL: https://osrepos.com/repo/evomap-autoresearch

## Summary

AutoResearch is an open-source agent workflow designed for AI and machine learning research. It automates the entire research process, from generating ideas and planning experiments to execution, analysis, and independent evaluation. This project helps researchers produce paper-ready evidence efficiently and with traceable provenance.

## Topics

- Python
- AI
- Machine Learning
- Research Agents
- Automation
- Open Source

## Repository Information

Last analyzed by OSRepos: Tue Sep 22 2026 20:21:09 GMT+0100 (Western European Summer Time)
Detail views: 2
GitHub clicks: 0

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## Introduction

AutoResearch, an open-source project by EvoMap, is an advanced agent workflow designed to streamline AI and machine learning research. It guides the entire research process, from initial idea generation and experiment planning to implementation, execution, result analysis, and independent evaluation. The goal is to produce a comprehensive evidence package ready for paper writing, significantly reducing manual effort and enhancing research quality.

This system addresses common challenges in AI/ML research by grounding problem discovery in real signals, incorporating domain knowledge, and validating claims through cross-model review, source records, experiment logs, critic reports, and blind reviews. It aims to minimize unsupported generation, unclear provenance, inflated self-evaluation, and overinterpretation of results, while preserving all necessary evidence and state for researcher review.

## Why Use It and Key Benefits

AutoResearch offers several core capabilities that make it a powerful tool for researchers:

*   **Cross-domain Idea Generation**: Discover new problems by combining recent external signals (papers, communities, open-source trends) with your local domain knowledge and constraints.
*   **Independent Multi-Model Review**: Utilize at least three distinct models during idea generation to ensure independent development and cross-review of candidate ideas, enhancing objectivity.
*   **Stateful Experiment Execution**: Plans, code, queues, logs, and conclusions are persistently stored, allowing long-running experiments to resume seamlessly after interruptions.
*   **Pilot Before Scaling**: Test the feasibility of experiments at a lower cost before committing to full-scale execution, enabling early stopping or revision.
*   **Traceable Evidence and Sources**: All research artifacts, including Forge sources, knowledge directions, experiment results, critic reports, and blind reviews, are meticulously recorded for full transparency.
*   **Support for Negative Results**: The system preserves evidence and allows for early termination when a hypothesis fails, preventing the forced narrative of success in every experiment.

## Installation

To get started with AutoResearch, follow these steps to set up your environment:

1.  **Clone the Repository and Check the Environment**:
    Prepare a Linux or SSH machine with Git, Python 3.10+, and `python3-venv` installed.

    bash
git clone https://github.com/EvoMap/AutoResearch.git
cd AutoResearch
bash scripts/bringup.sh
    

    `bringup.sh` sets up the Python environment, installs dependencies, runs baseline tests, and checks model configuration without contacting model services.

2.  **Configure Model Services**:
    Create local configuration files for API keys and provider settings.

    bash
test -f .env || cp .env.example .env
test -f config/providers.local.json || \
  cp config/providers.example.json config/providers.local.json
    

    Edit `.env` for API URLs/keys and `config/providers.local.json` for endpoints and model assignments. AutoResearch supports various combinations of Gemini, GPT, or Claude models.

3.  **Test the APIs**:
    Verify your model configurations by sending a small number of real requests.

    bash
set -a
. ./.env
set +a
.venv/bin/python scripts/preflight.py --live
    

    An exit code `0` indicates that normal roles have usable models and multi-model stages meet independence requirements.

## Examples

AutoResearch supports two main workflows: Idea Generation and Idea Execution.

### Idea Generation: Cross-Domain Discovery

This workflow helps you discover and plan new research directions.

1.  **Run the Pipeline**:
    Execute the default entrypoint to collect signals, filter, intersect with local knowledge, generate and review ideas, and plan experiments.

    bash
.venv/bin/python idea_generation.py
    

    Main outputs are found in `data/candidates/`, `data/verified/`, `data/idea_forge/`, and `logs/`.

2.  **Select and Export an Idea**:
    List executable plans from a forge file and then export a selected plan for execution.

    bash
.venv/bin/python src/idea_provenance.py list \
  --forge-file data/idea_forge/forge_YYYYMMDD_HHMM.json

.venv/bin/python src/idea_provenance.py export \
  --forge-file data/idea_forge/forge_YYYYMMDD_HHMM.json \
  --result-index 1 \
  --plan-index 1 \
  --output data/ideas/my_experiment.txt
    

### Idea Execution

If you already have a research idea, you can directly proceed with execution.

1.  **Prepare the Execution Environment**:
    Install Bun 1.3+, Node.js, Conda (or another Python environment manager), and the Ralph Loop plugin for Claude Code.

    bash
cd ar-runtime
bun install --frozen-lockfile
cd ..
    

2.  **Generate the Execution Configuration**:
    Create machine-local settings and project the unified provider configuration.

    bash
test -f ar-runtime/.claude/settings.local.json || \
  cp ar-runtime/.claude/settings.local.example.json \
     ar-runtime/.claude/settings.local.json

set -a
. ./.env
set +a
.venv/bin/python scripts/render_env.py
.venv/bin/python scripts/preflight.py --live --tools
    

3.  **Start the Coordinator**:
    Run the Claude Code CLI in an isolated environment and start the coordinator with your idea.

    bash
cd ar-runtime
claude --dangerously-skip-permissions
# Inside Claude Code:
# /ar-coordinator ../data/ideas/my_experiment.txt ../data/projects/my_experiment
    

    For non-interactive runs, use the supervisor script:

    bash
cd ar-runtime
scripts/ar-supervisor.sh \
  ../data/ideas/my_experiment.txt \
  ../data/projects/my_experiment
    

4.  **Inspect Project Results**:
    Generate a dashboard to visualize the progress and results of your project.

    bash
.venv/bin/python src/generate_project_dashboard.py my_experiment
    

## Links

*   **GitHub Repository**: [EvoMap/AutoResearch](https://github.com/EvoMap/AutoResearch){target="_blank"}
*   **EvoMap Ecosystem**: [EvoMap](https://evomap.ai){target="_blank"}
*   **arXiv Report**: [arXiv:2608.17906](https://arxiv.org/abs/2608.17906){target="_blank"}
*   **Unified Provider Configuration**: [Documentation](https://github.com/EvoMap/AutoResearch/blob/main/docs/unified_provider_config.md){target="_blank"}
*   **Model Provider Setup and Validation**: [Documentation](https://github.com/EvoMap/AutoResearch/blob/main/docs/llm_provider_setup.md){target="_blank"}
*   **Execution State Machine**: [Documentation](https://github.com/EvoMap/AutoResearch/blob/main/ar-runtime/ar-coordinator-startup-flow.md){target="_blank"}