flex-md 2.0.0 → 3.1.0

package/README.md

@@ -1,341 +1,89 @@
-# flex-md
+# Flex-MD (v3.0) — Markdown Output Contract
 
-Parse and stringify **FlexMD**: semi-structured Markdown with three powerful layers:
+Flex-MD is a TypeScript library for building and enforcing **Markdown Output Contracts** with LLMs. It treats Markdown as a semi-structured data format, allowing you to define required sections, list types, and tables while maintaining 100% standard Markdown compatibility.
 
-- **Layer A**: FlexMD Frames - reliable round-trip Markdown ↔ JSON
-- **Layer B**: Output Format Spec (OFS) - LLM-friendly Markdown contracts
-- **Layer C**: Detection & Extraction - find FlexMD in arbitrary text
+Version 3.0 introduces the **Detect-Repair-Enforce** pipeline, ensuring LLM responses are coerced into compliant structures before being parsed.
 
-## Install
+## Key Features
 
-```bash
-npm i flex-md
-```
-
-## Quick Start
-
-### Layer A: FlexMD Frames
-
-Parse and stringify semi-structured Markdown with frames, metadata, and payloads:
-
-```javascript
-import { parseFlexMd, stringifyFlexMd } from "flex-md";
-
-const md = `[[message role=user id=m1]]
-@tags: auth, login
-Hello
-
-@payload:name: input
-\`\`\`json
-{"a":1}
-\`\`\`
-`;
-
-const doc = parseFlexMd(md);
-console.log(doc.frames[0]?.type); // "message"
-console.log(doc.frames[0]?.meta?.tags); // ["auth", "login"]
-
-const back = stringifyFlexMd(doc, { skipEmpty: true });
-console.log(back);
-```
-
-**Validation:**
-
-```javascript
-import { validateFlexMd } from "flex-md";
-
-const result = validateFlexMd(md);
-if (!result.valid) {
-  console.log("Validation errors:", result.errors);
-}
-```
-
-**Datatype Handling:**
+- **Standard Markdown**: No proprietary tags. Pure headings, lists, and tables.
+- **Strictness Levels (L0–L3)**: From loose guidance to rigid structural enforcement.
+- **Deterministic Repair**: Auto-fixes misformatted LLM output (merged fences, missing headings, format conversion).
+- **Issues Envelope**: A structured failure format for when repairs fail, allowing safe fallbacks.
+- **Tax-Aware Prompts**: Generates minimal, relevant instructions to save tokens.
 
-```javascript
-// Infer types automatically
-const doc = parseFlexMd(md, { metaTypeMode: "infer" });
-// @priority: 5 → number
-// @enabled: true → boolean
-// @value: null → null
+## Installation
 
-// Or use a schema
-const doc2 = parseFlexMd(md, {
-  metaTypeMode: "schema",
-  metaSchema: {
-    priority: "number",
-    enabled: "boolean"
-  }
-});
-```
-
----
-
-### Layer B: Output Format Spec (OFS)
-
-Create LLM-friendly Markdown contracts and extract structured data:
-
-```javascript
-import {
-  parseOutputFormatSpec,
-  stringifyOutputFormatSpec,
-  enrichInstructions,
-  validateOutput,
-  extractOutput
-} from "flex-md";
-
-// Define an output format
-const spec = {
-  descriptorType: "output_format_spec",
-  format: "markdown",
-  sectionOrderMatters: false,
-  sections: [
-    { name: "Short answer", kind: "prose" },
-    { name: "Reasoning", kind: "ordered_list" },
-    { name: "Assumptions", kind: "list" }
-  ],
-  tablesOptional: true,
-  tables: [],
-  emptySectionValue: "None"
-};
-
-// Generate minimal LLM instructions
-const instructions = enrichInstructions(spec);
-console.log(instructions);
-// Output:
-// Rules:
-// - If a section is empty, write `None`.
-// - Ordered-list sections must use numbered items (nested allowed).
-// - List sections must use '-' bullets (nested allowed).
-
-// Stringify for LLM prompt
-const ofsMarkdown = stringifyOutputFormatSpec(spec);
-
-// Later, validate LLM response
-const llmResponse = `
-## Short answer
-The answer is 42.
-
-## Reasoning
-1. First, we analyze the question
-2. Then we compute the result
-
-## Assumptions
-- The universe is deterministic
-- We have sufficient compute
-`;
-
-const validation = validateOutput(llmResponse, spec);
-console.log(validation.ok); // true
-
-// Extract structured data
-const extracted = extractOutput(llmResponse, spec);
-console.log(extracted.sectionsByName["Short answer"].md);
-// "The answer is 42."
-
-console.log(extracted.sectionsByName["Reasoning"].list);
-// { kind: "list", ordered: true, items: [...] }
+```bash
+npm install flex-md
 ```
 
