histeeria 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# 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
+
+```bash
+npm install histeeria
+```
+
+## Quickstart
+
+```typescript
+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
+
+```typescript
+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)
+
+```typescript
+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

package/dist/index.cjs

@@ -0,0 +1,151 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Histeeria: () => Histeeria,
+  Trace: () => Trace,
+  VERSION: () => VERSION,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var VERSION = "0.1.0";
+var DEFAULT_BASE_URL = "https://api.histeeria.com";
+function resolveEnv(key) {
+  if (typeof process !== "undefined" && process.env) {
+    return process.env[key];
+  }
+  return void 0;
+}
+function asString(value) {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+var Trace = class {
+  constructor(client, options) {
+    this.client = client;
+    this.options = options;
+    this.steps = [];
+    this.completed = false;
+  }
+  step(name, io = {}) {
+    this.steps.push({ name, input: io.input, output: io.output });
+    return this;
+  }
+  complete(opts = {}) {
+    if (this.completed) return;
+    this.completed = true;
+    const metadata = {
+      ...this.options.metadata ?? {},
+      ...opts.metadata ?? {},
+      steps: this.steps
+    };
+    if (opts.resolved !== void 0) metadata.resolved = opts.resolved;
+    const finalOutput = opts.finalOutput !== void 0 ? opts.finalOutput : this.steps.length ? this.steps[this.steps.length - 1].output : "";
+    this.client.observe({
+      input: { steps: this.steps },
+      output: finalOutput ?? "",
+      agentId: this.options.agentId,
+      sessionId: this.options.sessionId,
+      domain: this.options.domain,
+      metadata
+    });
+  }
+};
+var Histeeria = class {
+  constructor(options = {}) {
+    this.pending = /* @__PURE__ */ new Set();
+    this.apiKey = options.apiKey ?? resolveEnv("HISTEERIA_API_KEY") ?? "";
+    this.baseUrl = (options.baseUrl ?? resolveEnv("HISTEERIA_BASE_URL") ?? DEFAULT_BASE_URL).replace(
+      /\/+$/,
+      ""
+    );
+    this.timeoutMs = options.timeoutMs ?? 5e3;
+    this.debug = options.debug ?? false;
+    this.enabled = (options.enabled ?? true) && Boolean(this.apiKey);
+    if (!this.apiKey && (options.enabled ?? true) && this.debug) {
+      console.warn("[histeeria] no API key provided; observations will be dropped.");
+    }
+  }
+  /** Record one agent decision. Returns immediately (fire and forget). */
+  observe(params) {
+    if (!this.enabled) return;
+    const payload = {
+      agent_id: params.agentId ?? null,
+      session_id: params.sessionId ?? null,
+      domain: params.domain ?? null,
+      input: params.input,
+      output: asString(params.output),
+      metadata: params.metadata ?? null,
+      input_tokens: params.inputTokens ?? null,
+      output_tokens: params.outputTokens ?? null,
+      sdk_version: VERSION
+    };
+    const task = this.send(payload).catch((err) => {
+      if (this.debug) console.warn("[histeeria] ingest error:", err);
+    });
+    this.pending.add(task);
+    void task.finally(() => this.pending.delete(task));
+  }
+  trace(options = {}) {
+    return new Trace(this, options);
+  }
+  /** Await all in-flight sends. Call before a short-lived process exits. */
+  async flush() {
+    await Promise.allSettled(Array.from(this.pending));
+  }
+  async send(payload) {
+    if (typeof fetch !== "function") {
+      if (this.debug) console.warn("[histeeria] global fetch unavailable; skipping send.");
+      return;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await fetch(`${this.baseUrl}/v1/ingest`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`,
+          "User-Agent": `histeeria-js/${VERSION}`
+        },
+        body: JSON.stringify(payload),
+        signal: controller.signal
+      });
+      if (!res.ok && this.debug) {
+        const body = await res.text().catch(() => "");
+        console.warn(`[histeeria] ingest failed ${res.status}: ${body}`);
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+var index_default = Histeeria;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Histeeria,
+  Trace,
+  VERSION
+});

package/dist/index.d.cts

