yaml-flow 7.1.0 → 8.0.1

package/examples/npm-libs/inference/pluggable-adapters.ts

@@ -1,254 +0,0 @@
-/**
- * Inference Example: Pluggable LLM Adapters
- *
- * Shows how to create adapters for different LLM providers.
- * Each adapter implements InferenceAdapter.analyze(prompt) → string.
- *
- * Run with: npx tsx examples/npm-libs/inference/pluggable-adapters.ts
- */
-
-import {
-  createLiveGraph,
-  schedule,
-} from '../../src/continuous-event-graph/index.js';
-import {
-  inferCompletions,
-  applyInferences,
-  buildInferencePrompt,
-  createCliAdapter,
-  createHttpAdapter,
-} from '../../src/inference/index.js';
-import type { InferenceAdapter } from '../../src/inference/index.js';
-import type { GraphConfig } from '../../src/continuous-event-graph/types.js';
-
-// ============================================================================
-// 1. Adapter Examples (uncomment the one for your LLM provider)
-// ============================================================================
-
-/**
- * OpenAI Adapter
- * npm install openai
- */
-function createOpenAIAdapter(apiKey: string, model = 'gpt-4o'): InferenceAdapter {
-  return {
-    analyze: async (prompt: string) => {
-      // import OpenAI from 'openai';
-      // const client = new OpenAI({ apiKey });
-      // const response = await client.chat.completions.create({
-      //   model,
-      //   messages: [{ role: 'user', content: prompt }],
-      //   temperature: 0.1,  // low temperature for deterministic analysis
-      // });
-      // return response.choices[0].message.content ?? '[]';
-
-      // Mock for demo
-      return '[]';
-    },
-  };
-}
-
-/**
- * Azure OpenAI Adapter
- * npm install openai
- */
-function createAzureOpenAIAdapter(
-  endpoint: string,
-  apiKey: string,
-  deployment: string,
-): InferenceAdapter {
-  return {
-    analyze: async (prompt: string) => {
-      // import OpenAI from 'openai';
-      // const client = new OpenAI({
-      //   apiKey,
-      //   baseURL: `${endpoint}/openai/deployments/${deployment}`,
-      //   defaultQuery: { 'api-version': '2024-02-15-preview' },
-      //   defaultHeaders: { 'api-key': apiKey },
-      // });
-      // const response = await client.chat.completions.create({
-      //   model: deployment,
-      //   messages: [{ role: 'user', content: prompt }],
-      //   temperature: 0.1,
-      // });
-      // return response.choices[0].message.content ?? '[]';
-
-      return '[]';
-    },
-  };
-}
-
-/**
- * Anthropic (Claude) Adapter
- * npm install @anthropic-ai/sdk
- */
-function createAnthropicAdapter(apiKey: string, model = 'claude-sonnet-4-20250514'): InferenceAdapter {
-  return {
-    analyze: async (prompt: string) => {
-      // import Anthropic from '@anthropic-ai/sdk';
-      // const client = new Anthropic({ apiKey });
-      // const response = await client.messages.create({
-      //   model,
-      //   max_tokens: 1024,
-      //   messages: [{ role: 'user', content: prompt }],
-      // });
-      // return response.content[0].type === 'text' ? response.content[0].text : '[]';
-
-      return '[]';
-    },
-  };
-}
-
-/**
- * Local/Custom Adapter — call any HTTP endpoint
- */
-function createCustomAdapter(url: string, headers: Record<string, string> = {}): InferenceAdapter {
-  return {
-    analyze: async (prompt: string) => {
-      const response = await fetch(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', ...headers },
-        body: JSON.stringify({ prompt }),
-      });
-      const data = await response.json() as { response?: string };
-      return data.response ?? '[]';
-    },
-  };
-}
-
-// ============================================================================
-// 1b. Built-in Adapter Factories (no boilerplate needed)
-// ============================================================================
-
-/**
- * Ollama via CLI — runs models locally
- * Install: https://ollama.com
- */
-const ollamaCliAdapter = createCliAdapter({
-  command: 'ollama',
-  args: (prompt) => ['run', 'llama3', prompt],
-});
-
-/**
- * Ollama via HTTP — same model, HTTP interface
- * Start with: ollama serve
- */
-const ollamaHttpAdapter = createHttpAdapter({
-  url: 'http://localhost:11434/api/generate',
-  buildBody: (prompt) => ({ model: 'llama3', prompt, stream: false }),
-  extractResponse: (json) => json.response as string,
-});
-
-/**
- * llm CLI — Simon Willison's LLM tool
- * Install: pip install llm
- */
-const llmCliAdapter = createCliAdapter({
-  command: 'llm',
-  args: () => ['--no-stream'],
-  stdin: true, // pipe prompt via stdin (better for long prompts)
-});
-
-/**
- * GitHub Copilot CLI — use gh copilot for inference
- * Install: gh extension install github/gh-copilot
- */
-const ghCopilotAdapter = createCliAdapter({
-  command: 'gh',
-  args: (prompt) => ['copilot', 'suggest', '-t', 'shell', prompt],
-  timeout: 30_000,
-});
-
-/**
- * Custom script adapter — run your own wrapper script
- * The script receives the prompt as argument (or stdin) and prints JSON to stdout
- */
-const customScriptAdapter = createCliAdapter({
-  command: 'python',
-  args: (prompt) => ['scripts/infer.py', '--json', prompt],
-  cwd: '/path/to/project',
-  env: { MODEL: 'gpt-4o', TEMPERATURE: '0.1' },
-  timeout: 60_000,
-});
-
-// ============================================================================
-// 2. Demo: Use the prompt builder standalone
-// ============================================================================
-
-const config: GraphConfig = {
-  settings: { completion: 'all-tasks' },
-  tasks: {
-    'code-reviewed': {
-      provides: ['review-done'],
-      description: 'Code review completed by team lead',
-      inference: {
-        criteria: 'PR approved with at least 2 approvals and no open comments',
-        keywords: ['pull-request', 'code-review', 'approval'],
-        suggestedChecks: ['check PR status for "approved"', 'verify no open comments'],
-        autoDetectable: true,
-      },
-    },
-    'tests-passed': {
-      requires: ['review-done'],
-      provides: ['tests-green'],
-      description: 'CI pipeline tests all passing',
-      inference: {
-        criteria: 'All CI checks green, code coverage above 80%',
-        keywords: ['ci', 'tests', 'coverage', 'pipeline'],
-        suggestedChecks: ['check CI status', 'verify coverage report'],
-        autoDetectable: true,
-      },
-    },
-    'deployed-staging': {
-      requires: ['tests-green'],
-      provides: ['staging-live'],
-      description: 'Deployed to staging environment',
-      inference: {
-        criteria: 'Staging URL returns HTTP 200 with correct version',
-        keywords: ['staging', 'deployment', 'version'],
-        autoDetectable: true,
-      },
-    },
-  },
-};
-
-async function main() {
-  const live = createLiveGraph(config);
-
-  // Just build the prompt — useful for debugging or using with your own LLM code
-  const prompt = buildInferencePrompt(live, {
-    context: 'PR #142: 3 approvals, 0 open comments. CI: all 47 tests pass, coverage 84%.',
-  });
-
-  console.log('=== Generated LLM Prompt ===');
-  console.log(prompt);
-  console.log('\n=== End Prompt ===');
-  console.log(`\nPrompt length: ${prompt.length} characters`);
-  console.log('This prompt can be sent to any LLM provider.');
-
-  // Demo: use a mock adapter to show the full flow
-  const mockAdapter: InferenceAdapter = {
-    analyze: async () => JSON.stringify([
-      { taskName: 'code-reviewed', confidence: 0.97, reasoning: '3 approvals, 0 open comments — PR is clearly approved.' },
-      { taskName: 'tests-passed', confidence: 0.92, reasoning: '47/47 tests pass, coverage 84% exceeds 80% threshold.' },
-    ]),
-  };
-
-  const result = await inferCompletions(live, mockAdapter, {
-    context: 'PR #142: 3 approvals, 0 open comments. CI: all 47 tests pass, coverage 84%.',
-  });
-
-  console.log('\n=== Inference Results ===');
-  for (const s of result.suggestions) {
-    console.log(`  ${s.taskName}: ${(s.confidence * 100).toFixed(0)}% — ${s.reasoning}`);
-  }
-
-  // Apply above threshold
-  const updated = applyInferences(live, result, 0.9);
-  console.log('\n=== After Applying (threshold 90%) ===');
-  for (const [name, state] of Object.entries(updated.state.tasks)) {
-    console.log(`  ${name}: ${state.status}`);
-  }
-  console.log('  Eligible:', schedule(updated).eligible);
-}
-
-main().catch(console.error);

