Skip to content

ChicagoHAI/idea-explorer

BranchesTags

Repository files navigation

Idea Explorer - AI-Powered Research Acceleration

GitHub Stars Python 3.10+ Docker License X Follow Discord

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.

Idea Explorer Demo
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: Docker (Recommended)

Docker provides an isolated, reproducible environment with GPU support.

# 1. Clone and setup
git clone https://github.com/ChicagoHAI/idea-explorer
cd idea-explorer
cp .env.docker.example .env
# Edit .env with your API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.)

# 2. Build container (one-time)
./idea-explorer build

# 3. Run! Fetch from IdeaHub and execute
./idea-explorer fetch https://hypogenic.ai/ideahub/idea/HGVv4Z0ALWVHZ9YsstWT \
    --submit --run --provider <YOUR_CLI> --full-permissions

The --full-permissions flag enables autonomous execution without permission prompts.

Option B: Native Installation

For users who prefer running directly on their system without containers.

# 0. Setup (one-time)
uv sync  # Install dependencies with uv
cp .env.example .env
# Edit .env - see Configuration section below for details

# 1. One-liner: Fetch, submit, and run immediately
uv run python src/cli/fetch_from_ideahub.py https://hypogenic.ai/ideahub/idea/HGVv4Z0ALWVHZ9YsstWT \
    --submit --run --provider <YOUR_CLI> --full-permissions

Create Your Own Idea

# Docker
./idea-explorer submit ideas/examples/ml_regularization_test.yaml
./idea-explorer run <idea_id> --provider <YOUR_CLI>  --full-permissions

# Native
uv run python src/cli/submit.py ideas/examples/ml_regularization_test.yaml
uv run python src/core/runner.py <idea_id> --provider <YOUR_CLI> --full-permissions
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

Option A: Docker (Recommended)

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

# 2. Configure environment
cp .env.docker.example .env
# Edit .env and add your API keys

# 3. Build container
./idea-explorer build

# 4. Login to CLI tools (one-time, if needed)
./idea-explorer login
# Inside the container, run: claude, codex, or gemini to authenticate

CLI Authentication: If you're already logged into Claude/Codex/Gemini on your host machine, credentials are automatically mounted into containers. Only run ./idea-explorer login if you haven't authenticated these CLI tools before.

Prerequisites for GPU support:

# Install NVIDIA Container Toolkit
sudo apt install nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Option B: Native 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 API keys (see Configuration section below)
Configuration

Environment Variables (.env)

Copy .env.example to .env and configure:

Variable Required Description
GITHUB_TOKEN Yes GitHub Personal Access Token. Generate here with repo and write:org scopes
OPENAI_API_KEY Yes* For IdeaHub integration. Generate here. *Not needed if not using IdeaHub
GITHUB_ORG No Your GitHub organization (default: ChicagoHAI)
ANTHROPIC_API_KEY No For Claude provider
GOOGLE_API_KEY No For Gemini provider

Workspace Configuration

Research workspaces are created in the directory specified by config/workspace.yaml.

Default: workspace/ in the project root (already gitignored, works out of the box)

To customize: Copy config/workspace.yaml.example to config/workspace.yaml and edit parent_dir:

workspace:
  parent_dir: "/path/to/your/workspaces"  # Your custom path
  auto_create: true

The workspace.yaml file is gitignored, so your local settings won't be pushed.

Usage Options

Running Research

# Docker (recommended)
./idea-explorer run <idea_id> --provider <YOUR_CLI> --full-permissions

# Native
uv run python src/core/runner.py <idea_id> --provider <YOUR_CLI> --full-permissions

Available options:

Option Description
--provider claude|gemini|codex AI provider (default: claude)
--timeout SECONDS Execution timeout (default: 3600)
--full-permissions Allow agents to run without prompts
--no-github Run locally without GitHub integration
--github-org ORG GitHub organization (default: GITHUB_ORG env var)
--use-scribe Enable Jupyter notebook integration

Common Commands

# Docker
./idea-explorer fetch <url>              # Fetch from IdeaHub
./idea-explorer fetch <url> --submit     # Fetch and submit
./idea-explorer submit <idea.yaml>       # Submit an idea
./idea-explorer run <id> [options]       # Run research
./idea-explorer shell                    # Interactive shell

# Native
uv run python src/cli/fetch_from_ideahub.py <url>
uv run python src/cli/submit.py <idea.yaml>
uv run python src/core/runner.py <id> [options]

Execution Modes

# Default mode: Raw CLI (recommended)
# Agents write Python scripts, simpler and more unified across providers
./idea-explorer run my_idea --provider <YOUR_CLI> --full-permissions

# Notebook mode: With scribe (optional, native only)
# Agents get Jupyter notebook access via MCP tools
uv run python src/core/runner.py my_idea --provider <YOUR_CLI> --full-permissions --use-scribe

Permission Modes

# With permission prompts (default, safer)
./idea-explorer run my_idea

# Full autonomous mode (faster, no interruptions)
./idea-explorer run my_idea --provider <YOUR_CLI> --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

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 explore your research ideas?

# Docker (recommended)
./idea-explorer submit ideas/examples/ml_regularization_test.yaml
./idea-explorer run <idea_id> --provider <YOUR_CLI> --full-permissions

# Native
uv run python src/cli/submit.py ideas/examples/ml_regularization_test.yaml
uv run python src/core/runner.py <idea_id> --provider <YOUR_CLI> --full-permissions

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

About

No description, website, or topics provided.

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

15 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors 2

  •  
  •  

Languages