@itz4blitz/agentful 0.3.0 → 0.5.1

package/lib/core/output-parser.example.js

@@ -0,0 +1,250 @@
+/**
+ * Output Parser Usage Examples
+ *
+ * Demonstrates how to use the OutputParser to extract structured data
+ * from agent responses.
+ */
+
+import {
+  OutputParser,
+  parseAgentOutput,
+  extractJSON,
+  extractDecisions,
+  extractProgress,
+  extractQuestions
+} from './output-parser.js';
+
+// Example 1: Parsing structured JSON output
+const jsonOutput = `
+I've analyzed the codebase and found the following:
+
+\`\`\`json
+{
+  "files": 42,
+  "lines": 3500,
+  "coverage": 85.2,
+  "issues": [
+    {"type": "warning", "file": "index.js", "line": 10}
+  ]
+}
+\`\`\`
+
+This shows good code quality overall.
+`;
+
+const result1 = parseAgentOutput(jsonOutput);
+console.log('Type:', result1.type); // 'structured'
+console.log('Data:', result1.data); // { files: 42, lines: 3500, ... }
+
+// Example 2: Extracting decisions
+const decisionOutput = `
+I need your input on the authentication approach:
+
+DECISION: Should we use JWT or sessions for authentication?
+OPTIONS:
+- JWT (stateless, scalable, better for microservices)
+- Sessions (simpler, better for monoliths, easier to revoke)
+
+This decision affects the architecture significantly.
+`;
+
+const result2 = parseAgentOutput(decisionOutput);
+console.log('Type:', result2.type); // 'decisions'
+console.log('Decisions:', result2.decisions);
+// [{
+//   question: "Should we use JWT or sessions for authentication?",
+//   options: [
+//     { value: "JWT", description: "stateless, scalable, better for microservices" },
+//     { value: "Sessions", description: "simpler, better for monoliths, easier to revoke" }
+//   ],
+//   context: "..."
+// }]
+
+// Example 3: Tracking progress
+const progressOutput = `
+Running validation checks...
+
+[PROGRESS: 75%]
+
+Progress: 6/8 tests passing
+
+Still working on the integration tests.
+`;
+
+const result3 = parseAgentOutput(progressOutput);
+console.log('Type:', result3.type); // 'progress'
+console.log('Progress:', result3.progress);
+// {
+//   percentage: 75,
+//   format: 'percentage',
+//   raw: '[PROGRESS: 75%]'
+// }
+
+// Example 4: Detecting questions
+const questionOutput = `
+I'm implementing the user service.
+
+QUESTION: What should be the password minimum length?
+
+Should we enforce special characters in passwords?
+
+I'll continue with the default settings for now.
+`;
+
+const result4 = parseAgentOutput(questionOutput);
+console.log('Type:', result4.type); // 'question'
+console.log('Questions:', result4.questions);
+// [
+//   {
+//     question: "What should be the password minimum length?",
+//     type: "explicit",
+//     line: 3,
+//     context: [...]
+//   },
+//   {
+//     question: "Should we enforce special characters in passwords?",
+//     type: "inferred",
+//     line: 5,
+//     context: [...]
+//   }
+// ]
+
+// Example 5: Plain text fallback
+const plainOutput = `
+I've completed the implementation. All tests are passing.
+`;
+
+const result5 = parseAgentOutput(plainOutput);
+console.log('Type:', result5.type); // 'text'
+console.log('Data:', result5.data); // "I've completed the implementation..."
+
+// Example 6: Using specific extraction functions
+const mixedOutput = `
+Here's the analysis:
+
+\`\`\`json
+{"status": "complete", "score": 95}
+\`\`\`
+
+DECISION: Deploy to production now?
+OPTIONS:
+- Yes (code is ready)
+- No (wait for QA)
+
+Progress: 4/5 features complete
+
+What's the deployment schedule?
+`;
+
+// Extract only JSON
+const jsonOnly = extractJSON(mixedOutput);
+console.log('Found JSON:', jsonOnly.found); // true
+console.log('Data:', jsonOnly.data); // { status: "complete", score: 95 }
+
+// Extract only decisions
+const decisionsOnly = extractDecisions(mixedOutput);
+console.log('Decisions:', decisionsOnly.length); // 1
+
+// Extract only progress
+const progressOnly = extractProgress(mixedOutput);
+console.log('Progress:', progressOnly.percentage); // 80
+
+// Extract only questions
+const questionsOnly = extractQuestions(mixedOutput);
+console.log('Questions:', questionsOnly.length); // 1
+
+// Example 7: Using the parser class directly
+const parser = new OutputParser();
+
+const agentResponse = `
+Implementation complete. Here's the summary:
+
+\`\`\`json
+{
+  "endpoint": "/api/users",
+  "method": "POST",
+  "validation": "zod",
+  "authentication": "JWT"
+}
+\`\`\`
+`;
+
+const parsed = parser.parse(agentResponse);
+if (parsed.type === 'structured') {
+  console.log('Extracted structured data:', parsed.data);
+  console.log('Endpoint:', parsed.data.endpoint); // "/api/users"
+  console.log('Method:', parsed.data.method); // "POST"
+}
+
+// Example 8: Multiple JSON blocks
+const multiJsonOutput = `
+\`\`\`json
+{"config": "development"}
+\`\`\`
+
+And here's the production config:
+
+\`\`\`json
+{"config": "production", "debug": false}
+\`\`\`
+`;
+
+const multiResult = extractJSON(multiJsonOutput);
+console.log('All JSON blocks:', multiResult.all);
+// [
+//   { config: "development" },
+//   { config: "production", debug: false }
+// ]
+console.log('First block:', multiResult.data); // { config: "development" }
+
+// Example 9: Integration with agent orchestrator
+async function handleAgentResponse(agentOutput) {
+  const parsed = parseAgentOutput(agentOutput);
+
+  switch (parsed.type) {
+    case 'structured':
+      // Store structured data in state
+      await saveToState(parsed.data);
+      break;
+
+    case 'decisions':
+      // Add to decisions.json for user resolution
+      await addPendingDecisions(parsed.decisions);
+      break;
+
+    case 'progress':
+      // Update completion tracking
+      await updateProgress(parsed.progress.percentage);
+      break;
+
+    case 'question':
+      // Prompt user for input
+      await promptUser(parsed.questions);
+      break;
+
+    case 'text':
+      // Log informational output
+      console.log('Agent:', parsed.data);
+      break;
+  }
+}
+
+// Example 10: Error handling
+try {
+  const invalidOutput = null;
+  const result = parseAgentOutput(invalidOutput);
+  console.log('Type:', result.type); // 'text'
+  console.log('Data:', result.data); // null
+} catch (error) {
+  console.error('Parser error:', error);
+}
+
+// Example 11: Complex progress patterns
+const complexProgress = `
+Testing progress: 3 of 5 features complete
+Coverage increased to 82%
+15% of integration tests still failing
+`;
+
+const prog1 = extractProgress(complexProgress);
+console.log('Progress:', prog1.percentage); // 60 (from "3 of 5")

