offpeak 0.1.0__py3-none-any.whl

offpeak/__init__.py

@@ -0,0 +1,37 @@
+"""offpeak — deadline-priced inference.
+
+Same model, same tokens, a different hour. Give AI work a deadline and run it
+on the cheapest venue that keeps the SLA — provider batch tiers (−50%) today.
+
+    import offpeak
+
+    jobs = [offpeak.job("claude-haiku-4-5", f"Summarize:\\n\\n{d}") for d in docs]
+    results = offpeak.run(jobs, deadline="06:00")
+    print(offpeak.receipt(results))
+"""
+
+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 .venues.base import BatchState, Venue
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "job",
+    "run",
+    "receipt",
+    "Job",
+    "Result",
+    "Receipt",
+    "Settlement",
+    "Status",
+    "Venue",
+    "BatchState",
+    "parse_deadline",
+    "seconds_until",
+    "default_venues",
+    "prices",
+    "__version__",
+]

offpeak/client.py

@@ -0,0 +1,223 @@
+"""The v0 desk: portfolio-submit jobs to batch venues, watch the deadline,
+fall back to sync if the batch won't make it, settle a receipt.
+
+This is deliberately simple — deadline risk is a buffer, not a forecast. The
+hosted desk adds queue-latency forecasting, cross-venue portfolio placement,
+own-GPU off-peak windows, and carbon-aware scheduling on the same interface.
+"""
+
+from __future__ import annotations
+
+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 .venues.base import Venue
+
+__all__ = ["run", "receipt", "Settlement", "default_venues"]
+
+
+def default_venues() -> list[Venue]:
+    """Provider batch tiers, tried in order. SDKs import lazily on first use."""
+    from .venues.anthropic_batch import AnthropicBatch
+    from .venues.openai_batch import OpenAIBatch
+
+    return [AnthropicBatch(), OpenAIBatch()]
+
+
+def _usage_tokens(raw: object) -> tuple[int, int]:
+    if not isinstance(raw, dict):
+        return 0, 0
+    input_tokens = raw.get("input_tokens", raw.get("prompt_tokens", 0)) or 0
+    output_tokens = raw.get("output_tokens", raw.get("completion_tokens", 0)) or 0
+    return int(input_tokens), int(output_tokens)
+
+
+def _pick_venue(model: str, venues: list[Venue]) -> Venue:
+    for venue in venues:
+        if venue.supports(model):
+            return venue
+    known = ", ".join(v.name for v in venues)
+    raise ValueError(f"no venue supports model {model!r} (venues: {known})")
+
+
+def run(
+    jobs: Job | list[Job],
+    deadline: object,
+    *,
+    venues: list[Venue] | None = None,
+    fallback: str = "sync",
+    poll_interval: float | None = None,
+    risk_buffer: float | None = None,
+) -> list[Result]:
+    """Run *jobs* against *deadline* on the cheapest supporting venue.
+
+    Submits each job to its venue's batch tier, polls until everything lands,
+    and — if the batch has not completed by the time the remaining window
+    shrinks to ``risk_buffer`` seconds — cancels and re-runs the stragglers
+    synchronously at list price so the deadline is met (``fallback="sync"``,
+    the default; ``fallback="none"`` reports them failed instead).
+
+    Returns one :class:`Result` per job, in input order, each with a
+    :class:`Receipt`.
+    """
+    job_list = [jobs] if isinstance(jobs, Job) else list(jobs)
+    if not job_list:
+        return []
+    resolved = parse_deadline(deadline)
+    window = seconds_until(resolved)
+    if risk_buffer is None:
+        risk_buffer = max(60.0, min(600.0, 0.15 * window))
+    venue_list = venues if venues is not None else default_venues()
+
+    groups: dict[str, tuple[Venue, list[Job]]] = {}
+    for j in job_list:
+        venue = _pick_venue(j.model, venue_list)
+        groups.setdefault(venue.name, (venue, []))[1].append(j)
+
+    submitted_at = datetime.now().astimezone()
+    pending: dict[str, str] = {}  # venue name -> batch handle
+    for name, (venue, group_jobs) in groups.items():
+        pending[name] = venue.submit(group_jobs)
+        for j in group_jobs:
+            j.status = Status.SUBMITTED
+
+    collected: dict[str, Result] = {}
+    fell_back: set[str] = set()
+
+    while pending:
+        for name in list(pending):
+            venue, group_jobs = groups[name]
+            state = venue.status(pending[name])
+            if state.status == "completed":
+                collected.update(venue.collect(pending[name]))
+                del pending[name]
+            elif state.status in ("failed", "cancelled"):
+                del pending[name]  # jobs surface below as fallback or errors
+
+        remaining = seconds_until(resolved)
+        if not pending and not _missing(groups, collected):
+            break
+        if remaining <= risk_buffer or not pending:
+            for name in list(pending):
+                groups[name][0].cancel(pending.pop(name))
+            if fallback == "sync":
+                for j in _missing(groups, collected):
+                    result = groups[_venue_of(j, groups)][0].run_sync(j)
+                    collected[j.id] = result
+                    fell_back.add(j.id)
+            break
+        time.sleep(
+            poll_interval
+            if poll_interval is not None
+            else min(30.0, max(2.0, remaining / 50.0))
+        )
+
+    completed_at = datetime.now().astimezone()
+    results: list[Result] = []
+    for j in job_list:
+        result = collected.get(j.id)
+        if result is None:
+            result = Result(job=j, error="not returned by venue before the deadline")
+            j.status = Status.FAILED
+        else:
+            result.job = j
+            j.status = (
+                Status.FELL_BACK
+                if j.id in fell_back
+                else (Status.SUCCEEDED if result.ok else Status.FAILED)
+            )
+        input_tokens, output_tokens = _usage_tokens(result.raw)
+        result.receipt = Receipt(
+            venue=groups[_venue_of(j, groups)][0].name,
+            model=j.model,
+            deadline=resolved,
+            submitted_at=submitted_at,
+            completed_at=completed_at if result.error is None else None,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            fell_back=j.id in fell_back,
+        )
+        results.append(result)
+    return results
+
+
+def _venue_of(j: Job, groups: dict[str, tuple[Venue, list[Job]]]) -> str:
+    for name, (_, group_jobs) in groups.items():
+        if j in group_jobs:
+            return name
+    raise KeyError(j.id)
+
+
+def _missing(
+    groups: dict[str, tuple[Venue, list[Job]]], collected: dict[str, Result]
+) -> list[Job]:
+    return [j for _, (_, js) in groups.items() for j in js if j.id not in collected]
+
+
+@dataclass
+class Settlement:
+    """Aggregate receipt across a run."""
+
+    total: int = 0
+    ok: int = 0
+    sla_met: int = 0
+    fell_back: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    list_usd: float = 0.0
+    paid_usd: float = 0.0
+    unpriced: int = 0
+    by_venue: dict = field(default_factory=dict)
+
+    @property
+    def captured_usd(self) -> float:
+        return self.list_usd - self.paid_usd
+
+    @property
+    def captured_pct(self) -> float:
+        return 0.0 if not self.list_usd else 100.0 * self.captured_usd / self.list_usd
+
+    def __str__(self) -> str:
+        venues = " · ".join(f"{k} {v}" for k, v in sorted(self.by_venue.items()))
+        lines = [
+            "OFFPEAK SETTLEMENT " + "─" * 28,
+            f"jobs      {self.total} ({self.ok} ok, {self.fell_back} sync fallback)",
+            f"sla       {self.sla_met}/{self.total} met",
+            f"venues    {venues or '—'}",
+            f"tokens    {self.input_tokens:,} in · {self.output_tokens:,} out",
+            f"list      ${self.list_usd:,.2f}",
+            f"paid      ${self.paid_usd:,.2f}",
+            f"captured  ${self.captured_usd:,.2f} ({self.captured_pct:.1f}%)",
+            f"prices    snapshot {PRICE_SHEET_DATE} — override via offpeak.prices",
+        ]
+        if self.unpriced:
+            lines.append(f"note      {self.unpriced} job(s) had no price sheet entry")
+        lines.append("─" * 47)
+        return "\n".join(lines)
+
+
+def receipt(results: list[Result]) -> Settlement:
+    """Settle a run: aggregate per-job receipts into one :class:`Settlement`."""
+    settlement = Settlement()
+    for result in results:
+        settlement.total += 1
+        if result.ok:
+            settlement.ok += 1
+        r = result.receipt
+        if r is None:
+            continue
+        settlement.sla_met += int(r.sla_met)
+        settlement.fell_back += int(r.fell_back)
+        settlement.input_tokens += r.input_tokens
+        settlement.output_tokens += r.output_tokens
+        settlement.by_venue[r.venue] = settlement.by_venue.get(r.venue, 0) + 1
+        if r.list_usd is None or r.paid_usd is None:
+            settlement.unpriced += 1
+        else:
+            settlement.list_usd += r.list_usd
+            settlement.paid_usd += r.paid_usd
+    return settlement

