offpeak 0.2.0__tar.gz → 0.2.2__tar.gz

offpeak-0.2.2/.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Docs
+
+# Builds the mkdocs site and deploys it to GitHub Pages. Pages is configured
+# with build_type=workflow, so this workflow is the only publisher — there is
+# no gh-pages branch to keep in sync.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "src/**"
+      - "mkdocs.yml"
+      - "mkdocs_hooks.py"
+      - "SPEC.md"
+      - "pyproject.toml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install -e ".[docs]"
+      - name: Build
+        run: mkdocs build --strict
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

{offpeak-0.2.0 → offpeak-0.2.2}/.github/workflows/nightly.yml

@@ -20,8 +20,11 @@ on:
 permissions:
   contents: write
 
+# Everything that pushes board-data shares one queue. Two workflows writing
+# different files on the same branch still race at the push, and a rejected
+# push loses a night's mark.
 concurrency:
-  group: night-board
+  group: board-data
   cancel-in-progress: false
 
 jobs:
@@ -54,10 +57,20 @@ jobs:
           echo "mode=$mode" >> "$GITHUB_OUTPUT"
           echo "running the $mode pass"
 
+      - name: Install US-zone data source
+        # gridstatus is an Action-only dependency: the SDK does not need it and
+        # the generator degrades to GB-only without it.
+        run: pip install "gridstatus>=0.36"
+
       - name: Generate
+        # EIA_API_KEY is optional: absent, the US carbon columns are recorded
+        # unavailable and every other leg runs exactly as before.
+        env:
+          EIA_API_KEY: ${{ secrets.EIA_API_KEY }}
         run: |
           python tools/night_report.py \
             --mode "${{ steps.pick.outputs.mode }}" \
+            --us-zones \
             --outdir board/nightly
 
       - name: Commit to board-data

offpeak-0.2.2/.github/workflows/settle.yml

@@ -0,0 +1,56 @@
+name: Settled runs
+
+# Publishes the receipts in `receipts/` onto the board-data branch as
+# `nightly/SETTLED.md`. Manual only: a settlement is a deliberate act, and the
+# ledger should move when someone decides it moves, not on every push.
+#
+# board-data is written by CI and never by hand — the same rule the night board
+# follows, for the same reason: main is protected and a bot push there would be
+# rejected, and a ledger anyone can hand-edit is not a ledger.
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+# Shared with the night board: everything that pushes board-data queues here.
+concurrency:
+  group: board-data
+  cancel-in-progress: false
+
+jobs:
+  settle:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the generator and the receipts (main)
+        uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Check out the ledger (board-data)
+        uses: actions/checkout@v7
+        with:
+          ref: board-data
+          path: board
+
+      - name: Render
+        run: |
+          python tools/settle_report.py \
+            --receipts receipts \
+            --outdir board/nightly
+
+      - name: Commit to board-data
+        working-directory: board
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add nightly
+          if git diff --staged --quiet; then
+            echo "nothing changed — the ledger already says this"
+            exit 0
+          fi
+          git commit -m "board: settled runs $(date -u +%Y-%m-%d)"
+          git push

{offpeak-0.2.0 → offpeak-0.2.2}/.gitignore

@@ -23,3 +23,7 @@ htmlcov/
 # Claude Code (personal)
 .claude/settings.local.json
 HANDOFF.md
+
+# Docs build output; docs/spec.md is copied from SPEC.md at build time
+site/
+docs/spec.md

