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

def answer_for(account, credits_debited):
    with ganivra.trace(
        metadata={"channel": "voice", "credits": credits_debited},
        application="support-platform",
        workflow="support_answer",
        feature="support_chatbot",
        customer_id=account.id,
        prompt_id="support_answer",
        prompt_version="v1",
    ):
        return 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 the stable tenant or account identifier already present in each authenticated request as customer_id; customers do not need to be registered with Ganivra first. Configure customer pricing plans separately when you want revenue derived automatically instead of sending revenue_usd per execution. The metadata mapping accepts additional bounded JSON dimensions and is inherited by nested traces. Use pseudonymous identifiers where appropriate.

Pricing rates stay in Ganivra; never look up a plan or calculate revenue in the instrumented request. Subscription and per-execution plans only need customer_id. Token and hybrid plans use the token/execution telemetry captured by the SDK. For a credit/unit plan, also pass the exact usage attribute configured on the plan—credits above—with the units your application already deducted. Ganivra combines that value with the assigned plan's unit rate.

Treat one billable customer action as one trace/execution. If one trace produces multiple model calls, the inherited transaction-level credit value is repeated on the resulting events and counted once. Start a separate trace for each independently billed action.

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.