offpeak 0.1.2__tar.gz → 0.2.1__tar.gz

{offpeak-0.1.2 → offpeak-0.2.1}/.github/workflows/ci.yml

@@ -20,6 +20,6 @@ jobs:
       - name: Install
         run: pip install -e ".[dev]"
       - name: Lint
-        run: ruff check src tests
+        run: ruff check src tests tools
       - name: Test
         run: pytest

offpeak-0.2.1/.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.1/.github/workflows/nightly.yml

@@ -0,0 +1,80 @@
+name: Night board
+
+# Quotes at dusk, marks at dawn. Output is committed to the `board-data`
+# branch, not to main: main is protected (PR + four required checks), so a
+# nightly bot push there would be rejected every night.
+
+on:
+  schedule:
+    - cron: "0 19 * * *"   # quote — the night ahead, carbon forecast
+    - cron: "30 6 * * *"   # mark  — the night just finished, carbon actuals
+  workflow_dispatch:
+    inputs:
+      mode:
+        description: "Which pass to run"
+        required: true
+        default: quote
+        type: choice
+        options: [quote, mark]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: night-board
+  cancel-in-progress: false
+
+jobs:
+  board:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the generator (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: Pick the pass
+        id: pick
+        run: |
+          if [ -n "${{ inputs.mode }}" ]; then
+            mode="${{ inputs.mode }}"
+          elif [ "${{ github.event.schedule }}" = "0 19 * * *" ]; then
+            mode=quote
+          else
+            mode=mark
+          fi
+          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
+        run: |
+          python tools/night_report.py \
+            --mode "${{ steps.pick.outputs.mode }}" \
+            --us-zones \
+            --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 — not committing an empty night"
+            exit 0
+          fi
+          git commit -m "board: ${{ steps.pick.outputs.mode }} $(date -u +%Y-%m-%d)"
+          git push

{offpeak-0.1.2 → offpeak-0.2.1}/.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.1.2 → offpeak-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: offpeak
-Version: 0.1.2
+Version: 0.2.1
 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,12 +72,15 @@ 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.
 - **One argument, not a workflow.** `run(jobs, deadline=...)` handles batching, submission, polling, collection, and result matching across providers.
 - **Deadlines are guarded, not hoped for.** If a batch hasn't landed by the time the remaining window shrinks to a risk buffer, `offpeak` cancels and re-runs the stragglers synchronously at list price. You state the deadline; it gets met.
 - **Every run settles a receipt.** List cost, paid cost, captured spread — arithmetic against public price sheets, not estimates.
@@ -88,6 +97,35 @@ pip install "offpeak[openai]"
 
 Venues use the standard environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`), or pass a configured client: `OpenAIBatch(client=my_client)`.
 
+## The free quote
+
+What is the wait worth? Ask before you spend anything — `quote()` makes no API calls and needs no key.
+
+```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, `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).
@@ -125,12 +163,16 @@ 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 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.
 
 A hosted desk that does the forecasting, cross-venue portfolio scheduling, and SLA insurance at fleet scale — payloads never leaving your perimeter — is being built by the same team. The SDK and the deadline spec stay open, Apache-2.0.

{offpeak-0.1.2 → offpeak-0.2.1}/README.md

@@ -29,12 +29,15 @@ 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.
 - **One argument, not a workflow.** `run(jobs, deadline=...)` handles batching, submission, polling, collection, and result matching across providers.
 - **Deadlines are guarded, not hoped for.** If a batch hasn't landed by the time the remaining window shrinks to a risk buffer, `offpeak` cancels and re-runs the stragglers synchronously at list price. You state the deadline; it gets met.
 - **Every run settles a receipt.** List cost, paid cost, captured spread — arithmetic against public price sheets, not estimates.
@@ -51,6 +54,35 @@ pip install "offpeak[openai]"
 
 Venues use the standard environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`), or pass a configured client: `OpenAIBatch(client=my_client)`.
 
+## The free quote
+
+What is the wait worth? Ask before you spend anything — `quote()` makes no API calls and needs no key.
+
+```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, `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).
@@ -88,12 +120,16 @@ 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 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.
 
 A hosted desk that does the forecasting, cross-venue portfolio scheduling, and SLA insurance at fleet scale — payloads never leaving your perimeter — is being built by the same team. The SDK and the deadline spec stay open, Apache-2.0.

offpeak-0.2.1/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.1/docs/night-board.md

@@ -0,0 +1,83 @@
+# 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.
+
+**[→ 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.
+
+## 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.
+- **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, two of them thin.** 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, and they are power only — no US carbon leg yet.
+- **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.1/docs/quickstart.md

@@ -0,0 +1,136 @@
+# 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.
+
+### 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.1/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