pramiti-agent-finops

Standalone AI agent warehouse cost attribution and cap enforcement. Zero dependencies -- inject any storage backend via the ICostBackend protocol.

Install

pip install pramiti-agent-finops

Quick Start

from pramiti_agent_finops import CapChecker, CapExceededError
from pramiti_agent_finops.backends import InMemoryBackend

backend = InMemoryBackend()
backend.set_cap("ws-1", "agent-1", max_usd=5.0, action="block")
backend.add_cost("ws-1", "agent-1", 6.0)

checker = CapChecker(backend)
try:
    checker.check("ws-1", "agent-1")
except CapExceededError as e:
    print(f"Blocked: {e}")
    # Blocked: Agent 'agent-1' daily warehouse cost cap exceeded: $6.0000 >= $5.0000 limit

Use action="warn" instead of "block" to issue a CapWarning (Python warning) rather than raising an exception.

Enforcement Semantics

check() is a pre-flight check against recorded spend, not a transactional reservation:

• The decision is based on costs/counts already recorded in the backend at check time. An in-flight call is not metered until its cost is recorded, so a single call may exceed the cap by its own cost.
• Concurrent calls that both pass check() before either is recorded can each proceed (check-then-act race). If you need hard atomic enforcement, implement it in your backend (e.g. a conditional UPDATE / reservation) -- this package does not provide it.
• Enforcement granularity is one call: the cap blocks the next call after recorded spend reaches the limit.

The same semantics apply to ActionBudgetChecker (tool-call count budgets).

API

Custom Backend

Implement ICostBackend (structural subtyping via Protocol -- no inheritance required) to use your own storage:

from pramiti_agent_finops.backends import ICostBackend

class MyBackend:
    def get_cap(self, workspace_id: str, agent_id: str) -> dict | None:
        """Return {"max_usd_per_day": float, "action_on_breach": "block"|"warn"} or None."""
        ...

    def get_today_cost(self, workspace_id: str, agent_id: str) -> float:
        """Return total warehouse cost in USD for agent today (midnight UTC to now)."""
        ...

License

MIT -- Pramiti Labs