flex-md 4.3.0 → 4.4.2

package/README.md

@@ -523,46 +523,37 @@ if (status === 'validated' || status === 'fixed') {
 }
 ```
 
-## Integrated OFS Transformation (The "Best of Both Worlds")
+Flex-MD allows you to use its native **Output Format Spec (OFS)** as the source of truth for **NX-MD-Parser's** structured extraction. 
 
-Flex-MD allows you to use its native **Output Format Spec (OFS)** (the markdown-style description) as the source of truth for **NX-MD-Parser's** structured extraction. This combines the simplicity of describing output with markdown and the power of schema-driven JSON transformation.
+### Modern "Smart" Transformation
 
-### Usage:
-
-```typescript
-import { parseOutputFormatSpec, transformWithOfs } from 'flex-md';
+The `transformWithOfs` function is now smarter. It performs **dual parsing**:
+1. **Automatic Parsing**: Even if you don't have a spec, it extracts all sections and camel-cases keys.
+2. **Contract Enforcement**: If you provide a spec, it uses `nx-md-parser` to validate, type-cast (lists/tables), and repair the output.
 
-// 1. Describe your output naturally
-const spec = parseOutputFormatSpec(`
-## Output format
-- Executive Summary — text (required)
-- Key Findings — ordered list (required)
-- Technical Specs — table (optional)
-  Columns: Component, Version, Notes
-`);
+#### Usage with LLM Outputs:
 
-// 2. Transfrom Markdown output using the spec
-const md = `
-### Summary
-The system is fully operational with 99.9% uptime.
+When working with LLMs, pass the **entire response text** directly. Flex-MD handles internal normalization (like escaped `\n` characters) automatically.
 
-### Findings
-1. Scalability improved by 40%
-2. Memory leak in cache module fixed
-`;
+```typescript
+import { transformWithOfs } from 'flex-md';
 
-const { result, status } = transformWithOfs(md, spec);
+// Pass the RAW content string from your LLM provider
+const { 
+  parsedOutput,   // Always populated (auto-extraction)
+  contractOutput, // Populated if spec was provided
+  contractStatus, // "ok" | "different" | "skipped"
+  status          // "validated" | "fixed" | "failed"
+} = transformWithOfs(llmResponseText, spec);
 
-if (status === 'validated' || status === 'fixed') {
-  console.log(result['Executive Summary']); // "The system is fully operational..."
-  console.log(result['Key Findings']);      // ["Scalability improved...", "Memory leak..."]
-}
+console.log(parsedOutput.shortAnswer);
 ```
 
 ### Why use this?
-1. **Fuzzy Matching**: Even if the LLM slightly changes the heading (e.g., "Summary" instead of "Executive Summary"), the adapter will correctly map it based on the spec.
-2. **Type Enforcement**: Lists and Tables are automatically converted to JSON arrays and objects.
-3. **Single Source of Truth**: Use the same spec to guide the LLM AND parse its response.
+1. **Zero-Config Extraction**: Get structured data without writing a schema first.
+2. **Dual-Safe**: Compare what the LLM *sent* (`parsedOutput`) with what the contract *required* (`contractOutput`).
+3. **Internal Normalization**: Handles messy data (escaped newlines, merged code blocks) so you don't have to.
+4. **Fuzzy Matching**: Even if the LLM slightly changes the heading (e.g., "Summary" vs "Executive Summary"), the contract will correctly map it.
 
 ## Advanced AI Features (via NX-MD-Parser 1.4.0)
 
@@ -622,8 +613,8 @@ const md = `
 Everything looks correctly formatted based on initial evidence.
 `;
 
