offpeak 0.2.0__tar.gz → 0.2.1__tar.gz

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

@@ -54,10 +54,16 @@ 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
         run: |
           python tools/night_report.py \
             --mode "${{ steps.pick.outputs.mode }}" \
+            --us-zones \
             --outdir board/nightly
 
       - name: Commit to board-data

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: offpeak
-Version: 0.2.0
+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,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.1}/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.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

offpeak-0.2.1/docs/roadmap.md

@@ -0,0 +1,54 @@
+# Roadmap
+
+What exists, what does not, and what is being built. This page is meant to be
+checkable — if something here is not true yet, it says so.
+
+## What exists today
+
+- **`run(jobs, deadline=...)`** across the OpenAI and Anthropic batch tiers,
+  with a sync fallback that protects the deadline.
+- **`quote(jobs, deadline=...)`** — pre-trade pricing with no API calls.
+- **Receipts and settlements** — list, paid, captured spread, and what a
+  fallback left on the table, as arithmetic against published price sheets.
+- **A `Venue` interface** — the extension point. A venue is anywhere deferred
+  work can run.
+- **[The night board](night-board.md)** — GB power and carbon, marked nightly.
+
+## What does not exist yet
+
+Stated plainly, because a roadmap that reads like a feature list is a
+misleading one:
+
+- **No queue-latency forecasting.** Deadline risk is a fixed buffer, not a
+  prediction. `offpeak` does not know how long a given venue's queue is; it
+  watches the clock and falls back.
+- **No cross-venue portfolio placement.** Jobs route to the first venue that
+  supports the model, not to the cheapest or fastest across a portfolio.
+- **No carbon-aware scheduling.** The night board observes the grid; the
+  scheduler does not read it.
+- **No venues beyond the two batch tiers.** Google batch, spot capacity, and
+  off-peak windows on your own GPUs are interface-shaped but unwritten. A
+  Groq batch driver exists in the tree but is **untested against the live
+  API** — it is opt-in, excluded from the `all` extra, and not in
+  `default_venues()`.
+
+## The hosted desk
+
+A hosted desk that does the forecasting, cross-venue portfolio scheduling, and
+SLA insurance at fleet scale — with payloads never leaving your perimeter — is
+being built by the same team.
+
+The intended seam is the one already in the library: a desk would be selected
+per run, alongside the venues you already pass, so that moving from local
+scheduling to hosted scheduling is a keyword argument rather than a rewrite.
+
+!!! note "Not implemented"
+    That parameter does not exist in the public API today, and nothing in this
+    release accepts it. It is described here so the shape of the plan is
+    legible — not as something you can call. The SDK and the deadline spec stay
+    open, Apache-2.0, either way.
+
+## The spec
+
+Deadline semantics are versioned separately in [SPEC.md](spec.md), so a second
+implementation can be written against them. Spec changes start as issues.

offpeak-0.2.1/mkdocs.yml

@@ -0,0 +1,56 @@
+site_name: offpeak
+site_description: Deadline-priced inference — same model, same tokens, a different hour.
+site_url: https://offpeak-ai.github.io/offpeak/
+repo_url: https://github.com/offpeak-ai/offpeak
+repo_name: offpeak-ai/offpeak
+edit_uri: edit/main/docs/
+
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: black
+      accent: indigo
+      toggle: {icon: material/weather-night, name: Switch to dark mode}
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      accent: indigo
+      toggle: {icon: material/weather-sunny, name: Switch to light mode}
+  features:
+    - navigation.sections
+    - navigation.top
+    - content.code.copy
+
+nav:
+  - Home: index.md
+  - Quickstart: quickstart.md
+  - The night board: night-board.md
+  - Spec: spec.md
+  - API reference: reference.md
+  - Roadmap: roadmap.md
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+          options:
+            show_source: true
+            show_root_heading: true
+            heading_level: 3
+            docstring_style: sphinx
+            members_order: source
+
+# SPEC.md lives at the repo root (it is the artifact people link to); this
+# copies it in at build time rather than keeping a second copy that drifts.
+hooks:
+  - mkdocs_hooks.py
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - toc: {permalink: true}

offpeak-0.2.1/mkdocs_hooks.py

@@ -0,0 +1,21 @@
+"""Build hook: mirror root-level docs into the site without duplicating them.
+
+SPEC.md is the artifact people cite and link to, so it stays at the repo root.
+Copying it in at build time means the site renders the same file the repo
+serves, rather than a second copy that quietly drifts out of date.
+
+docs/spec.md is generated and gitignored — do not edit it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+
+
+def on_pre_build(config, **kwargs) -> None:
+    spec = ROOT / "SPEC.md"
+    if not spec.exists():  # pragma: no cover - repo always ships it
+        raise FileNotFoundError(f"SPEC.md missing at {spec}; the docs nav expects it")
+    (ROOT / "docs" / "spec.md").write_text(spec.read_text())