Ganivra Python SDK

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

Install

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

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

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

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.