@riotprompt/riotprompt 0.0.12 → 0.0.14

package/dist/riotprompt.d.ts

@@ -22,6 +22,9 @@ export { ConversationLogger, ConversationReplayer } from './conversation-logger'
 export { ToolRegistry } from './tools';
 export { StrategyExecutor, IterationStrategyFactory } from './iteration-strategy';
 export { MetricsCollector, ReflectionReportGenerator } from './reflection';
+export * as Serializer from './serializer';
+export * as Writer from './writer';
+export * as Execution from './execution/index';
 export { ModelRegistry, getModelRegistry, resetModelRegistry, getPersonaRole, getEncoding, supportsToolCalls, getModelFamily, configureModel } from './model-config';
 export type { Content } from './items/content';
 export type { Context } from './items/context';

package/dist/riotprompt.js

@@ -29,5 +29,11 @@ export { ConversationLogger, ConversationReplayer } from './conversation-logger.
 export { ToolRegistry } from './tools.js';
 export { IterationStrategyFactory, StrategyExecutor } from './iteration-strategy.js';
 export { MetricsCollector, ReflectionReportGenerator } from './reflection.js';
+import * as serializer from './serializer.js';
+export { serializer as Serializer };
+import * as writer from './writer.js';
+export { writer as Writer };
+import * as index from './execution/index.js';
+export { index as Execution };
 export { ModelRegistry, configureModel, getEncoding, getModelFamily, getModelRegistry, getPersonaRole, resetModelRegistry, supportsToolCalls } from './model-config.js';
 //# sourceMappingURL=riotprompt.js.map

package/dist/riotprompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"riotprompt.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"riotprompt.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/serializer.d.ts

@@ -0,0 +1,5 @@
+import { Prompt } from './prompt';
+export declare const toJSON: (prompt: Prompt) => string;
+export declare const toXML: (prompt: Prompt) => string;
+export declare const fromJSON: (jsonString: string) => Prompt;
+export declare const fromXML: (xmlString: string) => Prompt;

package/dist/serializer.js

