Metadata-Version: 2.4
Name: pradvion
Version: 1.0.1
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.1; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20.0; extra == "anthropic"
Provides-Extra: all
Requires-Dist: openai>=1.0.1; extra == "all"
Requires-Dist: anthropic>=0.20.0; extra == "all"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Pradvion Python SDK

[![PyPI version](https://img.shields.io/pypi/v/pradvion.svg)](https://pypi.org/project/pradvion)
[![Python](https://img.shields.io/pypi/pyversions/pradvion.svg)](https://pypi.org/project/pradvion)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Track AI API costs by client, feature, and team. Connect every dollar spent to the business outcome behind it — meetings booked, deals closed, reports generated.

**[pradvion.com](https://pradvion.com) · [Docs](https://pradvion.com/docs) · [Dashboard](https://pradvion.com)**

---

## Installation

```bash
pip install pradvion
```

OpenAI and Anthropic are optional extras — install only what you use:

```bash
pip install "pradvion[openai]"       # OpenAI support
pip install "pradvion[anthropic]"    # Anthropic support
pip install "pradvion[all]"          # Both
```

---

## Quick Start

```python
import openai
import pradvion

# Initialize once at startup
pradvion.init(api_key="nx_live_...")

# Wrap your OpenAI client — drop-in replacement
client = pradvion.monitor(openai.OpenAI())

# Tag with business context, then call as normal
with pradvion.context(
    feature="resume-summarizer",
    customer_id="customer-001",   # hashed with SHA-256 before sending
    team="hr-team",
    environment="production",
):
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Summarize this resume"}],
    )
# Cost, tokens, and latency tracked automatically — zero prompt storage
```

Both `pradvion.monitor()` and `pradvion.wrap()` work — they are aliases.

---

## Supported Providers

```python
import openai, anthropic, pradvion

# OpenAI
openai_client   = pradvion.monitor(openai.OpenAI())
async_client    = pradvion.monitor(openai.AsyncOpenAI())  # async supported

# Anthropic
anthropic_client = pradvion.monitor(anthropic.Anthropic())

# Streaming — tokens accumulate correctly across chunks
stream = openai_client.chat.completions.create(model="gpt-4o", messages=[...], stream=True)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")
# Usage tracked automatically from the final chunk
```

---

## Context Tagging

Tag all AI calls within a block. All parameters are optional.

```python
with pradvion.context(
    feature="resume-summarizer",   # what the AI is doing
    team="hr-team",                # team that owns this feature
    department="engineering",      # department-level grouping
    customer_id="customer-001",     # auto-hashed with SHA-256
    environment="production",      # filters out test traffic in analytics
    conversation_id="run-abc-123", # groups multi-step agent calls
    project="my-project",          # optional project tag
):
    response = client.chat.completions.create(...)
```

### FastAPI middleware

Set context once per request so every AI call in that request is tagged:

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

---

## Business Signals

Track the outcomes your AI produces — not just the cost.

```python
# After an AI call creates a downstream result, record the signal
pradvion.signal(
    customer_id="customer-001",   # links back to AI costs for this customer
    event="meeting_booked",      # lowercase, snake_case
    quantity=1,
    value=150.00,                # dollar value of the outcome
    feature="outreach-agent",
    environment="production",
)

# Batch version
pradvion.signal_batch([
    {"customer_id": "my-company", "event": "email_sent",     "quantity": 50},
    {"customer_id": "my-company", "event": "meeting_booked", "quantity": 3, "value": 450.0},
    {"customer_id": "my-company", "event": "deal_closed",    "quantity": 1, "value": 12000.0},
])
```

Pradvion automatically computes **cost per meeting booked**, **margin per customer**, and **ROI per feature** in the Unit Economics dashboard.

---

## Agent / Multi-step Tracking

Group all LLM calls within a single agent run:

```python
run_id = pradvion.new_conversation()  # generates a unique ID

with pradvion.context(
    feature="research-agent",
    customer_id="my-company",
    conversation_id=run_id,
    environment="production",
):
    plan   = client.chat.completions.create(...)   # step 1
    search = client.chat.completions.create(...)   # step 2
    report = client.chat.completions.create(...)   # step 3

# All 3 calls appear in the dashboard linked by conversation_id
# Record the business outcome once the agent completes
if task_completed:
    pradvion.signal("my-company", "report_generated", quantity=1, value=50.0)
```

---

## Manual Tracking

Track calls from providers not yet wrapped:

```python
import time

start = time.monotonic()
try:
    response = my_llm_client.generate(prompt)
    pradvion.get_client().track(
        provider="openai",
        model="gpt-4o",
        input_tokens=response.usage.prompt_tokens,
        output_tokens=response.usage.completion_tokens,
        latency_ms=int((time.monotonic() - start) * 1000),
        status_code=200,
        customer_id="my-company",
        feature="chatbot",
    )
except Exception as e:
    pradvion.track_error(
        provider="openai",
        model="gpt-4o",
        error=str(e),
        status_code=500,
        latency_ms=int((time.monotonic() - start) * 1000),
        customer_id="my-company",
    )
    raise

# Batch version
pradvion.track_batch([
    {"provider": "openai", "model": "gpt-4o",        "input_tokens": 500, "output_tokens": 200, "latency_ms": 800},
    {"provider": "anthropic", "model": "claude-sonnet-4-6", "input_tokens": 300, "output_tokens": 150, "latency_ms": 600},
])
```

---

## Integrations

### LangChain

```python
from langchain_openai import ChatOpenAI
from pradvion.integrations.langchain import PradvionCallback
import pradvion

pradvion.init(api_key="nx_live_...")

callback = PradvionCallback(
    feature="research-chain",
    customer_id="my-company",
    environment="production",
)

# Works with chains, agents, and LCEL runnables
llm = ChatOpenAI(model="gpt-4o", callbacks=[callback])
response = llm.invoke("Summarize this document")
```

### LangGraph

LangGraph uses LangChain under the hood — the same callback works:

```python
from langgraph.graph import StateGraph
from langchain_openai import ChatOpenAI
from pradvion.integrations.langchain import PradvionCallback
import pradvion

pradvion.init(api_key="nx_live_...")
run_id = pradvion.new_conversation()

callback = PradvionCallback(
    feature="research-agent",
    customer_id="my-company",
    conversation_id=run_id,
)

llm = ChatOpenAI(model="gpt-4o", callbacks=[callback])

graph = StateGraph(...)
# ... define nodes and edges ...
graph.invoke(inputs)
```

### LlamaIndex

```python
from llama_index.core import Settings
from llama_index.core.callbacks import CallbackManager
from pradvion.integrations.llamaindex import PradvionLlamaCallback
import pradvion

pradvion.init(api_key="nx_live_...")

callback = PradvionLlamaCallback(
    feature="rag-pipeline",
    customer_id="my-company",
    environment="production",
)

# Set globally — all LlamaIndex pipelines are tracked
Settings.callback_manager = CallbackManager([callback])

index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
response = query_engine.query("What are the main findings?")
```

### OpenTelemetry

```python
from pradvion.integrations.otel import PradvionSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

exporter = PradvionSpanExporter(api_key="nx_live_...")
provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(exporter))

# Pradvion reads GenAI semantic conventions from OTEL spans
# Compatible with: OpenLLMetry, traceloop, Langfuse OTEL, etc.
```

---

## init() Options

```python
pradvion.init(
    api_key="nx_live_...",    # required — from Dashboard → Projects → API Keys
    base_url="https://...",   # optional — default: Pradvion cloud
    timeout=5,                # HTTP timeout in seconds (default: 5)
    async_tracking=True,      # background queue, non-blocking (default: True)
    auto_flush=True,          # flush on process exit (default: True)
)
```

---

## Flush & Shutdown

Auto-flush is on by default (flushes on process exit). In short-lived processes — scripts, Lambda functions, or tests — call flush explicitly:

```python
pradvion.flush(timeout=10.0)  # wait up to 10s for all events to send
pradvion.shutdown()           # flush + stop background worker
```

---

## Privacy

Pradvion is **privacy-first** by design:

- Tracks token counts, model names, and latency — nothing else
- Customer IDs are SHA-256 hashed before leaving your server
- Prompts and responses are **never** captured or transmitted
- All source code is open source and auditable

---

## Requirements

- Python >= 3.9
- No required dependencies — OpenAI and Anthropic are optional extras

---

## Support

- Email: [hello@pradvion.com](mailto:hello@pradvion.com)
- Dashboard: [pradvion.com](https://pradvion.com)
- Docs: [pradvion.com/docs](https://pradvion.com/docs)
- Issues: [GitHub](https://github.com/pradvion/pradvion-python-sdk/issues)

---

## License

MIT — see [LICENSE](LICENSE)
