deltav 0.0.0__tar.gz

deltav-0.0.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.ty/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.env
+.env.*
+!.env.example

deltav-0.0.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: deltav
+Version: 0.0.0
+Summary: DeltaV reservation-based budget enforcement for agent and tool runs.
+Project-URL: Homepage, https://github.com/cachetronaut/deltav
+Project-URL: Repository, https://github.com/cachetronaut/deltav
+Project-URL: Issues, https://github.com/cachetronaut/deltav/issues
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: dockbay>=0.0.0
+Requires-Dist: psycopg-pool>=3.2
+Requires-Dist: psycopg[binary]>=3.2
+Description-Content-Type: text/markdown
+
+# deltav
+
+Python implementation of DeltaV.
+
+For product-level context, shared contracts, and cross-language repository information, see the public repository: https://github.com/cachetronaut/deltav.
+
+## Install
+
+```sh
+pip install deltav
+```
+
+## Import
+
+```python
+import deltav
+```
+
+## Development
+
+Run from `py/`:
+
+```sh
+uv sync --dev
+uv run --with ruff ruff check .
+uv run --with ruff ruff format --check .
+uv run --with ty ty check
+uv run --with pytest --with pytest-asyncio python -m pytest
+```
+
+## License
+
+MIT

deltav-0.0.0/README.md

@@ -0,0 +1,33 @@
+# deltav
+
+Python implementation of DeltaV.
+
+For product-level context, shared contracts, and cross-language repository information, see the public repository: https://github.com/cachetronaut/deltav.
+
+## Install
+
+```sh
+pip install deltav
+```
+
+## Import
+
+```python
+import deltav
+```
+
+## Development
+
+Run from `py/`:
+
+```sh
+uv sync --dev
+uv run --with ruff ruff check .
+uv run --with ruff ruff format --check .
+uv run --with ty ty check
+uv run --with pytest --with pytest-asyncio python -m pytest
+```
+
+## License
+
+MIT

deltav-0.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "deltav"
+version = "0.0.0"
+description = "DeltaV reservation-based budget enforcement for agent and tool runs."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+dependencies = ["dockbay>=0.0.0", "psycopg[binary]>=3.2", "psycopg-pool>=3.2"]
+
+[project.urls]
+Homepage = "https://github.com/cachetronaut/deltav"
+Repository = "https://github.com/cachetronaut/deltav"
+Issues = "https://github.com/cachetronaut/deltav/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/deltav"]
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "ruff>=0.6", "ty>=0.0.1a8"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[tool.ty.environment]
+extra-paths = ["src"]

deltav-0.0.0/src/deltav/__init__.py

@@ -0,0 +1,53 @@
+from .core import (
+    Breach,
+    Budget,
+    BudgetStore,
+    Decision,
+    Reservation,
+    Spend,
+    SpendRequest,
+    Usage,
+    UsageMap,
+    canonicalize,
+    check,
+    check_stack,
+    empty_usage,
+    release,
+    release_stack,
+    reserve,
+    reserve_stack,
+    settle,
+    settle_stack,
+)
+from .store_convex import ConvexBudgetStore, create_budget_operations
+from .store_local import InMemoryBudgetStore
+from .store_postgres import DriverBudgetStore, PostgresBudgetStore
+from .store_remote import RemoteBudgetStore
+
+__all__ = [
+    "Breach",
+    "Budget",
+    "BudgetStore",
+    "ConvexBudgetStore",
+    "Decision",
+    "DriverBudgetStore",
+    "InMemoryBudgetStore",
+    "PostgresBudgetStore",
+    "RemoteBudgetStore",
+    "Reservation",
+    "Spend",
+    "SpendRequest",
+    "Usage",
+    "UsageMap",
+    "canonicalize",
+    "check",
+    "check_stack",
+    "create_budget_operations",
+    "empty_usage",
+    "release",
+    "release_stack",
+    "reserve",
+    "reserve_stack",
+    "settle",
+    "settle_stack",
+]

