liulab-llms 2026.11.0__tar.gz

liulab_llms-2026.11.0/.github/workflows/ci.yml

@@ -0,0 +1,109 @@
+# The gate, run on the pull request rather than on the branch.
+#
+# A job exists because a pixi ENVIRONMENT differs, not because a tool differs. The six
+# static steps share one environment and are one job; `test` runs in the `test`
+# environment; `docs` needs the heavy `docs` environment that nothing else installs, which
+# is the whole reason it is a job of its own.
+#
+# Every step invokes `pixi run <task>` and never a command line. The step list lives in
+# `pyproject.toml` — `check-static` names it once — so adding a step is one more word
+# there and nothing here. Conformance rule `workflow-step-tasks` holds every workflow in
+# the repo to it, and what it checks is that the command came from the task table: a step
+# may pass arguments after `--`, and the rule prints them rather than forbidding them.
+# It reads the `run:` line only, so `env:`, `working-directory:`, `shell:` and a local
+# composite action can still make a step do something no `pixi run` does here. Keeping
+# CI and a laptop the same is a habit this file keeps, not a property anything proves.
+#
+# Not shipped, deliberately: a `claude.yml`, because on a public repo anyone who can
+# comment could spend the API budget; container and benchmark workflows, because nothing
+# here needs them.
+name: ci
+
+on:
+  # `pull_request` is the trigger that matters. It tests the MERGE commit — the code that
+  # will exist after the merge, not the branch tip — and it is the only event that
+  # produces a run for a pull request from a fork. `push` is for `main` alone; on every
+  # branch it would run everything a second time for no new information.
+  push:
+    branches: [main]
+  pull_request:
+
+# Keyed on the workflow and the ref, so pushing again to a pull request cancels the run it
+# supersedes. `main` runs are never cancelled: a cancelled run on the branch everything
+# merges into is an unreliable gate, and a red-or-missing history is worse than a slow one.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  # ruff, pyright, vale, markdownlint and conformance, all at once, all reported.
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      # A real checkout, not a source archive: `conformance` shells out to `git ls-files`
+      # and exits 2 without a `.git` — its "could not run", spelled apart from the 1 a
+      # broken rule exits, so a bad checkout never reads as a rule this repo failed. The
+      # default shallow depth is enough — it needs the file list, not the history.
+      - uses: actions/checkout@v7
+      - uses: prefix-dev/setup-pixi@v0.10.2
+        with:
+          environments: default
+          # Fail if `pixi.lock` no longer matches `pyproject.toml`, rather than silently
+          # solving something else. This is what makes CI run the versions the laptop ran.
+          locked: true
+      # `check-static`, not `check`: `check` is the static steps plus pytest, and pytest is
+      # the `test` job below, in the environment that owns it.
+      - run: pixi run check-static
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: prefix-dev/setup-pixi@v0.10.2
+        with:
+          environments: test
+          locked: true
+      # `-e test` is load-bearing: the `test` task exists in every environment, and without
+      # the flag pixi would run it in `default`, which this job did not install.
+      - run: pixi run -e test test
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # The one job that needs history. The version is dynamic and hatch-vcs reads the
+          # newest tag; a shallow clone carries no tags, so the wheel would be stamped as a
+          # dev build even on a released commit.
+          fetch-depth: 0
+      - uses: prefix-dev/setup-pixi@v0.10.2
+        with:
+          # No `environments`: `build` is a plain task, so the default environment has it.
+          locked: true
+      - run: pixi run build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          # An empty upload is a green job that proved nothing.
+          if-no-files-found: error
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: prefix-dev/setup-pixi@v0.10.2
+        with:
+          environments: docs
+          locked: true
+      # `docs-build` is a task on the `docs` FEATURE, so pixi finds it in the one
+      # environment that has zensical and no `-e` flag is needed. The task carries
+      # `--strict`, so a dead link or a bad reference fails here — but not every kind of
+      # broken link, and not a `nav:` entry naming a missing file. The comment above
+      # `validation:` in `mkdocs.yml` lists what this job catches and what it does not, so
+      # a green run here is not a claim the site has no dead ends. This job builds the
+      # site and stops; publishing it is `docs.yml`, on `main`.
+      - run: pixi run docs-build