offpeak/deadline.py

@@ -0,0 +1,84 @@
+"""Deadline parsing — how software says "this can wait".
+
+Accepted forms:
+
+- ``datetime`` — aware or naive; a naive datetime is assumed to be local time.
+- ``timedelta`` — relative to now.
+- ``int`` / ``float`` — seconds from now.
+- ``"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"``.
+
+All deadlines resolve to an aware :class:`datetime.datetime`. See SPEC.md for
+the full semantics.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta
+
+__all__ = ["parse_deadline", "seconds_until"]
+
+_REL = re.compile(
+    r"^\s*(\d+(?:\.\d+)?)\s*(s|secs?|seconds?|m|mins?|minutes?|h|hrs?|hours?|d|days?)\s*$",
+    re.IGNORECASE,
+)
+_WALL = re.compile(r"^\s*([01]?\d|2[0-3]):([0-5]\d)\s*$")
+_UNIT_SECONDS = {"s": 1.0, "m": 60.0, "h": 3600.0, "d": 86400.0}
+
+
+def _local_now() -> datetime:
+    return datetime.now().astimezone()
+
+
+def parse_deadline(value: object, *, now: datetime | None = None) -> datetime:
+    """Resolve *value* to an aware datetime.
+
+    Raises ``ValueError`` if the form is unrecognized or the resolved deadline
+    is not in the future, and ``TypeError`` for unsupported types.
+    """
+    if now is None:
+        now = _local_now()
+    elif now.tzinfo is None:
+        now = now.astimezone()
+    deadline = _parse(value, now)
+    if deadline <= now:
+        raise ValueError(
+            f"deadline {deadline.isoformat()} is not in the future (now: {now.isoformat()})"
+        )
+    return deadline
+
+
+def seconds_until(deadline: datetime, *, now: datetime | None = None) -> float:
+    """Seconds remaining until *deadline* (negative if it has passed)."""
+    if now is None:
+        now = _local_now()
+    return (deadline - now).total_seconds()
+
+
+def _parse(value: object, now: datetime) -> datetime:
+    if isinstance(value, datetime):
+        return value if value.tzinfo else value.astimezone()
+    if isinstance(value, timedelta):
+        return now + value
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return now + timedelta(seconds=float(value))
+    if isinstance(value, str):
+        if m := _REL.match(value):
+            qty = float(m.group(1))
+            unit = m.group(2)[0].lower()
+            return now + timedelta(seconds=qty * _UNIT_SECONDS[unit])
+        if m := _WALL.match(value):
+            hour, minute = int(m.group(1)), int(m.group(2))
+            candidate = now.replace(hour=hour, minute=minute, second=0, microsecond=0)
+            if candidate <= now:
+                candidate += timedelta(days=1)
+            return candidate
+        try:
+            parsed = datetime.fromisoformat(value.strip())
+        except ValueError:
+            raise ValueError(f"unrecognized deadline: {value!r}") from None
+        return parsed if parsed.tzinfo else parsed.astimezone()
+    raise TypeError(f"unsupported deadline type: {type(value).__name__}")

offpeak/job.py

@@ -0,0 +1,109 @@
+"""Job, Result, and Receipt — the unit of deferred work and its settlement."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+
+from .prices import batch_cost_usd, list_cost_usd
+
+__all__ = ["Job", "Result", "Receipt", "Status", "job"]
+
+
+class Status(str, Enum):
+    QUEUED = "queued"
+    SUBMITTED = "submitted"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    FELL_BACK = "fell_back"  # completed, but via the sync fallback (list price)
+
+
+@dataclass
+class Job:
+    """A venue-agnostic chat-completion job."""
+
+    model: str
+    messages: list[dict]
+    params: dict = field(default_factory=dict)
+    id: str = field(default_factory=lambda: f"job_{uuid.uuid4().hex[:12]}")
+    metadata: dict = field(default_factory=dict)
+    status: Status = Status.QUEUED
+
+
+def job(
+    model: str,
+    input: str | list[dict] | None = None,
+    *,
+    system: str | None = None,
+    metadata: dict | None = None,
+    **params: object,
+) -> Job:
+    """Build a :class:`Job`.
+
+    ``input`` may be a plain prompt string or a full ``messages`` list.
+    Extra keyword arguments (``temperature``, ``max_tokens``, ...) are passed
+    through to the venue.
+    """
+    if input is None:
+        raise ValueError("job() requires an input (a prompt string or a messages list)")
+    if isinstance(input, str):
+        messages = [{"role": "user", "content": input}]
+    else:
+        messages = list(input)
+    if system is not None:
+        messages = [{"role": "system", "content": system}, *messages]
+    return Job(model=model, messages=messages, params=dict(params), metadata=metadata or {})
+
+
+@dataclass
+class Receipt:
+    """Per-job settlement: what ran where, when, and what the hour was worth."""
+
+    venue: str
+    model: str
+    deadline: datetime
+    submitted_at: datetime
+    completed_at: datetime | None = None
+    input_tokens: int = 0
+    output_tokens: int = 0
+    fell_back: bool = False
+
+    @property
+    def sla_met(self) -> bool:
+        return self.completed_at is not None and self.completed_at <= self.deadline
+
+    @property
+    def list_usd(self) -> float | None:
+        """What the job would have cost run synchronously at list price."""
+        return list_cost_usd(self.model, self.input_tokens, self.output_tokens)
+
+    @property
+    def paid_usd(self) -> float | None:
+        """What the job cost on the venue it actually ran on."""
+        if self.fell_back:
+            return self.list_usd
+        return batch_cost_usd(self.model, self.input_tokens, self.output_tokens)
+
+    @property
+    def spread_usd(self) -> float | None:
+        """Captured spread: list minus paid."""
+        if self.list_usd is None or self.paid_usd is None:
+            return None
+        return self.list_usd - self.paid_usd
+
+
+@dataclass
+class Result:
+    """The outcome of one job."""
+
+    job: Job
+    text: str | None = None
+    raw: object = None
+    error: str | None = None
+    receipt: Receipt | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None and self.text is not None

