flex-md 4.7.1 → 4.7.3

package/dist-cjs/ofs/adapter.cjs

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ofsToSchema = ofsToSchema;
+exports.transformWithOfs = transformWithOfs;
+const nx_md_parser_1 = require("nx-md-parser");
+const memory_js_1 = require("./memory.cjs");
+const parse_js_1 = require("../md/parse.cjs");
+const normalize_js_1 = require("../md/normalize.cjs");
+const nx_helpers_1 = require("nx-helpers");
+const nx_json_parser_1 = require("nx-json-parser");
+const logger_js_1 = require("../logger.cjs");
+/**
+ * Converts a Flex-MD OutputFormatSpec to an nx-md-parser Schema.
+ */
+function ofsToSchema(spec) {
+    const properties = {};
+    for (const section of spec.sections) {
+        let type;
+        switch (section.kind) {
+            case "list":
+            case "ordered_list":
+                type = nx_md_parser_1.Schema.array(nx_md_parser_1.Schema.string());
+                break;
+            case "table":
+            case "ordered_table":
+                if (section.columns && section.columns.length > 0) {
+                    const rowProps = {};
+                    for (const col of section.columns) {
+                        rowProps[col] = nx_md_parser_1.Schema.string();
+                    }
+                    type = nx_md_parser_1.Schema.array(nx_md_parser_1.Schema.object(rowProps));
+                }
+                else {
+                    type = nx_md_parser_1.Schema.string();
+                }
+                break;
+            case "text":
+            default:
+                type = nx_md_parser_1.Schema.string();
+                break;
+        }
+        properties[section.name] = type;
+    }
+    if (spec.tables && spec.tables.length > 0) {
+        for (const table of spec.tables) {
+            const tableKey = table.columns.join("_");
+            const rowProps = {};
+            for (const col of table.columns) {
+                rowProps[col] = nx_md_parser_1.Schema.string();
+            }
+            properties[tableKey] = nx_md_parser_1.Schema.array(nx_md_parser_1.Schema.object(rowProps));
+        }
+    }
+    return nx_md_parser_1.Schema.object(properties);
+}
+/**
+ * Transforms markdown text using a Flex-MD OutputFormatSpec or a recallId.
+ * If no spec is provided, it attempts to infer it from the markdown (autospecs).
+ */
+function transformWithOfs(md, specOrRecallId) {
+    logger_js_1.logger.info("Starting Flex-MD transformation", {
+        inputLength: md.length,
+        hasSpec: !!specOrRecallId,
+        specType: specOrRecallId ? typeof specOrRecallId : 'none'
+    });
+    // 0. Normalize input (handle literal \n common in LLM outputs)
+    const normalizedMd = (0, normalize_js_1.normalizeMarkdownInput)(md);
+    logger_js_1.logger.debug("Input normalization", {
+        originalLength: md.length,
+        normalizedLength: normalizedMd.length,
+        changed: md !== normalizedMd
+    });
+    // 1. Automatic parsing (Dual-Response) using nx-json-parser
+    logger_js_1.logger.debug("Starting automatic parsing with nx-json-parser");
+    const parsedOutput = (0, nx_json_parser_1.markdownToJson)(normalizedMd);
+    logger_js_1.logger.debug("Automatic parsing completed", {
+        parsedKeys: Object.keys(parsedOutput),
+        parsedKeyCount: Object.keys(parsedOutput).length
+    });
+    if (!specOrRecallId) {
+        logger_js_1.logger.info("No spec provided, returning parsed output only");
+        return {
+            parsedOutput,
+            contractOutput: null,
+            contractStatus: "skipped",
+            status: "validated",
+            errors: []
+        };
+    }
+    let spec;
+    if (typeof specOrRecallId === "string") {
+        logger_js_1.logger.debug("Recalling spec from memory", { recallId: specOrRecallId });
+        const recalled = (0, memory_js_1.recall)(specOrRecallId);
+        if (!recalled) {
+            logger_js_1.logger.warn("Recall ID not found", { recallId: specOrRecallId });
+            return {
+                parsedOutput,
+                contractOutput: null,
+                contractStatus: "skipped",
+                status: "failed",
+                errors: [`Recall ID "${specOrRecallId}" not found in memory.`]
+            };
+        }
+        spec = recalled;
+        logger_js_1.logger.debug("Spec recalled successfully", {
+            sectionCount: spec.sections.length,
+            sectionNames: spec.sections.map(s => s.name)
+        });
+    }
+    else {
+        spec = specOrRecallId;
+        logger_js_1.logger.debug("Using provided spec directly", {
+            sectionCount: spec.sections.length,
+            sectionNames: spec.sections.map(s => s.name)
+        });
+    }
+    // 2. Parse sections using Flex-MD parser for the contract mapping
+    const bulletNames = spec.sections.map(s => s.name);
+    logger_js_1.logger.debug("Starting section parsing", {
+        expectedSections: bulletNames,
+        sectionCount: bulletNames.length
+    });
+    // Note: We use the local headings parser to find the specific sections defined in the spec
+    const parsedSections = (0, parse_js_1.parseHeadingsAndSections)(normalizedMd, { bulletNames });
+    logger_js_1.logger.debug("Section parsing completed", {
+        foundSections: parsedSections.map(s => s.heading.name),
+        foundCount: parsedSections.length
+    });
+    const parsedObj = {};
+    for (const sectionSpec of spec.sections) {
+        const normName = (0, parse_js_1.normalizeName)(sectionSpec.name);
+        const found = parsedSections.find(s => (0, parse_js_1.normalizeName)(s.heading.name) === normName);
+        logger_js_1.logger.verbose(`Processing section "${sectionSpec.name}"`, {
+            normalizedName: normName,
+            found: !!found,
+            kind: sectionSpec.kind,
+            hasColumns: !!sectionSpec.columns
+        });
+        if (found) {
+            let value;
+            switch (sectionSpec.kind) {
+                case "list":
+                case "ordered_list":
+                    value = (0, parse_js_1.extractBullets)(found.body);
+                    logger_js_1.logger.debug(`Extracted bullets for "${sectionSpec.name}"`, {
+                        bulletCount: Array.isArray(value) ? value.length : 'unknown'
+                    });
+                    break;
+                case "table":
+                case "ordered_table":
+                    if (sectionSpec.columns) {
+                        value = (0, parse_js_1.parseMarkdownTable)(found.body, sectionSpec.columns);
+                        logger_js_1.logger.debug(`Parsed table for "${sectionSpec.name}"`, {
+                            columns: sectionSpec.columns,
+                            rowCount: Array.isArray(value) ? value.length : 'unknown'
+                        });
+                    }
+                    else {
+                        value = found.body.trim();
+                        logger_js_1.logger.debug(`Using raw body for table "${sectionSpec.name}" (no columns specified)`);
+                    }
+                    break;
+                default:
+                    value = found.body.trim();
+                    logger_js_1.logger.debug(`Using trimmed body for "${sectionSpec.name}"`);
+                    break;
+            }
+            parsedObj[sectionSpec.name] = value;
+        }
+        else {
+            logger_js_1.logger.warn(`Section "${sectionSpec.name}" not found in markdown`);
+        }
+    }
+    logger_js_1.logger.debug("Contract parsing completed", {
+        parsedKeys: Object.keys(parsedObj),
+        parsedKeyCount: Object.keys(parsedObj).length
+    });
+    // 3. Transform using nx-md-parser (latest v2.2.0) for schema validation and fixing
+    const schema = ofsToSchema(spec);
+    const transformer = new nx_md_parser_1.JSONTransformer(schema);
+    const transformResult = transformer.transform(parsedObj);
+    // 4. Compare parsed results with contract results
+    const autoKeys = Object.keys(parsedOutput).sort();
+    const contractKeys = transformResult.result ? Object.keys(transformResult.result).map(k => (0, nx_helpers_1.toCamelCase)(k)).sort() : [];
+    const isSame = autoKeys.length > 0 &&
+        autoKeys.every(k => contractKeys.includes(k)) &&
+        contractKeys.length === autoKeys.length;
+    return {
+        parsedOutput,
+        contractOutput: transformResult.result,
+        contractStatus: isSame ? "ok" : "different",
+        status: transformResult.status,
+        errors: transformResult.errors || []
+    };
+}