liulab_llms-2026.11.0/.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+# Publishing the site to the `gh-pages` branch.
+#
+# Hand-written on purpose: zensical has no `gh-deploy` and none is planned, so the two
+# halves are spelled out — build into `./site`, then force-push that directory to
+# `gh-pages`.
+#
+# The pull request already builds the site (the `docs` job in `ci.yml`). This workflow adds
+# only the publish, so it runs on `main` and nowhere else.
+name: docs
+
+on:
+  push:
+    branches: [main]
+  # For re-publishing without a commit — a Pages setting changed, a deploy was lost.
+  workflow_dispatch:
+
+# The deploy force-pushes a branch of this repository. Nothing else here writes.
+permissions:
+  contents: write
+
+# NOT cancelled in flight, unlike `ci.yml`. This job replaces a published branch, and a run
+# killed between the build and the push leaves `gh-pages` holding half a site with nothing
+# queued to finish it. A superseded run is cheap; a half-written public site is not.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: prefix-dev/setup-pixi@v0.10.2
+        with:
+          environments: docs
+          locked: true
+      # Writes `./site`. `--clean --strict` live in the task, so this and a laptop build
+      # the same way.
+      - run: pixi run docs-build
+      - uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          publish_branch: gh-pages
+          # `gh-pages` holds built output and no history anyone reads: one commit,
+          # replaced whole each deploy. This is what `mkdocs gh-deploy --force` did.
+          force_orphan: true

liulab_llms-2026.11.0/.github/workflows/release.yml

@@ -0,0 +1,72 @@
+# Publishing to PyPI.
+#
+# Before the first release, PyPI needs a trusted publisher for this repository, this
+# workflow filename and the environment named below. That step is outside the repo, so
+# `init-repo` hands you the checklist rather than leaving a workflow that looks ready and
+# is not. There is no API token here, and there must never be one.
+#
+# Two jobs on purpose. Only `publish` holds the OIDC token that PyPI trusts, and it runs no
+# code from this repository — it downloads what `build` made and hands it over. A build
+# step and a publishing credential in one job means every build dependency can reach that
+# credential.
+#
+# A repo that does not publish deletes this file; `init-repo` does that for you.
+name: release
+
+on:
+  # NEVER a trigger that pushing `v0.0.0` can fire — a `push:` with no branch filter,
+  # `create`, or a `tags:` filter that admits it. `init-repo` pushes `v0.0.0` on a repo's
+  # first day so the version does not read as if a release already happened, and any of
+  # those would fire a PyPI publish right then, from a repo nobody has finished naming.
+  # Publishing a GitHub Release is a deliberate act by a person, so that is the trigger.
+  # This paragraph is the advice and conformance rule `release-trigger` is the enforcement;
+  # they say one thing, so they change together.
+  release:
+    types: [published]
+  # For a release whose publish failed on something outside the code — a missing trusted
+  # publisher, a PyPI outage. Choose the tag when you run it.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # hatch-vcs reads the newest tag, and a shallow clone has none, so without this
+          # the release would be built and published as a dev version.
+          fetch-depth: 0
+      - uses: prefix-dev/setup-pixi@v0.10.2
+        with:
+          locked: true
+      # The same task the `build` job in `ci.yml` runs, so what is published was built the
+      # way every pull request already proved.
+      - run: pixi run build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Name this environment in the PyPI trusted publisher too, if you set one there. Add
+    # required reviewers to it to put a person between a published Release and PyPI.
+    environment:
+      name: pypi
+    permissions:
+      # OIDC: GitHub mints a short-lived token, PyPI checks it came from this repository
+      # and this workflow. This is the only permission the job has.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      # PyPA's own pointer, which is what their trusted-publishing guide tells you to use:
+      # it moves with security fixes to the publishing action. `dist/` is its default.
+      - uses: pypa/gh-action-pypi-publish@release/v1

