@punktechnologies/sdk 0.1.2 → 0.2.0

package/README.md

@@ -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>;