package/dist-cjs/ofs/enricher.cjs

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMarkdownGuidance = buildMarkdownGuidance;
+exports.enrichInstructions = enrichInstructions;
+exports.enrichInstructionsWithFlexMd = enrichInstructionsWithFlexMd;
+/**
+ * Generates Markdown guidance instructions for the LLM based on the OFS and contract level.
+ * Strictly avoids the word "flex-md" and remains "tax-aware" by only including relevant rules.
+ */
+function buildMarkdownGuidance(spec, strict, opts) {
+    const level = strict.level ?? 0;
+    const fence = opts?.containerFence === "flexmd" ? "```flexmd" : "```markdown";
+    // L0 - Minimal Markdown
+    if (level === 0) {
+        return "Reply in Markdown.";
+    }
+    const lines = [];
+    // L2+ Container Rule
+    if (level >= 2) {
+        lines.push(`Return your entire answer inside a single ${fence} fenced block and nothing else.`);
+        lines.push("");
+        lines.push("Inside the block, include these section headings somewhere (order does not matter):");
+    }
+    else {
+        lines.push("Reply in Markdown.");
+        lines.push("");
+        lines.push("Include these section headings somewhere (order does not matter):");
+    }
+    // Heading List
+    for (const s of spec.sections) {
+        let suffix = "";
+        if (level >= 3) {
+            if (s.kind === "list")
+                suffix = " (list)";
+            else if (s.kind === "ordered_list")
+                suffix = " (ordered list)";
+        }
+        lines.push(`- ${s.name}${suffix}`);
+        if (level >= 1) {
+            if (s.description) {
+                lines.push(`  Description: ${s.description}`);
+            }
+            if (s.instruction) {
+                lines.push(`  Instruction: ${s.instruction}`);
+            }
+        }
+    }
+    lines.push("");
+    // None Rule
+    const noneRule = opts?.includeNoneRule ?? "auto";
+    const hasRequired = spec.sections.some(s => s.required !== false);
+    const includeNone = noneRule === "always" || (noneRule === "auto" && (hasRequired || level >= 3));
+    if (includeNone) {
+        lines.push(`If a section is empty, write \`None\`.`);
+        lines.push("");
+    }
+    // List Rules
+    const listRule = opts?.includeListRules ?? "auto";
+    const hasListDecls = spec.sections.some(s => s.kind === "list" || s.kind === "ordered_list");
+    const includeList = listRule === "always" || (listRule === "auto" && (hasListDecls || level >= 3));
+    if (includeList) {
+        lines.push("List rules:");
+        lines.push("- Use numbered lists (`1.`, `2.`, …) for ordered lists.");
+        lines.push("- Use `-` bullets for unordered lists.");
+        lines.push("");
+    }
+    // Table Rules
+    const tableRule = opts?.includeTableRules ?? "auto";
+    const hasTableDecls = (spec.tables && spec.tables.length > 0) || spec.sections.some(s => s.kind === "table" || s.kind === "ordered_table");
+    const includeTable = tableRule === "always" || (tableRule === "auto" && (hasTableDecls || level >= 3));
+    if (includeTable) {
+        const hasOrderedTable = spec.tables?.some(t => t.kind === "ordered_table") || spec.sections.some(s => s.kind === "ordered_table");
+        lines.push("Tables:");
+        lines.push("- If you include a table, use a Markdown pipe table.");
+        if (hasOrderedTable || level >= 3) {
+            lines.push("- For ordered tables, add a first column named `#` and number rows 1..N.");
+        }
+        lines.push("");
+    }
+    if (level >= 3) {
+        lines.push("Do not return JSON as the response format.");
+    }
+    return lines.join("\n").trim();
+}
+/**
+ * @deprecated Use buildMarkdownGuidance
+ */
+function enrichInstructions(spec, strict) {
+    return buildMarkdownGuidance(spec, strict);
+}
+/**
+ * Enrich instructions with flex-md compliance guidance.
+ * Returns detailed information about what was changed.
+ */
+async function enrichInstructionsWithFlexMd(instructions, strictnessLevel, spec // Optional spec, if provided will include section guidance
+) {
+    const originalLength = instructions.length;
+    const level = parseInt(strictnessLevel.slice(1));
+    // Default spec if none provided (minimal)
+    const effectiveSpec = spec ?? { sections: [] };
+    const guidance = buildMarkdownGuidance(effectiveSpec, { level });
+    // Check if guidance is already present (simple check)
+    if (instructions.includes(guidance)) {
+        return {
+            enriched: instructions,
+            changes: [],
+            originalLength,
+            enhancedLength: originalLength,
+            metadata: {
+                sectionsAdded: 0,
+                containerAdded: false,
+                guidanceAdded: false
+            }
+        };
+    }
+    const separator = instructions.trim().length > 0 ? "\n\n" : "";
+    const enriched = instructions.trim() + separator + guidance;
+    const enhancedLength = enriched.length;
+    const changes = [
+        {
+            type: "added-guidance",
+            description: `Added Flex-MD ${strictnessLevel} compliance guidance.`,
+            location: {
+                start: instructions.trim().length + separator.length,
+                end: enhancedLength
+            },
+            content: guidance
+        }
+    ];
+    if (level >= 2) {
+        changes.push({
+            type: "added-container",
+            description: "Added requirement for a fenced container block.",
+            location: {
+                start: instructions.trim().length + separator.length,
+                end: enhancedLength
+            }
+        });
+    }
+    return {
+        enriched,
+        changes,
+        originalLength,
+        enhancedLength,
+        metadata: {
+            sectionsAdded: effectiveSpec.sections.length,
+            containerAdded: level >= 2,
+            guidanceAdded: true
+        }
+    };
+}

