@punktechnologies/sdk 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @punktechnologies/sdk
 
-OpenAI-compatible AI gateway SDK for agent tracing, tool caching, governance, observability, and cost optimization.
+Gateway Agnostic AI runtime SDK for OpenAI, Anthropic, OpenRouter, and more, with agent tracing, tool caching, governance, observability, and cost optimization.
 
 Punk is the adaptive runtime for production AI agents. Put the gateway between your agents and model providers, then use this SDK where gateway traffic alone cannot see enough context: tool tracing, side-effect declarations, tool-result caching, semantic web fetches, feedback, receipts, evidence packets, MCP registry helpers, prompt ingest, and learning/artifact APIs.
 
@@ -16,7 +16,7 @@ npm i @punktechnologies/sdk
 bun add @punktechnologies/sdk
 ```
 
-Zero runtime dependencies. Requires Node 18+ or Bun and a running Punk gateway. For local evaluation from the Punk repo:
+Zero runtime dependencies. Requires Node 18+ or Bun and a running Punk gateway. `new Punk()` reads `PUNK_BASE_URL`, `PUNK_API_KEY`, `PUNK_APP`, `PUNK_AGENT`, and `PUNK_SUBJECT`; explicit constructor options still win. For local evaluation from the Punk repo:
 
 ```bash
 bun install
@@ -36,18 +36,17 @@ For hosted trials, use `baseUrl: "https://app.punktechnologies.com"` with a tena
 
 ## 60-Second Start
 
-**1. Point existing OpenAI-style traffic at Punk.**
+**1. Point existing model traffic at Punk.**
 
-You do not need this SDK for the core gateway value. OpenAI-style and Anthropic-style clients can talk to Punk by changing the gateway URL.
+You do not need this SDK for the core gateway value. OpenAI-style and Anthropic-style clients can talk to Punk by changing the gateway URL, and the SDK can generate the right config objects when you do use it.
 
 ```ts
 import OpenAI from "openai";
+import { Punk } from "@punktechnologies/sdk";
 
-const client = new OpenAI({
-  baseURL: "http://localhost:4100/v1",
-  apiKey: process.env.PUNK_API_KEY ?? "punk-local",
-  defaultHeaders: { "X-Punk-App": "my-app" },
-});
+const punk = new Punk({ app: "my-app", agent: "my-bot", subject: "user-123" });
+
+const client = new OpenAI(punk.openAIConfig());
 ```
 
 **2. Use the SDK when you need the richer runtime surface.**
