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"},
        application="support-platform",
        workflow="support_answer",
        feature="support_chatbot",
        customer_id=account.id,
        plan_key=account.plan_key,
        credits=credits_debited,
        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 rate 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. Send plan_key when customers can choose or change plans without a manual Ganivra assignment. Ganivra combines the plan and credit usage with the rate configured in your workspace.

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.

Track MCP tool calls through the same API

Ganivra 0.4 adds ganivra.mcp_call(...). It uses the same API key, background queue, batching, retries, /v1/events endpoint, and active trace as automatic model instrumentation. The helper measures latency and outcome around the tool call but never receives or inspects its arguments or result.

import ganivra

with ganivra.trace(
    application="customer-operations-platform",
    workflow="lead_qualification",
    feature="sales_agent",
    customer_id=account.id,
) as execution:
    with ganivra.mcp_call(
        server="crm-server",
        tool="search_accounts",
        transport="streamable_http",
        auth_type="oauth",
        metadata={
            "result_count": 3,
            "cache_hit": False,
            "region": "us-east",
        },
        provider_reported_cost_usd=0.002,
    ) as tool_call:
        result = mcp_client.call_tool("search_accounts", arguments)

The emitted MCP event shares execution.execution_id with model calls inside the surrounding trace. On success it records status="success"; if the tool raises, Ganivra records only the exception class as error_type and re-raises the original exception unchanged.

Link a model call caused by an MCP result

Shared execution_id is sufficient for execution-level cost attribution. When you also need an explicit parent-child edge, use the yielded MCP step_id as the next trace's parent_step_id:

with ganivra.trace(
    execution_id=execution.execution_id,
    parent_step_id=tool_call.step_id,
):
    response = client.responses.create(
        model="gpt-5",
        input=build_model_input(result),
    )

The OpenAI event remains a normal model event with no event_type; only the MCP tool event sends event_type="mcp".

MCP helper parameters

Do not place tool arguments, tool results, prompts, responses, OAuth scopes, workspace IDs, tokens, secrets, personal data, or request/response bodies in metadata. Ganivra rejects these content-bearing fields at ingestion.

MCP cost behavior

• If the MCP provider returns an exact cost, pass it through provider_reported_cost_usd.
• If a tool has a fixed contract rate, configure provider mcp, model <server>/<tool>, and a request component rate in Ganivra.
• Send provider_reported_cost_usd=0 only for a confirmed free tool call.
• If no exact cost or rate exists, omit cost. Ganivra marks the step unpriced rather than silently treating unknown cost as zero.

When not to use the Python helper

Use the REST event contract directly when MCP calls happen in Node.js, Java, Go, another service, or existing middleware that already measures tool calls. Do not duplicate the event from both the Python helper and REST integration; if retries are possible, keep one stable event_id in the direct REST path.

Record confirmed purchases (optional)

Event telemetry works on its own and provides AI cost plus plan-rated unit economics. After your payment webhook is verified and your application has updated the customer's credits or subscription, optionally send the confirmed financial transaction so Ganivra can reconcile plan-rated revenue with payment actuals.

result = ganivra.transactions.create(
    external_id=payment_intent.id,  # stable provider ID; retries are idempotent
    customer_id=account.id,
    transaction_type="credit_purchase",
    amount=3999,
    currency="INR",
    amount_usd=47,
    units_purchased=1000,
    plan_key="growth",
    source="stripe",
)

For USD, send only amount and currency="USD". For another currency, send exactly one of amount_usd or exchange_rate_to_usd. Use transaction_type="subscription_payment" for renewals and transaction_type="refund" for refunds. Include execution_id when a payment belongs to a particular AI result. This call is synchronous and raises ganivra.GanivraAPIError if Ganivra does not accept the transaction; only call it after your own payment and entitlement updates succeed.

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.