@modelrelay/sdk 5.3.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`.
@@ -130,6 +215,43 @@ const spec = parallel([
   .build();
 ```
 
+### Precompiled Workflows
+
+For workflows that run repeatedly, compile once and reuse:
+
+```ts
+// 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 },
+  });
+}
+```
+
+### Plugins (Workflows)
+
+Load GitHub-hosted plugins (markdown commands + agents), convert to workflows via `/responses`, then run them with `/runs`:
+
+```ts
+import { ModelRelay, OrchestrationModes } from "@modelrelay/sdk";
+import { createLocalFSTools } from "@modelrelay/sdk/node";
+
+const mr = ModelRelay.fromSecretKey(process.env.MODELRELAY_API_KEY!);
+const tools = createLocalFSTools({ root: process.cwd() });
+
+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
 
 For the most common path (**system + user → assistant text**):