dispatch-kit 0.1.0__py3-none-any.whl

dispatch_kit/__init__.py

@@ -0,0 +1,88 @@
+"""dispatch-kit — a pure, fail-closed library for gating expensive remote/external work.
+
+Decide whether an expensive operation may run, how much it will cost, and where it should run —
+the same machinery for a cloud GPU job (Cloud Run L4 over a tailnet) and a paid LLM/SDK API call:
+
+    from dispatch_kit import BudgetCap, BudgetState, admits, estimate_cost  # the hard $ cap
+    from dispatch_kit import select_backend, BackendKind, ToolRequirements  # where it runs
+    from dispatch_kit import SecretRef, ExternalEndpoint, log_egress  # opt-in API egress
+    from dispatch_kit import Approval  # the approval audit fact
+
+Pure domain — stdlib only, no I/O, no provider SDK code; every check is fail-closed (default budget
+``0`` = paid work off; SDK egress opt-in only; a missing key/over-budget refuses). The transport
+auth (who) is a separate concern — pair this with ``tailnet-guard``. The consuming app keeps its job
+entity, persistence, and executor; this owns the policy.
+"""
+
+from __future__ import annotations
+
+from .approval import Approval, ApprovalOutcome
+from .budget import (
+    AdmissionDecision,
+    BudgetCap,
+    BudgetState,
+    BudgetWindow,
+    CostRates,
+    admits,
+    estimate_cost,
+)
+from .dispatch import (
+    DispatchError,
+    JobStore,
+    Lease,
+    Transport,
+    WorkerExecutor,
+    is_lease_stale,
+    should_give_up,
+)
+from .egress import (
+    EnvLookup,
+    ExternalEndpoint,
+    SecretMissingError,
+    SecretRef,
+    log_egress,
+)
+from .estimate import CostEstimate, HostCapabilities, vram_fits
+from .routing import (
+    BackendCapabilities,
+    BackendKind,
+    NodeIdentity,
+    NoEligibleBackendError,
+    Routable,
+    ToolRequirements,
+    select_backend,
+)
+
+__all__ = [
+    "AdmissionDecision",
+    "Approval",
+    "ApprovalOutcome",
+    "BackendCapabilities",
+    "BackendKind",
+    "BudgetCap",
+    "BudgetState",
+    "BudgetWindow",
+    "CostEstimate",
+    "CostRates",
+    "DispatchError",
+    "EnvLookup",
+    "ExternalEndpoint",
+    "HostCapabilities",
+    "JobStore",
+    "Lease",
+    "NoEligibleBackendError",
+    "NodeIdentity",
+    "Routable",
+    "SecretMissingError",
+    "SecretRef",
+    "ToolRequirements",
+    "Transport",
+    "WorkerExecutor",
+    "admits",
+    "estimate_cost",
+    "is_lease_stale",
+    "log_egress",
+    "select_backend",
+    "should_give_up",
+    "vram_fits",
+]

dispatch_kit/approval.py