----
-
-### Outline & Tree Building
-
-Build nested heading trees from any Markdown:
-
-```javascript
-import { buildOutline, renderOutline } from "flex-md";
-
-const md = `
-# Introduction
-Some intro text
-
-## Background
-More details
+## Quick Start
 
-### History
-Even more details
+### 1. Define your Output Format Spec (OFS)
 
-## Methodology
-Our approach
-`;
+```typescript
+import { parseOutputFormatSpec } from 'flex-md';
 
-const outline = buildOutline(md);
-console.log(outline.nodes[0].title); // "Introduction"
-console.log(outline.nodes[0].children[0].title); // "Background"
-console.log(outline.nodes[0].children[0].children[0].title); // "History"
+const spec = parseOutputFormatSpec(`
+## Output format
+- Short answer — text (required)
+- Reasoning — ordered list (required)
+- Assumptions — list (optional)
 
-// Render back to Markdown
-const rendered = renderOutline(outline);
+empty sections:
+- If a section is empty, write \`None\`.
+`);
 ```
 
----
-
-### List & Table Parsing
-
-Parse nested lists and tables:
-
-```javascript
-import { parseList, parsePipeTable, extractAllTables } from "flex-md";
-
-// Parse nested lists
-const listMd = `
-- Item 1
-  - Nested 1.1
-  - Nested 1.2
-- Item 2
-`;
-
-const list = parseList(listMd);
-console.log(list.items[0].children.length); // 2
+### 2. Generate Prompt Guidance
 
-// Parse ordered lists
-const orderedMd = `
-1. First step
-   1. Sub-step 1.1
-   2. Sub-step 1.2
-2. Second step
-`;
+```typescript
+import { buildMarkdownGuidance } from 'flex-md';
 
-const orderedList = parseList(orderedMd);
-console.log(orderedList.ordered); // true
-
-// Parse tables
-const tableMd = `
-| Name | Age |
-|------|-----|
-| Alice | 30 |
-| Bob | 25 |
-`;
-
-const table = parsePipeTable(tableMd);
-console.log(table.columns); // ["Name", "Age"]
-console.log(table.rows); // [["Alice", "30"], ["Bob", "25"]]
-
-// Extract all tables from a document
-const allTables = extractAllTables(documentMd);
+const guidance = buildMarkdownGuidance(spec, { level: 1 });
+// Output: "Reply in Markdown. Include these headings... If a section is empty, write 'None'."
 ```
 
----
-
-### Layer C: Detection & Extraction
-
-Find and parse FlexMD from arbitrary text:
+### 3. Enforce the Contract
 
-```javascript
-import { detectObjects, parseAny } from "flex-md";
+```typescript
+import { enforceFlexMd } from 'flex-md';
 
