labkit

Imported from kmax-tech/labkit (AGENTS.md). Install upstream with npx skills add kmax-tech/labkit. Copyright stays with the author.

AGENTS.md — labkit

Entry file for any coding agent working in this repo (Claude Code reads it through the CLAUDE.md symlink). It holds only what an agent without the author's machine needs; everything else is linked.

What this is

labkit is the shared helper package of a research lab: run index, LLM backend, protocol checks and the gates around a run. Its claim:

labkit detects violations of explicitly encoded scientific intent across implementation, execution and reporting.

The chain is intent → explicit promise → code → run → reported number. Every check belongs to one of three tiers — guaranteed (exact, mechanical, silent on correct input), static evidence (warns, never blocks), agent audit (semantics). Never present a static check as proof of semantics. Contract and rationale: docs/promise-block.md.

Read first

Setup and tests

python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/pytest -q

The editor's type checker reads the same .venv ([tool.pyright] in pyproject.toml). Reading and debugging recipes (a test under pdb, a command's call tree or timeline): justfile (just lists them); in VS Code .vscode/launch.json. Before a commit: .venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/pyright — all three clean (docs/coding-style.md CODE-008 Run the linter and the type checker), and the suite green. The versioned hook .githooks/pre-commit runs all four and refuses the commit otherwise; turn it on once per clone with git config core.hooksPath .githooks. A release is one step: write the CHANGELOG.md entry, then just release X.Y.Z sets the version, commits through the hook and tags that commit — in this order the tag test (tests/test_release_tags.py) is never red; the push stays with the author.

The suite is self-contained: it passes in a fresh clone with an empty home directory (a shallow clone without tags skips the tag test; git fetch --tags origin brings them). One test skips everywhere for want of a requirements.lock (tests/test_runlog_env.py). usability stage stamps its probe from the package's own templates (since 0.78.0) and pins labkit at the release tag of the installed version on GitHub — until that tag is pushed the probe's pip install fails (--venv links an existing venv instead).

Rules

• stdlib only. dependencies = [] is deliberate; a lab helper that pulls packages in decides every experiment's environment. Dev tools go in the dev extra.
• Fail loud. No bare except, no silent skip. A malformed input raises with a sentence naming the field.
• One home per logic. The id alphabet lives in labkit/promises.py; other modules import it. A second use means moving code, not copying it.
• Every number-producing function gets a test. A gate that blocks gets a twin test: the correct variant must pass (no false blocker).
• Language. Code, identifiers, docstrings, docs in docs/, commit messages: English. Talk to the user, and write TODO.md entries, in German.
• Breaking changes, not legacy paths. Build for the current format; keep code clear and modular. Do not add or extend code that reads old formats. A format change is an announced break (CHANGELOG.md, "Breaking", naming the last version that reads the old format); old runs are reproduced with the repo's commit and its pinned labkit version. Existing legacy paths go in one Breaking release, not piecemeal (0.48.0 the id letters, 0.89.0 the legacy run state and the endpoint string).
• Order before features. Build what TODO.md puts next, nothing ahead of it: static-evidence checks wait for the benchmark pilot to show they are needed. Rollout to other repos, templates and the house doctrine is a separate task and out of reach here.
• One commit per step, the message says why. Do not push, tag or release; report what is ready to commit.

Not in this repo

The research thread (literature, paper plan, benchmark case list), the author's house rules (the German arbeitsstandard, seven rules on notes and the thread) and the dated incidents behind every rule live on the author's machine. The lab standard itself ships here (labkit/docs/standard.md, since 0.77.0). Where a docstring cites LAB-015 Preflight audit before freezing, that is a rule of this standard; where it cites a dated incident, that is the evidence; the code's own docstring states the rule it enforces.