package/examples/npm-libs/node/ai-conversation.ts

@@ -1,195 +0,0 @@
-/**
- * Node.js Example: AI Conversation with External API
- * 
- * Demonstrates a more complex flow with:
- * - Component injection (AI client)
- * - Retry logic
- * - Circuit breakers
- * - Event handling
- * 
- * Run with: npx ts-node examples/npm-libs/node/ai-conversation.ts
- */
-
-import { createEngine, loadFlow, MemoryStore } from '../../src/index.js';
-import type { StepInput, StepContext, StepResult } from '../../src/index.js';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Simulated AI client (replace with actual OpenAI/Anthropic client)
-const mockAIClient = {
-  async generateResponse(prompt: string, history: string[]): Promise<{ text: string; confidence: number }> {
-    // Simulate API latency
-    await new Promise(resolve => setTimeout(resolve, 100));
-    
-    // Simulate occasional low confidence
-    const confidence = Math.random() > 0.3 ? 0.85 : 0.4;
-    
-    return {
-      text: `AI Response to: "${prompt}" (simulated)`,
-      confidence,
-    };
-  },
-};
-
-// Define step handlers
-const handlers = {
-  async generate_response(input: StepInput, ctx: StepContext): Promise<StepResult> {
-    const userMessage = input.user_message as string;
-    const history = (input.conversation_history as string[]) || [];
-    
-    // Access injected AI client from components
-    const ai = ctx.components.aiClient as typeof mockAIClient;
-    
-    console.log(`[generate] Processing: "${userMessage}"`);
-    
-    try {
-      const response = await ai.generateResponse(userMessage, history);
-      
-      return {
-        result: 'success',
-        data: {
-          ai_response: response.text,
-          confidence_score: response.confidence,
-        },
-      };
-    } catch (error) {
-      console.log('[generate] API call failed, will retry...');
-      return { result: 'failure' };
-    }
-  },
-
-  async validate_response(input: StepInput, ctx: StepContext): Promise<StepResult> {
-    const response = input.ai_response as string;
-    const confidence = input.confidence_score as number;
-    
-    console.log(`[validate] Confidence: ${(confidence * 100).toFixed(1)}%`);
-    
-    // Check quality criteria
-    if (confidence >= 0.7 && response.length > 10) {
-      return {
-        result: 'valid',
-        data: {
-          validation_result: 'passed',
-          validation_feedback: null,
-        },
-      };
-    }
-    
-    return {
-      result: 'needs_refinement',
-      data: {
-        validation_result: 'needs_improvement',
-        validation_feedback: confidence < 0.7 
-          ? 'Low confidence - regenerate with more context'
-          : 'Response too short',
-      },
-    };
-  },
-
-  async refine_response(input: StepInput, ctx: StepContext): Promise<StepResult> {
-    const feedback = input.validation_feedback as string;
-    const userMessage = input.user_message as string;
-    
-    console.log(`[refine] Refining based on: ${feedback}`);
-    
-    const ai = ctx.components.aiClient as typeof mockAIClient;
-    
-    // Enhanced prompt with feedback
-    const enhancedPrompt = `${userMessage} (Note: ${feedback})`;
-    const response = await ai.generateResponse(enhancedPrompt, []);
-    
-    return {
-      result: 'success',
-      data: {
-        ai_response: response.text + ' [refined]',
-        confidence_score: Math.min(response.confidence + 0.2, 0.95), // Boost confidence
-      },
-    };
-  },
-
-  async check_approval(input: StepInput, ctx: StepContext): Promise<StepResult> {
-    const response = input.ai_response as string;
-    
-    console.log(`[approval] Response ready: "${response}"`);
-    
-    // Simulate user approval (in real app, this would wait for user input)
-    const userApproves = Math.random() > 0.3;
-    
-    if (userApproves) {
-      console.log('[approval] User approved!');
-      return {
-        result: 'approved',
-        data: {
-          user_approved: true,
-          user_feedback: null,
-        },
-      };
-    }
-    
-    console.log('[approval] User rejected, requesting changes');
-    return {
-      result: 'rejected',
-      data: {
-        user_approved: false,
-        user_feedback: 'Please make it more concise',
-      },
-    };
-  },
-
-  async incorporate_feedback(input: StepInput, ctx: StepContext): Promise<StepResult> {
-    const response = input.ai_response as string;
-    const feedback = input.user_feedback as string;
-    
-    console.log(`[feedback] Incorporating: "${feedback}"`);
-    
-    return {
-      result: 'success',
-      data: {
-        ai_response: response.replace(' [refined]', '') + ' [user-adjusted]',
-        confidence_score: 0.9,
-      },
-    };
-  },
-};
-
-async function main() {
-  // Load the AI conversation flow
-  const flowPath = join(__dirname, '../flows/ai-conversation.yaml');
-  const flow = await loadFlow(flowPath);
-  
-  console.log('=== AI Conversation Flow Demo ===\n');
-
-  // Create engine with AI client component
-  const engine = createEngine(flow, handlers, {
-    store: new MemoryStore(),
-    components: {
-      aiClient: mockAIClient,
-    },
-    onTransition: (from, to) => {
-      console.log(`  >> ${from} -> ${to}`);
-    },
-  });
-
-  // Subscribe to events
-  engine.on('step:error', (event) => {
-    console.log(`  !! Error in step: ${event.data.step}`);
-  });
-
-  // Run the flow
-  const result = await engine.run({
-    user_message: 'Explain quantum computing in simple terms',
-    conversation_history: [],
-  });
-
-  console.log('\n=== Flow Complete ===');
-  console.log('Status:', result.status);
-  console.log('Intent:', result.intent);
-  console.log('Final Response:', result.data.ai_response);
-  console.log('Steps taken:', result.stepHistory.length);
-  console.log('Duration:', result.durationMs, 'ms');
-}
-
-main().catch(console.error);