liulab_llms-2026.11.0/.gitignore

@@ -0,0 +1,27 @@
+.pixi/
+# Build output: `site/` is the docs, `dist/` the wheel. `.cache/` is mkdocs' download cache,
+# which mkdocstrings fills with fetched inventories. mkdocs writes a `.gitignore` holding `*`
+# inside it, so it already hides itself — named here anyway, because a rule this repo relies
+# on should not live in a file a dependency happens to generate.
+site/
+.cache/
+dist/
+build/
+__pycache__/
+*.egg-info/
+.coverage
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.DS_Store
+
+# Agent products. Never a blanket `/.claude/`: the skill symlinks under `.claude/skills/`
+# and `.agents/skills/` are TRACKED, because `init-repo` has to be discoverable the instant
+# you clone — before anyone could run the thing that runs installers. So this names the two
+# machine-local files inside `.claude/` and nothing else.
+.claude/settings.local.json
+.claude/worktrees/
+# Installer output, from `python skills/install.py --target codex|gemini`. Nobody's clone
+# needs another machine's copy.
+/.codex/
+/.gemini/

liulab_llms-2026.11.0/.markdownlint-cli2.yaml

@@ -0,0 +1,35 @@
+# markdownlint reads structure; vale reads language. Both are steps of `check-static`.
+#
+# There is deliberately no `ignores:` list. It used to exist only to mirror a second list
+# of excluded paths kept elsewhere, and two lists that must agree are a drift waiting to
+# happen. Every markdown file in the repo is linted, agent-facing ones included.
+#
+# `gitignore: true` is not that list coming back: it delegates to the one exclusion list
+# the repo already has, so `.pixi/`, `site/`, `dist/` and `build/` are skipped without
+# anything new to keep in sync. It is load-bearing — without it the glob below walks
+# `.pixi/envs/`, finds 376 markdown files shipped inside node_modules and reports 5010
+# issues in other people's READMEs.
+gitignore: true
+
+# The glob lives here rather than on the pixi task line so that the file set does not
+# depend on whether the task shell expands `**` before markdownlint-cli2 sees it.
+globs:
+  - "**/*.md"
+
+config:
+  default: true
+  # Scoped, not disabled. A hard tab in prose is an accident; inside a fenced block it is the
+  # content — `docs/research/` quotes a tab-indented record verbatim, the reason `Lab.Jargon`,
+  # `Lab.Readability` and the agent-docs table already exempt it.
+  MD010:
+    code_blocks: false
+  # The formatter owns line length in code and nothing owns it in prose. Wrapping is a
+  # matter of taste, and tables and long links routinely exceed any limit, so MD013 would
+  # fire on every one of them.
+  MD013: false
+  # Scoped, not disabled. A Keep a Changelog file gives every release the same section
+  # names, so `### Added` recurs once per release by design and the default fails a
+  # correct changelog on its SECOND release. `siblings_only` still fails one release
+  # repeating its own section, which is the duplicate that is a real mistake.
+  MD024:
+    siblings_only: true

liulab_llms-2026.11.0/.vale.ini

