@modelrelay/sdk 5.1.0 → 8.0.0

package/README.md

@@ -4,6 +4,91 @@
 bun add @modelrelay/sdk
 ```
 
+## Convenience API
+
+The simplest way to get started. Three methods cover the most common use cases:
+
+### Ask — Get a Quick Answer
+
+```typescript
+import { ModelRelay } from "@modelrelay/sdk";
+
+const mr = ModelRelay.fromSecretKey(process.env.MODELRELAY_API_KEY!);
+
+const answer = await mr.ask("claude-sonnet-4-5", "What is 2 + 2?");
+console.log(answer); // "4"
+```
+
+### Chat — Full Response with Metadata
+
+```typescript
+const response = await mr.chat("claude-sonnet-4-5", "Explain quantum computing", {
+  system: "You are a physics professor",
+});
+
+console.log(response.output);
+console.log("Tokens:", response.usage.totalTokens);
+```
+
+### Agent — Agentic Tool Loops
+
+Run an agent that automatically executes tools until completion:
+
+```typescript
+import { z } from "zod";
+
+const tools = mr
+  .tools()
+  .add(
+    "read_file",
+    "Read a file from the filesystem",
+    z.object({ path: z.string().describe("File path to read") }),
+    async (args) => {
+      const content = await fs.readFile(args.path, "utf-8");
+      return content;
+    }
+  );
+
+const result = await mr.agent("claude-sonnet-4-5", {
+  tools,
+  prompt: "Read config.json and summarize it",
+  system: "You are a helpful file assistant",
+});
+
+console.log(result.output);
+console.log("Tool calls:", result.usage.toolCalls);
+```
+
+### User Interaction — `user.ask`
+
+Use the built-in `user.ask` tool to request human input in a workflow run:
+
+```typescript
+import { ModelRelay, ToolRegistry, ToolRunner, createUserAskTool } from "@modelrelay/sdk";
+
+const mr = ModelRelay.fromSecretKey(process.env.MODELRELAY_API_KEY!);
+
+const tools = [createUserAskTool()];
+const registry = new ToolRegistry();
+
+const runner = new ToolRunner({
+  registry,
+  runsClient: mr.runs,
+  onUserAsk: async (_pending, args) => {
+    const answer = await promptUser(args.question); // your UI/input here
+    return { answer, is_freeform: true };
+  },
+});
+
+const run = await mr.runs.create(spec);
+
+for await (const event of mr.runs.events(run.run_id)) {
+  if (event.type === "node_waiting") {
+    await runner.handleNodeWaiting(run.run_id, event.node_id, event.waiting);
+  }
+}
+```
+
 ## 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`.
@@ -98,81 +183,73 @@ const text = await mr.responses.textForCustomer({
 
 ## Workflows
 
-High-level helpers for common workflow patterns:
-
-### Chain (Sequential)
+Build multi-step AI pipelines with the workflow helpers.
 
-Sequential LLM calls where each step's output feeds the next step's input:
+### Sequential Chain
 
 ```ts
-import { chain, llmStep } from "@modelrelay/sdk";
+import { chain, llm } from "@modelrelay/sdk";
 
-const summarizeReq = mr.responses
-  .new()
-  .model("claude-sonnet-4-5")
-  .system("Summarize the input concisely.")
-  .user("The quick brown fox...")
+const spec = chain([
+  llm("summarize", (n) => n.system("Summarize.").user("{{task}}")),
+  llm("translate", (n) => n.system("Translate to French.").user("{{summarize}}")),
+], { name: "summarize-translate", model: "claude-sonnet-4-5" })
+  .output("result", "translate")
   .build();
 
-const translateReq = mr.responses
-  .new()
-  .model("claude-sonnet-4-5")
-  .system("Translate the input to French.")
-  .user("") // Bound from previous step
-  .build();
+const { run_id } = await mr.runs.create(spec);
+```
+
+### Parallel with Aggregation
 
-const spec = chain("summarize-translate")
-  .step(llmStep("summarize", summarizeReq))
-  .step(llmStep("translate", translateReq).withStream())
-  .outputLast("result")
+```ts
+import { parallel, llm } from "@modelrelay/sdk";
+
+const spec = parallel([
+  llm("agent_a", (n) => n.user("Write 3 ideas for {{task}}.")),
+  llm("agent_b", (n) => n.user("Write 3 objections for {{task}}.")),
+], { name: "multi-agent", model: "claude-sonnet-4-5" })
+  .llm("aggregate", (n) => n.system("Synthesize.").user("{{join}}"))
+  .edge("join", "aggregate")
+  .output("result", "aggregate")
   .build();
 ```
 
-### Parallel (Fan-out with Aggregation)
+### Precompiled Workflows
 
-Concurrent LLM calls with optional aggregation:
+For workflows that run repeatedly, compile once and reuse:
 
 ```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-5").user("Analyze this...").build();
-const synthesizeReq = mr.responses
-  .new()
-  .model("claude-sonnet-4-5")
-  .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();
+// Compile once
+const { plan_hash } = await mr.workflows.compile(spec);
+
+// Run multiple times with different inputs
+for (const task of tasks) {
+  const run = await mr.runs.createFromPlan(plan_hash, {
+    input: { task },
+  });
+}
 ```
 
-### MapReduce (Parallel Map with Reduce)
+### Plugins (Workflows)
 
-Process items in parallel, then combine results:
+Load GitHub-hosted plugins (markdown commands + agents), convert to workflows via `/responses`, then run them with `/runs`:
 
 ```ts
-import { mapReduce } from "@modelrelay/sdk";
+import { ModelRelay, OrchestrationModes } from "@modelrelay/sdk";
+import { createLocalFSTools } from "@modelrelay/sdk/node";
 
-const combineReq = mr.responses
-  .new()
-  .model("claude-sonnet-4-5")
-  .system("Combine summaries into a cohesive overview.")
-  .user("") // Bound from join output
-  .build();
+const mr = ModelRelay.fromSecretKey(process.env.MODELRELAY_API_KEY!);
+const tools = createLocalFSTools({ root: process.cwd() });
 
-const spec = mapReduce("summarize-docs")
-  .item("doc1", doc1Req)
-  .item("doc2", doc2Req)
-  .item("doc3", doc3Req)
-  .reduce("combine", combineReq)
-  .output("result", "combine")
-  .build();
+const plugin = await mr.plugins.load("github.com/your-org/your-plugin");
+const result = await mr.plugins.run(plugin, "run", {
+  userTask: "Summarize the repo and suggest next steps.",
+  orchestrationMode: OrchestrationModes.Dynamic,
+  toolRegistry: tools,
+});
+
+console.log(result.outputs?.result);
 ```
 
 ## Chat-Like Text Helpers