{offpeak-0.2.0 → offpeak-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: offpeak
-Version: 0.2.0
+Version: 0.2.2
 Summary: Deadline-priced inference: give AI jobs a deadline and run them on the cheapest venue — provider batch tiers (−50%) today. Same model, same tokens, a different hour.
 Project-URL: Homepage, https://github.com/offpeak-ai/offpeak
 Project-URL: Repository, https://github.com/offpeak-ai/offpeak
@@ -31,6 +31,12 @@ Requires-Dist: build; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Requires-Dist: twine; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material<10,>=9.5; extra == 'docs'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Provides-Extra: groq
+Requires-Dist: groq>=0.11; extra == 'groq'
 Provides-Extra: openai
 Requires-Dist: openai>=1.50; extra == 'openai'
 Description-Content-Type: text/markdown
@@ -66,10 +72,12 @@ tokens    12,410,332 in · 3,104,551 out
 list      $27.93
 paid      $14.02
 captured  $13.91 (49.8%)
-prices    snapshot 2026-08 — override via offpeak.prices
+prices    snapshot 2026-08-21 — override via offpeak.prices
 ───────────────────────────────────────────────
 ```
 
+**[Documentation](https://offpeak-ai.github.io/offpeak/)** · [Quickstart](https://offpeak-ai.github.io/offpeak/quickstart/) · [Spec](https://offpeak-ai.github.io/offpeak/spec/) · [Roadmap](https://offpeak-ai.github.io/offpeak/roadmap/)
+
 ## What it does
 
 - **Know the price before you spend it.** `quote(jobs, deadline=...)` prices a run against the published sheets with no API calls and no key — list versus batch, per venue, plus what the wait is worth.
@@ -103,18 +111,21 @@ jobs      5000 across 1 venue(s)
 deadline  2026-08-21 21:11 PDT (24.0h out)
 tokens    4,000,000 in · 1,000,000 out
 
-  openai:batch      5000 job(s)  list $1.00  batch $0.50  save $0.50 (50.0%)
+  openai:batch      5000 job(s)  list $2.00  batch $1.00  save $1.00 (50.0%)
 
-list      $1.00   (run now, synchronously)
-batch     $0.50   (run by the deadline)
-save      $0.50 (50.0%)
+list      $2.00   (run now, synchronously)
+batch     $1.00   (run by the deadline)
+save      $1.00 (50.0%)
+risk      deadline is inside the 24h batch window — the SLA rests on the sync fallback, which pays list
 basis     input explicit; output explicit
-prices    snapshot 2026-08 — estimate only, not a bill
+prices    snapshot 2026-08-21 — estimate only, not a bill
 ───────────────────────────────────────────────
 ```
 
 From Python, `offpeak.quote(jobs, deadline="06:00")` takes the same jobs you would pass to `run()`. Token counts come from the job where it knows them (`metadata={"input_tokens": ..., "output_tokens": ...}`, or `max_tokens` as an output ceiling) and are a labeled chars/4 estimate where it does not — every figure reports its provenance in `basis`, and a quote with no output signal is marked a **floor**, not an estimate.
 
+If you do know roughly what the model will write, say so and get a priced number instead — `quote(jobs, deadline=..., assumed_output_ratio=0.25)`, or `metadata={"expected_output_tokens": 300}` on a single job. Those quotes are marked **EST**, distinct from a floor. Both are opt-in: absent one, `offpeak` assumes nothing on your behalf.
+
 ## Deadlines
 
 Deadlines are how software says "this can wait" — the full semantics live in [SPEC.md](SPEC.md).
@@ -152,13 +163,15 @@ import offpeak
 offpeak.prices.register_price("my-fine-tune", input_per_m=4.0, output_per_m=16.0)
 ```
 
-Unknown models settle with `cost = None` rather than a guess.
+Unknown models settle with `cost = None` rather than a guess. The sheet also carries what the venues charge for *urgency* — `get_fast_price()`, `urgency_spread()` — and flags list prices that are promotional, with the date and the price they decay to: `promo_decay("gpt-5.6-sol")` is `(1.25, 1.5)` after 2026-11-21.
 
 ## What this is (and the roadmap)
 
 `offpeak` is the open client and spec for a simple claim: **intelligence has a time value**. A large share of AI work — embeddings, evals, backfills, report generation, overnight agents — has no human waiting on it, and the venues already price that patience at −50%. This library is the missing workflow.
 
-The **[night board](https://github.com/offpeak-ai/offpeak/blob/board-data/nightly/BOARD.md)** marks the same claim against open grid data every night — power and carbon peak/off-peak spreads, alongside the 2.0x token spread the batch tiers already publish.
+The token side is wider than the headline discount. Patience is priced at −50% — a 2.0x spread — and haste is priced too: hold the model and venue constant and `gpt-5.6-sol` costs **$8.00 / $40.00** per 1M on OpenAI's fast tier against **$2.00 / $10.00** on its batch tier, a **4x intra-venue urgency spread** for the hour alone ([source](https://developers.openai.com/api/docs/pricing); sol's standard rate is promotional at least through 2026-11-21, and both tiers are defined off it, so the ratio outlives the prices). It is data, not prose: `offpeak.prices.urgency_spread("gpt-5.6-sol")` returns `4.0`.
+
+The **[night board](https://github.com/offpeak-ai/offpeak/blob/board-data/nightly/BOARD.md)** marks the same claim against open grid data every night — GB power and carbon plus CAISO SP15 and ERCOT Houston peak/off-peak spreads, alongside the published token spreads. ERCOT Houston marked 3.94x on the night of 2026-08-20; a venue charges 4x for the same impatience.
 
 The roadmap follows the same interface upward: more venues (Google batch, spot capacity, off-peak windows on your own GPUs), queue-latency forecasting instead of a fixed risk buffer, portfolio placement across venues, energy- and carbon-aware scheduling with per-job receipts. The venue interface (`offpeak.Venue`) is deliberately the extension point — a venue is anywhere deferred work can run.
 

{offpeak-0.2.0 → offpeak-0.2.2}/README.md

@@ -29,10 +29,12 @@ tokens    12,410,332 in · 3,104,551 out
 list      $27.93
 paid      $14.02
 captured  $13.91 (49.8%)
-prices    snapshot 2026-08 — override via offpeak.prices
+prices    snapshot 2026-08-21 — override via offpeak.prices
 ───────────────────────────────────────────────
 ```
 
+**[Documentation](https://offpeak-ai.github.io/offpeak/)** · [Quickstart](https://offpeak-ai.github.io/offpeak/quickstart/) · [Spec](https://offpeak-ai.github.io/offpeak/spec/) · [Roadmap](https://offpeak-ai.github.io/offpeak/roadmap/)
+
 ## What it does
 
 - **Know the price before you spend it.** `quote(jobs, deadline=...)` prices a run against the published sheets with no API calls and no key — list versus batch, per venue, plus what the wait is worth.
@@ -66,18 +68,21 @@ jobs      5000 across 1 venue(s)
 deadline  2026-08-21 21:11 PDT (24.0h out)
 tokens    4,000,000 in · 1,000,000 out
 
-  openai:batch      5000 job(s)  list $1.00  batch $0.50  save $0.50 (50.0%)
+  openai:batch      5000 job(s)  list $2.00  batch $1.00  save $1.00 (50.0%)
 
-list      $1.00   (run now, synchronously)
-batch     $0.50   (run by the deadline)
-save      $0.50 (50.0%)
+list      $2.00   (run now, synchronously)
+batch     $1.00   (run by the deadline)
+save      $1.00 (50.0%)
+risk      deadline is inside the 24h batch window — the SLA rests on the sync fallback, which pays list
 basis     input explicit; output explicit
-prices    snapshot 2026-08 — estimate only, not a bill
+prices    snapshot 2026-08-21 — estimate only, not a bill
 ───────────────────────────────────────────────
 ```
 
 From Python, `offpeak.quote(jobs, deadline="06:00")` takes the same jobs you would pass to `run()`. Token counts come from the job where it knows them (`metadata={"input_tokens": ..., "output_tokens": ...}`, or `max_tokens` as an output ceiling) and are a labeled chars/4 estimate where it does not — every figure reports its provenance in `basis`, and a quote with no output signal is marked a **floor**, not an estimate.
 
+If you do know roughly what the model will write, say so and get a priced number instead — `quote(jobs, deadline=..., assumed_output_ratio=0.25)`, or `metadata={"expected_output_tokens": 300}` on a single job. Those quotes are marked **EST**, distinct from a floor. Both are opt-in: absent one, `offpeak` assumes nothing on your behalf.
+
 ## Deadlines
 
 Deadlines are how software says "this can wait" — the full semantics live in [SPEC.md](SPEC.md).
@@ -115,13 +120,15 @@ import offpeak
 offpeak.prices.register_price("my-fine-tune", input_per_m=4.0, output_per_m=16.0)
 ```
 
-Unknown models settle with `cost = None` rather than a guess.
+Unknown models settle with `cost = None` rather than a guess. The sheet also carries what the venues charge for *urgency* — `get_fast_price()`, `urgency_spread()` — and flags list prices that are promotional, with the date and the price they decay to: `promo_decay("gpt-5.6-sol")` is `(1.25, 1.5)` after 2026-11-21.
 
 ## What this is (and the roadmap)
 
 `offpeak` is the open client and spec for a simple claim: **intelligence has a time value**. A large share of AI work — embeddings, evals, backfills, report generation, overnight agents — has no human waiting on it, and the venues already price that patience at −50%. This library is the missing workflow.
 
-The **[night board](https://github.com/offpeak-ai/offpeak/blob/board-data/nightly/BOARD.md)** marks the same claim against open grid data every night — power and carbon peak/off-peak spreads, alongside the 2.0x token spread the batch tiers already publish.
+The token side is wider than the headline discount. Patience is priced at −50% — a 2.0x spread — and haste is priced too: hold the model and venue constant and `gpt-5.6-sol` costs **$8.00 / $40.00** per 1M on OpenAI's fast tier against **$2.00 / $10.00** on its batch tier, a **4x intra-venue urgency spread** for the hour alone ([source](https://developers.openai.com/api/docs/pricing); sol's standard rate is promotional at least through 2026-11-21, and both tiers are defined off it, so the ratio outlives the prices). It is data, not prose: `offpeak.prices.urgency_spread("gpt-5.6-sol")` returns `4.0`.
+
+The **[night board](https://github.com/offpeak-ai/offpeak/blob/board-data/nightly/BOARD.md)** marks the same claim against open grid data every night — GB power and carbon plus CAISO SP15 and ERCOT Houston peak/off-peak spreads, alongside the published token spreads. ERCOT Houston marked 3.94x on the night of 2026-08-20; a venue charges 4x for the same impatience.
 
 The roadmap follows the same interface upward: more venues (Google batch, spot capacity, off-peak windows on your own GPUs), queue-latency forecasting instead of a fixed risk buffer, portfolio placement across venues, energy- and carbon-aware scheduling with per-job receipts. The venue interface (`offpeak.Venue`) is deliberately the extension point — a venue is anywhere deferred work can run.
 

offpeak-0.2.2/docs/index.md

@@ -0,0 +1,39 @@
+# offpeak
+
+**Deadline-priced inference.** Same model, same tokens, a different hour.
+
+A large share of AI work — embeddings, evals, backfills, report generation,
+overnight agents — has no human waiting on it. The providers already price that
+patience: OpenAI and Anthropic both publish their batch tiers at **50% of
+list**. `offpeak` is the workflow that collects the difference.
+
+```python
+import offpeak
+
+jobs = [offpeak.job("claude-haiku-4-5", f"Summarize:\n\n{d}") for d in docs]
+
+print(offpeak.quote(jobs, deadline="06:00"))   # what is the wait worth?
+results = offpeak.run(jobs, deadline="06:00")  # collect it
+print(offpeak.receipt(results))                # what it actually cost
+```
+
+- **[Quickstart](quickstart.md)** — install, quote, run, read the receipt.
+- **[The night board](night-board.md)** — the same claim, marked nightly against open grid data.
+- **[Spec](spec.md)** — deadline semantics, statuses, receipts.
+- **[API reference](reference.md)** — every public symbol.
+- **[Roadmap](roadmap.md)** — what exists, what does not, and what is being built.
+
+## What it guarantees
+
+**One `Result` per job, always.** Provider failures at submit, poll, cancel or
+sync are captured, not raised. Affected jobs take the sync fallback where the
+deadline still allows it, and otherwise return failed with the provider's
+message attached. Exceptions are reserved for programming errors — a deadline
+in the past, or a model no venue supports.
+
+**Your keys, your perimeter.** `offpeak` talks straight to the providers with
+your own credentials. There is no proxy and no third party in the data path.
+
+**Receipts are arithmetic, not estimates.** Every figure traces to a published
+price sheet, and a model that is not on one settles as `None` rather than a
+guess.

offpeak-0.2.2/docs/night-board.md

@@ -0,0 +1,123 @@
+# The night board
+
+`offpeak` rests on a claim: **intelligence has a time value.** The token side of
+that claim is already settled, and it is wider than the headline discount.
+
+- **Patience is priced at −50%.** OpenAI and Anthropic both publish batch tiers
+  at half of list: a flat **2.0x** spread for work that can wait.
+- **Haste is priced too.** Hold the model and the venue constant and read the
+  same sheet across its urgency tiers: `gpt-5.6-sol` is **$8.00 / $40.00** per
+  1M tokens on OpenAI's fast tier against **$2.00 / $10.00** on its batch tier
+  — a **4x intra-venue urgency spread**, on both legs, for the hour alone.
+  Source: [developers.openai.com/api/docs/pricing](https://developers.openai.com/api/docs/pricing).
+
+!!! note "The promo caveat"
+    `gpt-5.6-sol`'s standard rate is promotional — the sheet says it runs *at
+    least* through **2026-11-21**, after which list is $5/$30. Fast and batch
+    are both defined off that list (2x and 0.5x), so the promo moves the
+    dollars and leaves the ratio: **the 4x is the durable figure, the prices
+    are the perishable ones.** Both are in the SDK rather than in prose —
+    `offpeak.prices.urgency_spread("gpt-5.6-sol")` returns `4.0`, and
+    `promo_decay()` returns the step-up the date will bring.
+
+The night board marks the same claim against the other side of the trade: the
+grid the compute runs on. Every night it records what power and carbon actually
+did between the evening peak and the small hours, from open, keyless sources.
+The grid's spread is not published anywhere — it has to be observed — and on the
+night of 2026-08-20 the ERCOT Houston hub marked **3.94x** between its evening
+peak and the trough that followed, against the 4x a venue charges for the same
+hour of impatience.
+
+The two sides of the grid do not move together, which is the point of marking
+both. On 2026-08-18 and 08-19, CAISO's carbon ran **cleaner at the evening peak
+than in the small hours** — spreads of 0.76x and 0.73x — because the sun that
+serves the California evening has set by midnight. Cheap hours are not
+automatically clean hours, and a board that only recorded price would have
+implied otherwise.
+
+**[→ Read the board](https://github.com/offpeak-ai/offpeak/blob/board-data/nightly/BOARD.md)**
+
+## How it works
+
+Two passes over the same night, run by
+[a scheduled workflow](https://github.com/offpeak-ai/offpeak/blob/main/.github/workflows/nightly.yml):
+
+| Pass | When | What it records |
+|---|---|---|
+| `quote` | 19:00Z | The night ahead — carbon **forecast**, day-ahead power |
+| `mark` | 06:30Z | The night just finished — carbon **actuals** |
+
+A night runs **16:00Z–07:00Z**: it opens with the 17:00 BST evening peak and
+closes after the 00–05 BST trough, so one span carries both windows the board
+compares.
+
+Output lands on the
+[`board-data` branch](https://github.com/offpeak-ai/offpeak/tree/board-data) —
+`nightly/BOARD.md` plus the raw JSON per night — because `main` is protected and
+would reject a nightly bot push.
+
+## Settled runs are a different ledger
+
+`BOARD.md` observes; it spends nothing at any venue. Runs that actually
+executed and actually billed go in `nightly/SETTLED.md` on the same branch,
+written by
+[`tools/settle_report.py`](https://github.com/offpeak-ai/offpeak/blob/main/tools/settle_report.py)
+from the receipts in
+[`receipts/`](https://github.com/offpeak-ai/offpeak/tree/main/receipts) — never
+by hand — and published by a manual workflow, because a settlement is a
+deliberate act.
+
+Every settled row carries its **scale**, and the column is not decoration. A
+few dozen jobs proving the mechanics end to end and a production book are both
+real settlements and are not the same evidence. A ledger that lets a reader
+confuse them is doing marketing rather than accounting, so the scale is printed
+before the money is.
+
+## Sources
+
+- **Carbon** — [NESO carbon intensity](https://api.carbonintensity.org.uk),
+  GB, keyless.
+- **Power, GB** — [Octopus Agile](https://api.octopus.energy) day-ahead unit
+  rates, GB region C, keyless.
+- **Power, US** — CAISO SP15 and ERCOT Houston day-ahead hourly, via
+  [gridstatus](https://github.com/gridstatus/gridstatus), keyless.
+- **Carbon, US** — [EIA-930](https://www.eia.gov/electricity/gridmonitor/)
+  hourly generation by fuel for the CAISO and ERCOT balancing authorities,
+  through the EIA Hourly Grid Monitor. Needs a free API key; without one the
+  column records itself unavailable and nothing else changes.
+- **Tokens** — the published price sheets, not a measurement:
+  [OpenAI](https://developers.openai.com/api/docs/pricing) and
+  [Anthropic](https://platform.claude.com/docs/en/about-claude/pricing).
+
+All are public and free. The board costs nothing to run and spends nothing at
+any venue.
+
+## Honest limits
+
+- **Four zones, unevenly covered.** GB carbon and GB power are half-hourly and
+  complete. CAISO SP15 and ERCOT Houston are **day-ahead hourly** prices, not
+  settled real-time ones.
+- **US carbon is derived, GB carbon is measured.** NESO publishes an intensity;
+  EIA does not. The US columns are computed from EIA-930's hourly generation
+  mix times EIA's own CO2 coefficients and fleet heat rates — every input
+  published, the product an estimate, and marked `"basis": "derived"` in the
+  record so it is never confused with a measurement. It counts generation, not
+  consumption: imports and the carbon already stored in a battery are outside
+  what the method can see, and the share of generation EIA files under "other"
+  is reported per night rather than averaged in.
+- **EIA runs about a day behind.** The 06:30Z mark usually lands before EIA has
+  published the night it is marking, so the US carbon columns are often empty
+  at first sight and fill in on a later re-mark. A column that is not there yet
+  is recorded as unavailable, never as zero.
+- **The token column is published, not observed.** The 2.0x and the 4x are read
+  off price sheets; only the grid columns are measurements. A published number
+  and a marked one are different kinds of claim, and the board should not blur
+  them.
+- **Observation, not advice.** The board records what the grid did. It does not
+  forecast, and `offpeak` does not currently schedule against it — the SDK
+  routes on published token prices alone.
+- **Carbon actuals lag** roughly two hours. The 06:30Z mark clears the 00–05 BST
+  trough comfortably; the tail of the night can still be sparse.
+- **A dead source costs its column, not the run.** Legs degrade independently,
+  and a night where both sources are down is recorded as unavailable rather than
+  guessed at.

offpeak-0.2.2/docs/quickstart.md

@@ -0,0 +1,152 @@
+# Quickstart
+
+## Install
+
+```bash
+pip install "offpeak[all]"        # OpenAI + Anthropic venues
+pip install "offpeak[anthropic]"  # or just one
+pip install "offpeak[openai]"
+```
+
+The core has zero dependencies; provider SDKs load only through the extras.
+Venues read the standard environment variables (`OPENAI_API_KEY`,
+`ANTHROPIC_API_KEY`), or take a configured client:
+`OpenAIBatch(client=my_client)`.
+
+## 1. Quote — before you spend anything
+
+`quote()` makes **no API calls and needs no key**. It prices your jobs against
+the bundled sheet: list versus batch, per venue.
+
+```bash
+python -m offpeak quote --model gpt-5.6-luna --input-tokens 800 --output-tokens 200 --jobs 5000
+```
+
+```
+OFFPEAK QUOTE ─────────────────────────────────
+jobs      5000 across 1 venue(s)
+deadline  2026-08-21 21:11 PDT (24.0h out)
+tokens    4,000,000 in · 1,000,000 out
+
+  openai:batch      5000 job(s)  list $2.00  batch $1.00  save $1.00 (50.0%)
+
+list      $2.00   (run now, synchronously)
+batch     $1.00   (run by the deadline)
+save      $1.00 (50.0%)
+risk      deadline is inside the 24h batch window — the SLA rests on the sync fallback, which pays list
+basis     input explicit; output explicit
+prices    snapshot 2026-08-21 — estimate only, not a bill
+───────────────────────────────────────────────
+```
+
+From Python, the same jobs you would pass to `run()`:
+
+```python
+q = offpeak.quote(jobs, deadline="06:00")
+print(q.spread_usd, q.spread_pct)
+```
+
+!!! warning "Quotes that omit output are marked a floor"
+    Output costs more than input on every model on the sheet. If a job carries
+    no output-token signal, `quote()` prices its output at **zero** and labels
+    the whole quote a `FLOOR` — a stated floor is safer than an invented
+    number. Give it `max_tokens`, or explicit counts:
+
+    ```python
+    offpeak.job("claude-haiku-4-5", prompt, max_tokens=512)
+    offpeak.Job(model=..., messages=[...],
+                metadata={"input_tokens": 800, "output_tokens": 200})
+    ```
+
+    `Quote.basis` reports the provenance of every figure.
+
+!!! warning "Reasoning models spend the ceiling before they speak"
+    On models that reason before answering — OpenAI's gpt-5 family, the
+    o-series — `max_tokens` caps **reasoning plus visible output**, and the
+    reasoning goes first. Set it too low and the job bills a full ceiling of
+    reasoning tokens and returns an empty string: a `Result` that is
+    technically ok, costs real money, and says nothing.
+
+    This is not hypothetical. A real batch here ran 24 jobs at
+    `max_tokens=16`, billed 374 output tokens, and returned 24 empty strings.
+    Give a reasoning model room — hundreds of tokens, not dozens — and price
+    the ceiling you actually set, which is what `quote()` does.
+
+    `offpeak` sends the ceiling under whichever name the venue wants
+    (`max_completion_tokens` where the model demands it), but it cannot make a
+    ceiling large enough to answer in.
+
+### If you know roughly what it will write
+
+A floor is honest but not always useful. When you do have a sense of the output
+size, say so — and the quote prices it, marked `EST` rather than `FLOOR`:
+
+```python
+# Across the run: assume each job writes a quarter of what it reads.
+offpeak.quote(jobs, deadline="06:00", assumed_output_ratio=0.25)
+
+# Or per job, which wins over a ratio and over max_tokens:
+offpeak.Job(model=..., messages=[...],
+            metadata={"expected_output_tokens": 300})
+```
+
+```
+EST       5000 job(s) priced on an assumed output size, not a measured one
+          the assumption is yours; the bill moves with what the model actually writes
+```
+
+Both are opt-in. Without one, nothing is assumed on your behalf: the default
+stays the floor. The two marks mean different things and a quote can carry both
+— `FLOOR` is understated by construction, `EST` can land either side of the
+bill. `Quote.is_floor` and `Quote.is_estimated` are the same distinction in
+code, and a ratio applies only to jobs with no signal of their own, so explicit
+counts and `max_tokens` are never overridden by it.
+
+## 2. Run — against a deadline
+
+```python
+results = offpeak.run(jobs, deadline="06:00")
+```
+
+Each job goes to the batch tier of a venue that supports its model. `offpeak`
+polls until the work lands. If the batch has not completed by the time the
+remaining window shrinks to the risk buffer, it cancels and re-runs the
+stragglers synchronously at list price — you stated a deadline, and it is met.
+
+Deadlines accept `"06:00"` (next occurrence), `"6h"`, `"90m"`, a `datetime`, a
+`timedelta`, seconds, or an ISO 8601 string.
+
+## 3. Read the receipt
+
+```python
+print(offpeak.receipt(results))
+```
+
+```
+OFFPEAK SETTLEMENT ────────────────────────────
+jobs      5000 (5000 ok, 120 sync fallback, 0 failed)
+sla       5000/5000 met
+venues    anthropic:batch 3000 · openai:batch 2000
+tokens    41,000,000 in · 3,200,000 out
+list      $2,469.00
+paid      $1,234.50
+captured  $1,234.50 (50.0%)
+left      $29.63 on the table (120 job(s) missed the batch tier)
+prices    snapshot 2026-08-21 — override via offpeak.prices
+───────────────────────────────────────────────
+```
+
+`left on the table` is what the sync fallback gave up by missing the batch
+tier. Per-job receipts render the same way — `print(results[0].receipt)` — with
+sub-cent precision, so a small run reports what it cost rather than `$0.00`.
+
+## Prices
+
+The bundled sheet is a dated snapshot. Providers move prices; override at
+runtime rather than waiting for a release:
+
+```python
+offpeak.prices.register_price("my-fine-tune", input_per_m=4.0, output_per_m=16.0)
+```
+
+Unknown models settle as `None`, never a guess.

offpeak-0.2.2/docs/reference.md

@@ -0,0 +1,48 @@
+# API reference
+
+Everything below is exported from the package root: `offpeak.run`,
+`offpeak.Job`, and so on.
+
+## Running work
+
+::: offpeak.run
+
+::: offpeak.quote
+
+::: offpeak.receipt
+
+::: offpeak.job
+
+## Types
+
+::: offpeak.Job
+
+::: offpeak.Result
+
+::: offpeak.Receipt
+
+::: offpeak.Status
+
+::: offpeak.Settlement
+
+::: offpeak.Quote
+
+::: offpeak.VenueQuote
+
+## Deadlines
+
+::: offpeak.parse_deadline
+
+::: offpeak.seconds_until
+
+## Venues
+
+::: offpeak.Venue
+
+::: offpeak.BatchState
+
+::: offpeak.default_venues
+
+## Prices
+
+::: offpeak.prices