@modelrelay/sdk 1.10.3 → 1.25.0

package/README.md

@@ -128,89 +128,84 @@ const text = await mr.responses.textForCustomer({
 });
 ```
 
-## Workflow Runs (workflow.v0)
+## 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 {
-  ModelRelay,
-  type LLMResponsesBindingV0,
-  parseNodeId,
-  parseOutputName,
-  parseSecretKey,
-  workflowV0,
-} from "@modelrelay/sdk";
+import { chain, llmStep } from "@modelrelay/sdk";
 
-const mr = new ModelRelay({ key: parseSecretKey("mr_sk_...") });
+const summarizeReq = mr.responses
+  .new()
+  .model("claude-sonnet-4-20250514")
+  .system("Summarize the input concisely.")
+  .user("The quick brown fox...")
+  .build();
 
-const spec = workflowV0()
-  .name("multi_agent_v0_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: "Write 3 ideas for a landing page." }] },
-    ],
-  })
-  .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: "Write 3 objections a user might have." }] },
-    ],
-  })
-  .llmResponses(parseNodeId("agent_c"), {
-    model: "claude-sonnet-4-20250514",
-    input: [
-      { type: "message", role: "system", content: [{ type: "text", text: "You are Agent C." }] },
-      { type: "message", role: "user", content: [{ type: "text", text: "Write 3 alternative headlines." }] },
-    ],
-  })
-  .joinAll(parseNodeId("join"))
-  .llmResponses(
-    parseNodeId("aggregate"),
-    {
-      model: "claude-sonnet-4-20250514",
-      input: [
-        {
-          type: "message",
-          role: "system",
-          content: [{ type: "text", text: "Synthesize the best answer from the following agent outputs (JSON)." }],
-        },
-        { type: "message", role: "user", content: [{ type: "text", text: "" }] }, // overwritten by bindings
-      ],
-    },
-    {
-      // Bind the join output into the aggregator prompt (fan-in).
-      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("agent_c"), parseNodeId("join"))
-  .edge(parseNodeId("join"), parseNodeId("aggregate"))
-  .output(parseOutputName("result"), parseNodeId("aggregate"))
+const translateReq = mr.responses
+  .new()
+  .model("claude-sonnet-4-20250514")
+  .system("Translate the input to French.")
+  .user("") // Bound from previous step
   .build();
 
-const { run_id } = await mr.runs.create(spec);
+const spec = chain("summarize-translate")
+  .step(llmStep("summarize", summarizeReq))
+  .step(llmStep("translate", translateReq).withStream())
+  .outputLast("result")
+  .build();
+```
 
-const events = await mr.runs.events(run_id);
-for await (const ev of events) {
-  if (ev.type === "run_completed") {
-    const status = await mr.runs.get(run_id);
-    console.log("outputs:", status.outputs);
-    console.log("cost_summary:", status.cost_summary);
-  }
-}
+### 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();
 ```
 
-See the full example in `sdk/ts/examples/workflows_multi_agent.ts`.
+### 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
 
@@ -250,24 +245,60 @@ for await (const delta of deltas) {
 
 ## Structured Outputs with Zod
 
+The simplest way to get typed structured output:
+
 ```ts
-import { ModelRelay, parseSecretKey } from "@modelrelay/sdk";
+import { ModelRelay } from "@modelrelay/sdk";
 import { z } from "zod";
 
-const mr = new ModelRelay({ key: parseSecretKey("mr_sk_...") });
+const mr = ModelRelay.fromSecretKey("mr_sk_...");
 
 const Person = z.object({
   name: z.string(),
   age: z.number(),
 });
 
+// Simple one-call API (recommended)
+const person = await mr.responses.object<z.infer<typeof Person>>({
+  model: "claude-sonnet-4-20250514",
+  schema: Person,
+  prompt: "Extract: John Doe is 30 years old",
+});
+
+console.log(person.name); // "John Doe"
+console.log(person.age);  // 30
+```
+
+For parallel structured output calls:
+
+```ts
+const [security, performance] = await Promise.all([
+  mr.responses.object<SecurityReview>({
+    model: "claude-sonnet-4-20250514",
+    schema: SecuritySchema,
+    system: "You are a security expert.",
+    prompt: code,
+  }),
+  mr.responses.object<PerformanceReview>({
+    model: "claude-sonnet-4-20250514",
+    schema: PerformanceSchema,
+    system: "You are a performance expert.",
+    prompt: code,
+  }),
+]);
+```
+
+For more control (retries, custom handlers, metadata):
+
+```ts
 const result = await mr.responses.structured(
   Person,
   mr.responses.new().model("claude-sonnet-4-20250514").user("Extract: John Doe is 30").build(),
   { maxRetries: 2 },
 );
 
-console.log(result.value); // { name: "John Doe", age: 30 }
+console.log(result.value);    // { name: "John Doe", age: 30 }
+console.log(result.attempts); // 1
 ```
 
 ## Streaming Structured Outputs
@@ -374,7 +405,7 @@ try {
   } 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"
+    console.log("Stream timeout:", error.kind); // "ttft" | "idle" | "total"
   }
 }
 ```