offpeak/prices.py

@@ -0,0 +1,68 @@
+"""List-price sheet and batch discounts, for receipts.
+
+Receipts are arithmetic against public price sheets — no estimates. The prices
+below are a **bundled snapshot** (see ``PRICE_SHEET_DATE``); providers change
+prices, so verify against their published sheets and override at runtime with
+:func:`register_price` where they have moved. Costs for unknown models resolve
+to ``None`` rather than a guess.
+
+Batch tiers at OpenAI, Anthropic, and Google are publicly priced at 50% of
+list, which is what :data:`BATCH_DISCOUNT` encodes.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "PRICE_SHEET_DATE",
+    "BATCH_DISCOUNT",
+    "register_price",
+    "get_price",
+    "list_cost_usd",
+    "batch_cost_usd",
+]
+
+PRICE_SHEET_DATE = "2026-08"
+
+# Fraction of list price paid on provider batch tiers (published: 50%).
+BATCH_DISCOUNT = 0.5
+
+# model -> (USD per 1M input tokens, USD per 1M output tokens), standard list.
+_PRICES: dict[str, tuple[float, float]] = {
+    # Anthropic (per anthropic.com/pricing)
+    "claude-opus-4-5": (5.00, 25.00),
+    "claude-sonnet-4-5": (3.00, 15.00),
+    "claude-haiku-4-5": (1.00, 5.00),
+    # OpenAI (per openai.com/api/pricing)
+    "gpt-5.1": (1.25, 10.00),
+    "gpt-5.1-mini": (0.25, 2.00),
+    "gpt-5.1-nano": (0.05, 0.40),
+}
+
+
+def register_price(model: str, input_per_m: float, output_per_m: float) -> None:
+    """Set or override the list price for *model* (USD per 1M tokens)."""
+    _PRICES[model] = (float(input_per_m), float(output_per_m))
+
+
+def get_price(model: str) -> tuple[float, float] | None:
+    """Exact match first, then longest registered prefix (handles date-pinned
+    model names like ``claude-sonnet-4-5-20250929``)."""
+    if model in _PRICES:
+        return _PRICES[model]
+    best = None
+    for name, price in _PRICES.items():
+        if model.startswith(name) and (best is None or len(name) > best[0]):
+            best = (len(name), price)
+    return best[1] if best else None
+
+
+def list_cost_usd(model: str, input_tokens: int, output_tokens: int) -> float | None:
+    price = get_price(model)
+    if price is None:
+        return None
+    return (input_tokens * price[0] + output_tokens * price[1]) / 1_000_000
+
+
+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

offpeak/venues/__init__.py

@@ -0,0 +1,5 @@
+"""Venues — the places deferred work can run."""
+
+from .base import BatchState, Venue
+
+__all__ = ["Venue", "BatchState"]

offpeak/venues/anthropic_batch.py

@@ -0,0 +1,141 @@
+"""Anthropic Message Batches venue (−50% vs list, 24h completion window).
+
+Uses your own ``ANTHROPIC_API_KEY``. Requires the ``anthropic`` extra:
+``pip install "offpeak[anthropic]"``.
+"""
+
+from __future__ import annotations
+
+from ..job import Job, Result
+from .base import BatchState, Venue
+
+__all__ = ["AnthropicBatch", "build_requests"]
+
+_DEFAULT_MAX_TOKENS = 4096
+
+
+def build_requests(jobs: list[Job]) -> list[dict]:
+    """Render *jobs* as Message Batches request dicts."""
+    requests = []
+    for j in jobs:
+        system = None
+        messages = []
+        for message in j.messages:
+            if message.get("role") == "system":
+                system = message.get("content")
+            else:
+                messages.append(message)
+        params = {
+            "model": j.model,
+            "messages": messages,
+            "max_tokens": j.params.get("max_tokens", _DEFAULT_MAX_TOKENS),
+            **{k: v for k, v in j.params.items() if k != "max_tokens"},
+        }
+        if system is not None:
+            params["system"] = system
+        requests.append({"custom_id": j.id, "params": params})
+    return requests
+
+
+def _text_of(message: object) -> str:
+    blocks = getattr(message, "content", None) or []
+    parts = []
+    for block in blocks:
+        text = getattr(block, "text", None)
+        if text is None and isinstance(block, dict):
+            text = block.get("text")
+        if text:
+            parts.append(text)
+    return "".join(parts)
+
+
+class AnthropicBatch(Venue):
+    name = "anthropic:batch"
+
+    def __init__(self, client: object | None = None):
+        self._client = client
+
+    @property
+    def client(self):
+        if self._client is None:
+            try:
+                from anthropic import Anthropic
+            except ImportError as exc:  # pragma: no cover
+                raise ImportError(
+                    'Anthropic venue requires the anthropic SDK: pip install "offpeak[anthropic]"'
+                ) from exc
+            self._client = Anthropic()
+        return self._client
+
+    def supports(self, model: str) -> bool:
+        return model.startswith("claude")
+
+    def submit(self, jobs: list[Job]) -> str:
+        batch = self.client.messages.batches.create(requests=build_requests(jobs))
+        return batch.id
+
+    def status(self, handle: str) -> BatchState:
+        batch = self.client.messages.batches.retrieve(handle)
+        counts = getattr(batch, "request_counts", None)
+        processing = getattr(batch, "processing_status", "in_progress")
+        status = "completed" if processing == "ended" else "in_progress"
+        if processing in ("canceling", "cancelled"):
+            status = "cancelled"
+        return BatchState(
+            status=status,
+            completed=getattr(counts, "succeeded", 0) or 0,
+            failed=(getattr(counts, "errored", 0) or 0) + (getattr(counts, "expired", 0) or 0),
+            total=sum(
+                getattr(counts, k, 0) or 0
+                for k in ("processing", "succeeded", "errored", "canceled", "expired")
+            ),
+        )
+
+    def collect(self, handle: str) -> dict[str, Result]:
+        results: dict[str, Result] = {}
+        for entry in self.client.messages.batches.results(handle):
+            outcome = entry.result
+            if getattr(outcome, "type", None) == "succeeded":
+                message = outcome.message
+                usage = getattr(message, "usage", None)
+                results[entry.custom_id] = Result(
+                    job=None,
+                    text=_text_of(message),
+                    raw={
+                        "input_tokens": getattr(usage, "input_tokens", 0),
+                        "output_tokens": getattr(usage, "output_tokens", 0),
+                    },
+                )
+            else:
+                results[entry.custom_id] = Result(
+                    job=None, error=f"{getattr(outcome, 'type', 'error')}: {outcome}"
+                )
+        return results
+
+    def cancel(self, handle: str) -> None:
+        try:
+            self.client.messages.batches.cancel(handle)
+        except Exception:  # noqa: BLE001 — best-effort
+            pass
+
+    def run_sync(self, job: Job) -> Result:
+        requests = build_requests([job])
+        params = requests[0]["params"]
+        try:
+            message = self.client.messages.create(**params)
+        except Exception as exc:  # noqa: BLE001
+            return Result(job=job, error=str(exc))
+        usage = getattr(message, "usage", None)
+        return Result(
+            job=job,
+            text=_text_of(message),
+            raw={
+                "input_tokens": getattr(usage, "input_tokens", 0),
+                "output_tokens": getattr(usage, "output_tokens", 0),
+            },
+        )
+
+
+def usage_tokens(usage: dict) -> tuple[int, int]:
+    """(input_tokens, output_tokens) from an Anthropic usage dict."""
+    return int(usage.get("input_tokens", 0) or 0), int(usage.get("output_tokens", 0) or 0)

offpeak/venues/base.py

@@ -0,0 +1,58 @@
+"""The Venue interface — anywhere a deferred job can run.
+
+v0.1 ships provider batch tiers. The same interface is how off-peak windows on
+your own GPUs, spot capacity, and cleaner regions plug in later.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+from ..job import Job, Result
+
+__all__ = ["Venue", "BatchState"]
+
+
+@dataclass
+class BatchState:
+    """A venue batch's progress."""
+
+    status: str  # "in_progress" | "completed" | "failed" | "cancelled"
+    completed: int = 0
+    failed: int = 0
+    total: int = 0
+
+    @property
+    def done(self) -> bool:
+        return self.status in ("completed", "failed", "cancelled")
+
+
+class Venue(ABC):
+    """A place deferred work can execute, plus a synchronous escape hatch."""
+
+    name: str = "venue"
+
+    @abstractmethod
+    def supports(self, model: str) -> bool:
+        """Whether this venue can run *model*."""
+
+    @abstractmethod
+    def submit(self, jobs: list[Job]) -> str:
+        """Submit *jobs* as one batch; return an opaque batch handle."""
+
+    @abstractmethod
+    def status(self, handle: str) -> BatchState:
+        """Poll a batch's progress."""
+
+    @abstractmethod
+    def collect(self, handle: str) -> dict[str, Result]:
+        """Fetch results for a finished batch, keyed by job id."""
+
+    @abstractmethod
+    def cancel(self, handle: str) -> None:
+        """Best-effort cancel of an in-flight batch."""
+
+    @abstractmethod
+    def run_sync(self, job: Job) -> Result:
+        """Run one job synchronously at list price (the SLA fallback path)."""

