Getting started

The toolchain is a small set of Python modules: parse, format, lint, compile, verify, run, project, and book.

Setup

Create the artifact venv:

python3 -m venv .venv
.venv/bin/python3 -m pip install -r requirements.txt

Point Angl at a compiler provider. A local Ollama model:

export ANGL_MODEL_URL=http://<host>:11434

Or, if you already have Claude Code authenticated, the Claude Code CLI adapter:

export ANGL_MODEL_PROVIDER=claude-code
export ANGL_MODEL=sonnet

Providers are toolchain configuration, not part of the .angl language.

Compile and verify

Run a composed spec (dependencies compile first, then dependents; every chapter is verified black box):

python3 -m angl.run specs/provision_service.angl

The agent workflow

Whether the author is a human or an agent, the loop is the same:

edit .angl
run formatter
run linter
run parser
compile
verify examples
inspect manifest

If a behavior changes, examples must change.

Reading a program as a book

angl.book renders a program from its real .angl files: source tree, dependency graph, prose intent, scenario table, exact source, generated edition, latest pass/fail evidence, and whether an artifact is stale relative to its source.

python3 -m angl.book specs/picnic_plan.angl --view chapter --html book.html

Or serve a live reader that rebuilds from the current files on each request:

python3 -m angl.book specs/picnic_plan.angl --serve --port 8783

/chapter   prose-first chapter view
/reader    IDE-style source reader
/markdown  generated Markdown
/api/book  JSON payload with exact source and generated artifact text

Toolchain tests

The tests are stdlib-runnable and do not require a model:

python3 tests/test_parse.py
python3 tests/test_verify.py
python3 tests/test_compile.py
python3 tests/test_run.py
python3 tests/test_book.py