@ryanfw/prompt-orchestration-pipeline 0.16.3 → 0.17.0

package/src/pages/Code.jsx

@@ -24,11 +24,75 @@ import {
 const sections = [
   { id: "environment", label: "Environment", icon: Key },
   { id: "getting-started", label: "Getting Started", icon: FileText },
+  { id: "pipeline-config", label: "Pipeline Config", icon: Folder },
   { id: "io-api", label: "IO API", icon: Database },
   { id: "llm-api", label: "LLM API", icon: Cpu },
   { id: "validation", label: "Validation", icon: Shield },
 ];
 
+// Sample pipeline.json for documentation
+const samplePipelineJson = {
+  name: "content-generation",
+  version: "1.0.0",
+  description: "Demo pipeline showcasing multi-stage LLM workflows",
+  tasks: ["research", "analysis", "synthesis", "formatting"],
+  taskConfig: {
+    research: {
+      maxRetries: 3,
+    },
+  },
+  llm: {
+    provider: "anthropic",
+    model: "claude-sonnet-4-20250514",
+  },
+};
+
+// Pipeline.json field definitions
+const pipelineFields = [
+  {
+    name: "name",
+    required: true,
+    type: "string",
+    description:
+      "Unique identifier for the pipeline. Used to reference this pipeline from seed files.",
+  },
+  {
+    name: "version",
+    required: false,
+    type: "string",
+    description:
+      'Semantic version of the pipeline (e.g., "1.0.0"). Useful for tracking changes.',
+  },
+  {
+    name: "description",
+    required: false,
+    type: "string",
+    description: "Human-readable description of what this pipeline does.",
+  },
+  {
+    name: "tasks",
+    required: true,
+    type: "string[]",
+    description:
+      "Ordered array of task names to execute. Each task must be registered in the task index.",
+  },
+  {
+    name: "taskConfig",
+    required: false,
+    type: "object",
+    description:
+      "Per-task configuration overrides. Keys are task names, values are config objects passed to stages.",
+  },
+  {
+    name: "llm",
+    required: false,
+    type: "{ provider, model }",
+    description:
+      "Pipeline-level LLM override. When set, ALL task LLM calls are routed to this provider/model.",
+    isNew: true,
+  },
+];
+
 // IO Functions organized by category
 const writeFunctions = [
   {
@@ -125,6 +189,7 @@ const envVars = [
   { name: "GEMINI_API_KEY", provider: "Google Gemini" },
   { name: "DEEPSEEK_API_KEY", provider: "DeepSeek" },
   { name: "ZHIPU_API_KEY", provider: "Zhipu" },
+  { name: "MOONSHOT_API_KEY", provider: "Moonshot" },
 ];
 
 // Collapsible Section Component
@@ -231,7 +296,7 @@ export default function CodePage() {
           }
         });
       },
