Metadata-Version: 2.4
Name: ai-control-plane
Version: 2.0.1
Summary: AI Control Plane Python SDK — observability, cost tracking, and analytics for LLM applications
Home-page: https://github.com/Anil175/ai-control-plane
Author: Anil Kumar
Author-email: akrava32@gmail.com
Project-URL: Homepage, https://ai-control-plane.in
Project-URL: Source, https://github.com/Anil175/ai-control-plane
Project-URL: Documentation, https://ai-control-plane.in/docs
Keywords: ai llm observability openai anthropic telemetry cost-tracking agents
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20.0; extra == "anthropic"
Provides-Extra: all
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: anthropic>=0.20.0; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# AI Control Plane — Python SDK

Operational infrastructure for production AI agents. Add observability, cost tracking, and usage analytics to any LLM application with **2 lines of code**.

[![PyPI version](https://img.shields.io/pypi/v/ai-control-plane.svg)](https://pypi.org/project/ai-control-plane/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://pypi.org/project/ai-control-plane/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
pip install ai-control-plane
```

With provider extras:

```bash
pip install ai-control-plane[openai]      # OpenAI support
pip install ai-control-plane[anthropic]   # Anthropic support
pip install ai-control-plane[all]         # All providers
```

## Quick Start

```python
from openai import OpenAI
from acp_sdk import wrap

# Wrap your existing client — that's it
client = wrap(OpenAI(), api_key="acp_live_...", app="my-app")

# Use exactly as before — same interface, zero code changes
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}],
)
```

Every call is now automatically tracked: tokens, cost, latency, and status — shipped asynchronously so your application is never slowed down.

## Features

- **2-line integration** — `import` + `wrap()`, nothing else changes
- **Zero latency overhead** — telemetry ships asynchronously in a background thread
- **Multi-provider** — OpenAI, Anthropic, and Google clients supported
- **Automatic cost tracking** — built-in pricing for GPT-4o, Claude 3.5, and more
- **Rich metadata** — attach user IDs, session IDs, agent IDs, and custom tags
- **Fail-open design** — if telemetry fails, your LLM calls still work
- **Type-safe config** — `ACPConfig` dataclass with environment variable support

## Usage

### OpenAI

```python
from openai import OpenAI
from acp_sdk import wrap

client = wrap(OpenAI(), api_key="acp_live_...", app="my-app")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Explain quantum computing"}],
    _acp_user_id="user_123",
    _acp_session_id="session_abc",
)
```

### Anthropic

```python
import anthropic
from acp_sdk import wrap

client = wrap(anthropic.Anthropic(), api_key="acp_live_...", app="my-app")

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain quantum computing"}],
    _acp_user_id="user_123",
)
```

### Embeddings

```python
from openai import OpenAI
from acp_sdk import wrap

client = wrap(OpenAI(), api_key="acp_live_...", app="my-app")

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="The quick brown fox",
)
```

### ACP Metadata Parameters

Attach metadata to any call using `_acp_` prefixed parameters:

| Parameter | Description |
|-----------|-------------|
| `_acp_user_id` | End-user identifier for per-user analytics |
| `_acp_session_id` | Session/conversation identifier |
| `_acp_agent_id` | Agent identifier (for multi-agent systems) |
| `_acp_run_id` | Run/execution identifier |
| `_acp_tags` | Custom tags dict for filtering and grouping |

```python
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
    _acp_user_id="user_123",
    _acp_session_id="sess_abc",
    _acp_agent_id="agent_research",
    _acp_run_id="run_456",
    _acp_tags={"team": "backend", "feature": "search"},
)
```

### Configuration

```python
from acp_sdk import wrap, ACPConfig

# Option 1: Inline parameters
client = wrap(OpenAI(), api_key="acp_live_...", app="my-app", environment="staging")

# Option 2: Config object
config = ACPConfig(
    api_key="acp_live_...",
    app="my-app",
    environment="production",
    tags={"team": "ml-platform"},
)
client = wrap(OpenAI(), config=config)

# Option 3: Environment variables
# Set ACP_API_KEY, ACP_APP, ACP_ENV, ACP_INGEST_URL
config = ACPConfig.from_env()
client = wrap(OpenAI(), config=config)
```

### Flush Before Exit

The SDK buffers telemetry and sends it in batches. Call `flush()` before your process exits to ensure all events are delivered:

```python
client.flush(timeout=5.0)
```

## What Gets Tracked

Every LLM call automatically captures:

| Field | Description |
|-------|-------------|
| `provider` | openai, anthropic, or google |
| `model_id` | Model name (gpt-4o, claude-3-5-sonnet, etc.) |
| `input_tokens` | Prompt/input token count |
| `output_tokens` | Completion/output token count |
| `cost_usd` | Estimated cost in USD |
| `latency_ms` | End-to-end call duration |
| `status` | success or error |
| `error_message` | Error details (on failure) |

## Requirements

- Python 3.10+
- `httpx >= 0.27.0`
- `pydantic >= 2.0`

## Links

- **Dashboard**: [ai-control-plane.in](https://ai-control-plane.in)
- **Source**: [github.com/Anil175/ai-control-plane](https://github.com/Anil175/ai-control-plane)

## License

MIT