@@ -0,0 +1,220 @@
+import { XMLParser } from 'fast-xml-parser';
+import { create as create$1 } from './prompt.js';
+import { create } from './items/section.js';
+
+const toJSON = (prompt)=>{
+    return JSON.stringify(prompt, null, 2);
+};
+const escapeXML = (str)=>{
+    return str.replace(/[<>&'"]/g, (c)=>{
+        switch(c){
+            case '<':
+                return '&lt;';
+            case '>':
+                return '&gt;';
+            case '&':
+                return '&amp;';
+            case '\'':
+                return '&apos;';
+            case '"':
+                return '&quot;';
+            default:
+                return c;
+        }
+    });
+};
+const itemToXML = (item)=>{
+    if (typeof item === 'string') {
+        return `<item>${escapeXML(item)}</item>`;
+    }
+    // Check if it's a section
+    if (item && typeof item === 'object' && 'items' in item) {
+        return sectionToXML(item);
+    }
+    // Check if it's a weighted item
+    if (item && typeof item === 'object' && 'text' in item) {
+        const weightAttr = item.weight !== undefined && item.weight !== null ? ` weight="${item.weight}"` : '';
+        return `<item${weightAttr}>${escapeXML(item.text)}</item>`;
+    }
+    return '';
+};
+const sectionToXML = (section, tagName = 'section')=>{
+    const titleAttr = section.title ? ` title="${escapeXML(section.title)}"` : '';
+    const weightAttr = section.weight ? ` weight="${section.weight}"` : '';
+    let xml = `<${tagName}${titleAttr}${weightAttr}>`;
+    if (section.items && Array.isArray(section.items)) {
+        xml += section.items.map((item)=>itemToXML(item)).join('');
+    }
+    xml += `</${tagName}>`;
+    return xml;
+};
+const toXML = (prompt)=>{
+    let xml = '<?xml version="1.0" encoding="UTF-8"?>\n<prompt>';
+    if (prompt.persona) {
+        xml += sectionToXML(prompt.persona, 'persona');
+    }
+    if (prompt.instructions) {
+        xml += sectionToXML(prompt.instructions, 'instructions');
+    }
+    if (prompt.contents) {
+        xml += sectionToXML(prompt.contents, 'contents');
+    }
+    if (prompt.contexts) {
+        xml += sectionToXML(prompt.contexts, 'contexts');
+    }
+    xml += '</prompt>';
+    return xml;
+};
+// ============================================================================
+// DESERIALIZATION
+// ============================================================================
+// --- JSON Parsing ---
+const parseSectionFromJSON = (jsonSection)=>{
+    if (!jsonSection || !jsonSection.items) {
+        throw new Error("Invalid section structure");
+    }
+    const section = create({
+        title: jsonSection.title,
+        weight: jsonSection.weight
+    });
+    for (const item of jsonSection.items){
+        if (typeof item === 'object' && 'items' in item) {
+            // It's a nested section
+            section.add(parseSectionFromJSON(item));
+        } else if (typeof item === 'object' && 'text' in item) {
+            section.add({
+                text: item.text,
+                weight: item.weight
+            });
+        } else if (typeof item === 'string') {
+            section.add(item);
+        }
+    }
+    return section;
+};
+const fromJSON = (jsonString)=>{
+    const json = JSON.parse(jsonString);
+    // We treat the root json object as matching Prompt interface
+    // But we need to convert plain objects back to Section instances with methods
+    const persona = json.persona ? parseSectionFromJSON(json.persona) : undefined;
+    const instructions = json.instructions ? parseSectionFromJSON(json.instructions) : create({
+        title: 'Instructions'
+    });
+    const contents = json.contents ? parseSectionFromJSON(json.contents) : undefined;
+    const contexts = json.contexts ? parseSectionFromJSON(json.contexts) : undefined;
+    return create$1({
+        persona,
+        instructions,
+        contents,
+        contexts
+    });
+};
+// --- XML Parsing ---
+const parseNodeToSection = (node)=>{
+    // Node structure with preserveOrder: true
+    // It seems attributes can be a sibling property ":@" OR inside the children array depending on version/config/content.
+    // Children are in the array value of the key "section", "persona", etc.
+    const children = node.section || node.persona || node.instructions || node.contents || node.contexts || [];
+    let attributes = node[":@"] || {};
+    // Fallback: check if attributes are inside the children array (as seen in some tests/mocks)
+    if (!node[":@"] && Array.isArray(children)) {
+        for (const child of children){
+            if (child[":@"]) {
+                attributes = child[":@"];
+                break;
+            }
+        }
+    }
+    const title = attributes["@_title"];
+    const weight = attributes["@_weight"] ? Number(attributes["@_weight"]) : undefined;
+    const section = create({
+        title,
+        weight
+    });
+    if (Array.isArray(children)) {
+        for (const child of children){
+            const key = Object.keys(child)[0]; // "item" or "section" or ":@"
+            // console.log(`Processing child key: ${key}`);
+            if (key === ":@") continue; // Already handled or just attributes
+            if (key === "item") {
+                // Item structure: [ { "#text": "Value" }, { ":@": ... } ]
+                const itemContent = child.item;
+                let text = "";
+                let itemWeight = undefined;
+                for (const part of itemContent){
+                    const keys = Object.keys(part);
+                    // console.log('Processing item part keys:', keys);
+                    if (keys.includes("#text")) {
+                        text = part["#text"];
+                    } else if (keys.includes(":@")) {
+                        const attrs = part[":@"];
+                        // console.log('Found attributes:', attrs);
+                        // Check both with and without prefix just in case
+                        const w = attrs["@_weight"] || attrs["weight"];
+                        if (w !== undefined) itemWeight = Number(w);
+                    } else {
+                        // Fallback for cases where attributes might be directly on the part (unexpected but possible)
+                        const w = part["@_weight"] || part["weight"];
+                        if (w !== undefined) itemWeight = Number(w);
+                    }
+                }
+                // console.log(`Adding item: ${text}`);
+                section.add({
+                    text,
+                    weight: itemWeight
+                });
+            } else if (key === "section") {
+                section.add(parseNodeToSection(child));
+            }
+        }
+    }
+    return section;
+};
+const fromXML = (xmlString)=>{
+    const parser = new XMLParser({
+        ignoreAttributes: false,
+        attributeNamePrefix: "@_",
+        preserveOrder: true,
+        trimValues: true
+    });
+    const parsed = parser.parse(xmlString);
+    // parsed is [ { "?xml": ... }, { "prompt": [ ... ] } ]
+    let promptNode = null;
+    for (const node of parsed){
+        if (node.prompt) {
+            promptNode = node.prompt;
+            break;
+        }
+    }
+    if (!promptNode) throw new Error("Invalid XML: missing <prompt> root");
+    let persona;
+    let instructions = create({
+        title: "Instructions"
+    });
+    let contents;
+    let contexts;
+    for (const child of promptNode){
+        if (child.persona) {
+            persona = parseNodeToSection(child);
+            persona.title = "Persona"; // Force title for standard sections?
+        } else if (child.instructions) {
+            instructions = parseNodeToSection(child);
+            instructions.title = "Instructions";
+        } else if (child.contents) {
+            contents = parseNodeToSection(child);
+            contents.title = "Contents";
+        } else if (child.contexts) {
+            contexts = parseNodeToSection(child);
+            contexts.title = "Contexts";
+        }
+    }
+    return create$1({
+        persona,
+        instructions,
+        contents,
+        contexts
+    });
+};
+
+export { fromJSON, fromXML, toJSON, toXML };
+//# sourceMappingURL=serializer.js.map

