Metadata-Version: 2.4
Name: pradvion
Version: 0.5.3
Summary: Track AI API costs per client, project, and feature
Home-page: https://pradvion.com
Author: Pradvion
Author-email: Pradvion <hello@pradvion.com>
License: MIT License
        
        Copyright (c) 2026 Pradvion (Pradip Vala)
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://pradvion.com
Project-URL: Documentation, https://pradvion.com/docs
Project-URL: Repository, https://github.com/pradvion/pradvion-python
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
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: home-page
Dynamic: license-file
Dynamic: requires-python

# Pradvion Python SDK

Track AI API costs per client, project, and feature.
Know exactly what to bill each client.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## Installation

```bash
pip install pradvion
```

## Quick Start — monitor()

The fastest integration. One line wraps your AI client.

```python
import pradvion
from openai import OpenAI

pradvion.init(api_key="nx_live_YOUR_KEY")
openai = pradvion.monitor(OpenAI())

# All calls tracked automatically — no other changes needed
response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)
```

## Auto-Instrument (Zero Setup)

The fastest way to add Pradvion to existing code:

```bash
# Install
pip install pradvion

# Preview changes (no files modified)
pradvion-instrument --dry-run

# Apply instrumentation
pradvion-instrument

# Instrument specific file or directory
pradvion-instrument src/
pradvion-instrument app.py

# Remove instrumentation
pradvion-instrument --undo
```

What it adds automatically:

```python
# Before
from openai import OpenAI
client = OpenAI()

# After
import os
import pradvion
pradvion.init(api_key=os.environ.get("PRADVION_API_KEY", ""))
from openai import OpenAI
client = pradvion.monitor(OpenAI())
```

## Context Manager

Tag calls with customer, feature, and environment:

```python
with pradvion.context(
    feature="resume-summarizer",
    customer_id="samsung-001",
    environment="production"
):
    response = openai.chat.completions.create(...)
```

## Real-Time Streaming Cost

See estimated cost as tokens arrive:

```python
def on_cost_update(cost: float):
    print(f"\r~${cost:.6f}", end="", flush=True)

for chunk in client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
    on_token=on_cost_update,  # Called every 5 tokens
):
    print(chunk.choices[0].delta.content or "", end="")
```

## Business Signals

Track what your AI creates, not just what it costs:

```python
# After an AI call creates value, record it
pradvion.signal(
    customer_id="samsung-001",
    event="email_generated",
    quantity=1,
    value=0.05,
    metadata={"type": "outbound_sales"}
)

pradvion.signal("samsung-001", "meeting_booked", value=150.00)
pradvion.signal("samsung-001", "report_generated", quantity=1, value=50.00)
```

## Conversation Tracking

Group multi-turn AI calls into a single conversation session:

```python
conv_id = pradvion.new_conversation()  # "conv_a3f9b2c1d4e5"

with pradvion.context(
    customer_id="samsung-001",
    conversation_id=conv_id
):
    turn1 = openai.chat.completions.create(...)  # both calls
    turn2 = openai.chat.completions.create(...)  # same conv_id
```

## Budget Management

```python
from pradvion.budget import get_budget_tracker

tracker = get_budget_tracker()
tracker.set_limit("samsung-001", monthly_usd=500.0, action="warn")
tracker.record_spend("samsung-001", 0.05)
print(f"Remaining: ${tracker.remaining('samsung-001'):.2f}")
```

## Cost Forecasting

```python
from pradvion.forecast import forecast_monthly

result = forecast_monthly(
    actual_spend=150.00,
    days_elapsed=15,
    budget_limit=500.00,
)

print(f"Projected: ${result.projected_monthly:.2f}/mo")
print(f"Will exceed: {result.will_exceed_budget}")
```

## Compare Models

```python
from pradvion.compare import compare_cost

result = compare_cost(input_tokens=1000, output_tokens=500)
print(f"Cheapest: {result.cheapest.model} — ${result.cheapest.total_cost:.6f}")
print(f"Save ${result.savings_vs_most_expensive:.4f} vs most expensive")
```

## Middleware Pattern (FastAPI)

```python
@app.middleware("http")
async def pradvion_middleware(request, call_next):
    user = get_current_user(request)
    pradvion.set_context(
        customer_id=user.company_id,
        environment="production"
    )
    response = await call_next(request)
    pradvion.clear_context()
    return response
```

## Async Support

```python
async_client = pradvion.monitor(openai.AsyncOpenAI())
response = await async_client.chat.completions.create(...)
```

## Streaming

```python
stream = openai.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content, end="")
# Usage captured automatically from last chunk
```

## Agent / RAG Usage

```python
with pradvion.context(feature="research-agent", customer_id="samsung"):
    # All sub-calls tracked under same context
    search = openai.chat.completions.create(...)
    analyze = openai.chat.completions.create(...)
    report = openai.chat.completions.create(...)
```

## Flush and Shutdown

Auto-flush is on by default (flushes on process exit).
For scripts or graceful shutdown:

```python
pradvion.flush()     # send all pending events now
pradvion.shutdown()  # stop background worker
```

## Zero Data Loss

All events are written to a local SQLite queue (`~/.pradvion/queue.db`)
before being sent to Pradvion. If your process crashes or the API is
unreachable, events are retried automatically on next startup.

## Support

hello@pradvion.com | https://pradvion.com