@@ -0,0 +1,54 @@
+# Rules live in styles/Lab/, tracked — so `styles/` is not in .gitignore.
+#
+# EVERY RULE IS NAMED IN EVERY SECTION. Vale's `*` matches `/`, so sections overlap and
+# per-rule settings accumulate, later sections winning. An omitted rule keeps whatever an
+# earlier section said, which once left ADRs checked by nothing on green CI. Broad section
+# first. Each [tool.liulab.agent-docs] key appears verbatim in one header below; conformance
+# rule 3 pairs them by substring. The caps are explained in docs/agents/writing.md.
+
+StylesPath = styles
+MinAlertLevel = error
+
+# 1. Human-facing: the published site. Uncapped.
+[{README.md,CHANGELOG.md,docs/**/*.md}]
+BasedOnStyles = Lab
+Lab.Jargon = YES
+Lab.Readability = YES
+Lab.LengthDoc = NO
+Lab.LengthAdr = NO
+
+# 2. Agent-facing: word budget only. GLOSSARY.md is not here — see section 5.
+[{AGENTS.md,docs/agents/**/*.md,skills/**/SKILL.md}]
+BasedOnStyles = Lab
+Lab.Jargon = NO
+Lab.Readability = NO
+Lab.LengthDoc = YES
+Lab.LengthAdr = NO
+
+# 3. Decision records: the tighter cap.
+[docs/adr/**/*.md]
+BasedOnStyles = Lab
+Lab.Jargon = NO
+Lab.Readability = NO
+Lab.LengthDoc = NO
+Lab.LengthAdr = YES
+
+# 4. Research notes: uncapped, and exempt from jargon because a note quotes what it argues
+# against — the note defining the jargon map lists every banned phrase as evidence.
+[docs/research/**/*.md]
+BasedOnStyles = Lab
+Lab.Jargon = NO
+Lab.Readability = NO
+Lab.LengthDoc = NO
+Lab.LengthAdr = NO
+
+# 5. The glossary: no file cap. It grows one term at a time and never shrinks, so a file-level
+# word count measures the size of the domain, not the quality of the writing. Conformance caps
+# each entry at 200 words instead — the unit that matches how the file grows. Last because it
+# is the narrowest pattern here, and the later section wins.
+[GLOSSARY.md]
+BasedOnStyles = Lab
+Lab.Jargon = NO
+Lab.Readability = NO
+Lab.LengthDoc = NO
+Lab.LengthAdr = NO

liulab_llms-2026.11.0/AGENTS.md

