Metadata-Version: 2.4
Name: aw-sdk
Version: 1.0.0
Summary: Lightweight drop-in wrapper for the OpenAI Python client that logs telemetry and detects PII risks.
License: MIT
Project-URL: Homepage, https://github.com/agentwatch/agentwatch
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: openai
Requires-Dist: httpx

# AgentWatch: Proactive LLM Governance Platform

AgentWatch is an ultra-low latency API proxy and SDK designed to solve the "runaway agent" problem for enterprise engineering teams. It intercepts, manages, and enforces budget constraints on LLM API requests at the edge, acting as a proactive governance layer between your application and upstream providers like OpenAI and Anthropic.

## The Problem It Solves

As engineering teams adopt autonomous LLM agents (e.g., coding assistants, research bots, recursive planners), they face a critical financial vulnerability: **the runaway loop**. 

If an agent gets stuck in a recursive error-correction loop, it can execute hundreds of API calls per minute. Because each iteration typically appends the previous output to the context window, the token size grows quadratically. This can result in a single stuck agent burning thousands of dollars in minutes—a scenario that passive monitoring tools will only report *after* the budget is already gone.

AgentWatch was built from the ground up to prevent this.

## Core Features

### 1. Session-Aware Identity Tracking
Instead of treating API requests as isolated events, AgentWatch tracks iterative agent loops as **Sessions**.
- Every request is tagged with a `session_id` and an `iteration_index`.
- The cumulative token count for a session is securely computed and maintained server-side in the AgentWatch Global Distributed State. This ensures that even if a local agent process crashes, restarts, or runs in parallel, the session's financial state cannot be bypassed or reset.

### 2. Synchronous Pre-Call Budget Enforcement
AgentWatch acts as a strict financial gatekeeper for agent sessions.
- Developers define a budget ceiling (e.g., `$2.00`) per session via the AgentWatch Python SDK.
- Before any upstream LLM call is made, the SDK performs a sub-millisecond synchronous pre-flight check to the AgentWatch Edge Engine.
- If the session's cumulative token cost exceeds the limit, the SDK instantly blocks the execution and raises an `AgentBudgetExceeded` exception.
- **Fail-Open Resilience:** By default, if the AgentWatch infrastructure experiences downtime, the budget check silently fails open. This ensures our infrastructure never causes a hard outage for your production traffic.

### 3. Inline Anomaly Detection
AgentWatch heuristically detects runaway behavior before the budget is even exhausted.
- The AgentWatch Edge Engine maintains a rolling window of the last 5 iterations for every active session.
- It calculates the token growth ratio synchronously on every ingest request.
- If three consecutive iterations show a `>1.4x` prompt growth—a hallmark signature of a context-appending loop—it asynchronously fires a webhook alert to your security team, adding zero latency to the critical API path.

### 4. Zero-Latency Proxying & Resilient Telemetry
- **Ultra-Low Latency:** The hot path of the proxy only handles authentication, routing, and credential management. 
- **Asynchronous Telemetry:** Payload logging and risk scanning are offloaded to our Async Telemetry Pipeline. The client receives the provider's response immediately.
- **Data Security & Compliance:** Strict data retention policies automatically purge payloads according to your enterprise compliance requirements.

## Python SDK Integration

AgentWatch integrates seamlessly via composition with standard OpenAI client wrappers:

```python
from agentwatch import WatchedOpenAI

client = WatchedOpenAI(
    agentwatch_api_key="your_aw_key",
    agentwatch_project="checkout-service",
    agentwatch_team="payments-eng",
    agentwatch_session_id="ci-run-123",
    agentwatch_session_budget_usd=2.00,  # Strict $2 limit
    agentwatch_enforcement_mode=True
)

# Standard OpenAI API usage
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Refactor this module..."}]
)
```

## Supported Providers

AgentWatch acts as a unified proxy. The client token is never forwarded upstream; AgentWatch seamlessly authenticates the request to the target provider.

- **OpenAI:** Supported fully.
- **Anthropic:** Supported fully.
- **Groq (Meta AI, Llama 3):** Supported fully.
- **Grok (xAI):** Supported fully.
- **Gemini:** Supported fully.