package/examples/npm-libs/node/simple-greeting.ts

@@ -1,101 +0,0 @@
-/**
- * Node.js Example: Simple Greeting Flow
- * 
- * Demonstrates basic usage with file-based persistence.
- * 
- * Run with: npx ts-node examples/npm-libs/node/simple-greeting.ts
- * Or after build: node examples/npm-libs/node/simple-greeting.js
- */
-
-import { createEngine, loadFlow, FileStore } from '../../src/index.js';
-import type { StepInput, StepContext, StepResult } from '../../src/index.js';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Define step handlers as pure functions
-const handlers = {
-  async greet(input: StepInput, ctx: StepContext): Promise<StepResult> {
-    const userName = (input.initial_name as string) || 'World';
-    
-    console.log(`[${ctx.stepName}] Generating greeting for: ${userName}`);
-    
-    return {
-      result: 'success',
-      data: {
-        greeting: 'Hello',
-        user_name: userName,
-      },
-    };
-  },
-
-  async validate(input: StepInput, ctx: StepContext): Promise<StepResult> {
-    const { greeting, user_name } = input;
-    
-    console.log(`[${ctx.stepName}] Validating: ${greeting} ${user_name}`);
-    
-    const isValid = typeof greeting === 'string' && 
-                    greeting.length > 0 && 
-                    typeof user_name === 'string';
-    
-    if (!isValid) {
-      return { result: 'invalid', data: { is_valid: false } };
-    }
-    
-    return {
-      result: 'success',
-      data: { is_valid: true },
-    };
-  },
-
-  async personalize(input: StepInput, ctx: StepContext): Promise<StepResult> {
-    const { greeting, user_name } = input;
-    
-    const finalMessage = `${greeting}, ${user_name}! Welcome to yaml-flow.`;
-    
-    console.log(`[${ctx.stepName}] Created message: ${finalMessage}`);
-    
-    return {
-      result: 'success',
-      data: { final_message: finalMessage },
-    };
-  },
-};
-
-async function main() {
-  // Load flow from YAML file
-  const flowPath = join(__dirname, '../flows/simple-greeting.yaml');
-  const flow = await loadFlow(flowPath);
-  
-  console.log('Loaded flow:', flow.id ?? 'simple-greeting');
-  console.log('Steps:', Object.keys(flow.steps).join(', '));
-  console.log('---');
-
-  // Create engine with file-based persistence
-  const engine = createEngine(flow, handlers, {
-    store: new FileStore({ directory: './flow-data' }),
-    onStep: (step, result) => {
-      console.log(`Step completed: ${step} -> ${result.result}`);
-    },
-    onTransition: (from, to) => {
-      console.log(`Transition: ${from} -> ${to}`);
-    },
-  });
-
-  // Run the flow
-  const result = await engine.run({
-    initial_name: 'Developer',
-  });
-
-  console.log('---');
-  console.log('Flow Result:');
-  console.log('  Status:', result.status);
-  console.log('  Intent:', result.intent);
-  console.log('  Data:', result.data);
-  console.log('  Steps:', result.stepHistory.join(' -> '));
-  console.log('  Duration:', result.durationMs, 'ms');
-}
-
-main().catch(console.error);

