flex-md 3.5.0 → 4.0.0

package/docs/Recommended New Strategies for AI Request Builder.md

@@ -0,0 +1,691 @@
+# Recommended New Strategies for AI Request Builder
+
+Based on different task categories, here are strategic additions that would significantly improve the RequestBuilder's versatility:
+
+---
+
+## 1. **`checklist-driven`** Strategy
+**Best for:** Audit tasks, quality checks, compliance reviews, evaluation tasks
+
+### Concept
+Uses explicit checklists and criteria to guide LLM reasoning, ensuring comprehensive coverage and systematic evaluation.
+
+### Required Inputs (Tokens)
+```typescript
+{
+  checklistItems: string[];  // Array of specific things to check/verify
+  evaluationCriteria: {
+    criterion: string;
+    weight?: number;  // Optional scoring weight
+    requiredEvidence?: string;  // What evidence is needed
+  }[];
+  scoringRubric?: {
+    excellent: string;
+    good: string;
+    fair: string;
+    poor: string;
+  };
+  mustCheckAll: boolean;  // Whether all items must be addressed
+}
+```
+
+### System Message Structure
+```
+You are performing a systematic audit/evaluation task.
+
+EVALUATION CRITERIA:
+{evaluationCriteria formatted as numbered list}
+
+CHECKLIST (must verify each):
+{checklistItems formatted with checkboxes}
+
+SCORING RUBRIC:
+{scoringRubric if provided}
+
+PROCESS:
+1. Review each checklist item systematically
+2. Gather evidence for each criterion
+3. Score against the rubric
+4. Document findings with specific references
+
+{schema guidance}
+```
+
+### Output Schema Requirements
+Must include:
+- `checklistResults: { item: string; status: 'pass'|'fail'|'warning'; evidence: string }[]`
+- `criteriaScores: { criterion: string; score: number; justification: string }[]`
+- `overallAssessment: string`
+- `recommendations: string[]`
+
+---
+
+## 2. **`chain-of-thought`** Strategy
+**Best for:** Complex reasoning, math problems, multi-step analysis, debugging
+
+### Concept
+Encourages explicit step-by-step reasoning before producing final output. Shows work and intermediate conclusions.
+
+### Required Inputs (Tokens)
+```typescript
+{
+  reasoningPrompt?: string;  // Custom reasoning instruction
+  requireExplicitSteps: boolean;
+  minimumReasoningSteps?: number;
+  showIntermediateWork: boolean;
+  verificationStep?: string;  // Optional: "verify your answer by..."
+}
+```
+
+### System Message Structure
+```
+{instructions}
+
+REASONING APPROACH:
+Before providing your final answer, you must:
+1. Break down the problem/task into clear steps
+2. Work through each step explicitly, showing your reasoning
+3. State intermediate conclusions
+4. {verificationStep if provided}
+5. Provide final answer based on your reasoning
+
+{schema guidance with reasoning field}
+```
+
+### Output Schema Requirements
+Must include:
+- `reasoning: { step: number; description: string; conclusion: string }[]`
+- `finalAnswer: {actual output fields}`
+- `confidenceLevel?: 'high' | 'medium' | 'low'`
+
+---
+
+## 3. **`citation-grounded`** Strategy
+**Best for:** Research summaries, fact-checking, question answering with sources
+
+### Concept
+Forces LLM to cite sources for every claim and distinguish between source content and inference.
+
+### Required Inputs (Tokens)
+```typescript
+{
+  sources: {
+    id: string;
+    title: string;
+    content: string;
+    metadata?: Record<string, any>;
+  }[];
+  requireCitationFor: 'all' | 'facts' | 'statistics' | 'quotes';
+  allowInference: boolean;
+  citationFormat: 'inline' | 'footnote' | 'structured';
+}
+```
+
+### System Message Structure
+```
+{instructions}
+
+SOURCES PROVIDED:
+{sources formatted with IDs}
+
+CITATION REQUIREMENTS:
+- Every factual claim must reference a source using [source_id]
+- Clearly distinguish between:
+  * Direct information from sources (cite with [source_id])
+  * Your inferences (mark as "Inference:")
+  * Uncertain information (mark as "Unclear from sources:")
+- Do not make claims without source support
+- If sources conflict, note the discrepancy
+
+{schema guidance}
+```
+
+### Output Schema Requirements
+```typescript
+{
+  answer: string;  // Main response with inline citations
+  citations: {
+    sourceId: string;
+    relevantExcerpt: string;
+    pageNumber?: number;
+  }[];
+  inferences: string[];  // Explicit list of inferences made
+  uncertainties: string[];  // What couldn't be determined
+  sourceConflicts?: { claim: string; sources: string[] }[];
+}
+```
+
+---
+
+## 4. **`style-guided`** Strategy
+**Best for:** Content writing, marketing copy, documentation, creative writing
+
+### Concept
+Uses explicit style guidelines and tone tokens to match desired voice and format.
+
+### Required Inputs (Tokens)
+```typescript
+{
+  tone: 'formal' | 'casual' | 'technical' | 'persuasive' | 'empathetic' | 'humorous' | string;
+  audience: string;  // "technical developers", "C-suite executives", "general public"
+  styleGuide: {
+    voiceCharacteristics: string[];  // ["conversational", "authoritative"]
+    avoidPhrases: string[];  // Phrases to avoid
+    preferredPhrases: string[];  // Preferred expressions
+    sentenceLength: 'short' | 'medium' | 'long' | 'varied';
+    vocabularyLevel: 'simple' | 'intermediate' | 'advanced' | 'domain-specific';
+  };
+  brandVoice?: {
+    personality: string[];  // ["friendly", "innovative", "trustworthy"]
+    writingRules: string[];  // ["use active voice", "avoid jargon"]
+  };
+  formatRequirements?: {
+    structure: string;  // "introduction, body, conclusion"
+    maxLength?: number;
+    includeElements?: string[];  // ["call-to-action", "statistics", "quotes"]
+  };
+}
+```
+
+### System Message Structure
+```
+{instructions}
+
+STYLE REQUIREMENTS:
+Tone: {tone}
+Audience: {audience}
+
+VOICE CHARACTERISTICS:
+{voiceCharacteristics as bullets}
+
+WRITING GUIDELINES:
+✓ DO: {preferredPhrases}
+✗ AVOID: {avoidPhrases}
+- Sentence Length: {sentenceLength}
+- Vocabulary: {vocabularyLevel}
+
+{brandVoice if provided}
+
+FORMAT:
+{formatRequirements}
+
+{schema guidance}
+```
+
+### Output Schema Requirements
+```typescript
+{
+  content: string;
+  wordCount: number;
+  styleCompliance: {
+    toneMatch: 'high' | 'medium' | 'low';
+    audienceAppropriate: boolean;
+    guidelinesFollowed: string[];
+    guidelinesViolated: string[];
+  };
+  suggestedImprovements?: string[];
+}
+```
+
+---
+
+## 5. **`decomposition-first`** Strategy
+**Best for:** Outlines, project planning, complex task breakdown
+
+### Concept
+Forces LLM to first decompose the task into components before executing, ensuring logical structure.
+
+### Required Inputs (Tokens)
+```typescript
+{
+  decompositionLevel: 'high-level' | 'detailed' | 'granular';
+  hierarchyDepth: number;  // How many levels deep
+  requireDependencies: boolean;  // Track dependencies between components
+  estimationRequired: boolean;  // Require time/effort estimates
+  decompositionCriteria?: {
+    maxComponentsPerLevel: number;
+    minComponentsPerLevel: number;
+    balanceStrategy: 'even' | 'by-complexity' | 'by-priority';
+  };
+}
+```
+
+### System Message Structure
+```
+{instructions}
+
+DECOMPOSITION PROCESS:
+Phase 1: BREAK DOWN THE TASK
+1. Identify the main objective
+2. Decompose into {hierarchyDepth} levels of sub-components
+3. {if requireDependencies: "Map dependencies between components"}
+4. {if estimationRequired: "Estimate effort/time for each"}
+
+Phase 2: VALIDATE STRUCTURE
+- Ensure completeness (nothing missing)
+- Check for logical flow
+- Verify hierarchy makes sense
+
+Phase 3: PRODUCE OUTPUT
+Format your decomposition according to the schema.
+
+DECOMPOSITION CRITERIA:
+{decompositionCriteria}
+
+{schema guidance}
+```
+
+### Output Schema Requirements
+```typescript
+{
+  objective: string;
+  decomposition: {
+    id: string;
+    level: number;
+    parentId?: string;
+    title: string;
+    description: string;
+    dependencies?: string[];  // IDs of components this depends on
+    estimatedEffort?: string;
+    priority?: 'high' | 'medium' | 'low';
+    children?: DecompositionNode[];
+  }[];
+  completenessCheck: {
+    allAreasCovered: boolean;
+    gaps: string[];
+  };
+  suggestedOrder?: string[];  // Optimal execution order considering dependencies
+}
+```
+
+---
+
+## 6. **`constraint-creative`** Strategy
+**Best for:** Creative writing, brainstorming, design tasks with guardrails
+
+### Concept
+Balances creativity with explicit constraints to guide output while maintaining originality.
+
+### Required Inputs (Tokens)
+```typescript
+{
+  creativityLevel: 'conservative' | 'moderate' | 'experimental';
+  hardConstraints: string[];  // Must-follow rules
+  softConstraints: string[];  // Preferences, can bend if needed
+  inspirationSources?: string[];  // Reference materials
+  avoidClichés: string[];  // Overused patterns to avoid
+  requiredElements?: string[];  // Must include these
+  forbiddenElements?: string[];  // Must not include these
+  noveltyRequirement: 'highly-original' | 'somewhat-original' | 'conventional';
+}
+```
+
+### System Message Structure
+```
+{instructions}
+
+CREATIVE BRIEF:
+Creativity Level: {creativityLevel}
+Novelty Requirement: {noveltyRequirement}
+
+HARD CONSTRAINTS (must follow):
+{hardConstraints}
+
+SOFT CONSTRAINTS (preferred):
+{softConstraints}
+
+REQUIRED ELEMENTS:
+{requiredElements}
+
+AVOID:
+- Clichés: {avoidClichés}
+- Forbidden: {forbiddenElements}
+
+{inspirationSources if provided}
+
+CREATIVE PROCESS:
+1. Generate multiple concepts
+2. Evaluate against constraints
+3. Select most promising + original
+4. Refine and develop
+
+{schema guidance}
+```
+
+### Output Schema Requirements
+```typescript
+{
+  primaryOutput: string;  // Main creative work
+  alternativeConcepts: string[];  // 2-3 alternatives considered
+  constraintCompliance: {
+    hardConstraintsMet: boolean;
+    softConstraintsScore: number;  // 0-100
+    violations: string[];
+  };
+  noveltyScore: number;  // Self-assessed 0-100
+  creativeRationale: string;  // Why this approach was chosen
+}
+```
+
+---
+
+## 7. **`test-driven`** Strategy
+**Best for:** Code generation, algorithm design, function creation
+
+### Concept
+Requires thinking about test cases and edge cases before generating code.
+
+### Required Inputs (Tokens)
+```typescript
+{
+  testCases: {
+    input: any;
+    expectedOutput: any;
+    description: string;
+  }[];
+  edgeCases?: string[];  // Descriptions of edge cases to handle
+  performanceRequirements?: {
+    timeComplexity?: string;  // "O(n)", "O(log n)"
+    spaceComplexity?: string;
+    maxExecutionTime?: number;  // milliseconds
+  };
+  codeStandards?: {
+    language: string;
+    framework?: string;
+    style: string;  // "functional", "object-oriented"
+    requireDocumentation: boolean;
+    requireTypeAnnotations: boolean;
+  };
+}
+```
+
+### System Message Structure
+```
+{instructions}
+
+TEST-DRIVEN DEVELOPMENT APPROACH:
+
+PROVIDED TEST CASES:
+{testCases formatted}
+
+EDGE CASES TO HANDLE:
+{edgeCases}
+
+PERFORMANCE REQUIREMENTS:
+{performanceRequirements}
+
+CODE STANDARDS:
+{codeStandards}
+
+PROCESS:
+1. Analyze test cases to understand requirements
+2. Identify edge cases and error scenarios
+3. Design solution approach
+4. Implement with test cases in mind
+5. Verify logic against all test cases
+6. Document assumptions and limitations
+
+{schema guidance}
+```
+
+### Output Schema Requirements
+```typescript
+{
+  code: string;
+  language: string;
+  testCoverage: {
+    testCase: string;
+    passes: boolean;
+    explanation: string;
+  }[];
+  edgeCasesHandled: string[];
+  assumptions: string[];
+  knownLimitations: string[];
+  documentation: string;
+  performanceAnalysis?: {
+    timeComplexity: string;
+    spaceComplexity: string;
+    rationale: string;
+  };
+}
+```
+
+---
+
+## 8. **`comparative-analysis`** Strategy
+**Best for:** Compare options, decision support, versus analysis
+
+### Concept
+Structured comparison across multiple dimensions with explicit criteria.
+
+### Required Inputs (Tokens)
+```typescript
+{
+  subjects: string[];  // Things being compared
+  dimensions: {
+    name: string;
+    description: string;
+    weight?: number;  // Importance weight
+    scoringMethod: 'quantitative' | 'qualitative' | 'binary';
+  }[];
+  decisionCriteria?: {
+    dealBreakers?: string[];  // Automatic disqualifiers
+    niceToHave?: string[];
+    priorities?: string[];
+  };
+  outputFormat: 'matrix' | 'narrative' | 'scorecard';
+}
+```
+
+### System Message Structure
+```
+{instructions}
+
+COMPARISON TASK:
+Subjects: {subjects}
+
+DIMENSIONS OF COMPARISON:
+{dimensions with weights}
+
+DECISION CRITERIA:
+{decisionCriteria}
+
+ANALYSIS APPROACH:
+1. Evaluate each subject across all dimensions
+2. Use consistent scoring method
+3. Weight dimensions appropriately
+4. Provide evidence for assessments
+5. Identify clear winner(s) if applicable
+6. Note trade-offs and considerations
+
+OUTPUT FORMAT: {outputFormat}
+
+{schema guidance}
+```
+
+### Output Schema Requirements
+```typescript
+{
+  comparisonMatrix: {
+    subject: string;
+    scores: {
+      dimension: string;
+      score: number | string;
+      evidence: string;
+      confidence: 'high' | 'medium' | 'low';
+    }[];
+    totalScore?: number;
+    rank?: number;
+  }[];
+  recommendation: {
+    topChoice: string;
+    rationale: string;
+    tradeOffs: string[];
+    contextualFactors: string[];
+  };
+  alternativeScenarios?: {
+    scenario: string;
+    recommendation: string;
+  }[];
+}
+```
+
+---
+
+## 9. **`iterative-refinement`** Strategy (Multi-turn)
+**Best for:** Draft improvement, editing, progressive enhancement
+
+### Concept
+Explicit multi-stage process where LLM produces, critiques, then refines its own output.
+
+### Required Inputs (Tokens)
+```typescript
+{
+  refinementCycles: number;  // How many improve iterations
+  critiqueCriteria: string[];  // What to look for in critique
+  improvementFocus: string[];  // "clarity", "conciseness", "accuracy"
+  preserveAspects?: string[];  // What should NOT change
+  targetQualityLevel: 'publication-ready' | 'review-ready' | 'draft';
+}
+```
+
+### System Message Structure
+```
+{instructions}
+
+ITERATIVE REFINEMENT PROCESS:
+
+You will go through {refinementCycles} cycles:
+
+CYCLE STRUCTURE:
+1. Produce (or Revise)
+2. Critique against: {critiqueCriteria}
+3. Identify improvements for: {improvementFocus}
+4. Preserve: {preserveAspects}
+5. Refine
+
+Target Quality: {targetQualityLevel}
+
+Show all iterations in your output.
+
+{schema guidance}
+```
+
+### Output Schema Requirements
+```typescript
+{
+  iterations: {
+    cycle: number;
+    output: string;
+    critique: {
+      strengths: string[];
+      weaknesses: string[];
+      specificIssues: string[];
+    };
+    improvements: string[];
+  }[];
+  finalOutput: string;
+  qualityAssessment: {
+    meetsTarget: boolean;
+    remainingIssues: string[];
+    confidenceLevel: number;
+  };
+}
+```
+
+---
+
+## 10. **`socratic-reasoning`** Strategy
+**Best for:** Educational content, question answering, knowledge exploration
+
+### Concept
+Guides user understanding through questions and gradual revelation rather than direct answers.
+
+### Required Inputs (Tokens)
+```typescript
+{
+  pedagogicalApproach: 'guided-discovery' | 'scaffolded' | 'exploratory';
+  questionDepth: 'surface' | 'moderate' | 'deep';
+  provideFinalAnswer: boolean;
+  knowledgeLevel: string;  // "beginner", "intermediate", "advanced"
+  learningObjectives?: string[];
+}
+```
+
+### System Message Structure
+```
+{instructions}
+
+SOCRATIC METHOD:
+Your goal is to guide understanding, not just provide answers.
+
+Approach: {pedagogicalApproach}
+Question Depth: {questionDepth}
+Learner Level: {knowledgeLevel}
+
+STRUCTURE YOUR RESPONSE:
+1. Ask clarifying questions to assess understanding
+2. Guide thinking with strategic questions
+3. Provide hints and scaffolding
+4. Allow discovery
+5. {if provideFinalAnswer: "Conclude with clear answer"}
+
+Learning Objectives: {learningObjectives}
+
+{schema guidance}
+```
+
+### Output Schema Requirements
+```typescript
+{
+  guidingQuestions: string[];
+  hints: {
+    level: 'subtle' | 'moderate' | 'direct';
+    content: string;
+  }[];
+  conceptsToExplore: string[];
+  finalExplanation?: string;
+  additionalResources?: string[];
+  assessmentQuestion?: string;  // To check understanding
+}
+```
+
+---
+
+## Implementation Notes
+
+### Strategy Selection Logic
+Add to `RequestBuilder`:
+
+```typescript
+interface StrategyContext {
+  taskType?: 'audit' | 'analysis' | 'writing' | 'code' | 'planning' | 'qa' | 'creative';
+  complexityLevel?: 'simple' | 'moderate' | 'complex';
+  requiresReasoning?: boolean;
+  requiresSources?: boolean;
+  iterative?: boolean;
+}
+
+// Auto-suggest strategy based on context
+function suggestStrategy(context: StrategyContext): string;
+```
+
+### Token Resolution Enhancement
+Support nested token structures:
+```typescript
+{
+  strategy: 'checklist-driven',
+  strategyConfig: {
+    checklistItems: [...],
+    evaluationCriteria: [...]
+  }
+}
+```
+
+### Validation
+Each strategy should validate required tokens are provided:
+```typescript
+validateStrategyInputs(strategy: string, request: BuildMessageRequest): ValidationResult
+```
+
+These strategies cover a much wider range of use cases while maintaining the structured, reliable approach that makes the RequestBuilder valuable. Each can be mixed with the existing few-shot or task-first patterns for maximum effectiveness.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flex-md",
-  "version": "3.5.0",
+  "version": "4.0.0",
   "description": "Parse and stringify FlexMD: semi-structured Markdown with three powerful layers - Frames, Output Format Spec (OFS), and Detection/Extraction.",
   "license": "MIT",
   "author": "",
@@ -37,13 +37,14 @@
     "SPEC.md"
   ],
   "scripts": {
-    "build": "tsc && node ./scripts/cjs-bridge.mjs",
+    "build": "tsc && tsc -p tsconfig.cjs.json && node ./scripts/cjs-bridge.mjs",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "test:smoke": "node test/smoke-require.cjs && node test/smoke-import.mjs"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
     "typescript": "^5.6.3",
     "vitest": "^4.0.16"
   }
-}
+}

package/dist/detection/detector.d.ts

@@ -1,6 +0,0 @@
-import type { DetectedObject } from "../types.js";
-/**
- * Detect FlexMD and other structured objects in arbitrary text.
- * Returns all detected objects with confidence scores and byte ranges.
- */
-export declare function detectObjects(text: string): DetectedObject[];