Metadata-Version: 2.4
Name: okovia
Version: 0.1.0
Summary: OkOvia Python SDK — measure the cost and margin of every AI operation from your backends and workers.
Project-URL: Homepage, https://okovia.com
Project-URL: Repository, https://github.com/geomichelon/okovia-python
Author-email: OkOvia <hello@okovia.com>
License: MIT
License-File: LICENSE
Keywords: ai,cost,llm,margin,metering,observability,okovia
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://okovia.com) or the Swift SDK there).

## Install

```bash
pip install okovia
```

## Usage

```python
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

```python
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)

```python
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)

```python
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"),
    ...
)
```

## 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:

```python
from viking_metering import VikingMeteringClient  # still works
```

## License

MIT — free while OkOvia is in beta.