package/dist-cjs/ofs/infer.cjs

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferOfsFromMarkdown = inferOfsFromMarkdown;
+const parse_js_1 = require("../md/parse.cjs");
+/**
+ * Infers an OutputFormatSpec from a Markdown string.
+ */
+function inferOfsFromMarkdown(md) {
+    // Collect all bullet names that look like headers ("- Name")
+    const lines = md.split("\n");
+    const bulletNames = [];
+    for (const line of lines) {
+        // Match "- Name" or "- Name\n" or "- Name " but NOT "- Name: more text"
+        const m = line.match(/^[-*+]\s+([^—:\n]+)$/);
+        if (m) {
+            bulletNames.push(m[1].trim());
+        }
+    }
+    const sections = (0, parse_js_1.parseHeadingsAndSections)(md, { bulletNames });
+    const specSections = [];
+    for (const sec of sections) {
+        const name = sec.heading.name;
+        const body = sec.body.trim();
+        // 1. Detect list
+        const bullets = (0, parse_js_1.extractBullets)(body);
+        if (bullets.length > 0) {
+            specSections.push({
+                name,
+                kind: "list",
+                required: true
+            });
+            continue;
+        }
+        // 2. Detect table (basic check)
+        const lines = body.split("\n").map(l => l.trim()).filter(Boolean);
+        if (lines.length >= 2 && lines[0].startsWith("|") && /^[|\s-:]+$/.test(lines[1])) {
+            // Extract columns
+            const cols = lines[0].split("|").map(c => c.trim()).filter(Boolean);
+            specSections.push({
+                name,
+                kind: "table",
+                columns: cols,
+                required: true
+            });
+            continue;
+        }
+        // Default to text
+        specSections.push({
+            name,
+            kind: "text",
+            required: true
+        });
+    }
+    return {
+        descriptorType: "output_format_spec",
+        format: "markdown",
+        sectionOrderMatters: false,
+        sections: specSections,
+        tablesOptional: true,
+        tables: [],
+        emptySectionValue: "None"
+    };
+}