@@ -0,0 +1,68 @@
+/**
+ * Histeeria — TypeScript/Node SDK.
+ *
+ * Observe and score your AI agent's judgement.
+ *   - Zero latency:      observe() never blocks; sends happen in the background.
+ *   - Zero dependencies: uses the platform fetch (Node 18+, browsers, edge).
+ *   - Failure silent:    transport errors are swallowed; your agent keeps running.
+ */
+declare const VERSION = "0.1.0";
+interface HisteeriaOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Default 5000. */
+    timeoutMs?: number;
+    /** Set false to make the SDK a no-op (useful in tests/local). */
+    enabled?: boolean;
+    /** Log transport errors to console. Default false. */
+    debug?: boolean;
+}
+interface ObserveParams {
+    input: unknown;
+    output: unknown;
+    agentId?: string;
+    sessionId?: string;
+    domain?: string;
+    metadata?: Record<string, unknown>;
+    inputTokens?: number;
+    outputTokens?: number;
+}
+interface TraceOptions {
+    agentId?: string;
+    sessionId?: string;
+    domain?: string;
+    metadata?: Record<string, unknown>;
+}
+declare class Trace {
+    private readonly client;
+    private readonly options;
+    private steps;
+    private completed;
+    constructor(client: Histeeria, options: TraceOptions);
+    step(name: string, io?: {
+        input?: unknown;
+        output?: unknown;
+    }): this;
+    complete(opts?: {
+        finalOutput?: unknown;
+        resolved?: boolean;
+        metadata?: Record<string, unknown>;
+    }): void;
+}
+declare class Histeeria {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    readonly enabled: boolean;
+    private readonly debug;
+    private readonly pending;
+    constructor(options?: HisteeriaOptions);
+    /** Record one agent decision. Returns immediately (fire and forget). */
+    observe(params: ObserveParams): void;
+    trace(options?: TraceOptions): Trace;
+    /** Await all in-flight sends. Call before a short-lived process exits. */
+    flush(): Promise<void>;
+    private send;
+}
+
+export { Histeeria, type HisteeriaOptions, type ObserveParams, Trace, type TraceOptions, VERSION, Histeeria as default };

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Histeeria — TypeScript/Node SDK.
+ *
+ * Observe and score your AI agent's judgement.
+ *   - Zero latency:      observe() never blocks; sends happen in the background.
+ *   - Zero dependencies: uses the platform fetch (Node 18+, browsers, edge).
+ *   - Failure silent:    transport errors are swallowed; your agent keeps running.
+ */
+declare const VERSION = "0.1.0";
+interface HisteeriaOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Default 5000. */
+    timeoutMs?: number;
+    /** Set false to make the SDK a no-op (useful in tests/local). */
+    enabled?: boolean;
+    /** Log transport errors to console. Default false. */
+    debug?: boolean;
+}
+interface ObserveParams {
+    input: unknown;
+    output: unknown;
+    agentId?: string;
+    sessionId?: string;
+    domain?: string;
+    metadata?: Record<string, unknown>;
+    inputTokens?: number;
+    outputTokens?: number;
+}
+interface TraceOptions {
+    agentId?: string;
+    sessionId?: string;
+    domain?: string;
+    metadata?: Record<string, unknown>;
+}
+declare class Trace {
+    private readonly client;
+    private readonly options;
+    private steps;
+    private completed;
+    constructor(client: Histeeria, options: TraceOptions);
+    step(name: string, io?: {
+        input?: unknown;
+        output?: unknown;
+    }): this;
+    complete(opts?: {
+        finalOutput?: unknown;
+        resolved?: boolean;
+        metadata?: Record<string, unknown>;
+    }): void;
+}
+declare class Histeeria {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    readonly enabled: boolean;
+    private readonly debug;
+    private readonly pending;
+    constructor(options?: HisteeriaOptions);
+    /** Record one agent decision. Returns immediately (fire and forget). */
+    observe(params: ObserveParams): void;
+    trace(options?: TraceOptions): Trace;
+    /** Await all in-flight sends. Call before a short-lived process exits. */
+    flush(): Promise<void>;
+    private send;
+}
+
+export { Histeeria, type HisteeriaOptions, type ObserveParams, Trace, type TraceOptions, VERSION, Histeeria as default };

package/dist/index.js

