offpeak 0.1.2__tar.gz → 0.2.0__tar.gz

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

@@ -0,0 +1,74 @@
+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: Generate
+        run: |
+          python tools/night_report.py \
+            --mode "${{ steps.pick.outputs.mode }}" \
+            --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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: offpeak
-Version: 0.1.2
+Version: 0.2.0
 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
@@ -72,6 +72,7 @@ prices    snapshot 2026-08 — override via offpeak.prices
 
 ## 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 +89,32 @@ 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 $1.00  batch $0.50  save $0.50 (50.0%)
+
+list      $1.00   (run now, synchronously)
+batch     $0.50   (run by the deadline)
+save      $0.50 (50.0%)
+basis     input explicit; output explicit
+prices    snapshot 2026-08 — 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.
+
 ## Deadlines
 
 Deadlines are how software says "this can wait" — the full semantics live in [SPEC.md](SPEC.md).
@@ -131,6 +158,8 @@ Unknown models settle with `cost = None` rather than a guess.
 
 `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 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.0}/README.md

@@ -35,6 +35,7 @@ prices    snapshot 2026-08 — override via offpeak.prices
 
 ## 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 +52,32 @@ 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 $1.00  batch $0.50  save $0.50 (50.0%)
+
+list      $1.00   (run now, synchronously)
+batch     $0.50   (run by the deadline)
+save      $0.50 (50.0%)
+basis     input explicit; output explicit
+prices    snapshot 2026-08 — 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.
+
 ## Deadlines
 
 Deadlines are how software says "this can wait" — the full semantics live in [SPEC.md](SPEC.md).
@@ -94,6 +121,8 @@ Unknown models settle with `cost = None` rather than a guess.
 
 `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 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.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "offpeak"
-version = "0.1.2"
+version = "0.2.0"
 description = "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."
 readme = "README.md"
 license = "Apache-2.0"

{offpeak-0.1.2 → offpeak-0.2.0}/src/offpeak/__init__.py

@@ -14,24 +14,30 @@ from . import prices
 from .client import Settlement, default_venues, receipt, run
 from .deadline import parse_deadline, seconds_until
 from .job import Job, Receipt, Result, Status, job
+from .prices import format_usd
+from .quote import Quote, VenueQuote, quote
 from .venues.base import BatchState, Venue
 
-__version__ = "0.1.2"
+__version__ = "0.2.0"
 
 __all__ = [
     "job",
     "run",
+    "quote",
     "receipt",
     "Job",
     "Result",
     "Receipt",
     "Settlement",
+    "Quote",
+    "VenueQuote",
     "Status",
     "Venue",
     "BatchState",
     "parse_deadline",
     "seconds_until",
     "default_venues",
+    "format_usd",
     "prices",
     "__version__",
 ]

offpeak-0.2.0/src/offpeak/__main__.py

