Histeeria — TypeScript / Node SDK

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

• Zero latency — observe() never blocks; sends run in the background.
• Zero dependencies — uses the platform fetch (Node 18+, browsers, edge).
• Failure silent — transport errors are swallowed; your agent keeps running.

Install

npm install histeeria

Quickstart

import { Histeeria } from "histeeria";

const h = new Histeeria({ apiKey: "hst_live_xxxx" }); // or set HISTEERIA_API_KEY

const response = await yourLLMCall(messages);

h.observe({
  input: messages,
  output: response,
  agentId: "agent_001",
  sessionId: "sess_abc",
  domain: "customer_support",
});

observe() returns immediately. In short-lived processes (serverless, scripts), call await h.flush() before exit to ensure delivery.

Options

| Option | Env var | Default | | ----------- | --------------------- | --------------------------- | | apiKey | HISTEERIA_API_KEY | — | | baseUrl | HISTEERIA_BASE_URL | https://api.histeeria.com | | timeoutMs | — | 5000 | | enabled | — | true | | debug | — | false |

Advanced usage

h.observe({
  input: messages,
  output: response,
  agentId: "agent_001",
  sessionId: "sess_abc",
  domain: "customer_support",
  inputTokens: 1240,
  outputTokens: 340,
  metadata: { userId: "usr_123", channel: "web", resolved: true },
});

Multi-step agents (tracing)

const trace = h.trace({ agentId: "agent_001", sessionId: "sess_abc" });

const step1 = await yourLLMCall(messages);
trace.step("research", { input: messages, output: step1 });

const step2 = await yourLLMCall([...step1, ...followup]);
trace.step("response", { input: step1, output: step2 });

trace.complete({ finalOutput: step2, resolved: true });
await h.flush();

License

Apache-2.0