-const mixedText = `
-Some random text here.
+const llmResponse = "I think... ## Short answer \n Yes. ## Reasoning \n 1. Logic";
+const result = enforceFlexMd(llmResponse, spec, { level: 1 });
 
-\`\`\`flexmd
-[[message role=user]]
-Hello from FlexMD!
-\`\`\`
-
-More text.
-
-\`\`\`json
-{
-  "frames": [
-    {"type": "message", "body_md": "JSON FlexDocument"}
-  ]
+if (result.ok) {
+  console.log(result.extracted.sectionsByName["Short answer"].md);
+} else {
+  // result.outputText will contain the Issues Envelope if strictness level >= 1
+  console.log(result.outputText); 
 }
-\`\`\`
-`;
-
-// Detect all objects
-const detected = detectObjects(mixedText);
-console.log(detected[0].kind); // "flexmd_fence"
-console.log(detected[0].confidence); // 1.0
-console.log(detected[1].kind); // "flexdoc_json_fence"
-console.log(detected[1].confidence); // 0.9
-
-// Parse everything
-const result = parseAny(mixedText);
-console.log(result.flexDocs.length); // 2
-console.log(result.remainder); // "Some random text here.\n\nMore text."
 ```
 
----
+## Strictness Levels
 
-## Features
+| Level | Goal | Guidance | Enforcement |
+| :--- | :--- | :--- | :--- |
+| **L0** | Plain Markdown | "Reply in Markdown." | None. Accept as-is. |
+| **L1** | Sectioned MD | "Include these headings..." | Headings must exist. |
+| **L2** | Fenced Container | "Return inside a single block..." | Exactly one fenced block. |
+| **L3** | Typed Structure | "Reasoning is an ordered list..." | Enforce list/table kinds. |
 
-- ✅ **Layer A**: FlexMD Frames with metadata and payloads
-- ✅ **Layer B**: Output Format Spec for LLM contracts
-- ✅ **Layer C**: Multi-tier detection from arbitrary text
-- ✅ **Nested heading trees**: Build and render outline structures
-- ✅ **List parsing**: Support for nested ordered/unordered lists
-- ✅ **Table parsing**: GFM pipe tables with ordered table support
-- ✅ **Datatype handling**: Infer or schema-based type conversion
-- ✅ **Validation**: Validate FlexMD syntax and OFS compliance
-- ✅ **TypeScript**: Full type definitions included
+## The Repair Pipeline
 
-## Documentation
-
-- [SPEC.md](./SPEC.md) - Complete specification with all details
-- [Examples](./examples/) - More usage examples (coming soon)
-
-## Use Cases
-
-### LLM Prompting & Response Parsing
-
-```javascript
-// 1. Define what you want from the LLM
-const spec = {
-  descriptorType: "output_format_spec",
-  format: "markdown",
-  sectionOrderMatters: false,
-  sections: [
-    { name: "Analysis", kind: "prose" },
-    { name: "Steps", kind: "ordered_list" },
-    { name: "Risks", kind: "list" }
-  ],
-  tablesOptional: true,
-  tables: [],
-  emptySectionValue: "None"
-};
-
-// 2. Generate instructions
-const instructions = enrichInstructions(spec);
-
-// 3. Send to LLM with your prompt + instructions
-
-// 4. Validate and extract response
-const validation = validateOutput(llmResponse, spec);
-const data = extractOutput(llmResponse, spec);
-```
+Flex-MD doesn't just validate; it **repairs**. Our deterministic 9-step plan handles:
+1. **Container Normalization**: Wrapping or merging multiple fenced blocks.
+2. **Heading Standardization**: Case-insensitive matching and naming cleanup.
+3. **Missing Headings**: Adding required sections as `None`.
+4. **Stray Content**: Moving text outside headings into a default section.
+5. **Format Conversion**: Transforming bullets to numbered lists (and vice-versa) based on spec.
 
-### Structured Conversation Storage
-
-```javascript
-const conversation = parseFlexMd(`
-[[message role=user id=msg1]]
-What is the capital of France?
-
-[[message role=assistant id=msg2]]
-The capital of France is Paris.
-`);
-
-// Store as JSON, query, manipulate, then stringify back
-const md = stringifyFlexMd(conversation);
-```
-
-### Markdown Documentation Processing
-
-```javascript
-// Build outline from docs
-const outline = buildOutline(documentationMd);
+## Documentation
 
-// Extract specific sections
-const extracted = extractOutput(documentationMd, {
-  sections: [
-    { name: "Installation", kind: "prose" },
-    { name: "API Reference", kind: "list" }
-  ],
-  // ... rest of spec
-});
-```
+Detailed guides and specs can be found in the [docs](./docs) folder:
+- [MDFlex Compliance Spec](./docs/mdflex-compliance.md)
+- [OFS Syntax Guide](./SPEC.md)
 
 ## License
 

package/dist/__tests__/ofs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/ofs.test.js

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { stringifyOutputFormatSpec } from "../ofs/stringify.js";
+import { buildMarkdownGuidance } from "../ofs/enricher.js";
+describe("OFS Object-to-Prompt Flow", () => {
+    const spec = {
+        description: "Standard report format for technical analysis.",
+        sections: [
+            {
+                name: "Summary",
+                kind: "text",
+                required: true,
+                description: "A brief summary of the topic.",
+                instruction: "Keep it under 3 sentences."
+            },
+            {
+                name: "Key Points",
+                kind: "list",
+                required: false,
+                description: "Important takeaways."
+            }
+        ],
+        emptySectionValue: "N/A"
+    };
+    it("should stringify an OFS object correctly", () => {
+        const md = stringifyOutputFormatSpec(spec);
+        expect(md).toContain("## Output format (Markdown)");
+        expect(md).toContain("Standard report format for technical analysis.");
+        expect(md).toContain("- Summary — text (required)");
+        expect(md).toContain("Description: A brief summary of the topic.");
+        expect(md).toContain("Instruction: Keep it under 3 sentences.");
+        expect(md).toContain("- Key Points — list (optional)");
+        expect(md).toContain("Description: Important takeaways.");
+        expect(md).toContain("If a section is empty, write `N/A`.");
+    });
+    it("should build markdown guidance (L1) correctly", () => {
+        const guidance = buildMarkdownGuidance(spec, { level: 1 });
+        expect(guidance).toContain("Include these section headings somewhere");
+        expect(guidance).toContain("- Summary");
+        expect(guidance).toContain("Description: A brief summary of the topic.");
+        expect(guidance).toContain("Instruction: Keep it under 3 sentences.");
+        expect(guidance).toContain("- Key Points");
+        expect(guidance).toContain("Description: Important takeaways.");
+    });
+    it("should build markdown guidance (L3) correctly", () => {
+        const guidance = buildMarkdownGuidance(spec, { level: 3 });
+        expect(guidance).toContain("Return your entire answer inside a single ```markdown fenced block");
+        expect(guidance).toContain("- Summary");
+        expect(guidance).toContain("- Key Points (list)");
+        expect(guidance).toContain("Do not return JSON");
+    });
+});

