Metadata-Version: 2.5
Name: create-atelier
Version: 0.2.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
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).

## What gets created

`create-atelier` is needed only to create a project or resume its creation
walkthrough. After that, the project carries its own skills, file contracts, and
lint helper under `.agents/skills/`. Read those files or ask your coding agent to
use them. The generator is not a runtime dependency.

Specs define valid files, skills guide the work, and the lint skill checks the
record. The optional browser reader displays it. You can run the example without
a coding agent.

## 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 create-atelier --resume .`.
See the generated project's README for setup details.

## Work inside the generated project

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` points to the project skills: task coordination,
writing, code review, figures, and lint. 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.

## Update an existing project

The generator refuses an existing destination. To adopt newer skills, generate a
separate temporary project, compare its `.agents/skills/` with yours, and commit
the changes you choose. Preserve local conventions and work records. There is no
automatic upgrade or requirement to update old projects.

## 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.

Use the generated `atelier-lint` skill to check a project:

```sh
cd /path/to/research
uv run .agents/skills/atelier-lint/scripts/lint.py . --programmatic
```

Omit `--programmatic` to add agent reviews of writing, code design, and figures.
The script declares its dependencies for uv. 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
```

In `src/create_atelier/`, `cli.py` generates projects, `setup.py` handles the
creation walkthrough, and `template/` holds copied files. The `atelier-lint`
skill inside that template owns its `references/` contracts and `scripts/` checks. The independent `frontend/` package has its own
instructions and tests. Read the shared [development plan](https://williamheld.com/atelier/?repo=WillHeld%2Fatelier-demo&type=dataset&revision=main#/file/docs%2Fdesign.md)
before claiming work.

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