@@ -0,0 +1,44 @@
+"""Approval — the human decision + audit record that gates an expensive (non-local) job.
+
+A gated job leaves "awaiting approval" only by a human decision; recording WHO decided, WHEN, and
+WHY keeps a paid run attributable (append-only in spirit). The state machine — which states are
+gated and the transitions between them — lives in the consuming app's job entity; this is the
+shared audit fact and the binary outcome both apps record.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+
+
+class ApprovalOutcome(enum.StrEnum):
+    """The decision a human made on a gated job."""
+
+    APPROVED = "approved"
+    REJECTED = "rejected"
+
+
+@dataclass(frozen=True, slots=True)
+class Approval:
+    """Who approved or rejected a gated job, when, and why — the audit fact.
+
+    ``author``/``reason``/``decided_at`` are all required: a decision is never anonymous,
+    unexplained, or untimestamped. ``decided_at`` is ISO-8601, server-assigned at the decision.
+    ``outcome`` defaults to APPROVED so the common "approve" path constructs positionally; a
+    rejection passes ``ApprovalOutcome.REJECTED``.
+    """
+
+    author: str
+    reason: str
+    decided_at: str
+    outcome: ApprovalOutcome = ApprovalOutcome.APPROVED
+
+    def __post_init__(self) -> None:
+        for name, value in (
+            ("author", self.author),
+            ("reason", self.reason),
+            ("decided_at", self.decided_at),
+        ):
+            if not value:
+                raise ValueError(f"an approval needs a non-empty {name}")

dispatch_kit/budget.py

@@ -0,0 +1,156 @@
+"""Budget ledger — a hard, fail-closed spend cap that gates expensive (non-local) work.
+
+Cloud GPU jobs and paid API calls cost real money, so a **hard** spend cap is a circuit breaker
+against errant testing or an agent flooding dispatch. The cap is enforced by **reserving** a job's
+upper-bound cost the moment it is approved/queued, against BOTH a per-run window and a per-month
+window: a job is admitted only if ``reserved + spent + its estimate`` stays within both caps. A
+burst of approvals reserves cumulatively, so once a cap is reached the next job is refused — you
+cannot even *queue* past it. The default cap is **zero**, so paid work stays off until you
+deliberately set a budget.
+
+This is pure domain (the rule); the persisted ledger rows + the per-backend rates live in the
+consuming app's storage layer. Money is a :class:`~decimal.Decimal` (exact), never a float — a
+fraction of a cent per GPU-second compounds, and a cost guard that drifts is not a guard.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from decimal import Decimal
+
+
+class BudgetWindow(enum.StrEnum):
+    """The windows a reservation is checked against — BOTH must have room (fail closed).
+
+    ``RUN`` bounds a single batch/session (stops one runaway loop); ``MONTH`` bounds slow
+    accumulation across sessions. A job must fit under both to be admitted.
+    """
+
+    RUN = "run"
+    MONTH = "month"
+
+
+@dataclass(frozen=True, slots=True)
+class BudgetCap:
+    """The hard ceiling per window, in USD. Default ``0`` means paid work is OFF (fail closed)."""
+
+    run_usd: Decimal = Decimal(0)
+    month_usd: Decimal = Decimal(0)
+
+    def __post_init__(self) -> None:
+        if self.run_usd < 0 or self.month_usd < 0:
+            raise ValueError("a budget cap cannot be negative")
+
+    def for_window(self, window: BudgetWindow) -> Decimal:
+        """The cap for ``window`` (the single source the admission rule reads)."""
+        return self.run_usd if window is BudgetWindow.RUN else self.month_usd
+
+
+@dataclass(frozen=True, slots=True)
+class BudgetState:
+    """Committed USD for a window: ``reserved`` (approved, not yet run) + ``spent`` (reconciled).
+
+    Reserving on approval and only reconciling ``reserved -> spent`` on completion is what makes a
+    burst of approvals count immediately — the cap sees the whole queue's cost, not just what ran.
+    """
+
+    reserved_usd: Decimal = Decimal(0)
+    spent_usd: Decimal = Decimal(0)
+
+    def __post_init__(self) -> None:
+        if self.reserved_usd < 0 or self.spent_usd < 0:
+            raise ValueError("budget reserved/spent cannot be negative")
+
+    def committed(self) -> Decimal:
+        """The total already committed against the cap (reserved + spent)."""
+        return self.reserved_usd + self.spent_usd
+
+
+@dataclass(frozen=True, slots=True)
+class CostRates:
+    """Per-second USD rates for a backend — plain config data (no provider SDK code here).
+
+    ``idle_tail_s`` is the post-request warm tail you still pay (a GPU Cloud Run instance bills for
+    ~10 min after the last request before scaling to zero); folding it into the estimate keeps the
+    reservation an upper bound. A token-priced API can model itself with ``gpu_usd_per_s`` = 0 and a
+    flat per-call cost via :func:`estimate_cost` inputs, or extend this with its own rate object.
+    """
+
+    gpu_usd_per_s: Decimal
+    vcpu_usd_per_s: Decimal
+    gib_usd_per_s: Decimal
+    idle_tail_s: Decimal = Decimal(0)
+
+    def __post_init__(self) -> None:
+        for name, value in (
+            ("gpu_usd_per_s", self.gpu_usd_per_s),
+            ("vcpu_usd_per_s", self.vcpu_usd_per_s),
+            ("gib_usd_per_s", self.gib_usd_per_s),
+            ("idle_tail_s", self.idle_tail_s),
+        ):
+            if value < 0:
+                raise ValueError(f"{name} cannot be negative")
+
+
+@dataclass(frozen=True, slots=True)
+class AdmissionDecision:
+    """Whether a job fits the budget, and — when it does not — which window refused and why.
+
+    ``refused_window`` is the first window (run, then month) that lacked room; ``None`` on admit.
+    The reason is human-facing, so the refusal is legible at approval, never a silent drop.
+    """
+
+    admitted: bool
+    refused_window: BudgetWindow | None
+    reason: str
+
+
+def admits(
+    estimate_usd: Decimal,
+    run_state: BudgetState,
+    month_state: BudgetState,
+    cap: BudgetCap,
+) -> AdmissionDecision:
+    """Can a job whose upper-bound cost is ``estimate_usd`` be admitted? Fail-closed, both windows.
+
+    Admitted only if ``reserved + spent + estimate <= cap`` for the run AND the month window. The
+    default cap (zero) admits nothing — paid work stays off until a budget is set. A negative
+    estimate is refused (its cost is not reasoned about); a zero-cost job within a zero cap is fine.
+    """
+    if estimate_usd < 0:
+        return AdmissionDecision(False, None, "a cost estimate cannot be negative")
+    for window, state in ((BudgetWindow.RUN, run_state), (BudgetWindow.MONTH, month_state)):
+        cap_window = cap.for_window(window)
+        if state.committed() + estimate_usd > cap_window:
+            return AdmissionDecision(
+                False,
+                window,
+                (
+                    f"would exceed the {window.value} budget cap (${cap_window}): "
+                    f"${state.committed()} committed + ${estimate_usd} estimate"
+                ),
+            )
+    return AdmissionDecision(True, None, "within budget")
+
+
+def estimate_cost(
+    rates: CostRates,
+    *,
+    max_runtime_s: int,
+    vcpus: int,
+    memory_gib: int,
+) -> Decimal:
+    """Upper-bound USD for one job: (max runtime + idle tail) x (GPU + vCPU + memory) rates. Pure.
+
+    Uses the caller's declared MAX runtime plus the warm idle tail, so the reservation
+    over-estimates; the ledger reconciles ``reserved -> spent`` from the backend's true reported
+    runtime on completion. Over-reserving is the safe direction for a hard cap.
+    """
+    if max_runtime_s < 0 or vcpus < 0 or memory_gib < 0:
+        raise ValueError("runtime/vcpus/memory cannot be negative")
+    billable_s = Decimal(max_runtime_s) + rates.idle_tail_s
+    per_second = (
+        rates.gpu_usd_per_s + rates.vcpu_usd_per_s * vcpus + rates.gib_usd_per_s * memory_gib
+    )
+    return billable_s * per_second

