@modelrelay/sdk 1.3.3 → 1.14.0

package/README.md

@@ -1,40 +1,215 @@
 # ModelRelay TypeScript SDK
 
-The ModelRelay TypeScript SDK is a **responses-first**, **streaming-first** client for building cross-provider LLM features without committing to any single vendor API.
-
-It's designed to feel great in TypeScript:
-- One fluent builder for **streaming/non-streaming**, **text/structured**, and **customer-attributed** requests
-- Structured outputs powered by Zod schemas with validation and retry
-- A practical tool-use toolkit for "LLM + tools" apps
-
 ```bash
-npm install @modelrelay/sdk
-# or
 bun add @modelrelay/sdk
 ```
 
-## Quick Start
+## Token Providers (Automatic Bearer Auth)
+
+Use token providers when you want the SDK to automatically obtain/refresh **bearer tokens** for data-plane calls like `/responses` and `/runs`.
+
+### OIDC id_token → customer bearer token (exchange)
+
+```ts
+import { ModelRelay, OIDCExchangeTokenProvider, parseSecretKey } from "@modelrelay/sdk";
+
+const tokenProvider = new OIDCExchangeTokenProvider({
+  apiKey: parseSecretKey(process.env.MODELRELAY_API_KEY!),
+  idTokenProvider: async () => {
+    // Return an OIDC id_token from your auth system (web login, device flow, etc).
+    return process.env.OIDC_ID_TOKEN!;
+  },
+});
+
+const mr = new ModelRelay({ tokenProvider });
+```
+
+If you need an `id_token` in a CLI-like context, you can use the OAuth device flow helper:
+
+```ts
+import { runOAuthDeviceFlowForIDToken } from "@modelrelay/sdk";
+
+const idToken = await runOAuthDeviceFlowForIDToken({
+  deviceAuthorizationEndpoint: "https://issuer.example.com/oauth/device/code",
+  tokenEndpoint: "https://issuer.example.com/oauth/token",
+  clientId: "your-client-id",
+  scope: "openid email profile",
+  onUserCode: ({ verificationUri, userCode }) => {
+    console.log(`Open ${verificationUri} and enter code: ${userCode}`);
+  },
+});
+```
+
+### Secret key → customer bearer token (mint)
+
+```ts
+import { CustomerTokenProvider, ModelRelay } from "@modelrelay/sdk";
+
+const tokenProvider = new CustomerTokenProvider({
+  secretKey: process.env.MODELRELAY_API_KEY!,
+  request: { customerId: "customer_..." },
+});
+
+const mr = new ModelRelay({ tokenProvider });
+```
+
+## Streaming Responses
 
 ```ts
 import { ModelRelay } from "@modelrelay/sdk";
 
-const mr = ModelRelay.fromSecretKey(process.env.MODELRELAY_API_KEY!);
+const mr = ModelRelay.fromSecretKey("mr_sk_...");
+
+const req = mr.responses
+  .new()
+  .model("claude-sonnet-4-20250514")
+  .user("Hello")
+  .build();
+
+const stream = await mr.responses.stream(req);
+
+for await (const event of stream) {
+  if (event.type === "message_delta" && event.textDelta) {
+    process.stdout.write(event.textDelta);
+  }
+}
+```
+
+## Customer-Scoped Convenience
 