-      { rootMargin: "-100px 0px -66% 0px" }
+      { rootMargin: "-100px 0px -66% 0px" },
     );
 
     sections.forEach(({ id }) => {
@@ -405,6 +470,140 @@ export default function CodePage() {
             </div>
           </CollapsibleSection>
 
+          {/* Pipeline Config Section */}
+          <CollapsibleSection
+            id="pipeline-config"
+            title="Pipeline Configuration (pipeline.json)"
+            icon={Folder}
+            defaultOpen={true}
+          >
+            <Text as="p" size="3" className="text-gray-600 mb-4">
+              Each pipeline is defined by a <Code size="2">pipeline.json</Code>{" "}
+              file in its directory. This file specifies which tasks to run and
+              optional configuration overrides.
+            </Text>
+
+            <div className="space-y-6">
+              {/* Fields Table */}
+              <div>
+                <Text size="2" weight="medium" className="mb-3 block">
+                  Fields
+                </Text>
+                <div className="border border-gray-200 rounded-lg overflow-hidden">
+                  <Table.Root>
+                    <Table.Header>
+                      <Table.Row>
+                        <Table.ColumnHeaderCell className="bg-gray-50">
+                          Field
+                        </Table.ColumnHeaderCell>
+                        <Table.ColumnHeaderCell className="bg-gray-50">
+                          Type
+                        </Table.ColumnHeaderCell>
+                        <Table.ColumnHeaderCell className="bg-gray-50">
+                          Required
+                        </Table.ColumnHeaderCell>
+                        <Table.ColumnHeaderCell className="bg-gray-50">
+                          Description
+                        </Table.ColumnHeaderCell>
+                      </Table.Row>
+                    </Table.Header>
+                    <Table.Body>
+                      {pipelineFields.map((field) => (
+                        <Table.Row key={field.name}>
+                          <Table.RowHeaderCell>
+                            <Flex align="center" gap="2">
+                              <Code size="2">{field.name}</Code>
+                              {field.isNew && (
+                                <span className="px-1.5 py-0.5 text-xs font-medium bg-green-100 text-green-700 rounded">
+                                  NEW
+                                </span>
+                              )}
+                            </Flex>
+                          </Table.RowHeaderCell>
+                          <Table.Cell>
+                            <Code size="1" className="text-gray-600">
+                              {field.type}
+                            </Code>
+                          </Table.Cell>
+                          <Table.Cell>
+                            {field.required ? (
+                              <span className="text-red-600 font-medium">
+                                Yes
+                              </span>
+                            ) : (
+                              <span className="text-gray-400">No</span>
+                            )}
+                          </Table.Cell>
+                          <Table.Cell className="text-gray-600 text-sm">
+                            {field.description}
+                          </Table.Cell>
+                        </Table.Row>
+                      ))}
+                    </Table.Body>
+                  </Table.Root>
+                </div>
+              </div>
+
+              {/* Example */}
+              <div>
+                <Text size="2" weight="medium" className="mb-2 block">
+                  Example
+                </Text>
+                <CopyableCodeBlock maxHeight="280px">
+                  {JSON.stringify(samplePipelineJson, null, 2)}
+                </CopyableCodeBlock>
+              </div>
+
+              {/* LLM Override Details */}
+              <div className="bg-blue-50 border border-blue-200 rounded-lg p-4">
+                <Flex align="center" gap="2" className="mb-2">
+                  <Cpu className="h-4 w-4 text-blue-600" />
+                  <Text size="2" weight="medium" className="text-blue-800">
+                    Pipeline-Level LLM Override
+                  </Text>
+                  <span className="px-1.5 py-0.5 text-xs font-medium bg-green-100 text-green-700 rounded">
+                    NEW
+                  </span>
+                </Flex>
+                <Text as="p" size="2" className="text-blue-700 mb-3">
+                  When the <Code size="2">llm</Code> field is set in
+                  pipeline.json, ALL LLM calls from task stages are
+                  automatically routed to the specified provider and model —
+                  regardless of what the task code requests.
+                </Text>
+                <ul className="space-y-1 text-sm text-blue-700">
+                  <li className="flex items-start gap-2">
+                    <span className="text-blue-500 mt-0.5">•</span>
+                    <span>
+                      Tasks calling <Code size="1">llm.deepseek.chat()</Code>{" "}
+                      will use the override provider/model
+                    </span>
+                  </li>
+                  <li className="flex items-start gap-2">
+                    <span className="text-blue-500 mt-0.5">•</span>
+                    <span>
+                      Original provider/model is preserved in{" "}
+                      <Code size="1">metadata.originalProvider</Code>
+                    </span>
+                  </li>
+                  <li className="flex items-start gap-2">
+                    <span className="text-blue-500 mt-0.5">•</span>
+                    <span>
+                      Useful for A/B testing, cost control, or switching
+                      providers during outages
+                    </span>
+                  </li>
+                </ul>
+              </div>
+
+              {/* File Location */}
+              <div className="text-sm text-gray-500">
+                <span>Location: </span>
+                <Code size="2">{"{pipelineDir}"}/pipeline.json</Code>
+              </div>
+            </div>
+          </CollapsibleSection>
+
           {/* IO API Section */}
           <CollapsibleSection
             id="io-api"
@@ -529,7 +728,7 @@ export default function CodePage() {
                                   </Code>
                                 </Table.Cell>
                               </Table.Row>
-                            ))
+                            )),
                         )}
                       </Table.Body>
                     </Table.Root>

