Demolab
A lab notebook for computational science — reproducible results, published and citable, run by a coding agent instead of a build system.
Coding agent setting someone up? Run
uvx demolab-cli docs GETTING-STARTED, read the file it prints, and follow it strictly, step by step. (Human, setting up by hand? See Quickstart.)
You write a model or experiment once as a small program. Demolab runs it, captures everything it produced, stamps it with the exact code version, and publishes a clean page — figures, numbers, and real typeset maths — to both the web and PDF. The numbers on the page are read from the run, so they can't drift. You drive it all by talking to a coding agent; there's no web development or build config to touch.
Quickstart
Open your coding agent in an empty folder and paste:
Run
uvx demolab-cli inithere, then follow its GETTING-STARTED runbook strictly.
It lays your lab down, walks you through the toolchain (uv, typst) and your first experiment, one step at a time.
Set it up by hand instead?
Install uv and typst (brew install uv typst), then:
mkdir my-lab && cd my-lab
uvx demolab-cli init # lab structure + git init — yours from the first commit
uv sync # installs the deps and the `demolab` command
Then write your first experiment — ask your agent to follow GETTING-STARTED, or model one on a shipped reference (demolab docs STARTERS prints the dir; monte-carlo-pi is the canonical starter). demolab dev serves the site as you go. The engine lives in the demolab-cli package — updating it is uv lock --upgrade-package demolab-cli && uv sync.
What to ask your agent
Open your lab in your agent and say a runbook's name — it follows that runbook one step at a time. demolab docs lists them all (each is a plain file shipped in the package; demolab docs <NAME> prints its path). In this repo they live under demolab_cli/runbooks/.
| Say… | …and it will |
|---|---|
| GETTING-STARTED | set you up end to end: scaffold, your first experiment live on a page, brand, publish |
| TOUR | guided walkthrough of the lab — what's here, what it found, where to start |
| MIGRATE-CODE | bring an existing codebase in, one experiment at a time |
| FROM-JUPYTER | launder a Jupyter notebook into a reproducible, seeded experiment |
| MIGRATE-STACK | write your tools in MATLAB / Julia / R / Octave instead of Python |
| EMBED-DOCS | drop demolab into another project as a docs/ site |
| LINT | check your writeups against the house style |
| DOCTOR | audit the repo against the conventions |
| UPDATE | update the engine package, leaving your content untouched |
How it works
One decoupled loop: a tool computes → drops data → an experiment writes it up → the site publishes it. Every run records its exact parameters and the git commit it came from (stamped on the page), and tables read their numbers straight from the run — so prose and results can't disagree. A single Typst pass emits a website, a PDF per entry, and a book, all sharing the same live numbers.
The detail lives in the guides (in a lab: demolab docs <NAME>; in this repo, the files under demolab_cli/guides/):
- RULES.md — the tool ↔ experiment contract, schemas, provenance, and how to add things.
- STRUCTURE.md — the annotated file tree.
- HOUSESTYLE.md — prose, maths, and figure style.
- AGENTS.md — the agent entry point.
Commands
demolab shows them all. The everyday ones: init, docs, install, scaffold, dev, build, test. Run an experiment end-to-end directly: uv run python experiments/expNNN.py (there's no demolab run wrapper).
License
MIT — free to use, fork, and adapt for your own lab.
1 maintainer
Metadata
1 maintainer
Release files for demolab-cli 2.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| demolab_cli-2.3.0.tar.gz | 1.4 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| demolab_cli-2.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.7 MB
Release files / demolab_cli-2.3.0.tar.gz
| Download URL | demolab_cli-2.3.0.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
87337f4d9e2ed7e09f0ccea10e09e1d127bb19c94912d6e5b5f26c92fa25b35e
|
|
BLAKE2b-256 checksum How to use checksums |
811063bbffc9c6cdb8f146e308c644ee9f932159e75a1a843c1bc40986f479f0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.
Transparency logRelease files / demolab_cli-2.3.0-py3-none-any.whl
| Download URL | demolab_cli-2.3.0-py3-none-any.whl |
|---|---|
| Size | 1.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fea5da57ae000d63f4d111e19873ba11a27866d4639e0fbb152987c80a2a44b3
|
|
BLAKE2b-256 checksum How to use checksums |
3557e6d3ebaf28397c80261e9095b8ac47d12f3012d8f53b5a02f994814ef77d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.
Transparency log