package/dist-cjs/ofs/issuesEnvelope.cjs

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseIssuesEnvelope = parseIssuesEnvelope;
+exports.buildIssuesEnvelope = buildIssuesEnvelope;
+exports.buildIssuesEnvelopeAuto = buildIssuesEnvelopeAuto;
+const parse_js_1 = require("../md/parse.cjs");
+function parseIssuesEnvelope(md) {
+    return (0, parse_js_1.isIssuesEnvelopeCheck)(md);
+}
+function buildIssuesEnvelope(args) {
+    const issues = args.validation.issues
+        .filter(i => i.severity === "warn" || i.severity === "error")
+        .map(i => `- ${i.message}`);
+    const expected = args.expectedSummary.map(x => `- ${x}`);
+    const found = args.foundSummary.map(x => `- ${x}`);
+    const how = args.howToFix.map(x => `- ${x}`);
+    return [
+        "## Status",
+        "Non-compliant output (cannot be repaired to the required format).",
+        "",
+        "## Issues",
+        issues.length ? issues.join("\n") : "- None",
+        "",
+        "## Expected",
+        expected.length ? expected.join("\n") : "- None",
+        "",
+        "## Found",
+        found.length ? found.join("\n") : "- None",
+        "",
+        "## How to fix",
+        how.length ? how.join("\n") : "- None",
+        "",
+    ].join("\n");
+}
+function buildIssuesEnvelopeAuto(args) {
+    const v = args.validation;
+    const expected = [];
+    const found = [];
+    const how = [];
+    if (args.level >= 2) {
+        expected.push("One single ```markdown fenced block containing the entire answer (no text outside).");
+    }
+    if (args.level >= 1 && (args.requiredSectionNames?.length ?? 0) > 0) {
+        expected.push(`Section headings present (order does not matter): ${args.requiredSectionNames.join(", ")}`);
+    }
+    if (args.level >= 3 && (args.kindRequirements?.length ?? 0) > 0) {
+        for (const k of args.kindRequirements)
+            expected.push(k);
+    }
+    if (v.stats) {
+        found.push(`Detected sections: ${v.stats.sectionCount}`);
+        if (v.stats.missingRequired.length)
+            found.push(`Missing: ${v.stats.missingRequired.join(", ")}`);
+        if (v.stats.duplicates.length)
+            found.push(`Duplicates: ${v.stats.duplicates.join(", ")}`);
+        found.push(`Fences: ${v.stats.container.fenceCount} (langs: ${v.stats.container.fenceLangs.join(", ") || "none"})`);
+        found.push(`Outside text: ${v.stats.container.hasOutsideText ? "yes" : "no"}`);
+    }
+    if (args.level >= 2)
+        how.push("Return a single ```markdown fenced block and nothing else.");
+    if (args.level >= 1)
+        how.push("Include the required headings and put content under each (order does not matter).");
+    how.push('If a section is empty, write "None".');
+    if (args.level >= 3) {
+        how.push('Use numbered lists ("1.", "2.", …) for ordered lists and "-" bullets for unordered lists.');
+        how.push("Use Markdown pipe tables for table sections; ordered tables include a first column '#'.");
+        how.push("Do not return JSON as the response format.");
+    }
+    return buildIssuesEnvelope({
+        validation: v,
+        level: args.level,
+        expectedSummary: expected,
+        foundSummary: found,
+        howToFix: how,
+    });
+}

package/dist-cjs/ofs/memory.cjs

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.remember = remember;
+exports.recall = recall;
+const parser_js_1 = require("./parser.cjs");
+const node_crypto_1 = require("node:crypto");
+const specMemory = new Map();
+/**
+ * Parses Flex-MD instructions and "remembers" the Output Format Spec.
+ * Returns a unique recallId that can be used later.
+ */
+function remember(instructions) {
+    const spec = (0, parser_js_1.parseOutputFormatSpec)(instructions);
+    if (!spec) {
+        throw new Error("No valid Output Format Spec found in instructions.");
+    }
+    const id = (0, node_crypto_1.randomUUID)();
+    specMemory.set(id, spec);
+    return id;
+}
+/**
+ * Recalls a previously remembered Output Format Spec.
+ */
+function recall(id) {
+    return specMemory.get(id);
+}