package/src/providers/anthropic.js

@@ -6,6 +6,7 @@ import {
   tryParseJSON,
   ensureJsonResponseFormat,
   ProviderJsonParseError,
+  createProviderError,
 } from "./base.js";
 import { createLogger } from "../core/logger.js";
 
@@ -70,10 +71,10 @@ export async function anthropicChat({
       });
 
       if (!response.ok) {
-        const error = await response
+        const errorBody = await response
           .json()
           .catch(() => ({ error: response.statusText }));
-        throw { status: response.status, ...error };
+        throw createProviderError(response.status, errorBody, response.statusText);
       }
 
       const data = await response.json();

package/src/providers/base.js

@@ -89,6 +89,25 @@ export function tryParseJSON(text) {
   }
 }
 
+/**
+ * Creates a proper Error instance from an HTTP error response.
+ * This ensures errors have proper stack traces and don't cause
+ * "UnhandledPromiseRejection: #<Object>" crashes.
+ * 
+ * @param {number} status - HTTP status code
+ * @param {Object} errorBody - Parsed error response body
+ * @param {string} fallbackMessage - Fallback message if none in errorBody
+ * @returns {Error} Error instance with status and details attached
+ */
+export function createProviderError(status, errorBody, fallbackMessage = "Request failed") {
+  const message = errorBody?.error?.message || errorBody?.message || fallbackMessage;
+  const err = new Error(`[${status}] ${message}`);
+  err.status = status;
+  err.code = errorBody?.error?.code || errorBody?.code;
+  err.details = errorBody;
+  return err;
+}
+
 /**
  * Error thrown when JSON response format is required but not provided
  */

package/src/providers/claude-code.js

@@ -0,0 +1,156 @@
+import { spawn, spawnSync } from "child_process";
+import {
+  extractMessages,
+  isRetryableError,
+  sleep,
+  stripMarkdownFences,
+  tryParseJSON,
+  ensureJsonResponseFormat,
+  ProviderJsonParseError,
+} from "./base.js";
+import { createLogger } from "../core/logger.js";
+
+const logger = createLogger("ClaudeCode");
+
+/**
+ * Check if Claude Code CLI is available
+ * @returns {boolean}
+ */
+export function isClaudeCodeAvailable() {
+  try {
+    const result = spawnSync("claude", ["--version"], {
+      encoding: "utf8",
+      timeout: 5000,
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Chat with Claude via the Claude Code CLI
+ * @param {Object} options
+ * @param {Array} options.messages - Array of message objects with role and content
+ * @param {string} [options.model="sonnet"] - Model name: sonnet, opus, or haiku
+ * @param {number} [options.maxTokens] - Maximum tokens in response
+ * @param {number} [options.maxTurns=1] - Maximum conversation turns
+ * @param {string} [options.responseFormat="json"] - Response format
+ * @param {number} [options.maxRetries=3] - Maximum retry attempts
+ * @returns {Promise<{content: any, text: string, usage: Object, raw: any}>}
+ */
+export async function claudeCodeChat({
+  messages,
+  model = "sonnet",
+  maxTokens,
+  maxTurns = 1,
+  responseFormat = "json",
+  maxRetries = 3,
+}) {
+  ensureJsonResponseFormat(responseFormat, "ClaudeCode");
+
+  const { systemMsg, userMsg } = extractMessages(messages);
+
+  const args = [
+    "-p",
+    userMsg,
+    "--output-format",
+    "json",
+    "--model",
+    model,
+    "--max-turns",
+    String(maxTurns),
+  ];
+
+  if (systemMsg) {
+    args.push("--system-prompt", systemMsg);
+  }
+
+  if (maxTokens) {
+    args.push("--max-tokens", String(maxTokens));
+  }
+
+  logger.log("Spawning claude CLI", { model, argsCount: args.length });
+
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const result = await spawnClaude(args);
+      return parseClaudeResponse(result, model);
+    } catch (err) {
+      lastError = err;
+      if (attempt < maxRetries && isRetryableError(err)) {
+        const delay = Math.pow(2, attempt) * 1000;
+        logger.log(`Retry ${attempt + 1}/${maxRetries} after ${delay}ms`);
+        await sleep(delay);
+        continue;
+      }
+      throw err;
+    }
+  }
+  throw lastError;
+}
+
+/**
+ * Spawn the claude CLI and collect output
+ * @param {string[]} args - CLI arguments
+ * @returns {Promise<string>} - stdout content
+ */
+function spawnClaude(args) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("claude", args, { stdio: ["ignore", "pipe", "pipe"] });
+
+    let stdout = "";
+    let stderr = "";
+
+    proc.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+
+    proc.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+
+    proc.on("error", (err) => {
+      reject(new Error(`Failed to spawn claude CLI: ${err.message}`));
+    });
+
+    proc.on("close", (code) => {
+      if (code === 0) {
+        resolve(stdout);
+      } else {
+        reject(new Error(`claude CLI exited with code ${code}: ${stderr}`));
+      }
+    });
+  });
+}
+
+/**
+ * Parse the JSON response from Claude CLI
+ * @param {string} stdout - Raw stdout from CLI
+ * @param {string} model - Model name for error reporting
+ * @returns {{content: any, text: string, usage: Object, raw: any}}
+ */
+function parseClaudeResponse(stdout, model) {
+  const jsonResponse = tryParseJSON(stdout);
+  if (!jsonResponse) {
+    throw new ProviderJsonParseError(
+      "claudecode",
+      model,
+      stdout.slice(0, 200),
+      "Failed to parse Claude CLI JSON response"
+    );
+  }
+
+  // Extract text content from response
+  const rawText = jsonResponse.result ?? jsonResponse.text ?? "";
+  const cleanedText = stripMarkdownFences(rawText);
+  const parsed = tryParseJSON(cleanedText) ?? cleanedText;
+
+  return {
+    content: parsed,
+    text: rawText,
+    usage: { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 },
+    raw: jsonResponse,
+  };
+}

