Metadata-Version: 2.5
Name: create-atelier
Version: 0.1.0
Summary: Create a portable, Git-native research project for humans and agents
Project-URL: Repository, https://github.com/Helw150/create-atelier
Project-URL: Development space, https://huggingface.co/datasets/WillHeld/atelier-demo
Project-URL: Reader, https://williamheld.com/atelier/
Author: William Held
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.11
Requires-Dist: huggingface-hub<3,>=1
Requires-Dist: markdown-it-py<5,>=3
Requires-Dist: pillow<13,>=11
Requires-Dist: pyarrow<27,>=18
Requires-Dist: pyyaml<7,>=6
Requires-Dist: resvg-py<0.6,>=0.4
Requires-Dist: tree-sitter-typescript<0.24,>=0.23
Requires-Dist: tree-sitter<0.27,>=0.25
Description-Content-Type: text/markdown

# 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](https://williamheld.com/atelier/?repo=WillHeld%2Fatelier-demo&type=dataset&revision=main#/overview).

## Try it

Requires Python 3.11+, [uv](https://docs.astral.sh/uv/), and Git.
Create a project:

```sh
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](https://github.com/Helw150/create-atelier/blob/main/docs/work-records.md).

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](https://github.com/Helw150/create-atelier/blob/main/docs/format.md) when adapting the example.

## Read and review

The [browser reader](https://williamheld.com/atelier/) opens an Atelier stored on
Hugging Face. It shows documents, agent work, experiments, and figures without
running repository code. The [separate frontend package](https://github.com/Helw150/create-atelier/blob/main/frontend/README.md) also
reads local working trees and builds a static site.

Check a research project's files with:

```sh
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](https://github.com/Helw150/create-atelier/blob/main/docs/lint.md).

## Develop Atelier

From a source checkout:

```sh
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.
