@sensu-ai/sdk 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,129 @@
+# @sensu-ai/sdk
+
+The official Node.js SDK for [Sensu](https://sensu-ai.com) — observability for AI agents.
+
+Instrument your agents to track LLM calls, tool use, token spend, latency, and cost. Events are buffered and sent in batches so there's no impact on your agent's performance.
+
+## Installation
+
+```bash
+npm install @sensu-ai/sdk
+```
+
+## Quick start
+
+```ts
+import { SensuClient } from '@sensu-ai/sdk';
+
+const sensu = new SensuClient({
+  apiKey: process.env.SENSU_API_KEY,
+  agentId: 'my-agent',
+});
+
+const run = sensu.startRun();
+const step = run.startStep({ name: 'plan' });
+
+// Wrap an LLM call — latency and token usage are captured automatically
+const response = await step.trackLlm({
+  provider: 'anthropic',
+  model: 'claude-sonnet-4-6',
+  fn: () => anthropic.messages.create({ ... }),
+});
+
+// Wrap a tool call
+const result = await step.trackTool({
+  toolName: 'search_web',
+  fn: () => searchWeb(query),
+});
+
+await step.end();
+await run.end();
+```
+
+## Configuration
+
+```ts
+const sensu = new SensuClient({
+  apiKey: 'sns_live_...',   // Required. Your Sensu API key
+  agentId: 'my-agent',      // Required. Identifies this agent in the dashboard
+  baseUrl: 'https://...',   // Default: http://localhost:3001
+  orgId: '',                // Optional. Populated automatically from your API key
+  batchSize: 10,            // Flush after N events (default: 10)
+  flushIntervalMs: 2000,    // Flush every N ms (default: 2000)
+  disabled: false,          // Set true to disable all telemetry (e.g. in tests)
+});
+```
+
+You can also load config from environment variables:
+
+```ts
+const sensu = new SensuClient({ fromEnv: true });
+```
+
+| Variable | Description |
+|---|---|
+| `SENSU_API_KEY` | Your Sensu API key |
+| `SENSU_AGENT_ID` | Agent identifier |
+| `SENSU_BASE_URL` | API base URL |
+| `SENSU_ORG_ID` | Organisation ID (optional) |
+
+## API
+
+### `SensuClient`
+
+| Method | Description |
+|---|---|
+| `startRun(opts?)` | Start a new agent run. Returns a `RunHandle`. |
+| `flush()` | Manually flush buffered events to the API. |
+| `destroy()` | Stop the background flush timer. |
+
+### `RunHandle`
+
+| Method | Description |
+|---|---|
+| `startStep(opts?)` | Start a step within the run. Returns a `StepHandle`. |
+| `end(status?)` | End the run. `status` is `'completed'` (default) or `'failed'`. |
+
+### `StepHandle`
+
+| Method | Description |
+|---|---|
+| `trackLlm(opts)` | Wrap an LLM call — measures latency and extracts token usage from the response. |
+| `recordLlm(opts)` | Emit a raw LLM event when you already have the stats. |
+| `trackTool(opts)` | Wrap a tool call — measures latency and output size. |
+| `end()` | End the step. |
+
+## Integrations
+
+### OpenAI
+
+Wrap the OpenAI client to track all completions automatically:
+
+```ts
+import { wrapOpenAI } from '@sensu-ai/sdk/integrations/openai';
+import OpenAI from 'openai';
+
+const openai = wrapOpenAI(new OpenAI({ apiKey }), {
+  client: sensu,
+  runHandle: run,
+});
+
+// All calls to openai.chat.completions.create() are now tracked
+const response = await openai.chat.completions.create({ model: 'gpt-4o', ... });
+```
+
+### LangChain
+
+```ts
+import { SensuCallbackHandler } from '@sensu-ai/sdk/integrations/langchain';
+
+const handler = new SensuCallbackHandler({ client: sensu, runHandle: run });
+const chain = new LLMChain({ llm, prompt, callbacks: [handler] });
+```
+
+## Supported models (cost estimation)
+
+The SDK automatically estimates cost for the following models:
+
+- Anthropic: `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5`, `claude-3-5-sonnet`, `claude-3-5-haiku`, `claude-3-opus`
+- OpenAI: `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sensu-ai/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
@@ -25,7 +25,11 @@
     "openai": ">=4.0.0"
   },
   "peerDependenciesMeta": {
-    "langchain": { "optional": true },
-    "openai": { "optional": true }
+    "langchain": {
+      "optional": true
+    },
+    "openai": {
+      "optional": true
+    }
   }
 }

package/src/client.ts

@@ -7,6 +7,7 @@ import type {
   TrackLlmOptions,
   TrackToolOptions,
   RawLlmCallOptions,
+  ContextBreakdown,
 } from './types.js';
 
 // ---------------------------------------------------------------------------
@@ -96,6 +97,7 @@ export class StepHandle {
 
     // Try to extract token usage from common response shapes
     const usage = extractUsage(result, opts.model);
+    const contextBreakdown = opts.extractContextBreakdown?.(result);
 
     this.client.enqueue({
       ...this.base(),
@@ -107,6 +109,7 @@ export class StepHandle {
       latency_ms: latencyMs,
       status,
       ...usage,
+      ...(contextBreakdown ? { context_breakdown: contextBreakdown } : {}),
     });
 
     if (err) throw err;
@@ -115,10 +118,12 @@ export class StepHandle {
 
   /** Emit a raw LLM call event (when you have the stats already) */
   recordLlm(opts: RawLlmCallOptions): void {
+    const { contextBreakdown, ...rest } = opts;
     this.client.enqueue({
       ...this.base(),
       event_type: 'llm.request.completed',
-      ...opts,
+      ...rest,
+      ...(contextBreakdown ? { context_breakdown: contextBreakdown } : {}),
     });
   }
 

package/src/index.ts

@@ -6,4 +6,5 @@ export type {
   TrackLlmOptions,
   TrackToolOptions,
   RawLlmCallOptions,
+  ContextBreakdown,
 } from './types.ts';

package/src/types.ts

@@ -27,12 +27,25 @@ export interface StartStepOptions {
   stepId?: string;
 }
 
+export interface ContextBreakdown {
+  system_tokens?: number;
+  user_tokens?: number;
+  assistant_tokens?: number;
+  tool_tokens?: number;
+  retrieval_tokens?: number;
+}
+
 export interface TrackLlmOptions {
   provider: string;
   model: string;
   /** Wraps the LLM call and measures latency automatically */
   fn: () => Promise<unknown>;
   maxContextTokens?: number;
+  /**
+   * Optional callback to extract a context breakdown from the LLM response.
+   * Called with the raw response after fn() resolves.
+   */
+  extractContextBreakdown?: (result: unknown) => ContextBreakdown | undefined;
 }
 
 export interface LlmResult {
@@ -62,4 +75,5 @@ export interface RawLlmCallOptions {
   ttftMs?: number;
   costUsdEstimate?: number;
   status?: 'success' | 'error' | 'timeout';
+  contextBreakdown?: ContextBreakdown;
 }