convene 0.2.1: dash-free docs

pip install --upgrade convene

A documentation release. No behaviour change: the same 92 tests pass, and every call, flag and default is as it was in 0.2.0.

README

• A 20 second terminal demo at the top, recorded against real calls: install, one expert triaging three support tickets, then convene usage. The tape is reproducible with bash docs/demo/record.sh.
• The top of the page is now what it is, the demo, install, a quickstart that reproduces the demo, why it exists, and the measured claims with their build, date, sample size and method.
• Links are absolute, so the PyPI page no longer points at 404s for FINDINGS.md, LICENSE, CONTRIBUTING.md and ROADMAP.md.

Reworded CLI strings

Wording only, no change in what is printed when:

• convene usage header: convene usage, last 7d
• the empty-ledger hint and the cold-cache note
• the BudgetError message: budget reached: <budget>, with $X already spent in the last <window>.

Anything that matched on the old text with its em dash needs updating.

Docs

FINDINGS.md, CONTRIBUTING.md, ROADMAP.md and the issue templates read the same with the dashes rewritten. No measurement changed.

Packaging

• Changelog project URL, pointing at these release notes.
• The demo assets stay out of the sdist.

convene 0.2.0 — spend ledger and budgets

pip install --upgrade convene

Answers the two questions the flat log couldn't: how much has this expert cost
me this week, and stop before this batch passes $5.

Spend ledger

Every call and every live-session turn is recorded to
~/.convene/ledger.sqlite3. Prompts and responses are never stored — it is
an accounting record, not a transcript, so it stays safe to hand to someone who
shouldn't see the data that went through it.

convene usage --since 7d

  TAG           CALLS         COST    PER CALL    CACHED   AVG TIME
  badprompt         8      $0.1600    $0.02000        0%       0.0s
  goodprompt        6      $0.0240    $0.00400      100%       0.0s
  ----------------------------------------------------------------
  TOTAL            14      $0.1840    $0.01314       43%       0.0s

  note: 'badprompt' read a warm cache on only 0% of 8 calls...

The CACHED column is the one to act on. Those two experts differ 5x in cost
per call for exactly the reason FINDINGS.md §2 describes, and
the note tells you which lever to pull.

Budgets

Rolling ceilings, optionally scoped to one expert, checked before the
subprocess is spawned:

export CONVENE_BUDGET_USD=5        # no code needed
convene run --expert triage --in tickets.jsonl --budget-usd 2

add_budget(Budget(1.00, "12h", tag="triage"))

A budget stop halts a batch with one message instead of marking every remaining
row failed.

What it is not: the ceiling is checked against spend already recorded, so
with 12 calls in flight it can be crossed by up to 12 calls' worth. It's a
guard rail, not a fence — use max_budget_usd for a hard per-call limit, which
the CLI enforces server-side. Documented in three places and pinned by a test
so it can't be quietly mis-sold. Reservation accounting is roadmap item #1.

Note for existing users

0.2.0 starts writing ~/.convene/ledger.sqlite3, which 0.1.0 did not. It holds
accounting only. CONVENE_LEDGER=0 turns it off.

No API changes — 0.1.0 code runs unmodified, and the claude_cli.py shim still
returns the predecessor's field names.

Verification

92 offline tests, 6 live against Claude Code 2.1.237. The ledger was checked
under the concurrency the library defaults to: 24 threads × 25 writes, zero
lost rows, zero errors, and reads stay consistent during continuous writes so
convene usage is safe to run mid-batch. In-place 0.1.0 → 0.2.0 upgrade
verified.

convene 0.1.0

First release. pip install convene

Runs Claude Code headlessly as a local inference layer — the first-party
claude binary, stripped from a coding agent back to an inference endpoint,
with the things you need around the call to run real workloads on it.

What's in it

• Experts — named specialists (system prompt, model, effort, schema,
  budget) in a TOML registry, with a lint that catches prompts too short to
  cache or interpolated per call.
• Sessions — durable (--session-id/--resume, survives process death)
  and hot (--input-format stream-json), plus a pool.
• convene doctor — tells you which account is about to be billed, and
  probes for the --bare default flip that would break subscription auth.
• convene run — resumable JSONL batches with cache warm-up.
• convene bench — re-runs every measurement the docs claim.

What the measurements changed

Three widely repeated limits turned out to be wrong, and each one was a
feature. Full tables with sample sizes in FINDINGS.md.

• Prompt caching works on this path and is worth ~9.5x on a stable
  4.4k-token system prompt, across separate processes. That inverts the usual
  advice: a long, stable system prompt is the cheap one. It's why the expert
  registry exists.
• Concurrency runs to at least n=20 with zero rate-limit errors — about
  10x serial throughput, not the "keep it near 5" folklore.
• Multi-turn works two ways, and the hot process was 4.3x cheaper than
  resume on the same three-turn conversation.

Scope

Local and first-party only: no HTTP server, no OpenAI-compatible endpoint, no
credential forwarding, no implicit API-key fallback. CI enforces the first and
last of those rather than merely documenting them. See
Scope in the README for why.

Zero dependencies, Python 3.11+, MIT.