package/dist/__tests__/validate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/validate.test.js

@@ -0,0 +1,108 @@
+import { describe, it, expect } from "vitest";
+import { validateMarkdownAgainstOfs } from "../validate/validate.js";
+import { parseIssuesEnvelope } from "../ofs/issuesEnvelope.js";
+const SPEC = {
+    emptySectionValue: "None",
+    sections: [
+        { name: "Short answer", kind: "text", required: true },
+        { name: "Long answer", kind: "text", required: true },
+        { name: "Reasoning", kind: "ordered_list", required: true },
+        { name: "Assumptions", kind: "list", required: true },
+        { name: "Unknowns", kind: "list", required: true },
+    ],
+};
+function mdL1Good() {
+    return [
+        "## Short answer",
+        "Yes.",
+        "",
+        "## Long answer",
+        "More details.",
+        "",
+        "## Reasoning",
+        "1. First",
+        "2. Second",
+        "",
+        "## Assumptions",
+        "- A",
+        "",
+        "## Unknowns",
+        "- U",
+    ].join("\n");
+}
+describe("parseIssuesEnvelope()", () => {
+    it("detects envelope and extracts bullets", () => {
+        const env = [
+            "## Status",
+            "Non-compliant output (cannot be repaired to the required format).",
+            "",
+            "## Issues",
+            "- Missing required section: \"Short answer\"",
+            "",
+            "## Expected",
+            "- Headings ...",
+            "",
+            "## Found",
+            "- Something ...",
+            "",
+            "## How to fix",
+            "- Do X",
+        ].join("\n");
+        const parsed = parseIssuesEnvelope(env);
+        expect(parsed.isIssuesEnvelope).toBe(true);
+        expect(parsed.sections["issues"].bullets[0]).toContain("Missing required section");
+    });
+});
+describe("validateMarkdownAgainstOfs()", () => {
+    it("L0 accepts anything", () => {
+        const r = validateMarkdownAgainstOfs("whatever", SPEC, 0);
+        expect(r.ok).toBe(true);
+    });
+    it("L1 fails when required section missing", () => {
+        const md = [
+            "## Short answer",
+            "Yes.",
+            "",
+            "## Reasoning",
+            "1. A",
+        ].join("\n");
+        const r = validateMarkdownAgainstOfs(md, SPEC, 1);
+        expect(r.ok).toBe(false);
+        expect(r.issues.some(i => i.code === "MISSING_SECTION")).toBe(true);
+    });
+    it("L2 requires a single fenced markdown block", () => {
+        const r = validateMarkdownAgainstOfs(mdL1Good(), SPEC, 2);
+        expect(r.ok).toBe(false);
+        expect(r.issues.some(i => i.code === "CONTAINER_MISSING")).toBe(true);
+    });
+    it("L2 passes with one fence containing valid L1", () => {
+        const md = ["```markdown", mdL1Good(), "```"].join("\n");
+        const r = validateMarkdownAgainstOfs(md, SPEC, 2);
+        expect(r.ok).toBe(true);
+    });
+    it("L3 enforces section kinds (Reasoning must be ordered list)", () => {
+        const bad = [
+            "```markdown",
+            [
+                "## Short answer",
+                "Yes",
+                "",
+                "## Long answer",
+                "Details",
+                "",
+                "## Reasoning",
+                "- bullet but should be ordered",
+                "",
+                "## Assumptions",
+                "- A",
+                "",
+                "## Unknowns",
+                "- U",
+            ].join("\n"),
+            "```",
+        ].join("\n");
+        const r = validateMarkdownAgainstOfs(bad, SPEC, 3);
+        expect(r.ok).toBe(false);
+        expect(r.issues.some(i => i.code === "WRONG_SECTION_KIND")).toBe(true);
+    });
+});