-const { result } = transformWithOfs(md, recallId);
-console.log(result.Confidence); // 0.95
+const { contractOutput } = transformWithOfs(md, recallId);
+console.log(contractOutput.Confidence); // 0.95
 ```
 
 ### Why use this?

package/dist/ofs/adapter.d.ts

@@ -1,5 +1,15 @@
-import { type SchemaType, type TransformResult } from "nx-md-parser";
+import { type SchemaType } from "nx-md-parser";
 import { type OutputFormatSpec } from "../types.js";
+/**
+ * Result of a Flex-MD transformation.
+ */
+export interface FlexTransformResult<T = any> {
+    parsedOutput: Record<string, any>;
+    contractOutput: T | null;
+    contractStatus: "ok" | "different" | "skipped";
+    status: "validated" | "fixed" | "failed";
+    errors: string[];
+}
 /**
  * Converts a Flex-MD OutputFormatSpec to an nx-md-parser Schema.
  */
@@ -8,4 +18,4 @@ export declare function ofsToSchema(spec: OutputFormatSpec): SchemaType;
  * 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).
  */
-export declare function transformWithOfs<T = any>(md: string, specOrRecallId?: OutputFormatSpec | string): TransformResult<T>;
+export declare function transformWithOfs<T = any>(md: string, specOrRecallId?: OutputFormatSpec | string): FlexTransformResult<T>;

package/dist/ofs/adapter.js

@@ -1,7 +1,9 @@
 import { JSONTransformer, Schema } from "nx-md-parser";
 import { recall } from "./memory.js";
-import { parseHeadingsAndSections, extractBullets, parseMarkdownTable, normalizeName, markdownToJson } from "../md/parse.js";
+import { parseHeadingsAndSections, extractBullets, parseMarkdownTable, normalizeName } from "../md/parse.js";
 import { normalizeMarkdownInput } from "../md/normalize.js";
+import { toCamelCase } from "nx-helpers";
+import { markdownToJson as autoMarkdownToJson } from "nx-json-parser";
 /**
  * Converts a Flex-MD OutputFormatSpec to an nx-md-parser Schema.
  */
@@ -53,13 +55,14 @@ export function ofsToSchema(spec) {
 export function transformWithOfs(md, specOrRecallId) {
     // 0. Normalize input (handle literal \n common in LLM outputs)
     const normalizedMd = normalizeMarkdownInput(md);
+    // 1. Automatic parsing (Dual-Response) using nx-json-parser
+    const parsedOutput = autoMarkdownToJson(normalizedMd);
     if (!specOrRecallId) {
-        // AUTOSPECS: If no spec is provided, use internal logic ONLY.
-        // This avoids complex schema generation and keeps it robust for unknown structures.
-        const result = markdownToJson(normalizedMd);
         return {
+            parsedOutput,
+            contractOutput: null,
+            contractStatus: "skipped",
             status: "validated",
-            result: result,
             errors: []
         };
     }
@@ -68,8 +71,10 @@ export function transformWithOfs(md, specOrRecallId) {
         const recalled = recall(specOrRecallId);
         if (!recalled) {
             return {
+                parsedOutput,
+                contractOutput: null,
+                contractStatus: "skipped",
                 status: "failed",
-                result: null,
                 errors: [`Recall ID "${specOrRecallId}" not found in memory.`]
             };
         }
@@ -78,14 +83,13 @@ export function transformWithOfs(md, specOrRecallId) {
     else {
         spec = specOrRecallId;
     }
-    // 1. Parse sections using Flex-MD parser
+    // 2. Parse sections using Flex-MD parser for the contract mapping
     const bulletNames = spec.sections.map(s => s.name);
+    // Note: We use the local headings parser to find the specific sections defined in the spec
     const parsedSections = parseHeadingsAndSections(normalizedMd, { bulletNames });
     const parsedObj = {};
-    // 2. Map sections to OFS and apply complex parsing (tables/lists)
     for (const sectionSpec of spec.sections) {
         const normName = normalizeName(sectionSpec.name);
-        // Find section with similar name
         const found = parsedSections.find(s => normalizeName(s.heading.name) === normName);
         if (found) {
             let value;
@@ -110,8 +114,21 @@ export function transformWithOfs(md, specOrRecallId) {
             parsedObj[sectionSpec.name] = value;
         }
     }
-    // 3. Transform using nx-md-parser for schema validation and auto-fixing
+    // 3. Transform using nx-md-parser (latest v2.2.0) for schema validation and fixing
     const schema = ofsToSchema(spec);
     const transformer = new JSONTransformer(schema);
-    return transformer.transform(parsedObj);
+    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 => 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flex-md",
-  "version": "4.3.0",
+  "version": "4.4.2",
   "description": "Parse and stringify FlexMD: semi-structured Markdown with three powerful layers - Frames, Output Format Spec (OFS), and Detection/Extraction.",
   "license": "MIT",
   "author": "",
@@ -16,6 +16,9 @@
     "detection",
     "extraction"
   ],
+  "ts-node": {
+    "esm": true
+  },
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -44,12 +47,14 @@
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
+    "tsx": "^4.21.0",
     "typescript": "^5.6.3",
     "vitest": "^4.0.16"
   },
   "dependencies": {
     "nd": "^1.2.0",
     "nx-helpers": "^1.5.0",
-    "nx-md-parser": "^2.0.2"
+    "nx-json-parser": "^1.1.0",
+    "nx-md-parser": "^2.2.0"
   }
-}
+}