Metadata-Version: 2.4
Name: ganivra
Version: 0.1.0
Summary: AI execution cost and unit-economics telemetry for the OpenAI Python SDK
Project-URL: Homepage, https://ganivra.com
Project-URL: Documentation, https://ganivra.com
Author: Ganivra
License-Expression: MIT
License-File: LICENSE
Keywords: ai,cost,llm,observability,openai,unit-economics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: openai>=1.50
Provides-Extra: release
Requires-Dist: build>=1.2; extra == 'release'
Requires-Dist: twine>=6.0; extra == 'release'
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# Ganivra Python SDK

Ganivra measures the cost and unit economics of AI executions without proxying
model traffic or storing prompts and responses.

## Install

```bash
python -m pip install ganivra
```

Ganivra requires Python 3.10 or newer and currently instruments synchronous
OpenAI Responses API calls.

## Initialize before creating the OpenAI client

```python
import ganivra
from openai import OpenAI

ganivra.init(api_key="gv_live_your_workspace_key")
client = OpenAI()

response = client.responses.create(
    model="gpt-5",
    input="Explain our refund policy simply.",
)
```

Initialization automatically captures model, input/output/cached token counts,
latency, status, error type, and environment. Ganivra creates execution and step
IDs and exports the metadata on a bounded background queue.

## Add business context for unit economics

```python
with ganivra.trace(
    workflow="support_answer",
    feature="support_chatbot",
    customer_id="acme",
    prompt_id="support_answer",
    prompt_version="v1",
    revenue_usd=0.10,
):
    response = client.responses.create(
        model="gpt-5",
        input="Explain our refund policy simply.",
    )
```

Trace metadata is optional. It enables customer, feature, workflow, prompt, and
margin reporting. Use pseudonymous identifiers where appropriate.

## Configuration

```python
ganivra.init(
    api_key="gv_live_your_workspace_key",
    endpoint="https://api.ganivra.com",
    environment="production",
    queue_size=1000,
    batch_size=20,
    timeout_seconds=2.0,
    max_retries=2,
)
```

For local Ganivra development, set `endpoint="http://127.0.0.1:8000"`.
Call `ganivra.flush()` in short-lived scripts when you want to wait briefly for
queued telemetry.

## Privacy and failure behavior

- OpenAI requests continue going directly from your application to OpenAI.
- Prompt and response bodies are never collected.
- OpenAI API keys are never collected.
- Telemetry failures never change the OpenAI result or exception your code sees.
- A full queue or unavailable Ganivra endpoint drops telemetry instead of
  blocking the application.

Prefer the language-independent REST API when automatic Python instrumentation
is not appropriate. The canonical API contract is documented at
`docs/API.md` in the Ganivra project.