@@ -0,0 +1,124 @@
+// src/index.ts
+var VERSION = "0.1.0";
+var DEFAULT_BASE_URL = "https://api.histeeria.com";
+function resolveEnv(key) {
+  if (typeof process !== "undefined" && process.env) {
+    return process.env[key];
+  }
+  return void 0;
+}
+function asString(value) {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+var Trace = class {
+  constructor(client, options) {
+    this.client = client;
+    this.options = options;
+    this.steps = [];
+    this.completed = false;
+  }
+  step(name, io = {}) {
+    this.steps.push({ name, input: io.input, output: io.output });
+    return this;
+  }
+  complete(opts = {}) {
+    if (this.completed) return;
+    this.completed = true;
+    const metadata = {
+      ...this.options.metadata ?? {},
+      ...opts.metadata ?? {},
+      steps: this.steps
+    };
+    if (opts.resolved !== void 0) metadata.resolved = opts.resolved;
+    const finalOutput = opts.finalOutput !== void 0 ? opts.finalOutput : this.steps.length ? this.steps[this.steps.length - 1].output : "";
+    this.client.observe({
+      input: { steps: this.steps },
+      output: finalOutput ?? "",
+      agentId: this.options.agentId,
+      sessionId: this.options.sessionId,
+      domain: this.options.domain,
+      metadata
+    });
+  }
+};
+var Histeeria = class {
+  constructor(options = {}) {
+    this.pending = /* @__PURE__ */ new Set();
+    this.apiKey = options.apiKey ?? resolveEnv("HISTEERIA_API_KEY") ?? "";
+    this.baseUrl = (options.baseUrl ?? resolveEnv("HISTEERIA_BASE_URL") ?? DEFAULT_BASE_URL).replace(
+      /\/+$/,
+      ""
+    );
+    this.timeoutMs = options.timeoutMs ?? 5e3;
+    this.debug = options.debug ?? false;
+    this.enabled = (options.enabled ?? true) && Boolean(this.apiKey);
+    if (!this.apiKey && (options.enabled ?? true) && this.debug) {
+      console.warn("[histeeria] no API key provided; observations will be dropped.");
+    }
+  }
+  /** Record one agent decision. Returns immediately (fire and forget). */
+  observe(params) {
+    if (!this.enabled) return;
+    const payload = {
+      agent_id: params.agentId ?? null,
+      session_id: params.sessionId ?? null,
+      domain: params.domain ?? null,
+      input: params.input,
+      output: asString(params.output),
+      metadata: params.metadata ?? null,
+      input_tokens: params.inputTokens ?? null,
+      output_tokens: params.outputTokens ?? null,
+      sdk_version: VERSION
+    };
+    const task = this.send(payload).catch((err) => {
+      if (this.debug) console.warn("[histeeria] ingest error:", err);
+    });
+    this.pending.add(task);
+    void task.finally(() => this.pending.delete(task));
+  }
+  trace(options = {}) {
+    return new Trace(this, options);
+  }
+  /** Await all in-flight sends. Call before a short-lived process exits. */
+  async flush() {
+    await Promise.allSettled(Array.from(this.pending));
+  }
+  async send(payload) {
+    if (typeof fetch !== "function") {
+      if (this.debug) console.warn("[histeeria] global fetch unavailable; skipping send.");
+      return;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await fetch(`${this.baseUrl}/v1/ingest`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`,
+          "User-Agent": `histeeria-js/${VERSION}`
+        },
+        body: JSON.stringify(payload),
+        signal: controller.signal
+      });
+      if (!res.ok && this.debug) {
+        const body = await res.text().catch(() => "");
+        console.warn(`[histeeria] ingest failed ${res.status}: ${body}`);
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+var index_default = Histeeria;
+export {
+  Histeeria,
+  Trace,
+  VERSION,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "histeeria",
+  "version": "0.1.0",
+  "description": "Histeeria SDK — observe and score your AI agent's judgement. Zero latency, zero dependencies.",
+  "license": "Apache-2.0",
+  "author": "Histeeria",
+  "homepage": "https://histeeria.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/histeeria/histeeria-sdk.git",
+    "directory": "typescript"
+  },
+  "keywords": [
+    "llm",
+    "agents",
+    "observability",
+    "evaluation",
+    "ai",
+    "monitoring"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  }
+}