package/dist/serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.js","sources":["../src/serializer.ts"],"sourcesContent":["import { XMLParser } from \"fast-xml-parser\";\nimport { Prompt, create as createPrompt } from \"./prompt\";\nimport { Section, create as createSection } from \"./items/section\";\nimport { Instruction } from \"./items/instruction\";\nimport { Context } from \"./items/context\";\nimport { Content } from \"./items/content\";\nimport { Weighted } from \"./items/weighted\";\n\nexport const toJSON = (prompt: Prompt): string => {\n    return JSON.stringify(prompt, null, 2);\n}\n\nconst escapeXML = (str: string): string => {\n    return str.replace(/[<>&'\"]/g, (c) => {\n        switch (c) {\n            case '<': return '&lt;';\n            case '>': return '&gt;';\n            case '&': return '&amp;';\n            case '\\'': return '&apos;';\n            case '\"': return '&quot;';\n            default: return c;\n        }\n    });\n}\n\nconst itemToXML = (item: any): string => {\n    if (typeof item === 'string') {\n        return `<item>${escapeXML(item)}</item>`;\n    }\n    \n    // Check if it's a section\n    if (item && typeof item === 'object' && 'items' in item) {\n        return sectionToXML(item);\n    }\n\n    // Check if it's a weighted item\n    if (item && typeof item === 'object' && 'text' in item) {\n        const weightAttr = (item.weight !== undefined && item.weight !== null) ? ` weight=\"${item.weight}\"` : '';\n        return `<item${weightAttr}>${escapeXML(item.text)}</item>`;\n    }\n\n    return '';\n}\n\nconst sectionToXML = (section: any, tagName: string = 'section'): string => {\n    const titleAttr = section.title ? ` title=\"${escapeXML(section.title)}\"` : '';\n    const weightAttr = section.weight ? ` weight=\"${section.weight}\"` : '';\n    \n    let xml = `<${tagName}${titleAttr}${weightAttr}>`;\n    \n    if (section.items && Array.isArray(section.items)) {\n        xml += section.items.map((item: any) => itemToXML(item)).join('');\n    }\n    \n    xml += `</${tagName}>`;\n    return xml;\n}\n\nexport const toXML = (prompt: Prompt): string => {\n    let xml = '<?xml version=\"1.0\" encoding=\"UTF-8\"?>\\n<prompt>';\n\n    if (prompt.persona) {\n        xml += sectionToXML(prompt.persona, 'persona');\n    }\n\n    if (prompt.instructions) {\n        xml += sectionToXML(prompt.instructions, 'instructions');\n    }\n\n    if (prompt.contents) {\n        xml += sectionToXML(prompt.contents, 'contents');\n    }\n\n    if (prompt.contexts) {\n        xml += sectionToXML(prompt.contexts, 'contexts');\n    }\n\n    xml += '</prompt>';\n    return xml;\n}\n\n// ============================================================================\n// DESERIALIZATION\n// ============================================================================\n\n// --- JSON Parsing ---\n\nconst parseSectionFromJSON = <T extends Weighted>(jsonSection: any): Section<T> => {\n    if (!jsonSection || !jsonSection.items) {\n        throw new Error(\"Invalid section structure\");\n    }\n\n    const section = createSection<T>({\n        title: jsonSection.title,\n        weight: jsonSection.weight\n    });\n\n    for (const item of jsonSection.items) {\n        if (typeof item === 'object' && 'items' in item) {\n            // It's a nested section\n            section.add(parseSectionFromJSON<T>(item));\n        } else if (typeof item === 'object' && 'text' in item) {\n            section.add({\n                text: item.text,\n                weight: item.weight\n            } as T);\n        } else if (typeof item === 'string') {\n            section.add(item);\n        }\n    }\n\n    return section;\n}\n\nexport const fromJSON = (jsonString: string): Prompt => {\n    const json = JSON.parse(jsonString);\n    \n    // We treat the root json object as matching Prompt interface\n    // But we need to convert plain objects back to Section instances with methods\n    \n    const persona = json.persona ? parseSectionFromJSON<Instruction>(json.persona) : undefined;\n    const instructions = json.instructions ? parseSectionFromJSON<Instruction>(json.instructions) : createSection<Instruction>({ title: 'Instructions' });\n    \n    const contents = json.contents ? parseSectionFromJSON<Content>(json.contents) : undefined;\n    const contexts = json.contexts ? parseSectionFromJSON<Context>(json.contexts) : undefined;\n\n    return createPrompt({\n        persona,\n        instructions,\n        contents,\n        contexts\n    });\n}\n\n// --- XML Parsing ---\n\nconst parseNodeToSection = <T extends Weighted>(node: any): Section<T> => {\n    // Node structure with preserveOrder: true\n    // It seems attributes can be a sibling property \":@\" OR inside the children array depending on version/config/content.\n    \n    // Children are in the array value of the key \"section\", \"persona\", etc.\n    const children = node.section || node.persona || node.instructions || node.contents || node.contexts || [];\n    \n    let attributes = node[\":@\"] || {};\n    \n    // Fallback: check if attributes are inside the children array (as seen in some tests/mocks)\n    if (!node[\":@\"] && Array.isArray(children)) {\n        for (const child of children) {\n            if (child[\":@\"]) {\n                attributes = child[\":@\"];\n                break;\n            }\n        }\n    }\n\n    const title = attributes[\"@_title\"];\n    const weight = attributes[\"@_weight\"] ? Number(attributes[\"@_weight\"]) : undefined;\n    \n    const section = createSection<T>({ title, weight });\n    \n    if (Array.isArray(children)) {\n        for (const child of children) {\n            const key = Object.keys(child)[0]; // \"item\" or \"section\" or \":@\"\n            // console.log(`Processing child key: ${key}`);\n            if (key === \":@\") continue; // Already handled or just attributes\n             \n            if (key === \"item\") {\n                // Item structure: [ { \"#text\": \"Value\" }, { \":@\": ... } ]\n                const itemContent = child.item;\n                let text = \"\";\n                let itemWeight = undefined;\n                 \n                for (const part of itemContent) {\n                    const keys = Object.keys(part);\n                    // console.log('Processing item part keys:', keys);\n                    if (keys.includes(\"#text\")) {\n                        text = part[\"#text\"];\n                    } else if (keys.includes(\":@\")) {\n                        const attrs = part[\":@\"];\n                        // console.log('Found attributes:', attrs);\n                        // Check both with and without prefix just in case\n                        const w = attrs[\"@_weight\"] || attrs[\"weight\"];\n                        if (w !== undefined) itemWeight = Number(w);\n                    } else {\n                        // Fallback for cases where attributes might be directly on the part (unexpected but possible)\n                        const w = part[\"@_weight\"] || part[\"weight\"];\n                        if (w !== undefined) itemWeight = Number(w);\n                    }\n                }\n                // console.log(`Adding item: ${text}`);\n                section.add({ text, weight: itemWeight } as T);\n            } else if (key === \"section\") {\n                section.add(parseNodeToSection<T>(child));\n            }\n        }\n    }\n    \n    return section;\n}\n\nexport const fromXML = (xmlString: string): Prompt => {\n    const parser = new XMLParser({\n        ignoreAttributes: false,\n        attributeNamePrefix: \"@_\",\n        preserveOrder: true,\n        trimValues: true\n    });\n\n    const parsed = parser.parse(xmlString);\n    // parsed is [ { \"?xml\": ... }, { \"prompt\": [ ... ] } ]\n\n    let promptNode = null;\n    for (const node of parsed) {\n        if (node.prompt) {\n            promptNode = node.prompt;\n            break;\n        }\n    }\n\n    if (!promptNode) throw new Error(\"Invalid XML: missing <prompt> root\");\n\n    let persona: Section<Instruction> | undefined;\n    let instructions: Section<Instruction> = createSection({ title: \"Instructions\" });\n    let contents: Section<Content> | undefined;\n    let contexts: Section<Context> | undefined;\n\n    for (const child of promptNode) {\n        if (child.persona) {\n            persona = parseNodeToSection<Instruction>(child);\n            persona.title = \"Persona\"; // Force title for standard sections?\n        } else if (child.instructions) {\n            instructions = parseNodeToSection<Instruction>(child);\n            instructions.title = \"Instructions\";\n        } else if (child.contents) {\n            contents = parseNodeToSection<Content>(child);\n            contents.title = \"Contents\";\n        } else if (child.contexts) {\n            contexts = parseNodeToSection<Context>(child);\n            contexts.title = \"Contexts\";\n        }\n    }\n\n    return createPrompt({\n        persona,\n        instructions,\n        contents,\n        contexts\n    });\n}\n"],"names":["toJSON","prompt","JSON","stringify","escapeXML","str","replace","c","itemToXML","item","sectionToXML","weightAttr","weight","undefined","text","section","tagName","titleAttr","title","xml","items","Array","isArray","map","join","toXML","persona","instructions","contents","contexts","parseSectionFromJSON","jsonSection","Error","createSection","add","fromJSON","jsonString","json","parse","createPrompt","parseNodeToSection","node","children","attributes","child","Number","key","Object","keys","itemContent","itemWeight","part","includes","attrs","w","fromXML","xmlString","parser","XMLParser","ignoreAttributes","attributeNamePrefix","preserveOrder","trimValues","parsed","promptNode"],"mappings":"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"}