offpeak/venues/openai_batch.py

@@ -0,0 +1,149 @@
+"""OpenAI Batch API venue (−50% vs list, 24h completion window).
+
+Uses your own ``OPENAI_API_KEY``. Requires the ``openai`` extra:
+``pip install "offpeak[openai]"``.
+"""
+
+from __future__ import annotations
+
+import json
+
+from ..job import Job, Result
+from .base import BatchState, Venue
+
+__all__ = ["OpenAIBatch", "build_jsonl", "parse_output_line"]
+
+_MODEL_PREFIXES = ("gpt-", "o1", "o3", "o4", "chatgpt-")
+_ENDPOINT = "/v1/chat/completions"
+
+
+def build_jsonl(jobs: list[Job]) -> bytes:
+    """Render *jobs* as OpenAI Batch API JSONL (one request per line)."""
+    lines = []
+    for j in jobs:
+        body = {"model": j.model, "messages": j.messages, **j.params}
+        lines.append(
+            json.dumps(
+                {"custom_id": j.id, "method": "POST", "url": _ENDPOINT, "body": body},
+                ensure_ascii=False,
+            )
+        )
+    return ("\n".join(lines) + "\n").encode("utf-8")
+
+
+def parse_output_line(line: str) -> tuple[str, str | None, dict, str | None]:
+    """Parse one output-file line -> (job_id, text, usage, error)."""
+    record = json.loads(line)
+    job_id = record.get("custom_id", "")
+    if record.get("error"):
+        return job_id, None, {}, str(record["error"])
+    response = record.get("response") or {}
+    body = response.get("body") or {}
+    if response.get("status_code") not in (200, None):
+        return job_id, None, {}, f"HTTP {response.get('status_code')}: {body}"
+    try:
+        text = body["choices"][0]["message"]["content"]
+    except (KeyError, IndexError, TypeError):
+        return job_id, None, {}, f"unexpected response body: {body!r}"
+    return job_id, text, body.get("usage") or {}, None
+
+
+class OpenAIBatch(Venue):
+    name = "openai:batch"
+
+    def __init__(self, client: object | None = None):
+        self._client = client
+
+    @property
+    def client(self):
+        if self._client is None:
+            try:
+                from openai import OpenAI
+            except ImportError as exc:  # pragma: no cover
+                raise ImportError(
+                    'OpenAI venue requires the openai SDK: pip install "offpeak[openai]"'
+                ) from exc
+            self._client = OpenAI()
+        return self._client
+
+    def supports(self, model: str) -> bool:
+        return model.startswith(_MODEL_PREFIXES)
+
+    def submit(self, jobs: list[Job]) -> str:
+        upload = self.client.files.create(
+            file=("offpeak_batch.jsonl", build_jsonl(jobs)), purpose="batch"
+        )
+        batch = self.client.batches.create(
+            input_file_id=upload.id, endpoint=_ENDPOINT, completion_window="24h"
+        )
+        return batch.id
+
+    def status(self, handle: str) -> BatchState:
+        batch = self.client.batches.retrieve(handle)
+        mapping = {
+            "validating": "in_progress",
+            "in_progress": "in_progress",
+            "finalizing": "in_progress",
+            "completed": "completed",
+            "failed": "failed",
+            "expired": "failed",
+            "cancelling": "cancelled",
+            "cancelled": "cancelled",
+        }
+        counts = getattr(batch, "request_counts", None)
+        return BatchState(
+            status=mapping.get(batch.status, "in_progress"),
+            completed=getattr(counts, "completed", 0) or 0,
+            failed=getattr(counts, "failed", 0) or 0,
+            total=getattr(counts, "total", 0) or 0,
+        )
+
+    def collect(self, handle: str) -> dict[str, Result]:
+        batch = self.client.batches.retrieve(handle)
+        out: dict[str, tuple[str | None, dict, str | None]] = {}
+        for file_id in (batch.output_file_id, batch.error_file_id):
+            if not file_id:
+                continue
+            content = self.client.files.content(file_id).text
+            for line in content.splitlines():
+                if not line.strip():
+                    continue
+                job_id, text, usage, error = parse_output_line(line)
+                out[job_id] = (text, usage, error)
+        results: dict[str, Result] = {}
+        for job_id, (text, usage, error) in out.items():
+            results[job_id] = Result(
+                job=None,  # attached by the scheduler
+                text=text,
+                raw=usage,
+                error=error,
+            )
+        return results
+
+    def cancel(self, handle: str) -> None:
+        try:
+            self.client.batches.cancel(handle)
+        except Exception:  # noqa: BLE001 — best-effort
+            pass
+
+    def run_sync(self, job: Job) -> Result:
+        try:
+            response = self.client.chat.completions.create(
+                model=job.model, messages=job.messages, **job.params
+            )
+        except Exception as exc:  # noqa: BLE001
+            return Result(job=job, error=str(exc))
+        usage = getattr(response, "usage", None)
+        return Result(
+            job=job,
+            text=response.choices[0].message.content,
+            raw={
+                "prompt_tokens": getattr(usage, "prompt_tokens", 0),
+                "completion_tokens": getattr(usage, "completion_tokens", 0),
+            },
+        )
+
+
+def usage_tokens(usage: dict) -> tuple[int, int]:
+    """(input_tokens, output_tokens) from an OpenAI usage dict."""
+    return int(usage.get("prompt_tokens", 0) or 0), int(usage.get("completion_tokens", 0) or 0)