@@ -0,0 +1,62 @@
+"""``python -m offpeak`` — the quote desk, from a terminal.
+
+    python -m offpeak quote --model gpt-5.6-luna --input-tokens 800 \\
+        --output-tokens 200 --jobs 5000
+
+Prices against the bundled sheet only. No API calls, no key required.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .job import Job
+from .quote import quote
+
+
+def _quote_cmd(a: argparse.Namespace) -> int:
+    jobs = [
+        Job(
+            model=a.model,
+            messages=[],
+            metadata={"input_tokens": a.input_tokens, "output_tokens": a.output_tokens},
+        )
+        for _ in range(a.jobs)
+    ]
+    try:
+        print(quote(jobs, a.deadline))
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="offpeak", description=__doc__.splitlines()[0])
+    ap.add_argument("--version", action="version", version=f"offpeak {__version__}")
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    q = sub.add_parser("quote", help="price a batch of jobs against a deadline")
+    q.add_argument("--model", required=True, help="e.g. gpt-5.6-luna, claude-haiku-4-5")
+    q.add_argument("--input-tokens", type=int, required=True, help="per job")
+    q.add_argument("--output-tokens", type=int, required=True, help="per job")
+    q.add_argument("--jobs", type=int, default=1, help="how many jobs (default 1)")
+    q.add_argument(
+        "--deadline",
+        default="24h",
+        help='when it must be done: "24h", "06:00", an ISO timestamp (default 24h)',
+    )
+    q.set_defaults(func=_quote_cmd)
+
+    a = ap.parse_args(argv)
+    if a.jobs < 1:
+        ap.error("--jobs must be at least 1")
+    if a.input_tokens < 0 or a.output_tokens < 0:
+        ap.error("token counts cannot be negative")
+    return a.func(a)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{offpeak-0.1.2 → offpeak-0.2.0}/src/offpeak/client.py

@@ -8,14 +8,13 @@ own-GPU off-peak windows, and carbon-aware scheduling on the same interface.
 
 from __future__ import annotations
 
-import math
 import time
 from dataclasses import dataclass, field
 from datetime import datetime
 
 from .deadline import parse_deadline, seconds_until
 from .job import Job, Receipt, Result, Status
-from .prices import PRICE_SHEET_DATE
+from .prices import BATCH_DISCOUNT, PRICE_SHEET_DATE, format_usd
 from .venues.base import Venue
 
 __all__ = ["run", "receipt", "Settlement", "default_venues"]
@@ -205,14 +204,7 @@ def _run_sync(venue: Venue, j: Job) -> Result:
         return Result(job=j, error=str(exc))
 
 
-def _usd(amount: float) -> str:
-    """Money for humans: 2dp once there are cents to show, more significant
-    digits below that so a sub-cent run does not settle as a column of $0.00."""
-    if amount == 0:
-        return "0.00"
-    if abs(amount) >= 0.005:
-        return f"{amount:,.2f}"
-    return f"{amount:,.{-math.floor(math.log10(abs(amount))) + 2}f}"
+_usd = format_usd  # kept as a private alias; the canonical home is prices
 
 
 @dataclass
@@ -228,6 +220,7 @@ class Settlement:
     output_tokens: int = 0
     list_usd: float = 0.0
     paid_usd: float = 0.0
+    left_on_table_usd: float = 0.0
     unpriced: int = 0
     by_venue: dict = field(default_factory=dict)
 
@@ -253,6 +246,11 @@ class Settlement:
             f"captured  ${_usd(self.captured_usd)} ({self.captured_pct:.1f}%)",
             f"prices    snapshot {PRICE_SHEET_DATE} — override via offpeak.prices",
         ]
+        if self.fell_back:
+            lines.append(
+                f"left      ${_usd(self.left_on_table_usd)} on the table "
+                f"({self.fell_back} job(s) missed the batch tier)"
+            )
         if self.unpriced:
             lines.append(f"note      {self.unpriced} job(s) had no price sheet entry")
         lines.append("─" * 47)
@@ -281,4 +279,7 @@ def receipt(results: list[Result]) -> Settlement:
         else:
             settlement.list_usd += r.list_usd
             settlement.paid_usd += r.paid_usd
+            if r.fell_back:
+                # The spread this job would have captured had the batch held.
+                settlement.left_on_table_usd += r.list_usd * (1 - BATCH_DISCOUNT)
     return settlement

{offpeak-0.1.2 → offpeak-0.2.0}/src/offpeak/deadline.py

@@ -8,7 +8,8 @@ Accepted forms:
 - ``"06:00"`` — the next occurrence of that wall-clock time (today if it is
   still ahead, otherwise tomorrow). This is the canonical overnight form.
 - ``"6h"``, ``"90m"``, ``"45s"``, ``"2d"`` — relative to now.
-- ISO 8601 strings — ``"2026-08-21T06:00:00-07:00"``.
+- ISO 8601 strings — ``"2026-08-21T06:00:00-07:00"``, including the
+  ``Z`` (UTC) suffix on every supported Python.
 
 All deadlines resolve to an aware :class:`datetime.datetime`. See SPEC.md for
 the full semantics.
@@ -76,8 +77,13 @@ def _parse(value: object, now: datetime) -> datetime:
             if candidate <= now:
                 candidate += timedelta(days=1)
             return candidate
+        text = value.strip()
+        # Python 3.11 taught fromisoformat to read a trailing "Z"; 3.10 did not,
+        # and Z is the ISO form most timestamps in the wild actually use.
+        if text.endswith(("Z", "z")):
+            text = f"{text[:-1]}+00:00"
         try:
-            parsed = datetime.fromisoformat(value.strip())
+            parsed = datetime.fromisoformat(text)
         except ValueError:
             raise ValueError(f"unrecognized deadline: {value!r}") from None
         return parsed if parsed.tzinfo else parsed.astimezone()

{offpeak-0.1.2 → offpeak-0.2.0}/src/offpeak/job.py

@@ -7,7 +7,7 @@ from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum
 
-from .prices import batch_cost_usd, list_cost_usd
+from .prices import batch_cost_usd, format_usd, list_cost_usd
 
 __all__ = ["Job", "Result", "Receipt", "Status", "job"]
 
@@ -93,6 +93,21 @@ class Receipt:
             return None
         return self.list_usd - self.paid_usd
 
+    def __str__(self) -> str:
+        """One line, in money you can actually read.
+
+        The float properties above stay floats — this is the rendering, so a
+        sub-cent job reports what it cost instead of $0.00.
+        """
+        where = f"{self.venue} {self.model}"
+        if self.fell_back:
+            where += " (sync fallback)"
+        return (
+            f"{where}: {self.input_tokens:,} in · {self.output_tokens:,} out · "
+            f"list ${format_usd(self.list_usd)} · paid ${format_usd(self.paid_usd)} · "
+            f"captured ${format_usd(self.spread_usd)}"
+        )
+
 
 @dataclass
 class Result:

{offpeak-0.1.2 → offpeak-0.2.0}/src/offpeak/prices.py

@@ -12,9 +12,12 @@ list, which is what :data:`BATCH_DISCOUNT` encodes.
 
 from __future__ import annotations
 
+import math
+
 __all__ = [
     "PRICE_SHEET_DATE",
     "BATCH_DISCOUNT",
+    "format_usd",
     "register_price",
     "get_price",
     "list_cost_usd",
@@ -77,3 +80,19 @@ def list_cost_usd(model: str, input_tokens: int, output_tokens: int) -> float |
 def batch_cost_usd(model: str, input_tokens: int, output_tokens: int) -> float | None:
     cost = list_cost_usd(model, input_tokens, output_tokens)
     return None if cost is None else cost * BATCH_DISCOUNT
+
+
+def format_usd(amount: float | None) -> str:
+    """Money for humans: 2dp once there are cents to show, more significant
+    digits below that so a sub-cent job does not settle as a column of $0.00.
+
+    ``None`` (an unpriced model) renders as an em dash, never as zero — a price
+    we do not know is not a price of nothing.
+    """
+    if amount is None:
+        return "—"
+    if amount == 0:
+        return "0.00"
+    if abs(amount) >= 0.005:
+        return f"{amount:,.2f}"
+    return f"{amount:,.{-math.floor(math.log10(abs(amount))) + 2}f}"