@@ -0,0 +1,132 @@
+# liulab-llms
+
+Lab repos call language models through one lab gateway, which holds the provider keys,
+caches every response for the whole lab, and refuses a call that would cross its meter's
+ceiling. This package is the client for it, the gateway itself under the `gateway` extra,
+and an engine for model work over many units. seqforge is the first user, not the only one.
+Distribution name **`liulab-llms`**, import name **`labllm`**.
+
+Easy to get wrong: the cache key is the hash of the request form `labllm.wire` builds, so
+nothing that labels a call (meter, tag, person, repo, ceiling) may enter the form. The plain
+install never imports LiteLLM; a test pins it.
+
+## Restraint
+
+Generalizable, lightweight, uncustomized — in that order, and ahead of thorough.
+
+Every gate, lint rule, cap and check is paid by everyone who works here afterwards. They
+arrive one at a time, each reasonable alone, and nothing measures the sum. So before adding
+one:
+
+- **Does it generalize?** A rule shaped by one situation belongs where that situation is.
+  Evidence that it helps there is not evidence about here.
+- **What is the total?** Count what someone must already satisfy before writing any code.
+- **Would a narrower rule do?** Prefer narrowing to forbidding a legitimate practice.
+
+**A measurement outranks a hypothesis.** When a rule is shown to fire on correct work, that
+is evidence; a defect it might also catch is not. Declining a rule, or removing one that
+misfires, is as much a contribution as adding one.
+
+## Toolchain
+
+- **pixi** is the only supported toolchain. Never bare pip, uv, or conda. `pyproject.toml`
+  is the single source of truth for dependencies, environments, and tasks.
+- **Python 3.13**, declared by `requires-python` and the pixi pin. Write it anywhere else — a
+  ruff target, a pyright version — and `conformance` holds that copy to the floor.
+- **hatchling + hatch-vcs**. The version comes from the newest git tag, CalVer
+  `vYYYY.M.PATCH`. Never hand-edit a version.
+- Platforms: `osx-arm64` and `linux-64`.
+
+## Layout
+
+```text
+src/labllm/       the package: client.py, wire.py (request form, cache key), testing.py,
+                  engine.py, state.py (state file), reviews.py, server/ (the gateway)
+tests/            pytest; test_call_layer.py runs against every gateway in conftest.py
+docs/             the published site; docs/adr/ and docs/agents/ are agent-facing
+skills/           repo-local agent skills; `python skills/install.py --help`
+scripts/check.sh  the gate runner
+GLOSSARY.md       the glossary — the words this repo uses
+```
+
+## Gates
+
+`pixi run check` must be green before you commit. It is `check-static` plus `test`:
+
+| Step | Tool |
+| --- | --- |
+| `lint`, `fmt-check` | ruff |
+| `typecheck` | pyright, `standard` mode, plus annotated parameters outside `tests/` |
+| `vale`, `markdownlint` | the writing rules |
+| `conformance` | the repo still matches the template's rules |
+| `test` | pytest |
+
+`check.sh` runs every step and reports **all** failures, not just the first — so read to the
+bottom before fixing anything. The docs build is not part of `check`; it needs its own pixi
+environment and runs as its own CI job.
+
+Work on a branch and merge through a pull request: `pull_request` tests the merge commit,
+while a push to `main` tests it only once it has landed.
+
+Four traps in the gate:
+
+- **`--doctest-modules` runs every `Examples` block in `src/` as a test.** An example that
+  downloads, shells out or needs a large file wants `# doctest: +SKIP`, and the marker covers
+  only the example it sits on.
+- **`filterwarnings = ["error"]`.** Each tolerated warning gets a targeted entry in
+  `pyproject.toml` with a comment saying why. Never a blanket ignore.
+- **`src/` is collected**, so every module is imported at test time. Keep a heavy import
+  inside the method body that needs it, not at module scope.
+- **A substring of `--help` output is not a substring of the help.** Typer prints it through
+  rich, which styles the first dash of an option on its own, so `--version` is several spans
+  and not one string. Colour is off under `ssh` and on in CI; reproduce CI with
+  `FORCE_COLOR=1`, and strip the styling before you assert.
+
+## Writing rules
+
+Three rules, all enforced by `vale`: be concise; agent-facing documents have word caps;
+human-facing prose avoids jargon and stays readable. Read `docs/agents/writing.md` before
+writing either kind — the caps are lower than you expect, and this file is subject to one.
+
+### Comments and docstrings are short
+
+Nothing checks these, so the rule is on you. A docstring says what a thing does and what it
+promises. A comment says why a line is surprising. Neither is a notebook.
+
+**Do not record:**
+
+- **Measurements.** Sizes, row counts, timings, percentages, entry totals. They were true
+  once, on one machine, against one release. A number in a comment is wrong by the next
+  release and nothing checks it.
+- **The environment.** Hostnames, absolute paths, package versions, which host something ran
+  on, what a tool printed that day.
+- **Implementation detail a reader can see.** Restating the code below in prose, or narrating
+  how the current version happens to work inside.
+- **History.** What a previous version did, what was tried, which ticket decided it, what the
+  alternative was.
+
+Where a fact genuinely has to survive, it has a home that is checked. A comment is the one
+place that holds none of them accountable, which is why it is the wrong place:
+
+| The fact | Where it lives |
+| --- | --- |
+| What the code does | a test pins it |
+| A decision and its trade-off | an ADR |
+| Vocabulary | `GLOSSARY.md` |
+| What is still open | an issue |
+| A measurement | nowhere — delete it |
+
+Keep a docstring to its contract — arguments, return, what it raises, one example if the
+example earns its keep. Say the surprising thing in one sentence and stop.
+
+## Read next
+
+| When | Read |
+| --- | --- |
+| Before changing code | `GLOSSARY.md`, then any ADR covering the area |
+| Before changing the wire or a gateway | `docs/adr/0001-the-call-layers-wire.md`, `tests/harness.py` |
+| Writing anything | `docs/agents/writing.md` |
+
+The issue tracker, triage labels and domain docs are the lab defaults, the page `/lab-setup`
+points every agent at. A page of this repo's own under `docs/agents/` overrides only that one
+default, so write one only where this repo differs.