package/dist/writer.d.ts

@@ -0,0 +1,2 @@
+import { Prompt } from './prompt';
+export declare const saveToDirectory: (prompt: Prompt, basePath: string) => Promise<void>;

package/dist/writer.js

@@ -0,0 +1,91 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+const saveToDirectory = async (prompt, basePath)=>{
+    // Ensure base directory exists
+    await fs.mkdir(basePath, {
+        recursive: true
+    });
+    // 1. Save Persona
+    if (prompt.persona) {
+        await saveSection(prompt.persona, path.join(basePath, 'persona'));
+    }
+    // 2. Save Instructions
+    if (prompt.instructions) {
+        await saveSection(prompt.instructions, path.join(basePath, 'instructions'));
+    }
+    // 3. Save Context
+    if (prompt.contexts) {
+        await saveSection(prompt.contexts, path.join(basePath, 'context'));
+    }
+    // 4. Save Content (if any)
+    if (prompt.contents) {
+        await saveSection(prompt.contents, path.join(basePath, 'content'));
+    }
+};
+const saveSection = async (section, targetPath)=>{
+    // If section has subsections, create a directory and recurse
+    // If section only has items, check if we can save as single file (e.g. name of section + .md)
+    // Simplification: We will use a mixed approach.
+    // If the section is "flat" (only items), we can write it to a file.
+    // If the section is "nested" (has subsections), we create a directory.
+    // However, to be consistent with Loader logic:
+    // Loader reads files in a directory as subsections.
+    // So if we have a section "Instructions", and we save it as a directory "instructions":
+    // Its items become content of files?
+    // Strategy:
+    // 1. Create directory `targetPath`.
+    // 2. If the section has items (text), verify if they have titles (subsections).
+    // 3. For each item:
+    //    - If it's a string/Instruction/Content/Context (leaf):
+    //      - If the parent section is the ROOT (e.g. 'persona'), and it's just text, maybe we prefer `persona.md`.
+    //    - If it's a subsection:
+    //      - Recurse into subdirectory.
+    // Let's refine based on typical usage:
+    // - Persona: usually one big text. -> `persona.md`
+    // - Instructions: usually one big text or list of files. -> `instructions.md` or `instructions/part1.md`
+    // - Context: usually list of files. -> `context/data.json`, `context/info.md`
+    // We need to differentiate based on the targetPath provided by caller.
+    // If targetPath ends in "persona" (directory name), we can choose to write `targetPath.md` instead if it's flat.
+    // But `saveToDirectory` created `basePath/persona` (directory path string).
+    // Let's check complexity:
+    const hasSubsections = section.items.some((item)=>typeof item === 'object' && 'items' in item);
+    if (!hasSubsections) {
+        // Flat section. 
+        // If it has multiple items, we can join them? Or write as numbered files?
+        // Usually, a flat section implies content for a single file.
+        // We prefer to write to `targetPath.md`.
+        const content = section.items.map((item)=>{
+            if (typeof item === 'string') return item;
+            return item.text;
+        }).join('\n\n');
+        // Check if we should write to .md file instead of directory
+        // targetPath is e.g. ".../persona". We want ".../persona.md".
+        await fs.writeFile(`${targetPath}.md`, content);
+        return;
+    }
+    // Nested section
+    await fs.mkdir(targetPath, {
+        recursive: true
+    });
+    for(let i = 0; i < section.items.length; i++){
+        const item = section.items[i];
+        if (typeof item === 'object' && 'items' in item) {
+            // Subsection
+            // Use title as filename/dirname
+            const subTitle = item.title || `part-${i + 1}`;
+            const subPath = path.join(targetPath, subTitle);
+            await saveSection(item, subPath);
+        } else {
+            // Leaf item mixed with subsections.
+            // Write to a file. 
+            // If it's just text, we need a filename.
+            const fileName = `item-${i + 1}.md`;
+            const content = typeof item === 'string' ? item : item.text;
+            await fs.writeFile(path.join(targetPath, fileName), content);
+        }
+    }
+};
+
+export { saveToDirectory };
+//# sourceMappingURL=writer.js.map

