---

Idea Explorer is an autonomous research framework that takes structured research ideas and orchestrates AI agents to design, execute, analyze, and document experiments across diverse domains.

Key Features

Feature	Description
Minimal Input	Just provide title, domain, and hypothesis - agents handle the rest
Agent-Driven Research	Literature review, dataset search, baseline identification
Multi-Provider Support	Works with Claude, Gemini, and Codex (raw CLI by default, notebooks optional)
Pragmatic Execution	Creates resources when they don't exist, always proceeds
Domain-Agnostic	ML, data science, AI, systems, theory, and more
Smart Documentation	Auto-generates reports, code, and results
GitHub Integration	Auto-creates repos and pushes results

Quick Start

Option A: Fetch from IdeaHub

# 0. Setup (one-time)
uv sync  # Install dependencies with uv
cp .env.example .env
# Edit .env and add your GITHUB_TOKEN and OPENAI_API_KEY

# 1. Fetch an idea from IdeaHub and auto-submit
python src/cli/fetch_from_ideahub.py https://hypogenic.ai/ideahub/idea/HGVv4Z0ALWVHZ9YsstWT --submit

# 2. Run the research
python src/core/runner.py <idea_id>

Option B: Create Your Own Idea

# 0. Setup (one-time)
uv sync
cp .env.example .env
# Edit .env and add your GITHUB_TOKEN

# 1. Submit a research idea (creates GitHub repo & workspace)
python src/cli/submit.py ideas/examples/ml_regularization_test.yaml

# 2. (Optional) Add resources to workspace
cd workspace/<repo-name>
# Add datasets, documents, code, etc.
git add . && git commit -m "Add research resources" && git push

# 3. Run the research
cd ../..
python src/core/runner.py <idea_id>

# 4. Results automatically pushed to GitHub

System Architecture

flowchart LR
    subgraph Input
        A[Research Idea<br/>YAML] --> B[Submit CLI]
        C[IdeaHub URL] --> B
    end

    subgraph Processing
        B --> D[GitHub Repo<br/>Created]
        D --> E[Research Agent]
        E --> F[Literature Review]
        E --> G[Experiment Design]
        E --> H[Code Execution]
    end

    subgraph Output
        F --> I[Documentation]
        G --> I
        H --> I
        I --> J[Notebooks]
        I --> K[Results & Plots]
        I --> L[GitHub Push]
    end

Loading

Directory Structure:

ideas/
  submitted/      <- New research ideas
  in_progress/    <- Currently executing
  completed/      <- Finished research

workspace/<repo-name>/
  src/            <- Python scripts for experiments (default mode)
  results/        <- Metrics, plots, models
  logs/           <- Execution logs and transcripts
  artifacts/      <- Models, checkpoints
  notebooks/      <- Jupyter notebooks (only with --use-scribe)
  .idea-explorer/ <- Original idea spec

Research-First Philosophy

You can submit minimal ideas - agents will research the details:

• Just provide: title, domain, research question
• Agent searches for: datasets, baselines, evaluation methods
• Grounds in literature when resources exist
• Creates synthetic data/baselines when they don't
• Always proceeds to execution - doesn't get stuck

Example minimal idea:

idea:
  title: "Do LLMs understand causality?"
  domain: artificial_intelligence
  hypothesis: "LLMs can distinguish causal from correlational relationships"
  # That's it! Agent handles the rest

Full specification example:

idea:
  title: "Clear, descriptive title"
  domain: machine_learning
  hypothesis: "Specific, testable hypothesis"

  background:
    description: "Context and motivation"
    papers:
      - url: "https://arxiv.org/..."
        description: "Why this paper is relevant"
    datasets:
      - name: "Dataset name"
        source: "Where to get it"

  methodology:
    approach: "High-level strategy"
    steps: ["Step 1", "Step 2"]
    baselines: ["Baseline 1", "Baseline 2"]
    metrics: ["Metric 1", "Metric 2"]

  constraints:
    compute: gpu_required
    time_limit: 3600

See ideas/schema.yaml for full specification.

Supported Domains

Domain	Examples
Artificial Intelligence	LLM evaluation, prompt engineering, AI agents, benchmarking
Machine Learning	Training, evaluation, hyperparameter tuning
Data Science	EDA, statistical analysis, visualization
Systems	Performance benchmarking, optimization
Theory	Algorithmic analysis, proof verification
Scientific Computing	Simulations, numerical methods
NLP	Language model experiments, text analysis
Computer Vision	Image processing, object detection
Reinforcement Learning	Agent training, policy evaluation

Installation

# 1. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Clone repository
git clone https://github.com/ChicagoHAI/idea-explorer
cd idea-explorer

# 3. Install dependencies
uv sync

# 4. (Optional) Install scribe for Jupyter notebook integration
# Only needed if you want to use --use-scribe flag
# Follow instructions at: https://github.com/goodfire-ai/scribe

# 5. Configure environment
cp .env.example .env
# Edit .env and add your GITHUB_TOKEN and AI provider API keys

Usage Options

Running Research

python src/core/runner.py <idea_id>

# Options:
#   --provider claude|gemini|codex  (default: claude)
#   --timeout SECONDS               (default: 3600)
#   --full-permissions              (allow agents to run without prompts)
#   --no-github                     (run locally without GitHub)
#   --github-org ORG                (specify GitHub org, default: ChicagoHAI)
#   --use-scribe                    (enable Jupyter notebook integration)

Execution Modes

# Default mode: Raw CLI (recommended)
# Agents write Python scripts, simpler and more unified across providers
python src/core/runner.py my_idea --full-permissions

# Notebook mode: With scribe (optional)
# Agents get Jupyter notebook access via MCP tools
python src/core/runner.py my_idea --full-permissions --use-scribe

Permission Modes

# With permission prompts (default, safer)
python src/core/runner.py my_idea

# Full autonomous mode (faster, no interruptions)
python src/core/runner.py my_idea --full-permissions

Evaluate Quality (Optional)

from src.evaluation.critic_runner import CriticRunner

runner = CriticRunner()
runner.evaluate_research(
    run_dir="runs/my_idea/",
    critics=["code_quality", "scientific_rigor", "reproducibility"]
)

---

Documentation

• docs/WORKFLOW.md - Complete workflow guide
• docs/IDEAHUB_INTEGRATION.md - IdeaHub integration
• DESIGN.md - Comprehensive design document
• GITHUB_INTEGRATION.md - GitHub setup and usage
• ideas/schema.yaml - Full specification schema
• ideas/examples/ - Example research ideas

Contributing

Contributions welcome! Areas of interest:

• New domain templates (biology, chemistry, social science, etc.)
• Additional evaluation criteria
• Integration with experiment trackers
• Web interface
• Multi-agent collaboration features

Citation

If you use Idea Explorer in research, please cite:

@software{idea_explorer_2025,
  title={Idea Explorer: Autonomous Research Framework},
  author={Haokun Liu, Chenhao Tan},
  year={2025},
  url={https://github.com/ChicagoHAI/idea-explorer}
}

License

Apache 2.0 - See LICENSE file

---

Ready to automate your research?

python src/cli/submit.py ideas/examples/ml_regularization_test.yaml

For questions and feedback, open an issue or join our Discord.