liulab_llms-2026.11.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+Every change worth knowing about, newest first. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version numbers are CalVer tags
+of the form `vYYYY.M.PATCH`, and the tag is where the version comes from — nothing here
+sets one.
+
+## [Unreleased]
+
+## [2026.11.0] - 2026-11-09
+
+The first release.
+
+### Added
+
+- The lab gateway, under the `gateway` extra: one service that holds the provider keys, sends
+  every model call, keeps every attempt in PostgreSQL and replays any request it has answered
+  before at no cost.
+- The engine: declare a unit kind as one plain function, run a pass over many units from your
+  own command, stop cleanly at a ceiling, and resume by running the same command again.
+- Off-peak-only passes, which send DeepSeek calls only in its half-price hours.
+- The call layer: open a meter with a dollar ceiling and make blocking chat and Jev calls through
+  the lab gateway, with `labllm.testing.FakeGateway` standing in for it in tests.
+- The review queue and reviews: list the units a person must look at, and save a person's
+  answer or drop to a file per kind that the repo commits to git.
+- The gateway keeps every caller under each provider's rate limits, waiting rather than
+  refusing, and tries a busy provider again for a few minutes. Each reply says how many
+  attempts it took.

liulab_llms-2026.11.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

liulab_llms-2026.11.0/GLOSSARY.md