@@ -55,12 +54,11 @@ const client = new OpenAI({
 ```ts
 import { Punk } from "@punktechnologies/sdk";
 
-const punk = new Punk({ app: "my-app", agent: "my-bot" });
-const result = await punk.chat({
+const result = await punk.gateway.chat({
   model: "gpt-4o",
   messages: [{ role: "user", content: "Classify this ticket: refund request" }],
 });
-console.log(result.content, result.route, result.runId);
+console.log(result.content, result.route, result.runId, result.usage);
 // route is "live" on the first call; repeats become "exact_cache" and,
 // once learned and proven, "artifact".
 ```
@@ -71,7 +69,7 @@ Open `http://localhost:4100` locally, or `https://app.punktechnologies.com` for
 
 ## API tour
 
-Construct once per app/agent identity:
+Construct once per app/agent identity. Omit options to read `PUNK_BASE_URL`, `PUNK_API_KEY`, `PUNK_APP`, `PUNK_AGENT`, and `PUNK_SUBJECT` from the environment.
 
 ```ts
 const punk = new Punk({
@@ -83,7 +81,27 @@ const punk = new Punk({
 });
 ```
 
-### `chat(params)` — OpenAI-style completions through the gateway
+### Adapter config helpers
+
+Use these helpers when your app already has a provider client:
+
+```ts
+new OpenAI(punk.openAIConfig());
+new Anthropic(punk.anthropicConfig());
+
+const aiSdkProvider = createOpenAICompatible(
+  punk.vercelOpenAICompatibleConfig({ name: "punk" })
+);
+
+const model = new ChatOpenAI({
+  model: "gpt-4o",
+  ...punk.langChainConfig()
+});
+```
+
+`identityHeaders()` returns the `X-Punk-*` headers, with optional `Authorization`. All config helpers accept per-call overrides such as `{ app, agent, subject, baseUrl, apiKey }`.
+
+### `chat(params)` / `openai.chat(params)` — OpenAI-style completions
 
 ```ts
 const r = await punk.chat({
@@ -94,11 +112,53 @@ const r = await punk.chat({
 r.content; // assistant text
 r.runId;   // from the x-punk-run-id response header — use it for tracing/feedback
 r.route;   // "live" | "exact_cache" | "artifact" | ... (x-punk-route header)
+r.usage;   // normalized input/output/total token counts when present
+r.model;   // response model when present
+r.provider;// response provider when present
 r.raw;     // the full OpenAI-shaped response body
 ```
 
 Every response carries a run id and the route Punk chose. `punk.runDetail(r.runId)` returns the full trace and the `RouteExplanation` — why this route, what was rejected, what it saved.
 
+Streaming is built in:
+
+```ts
+for await (const chunk of punk.streamChat({
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "Stream a support reply." }]
+})) {
+  if (chunk.type === "delta") process.stdout.write(chunk.content);
+}
+```
+
+### `anthropic.messages(params)` — Anthropic Messages
+
+```ts
+const msg = await punk.anthropic.messages({
+  model: "claude-sonnet-4-6",
+  max_tokens: 256,
+  messages: [{ role: "user", content: "What is a deterministic artifact?" }]
+});
+
+msg.content;       // text blocks joined together
+msg.contentBlocks; // original Anthropic content blocks
+msg.runId;
+msg.route;
+msg.usage;
+```
+
+Streaming Anthropic-shaped responses works the same way:
+
+```ts
+for await (const chunk of punk.streamMessages({
+  model: "claude-sonnet-4-6",
+  max_tokens: 256,
+  messages: [{ role: "user", content: "Stream a haiku about caching." }]
+})) {
+  if (chunk.type === "delta") process.stdout.write(chunk.content);
+}
+```
+
 For Punk Chorus, use `model: "punk/chorus"` and add Chorus-specific routing fields to the same body. The SDK helper below uses the OpenAI-style chat wire; direct HTTP callers can use the same model id through supported gateway wires.
 
 ```ts
@@ -149,8 +209,9 @@ const lookupAccount = punk.traceTool({
   execute: async (args: { accountId: string }) => crm.get(args.accountId),
 });
 
-// Pass the runId from the chat that triggered the tool:
-const account = await lookupAccount({ accountId: "acct_42" }, { runId: r.runId });
+await punk.withRun(r, async () => {
+  const account = await lookupAccount({ accountId: "acct_42" });
+});
 ```
 
 Side-effect levels (PRD §17):
@@ -163,7 +224,7 @@ Side-effect levels (PRD §17):
 | 3 | User-visible write | email, Slack, ticket creation |
 | 4 | High-impact | payments, deletion, permissions |
 
-Undeclared tools default to **level 3** (conservative). Levels 0–1 with a TTL are cached per tenant/subject; levels ≥ 2 emit `side_effect.planned` before execution so replay and shadow runs can suppress them. Without a `runId`, the tool still executes — just untraced. Cache and trace failures never break the tool call.
+Undeclared tools default to **level 3** (conservative). Levels 0–1 with a TTL are cached per tenant/subject; levels ≥ 2 emit `side_effect.planned` before execution so replay and shadow runs can suppress them. `traceTool` uses an explicit `{ runId }` when supplied, otherwise the active `withRun(...)` context. Without either, the tool still executes — just untraced. Cache and trace failures never break the tool call.
 
 ### `feedback(runId, rating, correction?)` — close the loop
 
@@ -231,6 +292,10 @@ await punk.patterns();         // discovered patterns and their lifecycle state
 await punk.artifacts();        // synthesized artifacts with confidence + evidence counts
 await punk.artifactDetail(id); // artifact + replay/shadow evaluations + source pattern
 await punk.runDetail(id);      // run + full trace events + side-effect records
+await punk.explain(id);        // routeExplanation only
+await punk.savingsForRun(id);  // per-run cost/savings counters
+await punk.sideEffectsForRun(id);
+await punk.waitForRun(id);     // poll until completed/failed/blocked
 await punk.receipt(id);        // Chorus receipt for a run
 await punk.evidencePacket(id); // support/security evidence packet for a run
 await punk.cacheStats();       // per-tier entries and hits

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  * `traceTool`, and the runtime observes, caches, learns and (after replay +
  * shadow proof) routes repeated work through deterministic artifacts.
  */
-import type { Artifact, ArtifactEvaluation, McpServerRecord, McpTestResult, Pattern, PromotionGateStatus, Run, SavingsSummary, SideEffectLevel, SideEffectRecord, SomDiff, SomSnapshot, TraceEvent, TraceEventType, TrustLane, WebActionIntent, WebActionResult } from "./types";
+import type { Artifact, ArtifactEvaluation, McpServerRecord, McpTestResult, Pattern, PromotionGateStatus, RouteExplanation, Run, SavingsSummary, SideEffectLevel, SideEffectRecord, SomDiff, SomSnapshot, TraceEvent, TraceEventType, TrustLane, WebActionIntent, WebActionResult } from "./types";
 export type * from "./types";
 export interface PunkOptions {
     /** Gateway base URL. Default: http://localhost:4100 */
@@ -108,6 +108,129 @@ export interface ChatResult {
     runId: string;
     route: string;
     raw: any;
+    usage?: PunkUsage;
+    model?: string;
+    provider?: string;
+}
+export interface PunkUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    raw: unknown;
+}
+export interface AnthropicContentBlock {
+    type: string;
+    text?: string;
+    [key: string]: unknown;
+}
+export interface AnthropicMessageParams extends PunkChorusOptions {
+    model: string;
+    max_tokens: number;
+    messages: Array<{
+        role: "user" | "assistant" | (string & {});
+        content: string | AnthropicContentBlock[];
+    }>;
+    system?: string | AnthropicContentBlock[];
+    temperature?: number;
+    top_p?: number;
+    top_k?: number;
+    stop_sequences?: string[];
+    tools?: unknown[];
+    tool_choice?: unknown;
+    metadata?: Record<string, unknown>;
+}
+export interface AnthropicMessageResult {
+    content: string;
+    contentBlocks: AnthropicContentBlock[];
+    runId: string;
+    route: string;
+    raw: any;
+    usage?: PunkUsage;
+    model?: string;
+    provider?: string;
+    stopReason?: string;
+}
+export interface ChatStreamChunk {
+    type: "delta" | "done";
+    content: string;
+    toolCalls: ChatToolCall[];
+    runId: string;
+    route: string;
+    raw?: any;
+    usage?: PunkUsage;
+    model?: string;
+    provider?: string;
+}
+export interface AnthropicMessageStreamChunk {
+    type: "delta" | "done";
+    content: string;
+    runId: string;
+    route: string;
+    event?: string;
+    raw?: any;
+    usage?: PunkUsage;
+    model?: string;
+    provider?: string;
+}
+export interface PunkIdentityHeadersOptions {
+    /** Include Authorization when this client has an API key. Default: true. */
+    includeAuthorization?: boolean;
+    /** Include Content-Type: application/json. Default: false. */
+    includeContentType?: boolean;
+    /** Override the X-Punk-App value for this config object. */
+    app?: string;
+    /** Override the X-Punk-Agent value for this config object. */
+    agent?: string;
+    /** Override the X-Punk-Subject value for this config object. */
+    subject?: string;
+    /** Extra headers to merge last. Blank values are ignored. */
+    headers?: Record<string, string | undefined>;
+}
+export interface PunkClientConfigOptions extends PunkIdentityHeadersOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    name?: string;
+    includeUsage?: boolean;
+}
+export interface PunkOpenAIConfig {
+    baseURL: string;
+    apiKey: string;
+    defaultHeaders: Record<string, string>;
+}
+export interface PunkAnthropicConfig {
+    baseURL: string;
+    authToken: string;
+    defaultHeaders: Record<string, string>;
+}
+export interface PunkVercelOpenAICompatibleConfig {
+    name: string;
+    baseURL: string;
+    apiKey: string;
+    headers: Record<string, string>;
+    includeUsage: boolean;
+}
+export interface PunkLangChainConfig {
+    apiKey: string;
+    configuration: {
+        baseURL: string;
+        defaultHeaders: Record<string, string>;
+    };
+}
+export interface RunSavings {
+    runId: string;
+    route?: string;
+    status: Run["status"];
+    costUsd: number;
+    savedUsd: number;
+    ghostSavedUsd: number;
+    latencyMs: number;
+    inputTokens: number;
+    outputTokens: number;
+}
+export interface RunWaitOptions {
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
 }
 export interface PunkReceipt {
     id?: string;
@@ -210,14 +333,53 @@ export declare class Punk {
     readonly agent?: string;
     readonly subject?: string;
     private readonly apiKey?;
+    private readonly runStack;
     constructor(opts?: PunkOptions);
+    readonly gateway: {
+        chat: (params: ChatParams) => Promise<ChatResult>;
+        streamChat: (params: ChatParams) => AsyncIterable<ChatStreamChunk>;
+        stream: (params: ChatParams) => AsyncIterable<ChatStreamChunk>;
+    };
+    readonly openai: {
+        chat: (params: ChatParams) => Promise<ChatResult>;
+        streamChat: (params: ChatParams) => AsyncIterable<ChatStreamChunk>;
+        stream: (params: ChatParams) => AsyncIterable<ChatStreamChunk>;
+        config: (opts?: PunkClientConfigOptions) => PunkOpenAIConfig;
+    };
+    readonly anthropic: {
+        messages: (params: AnthropicMessageParams) => Promise<AnthropicMessageResult>;
+        streamMessages: (params: AnthropicMessageParams) => AsyncIterable<AnthropicMessageStreamChunk>;
+        stream: (params: AnthropicMessageParams) => AsyncIterable<AnthropicMessageStreamChunk>;
+        config: (opts?: PunkClientConfigOptions) => PunkAnthropicConfig;
+    };
+    identityHeaders(opts?: PunkIdentityHeadersOptions): Record<string, string>;
+    openAIConfig(opts?: PunkClientConfigOptions): PunkOpenAIConfig;
+    anthropicConfig(opts?: PunkClientConfigOptions): PunkAnthropicConfig;
+    vercelAIConfig(opts?: PunkClientConfigOptions): PunkVercelOpenAICompatibleConfig;
+    vercelOpenAICompatibleConfig(opts?: PunkClientConfigOptions): PunkVercelOpenAICompatibleConfig;
+    langChainConfig(opts?: PunkClientConfigOptions): PunkLangChainConfig;
+    currentRunId(): string | undefined;
+    withRun<T>(run: string | {
+        runId?: string | null | undefined;
+    }, fn: () => T | Promise<T>): Promise<Awaited<T>>;
     /** Send an OpenAI-compatible chat completion through the gateway. */
     chat(params: ChatParams): Promise<ChatResult>;
+    /** Stream an OpenAI-compatible chat completion through the gateway. */
+    streamChat(params: ChatParams): AsyncIterable<ChatStreamChunk>;
+    /** Stream an OpenAI-compatible chat completion through the gateway. */
+    chatStream(params: ChatParams): AsyncIterable<ChatStreamChunk>;
+    /** Send an Anthropic-compatible Messages request through the gateway. */
+    messages(params: AnthropicMessageParams): Promise<AnthropicMessageResult>;
+    /** Stream an Anthropic-compatible Messages request through the gateway. */
+    streamMessages(params: AnthropicMessageParams): AsyncIterable<AnthropicMessageStreamChunk>;
+    /** Stream an Anthropic-compatible Messages request through the gateway. */
+    messagesStream(params: AnthropicMessageParams): AsyncIterable<AnthropicMessageStreamChunk>;
     /**
      * Wrap a tool so every invocation is traced into the run it belongs to, and
      * explicitly declared read-only results (level <= 1 with a TTL) flow
-     * through the tool-result cache. Tracing requires `ctx.runId`; without it
-     * the tool still executes, silently untraced and uncached.
+     * through the tool-result cache. Tracing uses `ctx.runId` first, then an
+     * active `withRun` id; without either the tool still executes, silently
+     * untraced and uncached.
      */
     traceTool<TArgs, TResult>(def: ToolDefinition<TArgs, TResult>): TracedTool<TArgs, TResult>;
     /** Append a trace event to a run. */
@@ -304,6 +466,11 @@ export declare class Punk {
     artifacts(): Promise<Artifact[]>;
     artifactDetail(id: string): Promise<ArtifactDetail>;
     runDetail(id: string): Promise<RunDetail>;
+    explain(runId: string): Promise<RouteExplanation | null>;
+    savingsForRun(runId: string): Promise<RunSavings>;
+    sideEffectsForRun(runId: string): Promise<SideEffectRecord[]>;
+    waitForRun(runId: string, opts?: RunWaitOptions): Promise<RunDetail>;
+    watchRun(runId: string, opts?: RunWaitOptions): AsyncIterable<RunDetail>;
     receipt(id: string): Promise<PunkReceipt>;
     evidencePacket(runId: string): Promise<EvidencePacket>;
     cacheStats(): Promise<CacheStats>;