deltav-0.0.0/src/deltav/core.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Protocol
+
+Spend = dict[str, float]
+
+
+@dataclass(frozen=True)
+class Budget:
+    id: str
+    layer: str
+    limits: dict[str, float]
+
+
+@dataclass(frozen=True)
+class Usage:
+    cumulative: Spend = field(default_factory=dict)
+    concurrent: Spend = field(default_factory=dict)
+    peak: Spend = field(default_factory=dict)
+    reserved: Spend = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class SpendRequest:
+    estimate: Spend
+    run_id: str | None = None
+
+
+@dataclass(frozen=True)
+class Reservation:
+    id: str
+    estimate: Spend
+
+
+@dataclass(frozen=True)
+class Breach:
+    budget_id: str
+    layer: str
+    dimension: str
+    limit: float
+    would_be: float
+
+
+@dataclass(frozen=True)
+class Decision:
+    ok: bool
+    reservation: Reservation | None = None
+    breach: Breach | None = None
+
+
+UsageMap = dict[str, Usage]
+_next_reservation = 1
+
+
+class BudgetStore(Protocol):
+    async def load(self, stack_id: str) -> tuple[list[Budget], UsageMap]: ...
+    async def try_reserve(self, stack_id: str, req: SpendRequest) -> Decision: ...
+    async def settle(self, stack_id: str, reservation: Reservation, actual: Spend) -> None: ...
+    async def release(self, stack_id: str, reservation: Reservation) -> None: ...
+    async def snapshot(self, stack_id: str) -> UsageMap: ...
+
+
+def empty_usage() -> Usage:
+    return Usage()
+
+
+def check(budget: Budget, usage: Usage, req: SpendRequest) -> Decision:
+    for dimension, amount in req.estimate.items():
+        limit = budget.limits.get(dimension)
+        if limit is None:
+            continue
+        if amount < 0:
+            return Decision(
+                ok=False,
+                breach=Breach(budget.id, budget.layer, dimension, 0, amount),
+            )
+        would_be = usage.cumulative.get(dimension, 0) + usage.reserved.get(dimension, 0) + amount
+        if would_be > limit:
+            return Decision(
+                ok=False,
+                breach=Breach(budget.id, budget.layer, dimension, limit, would_be),
+            )
+    return Decision(ok=True, reservation=_reservation(req.estimate))
+
+
+def check_stack(stack: list[Budget], usages: UsageMap, req: SpendRequest) -> Decision:
+    reservation: Reservation | None = None
+    for budget in stack:
+        decision = check(budget, usages.get(budget.id, empty_usage()), req)
+        if not decision.ok:
+            return decision
+        reservation = decision.reservation
+    return Decision(ok=True, reservation=reservation or _reservation(req.estimate))
+
+
+def reserve(usage: Usage, req: SpendRequest) -> Usage:
+    return Usage(
+        cumulative=dict(usage.cumulative),
+        concurrent=dict(usage.concurrent),
+        peak=dict(usage.peak),
+        reserved=_add_delta(usage.reserved, req.estimate),
+    )
+
+
+def settle(usage: Usage, reservation: Reservation, actual: Spend) -> Usage:
+    cumulative = dict(usage.cumulative)
+    for dimension, amount in actual.items():
+        cumulative[dimension] = cumulative.get(dimension, 0) + amount
+    return Usage(
+        cumulative=cumulative,
+        concurrent=dict(usage.concurrent),
+        peak=dict(usage.peak),
+        reserved=_add_delta(usage.reserved, {k: -v for k, v in reservation.estimate.items()}),
+    )
+
+
+def release(usage: Usage, reservation: Reservation) -> Usage:
+    return Usage(
+        cumulative=dict(usage.cumulative),
+        concurrent=dict(usage.concurrent),
+        peak=dict(usage.peak),
+        reserved=_add_delta(usage.reserved, {k: -v for k, v in reservation.estimate.items()}),
+    )
+
+
+def reserve_stack(stack: list[Budget], usages: UsageMap, req: SpendRequest) -> UsageMap:
+    next_usages = dict(usages)
+    for budget in stack:
+        next_usages[budget.id] = reserve(next_usages.get(budget.id, empty_usage()), req)
+    return next_usages
+
+
+def settle_stack(
+    stack: list[Budget], usages: UsageMap, reservation: Reservation, actual: Spend
+) -> UsageMap:
+    next_usages = dict(usages)
+    for budget in stack:
+        next_usages[budget.id] = settle(
+            next_usages.get(budget.id, empty_usage()), reservation, actual
+        )
+    return next_usages
+
+
+def release_stack(stack: list[Budget], usages: UsageMap, reservation: Reservation) -> UsageMap:
+    next_usages = dict(usages)
+    for budget in stack:
+        next_usages[budget.id] = release(next_usages.get(budget.id, empty_usage()), reservation)
+    return next_usages
+
+
+def canonicalize(value: object) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), default=_json_default)
+
+
+def _reservation(estimate: Spend) -> Reservation:
+    global _next_reservation
+    reservation = Reservation(id=f"reservation_{_next_reservation}", estimate=dict(estimate))
+    _next_reservation += 1
+    return reservation
+
+
+def _add_delta(values: Spend, delta: Spend) -> Spend:
+    out = dict(values)
+    for dimension, amount in delta.items():
+        value = out.get(dimension, 0) + amount
+        if value == 0:
+            out.pop(dimension, None)
+        else:
+            out[dimension] = value
+    return out
+
+
+def _json_default(value: object) -> object:
+    if hasattr(value, "__dict__"):
+        return value.__dict__
+    raise TypeError(f"Cannot serialize {type(value)!r}")

