@agent-ledger/sdk-ts 0.0.3 → 0.0.4

package/README.md

@@ -1,6 +1,29 @@
 # @agent-ledger/sdk-ts
 
-Official TypeScript client for Agent Ledger. The SDK instruments your agents so you can stream sessions, log LLM/tool activity, and enforce budget guardrails against the Agent Ledger API.
+Official TypeScript client for Agent Ledger. Use it to instrument any Node.js/Edge agent with structured telemetry, stream session events, and receive immediate feedback when budget guardrails block spending.
+
+## Table of contents
+
+1. [Features](#features)
+2. [Installation](#installation)
+3. [Runtime requirements](#runtime-requirements)
+4. [Getting started](#getting-started)
+5. [Session lifecycle](#session-lifecycle)
+6. [Event reference](#event-reference)
+7. [API reference](#api-reference)
+8. [Error handling](#error-handling)
+9. [Configuration & environments](#configuration--environments)
+10. [Recipes](#recipes)
+11. [Testing & local dev](#testing--local-dev)
+12. [License](#license)
+
+## Features
+
+- Minimal, dependency-free client that speaks directly to the Agent Ledger REST API (`/v1/sessions` and `/v1/events`).
+- First-class TypeScript typings for every event structure (`LlmCallEvent`, `ToolCallEvent`, `ToolResultEvent`).
+- Built-in budget guardrail awareness through `BudgetGuardrailError` so you can halt expensive runs immediately.
+- Works anywhere `fetch` is available (Node.js 18+, Bun, Deno, Edge runtimes, or browsers talking to your own proxy).
+- Simple abstractions so you can reuse the same instrumentation across CLI scripts, background workers, or serverless functions.
 
 ## Installation
 
@@ -8,77 +31,189 @@ Official TypeScript client for Agent Ledger. The SDK instruments your agents so
 pnpm add @agent-ledger/sdk-ts
 # or
 npm install @agent-ledger/sdk-ts
+# or
+yarn add @agent-ledger/sdk-ts
 ```
 
-## Quick start
+## Runtime requirements
+
+- Node.js 18 or newer (for the built-in `fetch` implementation). If you run older Node versions, polyfill `fetch` before importing the SDK.
+- An Agent Ledger API key generated from the dashboard (Settings → API Keys).
+- Outbound HTTPS access to `https://agent-ledger-api.azurewebsites.net` (or your self-hosted instance).
+
+## Getting started
 
 ```ts
-import { AgentLedgerClient } from "@agent-ledger/sdk-ts";
+import { AgentLedgerClient, BudgetGuardrailError } from "@agent-ledger/sdk-ts";
 
 const ledger = new AgentLedgerClient({
   apiKey: process.env.AGENT_LEDGER_API_KEY!,
-  // baseUrl is optional. Defaults to the production Agent Ledger API.
 });
 
-async function runAgent() {
+export async function runSupportAgent(prompt: string) {
   const sessionId = await ledger.startSession("support-bot");
+
   try {
+    // 1. Run your own LLM/tool logic
+    const response = await callModel(prompt);
+
+    // 2. Log the LLM call (Agent Ledger auto-computes spend from provider/model/tokens)
     await ledger.logLLMCall(sessionId, {
       stepIndex: 0,
-      model: "gpt-4o",
       provider: "openai",
-      prompt: "Draft a welcome email",
-      response: "Hello ...",
-      tokensIn: 120,
-      tokensOut: 98,
-      latencyMs: 2300,
+      model: "gpt-4o-mini",
+      prompt,
+      response: response.text,
+      tokensIn: response.usage.inputTokens,
+      tokensOut: response.usage.outputTokens,
+      latencyMs: response.latencyMs,
     });
 
-    // ...additional tool calls/events...
-
     await ledger.endSession(sessionId, "success");
+    return response.text;
   } catch (err) {
+    if (err instanceof BudgetGuardrailError) {
+      console.warn("Budget exceeded", err.details);
+    }
     await ledger.endSession(sessionId, "error", { errorMessage: (err as Error).message });
     throw err;
   }
 }
 ```
 
-## API surface
+## Session lifecycle
+
+1. **Start sessions** early with `startSession(agentName)` to capture every downstream event.
+2. **Log events** whenever you call an LLM or tool:
+   - `logLLMCall` for prompts/responses.
+   - `logToolCall` for tool invocations (store the inputs).
+   - `logToolResult` for tool responses (store outputs/latency).
+   - `logEvents` if you need to batch arbitrary event objects.
+3. **End sessions** with `endSession(sessionId, "success" | "error", { errorMessage? })` so the dashboard knows whether the run finished cleanly.
+
+Tip: keep a simple helper that wraps this flow so every agent in your repo emits consistent telemetry.
+
+## Event reference
+
+| Event | Required fields | Optional fields | Notes |
+| --- | --- | --- | --- |
+| `LlmCallEvent` | `stepIndex`, `model`, `provider`, `prompt`, `response`, `tokensIn`, `tokensOut`, `latencyMs` | — | `logLLMCall` automatically sets `type` to `llm_call` and lets the backend price the call based on provider/model. |
+| `ToolCallEvent` | `stepIndex`, `toolName`, `toolInput` | — | Capture the structured input you sent to an internal or external tool. |
+| `ToolResultEvent` | `stepIndex`, `toolName`, `toolOutput`, `latencyMs` | — | Use together with `ToolCallEvent` to understand tool latency and result size. |
+| Custom | Whatever your workflow needs plus `type` | — | Supply via `logEvents` if you want to store derived signals (examples: `session_start`, `session_end`, `guardrail_trigger`). |
+
+Conventions:
+
+- `stepIndex` is a zero-based counter that makes it easy to diff runs. Increment it in the order events happen, even if multiple tools share the same LLM output.
+- Keep prompts/responses under 64 KB per event so they render nicely in the dashboard diff view.
+- All numeric values are stored as numbers (no strings) so the API can aggregate cost statistics.
+
+## API reference
+
+### `new AgentLedgerClient(options)`
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `apiKey` | `string` (required) | Workspace API key from the dashboard. |
+
+### `startSession(agentName: string): Promise<string>`
+
+Creates a session row and returns its UUID. `agentName` should match how you identify the workflow in the dashboard (e.g., `support-bot`, `retrieval-worker`).
+
+### `endSession(sessionId, status, opts?)`
+
+Marks the session closed. Pass `{ errorMessage }` for failures so the UI shows context next to the run.
+
+### `logEvents(sessionId, events)`
+
+Lowest-level ingestion helper. Accepts an array of plain objects, so you can batch multiple events into a single network call. Events must include a `type` string (e.g., `llm_call`).
 
-- `new AgentLedgerClient({ apiKey, baseUrl? })`
-- `startSession(agentName)` → session ID
-- `endSession(sessionId, status, { errorMessage? })`
-- `logEvents(sessionId, events)` (low-level entry point)
-- `logLLMCall`, `logToolCall`, `logToolResult` (typed helpers)
+### `logLLMCall(sessionId, event)` / `logToolCall` / `logToolResult`
 
-All helpers eventually POST to the Agent Ledger REST API using the API key supplied in the constructor.
+Typed helpers that:
 
-### Budget guardrail errors
+- Fill the `type` automatically.
+- Validate required fields at compile time.
+- Call `logEvents` under the hood.
 
-If Agent Ledger blocks an event because of a per-agent budget limit, the SDK throws `BudgetGuardrailError`. Catch it to inspect the `details` payload and react accordingly:
+### Types exported
+
+`AgentLedgerClient`, `AgentLedgerClientOptions`, `BudgetGuardrailError`, `BudgetGuardrailDetails`, `LlmCallEvent`, `ToolCallEvent`, `ToolResultEvent`, `AnyEvent`, `EventType`.
+
+## Error handling
+
+- **`BudgetGuardrailError`** (HTTP 429): thrown when the backend refuses the event because the agent exceeded its daily limit. Inspect `error.details`:
+
+  ```ts
+  {
+    agentName: string;
+    dailyLimitUsd: number;
+    spentTodayUsd: number;
+    attemptedCostUsd: number;
+    projectedCostUsd: number;
+    remainingBudgetUsd: number;
+  }
+  ```
+
+- **Generic `Error`**: wraps any other non-2xx response (`startSession`, `endSession`, `logEvents`). The `.message` contains the server-provided text when available.
+
+Recommended practice: catch errors where you call `logEvents` so your business logic can continue (or at least emit a structured failure) even when the telemetry call is rejected.
+
+## Configuration & environments
+
+- Provide `AGENT_LEDGER_API_KEY` (or load it from your preferred secrets manager) and the SDK connects to the hosted API automatically.
+- Default endpoint → `https://agent-ledger-api.azurewebsites.net`.
+- For local API experiments, keep the SDK untouched and proxy traffic through your own tooling (MSW, mock servers, etc.).
+
+Because the client is stateless, you can instantiate one per agent type or share a singleton across the entire app.
+
+## Recipes
+
+### Streaming agents / multi-step workflows
+
+Reuse a monotonically increasing `stepIndex` while you stream partial responses. You can emit interim tool calls before the final LLM response lands to visualize branching logic.
+
+### Custom tool instrumentation
 
 ```ts
-import { BudgetGuardrailError } from "@agent-ledger/sdk-ts";
+async function callWeather(sessionId: string, city: string, stepIndex: number) {
+  await ledger.logToolCall(sessionId, {
+    stepIndex,
+    toolName: "weather",
+    toolInput: { city },
+  });
+
+  const result = await fetchWeather(city);
+
+  await ledger.logToolResult(sessionId, {
+    stepIndex,
+    toolName: "weather",
+    toolOutput: result,
+    latencyMs: result.latencyMs,
+  });
+}
+```
 
+### Handling guardrail blocks
+
+```ts
 try {
-  await ledger.logEvents(sessionId, events);
+  await ledger.logLLMCall(sessionId, event);
 } catch (err) {
   if (err instanceof BudgetGuardrailError) {
-    console.warn("Budget exceeded", err.details);
+    await ledger.endSession(sessionId, "error", {
+      errorMessage: `Budget exceeded: remaining ${err.details.remainingBudgetUsd}`,
+    });
+    return;
   }
+  throw err;
 }
 ```
 
-### Environment overrides
-
-- `baseUrl` option overrides the API host per client.
-- When omitted, the SDK looks for `process.env.AGENT_LEDGER_BASE_URL` and falls back to `https://agent-ledger-api.azurewebsites.net`.
-- For local testing, set `AGENT_LEDGER_BASE_URL=http://localhost:3000` (or your tunnel URL) before instantiating the client.
-
-## TypeScript support
+## Testing & local dev
 
-This package ships its own `.d.ts` files (generated from `src/index.ts`). No additional typings are required.
+- The SDK performs real HTTP requests. For unit tests, stub `global.fetch` or intercept calls with tools like [MSW](https://mswjs.io/).
+- When running the Agent Ledger API locally, ensure your test key exists in the development database and export it via `AGENT_LEDGER_API_KEY`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-ledger/sdk-ts",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "private": false,
   "type": "module",
   "main": "dist/index.js",