package/dist/detect/json/detectIntent.d.ts

@@ -0,0 +1,2 @@
+import { DetectJsonIntentResult } from "./types.js";
+export declare function detectJsonIntent(text: string): DetectJsonIntentResult;

package/dist/detect/json/detectIntent.js

@@ -0,0 +1,79 @@
+const HARD_PATTERNS = [
+    /\breturn\s+only\s+json\b/i,
+    /\boutput\s+only\s+json\b/i,
+    /\bvalid\s+json\s+(object|array)\b/i,
+    /\bno\s+(prose|text|markdown)\b/i,
+    /\bdo\s+not\s+output\s+anything\s+else\b/i,
+];
+const SOFT_PATTERNS = [
+    /\binclude\s+json\b/i,
+    /\bjson\s+preferred\b/i,
+    /\badd\s+a\s+json\b/i,
+    /\bjson\s+format\b/i,
+];
+const SCHEMA_PATTERNS = [
+    /\bjson\s+schema\b/i,
+    /\bschema\b.*\bjson\b/i,
+    /\bajv\b/i,
+    /\bzod\b/i,
+    /\bopenapi\b/i,
+];
+const TOOLING_PATTERNS = [
+    /\bfunction\s+calling\b/i,
+    /\btools?\b/i,
+    /\bresponse_format\b/i,
+    /\btool\s+call\b/i,
+    /\barguments\b.*\bjson\b/i,
+];
+export function detectJsonIntent(text) {
+    const signals = [];
+    const add = (rx, strength, idx, len) => {
+        signals.push({
+            type: "pattern",
+            value: rx.source,
+            strength,
+            start: idx,
+            end: idx != null && len != null ? idx + len : undefined,
+        });
+    };
+    const scan = (patterns, strength) => {
+        for (const base of patterns) {
+            const rx = new RegExp(base.source, base.flags.includes("g") ? base.flags : base.flags + "g");
+            rx.lastIndex = 0;
+            let m;
+            while ((m = rx.exec(text)) !== null) {
+                add(base, strength, m.index, m[0]?.length ?? 0);
+                if (m[0]?.length === 0)
+                    rx.lastIndex++;
+            }
+        }
+    };
+    scan(HARD_PATTERNS, "hard");
+    scan(TOOLING_PATTERNS, "soft");
+    scan(SCHEMA_PATTERNS, "soft");
+    scan(SOFT_PATTERNS, "soft");
+    const hasHard = signals.some(s => s.strength === "hard");
+    const hasSchema = signals.some(s => SCHEMA_PATTERNS.some(rx => rx.source === s.value));
+    const hasTooling = signals.some(s => TOOLING_PATTERNS.some(rx => rx.source === s.value));
+    const hasSoft = signals.some(s => s.strength === "soft");
+    let intent = "none";
+    if (hasHard)
+        intent = "hard";
+    else if (hasSchema)
+        intent = "schema";
+    else if (hasTooling)
+        intent = "tooling";
+    else if (hasSoft)
+        intent = "soft";
+    const confidence = scoreConfidence(intent, signals);
+    return { intent, signals, confidence };
+}
+function scoreConfidence(intent, signals) {
+    if (intent === "none")
+        return signals.length ? 0.2 : 0.0;
+    const hard = signals.filter(s => s.strength === "hard").length;
+    const soft = signals.filter(s => s.strength === "soft").length;
+    if (intent === "hard")
+        return Math.min(1, 0.7 + hard * 0.15);
+    return Math.min(1, 0.4 + soft * 0.1);
+}

package/dist/detect/json/detectPresence.d.ts

@@ -0,0 +1,6 @@
+import { DetectJsonPresenceResult, DetectJsonContainersResult } from "./types.js";
+export declare function detectJsonContainers(md: string): DetectJsonContainersResult;
+export declare function detectJsonPresence(text: string, opts?: {
+    parse?: boolean;
+    maxParses?: number;
+}): DetectJsonPresenceResult;