package/dist/writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.js","sources":["../src/writer.ts"],"sourcesContent":["import * as fs from 'fs/promises';\nimport * as path from 'path';\nimport { Prompt } from './prompt';\nimport { Section } from './items/section';\nimport { Weighted } from './items/weighted';\n\nexport const saveToDirectory = async (prompt: Prompt, basePath: string) => {\n    // Ensure base directory exists\n    await fs.mkdir(basePath, { recursive: true });\n\n    // 1. Save Persona\n    if (prompt.persona) {\n        await saveSection(prompt.persona, path.join(basePath, 'persona'));\n    }\n\n    // 2. Save Instructions\n    if (prompt.instructions) {\n        await saveSection(prompt.instructions, path.join(basePath, 'instructions'));\n    }\n\n    // 3. Save Context\n    if (prompt.contexts) {\n        await saveSection(prompt.contexts, path.join(basePath, 'context'));\n    }\n\n    // 4. Save Content (if any)\n    if (prompt.contents) {\n        await saveSection(prompt.contents, path.join(basePath, 'content'));\n    }\n}\n\nconst saveSection = async (section: Section<Weighted>, targetPath: string) => {\n    // If section has subsections, create a directory and recurse\n    // If section only has items, check if we can save as single file (e.g. name of section + .md)\n    \n    // Simplification: We will use a mixed approach.\n    // If the section is \"flat\" (only items), we can write it to a file.\n    // If the section is \"nested\" (has subsections), we create a directory.\n    \n    // However, to be consistent with Loader logic:\n    // Loader reads files in a directory as subsections.\n    // So if we have a section \"Instructions\", and we save it as a directory \"instructions\":\n    // Its items become content of files?\n    \n    // Strategy:\n    // 1. Create directory `targetPath`.\n    // 2. If the section has items (text), verify if they have titles (subsections).\n    // 3. For each item:\n    //    - If it's a string/Instruction/Content/Context (leaf):\n    //      - If the parent section is the ROOT (e.g. 'persona'), and it's just text, maybe we prefer `persona.md`.\n    //    - If it's a subsection:\n    //      - Recurse into subdirectory.\n\n    // Let's refine based on typical usage:\n    // - Persona: usually one big text. -> `persona.md`\n    // - Instructions: usually one big text or list of files. -> `instructions.md` or `instructions/part1.md`\n    // - Context: usually list of files. -> `context/data.json`, `context/info.md`\n    \n    // We need to differentiate based on the targetPath provided by caller.\n    // If targetPath ends in \"persona\" (directory name), we can choose to write `targetPath.md` instead if it's flat.\n    \n    // But `saveToDirectory` created `basePath/persona` (directory path string).\n    \n    // Let's check complexity:\n    const hasSubsections = section.items.some(item => \n        typeof item === 'object' && 'items' in item\n    );\n\n    if (!hasSubsections) {\n        // Flat section. \n        // If it has multiple items, we can join them? Or write as numbered files?\n        // Usually, a flat section implies content for a single file.\n        // We prefer to write to `targetPath.md`.\n        const content = section.items.map(item => {\n            if (typeof item === 'string') return item;\n            return (item as Weighted).text;\n        }).join('\\n\\n');\n        \n        // Check if we should write to .md file instead of directory\n        // targetPath is e.g. \".../persona\". We want \".../persona.md\".\n        await fs.writeFile(`${targetPath}.md`, content);\n        return;\n    }\n\n    // Nested section\n    await fs.mkdir(targetPath, { recursive: true });\n\n    for (let i = 0; i < section.items.length; i++) {\n        const item = section.items[i];\n        \n        if (typeof item === 'object' && 'items' in item) {\n            // Subsection\n            // Use title as filename/dirname\n            const subTitle = (item as Section<Weighted>).title || `part-${i + 1}`;\n            const subPath = path.join(targetPath, subTitle);\n            await saveSection(item as Section<Weighted>, subPath);\n        } else {\n            // Leaf item mixed with subsections.\n            // Write to a file. \n            // If it's just text, we need a filename.\n            const fileName = `item-${i + 1}.md`;\n            const content = typeof item === 'string' ? item : (item as Weighted).text;\n            await fs.writeFile(path.join(targetPath, fileName), content);\n        }\n    }\n}\n\n"],"names":["saveToDirectory","prompt","basePath","fs","mkdir","recursive","persona","saveSection","path","join","instructions","contexts","contents","section","targetPath","hasSubsections","items","some","item","content","map","text","writeFile","i","length","subTitle","title","subPath","fileName"],"mappings":"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"}

package/guide/architecture.md

@@ -0,0 +1,51 @@
+# Architecture
+
+**Purpose**: High-level overview of the internal design of `riotprompt`.
+
+## Core Concepts
+
+### Prompt Structure
+A `Prompt` in RiotPrompt is not a string; it is a structured object containing four main components:
+
+1.  **Persona**: Defines *who* the AI is (System Prompt).
+2.  **Instructions**: Defines *what* the AI should do (User Prompt / Task).
+3.  **Context**: Background information, data, or documents needed to perform the task.
+4.  **Content**: Specific input data to be processed in this execution (optional, often merged with Context in simpler use cases).
+
+### Section System
+The fundamental building block is the `Section<T>`.
+*   A `Section` contains a list of items (of type `T`) and can also contain nested `Sections`.
+*   This allows for recursive, hierarchical structures (e.g., a Context section containing a "Market Data" section, which contains a "Q1 Results" section).
+*   **Weighted Items**: Most items extend `Weighted`, allowing them to have associated weights or parameters for advanced optimization (though simple usage ignores this).
+
+## Module Structure
+
+The project is organized into distinct logical modules:
+
+*   **`src/riotprompt.ts`**: The main entry point. Exports all sub-modules.
+*   **`src/prompt.ts`**: Defines the `Prompt` interface and factory.
+*   **`src/items/`**: Contains definitions for `Section`, `Instruction`, `Context`, `Content`.
+*   **`src/loader.ts`**: Logic for loading prompt parts from the filesystem. It handles traversing directories and parsing Markdown files (extracting headers as section titles).
+*   **`src/formatter.ts`**: Responsible for taking a `Prompt` object and converting it into a specific format (e.g., a Chat Request object or a flat string). It handles model-specific nuances via adapters.
+*   **`src/serializer.ts`**: Handles converting the internal `Prompt` structure to portable formats like JSON and XML.
+*   **`src/cli.ts`**: The command-line interface implementation, using `commander` and `cardigantime` for config.
+
+## Data Flow (CLI)
+
+1.  **Input**: User provides a directory path.
+2.  **Loader**: `loader.ts` scans the directory.
+    *   `persona.md` or `persona/` -> `Section<Instruction>` (Persona)
+    *   `instructions.md` or `instructions/` -> `Section<Instruction>` (Instructions)
+    *   `context/` -> `Section<Context>` (Context)
+3.  **Assembly**: Parts are combined into a `Prompt` object.
+4.  **Processing**:
+    *   If **Serialization** is requested: `Serializer` converts `Prompt` to JSON/XML.
+    *   If **Formatting** is requested: `Formatter` applies model-specific rules (e.g., role assignment) to generate a Chat Request.
+5.  **Output**: Result is written to stdout or file.
+
+## Design Decisions
+
+*   **Composition over Concatenation**: By keeping prompt parts separate until the final moment, we allow for dynamic injection, reordering, and model-specific formatting without string manipulation hell.
+*   **FileSystem as Source**: We treat the filesystem as a primary way to organize complex prompts. Folders represent Sections, files represent Items. This makes prompts version-controllable and easy to navigate.
+*   **Type Safety**: Extensive use of TypeScript generic types (`Section<T>`) ensures that we don't accidentally mix up Context (data) with Instructions (logic).
+

package/guide/configuration.md

@@ -0,0 +1,51 @@
+# Configuration Reference
+
+**Purpose**: Detailed guide on configuring `riotprompt`.
+
+## Configuration File
+
+RiotPrompt uses `cardigantime` for configuration management. It looks for a `riotprompt.yaml` file in the current working directory or parent directories.
+
+### Schema
+
+```yaml
+# Default model to use if -m flag is not provided
+defaultModel: "gpt-4"
+
+# Base directory for prompts (optional, defaults to current dir)
+promptsDir: "."
+
+# Default output directory for processing (optional)
+outputDir: "./output"
+```
+
+## Model Configuration
+
+RiotPrompt has an internal `ModelRegistry` that determines how prompts are formatted for different models.
+
+*   **Persona Role**: 
+    *   `gpt-4`, `claude` family -> `system` role
+    *   `o1` (o-series) -> `developer` role
+*   **Encoding**: Used for token counting (if enabled).
+
+Currently, these are hardcoded in `src/model-config.ts` but the library supports runtime configuration via `configureModel`.
+
+```typescript
+import { configureModel } from '@riotprompt/riotprompt';
+
+// Register a custom local model
+configureModel({
+    exactMatch: 'my-local-llama',
+    personaRole: 'system',
+    encoding: 'cl100k_base',
+    family: 'llama'
+});
+```
+
+## CLI Flags
+
+CLI flags always override configuration file settings.
+
+*   `-m, --model <name>`: Overrides `defaultModel`.
+*   `-o, --output <path>`: Overrides `outputDir`.
+

package/guide/development.md

@@ -0,0 +1,62 @@
+# Development Guide
+
+**Purpose**: Instructions for contributing to and developing `riotprompt`.
+
+## Setup
+
+1.  **Install Dependencies**:
+    ```bash
+    npm install
+    ```
+
+2.  **Build**:
+    ```bash
+    npm run build
+    ```
+    This builds both the library (`dist/riotprompt.js`) and the CLI (`dist/cli.cjs`).
+
+## Testing
+
+We use **Vitest** for testing.
+
+*   **Run Tests**:
+    ```bash
+    npm test
+    ```
+*   **Run with Coverage**:
+    ```bash
+    npm run test:coverage
+    ```
+
+### Test Structure
+
+*   `tests/unit/`: Tests for individual modules (Serializer, Writer, etc.).
+*   `tests/execution/`: Tests for LLM providers (mocked).
+*   `tests/integration/`: End-to-end tests for the CLI.
+
+### Mocking
+
+Tests that involve LLM APIs or filesystem operations MUST use mocks (`vi.mock`).
+*   **Filesystem**: Use `fs/promises` mocks or temporary directories (via `fs.mkdtemp`).
+*   **APIs**: Mock the SDKs (`openai`, `@anthropic-ai/sdk`) to avoid making real network calls and incurring costs.
+
+## Project Structure
+
+*   `src/`: Source code.
+    *   `items/`: Core data structures (Section, Instruction, etc.).
+    *   `execution/`: LLM provider implementations.
+    *   `util/`: Helpers (filesystem, text processing).
+*   `tests/`: Unit and integration tests.
+*   `input/`: Sample prompts for manual testing.
+
+## Adding Features
+
+1.  **Serialization**: If adding a new format, update `src/serializer.ts` and add the option to `src/cli.ts`.
+2.  **New Item Types**: If adding a new prompt component (e.g., `Example`), create a new file in `src/items/` and update `Prompt` interface in `src/prompt.ts`.
+3.  **CLI Commands**: Update `src/cli.ts` using `commander` syntax.
+4.  **New Providers**: Implement the `Provider` interface in `src/execution/` and register it in `ExecutionManager`.
+
+## Linting
+
+*   **Check**: `npm run lint`
+*   **Fix**: `npm run lint:fix`

package/guide/index.md

@@ -0,0 +1,55 @@
+# AI Agent Guide: RiotPrompt
+
+**Role**: You are an AI assistant tasked with understanding, integrating, or extending `riotprompt`, a structured prompt engineering library.
+
+**Goal**: Provide a comprehensive understanding of `riotprompt`'s capabilities, architecture, and usage patterns to facilitate correct implementation and extension.
+
+## Core Capabilities
+
+`riotprompt` is a library and CLI tool designed to treat LLM prompts as structured code objects rather than simple strings. It allows for the modular assembly, validation, and formatting of prompts.
+
+*   **Structured Prompts**: Prompts are composed of distinct sections: `Persona`, `Instructions`, `Context`, and `Content`.
+*   **Modular Assembly**: Sections can be loaded from separate files or directories and combined dynamically.
+*   **Model-Agnostic Formatting**: The library separates the *content* of a prompt from its *format*. It can output prompts optimized for different models (e.g., OpenAI, Claude) using adapters.
+*   **Serialization**: Prompts can be serialized to JSON or XML for storage or exchange.
+*   **CLI Tool**: A command-line interface allows for easy processing of prompt directories into formatted outputs.
+
+## Quick Start Context
+
+When analyzing or generating code using `riotprompt`, keep these patterns in mind:
+
+1.  **Define Sections**: Prompts are built from `Section<T>` objects.
+2.  **Create Prompt**: Use `createPrompt` to combine sections.
+3.  **Format**: Use `Formatter` to convert the structured prompt into a string or chat messages for a specific model.
+
+```typescript
+import * as RiotPrompt from '@riotprompt/riotprompt';
+
+// 1. Create Sections
+const persona = RiotPrompt.createSection({ title: 'Persona' })
+    .add(RiotPrompt.createInstruction('You are a helpful assistant.'));
+
+const instructions = RiotPrompt.createSection({ title: 'Instructions' })
+    .add(RiotPrompt.createInstruction('Summarize the following text.'));
+
+// 2. Create Prompt
+const prompt = RiotPrompt.createPrompt({
+    persona,
+    instructions
+});
+
+// 3. Format
+const formatter = RiotPrompt.Formatter.create();
+// chatRequest will be a structured object suitable for API calls (e.g. OpenAI chat completion)
+const chatRequest = formatter.formatPrompt('gpt-4', prompt); 
+```
+
+## Documentation Structure
+
+This guide directory contains specialized documentation for different aspects of the system:
+
+*   [Architecture](./architecture.md): Internal design, module structure, and data flow.
+*   [Usage Patterns](./usage.md): Common patterns for CLI and library usage.
+*   [Configuration](./configuration.md): Deep dive into configuration options.
+*   [Development](./development.md): Guide for contributing to `riotprompt`.
+