Atelier

Atelier is a starter for research with coding agents. Keep the question, experiment, results, and conclusion linked in one Git repository. Agent work records give people a short summary and the next agent enough context to continue.

This is an early release; the file conventions are still being tested.

Browse the demo.

Try it

Requires Python 3.11+, uv, and Git. Create a project:

uvx create-atelier my-research --no-setup
cd my-research
uv sync
git add .
git commit -m "Initialize research project"
uv run --locked python experiments/exp-001/analyze.py
uv run python -c "import polars as pl; print(pl.read_parquet('experiments/exp-001/summary.parquet'))"

The example estimates a mean from synthetic observations. Inspect experiments/exp-001/summary.parquet for how error changes with sample size. The source revision and inputs are in experiments/exp-001/provenance.json. This demonstrates the workflow; it makes no claim about real-world systems.

For the optional figure, install Node.js 22+ and run npm install && npm run figure inside my-research. Open figures/cache/mean.svg.

Omit --no-setup for a walkthrough that offers dependency installation, optional figure tools, Hugging Face storage, and a first commit and push. Remote repositories default to private; creation and upload require confirmation. Local work needs no remote account. Resume with uvx --from create-atelier atelier setup .. See the generated project's README for setup details.

Do your research

Start with docs/design.md: replace the example question with your hypothesis and tasks. Use your editor or coding agent to change the experiment configuration and analysis in experiments/exp-001/. Commit the inputs, run the experiment, inspect its results, and link the evidence when proposing a conclusion in the design document.

The generated AGENTS.md describes task claims, evidence, and review conventions. Its skills guide writing, code design, and figures. For substantial work, keep agents/work/<task>.md current: a TL;DR at the top, followed by an append-only log of inputs, attempts, results, decisions, and next steps. Optional branch refs and commit hashes link the work to its code changes. See work records.

The files remain usable without the generator or a particular frontend. Markdown holds documents; YAML holds configuration and discussions; Parquet holds tables. Each experiment records its inputs and source revision to help another person or agent reproduce it. See the file conventions when adapting the example.

Read and review

The browser reader opens an Atelier stored on Hugging Face. It shows documents, agent work, experiments, and figures without running repository code. The separate frontend package also reads local working trees and builds a static site.

Check a research project's files with:

uvx --from create-atelier atelier lint /path/to/research --programmatic

Omit --programmatic to add agent reviews of writing, code design, and figures. Full review requires an authenticated Codex or Claude Code CLI and sends review content through that CLI to its model provider. These checks inspect the record; they do not establish that a scientific conclusion is true. Lint neither runs the experiment nor applies fixes. See lint coverage and reports.

Develop Atelier

From a source checkout:

uv run python -m unittest discover -s tests
uv build

The generator lives in src/create_atelier/; generated files come from its template/ directory. The independent frontend/ package has its own instructions and tests.

Licensed under Apache-2.0. Generated projects include the license and attribution; vendored libraries retain their own licenses.