offpeak-0.1.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: offpeak
+Version: 0.1.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
+Project-URL: Issues, https://github.com/offpeak-ai/offpeak/issues
+Project-URL: Changelog, https://github.com/offpeak-ai/offpeak/releases
+Author: Offpeak
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: anthropic,batch,batch-api,cost-optimization,deadline,finops,inference,llm,openai,scheduling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40; extra == 'all'
+Requires-Dist: openai>=1.50; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: dev
+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: openai
+Requires-Dist: openai>=1.50; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# offpeak
+
+**Deadline-priced inference.** Same model, same tokens, a different hour — for half the price.
+
+[![CI](https://github.com/offpeak-ai/offpeak/actions/workflows/ci.yml/badge.svg)](https://github.com/offpeak-ai/offpeak/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/offpeak)](https://pypi.org/project/offpeak/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+OpenAI, Anthropic, and Google all sell batch inference at **50% off list price**. Almost nobody uses it, because no API lets work say it can wait: every token runs "now" by default, and the batch workflow — build a file, upload, poll, download, match results back up — is enough friction that urgency gets bought by accident.
+
+`offpeak` gives your code one new argument.
+
+```python
+import offpeak
+
+jobs = [offpeak.job("claude-haiku-4-5", f"Summarize:\n\n{doc}") for doc in docs]
+
+results = offpeak.run(jobs, deadline="06:00")   # done by 6am, at batch prices
+
+print(offpeak.receipt(results))
+```
+
+```
+OFFPEAK SETTLEMENT ────────────────────────────
+jobs      1,000 (1,000 ok, 2 sync fallback)
+sla       1,000/1,000 met
+venues    anthropic:batch 1,000
+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
+───────────────────────────────────────────────
+```
+
+## What it does
+
+- **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.
+- **Your keys, your perimeter.** `offpeak` talks directly to the providers with your own API keys. There is no proxy and no third party in the data path.
+- **Zero-dependency core.** Provider SDKs load only via extras.
+
+## Install
+
+```bash
+pip install "offpeak[all]"        # OpenAI + Anthropic venues
+pip install "offpeak[anthropic]"  # or one provider
+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)`.
+
+## Deadlines
+
+Deadlines are how software says "this can wait" — the full semantics live in [SPEC.md](SPEC.md).
+
+| Form | Meaning |
+| --- | --- |
+| `"06:00"` | the next 6am, local time (the canonical overnight form) |
+| `"4h"`, `"90m"`, `"2d"` | relative to now |
+| `"2026-08-21T06:00:00-07:00"` | ISO 8601, absolute |
+| `datetime` / `timedelta` / seconds | native Python forms |
+
+## How a run works
+
+1. Jobs are grouped by venue (`claude-*` → Anthropic Message Batches, `gpt-*`/`o*` → OpenAI Batch) and submitted at the batch tier — 50% of list.
+2. `offpeak` polls the venues, backing off while the window is long.
+3. When remaining time reaches the **risk buffer** (default: 15% of the window, clamped to 1–10 minutes), unfinished jobs are cancelled and re-run synchronously so the deadline holds. Set `fallback="none"` to report them instead.
+4. Results come back in input order, each with a per-job `Receipt`; `offpeak.receipt(results)` settles the run.
+
+```python
+results = offpeak.run(
+    jobs,
+    deadline="06:00",
+    fallback="sync",       # meet the deadline at list price if the batch is at risk
+    risk_buffer=600,       # seconds held in reserve (optional)
+)
+```
+
+## Receipts and prices
+
+Receipts are computed against a bundled snapshot of public list prices (batch = 50% of list, as published). Providers change prices — verify and override at runtime:
+
+```python
+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.
+
+## 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 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.
+
+## Contributing
+
+Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Spec changes start as issues against [SPEC.md](SPEC.md).
+
+## License
+
+Apache-2.0 © Offpeak

offpeak-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+offpeak/__init__.py,sha256=c162EB9ueM1zTqsKiSSNKZo4fWuyimm6Wj19Wa3vMiY,902
+offpeak/client.py,sha256=8z-cShoDYNfaSV1zShktZGYHOYsR7F3ZOJVACwGGzk8,8060
+offpeak/deadline.py,sha256=iA_Y3KnnAO93Gq1EzlUnKSnPMwu-XWiVSu9eTe5W9nU,3078
+offpeak/job.py,sha256=0xDcsBVLBcQstufnq6lWnuMTVJx8n-UKXa9udabHqfk,3114
+offpeak/prices.py,sha256=8aS-eV_J8oieDkW-xPESSHCOhpnC7g5lFxPwEQDYKBw,2387
+offpeak/venues/__init__.py,sha256=O7JP5ZLneZuzWDaAoGtOSBHFLWM0sI928IxbZx_CLZ0,123
+offpeak/venues/anthropic_batch.py,sha256=Tbwm-sWVEjL7ehLDDGa9Hge-rF6rchM9Ppm3JIs-Vbo,4985
+offpeak/venues/base.py,sha256=6E5jQCueES1pdey9jf5ECkwxPfDnC5oju53ZV97fxQ8,1590
+offpeak/venues/openai_batch.py,sha256=PyZdQQYFWyDAqrHTVQY0w7w90_KYhimT8dlrSjwYj44,5331
+offpeak-0.1.0.dist-info/METADATA,sha256=ZVrUVElb6S83hVILwfWze57SpYcqDqCPcPXmR1eU9Rc,7009
+offpeak-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+offpeak-0.1.0.dist-info/licenses/LICENSE,sha256=b5Z1Ke9S-OpiuXz9qfIFMo-6ZEMkmjjTSel0ABqfuNA,11340
+offpeak-0.1.0.dist-info/RECORD,,

offpeak-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

offpeak-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        https://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Offpeak
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.