pramiti-agent-finops 0.2.0

Standalone AI agent warehouse cost attribution and cap enforcement

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.

API

Export	Description
CapChecker	Core enforcement engine. Inject any ICostBackend. Call check() to enforce and get_today_cost() to query.
ICostBackend	Protocol for storage backends. Requires get_cap() and get_today_cost().
InMemoryBackend	In-memory backend for testing and development. Provides set_cap(), add_cost(), reset_cost().
CapExceededError	Raised when an agent exceeds its daily cost cap (action="block").
CapWarning	Python UserWarning issued when cap exceeded with action="warn".

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