package/src/providers/deepseek.js

@@ -6,6 +6,7 @@ import {
   tryParseJSON,
   ensureJsonResponseFormat,
   ProviderJsonParseError,
+  createProviderError,
 } from "./base.js";
 import { createLogger } from "../core/logger.js";
 
@@ -77,10 +78,10 @@ export async function deepseekChat({
       );
 
       if (!response.ok) {
-        const error = await response
+        const errorBody = await response
           .json()
           .catch(() => ({ error: response.statusText }));
-        throw { status: response.status, ...error };
+        throw createProviderError(response.status, errorBody, response.statusText);
       }
 
       // Streaming mode - return async generator for real-time chunks

package/src/providers/moonshot.js

@@ -0,0 +1,218 @@
+import {
+  extractMessages,
+  isRetryableError,
+  sleep,
+  stripMarkdownFences,
+  tryParseJSON,
+  ProviderJsonParseError,
+  createProviderError,
+} from "./base.js";
+import { createLogger } from "../core/logger.js";
+
+const logger = createLogger("Moonshot");
+
+export async function moonshotChat({
+  messages,
+  model = "moonshot-v1-128k",
+  temperature = 0.7,
+  maxTokens,
+  responseFormat = "json_object",
+  topP,
+  frequencyPenalty,
+  presencePenalty,
+  stop,
+  stream = false,
+  maxRetries = 3,
+}) {
+  const isJsonMode =
+    responseFormat?.type === "json_object" ||
+    responseFormat?.type === "json_schema" ||
+    responseFormat === "json" ||
+    responseFormat === "json_object";
+
+  logger.log("moonshotChat called", { model, stream, maxRetries, isJsonMode });
+
+  if (!process.env.MOONSHOT_API_KEY) {
+    throw new Error("Moonshot API key not configured");
+  }
+
+  const { systemMsg, userMsg } = extractMessages(messages);
+
+  logger.log("Messages extracted", {
+    systemMsgLength: systemMsg?.length,
+    userMsgLength: userMsg?.length,
+  });
+
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    if (attempt > 0) {
+      const sleepMs = Math.pow(2, attempt) * 1000;
+      logger.log("Retry attempt", { attempt, sleepMs });
+      await sleep(sleepMs);
+    }
+
+    try {
+      logger.log("Sending request to Moonshot API", { attempt, model });
+      // Thinking models only accept temperature=1
+      //const isThinkingModel = model.includes("thinking");
+      //const effectiveTemperature = isThinkingModel ? 1 : temperature;
+
+      const requestBody = {
+        model,
+        messages: [
+          { role: "system", content: systemMsg },
+          { role: "user", content: userMsg },
+        ],
+        temperature: 1,
+        max_tokens: maxTokens,
+        top_p: topP,
+        frequency_penalty: frequencyPenalty,
+        presence_penalty: presencePenalty,
+        stop,
+        stream,
+      };
+
+      if (isJsonMode && !stream) {
+        requestBody.response_format = { type: "json_object" };
+      }
+
+      logger.log("About to call fetch...");
+      const response = await fetch(
+        "https://api.moonshot.ai/v1/chat/completions",
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${process.env.MOONSHOT_API_KEY}`,
+          },
+          body: JSON.stringify(requestBody),
+        },
+      );
+      logger.log("Fetch returned", {
+        status: response.status,
+        ok: response.ok,
+      });
+
+      if (!response.ok) {
+        const errorBody = await response
+          .json()
+          .catch(() => ({ error: response.statusText }));
+
+        // Provide more helpful error message for authentication failures
+        if (response.status === 401) {
+          const enhancedError = createProviderError(
+            response.status,
+            errorBody,
+            "Invalid Moonshot API key. Please verify your MOONSHOT_API_KEY environment variable is correct and has not expired. Get your API key at https://platform.moonshot.ai/",
+          );
+          throw enhancedError;
+        }
+
+        throw createProviderError(
+          response.status,
+          errorBody,
+          response.statusText,
+        );
+      }
+
+      // Step 6: Handle streaming response path
+      if (stream) {
+        logger.log("Handling streaming response");
+        return createStreamGenerator(response.body);
+      }
+
+      // Step 7: Handle non-streaming response parsing
+      logger.log("Parsing JSON response...");
+      const data = await response.json();
+      logger.log("JSON parsed successfully", {
+        hasChoices: !!data.choices,
+        choicesCount: data.choices?.length,
+      });
+      const rawContent = data.choices[0].message.content;
+
+      const content = stripMarkdownFences(rawContent);
+
+      if (isJsonMode) {
+        const parsed = tryParseJSON(content);
+        if (!parsed) {
+          throw new ProviderJsonParseError(
+            "Moonshot",
+            model,
+            content.substring(0, 200),
+            "Failed to parse JSON response from Moonshot API",
+          );
+        }
+        return {
+          content: parsed,
+          usage: data.usage,
+          raw: data,
+        };
+      }
+
+      return {
+        content,
+        usage: data.usage,
+        raw: data,
+      };
+    } catch (error) {
+      lastError = error;
+      logger.warn("Attempt failed", {
+        attempt,
+        errorMessage: error.message || error,
+        errorStatus: error.status,
+      });
+
+      if (error.status === 401) throw error;
+
+      if (isRetryableError(error) && attempt < maxRetries) {
+        continue;
+      }
+
+      if (attempt === maxRetries) throw error;
+    }
+  }
+
+  throw lastError || new Error(`Failed after ${maxRetries + 1} attempts`);
+}
+
+/**
+ * Create async generator for streaming Moonshot responses.
+ * Moonshot uses Server-Sent Events format with "data:" prefix.
+ */
+async function* createStreamGenerator(stream) {
+  const decoder = new TextDecoder();
+  const reader = stream.getReader();
+  let buffer = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop(); // Keep incomplete line
+
+      for (const line of lines) {
+        if (line.startsWith("data: ")) {
+          const data = line.slice(6);
+          if (data === "[DONE]") continue;
+
+          try {
+            const parsed = JSON.parse(data);
+            const content = parsed.choices?.[0]?.delta?.content;
+            // Skip only truly empty chunks; preserve whitespace-only content
+            if (content !== undefined && content !== null && content !== "") {
+              yield { content };
+            }
+          } catch (e) {
+            // Skip malformed JSON
+            logger.warn("Failed to parse stream chunk:", e);
+          }
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}