@ryanfw/prompt-orchestration-pipeline 0.0.1 → 0.3.0

package/src/core/validation.js

@@ -8,7 +8,7 @@ function getSeedSchema() {
   const config = getConfig();
   return {
     type: "object",
-    required: ["name", "data"],
+    required: ["name", "data", "pipeline"],
     properties: {
       name: {
         type: "string",
@@ -21,6 +21,11 @@ function getSeedSchema() {
         type: "object",
         description: "Job data payload",
       },
+      pipeline: {
+        type: "string",
+        enum: Object.keys(config.pipelines),
+        description: "Pipeline slug from registry",
+      },
       metadata: {
         type: "object",
         description: "Optional metadata",
@@ -98,3 +103,117 @@ export function validateSeedOrThrow(seed) {
     throw new Error(formatValidationErrors(result.errors));
   }
 }
+
+/**
+ * Validate pipeline config object shape (canonical)
+ * Expected shape:
+ * {
+ *   name: string,
+ *   tasks: string[],
+ *   taskConfig?: { [taskName: string]: object }
+ * }
+ *
+ * @param {object} pipeline - pipeline object to validate
+ * @returns {{ valid: boolean, errors?: array }}
+ */
+export function validatePipeline(pipeline) {
+  if (!pipeline || typeof pipeline !== "object") {
+    return {
+      valid: false,
+      errors: [
+        {
+          message: "Pipeline must be a valid JSON object",
+          path: "",
+        },
+      ],
+    };
+  }
+
+  const pipelineSchema = {
+    type: "object",
+    required: ["name", "tasks"],
+    properties: {
+      name: { type: "string" },
+      tasks: {
+        type: "array",
+        items: { type: "string" },
+        minItems: 1,
+      },
+      taskConfig: {
+        type: "object",
+        additionalProperties: { type: "object" },
+      },
+    },
+    additionalProperties: true,
+  };
+
+  const validatePipelineSchema = ajv.compile(pipelineSchema);
+  const valid = validatePipelineSchema(pipeline);
+
+  if (!valid) {
+    return {
+      valid: false,
+      errors: validatePipelineSchema.errors.map((err) => ({
+        message: err.message,
+        path: err.instancePath || err.dataPath || "",
+        params: err.params,
+        keyword: err.keyword,
+      })),
+    };
+  }
+
+  // Additional check: ensure every task listed has either an entry in taskConfig or empty object is acceptable.
+  if (Array.isArray(pipeline.tasks)) {
+    for (const t of pipeline.tasks) {
+      if (typeof t !== "string") {
+        return {
+          valid: false,
+          errors: [
+            {
+              message: "Every task entry must be a string task name",
+              path: "tasks",
+            },
+          ],
+        };
+      }
+    }
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Formats pipeline validation errors into a human-readable message
+ * @param {array} errors
+ * @returns {string}
+ */
+export function formatPipelineValidationErrors(errors) {
+  if (!errors || errors.length === 0) {
+    return "Unknown pipeline validation error";
+  }
+
+  const messages = errors.map((err) => {
+    const path = err.path ? `at '${err.path}'` : "";
+    return `  - ${err.message} ${path}`.trim();
+  });
+
+  return `Pipeline validation failed:\n${messages.join("\n")}`;
+}
+
+/**
+ * Validate pipeline object or throw an Error with friendly message.
+ * Accepts either a pipeline object or the path string to the pipeline file,
+ * in which case the caller should read and parse the file before calling.
+ *
+ * @param {object} pipeline - pipeline object to validate
+ * @param {string} [pathHint] - optional path for error messages
+ * @throws {Error} If validation fails
+ */
+export function validatePipelineOrThrow(pipeline, pathHint = "pipeline.json") {
+  const result = validatePipeline(pipeline);
+  if (!result.valid) {
+    const header = `Invalid pipeline definition (${pathHint}):`;
+    const body = formatPipelineValidationErrors(result.errors);
+    throw new Error(`${header}\n${body}`);
+  }
+}

package/src/lib/utils.js

@@ -0,0 +1,6 @@
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}

package/src/llm/README.md

@@ -27,17 +27,145 @@ src/
     └── anthropic.js      ← Anthropic implementation
 ```
 
-## Core Functions
+## Provider-Grouped Functions (Primary API)
 
-### `chat(options)`
+The LLM layer exposes provider-grouped functions that map to named models in the configuration registry. This is the recommended approach for task development.
+
+### `createLLM(options)`
+
+Factory function that creates an interface with only provider-grouped functions.
+
+```javascript
+import { createLLM } from "../llm/index.js";
+
+const llm = createLLM();
+
+// Provider-grouped functions available:
+await llm.openai.gpt4({ messages: [{ role: "user", content: "Hello!" }] });
+await llm.openai.gpt4Turbo({ messages: [{ role: "user", content: "Hello!" }] });
+await llm.openai.gpt5({ messages: [{ role: "user", content: "Hello!" }] });
+
+await llm.deepseek.reasoner({
+  messages: [{ role: "user", content: "Hello!" }],
+});
+await llm.deepseek.chat({ messages: [{ role: "user", content: "Hello!" }] });
+
+await llm.anthropic.opus({ messages: [{ role: "user", content: "Hello!" }] });
+await llm.anthropic.sonnet({ messages: [{ role: "user", content: "Hello!" }] });
+```
+
+### Task Context Usage
+
+In task modules, `context.llm` provides only provider-grouped functions:
+
+```javascript
+// In a task module:
+export default async function analysis(context) {
+  const response = await context.llm.openai.gpt4({
+    messages: [{ role: "user", content: "Analyze this data" }],
+    temperature: 0.7,
+  });
+
+  return { analysis: response.content };
+}
+```
+
+### Provider and Model Overrides
+
+You can override the default provider and model:
+
+```javascript
+// Use OpenAI provider with custom model
+await llm.deepseek.reasoner({
+  messages: [{ role: "user", content: "Hello!" }],
+  provider: "openai", // Override provider
+  model: "gpt-4-custom", // Override model
+});
+
+// All other options are passed through
+await llm.openai.gpt4({
+  messages: [{ role: "user", content: "Hello!" }],
+  temperature: 0.5,
+  maxTokens: 1000,
+  metadata: { taskId: "task-123" },
+});
+```
+
+### Event Metadata
+
+Provider-grouped functions automatically include alias metadata in events:
+
+```javascript
+import { getLLMEvents } from "../llm/index.js";
+
+const events = getLLMEvents();
+events.on("llm:request:complete", (data) => {
+  console.log(data.metadata.alias); // "openai:gpt-4"
+});
+```
+
+### Model Registry
+
+The provider-grouped functions are generated from the model registry in your configuration. The default registry includes:
+
+```json
+{
+  "llm": {
+    "models": {
+      "openai:gpt-4": { "provider": "openai", "model": "gpt-4" },
+      "openai:gpt-4-turbo": { "provider": "openai", "model": "gpt-4-turbo" },
+      "openai:gpt-5": { "provider": "openai", "model": "gpt-5-chat-latest" },
+      "deepseek:reasoner": {
+        "provider": "deepseek",
+        "model": "deepseek-reasoner"
+      },
+      "deepseek:chat": { "provider": "deepseek", "model": "deepseek-chat" },
+      "anthropic:opus": { "provider": "anthropic", "model": "claude-3-opus" },
+      "anthropic:sonnet": {
+        "provider": "anthropic",
+        "model": "claude-3-sonnet"
+      }
+    }
+  }
+}
+```
+
+**Function Naming:**
+
+- Registry aliases are converted to camelCase function names
+- `openai:gpt-4-turbo` → `gpt4Turbo()`
+- `deepseek:reasoner` → `reasoner()`
+
+**Custom Registry:**
+You can customize the registry in your `config.json`:
+
+```json
+{
+  "llm": {
+    "models": {
+      "openai:custom": { "provider": "openai", "model": "gpt-4-custom" },
+      "deepseek:fast": { "provider": "deepseek", "model": "deepseek-chat" }
+    }
+  }
+}
+```
 
-Main function for LLM interactions. Supports multiple providers and models.
+This will generate:
+
+- `llm.openai.custom()`
+- `llm.deepseek.fast()`
+
+## Legacy Functions (Deprecated)
+
+The following functions are still available but deprecated in favor of provider-grouped functions:
+
+### `chat(options)`
 
 ```javascript
 import { chat } from "../llm/index.js";
 
 const response = await chat({
-  provider: "openai", // or "deepseek", "anthropic"
+  provider: "openai",
   model: "gpt-5-chat-latest",
   messages: [
     { role: "system", content: "You are a helpful assistant" },
@@ -45,18 +173,14 @@ const response = await chat({
   ],
   temperature: 0.7,
   maxTokens: 1000,
-  metadata: { taskId: "task-123" }, // Optional tracking data
+  metadata: { taskId: "task-123" },
 });
-
-console.log(response.content); // AI response text
-console.log(response.usage); // Token usage stats
 ```
 
-### `complete(prompt, options)`
-
-Convenience function for simple single-turn completions.
+### `complete(prompt, options)` (Deprecated)
 
 ```javascript
+// DEPRECATED: Use provider-grouped functions instead
 import { complete } from "../llm/index.js";
 
 const response = await complete("What is 2+2?", {
@@ -64,28 +188,13 @@ const response = await complete("What is 2+2?", {
   model: "gpt-5-chat-latest",
 });
 
-console.log(response.content); // "4"
-```
-
-### `createLLM(options)`
-
-Factory function to create a bound LLM interface with default settings.
-
-```javascript
+// RECOMMENDED: Use provider-grouped function
 import { createLLM } from "../llm/index.js";
 
-const llm = createLLM({
-  defaultProvider: "openai",
-  defaultModel: "gpt-5-chat-latest",
+const llm = createLLM();
+const response = await llm.openai.gpt5({
+  messages: [{ role: "user", content: "What is 2+2?" }],
 });
-
-// Use the bound interface
-const response = await llm.chat({
-  messages: [{ role: "user", content: "Hello!" }],
-});
-
-// Or use convenience methods
-const result = await llm.complete("What is AI?");
 ```
 
 ### `createChain()`