dispatch_kit/dispatch.py

@@ -0,0 +1,102 @@
+"""Dispatch contract for expensive async jobs that run anywhere on the tailnet.
+
+Both a PULL worker (it polls: claim a job, run it, complete it) and a PUSH orchestrator (it posts a
+job to a worker and waits) need the SAME guarantees: a job is CLAIMED atomically so it runs exactly
+once, a stale result is REJECTED, and a worker that dies mid-job has its lease RECOVERED. This
+module is the shared CONTRACT — the pure lease rules + the store/transport/worker protocols. The
+store (SQLite vs SQLAlchemy), the transport (pull vs push), and the payload (a transcribe request vs
+a tool invocation) are per-app ADAPTERS, so two apps converge on one model WITHOUT a shared DB.
+
+Auth (who may run a job) is :mod:`tailnet_guard`; policy (afford / route / approve) is the rest of
+:mod:`dispatch_kit`. This is only the run-it-once-recoverably engine on top of those.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+class DispatchError(RuntimeError):
+    """A dispatch invariant was violated (a stale complete, or a job recovered past its cap)."""
+
+
+@dataclass(frozen=True, slots=True)
+class Lease:
+    """A claim on a job: when it was leased and how many times it has been recovered.
+
+    ``leased_at`` is epoch seconds, stamped at the atomic claim. ``attempts`` counts recoveries (a
+    worker that died and had its lease reclaimed); a job past ``max_attempts`` fails rather than
+    re-leasing forever.
+    """
+
+    job_id: str
+    leased_at: float
+    attempts: int = 0
+
+
+def is_lease_stale(leased_at: float, now: float, ttl_seconds: float) -> bool:
+    """Whether a lease has outlived its TTL (the worker likely died) and may be reclaimed.
+
+    The single home of the lease-staleness rule, shared by every store's ``recover_stale`` so a
+    "leased but silent" job is reclaimed on one schedule. ``ttl_seconds`` should comfortably exceed
+    the longest a healthy run takes, so a slow job is not stolen from a live worker.
+    """
+    return (now - leased_at) >= ttl_seconds
+
+
+def should_give_up(attempts: int, max_attempts: int) -> bool:
+    """Whether a job has been recovered too many times and should FAIL rather than re-lease.
+
+    Fail-closed against a poison job that crashes every worker it lands on: after ``max_attempts``
+    recoveries it is marked failed (with its recorded error), never re-queued indefinitely.
+    """
+    return attempts >= max_attempts
+
+
+class JobStore(Protocol):
+    """The authoritative job store — the ONE place a job's claim/complete is decided, ATOMICALLY.
+
+    ``claim`` must be atomic (one transaction / compare-and-set): two concurrent workers can never
+    both claim the same job — that single claim is the run-exactly-once guarantee. ``complete`` must
+    REJECT a result for a job not currently leased/running (a stale resubmit after the lease was
+    recovered), returning ``False`` so a re-run cannot clobber a fresh result. ``recover_stale``
+    re-leases jobs whose lease outlived the TTL (see :func:`is_lease_stale`), bumping the attempt
+    count and failing a job past ``max_attempts`` (see :func:`should_give_up`). The payload type is
+    the app's own (a transcribe request, a tool invocation, ...).
+    """
+
+    def claim(self, lanes: Sequence[str]) -> tuple[str, Any] | None:
+        """Atomically claim ONE runnable job in ``lanes`` -> ``(job_id, payload)``, or ``None``."""
+
+    def complete(self, job_id: str, result: Any) -> bool:
+        """Apply a result IFF the job is leased/running; ``False`` if stale (done/recovered)."""
+
+    def recover_stale(self, *, now: float, ttl_seconds: float, max_attempts: int) -> Sequence[str]:
+        """Re-lease jobs whose lease is stale (return their ids); fail those past the cap."""
+
+
+class Transport(Protocol):
+    """The hop that moves a job to where it runs — the only thing that differs push vs pull.
+
+    PULL: the worker calls the store's claim/complete directly, so there is no Transport. PUSH: the
+    orchestrator submits the encoded job to a worker endpoint and gets the encoded result back.
+    Either way the worker's auth (``tailnet_guard``) and the policy are unchanged — this is
+    purely the byte-moving seam, so an app swaps pull for push without touching its job model.
+    """
+
+    def submit(self, envelope: dict[str, Any], token: str) -> dict[str, Any]:
+        """Deliver an encoded job to a worker with its capability token; return the response."""
+
+
+class WorkerExecutor(Protocol):
+    """The worker-side run contract: decode (integrity-checked) -> run -> encode.
+
+    The decode MUST verify every artifact's content hash, and the run happens only AFTER the auth
+    guard passes (guard-before-decode), so a tampered/unauthorized job never reaches the executor.
+    Returns the encoded result the store/transport carries back.
+    """
+
+    def execute(self, payload: Any) -> Any:
+        """Run an already-authorized, integrity-checked payload and return its encoded result."""

dispatch_kit/egress.py

@@ -0,0 +1,108 @@
+"""External-API egress — the ONE sanctioned way data leaves the trust boundary, opt-in + logged.
+
+A hosted SDK or LLM API (Rowan, Gemini, Claude, ...) is public TLS + an API key — it intentionally
+breaks the tailnet-only / local-only default. This module gives the three non-negotiable properties
+WITHOUT each caller re-rolling them:
+
+* the key is a SECRET REFERENCE (an env-var name), resolved at call time, never inlined/logged;
+* a missing key fails closed (raises) — never an unauthenticated call;
+* every dispatch logs the egress (that data left the boundary, to which host) — never the key.
+
+The actual HTTP request stays in the consuming app (it knows its payload shape); this module owns
+the credential discipline + the egress audit so every external call is consistent and never the
+default. Pair it with :func:`dispatch_kit.routing.select_backend` (SDK is opt-in) and the budget.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Callable
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+_LOGGER = logging.getLogger("dispatch_kit.egress")
+
+#: A lookup from an env-var name to its value (or ``None``) — injectable so tests need no real env.
+EnvLookup = Callable[[str], "str | None"]
+
+
+class SecretMissingError(RuntimeError):
+    """The referenced secret (API key) is absent from the environment — fail closed.
+
+    A missing key is a hard stop, not a silent unauthenticated call: the opt-in egress exception is
+    only valid with an explicit, configured credential.
+    """
+
+
+@dataclass(frozen=True, slots=True)
+class SecretRef:
+    """A reference to a secret by ENV VAR NAME — never the value.
+
+    The credential is sourced from a secret at call time (:meth:`resolve`) and cannot leak into
+    source or a serialized config: a config object holds only the *name* of the env var.
+    """
+
+    env_var: str
+
+    def __post_init__(self) -> None:
+        if not self.env_var:
+            raise ValueError("a SecretRef needs a non-empty env var name")
+
+    def resolve(self, env: EnvLookup = os.environ.get) -> str:
+        """Read the secret from the environment now; raise :class:`SecretMissingError` if unset."""
+        value = env(self.env_var)
+        if not value:
+            raise SecretMissingError(
+                f"secret env var {self.env_var!r} is unset — refusing an unauthenticated call"
+            )
+        return value
+
+
+@dataclass(frozen=True, slots=True)
+class ExternalEndpoint:
+    """A hosted external API the app may call (opt-in egress): an https base URL + its key ref.
+
+    Construction refuses a non-``https://`` URL (public egress must be TLS). ``name`` is a stable
+    display label used in the egress audit; ``secret`` references the key by env-var name only.
+    """
+
+    name: str
+    base_url: str
+    secret: SecretRef
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            raise ValueError("an external endpoint needs a non-empty name")
+        if not self.base_url.startswith("https://"):
+            raise ValueError(
+                f"external endpoint {self.name!r} must use https:// (public TLS); got "
+                f"{self.base_url!r}"
+            )
+
+    def host(self) -> str:
+        """The endpoint host, for the egress audit (never the full URL with query/credentials)."""
+        return urlsplit(self.base_url).hostname or self.base_url
+
+    def bearer(self, env: EnvLookup = os.environ.get) -> str:
+        """Resolve the key now and return the ``Authorization`` header value (``Bearer <key>``).
+
+        Raises :class:`SecretMissingError` if the key is unset, so a request is never built without
+        a credential. The returned string contains the key — it is for the header only, never a log.
+        """
+        return f"Bearer {self.secret.resolve(env)}"
+
+
+def log_egress(endpoint: ExternalEndpoint, *, detail: str = "") -> None:
+    """Audit that data is leaving the trust boundary, to which host — never the secret.
+
+    Call this immediately before an external request. Logs the endpoint name + host only (the
+    audit-relevant fact); ``detail`` may add a non-sensitive note (e.g. the tool/model name).
+    """
+    suffix = f" [{detail}]" if detail else ""
+    _LOGGER.warning(
+        "egress: %r -> host %r (data leaves the trust boundary)%s",
+        endpoint.name,
+        endpoint.host(),
+        suffix,
+    )

