Metadata-Version: 2.4
Name: pramiti-agent-finops
Version: 0.2.0
Summary: Standalone AI agent warehouse cost attribution and cap enforcement
License: MIT
Project-URL: Homepage, https://getpramiti.com
Keywords: ai,agent,finops,cost,cap-enforcement,pramiti
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# pramiti-agent-finops

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

## Install

```bash
pip install pramiti-agent-finops
```

## Quick Start

```python
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:

```python
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
