@inferencesh/ui 0.0.0-stage → 0.1.1

package/src/examples/index.ts

@@ -0,0 +1,1153 @@
+/**
+ * Centralized SDK Code Examples
+ *
+ * All SDK usage examples in one place for easy maintenance.
+ * Used by: app ApiUsage component, docs, README files
+ */
+
+/**
+ * The one API key variable: belt, the SDKs and curl examples all read it.
+ * belt still accepts INFSH_API_KEY as a deprecated fallback (go/cli internal/config).
+ */
+export const API_KEY_ENV = 'INFERENCE_API_KEY';
+
+/** @deprecated Use API_KEY_ENV. */
+export const SDK_API_KEY_ENV = API_KEY_ENV;
+
+/** @deprecated Use API_KEY_ENV. belt reads INFERENCE_API_KEY now. */
+export const CLI_API_KEY_ENV = API_KEY_ENV;
+
+export interface ExampleParams {
+  /** App reference: namespace/name@shortId */
+  appRef: string;
+  /** Short ID of the version (for comments) */
+  shortId?: string;
+  /** Input data */
+  input?: Record<string, unknown>;
+  /** Setup data (optional) */
+  setup?: Record<string, unknown>;
+  /** Infrastructure mode */
+  infra?: string;
+  /** Worker IDs for private infra */
+  workers?: string[];
+}
+
+export interface ExampleOptions {
+  /** Include streaming example */
+  includeStreaming?: boolean;
+  /** Include fire-and-forget example */
+  includeFireAndForget?: boolean;
+  /** JSON indentation */
+  indent?: number;
+}
+
+/**
+ * Build the request data object used in all examples
+ */
+export function buildRequestData(params: ExampleParams): Record<string, unknown> {
+  const { appRef, input, setup, infra, workers } = params;
+  const hasSetup = setup && Object.keys(setup).length > 0;
+
+  return {
+    app: appRef,
+    ...(hasSetup && { setup }),
+    input: input || {},
+    ...(infra && infra !== 'cloud' && { infra }),
+    ...(infra === 'private' && workers && { workers }),
+  };
+}
+
+/**
+ * Generate Python SDK example
+ */
+export function generatePythonExample(
+  params: ExampleParams,
+  options: ExampleOptions = {}
+): string {
+  const { shortId } = params;
+  const { includeStreaming = true } = options;
+  const requestData = buildRequestData(params);
+  const jsonStr = formatJson(requestData, 4, '    ');
+
+  const versionComment = shortId
+    ? `# version @${shortId} pinned`
+    : ``;
+
+  let code = `import os
+from inferencesh import inference, TaskStatus
+
+# initialize client
+client = inference(api_key=os.environ["INFERENCE_API_KEY"])
+
+${versionComment}
+# run and wait for completion (default)
+task = client.tasks.run(${jsonStr})
+
+print(f"Task ID: {task['id']}")
+
+if task["status"] == TaskStatus.COMPLETED:
+    print("Task completed!")
+    print(f"Output: {task['output']}")
+elif task["status"] == TaskStatus.FAILED:
+    print(f"Task failed: {task.get('error')}")`;
+
+  if (includeStreaming) {
+    code += `
+
+# stream updates for real-time progress
+for update in client.tasks.run(${jsonStr}, stream=True):
+    print(f"Status: {update['status']}")
+    if update["status"] == TaskStatus.COMPLETED:
+        print(f"Result: {update['output']}")`;
+  }
+
+  return code;
+}
+
+/**
+ * Generate TypeScript SDK example
+ */
+export function generateTypeScriptExample(
+  params: ExampleParams,
+  options: ExampleOptions = {}
+): string {
+  const { shortId } = params;
+  const { includeStreaming = true, includeFireAndForget = true } = options;
+  const requestData = buildRequestData(params);
+  const jsonStr = formatJson(requestData, 2);
+
+  const versionComment = shortId
+    ? `// version @${shortId} pinned`
+    : ``;
+
+  let code = `import { inference, TaskStatusCompleted, TaskStatusFailed } from '@inferencesh/sdk'
+
+// initialize client
+const client = inference({ apiKey: process.env.INFERENCE_API_KEY })
+
+${versionComment}
+// run and wait for completion (default)
+const task = await client.tasks.run(${jsonStr})
+
+console.log("Task ID:", task.id)
+
+if (task.status === TaskStatusCompleted) {
+  console.log("Task completed!")
+  console.log("Output:", task.output)
+} else if (task.status === TaskStatusFailed) {
+  console.log("Task failed:", task.error)
+}`;
+
+  if (includeStreaming) {
+    code += `
+
+// with real-time status updates
+const result = await client.tasks.run(
+  ${jsonStr},
+  {
+    onUpdate: (update) => {
+      console.log("Status:", update.status)
+    }
+  }
+)`;
+  }
+
+  if (includeFireAndForget) {
+    code += `
+
+// fire and forget (returns immediately)
+const pending = await client.tasks.run(
+  ${jsonStr},
+  { wait: false }
+)
+console.log("Task submitted:", pending.id)`;
+  }
+
+  return code;
+}
+
+/**
+ * Generate JavaScript (CommonJS) SDK example
+ */
+export function generateJavaScriptExample(
+  params: ExampleParams,
+  options: ExampleOptions = {}
+): string {
+  const { shortId } = params;
+  const { includeStreaming = true, includeFireAndForget = true } = options;
+  const requestData = buildRequestData(params);
+  const jsonStr = formatJson(requestData, 2);
+
+  const versionComment = shortId
+    ? `// version @${shortId} pinned`
+    : ``;
+
+  let code = `const { inference, TaskStatusCompleted, TaskStatusFailed } = require('@inferencesh/sdk')
+
+// initialize client
+const client = inference({ apiKey: process.env.INFERENCE_API_KEY })
+
+${versionComment}
+// run and wait for completion (default)
+const task = await client.tasks.run(${jsonStr})
+
+console.log("Task ID:", task.id)
+
+if (task.status === TaskStatusCompleted) {
+  console.log("Task completed!")
+  console.log("Output:", task.output)
+} else if (task.status === TaskStatusFailed) {
+  console.log("Task failed:", task.error)
+}`;
+
+  if (includeStreaming) {
+    code += `
+
+// with real-time status updates
+const result = await client.tasks.run(
+  ${jsonStr},
+  {
+    onUpdate: (update) => {
+      console.log("Status:", update.status)
+    }
+  }
+)`;
+  }
+
+  if (includeFireAndForget) {
+    code += `
+
+// fire and forget (returns immediately)
+const pending = await client.tasks.run(
+  ${jsonStr},
+  { wait: false }
+)
+console.log("Task submitted:", pending.id)`;
+  }
+
+  return code;
+}
+
+// =============================================================================
+// Swift helpers
+// =============================================================================
+
+const SWIFT_INDENT = '    ';
+
+/** Escape a string as a Swift string literal (quotes included). */
+export function swiftString(value: string): string {
+  let out = '"';
+  for (const ch of value) {
+    switch (ch) {
+      case '\\': out += '\\\\'; break;
+      case '"': out += '\\"'; break;
+      case '\n': out += '\\n'; break;
+      case '\r': out += '\\r'; break;
+      case '\t': out += '\\t'; break;
+      case '\0': out += '\\0'; break;
+      default: {
+        const code = ch.codePointAt(0)!;
+        // other control characters (and line/paragraph separators) as \u{...}
+        if (code < 0x20 || code === 0x7f || code === 0x2028 || code === 0x2029) {
+          out += `\\u{${code.toString(16)}}`;
+        } else {
+          out += ch;
+        }
+      }
+    }
+  }
+  return out + '"';
+}
+
+/**
+ * Format a JSON value as a Swift literal for a `JSONValue` context
+ * (dictionaries, arrays, strings, numbers, booleans, `nil`).
+ * Continuation lines are indented relative to `level`.
+ */
+export function formatSwiftValue(value: unknown, level: number = 0): string {
+  if (value === null || value === undefined) return 'nil';
+  if (typeof value === 'string') return swiftString(value);
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'number' || typeof value === 'bigint') {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return 'nil';
+    // integers beyond Int64 would overflow an integer literal; emit a float literal
+    if (Number.isInteger(n) && !Number.isSafeInteger(n)) {
+      const s = String(n);
+      return /[.e]/i.test(s) ? s : `${s}.0`;
+    }
+    return String(n);
+  }
+
+  const pad = SWIFT_INDENT.repeat(level + 1);
+  const closePad = SWIFT_INDENT.repeat(level);
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    // short arrays of scalars stay on one line: ["a", "b"], [512, 768]
+    if (value.every((v) => v === null || typeof v !== 'object')) {
+      const inline = `[${value.map((v) => formatSwiftValue(v, level)).join(', ')}]`;
+      if (inline.length <= 60) return inline;
+    }
+    const items = value.map((v) => `${pad}${formatSwiftValue(v, level + 1)},`);
+    return `[\n${items.join('\n')}\n${closePad}]`;
+  }
+
+  if (typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>).filter(([, v]) => v !== undefined);
+    if (entries.length === 0) return '[:]';
+    const items = entries.map(([k, v]) => `${pad}${swiftString(k)}: ${formatSwiftValue(v, level + 1)},`);
+    return `[\n${items.join('\n')}\n${closePad}]`;
+  }
+
+  return swiftString(String(value));
+}
+
+/** Swift expression for an infra value (`Infra` is a string-backed struct). */
+function swiftInfra(infra: string): string {
+  switch (infra) {
+    case 'cloud': return '.cloud';
+    case 'private': return '.private';
+    case 'private_first': return '.privateFirst';
+    default: return `Infra(rawValue: ${swiftString(infra)})`;
+  }
+}
+
+export interface SwiftAppRunRequestFields {
+  app: string;
+  infra?: string;
+  workers?: string[];
+  webhook?: string;
+  setup?: Record<string, unknown>;
+  input?: Record<string, unknown>;
+}
+
+/**
+ * Format an `ApiAppRunRequest(...)` initializer call.
+ * Labels follow the initializer's declaration order
+ * (app, infra, workers, webhook, setup, input).
+ */
+export function formatSwiftAppRunRequest(fields: SwiftAppRunRequestFields, level: number = 0): string {
+  const pad = SWIFT_INDENT.repeat(level + 1);
+  const args: string[] = [`app: ${swiftString(fields.app)}`];
+  if (fields.infra) args.push(`infra: ${swiftInfra(fields.infra)}`);
+  if (fields.workers) args.push(`workers: ${formatSwiftValue(fields.workers, level + 1)}`);
+  if (fields.webhook) args.push(`webhook: ${swiftString(fields.webhook)}`);
+  if (fields.setup) args.push(`setup: ${formatSwiftValue(fields.setup, level + 1)}`);
+  args.push(`input: ${formatSwiftValue(fields.input || {}, level + 1)}`);
+  return `ApiAppRunRequest(\n${args.map((a) => pad + a).join(',\n')}\n${SWIFT_INDENT.repeat(level)})`;
+}
+
+/** The app run request for the example params, as a Swift initializer call. */
+function swiftRequest(params: ExampleParams, level: number = 0): string {
+  const data = buildRequestData(params) as {
+    app: string;
+    setup?: Record<string, unknown>;
+    input: Record<string, unknown>;
+    infra?: string;
+    workers?: string[];
+  };
+  return formatSwiftAppRunRequest(data, level);
+}
+
+/**
+ * Generate Swift SDK example
+ */
+export function generateSwiftExample(
+  params: ExampleParams,
+  options: ExampleOptions = {}
+): string {
+  const { shortId } = params;
+  const { includeStreaming = true, includeFireAndForget = true } = options;
+
+  const versionComment = shortId
+    ? `// version @${shortId} pinned`
+    : ``;
+
+  let code = `import Foundation
+import InferenceSDK
+
+// initialize client
+let client = InferenceClient(apiKey: ProcessInfo.processInfo.environment["INFERENCE_API_KEY"] ?? "")
+
+${versionComment}
+let request = ${swiftRequest(params)}
+
+// run and wait for completion (default)
+do {
+    let task = try await client.tasks.run(request)
+    print("Task ID:", task.id)
+    print("Output:", task.output)
+} catch let error as TaskRunError {
+    // failed and cancelled tasks throw
+    print("Task failed:", error.localizedDescription)
+}`;
+
+  if (includeStreaming) {
+    code += `
+
+// with real-time status updates
+let result = try await client.tasks.run(
+    request,
+    options: TaskRunOptions(onUpdate: { update in
+        print("Status:", update.status.rawValue)
+    })
+)
+print("Output:", result.output)`;
+  }
+
+  if (includeFireAndForget) {
+    code += `
+
+// fire and forget (returns immediately)
+let pending = try await client.tasks.run(
+    request,
+    options: TaskRunOptions(wait: false)
+)
+print("Task submitted:", pending.id)`;
+  }
+
+  return code;
+}
+
+/**
+ * Swift file upload examples (the Swift SDK does not auto-upload local files)
+ */
+export function generateSwiftFileExamples(appRef: string): { auto: string; manual: string } {
+  return {
+    auto: `// pass file URLs directly as input
+let result = try await client.tasks.run(ApiAppRunRequest(
+    app: ${swiftString(appRef)},
+    input: [
+        "image": "https://example.com/image.png",
+    ]
+))`,
+    manual: `// upload a local file and pass its hosted URL
+let data = try Data(contentsOf: URL(fileURLWithPath: "/path/to/file.png"))
+let file = try await client.files.upload(data, filename: "file.png", contentType: "image/png")
+print(file.uri)  // https://cloud.inference.sh/...`,
+  };
+}
+
+/**
+ * Swift webhook example (fire and forget, result POSTed to the webhook)
+ */
+export function generateSwiftWebhookExample(appRef: string, input: Record<string, unknown>): string {
+  return `let task = try await client.tasks.run(
+    ${formatSwiftAppRunRequest({ app: appRef, webhook: 'https://your-server.com/webhook', input }, 1)},
+    options: TaskRunOptions(wait: false)
+)`;
+}
+
+/**
+ * Generate cURL example
+ */
+export function generateCurlExample(params: ExampleParams): string {
+  const { shortId } = params;
+  const requestData = buildRequestData(params);
+  const jsonStr = JSON.stringify(requestData, null, 2).split('\n').join('\n  ');
+
+  const versionComment = shortId
+    ? `# version @${shortId} pinned`
+    : ``;
+
+  const waitJson = JSON.stringify({ ...requestData, wait: true }, null, 2).split('\n').join('\n  ');
+  const streamJson = JSON.stringify({ ...requestData, stream: true }, null, 2).split('\n').join('\n  ');
+
+  return `${versionComment}
+# run and wait for the result
+curl -X POST https://api.inference.sh/apps/run \\
+  -H "Authorization: Bearer $INFERENCE_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d ${shellQuote(waitJson)}
+
+# or stream live updates (server-sent events)
+curl -N -X POST https://api.inference.sh/apps/run \\
+  -H "Authorization: Bearer $INFERENCE_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d ${shellQuote(streamJson)}`;
+}
+
+/**
+ * Generate all examples for a given set of parameters
+ */
+export function generateAllExamples(
+  params: ExampleParams,
+  options: ExampleOptions = {}
+): Record<string, string> {
+  return {
+    python: generatePythonExample(params, options),
+    typescript: generateTypeScriptExample(params, options),
+    javascript: generateJavaScriptExample(params, options),
+    swift: generateSwiftExample(params, options),
+    curl: generateCurlExample(params),
+    belt: generateBeltExample(params),
+  };
+}
+
+/**
+ * Generate result-only examples (no streaming, just wait for completion)
+ */
+export function generateResultOnlyExamples(params: ExampleParams): Record<string, string> {
+  const requestData = buildRequestData(params);
+  const { shortId } = params;
+
+  const versionCommentPy = shortId
+    ? `# version @${shortId} pinned`
+    : ``;
+
+  const versionCommentJs = shortId
+    ? `// version @${shortId} pinned`
+    : ``;
+
+  const jsonStrPy = formatJson(requestData, 4, '    ');
+  const jsonStrJs = formatJson(requestData, 2);
+  const jsonStrCurl = JSON.stringify({ ...requestData, wait: true }, null, 2).split('\n').join('\n  ');
+  const swiftReq = swiftRequest(params);
+
+  return {
+    python: `import os
+from inferencesh import inference
+
+client = inference(api_key=os.environ["INFERENCE_API_KEY"])
+
+${versionCommentPy}
+result = client.run(${jsonStrPy})
+
+print(result["output"])`,
+
+    typescript: `import { inference } from "@inferencesh/sdk"
+
+const client = inference({ apiKey: process.env.INFERENCE_API_KEY })
+
+${versionCommentJs}
+const result = await client.run(${jsonStrJs})
+
+console.log(result.output)`,
+
+    javascript: `const { inference } = require("@inferencesh/sdk")
+
+const client = inference({ apiKey: process.env.INFERENCE_API_KEY })
+
+${versionCommentJs}
+const result = await client.run(${jsonStrJs})
+
+console.log(result.output)`,
+
+    swift: `import Foundation
+import InferenceSDK
+
+let client = InferenceClient(apiKey: ProcessInfo.processInfo.environment["INFERENCE_API_KEY"] ?? "")
+
+${versionCommentJs}
+let result = try await client.tasks.run(${swiftReq})
+
+print(result.output)`,
+
+    curl: `${versionCommentPy}
+# "wait": true holds the connection until the task finishes.
+# the response is {"data": {"id", "status", "status_text", "output", ...}}
+curl -X POST https://api.inference.sh/apps/run \\
+  -H "Authorization: Bearer $INFERENCE_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d ${shellQuote(jsonStrCurl)}`,
+
+    belt: `${versionCommentPy}
+belt app run ${params.appRef} --input ${shellQuote(JSON.stringify(requestData.input || {}))}`,
+  };
+}
+
+/**
+ * Generate streaming examples (real-time updates)
+ */
+export function generateStreamingExamples(params: ExampleParams): Record<string, string> {
+  const requestData = buildRequestData(params);
+  const { shortId } = params;
+
+  const versionCommentPy = shortId
+    ? `# version @${shortId} pinned`
+    : ``;
+
+  const versionCommentJs = shortId
+    ? `// version @${shortId} pinned`
+    : ``;
+
+  const jsonStrPy = formatJson(requestData, 4, '    ');
+  const jsonStrJs = formatJson(requestData, 2);
+  const jsonStrCurl = JSON.stringify({ ...requestData, stream: true }, null, 2).split('\n').join('\n  ');
+
+  return {
+    python: `import os
+from inferencesh import inference
+
+client = inference(api_key=os.environ["INFERENCE_API_KEY"])
+
+${versionCommentPy}
+# stream=True yields updates as they arrive
+for update in client.run(${jsonStrPy}, stream=True):
+    if update.get("progress"):
+        print(f"progress: {update['progress']}%")
+    if update.get("output"):
+        print(f"output: {update['output']}")`,
+
+    typescript: `import { inference } from "@inferencesh/sdk"
+
+const client = inference({ apiKey: process.env.INFERENCE_API_KEY })
+
+${versionCommentJs}
+// onUpdate callback fires on each status change
+const result = await client.run(${jsonStrJs}, {
+  onUpdate: (update) => {
+    if (update.progress) {
+      console.log(\`progress: \${update.progress}%\`)
+    }
+    if (update.output) {
+      console.log("output:", update.output)
+    }
+  }
+})`,
+
+    javascript: `const { inference } = require("@inferencesh/sdk")
+
+const client = inference({ apiKey: process.env.INFERENCE_API_KEY })
+
+${versionCommentJs}
+// onUpdate callback fires on each status change
+const result = await client.run(${jsonStrJs}, {
+  onUpdate: (update) => {
+    if (update.progress) {
+      console.log(\`progress: \${update.progress}%\`)
+    }
+    if (update.output) {
+      console.log("output:", update.output)
+    }
+  }
+})`,
+
+    swift: `import Foundation
+import InferenceSDK
+
+let client = InferenceClient(apiKey: ProcessInfo.processInfo.environment["INFERENCE_API_KEY"] ?? "")
+
+${versionCommentJs}
+// onUpdate fires on each status change
+let result = try await client.tasks.run(
+    ${swiftRequest(params, 1)},
+    options: TaskRunOptions(onUpdate: { update in
+        print("status:", update.status.rawValue)
+    })
+)
+
+print("output:", result.output)`,
+
+    curl: `${versionCommentPy}
+# "stream": true answers with server-sent events until the task finishes
+curl -N -X POST https://api.inference.sh/apps/run \\
+  -H "Authorization: Bearer $INFERENCE_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d ${shellQuote(jsonStrCurl)}`,
+
+    belt: `${versionCommentPy}
+# belt streams progress by default
+belt app run ${params.appRef} --input ${shellQuote(JSON.stringify(requestData.input || {}))}`,
+  };
+}
+
+/**
+ * Run without waiting, then check on the task later.
+ * Each SDK returns the task right away; GET /tasks/{id} reads its state.
+ */
+export function generateBackgroundExamples(params: ExampleParams): Record<string, string> {
+  const requestData = buildRequestData(params);
+  const jsonStrPy = formatJson(requestData, 4, '    ');
+  const jsonStrJs = formatJson(requestData, 2);
+  const jsonStrCurl = JSON.stringify(requestData, null, 2).split('\n').join('\n  ');
+  const jsClient = (importLine: string) => `${importLine}
+
+const client = inference({ apiKey: process.env.INFERENCE_API_KEY })
+
+// returns as soon as the task is created
+const task = await client.run(${jsonStrJs}, { wait: false })
+
+// later: read its current state
+const { data: state } = await client.tasks.get(task.id)
+if (state.status === TaskStatusCompleted) {
+  console.log(state.output)
+}`;
+
+  return {
+    python: `import os
+from inferencesh import inference, TaskStatus
+
+client = inference(api_key=os.environ["INFERENCE_API_KEY"])
+
+# returns as soon as the task is created
+task = client.run(${jsonStrPy}, wait=False)
+
+# later: read its current state
+state = client.tasks.get(task["id"]).data
+if state["status"] == TaskStatus.COMPLETED:
+    print(state["output"])`,
+
+    typescript: jsClient(`import { inference, TaskStatusCompleted } from "@inferencesh/sdk"`),
+    javascript: jsClient(`const { inference, TaskStatusCompleted } = require("@inferencesh/sdk")`),
+
+    swift: `import Foundation
+import InferenceSDK
+
+let client = InferenceClient(apiKey: ProcessInfo.processInfo.environment["INFERENCE_API_KEY"] ?? "")
+
+// returns as soon as the task is created
+let task = try await client.tasks.run(
+    ${swiftRequest(params, 1)},
+    options: TaskRunOptions(wait: false)
+)
+
+// later: read its current state
+let state = try await client.tasks.get(task.id)
+print(state.status, state.output)`,
+
+    curl: `# without "wait" the call returns the task right away (status 1, "received")
+TASK_ID=$(curl -s -X POST https://api.inference.sh/apps/run \\
+  -H "Authorization: Bearer $INFERENCE_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d ${shellQuote(jsonStrCurl)} | jq -r '.data.id')
+
+# later: read its state. done when status is 10 (completed), 11 (failed) or 12 (cancelled)
+curl -s https://api.inference.sh/tasks/$TASK_ID \\
+  -H "Authorization: Bearer $INFERENCE_API_KEY" | jq '.data | {status, status_text, output}'`,
+
+    belt: `# returns the task id without waiting
+belt app run ${params.appRef} --input ${shellQuote(JSON.stringify(requestData.input || {}))} --no-wait
+
+# later: read its state (-f follows it until it finishes)
+belt task get TASK_ID -f`,
+  };
+}
+
+/**
+ * File input examples: passing files in, and uploading one by hand.
+ */
+export function generateFileExamples(appRef: string): Record<string, { auto: string; manual: string }> {
+  const js = {
+    auto: `// File/Blob objects and data URIs are automatically uploaded
+const result = await client.run({
+  app: "${appRef}",
+  input: {
+    image: fileInput.files[0],  // File from <input> - uploaded
+    photo: await fetch(url).then(r => r.blob()),  // Blob - uploaded
+    icon: "data:image/png;base64,...",  // data URI - uploaded
+  }
+})`,
+    manual: `// upload and get a hosted URL
+const file = await client.files.upload(blob, {
+  filename: "image.png",
+  contentType: "image/png"
+})
+console.log(file.uri)  // https://cloud.inference.sh/...`,
+  };
+  return {
+    python: {
+      auto: `# local file paths are automatically uploaded
+result = client.run({
+    "app": "${appRef}",
+    "input": {
+        "image": "/path/to/local/image.png",  # detected & uploaded
+        "audio": "https://example.com/audio.mp3",  # url passed through
+    }
+})`,
+      manual: `# upload and get a hosted URL
+file = client.files.upload("/path/to/file.png")
+print(file.uri)  # https://cloud.inference.sh/...`,
+    },
+    typescript: js,
+    javascript: js,
+    swift: generateSwiftFileExamples(appRef),
+    curl: {
+      auto: `# pass URLs or data URIs as input values
+curl -X POST https://api.inference.sh/apps/run \\
+  -H "Authorization: Bearer $INFERENCE_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "app": "${appRef}",
+    "input": {
+      "image": "https://example.com/image.png",
+      "audio": "data:audio/mp3;base64,..."
+    },
+    "wait": true
+  }'`,
+      manual: `# 1. create the file: the response has an upload_url and the file's uri
+FILE=$(curl -s -X POST https://api.inference.sh/files \\
+  -H "Authorization: Bearer $INFERENCE_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d '{"files": [{"filename": "image.png", "content_type": "image/png"}]}')
+
+# 2. PUT the bytes to upload_url
+curl -X PUT "$(echo "$FILE" | jq -r '.data[0].upload_url')" \\
+  -H "Content-Type: image/png" \\
+  --data-binary @image.png
+
+# 3. pass the uri as an input value
+echo "$FILE" | jq -r '.data[0].uri'`,
+    },
+    belt: {
+      auto: `# belt uploads local paths in the input for you
+belt app run ${appRef} --input '{"image": "/path/to/local/image.png"}'`,
+      manual: `# files are handled automatically by belt
+# pass local paths or URLs in the input JSON`,
+    },
+  };
+}
+
+/**
+ * Generate belt CLI example
+ */
+export function generateBeltExample(params: ExampleParams): string {
+  const { appRef, input } = params;
+  const inputJson = shellQuote(JSON.stringify(input || {}));
+
+  return `# install belt
+curl -fsSL https://cli.inference.sh | sh
+
+# sign in (or set ${API_KEY_ENV} on a headless machine)
+belt login
+
+# run and wait for result
+belt app run ${appRef} --input ${inputJson}
+
+# save output to file
+belt app run ${appRef} --input ${inputJson} -o result.json
+
+# get app details and schema
+belt app get ${appRef}`;
+}
+
+/**
+ * Install commands for each language
+ */
+export const installCommands: Record<string, { command: string; label: string } | null> = {
+  python: { command: 'pip install inferencesh', label: '$' },
+  typescript: { command: 'npm install @inferencesh/sdk', label: '$' },
+  javascript: { command: 'npm install @inferencesh/sdk', label: '$' },
+  swift: { command: '.package(url: "https://github.com/inference-sh/sdk-swift", from: "0.1.0")', label: 'spm' },
+  curl: null,
+  belt: { command: 'curl -fsSL https://cli.inference.sh | sh', label: '$' },
+};
+
+/**
+ * How each language picks up the API key. Every tool reads the same variable,
+ * API_KEY_ENV; belt also uses its saved login.
+ */
+export const apiKeySetup: Record<string, { variable: string; command: string }> = {
+  python: { variable: API_KEY_ENV, command: `export ${API_KEY_ENV}="inf_your_key"` },
+  typescript: { variable: API_KEY_ENV, command: `export ${API_KEY_ENV}="inf_your_key"` },
+  javascript: { variable: API_KEY_ENV, command: `export ${API_KEY_ENV}="inf_your_key"` },
+  swift: { variable: API_KEY_ENV, command: `export ${API_KEY_ENV}="inf_your_key"` },
+  curl: { variable: API_KEY_ENV, command: `export ${API_KEY_ENV}="inf_your_key"` },
+  belt: {
+    variable: API_KEY_ENV,
+    command: `# sign in from a browser
+belt login
+
+# or, on a headless machine
+export ${API_KEY_ENV}="inf_your_key"`,
+  },
+};
+
+/** Quote a string for a POSIX shell: single quotes, with any single quote spliced in. */
+export function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+// Helper to format JSON with custom indentation for nested content
+function formatJson(obj: Record<string, unknown>, indent: number, prefix: string = ''): string {
+  const json = JSON.stringify(obj, null, indent);
+  if (!prefix) return json;
+  return json.split('\n').map((line, i) => i === 0 ? line : prefix + line).join('\n');
+}
+
+// =============================================================================
+// Agent Examples
+// =============================================================================
+
+export interface AgentExampleParams {
+  /** Agent reference: namespace/name@shortVersionId */
+  agentRef: string;
+  /** Short version ID (for comments) */
+  shortVersionId?: string;
+}
+
+/**
+ * Generate Python Agent SDK example
+ */
+export function generateAgentPythonExample(params: AgentExampleParams): string {
+  const { agentRef, shortVersionId } = params;
+
+  const versionComment = shortVersionId
+    ? `# version @${shortVersionId} pinned`
+    : ``;
+
+  return `import os
+from inferencesh import inference
+
+# initialize client
+client = inference(api_key=os.environ["INFERENCE_API_KEY"])
+
+${versionComment}
+# create agent from template
+agent = client.agents.create("${agentRef}")
+
+# send a message
+response = agent.send_message("Hello!")
+print(response)
+
+# with streaming
+def on_message(msg):
+    if msg.get("content"):
+        print(msg["content"], end="", flush=True)
+
+def on_tool_call(call):
+    print(f"\\n[Tool: {call.name}]")
+    result = handle_tool(call.name, call.args)
+    agent.submit_tool_result(call.id, result)
+
+response = agent.send_message(
+    "Help me with something",
+    on_message=on_message,
+    on_tool_call=on_tool_call
+)
+
+# get chat history
+chat = agent.get_chat()
+print(f"Chat ID: {chat['id']}")
+
+# stop generation
+agent.stop_chat()
+
+# start fresh conversation
+agent.reset()`;
+}
+
+/**
+ * Generate TypeScript Agent SDK example
+ */
+export function generateAgentTypeScriptExample(params: AgentExampleParams): string {
+  const { agentRef, shortVersionId } = params;
+
+  const versionComment = shortVersionId
+    ? `// version @${shortVersionId} pinned`
+    : ``;
+
+  return `import { inference } from '@inferencesh/sdk'
+
+// initialize client
+const client = inference({ apiKey: process.env.INFERENCE_API_KEY })
+
+${versionComment}
+// create agent from template
+const agent = client.agents.create('${agentRef}')
+
+// send a message
+const response = await agent.sendMessage('Hello!')
+console.log(response)
+
+// with streaming
+await agent.sendMessage('Help me with something', {
+  onMessage: (msg) => {
+    if (msg.content) {
+      for (const c of msg.content) {
+        if (c.type === 'text' && c.text) {
+          process.stdout.write(c.text)
+        }
+      }
+    }
+  },
+  onToolCall: async (call) => {
+    console.log(\`\\n[Tool: \${call.name}]\`)
+    const result = await handleTool(call.name, call.args)
+    await agent.submitToolResult(call.id, result)
+  }
+})
+
+// get chat history
+const chat = await agent.getChat()
+console.log('Chat ID:', chat?.id)
+
+// stop generation
+await agent.stopChat()
+
+// cleanup
+agent.disconnect()`;
+}
+
+/**
+ * Generate JavaScript Agent SDK example
+ */
+export function generateAgentJavaScriptExample(params: AgentExampleParams): string {
+  const { agentRef, shortVersionId } = params;
+
+  const versionComment = shortVersionId
+    ? `// version @${shortVersionId} pinned`
+    : ``;
+
+  return `const { inference } = require('@inferencesh/sdk')
+
+// initialize client
+const client = inference({ apiKey: process.env.INFERENCE_API_KEY })
+
+${versionComment}
+// create agent from template
+const agent = client.agents.create('${agentRef}')
+
+// send a message
+const response = await agent.sendMessage('Hello!')
+console.log(response)
+
+// with streaming
+await agent.sendMessage('Help me with something', {
+  onMessage: (msg) => {
+    if (msg.content) {
+      for (const c of msg.content) {
+        if (c.type === 'text' && c.text) {
+          process.stdout.write(c.text)
+        }
+      }
+    }
+  },
+  onToolCall: async (call) => {
+    console.log(\`\\n[Tool: \${call.name}]\`)
+    const result = await handleTool(call.name, call.args)
+    await agent.submitToolResult(call.id, result)
+  }
+})
+
+// get chat history
+const chat = await agent.getChat()
+console.log('Chat ID:', chat?.id)
+
+// stop generation
+await agent.stopChat()
+
+// cleanup
+agent.disconnect()`;
+}
+
+/**
+ * Generate Swift Agent SDK example
+ */
+export function generateAgentSwiftExample(params: AgentExampleParams): string {
+  const { agentRef, shortVersionId } = params;
+
+  const versionComment = shortVersionId
+    ? `// version @${shortVersionId} pinned`
+    : ``;
+
+  return `import InferenceSDK
+
+// initialize client
+let client = InferenceClient(apiKey: ProcessInfo.processInfo.environment["INFERENCE_API_KEY"] ?? "")
+
+${versionComment}
+// one-shot run: streams snapshots of the reply until it finishes
+let request = ApiAgentRunRequest(agent: ${swiftString(agentRef)}, input: LLMInput(text: "Hello!"))
+for try await message in client.runAgentStream(request) {
+    if message.status.isTerminal {
+        print(message.text)
+        break
+    }
+}
+
+// chat session: keeps the conversation and follows its stream
+// (AgentChatSession is @MainActor)
+let session = AgentChatSession(client: client, agent: ${swiftString(agentRef)})
+
+session.onChange = { state in
+    // every state change: messages, chat status, connection, errors
+    if let last = state.messages.last {
+        print(last.role.rawValue, last.text)
+    }
+}
+session.callbacks.onTurnEnd = { chat in
+    print("Chat ID:", chat.id)
+}
+
+// send a message
+await session.sendMessage("Help me with something")
+
+// tool calls that need the user wait in message.toolInvocations:
+// try await session.approveTool(invocation.id)
+// try await session.submitToolResult(invocation.id, result: resultJSON)
+
+// stop generation
+session.stopGeneration()
+
+// start fresh conversation
+session.reset()`;
+}
+
+/**
+ * Generate cURL Agent example
+ */
+export function generateAgentCurlExample(params: AgentExampleParams): string {
+  const { agentRef, shortVersionId } = params;
+
+  const versionComment = shortVersionId
+    ? `# Using pinned version @${shortVersionId} (recommended for production)`
+    : `# Using latest version (add version_id for production stability)`;
+
+  return `${versionComment}
+# send a message with streaming
+curl -N -X POST \\
+  -H "Authorization: Bearer $INFERENCE_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "agent": "${agentRef}",
+    "input": {"text": "Hello!", "role": "user"},
+    "stream": true
+  }' \\
+  https://api.inference.sh/agents/run
+
+# without streaming (returns JSON with chat_id)
+curl -X POST \\
+  -H "Authorization: Bearer $INFERENCE_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "agent": "${agentRef}",
+    "input": {"text": "Hello!", "role": "user"}
+  }' \\
+  https://api.inference.sh/agents/run
+
+# continue conversation (use chat_id from previous response)
+curl -N -X POST \\
+  -H "Authorization: Bearer $INFERENCE_API_KEY" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "agent": "${agentRef}",
+    "chat_id": "CHAT_ID",
+    "input": {"text": "Tell me more", "role": "user"},
+    "stream": true
+  }' \\
+  https://api.inference.sh/agents/run
+
+# stop generation
+curl -X POST \\
+  -H "Authorization: Bearer $INFERENCE_API_KEY" \\
+  https://api.inference.sh/chats/CHAT_ID/stop`;
+}
+
+/**
+ * Generate all agent examples
+ */
+export function generateAllAgentExamples(params: AgentExampleParams): Record<string, string> {
+  return {
+    python: generateAgentPythonExample(params),
+    typescript: generateAgentTypeScriptExample(params),
+    javascript: generateAgentJavaScriptExample(params),
+    swift: generateAgentSwiftExample(params),
+    curl: generateAgentCurlExample(params),
+  };
+}
+
+// Re-export guide markdown generator
+export { generateGuideMarkdown } from './guide-markdown'
+export type { GuideApp, GuideVersion, GuideLanguage } from './guide-markdown'