dispatch_kit/estimate.py

@@ -0,0 +1,58 @@
+"""Pre-dispatch cost + feasibility estimates — refuse a job that cannot fit BEFORE it runs.
+
+A backend declares how much compute it has (:class:`HostCapabilities`); an adapter declares what a
+job will cost and need (:class:`CostEstimate`). The shared :func:`vram_fits` rule — "no GPU means a
+GPU job is infeasible" — lives in exactly one place so the local cost gate and the backend router
+agree. All pure: no I/O, no side effects.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+def vram_fits(available_gb: float | None, required_gb: float | None) -> bool:
+    """The single VRAM-budget rule, shared by the host dispatch-kit and the backend router. Pure.
+
+    A CPU job (``required_gb`` is ``None``) always fits; a GPU job needs a GPU present
+    (``available_gb`` not ``None``) with at least the required VRAM. Both the local cost gate
+    (:meth:`HostCapabilities.can_fit_vram`) and the backend capability match defer here so the
+    fail-closed "no GPU means a GPU job is infeasible" rule lives in exactly one place.
+    """
+    if required_gb is None:
+        return True
+    if available_gb is None:
+        return False
+    return available_gb >= required_gb
+
+
+@dataclass(frozen=True, slots=True)
+class HostCapabilities:
+    """A machine's compute budget, supplied per dispatch so the cost gate can fail closed.
+
+    ``available_vram_gb`` of ``None`` means no GPU is present (a GPU job is then infeasible). A
+    CPU-only tool ignores this; a GPU tool compares its ``estimated_vram_gb`` against the budget so
+    a too-large job is refused before the executor runs. The default models a no-GPU host so a
+    missing budget fails closed, never open.
+    """
+
+    available_vram_gb: float | None = None
+
+    def can_fit_vram(self, required_gb: float | None) -> bool:
+        """True if a job needing ``required_gb`` of VRAM fits here (a CPU job always fits)."""
+        return vram_fits(self.available_vram_gb, required_gb)
+
+
+@dataclass(frozen=True, slots=True)
+class CostEstimate:
+    """A pre-dispatch estimate so a too-large/too-long job is refused before it runs.
+
+    ``feasible_locally`` is the gate result (does it fit the host that would run it); ``reason`` is
+    the human-facing rationale carried on a refusal. ``estimated_seconds`` + ``estimated_vram_gb``
+    also feed the budget reservation (:func:`dispatch_kit.budget.estimate_cost`).
+    """
+
+    estimated_seconds: float
+    estimated_vram_gb: float | None
+    feasible_locally: bool
+    reason: str

dispatch_kit/routing.py

@@ -0,0 +1,157 @@
+"""Backend routing — the PURE preference policy that picks where a job runs.
+
+A job carries its :class:`ToolRequirements` (what it needs); a backend declares its
+:class:`BackendCapabilities` (what it can run). :func:`select_backend` is pure: it filters
+to the backends that can satisfy the job, then applies the fixed policy preference —
+**LOCAL -> LAN worker -> CLOUD worker -> SDK** — returning the first match. The SDK (the deliberate
+public-egress exception) is admitted only when the caller explicitly opts in; otherwise it is never
+selected, even if it is the only fit (fail closed on egress).
+
+The router never runs anything and holds no executor — it only *chooses*, over any objects that are
+:class:`Routable` (have a ``kind`` and a ``can_satisfy``). The consuming app binds the actual
+executor onto its own backend type; this library stays free of that I/O.
+"""
+
+from __future__ import annotations
+
+import enum
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Protocol, TypeVar
+
+from .estimate import vram_fits
+
+
+class BackendKind(enum.StrEnum):
+    """Where a job's compute runs — sets the router's preference and lands on provenance/audit."""
+
+    LOCAL = "local"
+    """In-process, or a local subprocess/container on the orchestrator host."""
+    LAN_WORKER = "lan_worker"
+    """A spare LAN desktop running a worker agent, reached over the tailnet."""
+    CLOUD_WORKER = "cloud_worker"
+    """A cloud GPU (e.g. GCP L4 on Cloud Run) running a worker agent, reached over the tailnet."""
+    SDK = "sdk"
+    """A third-party hosted SDK / API over public TLS — the one opt-in egress exception."""
+
+
+# The fixed policy preference order. LOCAL first (cheapest, no egress), then a LAN worker, then a
+# cloud worker, and SDK last — and only when explicitly opted in. This tuple IS the policy; the
+# router walks it in order, so changing the preference is a one-line edit here, not scattered.
+_PREFERENCE_ORDER: tuple[BackendKind, ...] = (
+    BackendKind.LOCAL,
+    BackendKind.LAN_WORKER,
+    BackendKind.CLOUD_WORKER,
+    BackendKind.SDK,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class NodeIdentity:
+    """The identity of a node a job ran on — pinned for audit + reproducibility.
+
+    For a local job this is the orchestrator host. For a remote worker it is the worker's pinned
+    tailnet identity (its MagicDNS name / tailnet IP), so an audit records not just *that* a job ran
+    remotely but *on which authorized worker* — the same identity the trust barrier pins.
+    """
+
+    name: str
+    address: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            raise ValueError("a NodeIdentity requires a non-empty name")
+
+
+@dataclass(frozen=True, slots=True)
+class ToolRequirements:
+    """What a job needs of a backend. Pure data.
+
+    ``min_vram_gb`` of ``None`` is a CPU job (any backend's compute fits). ``image`` set means the
+    job runs in a pinned container, so a backend must be able to run that image. ``tool_id`` lets a
+    backend that ships only certain tools (no image) declare it can run them. The consuming app
+    derives these from its own manifest/invocation — this library does not couple to those types.
+    """
+
+    tool_id: str
+    min_vram_gb: float | None = None
+    image: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class BackendCapabilities:
+    """What a backend can run — matched against :class:`ToolRequirements` by the router. Pure data.
+
+    ``available_vram_gb`` of ``None`` means no GPU (a GPU job cannot run here). ``images`` /
+    ``tool_ids`` of ``None`` mean "no restriction" (a general-purpose backend that runs any pinned
+    image or any tool); a non-empty set restricts the backend to exactly those.
+    """
+
+    has_gpu: bool = False
+    available_vram_gb: float | None = None
+    images: frozenset[str] | None = None
+    tool_ids: frozenset[str] | None = None
+
+    def can_satisfy(self, requirements: ToolRequirements) -> bool:
+        """True if a backend with these capabilities can run a job with ``requirements``. Pure.
+
+        VRAM feasibility defers to the shared :func:`dispatch_kit.estimate.vram_fits` rule (the one
+        home of "no GPU means a GPU job is infeasible"); the image/tool gate is local.
+        """
+        if not vram_fits(self.available_vram_gb, requirements.min_vram_gb):
+            return False
+        if requirements.image is not None and self.images is not None:
+            return requirements.image in self.images
+        if requirements.image is None and self.tool_ids is not None:
+            return requirements.tool_id in self.tool_ids
+        return True
+
+
+class Routable(Protocol):
+    """A backend the router can choose among: it has a :class:`BackendKind` and can answer whether
+    it can run a job. The consuming app's executor-bound backend type satisfies this structurally,
+    so :func:`select_backend` chooses without this library ever knowing about executors."""
+
+    @property
+    def kind(self) -> BackendKind:
+        """The backend's kind, which sets its routing preference."""
+
+    def can_satisfy(self, requirements: ToolRequirements) -> bool:
+        """Whether this backend can run a job with the given requirements."""
+
+
+class NoEligibleBackendError(RuntimeError):
+    """Raised when no registered backend can satisfy a job's requirements under the policy.
+
+    Fail closed: a job with no place to run is a hard error, never a silent local fallback that
+    might OOM or an SDK call the caller did not opt into.
+    """
+
+
+_R = TypeVar("_R", bound=Routable)
+
+
+def select_backend(
+    backends: Iterable[_R],
+    requirements: ToolRequirements,
+    *,
+    allow_sdk: bool = False,
+) -> _R:
+    """Pick the preferred backend that can satisfy ``requirements`` — PURE policy.
+
+    Walks the fixed preference order (LOCAL -> LAN -> CLOUD -> SDK) and returns the first registered
+    backend of that kind whose capabilities satisfy the job. An SDK backend is considered ONLY when
+    ``allow_sdk`` is true — the deliberate egress exception is opt-in, so by default SDK is skipped
+    even if it is the only fit. Raises :class:`NoEligibleBackendError` if nothing eligible matches.
+    """
+    candidates = list(backends)
+    for kind in _PREFERENCE_ORDER:
+        if kind is BackendKind.SDK and not allow_sdk:
+            continue
+        for backend in candidates:
+            if backend.kind is kind and backend.can_satisfy(requirements):
+                return backend
+    raise NoEligibleBackendError(
+        f"no eligible backend for tool {requirements.tool_id!r} "
+        f"(vram>={requirements.min_vram_gb}, image={requirements.image}, allow_sdk={allow_sdk})"
+    )

dispatch_kit-0.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: dispatch-kit
+Version: 0.1.0
+Summary: Pure, fail-closed cost-gating for expensive remote/external work: a hard $ budget cap, backend routing (local->cloud->SDK), and opt-in audited API egress.
+Author-email: Aryan Falahatpisheh <aryanfalahat@gmail.com>
+License: MIT
+Keywords: budget,cost,cloud,gpu,llm,dispatch,egress,approval
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Requires-Dist: pylint>=3.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+
+# dispatch-kit
+
+A tiny, **pure, dependency-free** library for gating expensive remote/external work — the same
+machinery for a **cloud GPU job** (a Cloud Run L4 reached over a tailnet) and a **paid LLM/SDK API
+call** (Gemini, Claude, Rowan). It answers three questions, fail-closed:
+
+- **Can we afford it?** — a hard, reserve-on-approval **budget cap** (per-run + per-month).
+- **Where should it run?** — a pure **router**: `LOCAL → LAN → CLOUD → SDK`, SDK opt-in only.
+- **Is the external call safe?** — opt-in, audited **API egress** with reference-only secrets.
+
+It owns the *policy* (afford / route / approve / egress); your app keeps its job entity,
+persistence, and executor. The transport *auth* (who may talk) is a separate concern — pair this
+with [`tailnet-guard`](https://github.com/falahat/tailnet-guard). Stdlib only; every check is
+fail-closed (default budget `0` = paid work off; SDK never auto-selected; a missing key refuses).
+
+## Use
+
+```python
+from decimal import Decimal
+from dispatch_kit import (
+    BudgetCap, BudgetState, CostRates, admits, estimate_cost,   # the hard $ cap
+    select_backend, BackendKind, ToolRequirements,              # the where
+    SecretRef, ExternalEndpoint, log_egress,                    # opt-in API egress
+    Approval,                                                   # the approval audit fact
+)
+
+# 1. Reserve-on-approval: refuse a job that would push past the cap (both windows).
+rates = CostRates(gpu_usd_per_s=Decimal("0.0008"), vcpu_usd_per_s=Decimal("0.00001"),
+                  gib_usd_per_s=Decimal("0.000002"), idle_tail_s=Decimal(600))
+cost = estimate_cost(rates, max_runtime_s=3600, vcpus=8, memory_gib=32)   # an UPPER bound
+decision = admits(cost, run_state, month_state, BudgetCap(run_usd=Decimal(50), month_usd=Decimal(500)))
+if not decision.admitted:
+    raise OverBudget(decision.reason)        # default cap is $0 — paid work is off until you set one
+
+# 2. Pick where it runs — LOCAL first, SDK only if explicitly allowed.
+backend = select_backend(my_backends, ToolRequirements(tool_id="cofold", min_vram_gb=24.0))
+
+# 3. An LLM/SDK key is a REFERENCE (env var name), resolved at call time, never logged.
+gemini = ExternalEndpoint("gemini", "https://generativelanguage.googleapis.com",
+                          SecretRef("GEMINI_API_KEY"))
+log_egress(gemini, detail="summarize")       # audit that data left the boundary
+headers = {"Authorization": gemini.bearer()} # raises if the key is unset (never an unauth call)
+```
+
+## What's in the box
+
+| Module | Purpose |
+|---|---|
+| `budget` | `BudgetCap` / `BudgetState` / `CostRates` / `admits` / `estimate_cost` — the hard, Decimal-exact, reserve-on-approval cap across a run + month window |
+| `estimate` | `CostEstimate` / `HostCapabilities` / `vram_fits` — the one "no GPU ⇒ a GPU job is infeasible" rule, shared by the gate and the router |
+| `routing` | `BackendKind` / `BackendCapabilities` / `ToolRequirements` / `select_backend` (generic over a `Routable`) — the pure `LOCAL→LAN→CLOUD→SDK` policy; SDK opt-in |
+| `egress` | `SecretRef` / `ExternalEndpoint` / `log_egress` — reference-only API keys, https-only, fail-closed on a missing key, audited egress (SDKs **and** LLM APIs) |
+| `approval` | `Approval` / `ApprovalOutcome` — the who/when/why audit fact for a gated job |
+| `dispatch` | `JobStore` / `Transport` / `WorkerExecutor` protocols + `is_lease_stale` / `should_give_up` / `Lease` — the run-it-once-recoverably contract (atomic claim, stale-reject, lease recovery); push vs pull is only the `Transport` adapter |
+
+## Notes
+
+- **The budget cap lives in your dispatch service, never the UI** — an agent hitting the API
+  directly is still gated. Default cap `$0`; if spend can't be computed, refuse.
+- **Reserve on approval, reconcile on completion** — approving reserves the estimate immediately so
+  a burst counts against the cap; the worker's true runtime reconciles `reserved → spent`.
+- **SDK / external egress is the one deliberate exception** — never the default (`allow_sdk` /
+  opt-in), always logged, the key sourced from a secret at call time and never written to a log.

dispatch_kit-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+dispatch_kit/__init__.py,sha256=PUWm1pmCcji8QpDA9ZLZ2m3mzZhOzhumFSFypqlVLoA,2356
+dispatch_kit/approval.py,sha256=6capLUQJbognPTSAzsoRyrNwWPJwRbxt6tkyDLqvxgs,1552
+dispatch_kit/budget.py,sha256=m-2MAkyWq0kg7asp1g5t6lfnyOAXjjcvjM_oJy8K9wI,6329
+dispatch_kit/dispatch.py,sha256=h2u2wVOFoQMWT_K-3affUilPm6E28VNDnRWPap3zPPk,5003
+dispatch_kit/egress.py,sha256=HPNCAJh0LTVG9pfkjyQbHWpaiPkSyUG4jUkKMpX4RRY,4392
+dispatch_kit/estimate.py,sha256=dnUv4iDAh3UyAjCgkq-mRWrhZP1t984aUhlfL9PHN6g,2507
+dispatch_kit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dispatch_kit/routing.py,sha256=BO0z8lUvteNOl19cyCAgEoDhFfOzDVvi_ffmnITkW1M,6698
+dispatch_kit-0.1.0.dist-info/METADATA,sha256=CfBSqIDhM-wX5e7TfPuw6qhOLo0d1dJOK9TXDKM13xU,5256
+dispatch_kit-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+dispatch_kit-0.1.0.dist-info/top_level.txt,sha256=MQSrew1pPSR4Ei9U80LdMbq3gEjKk03Xa597gflZrsE,13
+dispatch_kit-0.1.0.dist-info/RECORD,,

dispatch_kit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dispatch_kit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dispatch_kit