package/lib/core/output-parser.js

@@ -0,0 +1,458 @@
+/**
+ * Output Parser - Structured data extraction from agent responses
+ *
+ * Parses raw agent output to extract:
+ * - JSON blocks (structured data)
+ * - Decision points (requiring user input)
+ * - Progress markers (completion tracking)
+ * - Questions (blocking queries)
+ * - Plain text (fallback)
+ *
+ * @module lib/core/output-parser
+ */
+
+/**
+ * Main output parser class
+ */
+export class OutputParser {
+  /**
+   * Parse agent output and return structured result
+   *
+   * @param {string} rawOutput - Raw agent response text
+   * @returns {ParsedOutput} Parsed output with type and extracted data
+   */
+  parse(rawOutput) {
+    if (!rawOutput || typeof rawOutput !== 'string') {
+      return {
+        type: 'text',
+        data: null,
+        raw: rawOutput || ''
+      };
+    }
+
+    // Try parsing in order of specificity
+    const jsonResult = this.extractJSON(rawOutput);
+    if (jsonResult.found) {
+      return {
+        type: 'structured',
+        data: jsonResult.data,
+        raw: rawOutput,
+        jsonBlocks: jsonResult.all
+      };
+    }
+
+    const decisions = this.extractDecisions(rawOutput);
+    if (decisions.length > 0) {
+      return {
+        type: 'decisions',
+        decisions,
+        raw: rawOutput
+      };
+    }
+
+    const progress = this.extractProgress(rawOutput);
+    if (progress) {
+      return {
+        type: 'progress',
+        progress,
+        raw: rawOutput
+      };
+    }
+
+    const questions = this.extractQuestions(rawOutput);
+    if (questions.length > 0) {
+      return {
+        type: 'question',
+        questions,
+        raw: rawOutput
+      };
+    }
+
+    return {
+      type: 'text',
+      data: rawOutput.trim(),
+      raw: rawOutput
+    };
+  }
+
+  /**
+   * Extract JSON from markdown code blocks or inline JSON
+   *
+   * @param {string} text - Text containing potential JSON
+   * @returns {Object} { found: boolean, data: object|null, all: array }
+   */
+  extractJSON(text) {
+    const result = {
+      found: false,
+      data: null,
+      all: []
+    };
+
+    // Pattern 1: Markdown JSON code blocks
+    const codeBlockPattern = /```(?:json)?\s*\n([\s\S]*?)\n```/g;
+    let match;
+
+    while ((match = codeBlockPattern.exec(text)) !== null) {
+      try {
+        const parsed = JSON.parse(match[1].trim());
+        result.all.push(parsed);
+        if (!result.found) {
+          result.data = parsed;
+          result.found = true;
+        }
+      } catch (e) {
+        // Not valid JSON, skip
+      }
+    }
+
+    // Pattern 2: Inline JSON objects (if no code blocks found)
+    if (!result.found) {
+      const inlinePattern = /(\{[\s\S]*?\})/g;
+
+      while ((match = inlinePattern.exec(text)) !== null) {
+        try {
+          const parsed = JSON.parse(match[1]);
+          // Verify it's a real object (not just {})
+          if (Object.keys(parsed).length > 0) {
+            result.all.push(parsed);
+            if (!result.found) {
+              result.data = parsed;
+              result.found = true;
+            }
+          }
+        } catch (e) {
+          // Not valid JSON, skip
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Extract decision points from agent output
+   *
+   * Format:
+   * DECISION: Question text?
+   * OPTIONS:
+   * - Option A (description)
+   * - Option B (description)
+   *
+   * @param {string} text - Text containing decisions
+   * @returns {Array<Decision>} Array of decision objects
+   */
+  extractDecisions(text) {
+    const decisions = [];
+
+    // Pattern: DECISION: ... OPTIONS: ...
+    const decisionPattern = /DECISION:\s*([^\n]+)\s*(?:OPTIONS?:)?\s*((?:[-*]\s*[^\n]+\n?)*)/gi;
+    let match;
+
+    while ((match = decisionPattern.exec(text)) !== null) {
+      const question = match[1].trim();
+      const optionsText = match[2].trim();
+
+      // Parse options
+      const options = [];
+      const optionPattern = /[-*]\s*([^\n(]+)(?:\(([^)]+)\))?/g;
+      let optionMatch;
+
+      while ((optionMatch = optionPattern.exec(optionsText)) !== null) {
+        options.push({
+          value: optionMatch[1].trim(),
+          description: optionMatch[2]?.trim() || null
+        });
+      }
+
+      decisions.push({
+        question,
+        options: options.length > 0 ? options : null,
+        context: this._extractContext(text, match.index)
+      });
+    }
+
+    // Alternative pattern: Simple "DECIDE: " marker
+    const simplePattern = /DECIDE:\s*([^\n]+)/gi;
+
+    while ((match = simplePattern.exec(text)) !== null) {
+      const question = match[1].trim();
+
+      // Don't duplicate if already found
+      if (!decisions.some(d => d.question === question)) {
+        decisions.push({
+          question,
+          options: null,
+          context: this._extractContext(text, match.index)
+        });
+      }
+    }
+
+    return decisions;
+  }
+
+  /**
+   * Extract progress indicators from text
+   *
+   * Patterns:
+   * - [PROGRESS: 50%]
+   * - Progress: 7/10 tests passing
+   * - 3 of 5 features complete
+   *
+   * @param {string} text - Text containing progress markers
+   * @returns {Progress|null} Progress object or null
+   */
+  extractProgress(text) {
+    // Pattern 1: [PROGRESS: 50%]
+    const bracketPattern = /\[PROGRESS:\s*(\d+)%\]/i;
+    let match = bracketPattern.exec(text);
+
+    if (match) {
+      return {
+        percentage: parseInt(match[1], 10),
+        format: 'percentage',
+        raw: match[0]
+      };
+    }
+
+    // Pattern 2: Progress: 7/10 tests passing
+    const ratioPattern = /Progress:\s*(\d+)\s*\/\s*(\d+)\s*([^\n]*)/i;
+    match = ratioPattern.exec(text);
+
+    if (match) {
+      const current = parseInt(match[1], 10);
+      const total = parseInt(match[2], 10);
+      return {
+        current,
+        total,
+        percentage: total > 0 ? Math.round((current / total) * 100) : 0,
+        format: 'ratio',
+        description: match[3].trim() || null,
+        raw: match[0]
+      };
+    }
+
+    // Pattern 3: 3 of 5 features complete
+    const ofPattern = /(\d+)\s+of\s+(\d+)\s+([^\n]*?)\s+(?:complete|done|finished|passing)/i;
+    match = ofPattern.exec(text);
+
+    if (match) {
+      const current = parseInt(match[1], 10);
+      const total = parseInt(match[2], 10);
+      return {
+        current,
+        total,
+        percentage: total > 0 ? Math.round((current / total) * 100) : 0,
+        format: 'of',
+        description: match[3].trim() || null,
+        raw: match[0]
+      };
+    }
+
+    // Pattern 4: Simple percentage
+    const percentPattern = /(\d+)%\s+(?:complete|done|finished)/i;
+    match = percentPattern.exec(text);
+
+    if (match) {
+      return {
+        percentage: parseInt(match[1], 10),
+        format: 'percentage',
+        raw: match[0]
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * Extract questions requiring user input
+   *
+   * Patterns:
+   * - Lines ending with "?"
+   * - "QUESTION: " prefix
+   * - "Need input: " prefix
+   *
+   * @param {string} text - Text containing questions
+   * @returns {Array<Question>} Array of question objects
+   */
+  extractQuestions(text) {
+    const questions = [];
+    const lines = text.split('\n');
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+
+      // Skip empty lines and code blocks
+      if (!line || line.startsWith('```')) continue;
+
+      // Pattern 1: Explicit QUESTION: marker
+      let match = /^QUESTION:\s*(.+)$/i.exec(line);
+      if (match) {
+        questions.push({
+          question: match[1].trim(),
+          type: 'explicit',
+          line: i + 1,
+          context: this._getLineContext(lines, i)
+        });
+        continue;
+      }
+
+      // Pattern 2: "Need input:" prefix
+      match = /^(?:Need input|Needs? input|Input needed):\s*(.+)$/i.exec(line);
+      if (match) {
+        questions.push({
+          question: match[1].trim(),
+          type: 'input_request',
+          line: i + 1,
+          context: this._getLineContext(lines, i)
+        });
+        continue;
+      }
+
+      // Pattern 3: Questions ending with "?"
+      // Only consider substantial questions (>10 chars, starts with question word or context)
+      if (line.endsWith('?') && line.length > 10) {
+        const questionWords = /^(what|where|when|why|how|which|who|should|can|could|would|will|is|are|do|does)/i;
+        if (questionWords.test(line)) {
+          questions.push({
+            question: line,
+            type: 'inferred',
+            line: i + 1,
+            context: this._getLineContext(lines, i)
+          });
+        }
+      }
+    }
+
+    return questions;
+  }
+
+  /**
+   * Extract surrounding context for a match
+   *
+   * @private
+   * @param {string} text - Full text
+   * @param {number} index - Match index
+   * @param {number} radius - Characters before/after to include
+   * @returns {string} Context snippet
+   */
+  _extractContext(text, index, radius = 100) {
+    const start = Math.max(0, index - radius);
+    const end = Math.min(text.length, index + radius);
+
+    let context = text.substring(start, end).trim();
+
+    // Add ellipsis if truncated
+    if (start > 0) context = '...' + context;
+    if (end < text.length) context = context + '...';
+
+    return context;
+  }
+
+  /**
+   * Get context lines around a specific line
+   *
+   * @private
+   * @param {Array<string>} lines - All lines
+   * @param {number} lineIndex - Target line index
+   * @param {number} radius - Lines before/after to include
+   * @returns {Array<string>} Context lines
+   */
+  _getLineContext(lines, lineIndex, radius = 2) {
+    const start = Math.max(0, lineIndex - radius);
+    const end = Math.min(lines.length, lineIndex + radius + 1);
+    return lines.slice(start, end);
+  }
+}
+
+/**
+ * Convenience function for parsing agent output
+ *
+ * @param {string} rawOutput - Raw agent response
+ * @returns {ParsedOutput} Parsed output
+ */
+export function parseAgentOutput(rawOutput) {
+  const parser = new OutputParser();
+  return parser.parse(rawOutput);
+}
+
+/**
+ * Extract only JSON from agent output
+ *
+ * @param {string} text - Text containing JSON
+ * @returns {Object} { found: boolean, data: object|null, all: array }
+ */
+export function extractJSON(text) {
+  const parser = new OutputParser();
+  return parser.extractJSON(text);
+}
+
+/**
+ * Extract only decisions from agent output
+ *
+ * @param {string} text - Text containing decisions
+ * @returns {Array<Decision>} Array of decisions
+ */
+export function extractDecisions(text) {
+  const parser = new OutputParser();
+  return parser.extractDecisions(text);
+}
+
+/**
+ * Extract only progress from agent output
+ *
+ * @param {string} text - Text containing progress markers
+ * @returns {Progress|null} Progress object or null
+ */
+export function extractProgress(text) {
+  const parser = new OutputParser();
+  return parser.extractProgress(text);
+}
+
+/**
+ * Extract only questions from agent output
+ *
+ * @param {string} text - Text containing questions
+ * @returns {Array<Question>} Array of questions
+ */
+export function extractQuestions(text) {
+  const parser = new OutputParser();
+  return parser.extractQuestions(text);
+}
+
+/**
+ * @typedef {Object} ParsedOutput
+ * @property {'structured'|'decisions'|'progress'|'question'|'text'} type - Output type
+ * @property {*} data - Extracted data (type-specific)
+ * @property {string} raw - Original raw output
+ */
+
+/**
+ * @typedef {Object} Decision
+ * @property {string} question - Decision question
+ * @property {Array<Option>|null} options - Available options (if provided)
+ * @property {string} context - Surrounding text context
+ */
+
+/**
+ * @typedef {Object} Option
+ * @property {string} value - Option value
+ * @property {string|null} description - Option description
+ */
+
+/**
+ * @typedef {Object} Progress
+ * @property {number} percentage - Progress as percentage (0-100)
+ * @property {'percentage'|'ratio'|'of'} format - Format type
+ * @property {number} [current] - Current count (for ratio/of formats)
+ * @property {number} [total] - Total count (for ratio/of formats)
+ * @property {string|null} [description] - Progress description
+ * @property {string} raw - Raw progress marker
+ */
+
+/**
+ * @typedef {Object} Question
+ * @property {string} question - Question text
+ * @property {'explicit'|'input_request'|'inferred'} type - Question detection type
+ * @property {number} line - Line number in output
+ * @property {Array<string>} context - Surrounding lines for context
+ */