deltav-0.0.0/src/deltav/store_convex.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+from dockbay import (
+    ConvexOperationContext,
+    ConvexOperationDriver,
+    ConvexStoreOperation,
+    JsonValue,
+)
+
+from .core import (
+    Budget,
+    Decision,
+    Reservation,
+    Spend,
+    SpendRequest,
+    Usage,
+    UsageMap,
+    check_stack,
+    release_stack,
+    reserve_stack,
+    settle_stack,
+)
+
+LOAD = "budget.load"
+TRY_RESERVE = "budget.tryReserve"
+SETTLE = "budget.settle"
+RELEASE = "budget.release"
+SNAPSHOT = "budget.snapshot"
+
+InitialState = dict[str, tuple[list[Budget], UsageMap]]
+_StackState = dict[str, Any]
+
+
+class ConvexBudgetStore:
+    def __init__(
+        self,
+        driver: ConvexOperationDriver,
+        *,
+        operations: dict[str, str] | None = None,
+    ) -> None:
+        self._driver = driver
+        self._operations = {
+            "load": LOAD,
+            "try_reserve": TRY_RESERVE,
+            "settle": SETTLE,
+            "release": RELEASE,
+            "snapshot": SNAPSHOT,
+            **(operations or {}),
+        }
+
+    async def load(self, stack_id: str) -> tuple[list[Budget], UsageMap]:
+        result = await self._driver.call(self._operations["load"], {"stackId": stack_id})
+        assert isinstance(result, dict)
+        return _row_to_stack(result), _row_to_usage_map(result["usages"])
+
+    async def try_reserve(self, stack_id: str, req: SpendRequest) -> Decision:
+        result = await self._driver.call(
+            self._operations["try_reserve"],
+            {"stackId": stack_id, "req": _spend_request_to_row(req)},
+        )
+        assert isinstance(result, dict)
+        return _row_to_decision(result)
+
+    async def settle(self, stack_id: str, reservation: Reservation, actual: Spend) -> None:
+        await self._driver.call(
+            self._operations["settle"],
+            {
+                "stackId": stack_id,
+                "reservation": _reservation_to_row(reservation),
+                "actual": actual,
+            },
+        )
+
+    async def release(self, stack_id: str, reservation: Reservation) -> None:
+        await self._driver.call(
+            self._operations["release"],
+            {"stackId": stack_id, "reservation": _reservation_to_row(reservation)},
+        )
+
+    async def snapshot(self, stack_id: str) -> UsageMap:
+        result = await self._driver.call(self._operations["snapshot"], {"stackId": stack_id})
+        return _row_to_usage_map(result)
+
+
+def create_budget_operations(initial: InitialState) -> list[ConvexStoreOperation]:
+    state: dict[str, _StackState] = {
+        stack_id: {
+            "stack": [_budget_to_row(budget) for budget in stack],
+            "usages": _usage_map_to_row(usages),
+            "openReservations": [],
+        }
+        for stack_id, (stack, usages) in initial.items()
+    }
+
+    async def load(_ctx: ConvexOperationContext, input_value: JsonValue) -> JsonValue:
+        stack_id = _stack_id_from(input_value)
+        current = _require_stack(state, stack_id)
+        return {
+            "stack": deepcopy(current["stack"]),
+            "usages": deepcopy(current["usages"]),
+        }
+
+    async def try_reserve(_ctx: ConvexOperationContext, input_value: JsonValue) -> JsonValue:
+        assert isinstance(input_value, dict)
+        stack_id = _stack_id_from(input_value)
+        current = _require_stack(state, stack_id)
+        stack = _row_to_stack(current)
+        usages = _row_to_usage_map(current["usages"])
+        decision = check_stack(stack, usages, _row_to_spend_request(input_value["req"]))
+        if not decision.ok or decision.reservation is None:
+            return _decision_to_row(decision)
+        state[stack_id] = {
+            **current,
+            "usages": _usage_map_to_row(
+                reserve_stack(stack, usages, _row_to_spend_request(input_value["req"]))
+            ),
+            "openReservations": [*current["openReservations"], decision.reservation.id],
+        }
+        return _decision_to_row(decision)
+
+    async def settle(_ctx: ConvexOperationContext, input_value: JsonValue) -> JsonValue:
+        assert isinstance(input_value, dict)
+        stack_id = _stack_id_from(input_value)
+        current = _require_stack(state, stack_id)
+        reservation = _row_to_reservation(input_value["reservation"])
+        if reservation.id not in current["openReservations"]:
+            return None
+        stack = _row_to_stack(current)
+        usages = _row_to_usage_map(current["usages"])
+        state[stack_id] = {
+            **current,
+            "usages": _usage_map_to_row(
+                settle_stack(stack, usages, reservation, input_value["actual"])
+            ),
+            "openReservations": [
+                item for item in current["openReservations"] if item != reservation.id
+            ],
+        }
+        return None
+
+    async def release(_ctx: ConvexOperationContext, input_value: JsonValue) -> JsonValue:
+        assert isinstance(input_value, dict)
+        stack_id = _stack_id_from(input_value)
+        current = _require_stack(state, stack_id)
+        reservation = _row_to_reservation(input_value["reservation"])
+        if reservation.id not in current["openReservations"]:
+            return None
+        stack = _row_to_stack(current)
+        usages = _row_to_usage_map(current["usages"])
+        state[stack_id] = {
+            **current,
+            "usages": _usage_map_to_row(release_stack(stack, usages, reservation)),
+            "openReservations": [
+                item for item in current["openReservations"] if item != reservation.id
+            ],
+        }
+        return None
+
+    async def snapshot(_ctx: ConvexOperationContext, input_value: JsonValue) -> JsonValue:
+        stack_id = _stack_id_from(input_value)
+        return deepcopy(_require_stack(state, stack_id)["usages"])
+
+    return [
+        ConvexStoreOperation(name=LOAD, kind="query", run=load),
+        ConvexStoreOperation(name=TRY_RESERVE, kind="mutation", run=try_reserve),
+        ConvexStoreOperation(name=SETTLE, kind="mutation", run=settle),
+        ConvexStoreOperation(name=RELEASE, kind="mutation", run=release),
+        ConvexStoreOperation(name=SNAPSHOT, kind="query", run=snapshot),
+    ]
+
+
+def _require_stack(state: dict[str, _StackState], stack_id: str) -> _StackState:
+    try:
+        return state[stack_id]
+    except KeyError as exc:
+        raise KeyError(f"Unknown budget stack: {stack_id}") from exc
+
+
+def _stack_id_from(input_value: JsonValue) -> str:
+    assert isinstance(input_value, dict)
+    stack_id = input_value.get("stackId")
+    if not isinstance(stack_id, str):
+        raise ValueError("Convex budget operation requires stackId")
+    return stack_id
+
+
+def _budget_to_row(budget: Budget) -> dict[str, Any]:
+    return {"id": budget.id, "layer": budget.layer, "limits": dict(budget.limits)}
+
+
+def _row_to_budget(row: Any) -> Budget:
+    return Budget(id=row["id"], layer=row["layer"], limits=dict(row["limits"]))
+
+
+def _usage_to_row(usage: Usage) -> dict[str, Any]:
+    return {
+        "cumulative": dict(usage.cumulative),
+        "concurrent": dict(usage.concurrent),
+        "peak": dict(usage.peak),
+        "reserved": dict(usage.reserved),
+    }
+
+
+def _row_to_usage(row: Any) -> Usage:
+    return Usage(
+        cumulative=dict(row["cumulative"]),
+        concurrent=dict(row["concurrent"]),
+        peak=dict(row["peak"]),
+        reserved=dict(row["reserved"]),
+    )
+
+
+def _usage_map_to_row(usages: UsageMap) -> dict[str, Any]:
+    return {budget_id: _usage_to_row(usage) for budget_id, usage in usages.items()}
+
+
+def _row_to_usage_map(row: Any) -> UsageMap:
+    return {budget_id: _row_to_usage(usage) for budget_id, usage in deepcopy(row).items()}
+
+
+def _row_to_stack(row: Any) -> list[Budget]:
+    return [_row_to_budget(budget) for budget in deepcopy(row["stack"])]
+
+
+def _spend_request_to_row(req: SpendRequest) -> dict[str, Any]:
+    return {"estimate": dict(req.estimate), "run_id": req.run_id}
+
+
+def _row_to_spend_request(row: Any) -> SpendRequest:
+    return SpendRequest(estimate=dict(row["estimate"]), run_id=row.get("run_id"))
+
+
+def _reservation_to_row(reservation: Reservation) -> dict[str, Any]:
+    return {"id": reservation.id, "estimate": dict(reservation.estimate)}
+
+
+def _row_to_reservation(row: Any) -> Reservation:
+    return Reservation(id=row["id"], estimate=dict(row["estimate"]))
+
+
+def _decision_to_row(decision: Decision) -> dict[str, Any]:
+    if decision.ok:
+        assert decision.reservation is not None
+        return {"ok": True, "reservation": _reservation_to_row(decision.reservation)}
+    assert decision.breach is not None
+    return {
+        "ok": False,
+        "breach": {
+            "budget_id": decision.breach.budget_id,
+            "layer": decision.breach.layer,
+            "dimension": decision.breach.dimension,
+            "limit": decision.breach.limit,
+            "would_be": decision.breach.would_be,
+        },
+    }
+
+
+def _row_to_decision(row: Any) -> Decision:
+    if row["ok"]:
+        return Decision(ok=True, reservation=_row_to_reservation(row["reservation"]))
+    breach = row["breach"]
+    from .core import Breach
+
+    return Decision(
+        ok=False,
+        breach=Breach(
+            budget_id=breach["budget_id"],
+            layer=breach["layer"],
+            dimension=breach["dimension"],
+            limit=breach["limit"],
+            would_be=breach["would_be"],
+        ),
+    )