package/examples/step-machine-cli/portfolio-tracker/cards/holdings-table.json

@@ -1,22 +0,0 @@
-{
-  "id": "holdings-table",
-  "meta": { "title": "Holdings Table" },
-  "requires": ["holdings", "prices"],
-  "provides": [{ "bindTo": "table", "ref": "computed_values.table" }],
-  "card_data": {},
-  "compute": [
-    {
-      "bindTo": "table",
-      "expr": "{ \"rows\": $map(requires.holdings, function($h) { { \"symbol\": $h.symbol, \"qty\": $h.qty, \"price\": $lookup(requires.prices, $h.symbol), \"value\": $h.qty * $lookup(requires.prices, $h.symbol) } }) }"
-    }
-  ],
-  "view": {
-    "elements": [
-      {
-        "kind": "table",
-        "label": "Portfolio Positions",
-        "data": { "bind": "computed_values.table.rows", "columns": ["symbol", "qty", "price", "value"] }
-      }
-    ]
-  }
-}

package/examples/step-machine-cli/portfolio-tracker/cards/portfolio-form.json

@@ -1,43 +0,0 @@
-{
-  "id": "portfolio-form",
-  "meta": {
-    "title": "Portfolio Holdings Form"
-  },
-  "provides": [
-    {
-      "bindTo": "holdings",
-      "ref": "card_data.holdings"
-    }
-  ],
-  "card_data": {
-    "holdings": [
-      {
-        "symbol": "AAPL",
-        "qty": 50
-      },
-      {
-        "symbol": "MSFT",
-        "qty": 30
-      },
-      {
-        "symbol": "GOOG",
-        "qty": 100
-      }
-    ]
-  },
-  "view": {
-    "elements": [
-      {
-        "kind": "table",
-        "label": "Holdings",
-        "data": {
-          "bind": "card_data.holdings",
-          "columns": [
-            "symbol",
-            "qty"
-          ]
-        }
-      }
-    ]
-  }
-}

