Metadata-Version: 2.4
Name: nivara
Version: 0.2.5
Summary: DEPRECATED: no longer maintained. Nivara is now Alder (https://meetalder.com).
Author: Nivara Tech
License: Proprietary
Project-URL: Homepage, https://github.com/nivara-tech/sdk
Project-URL: Repository, https://github.com/nivara-tech/sdk
Project-URL: Issues, https://github.com/nivara-tech/sdk/issues
Keywords: metrics,llm,observability,tokens,ai
Classifier: Development Status :: 7 - Inactive
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

> **Deprecated.** This package is no longer maintained and will not receive
> further updates. Nivara is now **Alder**: https://meetalder.com

Nivara — Python Metrics Client
==============================

Lightweight client to record LLM/AI usage metrics to the Nivara Metrics API.
Defaults to background delivery with safe timeouts and optional retries; also
supports a simple synchronous call for one‑off usage.

Environment
-----------

```
export NIVARA_API_KEY="ak_live_..."              # required
export NIVARA_BASE_URL="https://api.getnivara.com"   # optional (default)
```

Quickstart
----------

Install

```
python3 -m pip install nivara
```

Configure (optional; sensible defaults are used):

```python
import nivara as nv

nv.configure(
  timeout=2.0,
  retries=2,
  mode="background",   # or "sync"
  queue_size=10000,
  debug=False,
)
```

Emit a metric (background):

```python
import nivara as nv

nv.emit(
  metric="llm.request",
  user_identifier="end_user_42",
  input_tokens=512,
  output_tokens=238,
  cached_tokens=64,
  reasoning_tokens=0,
)
nv.flush(timeout=2.0)
```

Notes
-----

- Sends only the supported fields; unknown values are omitted.
- Accepts `ts` as RFC3339 string or `datetime` (converted to `Z`).
- Returns `{"status":"ok","http_status":201}` on success; error responses include `error` and `http_status` when available.

Synchronous one‑shot record
---------------------------

```python
from datetime import datetime, timezone
import nivara as nv

nv.record(
  metric="llm.request",
  ts=datetime.now(timezone.utc),   # optional; server uses now() if omitted
  input_tokens=100,
  output_tokens=20,
)
```

Helpers
-------

- `nivara.from_openai(response, user_identifier=None)` — map OpenAI usage to emit kwargs:

```python
resp = client.responses.create(model="gpt-4o-mini", input="hi")
nv.emit(metric="llm.request", **nv.from_openai(resp))
```

Lifecycle
---------

- `nv.flush(timeout=5.0)` — wait for the background queue to drain.
- `nv.close()` — stop the worker.
- `nv.stats()` — returns `{ queued, sent, failed, last_error }`.

API Reference
-------------

- `configure(base_url=None, api_key=None, timeout=2.0, retries=0, mode="background", queue_size=10000, debug=False)`
  - Sets global behavior; starts a background worker when `mode="background"`.
  - Use to enable retries or tune queue/timeout; otherwise safe defaults apply.

- `emit(*, metric, ts=None, user_identifier=None, input_tokens=None, output_tokens=None, cached_tokens=None, reasoning_tokens=None, timeout=None, sample_rate=1.0) -> dict`
  - Background enqueue; returns `{"status":"queued"}` or `{"status":"sampled_out"}`.
  - Drops events probabilistically when `sample_rate < 1.0`.

- `record(*, metric, ts=None, user_identifier=None, input_tokens=None, output_tokens=None, cached_tokens=None, reasoning_tokens=None, timeout=None) -> dict`
  - Synchronous send; returns server JSON such as `{"status":"ok","http_status":201}`.

- `set_user(user_identifier: str | None) -> None`
  - Sets/clears a default end‑user label used when `user_identifier` is omitted.

- `from_openai(response, *, user_identifier=None) -> dict`
  - Extracts token usage fields from an OpenAI Responses API object for `emit/record`.

- `flush(timeout=None) -> bool` | `close() -> None` | `stats() -> dict`
  - Drain queue, stop worker, inspect counters (`queued/sent/failed/last_error`).

Parameters
----------
- `metric` (str, required): e.g., `"llm.request"`.
- `ts` (datetime | RFC3339 string, optional): omit to let the server set it.
- `user_identifier` (str, optional): end‑user label you provide.
- `input_tokens`, `output_tokens`, `cached_tokens`, `reasoning_tokens` (int ≥ 0, optional).
- `timeout` (float, optional): per‑request override.
- `sample_rate` (float 0..1): client‑side sampling on `emit`.

Behavior Notes
--------------
- Only supported fields are sent; unknown values are omitted.
- Datetime values are converted to RFC3339 with `Z` (UTC).
- Retries (408/429/5xx) apply when configured via `configure(retries=...)`.

Example script
--------------

Run a minimal OpenAI demo and record usage:

```
export OPENAI_API_KEY=sk-...
export NIVARA_API_KEY=ak_live_...
python3 -m pip install nivara
python3 examples/openai_demo.py --prompt "hello there"
```

More docs
---------

- nivara-sdk-docs/ — developer docs (install, API, examples, troubleshooting)
- docs/index.md — legacy docs entry point

Development
-----------

If you’re working on this repo locally:

```
python3 -m pip install -e .
```

License
-------

Proprietary to Nivara Tech, (c) 2025.