deltav-0.0.0/src/deltav/store_local.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import asyncio
+from copy import deepcopy
+
+from .core import (
+    Budget,
+    Decision,
+    Reservation,
+    Spend,
+    SpendRequest,
+    UsageMap,
+    check_stack,
+    release_stack,
+    reserve_stack,
+    settle_stack,
+)
+
+
+class InMemoryBudgetStore:
+    def __init__(self, initial: dict[str, tuple[list[Budget], UsageMap]] | None = None) -> None:
+        self._stacks: dict[str, tuple[list[Budget], UsageMap]] = initial or {}
+        self._open: dict[str, set[str]] = {stack_id: set() for stack_id in self._stacks}
+        self._lock = asyncio.Lock()
+
+    async def load(self, stack_id: str) -> tuple[list[Budget], UsageMap]:
+        async with self._lock:
+            stack, usages = self._require(stack_id)
+            return list(stack), deepcopy(usages)
+
+    async def try_reserve(self, stack_id: str, req: SpendRequest) -> Decision:
+        async with self._lock:
+            stack, usages = self._require(stack_id)
+            decision = check_stack(stack, usages, req)
+            if decision.ok and decision.reservation is not None:
+                self._stacks[stack_id] = (stack, reserve_stack(stack, usages, req))
+                self._open.setdefault(stack_id, set()).add(decision.reservation.id)
+            return decision
+
+    async def settle(self, stack_id: str, reservation: Reservation, actual: Spend) -> None:
+        async with self._lock:
+            if reservation.id not in self._open.setdefault(stack_id, set()):
+                return
+            stack, usages = self._require(stack_id)
+            self._stacks[stack_id] = (stack, settle_stack(stack, usages, reservation, actual))
+            self._open[stack_id].remove(reservation.id)
+
+    async def release(self, stack_id: str, reservation: Reservation) -> None:
+        async with self._lock:
+            if reservation.id not in self._open.setdefault(stack_id, set()):
+                return
+            stack, usages = self._require(stack_id)
+            self._stacks[stack_id] = (stack, release_stack(stack, usages, reservation))
+            self._open[stack_id].remove(reservation.id)
+
+    async def snapshot(self, stack_id: str) -> UsageMap:
+        async with self._lock:
+            return deepcopy(self._require(stack_id)[1])
+
+    def _require(self, stack_id: str) -> tuple[list[Budget], UsageMap]:
+        if stack_id not in self._stacks:
+            raise KeyError(f"Unknown budget stack: {stack_id}")
+        return self._stacks[stack_id]