okovia 0.2.0

OkOvia Python SDK — measure the cost and margin of every AI operation from your backends and workers.

okovia — OkOvia Python SDK

Measure the cost and margin of every AI operation from your backends, workers, queues, and AI-infrastructure code. OkOvia prices each model call and GPU-second and attributes it to a product operation.

Server-side only — use a secret (vik_sec_…) or ingest-only (vik_ing_…) key. Never ship this in a browser or mobile app (use the web tag or the Swift SDK there).

Install

pip install okovia

Usage

from okovia import OkoviaClient

client = OkoviaClient(
    secret_key="vik_sec_xxx",
    project_id="project_123",
    endpoint="https://api.okovia.com",
)

client.record_usage(
    operation_id="op_checkout_7K9x",
    provider="openai",
    model_name="gpt-4o",
    input_tokens=1200,
    output_tokens=300,
    cache_write_tokens=2048,   # cost-category fields the pricing engine uses
    reasoning_tokens=128,
    stream_status="complete",
)

Time a step automatically

with client.step(operation_id="op_1", step_name="rag", provider="openai") as step:
    result = call_your_llm()
    step.add_metric("input_tokens", result.usage.input_tokens)
    step.add_metric("output_tokens", result.usage.output_tokens)
# an unhandled exception inside the block marks the event status="error"

Correlate browser context with backend usage (FastAPI/Starlette)

from okovia import OkoviaCorrelationMiddleware, current_operation_id

app.add_middleware(OkoviaCorrelationMiddleware)
# ... then in a request handler:
client.record_usage(operation_id=current_operation_id() or "op_fallback", ...)

On-device hashing for recommendations (privacy-safe)

from okovia import hash_prompt_prefix

# Salted digest of the repeated prompt prefix — content never leaves the
# process; only the hash is sent. Feeds the "prompt caching off" rule.
client.record_usage(
    operation_id="op_1",
    prompt_prefix_hash=hash_prompt_prefix(prompt, salt="your-project-salt"),
    ...
)

Command line (okovia)

Installing the package also installs the okovia CLI — for the places SDKs don't reach naturally: shell scripts, cron jobs, CI pipelines, GPU batch workers.

export OKOVIA_INGEST_KEY="vik_ing_..."
export OKOVIA_PROJECT_ID="..."
export OKOVIA_ENDPOINT="https://api.okovia.com"

okovia doctor --send-test      # validate credentials + connectivity end to end

okovia track --provider openai --model gpt-4o \
             --input-tokens 1200 --output-tokens 340 --feature nightly_batch

okovia track --gpu-seconds 142.5 --provider runpod --model a100 \
             --feature training_job                 # unit type is inferred

okovia costs                   # cost by feature, straight from the API

track infers the unit type from the flags you pass (tokens → tokens, --gpu-seconds → GPU, --images → image generation, none → api_call) and prints the ingestion result as JSON, so it composes with jq.

Privacy

Prompts and completions are never collected. Only usage metadata and salted hashes leave your process; sensitive fields are rejected client-side before sending.

Compatibility

The historical viking_metering package and VikingMeteringClient name remain importable for existing code:

from viking_metering import VikingMeteringClient  # still works

License

MIT — free while OkOvia is in beta.