-const response = await mr.responses.create(
-  mr.responses
-    .new()
-    .model("claude-sonnet-4-20250514")
-    .system("Answer concisely.")
-    .user("Write one line about TypeScript.")
-    .build()
+```ts
+import { ModelRelay } from "@modelrelay/sdk";
+
+const mr = ModelRelay.fromSecretKey("mr_sk_...");
+const customer = mr.forCustomer("customer_abc123");
+
+const text = await customer.responses.text(
+  "You are a helpful assistant.",
+  "Summarize Q4 results",
 );
+```
+
+You can also stream structured JSON for a specific customer:
+
+```ts
+import { z } from "zod";
+import { ModelRelay, outputFormatFromZod } from "@modelrelay/sdk";
+
+const mr = ModelRelay.fromSecretKey("mr_sk_...");
+const customer = mr.forCustomer("customer_abc123");
+
+const schema = z.object({
+  summary: z.string(),
+  highlights: z.array(z.string()),
+});
+
+const req = customer.responses
+  .new()
+  .outputFormat(outputFormatFromZod(schema))
+  .system("You are a helpful assistant.")
+  .user("Summarize Q4 results")
+  .build();
+
+const stream = await customer.responses.streamJSON<z.infer<typeof schema>>(req);
+for await (const event of stream) {
+  if (event.type === "completion") {
+    console.log(event.payload);
+  }
+}
+```
+
+You can also pass a single object to `textForCustomer`:
 
-console.log(response.text());
+```ts
+const text = await mr.responses.textForCustomer({
+  customerId: "customer_abc123",
+  system: "You are a helpful assistant.",
+  user: "Summarize Q4 results",
+});
+```
+
+## Workflows
+
+High-level helpers for common workflow patterns:
+
+### Chain (Sequential)
+
+Sequential LLM calls where each step's output feeds the next step's input:
+
+```ts
+import { chain, llmStep } from "@modelrelay/sdk";
+
+const summarizeReq = mr.responses
+  .new()
+  .model("claude-sonnet-4-20250514")
+  .system("Summarize the input concisely.")
+  .user("The quick brown fox...")
+  .build();
+
+const translateReq = mr.responses
+  .new()
+  .model("claude-sonnet-4-20250514")
+  .system("Translate the input to French.")
+  .user("") // Bound from previous step
+  .build();
+
+const spec = chain("summarize-translate")
+  .step(llmStep("summarize", summarizeReq))
+  .step(llmStep("translate", translateReq).withStream())
+  .outputLast("result")
+  .build();
+```
+
+### Parallel (Fan-out with Aggregation)
+
+Concurrent LLM calls with optional aggregation:
+
+```ts
+import { parallel, llmStep } from "@modelrelay/sdk";
+
+const gpt4Req = mr.responses.new().model("gpt-4.1").user("Analyze this...").build();
+const claudeReq = mr.responses.new().model("claude-sonnet-4-20250514").user("Analyze this...").build();
+const synthesizeReq = mr.responses
+  .new()
+  .model("claude-sonnet-4-20250514")
+  .system("Synthesize the analyses into a unified view.")
+  .user("") // Bound from join output
+  .build();
+
+const spec = parallel("multi-model-compare")
+  .step(llmStep("gpt4", gpt4Req))
+  .step(llmStep("claude", claudeReq))
+  .aggregate("synthesize", synthesizeReq)
+  .output("result", "synthesize")
+  .build();
+```
+
+### MapReduce (Parallel Map with Reduce)
+
+Process items in parallel, then combine results:
+
+```ts
+import { mapReduce } from "@modelrelay/sdk";
+
+const combineReq = mr.responses
+  .new()
+  .model("claude-sonnet-4-20250514")
+  .system("Combine summaries into a cohesive overview.")
+  .user("") // Bound from join output
+  .build();
+
+const spec = mapReduce("summarize-docs")
+  .item("doc1", doc1Req)
+  .item("doc2", doc2Req)
+  .item("doc3", doc3Req)
+  .reduce("combine", combineReq)
+  .output("result", "combine")
+  .build();
 ```
 
 ## Chat-Like Text Helpers
 
-For the most common path (**system + user → assistant text**), use the built-in convenience:
+For the most common path (**system + user → assistant text**):
 
 ```ts
 const text = await mr.responses.text(
@@ -48,16 +223,14 @@ console.log(text);
 For customer-attributed requests where the backend selects the model:
 
 ```ts
-const customer = mr.forCustomer("customer-123");
-const text = await customer.responses.text(
-  "You are a helpful assistant.",
-  "Summarize Q4 results",
+const text = await mr.responses.textForCustomer(
+  "customer-123",
+  "Answer concisely.",
+  "Say hi.",
 );
 ```
 
-## Streaming
-
-Stream text deltas for real-time output:
+To stream only message text deltas:
 
 ```ts
 const deltas = await mr.responses.streamTextDeltas(
@@ -70,31 +243,14 @@ for await (const delta of deltas) {
 }
 ```
 
-For full control, stream typed events:
-
-```ts
-const req = mr.responses
-  .new()
-  .model("claude-sonnet-4-20250514")
-  .user("Hello")
-  .build();
-
-const stream = await mr.responses.stream(req);
-
-for await (const event of stream) {
-  if (event.type === "message_delta" && event.textDelta) {
-    process.stdout.write(event.textDelta);
-  }
-}
-```
-
 ## Structured Outputs with Zod
 
-Get typed, validated responses from the model:
-
 ```ts
+import { ModelRelay, parseSecretKey } from "@modelrelay/sdk";
 import { z } from "zod";
 
+const mr = new ModelRelay({ key: parseSecretKey("mr_sk_...") });
+
 const Person = z.object({
   name: z.string(),
   age: z.number(),
@@ -109,11 +265,16 @@ const result = await mr.responses.structured(
 console.log(result.value); // { name: "John Doe", age: 30 }
 ```
 
-### Streaming Structured Outputs
+## Streaming Structured Outputs
 
 Build progressive UIs that render fields as they complete:
 
 ```ts
+import { ModelRelay, parseSecretKey } from "@modelrelay/sdk";
+import { z } from "zod";
+
+const mr = new ModelRelay({ key: parseSecretKey("mr_sk_...") });
+
 const Article = z.object({
   title: z.string(),
   summary: z.string(),
@@ -126,12 +287,15 @@ const stream = await mr.responses.streamStructured(
 );
 
 for await (const event of stream) {
+  // Render fields as soon as they're complete
   if (event.completeFields.has("title")) {
     renderTitle(event.payload.title);  // Safe to display
   }
   if (event.completeFields.has("summary")) {
     renderSummary(event.payload.summary);
   }
+
+  // Show streaming preview of incomplete fields
   if (!event.completeFields.has("body")) {
     renderBodyPreview(event.payload.body + "▋");
   }
@@ -140,7 +304,7 @@ for await (const event of stream) {
 
 ## Customer-Attributed Requests
 
-For metered billing, use `customerId()`. The customer's tier determines the model, so `model()` can be omitted:
+For metered billing, use `customerId()` — the customer's subscription tier determines the model and `model` can be omitted:
 
 ```ts
 const req = mr.responses
@@ -152,122 +316,64 @@ const req = mr.responses
 const stream = await mr.responses.stream(req);
 ```
 
-Or use the convenience method:
-
-```ts
-const text = await mr.responses.textForCustomer(
-  "customer-123",
-  "Answer concisely.",
-  "Say hi.",
-);
-```
-
 ## Customer Management (Backend)
 
 ```ts
 // Create/update customer
 const customer = await mr.customers.upsert({
-  tier_id: "tier-uuid",
   external_id: "your-user-id",
   email: "user@example.com",
 });
 
 // Create checkout session for subscription billing
-const session = await mr.customers.createCheckoutSession(customer.id, {
+const session = await mr.customers.subscribe(customer.customer.id, {
+  tier_id: "tier-uuid",
   success_url: "https://myapp.com/success",
   cancel_url: "https://myapp.com/cancel",
 });
 
 // Check subscription status
-const status = await mr.customers.getSubscription(customer.id);
+const status = await mr.customers.getSubscription(customer.customer.id);
 ```
 
-## Workflow Runs
+## Error Handling
 
-Build multi-agent workflows with parallel execution:
+Errors are typed so callers can branch cleanly:
 
 ```ts
-import { workflowV0, parseNodeId, parseOutputName, type LLMResponsesBindingV0 } from "@modelrelay/sdk";
-
-const spec = workflowV0()
-  .name("multi_agent_example")
-  .execution({ max_parallelism: 3, node_timeout_ms: 20_000, run_timeout_ms: 30_000 })
-  .llmResponses(parseNodeId("agent_a"), {
-    model: "claude-sonnet-4-20250514",
-    input: [
-      { type: "message", role: "system", content: [{ type: "text", text: "You are Agent A." }] },
-      { type: "message", role: "user", content: [{ type: "text", text: "Analyze the question." }] },
-    ],
-  })
-  .llmResponses(parseNodeId("agent_b"), {
-    model: "claude-sonnet-4-20250514",
-    input: [
-      { type: "message", role: "system", content: [{ type: "text", text: "You are Agent B." }] },
-      { type: "message", role: "user", content: [{ type: "text", text: "Find edge cases." }] },
-    ],
-  })
-  .joinAll(parseNodeId("join"))
-  .llmResponses(
-    parseNodeId("aggregate"),
-    {
-      model: "claude-sonnet-4-20250514",
-      input: [
-        { type: "message", role: "system", content: [{ type: "text", text: "Synthesize the best answer." }] },
-        { type: "message", role: "user", content: [{ type: "text", text: "" }] },
-      ],
-    },
-    {
-      bindings: [
-        { from: parseNodeId("join"), to: "/input/1/content/0/text", encoding: "json_string" } satisfies LLMResponsesBindingV0,
-      ],
-    },
-  )
-  .edge(parseNodeId("agent_a"), parseNodeId("join"))
-  .edge(parseNodeId("agent_b"), parseNodeId("join"))
-  .edge(parseNodeId("join"), parseNodeId("aggregate"))
-  .output(parseOutputName("result"), parseNodeId("aggregate"))
-  .build();
-
-const { run_id } = await mr.runs.create(spec);
-
-for await (const ev of await mr.runs.events(run_id)) {
-  if (ev.type === "run_completed") {
-    const status = await mr.runs.get(run_id);
-    console.log("outputs:", status.outputs);
+import {
+  ModelRelay,
+  APIError,
+  TransportError,
+  StreamTimeoutError,
+  ConfigError,
+} from "@modelrelay/sdk";
+
+try {
+  const response = await mr.responses.text(
+    "claude-sonnet-4-20250514",
+    "You are helpful.",
+    "Hello!"
+  );
+} catch (error) {
+  if (error instanceof APIError) {
+    console.log("Status:", error.status);
+    console.log("Code:", error.code);
+    console.log("Message:", error.message);
+
+    if (error.isRateLimit()) {
+      // Back off and retry
+    } else if (error.isUnauthorized()) {
+      // Re-authenticate
+    }
+  } else if (error instanceof TransportError) {
+    console.log("Network error:", error.message);
+  } else if (error instanceof StreamTimeoutError) {
+    console.log("Stream timeout:", error.streamKind); // "ttft" | "idle" | "total"
   }
 }
 ```
 
-## Token Providers (Advanced)
-
-For automatic bearer token management in data-plane calls:
-
-### Secret key → customer bearer token
-
-```ts
-import { CustomerTokenProvider, ModelRelay } from "@modelrelay/sdk";
-
-const tokenProvider = new CustomerTokenProvider({
-  secretKey: process.env.MODELRELAY_API_KEY!,
-  request: { projectId: "proj_...", customerId: "cust_..." },
-});
-
-const mr = new ModelRelay({ tokenProvider });
-```
-
-### OIDC exchange
-
-```ts
-import { ModelRelay, OIDCExchangeTokenProvider, parseSecretKey } from "@modelrelay/sdk";
-
-const tokenProvider = new OIDCExchangeTokenProvider({
-  apiKey: parseSecretKey(process.env.MODELRELAY_API_KEY!),
-  idTokenProvider: async () => process.env.OIDC_ID_TOKEN!,
-});
-
-const mr = new ModelRelay({ tokenProvider });
-```
-
 ## Configuration
 
 ```ts
@@ -278,3 +384,14 @@ const mr = new ModelRelay({
   retry: { maxAttempts: 3 },
 });
 ```
+
+## Documentation
+
+For detailed guides and API reference, visit [docs.modelrelay.ai](https://docs.modelrelay.ai):
+
+- [First Request](https://docs.modelrelay.ai/getting-started/first-request) — Make your first API call
+- [Streaming](https://docs.modelrelay.ai/guides/streaming) — Real-time response streaming
+- [Structured Output](https://docs.modelrelay.ai/guides/structured-output) — Get typed JSON responses
+- [Tool Use](https://docs.modelrelay.ai/guides/tools) — Let models call functions
+- [Error Handling](https://docs.modelrelay.ai/guides/error-handling) — Handle errors gracefully
+- [Workflows](https://docs.modelrelay.ai/guides/workflows) — Multi-step AI pipelines