@@ -0,0 +1,159 @@
+# Glossary
+
+The words for model calls through the lab gateway, and for the work run over many units.
+
+## Glossary
+
+### Ceiling
+
+A meter's limit in dollars, required and with no default. The gateway refuses a call whose
+largest possible cost (estimated input plus the full output allowance), added to what the
+meter has spent and holds for calls in flight, would cross it. A cache hit never counts.
+_Avoid_: budget, cap, limit
+
+### Dropped
+
+An ending a person's review gives: the unit is taken out of the work, with a note giving the
+reason. No answer is kept. Like an answer from a review, it holds until the unit's inputs tag
+changes.
+_Avoid_: skipped, excluded
+
+### Exchange
+
+One attempt at a provider, retries each their own, recorded whole in the gateway's record:
+the request, the response or error, usage, cost, and the person, repo, meter and tag. A cache
+hit adds an exchange with no bodies.
+_Avoid_: transcript, log entry
+
+### Gateway
+
+The lab's one service that sends every model call: it holds the provider keys, keeps the
+record, replays any request it has answered, and enforces each meter's ceiling. A call
+identical to one in flight waits for it, so a request is paid once. `Gateway` is also the
+library's client for it.
+_Avoid_: proxy
+
+### Held
+
+A unit whose inputs are not there yet: its kind's loader raised `Held`, and the reason is
+recorded. Not an ending, so it leaves the unit's current answer as it was.
+_Avoid_: skipped, pending
+
+### Inputs tag
+
+A string the repo's loader returns with a unit's inputs, stamped on its answer. The engine
+only compares it, so the repo chooses how fine it is.
+_Avoid_: hash, checksum
+
+### Meter
+
+A group of calls under one ceiling, with its own identity on the gateway. Its label is for
+people, so two meters with one label never share a ceiling. A pass opens one meter.
+_Avoid_: session, budget
+
+### Off-peak only
+
+A meter and pass setting, off by default. Its calls go to a provider only outside the peak
+hours of the model's price table entry: in peak the gateway answers with the time peak ends,
+and the call waits and is sent again. New calls stop a set margin before peak starts. A cache
+hit is answered at once, and a model with no off-peak hours is unaffected.
+_Avoid_: night mode, discount mode
+
+### Pass
+
+One run of a unit kind over the keys it is given, in that order, under one meter. It records
+each unit's outcome and returns counts per ending. Rerunning the same command starts a new
+pass whose finished calls replay free, which is how a stopped pass resumes.
+_Avoid_: run, batch, job, round
+
+### Rate limit
+
+A provider's limit, set in the gateway's settings for all callers together: requests a
+second, input tokens a second, or calls at once, for the provider or for one of its models.
+A per-minute limit is entered as its per-second rate. A call over one waits; none is refused.
+_Avoid_: quota, throttle, ceiling
+
+### Record
+
+The gateway's one table of every exchange, which is also its response cache: the cache
+entry for a request is its first successful exchange not retired. A bad entry is retired by
+hand and stays in the record. Each meter's spend is rebuilt from it after a restart.
+_Avoid_: log, transcript, cache table
+
+### Refused
+
+An ending: the kind's code refused the unit with a message. No answer is kept.
+_Avoid_: rejected, failed
+
+### Request form
+
+What decides a call's answer, as `labllm.wire` builds it: provider, exact model name,
+settings, the messages or Jev's description and questions, and the output schema. Its hash
+is the cache key; labels, the tag and the ceiling are never in it.
+_Avoid_: payload, prompt
+
+### Review
+
+One person's recorded decision on one unit: an answer, or a drop. It is a line in its kind's
+review file, made for the unit's inputs tag of that moment, and outranks the models' answer
+while the tag is unchanged. Of a unit's reviews for one tag, the latest-timed wins.
+_Avoid_: correction, label, annotation
+
+### Review queue
+
+Every unit whose current answer is unsettled or refused, in key order: the units a person
+must look at.
+_Avoid_: inbox, backlog, triage list
+
+### Settled
+
+An ending: the unit has an answer and every check passed, or a person overrode a failed check
+with a reason. Code alone may settle a unit, unless a check it recorded failed.
+_Avoid_: done, accepted
+
+### Stamp
+
+What produced an answer, recorded with it: the kind and its version, the model for each
+role, the inputs tag, the pass, and the calling repo's and liulab-llms's code versions.
+_Avoid_: provenance, metadata
+
+### Task
+
+One body of work's state: one SQLite file in a folder the calling command names, held by one
+process at a time. It keeps every pass and each unit's outcome, answer, stamp and check
+results per pass. Deleting the file is safe: rerunning rebuilds the models' answers from the
+cache.
+_Avoid_: project, database
+
+### Unfinished
+
+A unit that reached no ending in a pass: its kind's code raised an error, its answer did not
+fit the answer schema, or the pass stopped. The reason is recorded. Not an ending, so it
+leaves the unit's current answer as it was.
+_Avoid_: failed, errored
+
+### Unit
+
+One independent piece of work, named by a string key, such as one sequencing Series. Its
+current answer is its outcome in the latest pass that reached an ending, unless a review made
+for that outcome's inputs tag outranks it.
+_Avoid_: item, row, sample
+
+### Unit kind
+
+A repo's declaration of one kind of unit: a name, a hand-set version, roles, a loader, one
+plain function that does the work, an answer schema and answer checks.
+_Avoid_: step list, pipeline
+
+### Unsettled
+
+An ending: the unit has an answer that fits its schema, but a check failed. The answer is
+kept with each failed check's message.
+_Avoid_: doubtful, partial
+
+### Waiting call
+
+A call the gateway holds back for a rate limit or a provider's pause after overload. Waiting
+calls go first come, first served, holding nothing against their meter's ceiling. Waiting
+for a rate limit never ends a call; only a provider still failing after the retry budget does.
+_Avoid_: queued request, throttled call