Metadata-Version: 2.4
Name: histeeria
Version: 0.1.0
Summary: Histeeria SDK — observe and score your AI agent's judgement. Zero latency, zero dependencies.
Project-URL: Homepage, https://histeeria.com
Project-URL: Documentation, https://histeeria.com/docs
Project-URL: Source, https://github.com/histeeria/histeeria-sdk
Author: Histeeria
License-Expression: Apache-2.0
Keywords: agents,ai,evaluation,llm,monitoring,observability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# Histeeria — Python SDK

Observe and score your AI agent's judgement. Wrap any LLM call, send the
decision, and Histeeria evaluates it asynchronously.

- **Zero latency** — every send is async, fire and forget.
- **Zero dependencies** — standard library only.
- **Failure silent** — if the API is down, your agent keeps running.

## Install

```bash
pip install histeeria
```

## Quickstart

```python
from histeeria import Histeeria

h = Histeeria(api_key="hst_live_xxxx")  # or set HISTEERIA_API_KEY

response = your_llm_call(messages)

h.observe(
    input=messages,            # what went into the agent
    output=response,           # what came out
    agent_id="agent_001",      # which agent
    session_id="sess_abc",     # conversation/session id
    domain="customer_support", # evaluation context
)
```

That's it. `observe()` returns immediately and the decision is delivered in the
background.

## Configuration

| Argument         | Env var               | Default                     |
| ---------------- | --------------------- | --------------------------- |
| `api_key`        | `HISTEERIA_API_KEY`   | —                           |
| `base_url`       | `HISTEERIA_BASE_URL`  | `https://api.histeeria.com` |
| `timeout`        | —                     | `5.0` seconds               |
| `max_queue_size` | —                     | `10000`                     |
| `enabled`        | —                     | `True`                      |
| `debug`          | —                     | `False`                     |

## Advanced usage

```python
h.observe(
    input=messages,
    output=response,
    agent_id="agent_001",
    session_id="sess_abc",
    domain="customer_support",
    input_tokens=1240,
    output_tokens=340,
    metadata={
        "user_id": "usr_123",
        "channel": "web",
        "escalated": False,
        "resolved": True,
        "tags": ["billing", "refund"],
    },
)
```

## Multi-step agents (tracing)

```python
with h.trace(agent_id="agent_001", session_id="sess_abc", domain="general") as trace:
    step1 = your_llm_call(messages)
    trace.step("research", input=messages, output=step1)

    step2 = your_llm_call(step1 + followup)
    trace.step("response", input=step1, output=step2)

    trace.complete(final_output=step2, resolved=True)
```

A trace emits a single decision containing all steps in its metadata.

## Flushing and shutdown

The client flushes automatically at interpreter exit. To flush explicitly
(e.g. in short-lived scripts or serverless functions):

```python
h.flush(timeout=3)   # wait up to 3s for pending sends
h.close()            # flush + stop the background sender
```

You can also use it as a context manager:

```python
with Histeeria(api_key="hst_live_xxxx") as h:
    h.observe(input=messages, output=response)
# flushed on exit
```

## License

Apache-2.0
