histeeria 0.1.0

Histeeria SDK — observe and score your AI agent's judgement. Zero latency, zero dependencies.

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

pip install histeeria

Quickstart

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

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)

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

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:

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

License

Apache-2.0