package/examples/step-machine-cli/portfolio-tracker/cards/portfolio-value.json

@@ -1,15 +0,0 @@
-{
-  "id": "portfolio-value",
-  "meta": { "title": "Portfolio Total Value" },
-  "requires": ["table"],
-  "provides": [{ "bindTo": "totalValue", "ref": "computed_values.totalValue" }],
-  "card_data": {},
-  "compute": [
-    { "bindTo": "totalValue", "expr": "$sum(requires.table.rows.value)" }
-  ],
-  "view": {
-    "elements": [
-      { "kind": "metric", "label": "Total Portfolio Value", "data": { "bind": "computed_values.totalValue" } }
-    ]
-  }
-}

package/examples/step-machine-cli/portfolio-tracker/cards/price-fetch.json

@@ -1,15 +0,0 @@
-{
-  "id": "price-fetch",
-  "meta": { "title": "Fetch Market Prices" },
-  "requires": ["holdings"],
-  "provides": [{ "bindTo": "prices", "ref": "fetched_sources.prices" }],
-  "card_data": {},
-  "source_defs": [
-    { "cli": "node ../fetch-prices.js --tmp-file-name tmp_file1", "bindTo": "prices", "outputFile": "prices.json" }
-  ],
-  "view": {
-    "elements": [
-      { "kind": "table", "label": "Market Prices", "data": { "bind": "fetched_sources.prices" } }
-    ]
-  }
-}

package/examples/step-machine-cli/portfolio-tracker/fetch-prices.js

@@ -1,48 +0,0 @@
-/**
- * fetch-prices.js
- * Polls for tmp_file1 payload and outputs JSON to stdout once available.
- */
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-
-function getArgValue(flagName) {
-  const idx = process.argv.indexOf(flagName);
-  if (idx < 0) return undefined;
-  return process.argv[idx + 1];
-}
-
-const envBoardDir = (process.env.BOARD_DIR ?? '').trim();
-const tmpFileName = String(getArgValue('--tmp-file-name') ?? process.env.TMP_FILE_NAME ?? 'tmp_file1').trim();
-const tmpFilePath = envBoardDir ? path.join(envBoardDir, tmpFileName) : '';
-
-if (!tmpFilePath) {
-  console.error('BOARD_DIR environment variable is required for fetch-prices.js');
-  process.exit(1);
-}
-
-function getReadableTmpFile() {
-  if (!fs.existsSync(tmpFilePath)) return undefined;
-  const content = fs.readFileSync(tmpFilePath, 'utf-8').trim();
-  if (!content) return undefined;
-  return { tmpFile: tmpFilePath, content };
-}
-
-function waitForFile(timeoutMs = 120000) {
-  const started = Date.now();
-  const interval = setInterval(() => {
-    if (Date.now() - started > timeoutMs) {
-      clearInterval(interval);
-      console.error('Timed out waiting for tmp_file1 market prices input.');
-      process.exit(1);
-    }
-
-    const ready = getReadableTmpFile();
-    if (!ready) return;
-
-    clearInterval(interval);
-    fs.writeFileSync(ready.tmpFile, '', 'utf-8');
-    process.stdout.write(`${ready.content}\n`);
-  }, 250);
-}
-
-waitForFile();