NeuriCo

Autonomous AI research framework. Idea in, paper out.

Quick Reference

What it does	Takes a research idea (YAML) and autonomously runs the full research lifecycle: literature review, experiment design, code execution, analysis, paper writing, GitHub push
Input

YAML file with 3 required fields: title, domain, hypothesis | | Output | Code (src/), results & plots (results/), LaTeX paper (paper_draft/), GitHub repo | | Providers | Claude Code, Codex, Gemini (OAuth login, not API keys) | | Install | git clone https://github.com/ChicagoHAI/neurico && cd neurico && ./neurico setup | | Source | github.com/ChicagoHAI/neurico — Chicago Human+AI Lab (ChicagoHAI), University of Chicago | | License | Apache 2.0 |

Requirements

Minimal (one of)

Option	What you need
Docker (recommended)	INLINECODE7 + INLINECODE8
Native

git + python>=3.10 + uv |

Resource

Access to at least one AI coding CLI (OAuth login required):

• - Claude Code (recommended)
• Codex
• Gemini CLI

Recommended

What	Why
GitHub token (classic, repo scope)	Auto-creates repos and pushes results. Create here

Optional API Keys

Key	Purpose
INLINECODE13	LLM-based repo naming, IdeaHub fetching, paper-finder
INLINECODE14

Semantic Scholar literature search via paper-finder | | OPENROUTER_KEY | Multi-model access during experiments | | COHERE_API_KEY | Improves paper-finder ranking (~7% boost) | | HF_TOKEN | Hugging Face private models/datasets | | WANDB_API_KEY | Weights & Biases experiment tracking |

Setup Tiers

• - Basic: CLI login + GITHUB_TOKEN -- full NeuriCo functionality
• Enhanced: + OPENAI_API_KEY -- LLM repo naming + IdeaHub support
• Full: + S2_API_KEY (+ optional COHERE_API_KEY) -- paper-finder literature search

Installation

Docker (recommended)

The Docker image is a pre-configured environment with Python, Node.js, AI coding CLIs (Claude Code, Codex, Gemini), and a full LaTeX installation for paper compilation -- so you don't have to install any of these yourself. All experiments run inside this container; nothing is installed on your host system beyond the cloned repo. The image is built from the open-source Dockerfile and hosted on GitHub Container Registry.

CODEBLOCK0

Or step by step:

CODEBLOCK1

Native

CODEBLOCK2

Invocation

Fastest: Fetch from IdeaHub and run

CODEBLOCK3

Browse ideas at IdeaHub, copy the URL, and run the command above. NeuriCo fetches the idea, creates a GitHub repo, runs experiments, writes a paper, and pushes everything.

From a YAML file

CODEBLOCK4

Run options

Option	Description
INLINECODE23	AI provider (default: claude)
INLINECODE24

Run locally without GitHub integration | | --write-paper | Generate LaTeX paper after experiments (default: on) | | --paper-style neurips\|icml\|acl\|ams | Paper format (default: neurips) | | --private | Create private GitHub repository |

Input Format

Only 3 fields required:

CODEBLOCK5

Optional fields: background (papers, datasets, code references), methodology (approach, steps, baselines, metrics), constraints (compute, time, memory, budget), expected_outputs, evaluation_criteria.

Full schema: ideas/schema.yaml

Output Format

CODEBLOCK6

Results are automatically pushed to the GitHub repo created during submission.

Supported Domains

Domain	Examples
Artificial Intelligence	LLM evaluation, prompt engineering, AI agents
Machine Learning

Training, evaluation, hyperparameter tuning | | Data Science | EDA, statistical analysis, visualization | | NLP | Language model experiments, text analysis | | Computer Vision | Image processing, object detection | | Reinforcement Learning | Agent training, policy evaluation | | Systems | Performance benchmarking, optimization | | Theory | Algorithmic analysis, proof verification | | Scientific Computing | Simulations, numerical methods |

Configuration

CODEBLOCK7

Environment variables go in .env (copy from .env.example). See README for details.

Security

• - No secrets are uploaded. API keys and tokens stay local in your .env file and are never committed, pushed, or sent anywhere beyond the APIs they authenticate with. Sensitive environment variables are explicitly filtered out from all subprocess calls and sanitized from logs.
• Experiments run inside Docker. The container is isolated from your host system. The only host directories mounted are your config, templates, and workspace output folder.
• Open source. The entire codebase, including the Dockerfile and install script, is publicly auditable on GitHub.
• Built by ChicagoHAI — the Human+AI Lab at the University of Chicago.