@loonylabs/llm-middleware 2.0.0

package/dist/examples/character-generator/character-generator.messages.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHARACTER_GENERATOR_USER_TEMPLATE = exports.CHARACTER_GENERATOR_SYSTEM_MESSAGE = void 0;
+// src/examples/character-generator/character-generator.messages.ts
+const json_formatting_constants_1 = require("../../middleware/shared/constants/json-formatting.constants");
+/**
+ * System message for character generation with detailed JSON schema
+ */
+exports.CHARACTER_GENERATOR_SYSTEM_MESSAGE = (0, json_formatting_constants_1.withBasicJsonInstruction)(`You are an expert character creation assistant for creative writing. Your task is to generate detailed, compelling characters based on the provided context.
+
+IMPORTANT: You MUST respond with ONLY a valid JSON object following this exact schema:
+
+{
+  "Name": "Full character name",
+  "Age": "Age or age range (e.g. '25' or 'Early 20s')",
+  "Description": "Brief 2-3 sentence character overview",
+  "Appearance": "Detailed physical description including distinguishing features",
+  "Personality": "Core personality traits, temperament, and behavioral patterns",
+  "Background": "Character's history, upbringing, and formative experiences",
+  "Goals": "What the character wants to achieve (short and long-term)",
+  "Conflicts": "Internal and external conflicts the character faces",
+  "Relationships": "Key relationships and how they relate to others",
+  "SpecialAbilities": "Special skills, talents, or supernatural abilities (if any)",
+  "Weaknesses": "Character flaws, vulnerabilities, and limitations",
+  "Motivation": "Core driving force behind the character's actions",
+  "CharacterArc": "How the character is likely to grow or change",
+  "Dialogue_Style": "How the character speaks and communicates",
+  "Key_Relationships": ["Array of important relationship types"],
+  "Character_Flaws": ["Array of specific character flaws"],
+  "Strengths": ["Array of character strengths and positive traits"]
+}
+
+Rules:
+- Respond with ONLY the JSON object, no additional text
+- All fields are required except SpecialAbilities
+- Make the character believable and three-dimensional
+- Ensure the character fits the provided setting, genre, and audience
+- Create internal consistency between all character elements
+- Include realistic flaws and strengths that create story potential
+
+<think>
+I need to analyze the provided context carefully:
+1. Review the setting, genre, and target audience constraints
+2. Consider the specific role and constraints provided
+3. Create a character that fits organically within these parameters
+4. Ensure all JSON fields are populated with detailed, relevant content
+5. Make sure the character has clear motivation and potential for growth
+</think>`);
+/**
+ * User template - the formatted context is already complete from formatUserMessage
+ */
+const CHARACTER_GENERATOR_USER_TEMPLATE = (formattedContext) => formattedContext;
+exports.CHARACTER_GENERATOR_USER_TEMPLATE = CHARACTER_GENERATOR_USER_TEMPLATE;
+//# sourceMappingURL=character-generator.messages.js.map

package/dist/examples/character-generator/character-generator.messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"character-generator.messages.js","sourceRoot":"","sources":["../../../src/examples/character-generator/character-generator.messages.ts"],"names":[],"mappings":";;;AAAA,mEAAmE;AACnE,2GAAuG;AAEvG;;GAEG;AACU,QAAA,kCAAkC,GAAG,IAAA,oDAAwB,EAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;SAuClE,CAAC,CAAC;AAEX;;GAEG;AACI,MAAM,iCAAiC,GAAG,CAAC,gBAAwB,EAAU,EAAE,CAAC,gBAAgB,CAAC;AAA3F,QAAA,iCAAiC,qCAA0D"}

package/dist/examples/character-generator/character-generator.usecase.d.ts

@@ -0,0 +1,129 @@
+import { BaseAIUseCase } from '../../middleware/usecases/base/base-ai.usecase';
+import { BaseAIRequest, BaseAIResult } from '../../middleware/shared/types/base-request.types';
+import { ModelParameterOverrides } from '../../middleware/services/model-parameter-manager/model-parameter-manager.service';
+/**
+ * Character generation prompt data
+ */
+export interface CharacterPromptData {
+    characterName?: string;
+    role: string;
+    setting?: {
+        Name: string;
+        TimePeriod: string;
+        Location: string;
+        Culture: string;
+        Atmosphere: string;
+    };
+    genre?: {
+        Name: string;
+        Themes: string;
+        Style: string;
+        Conventions: string;
+    };
+    targetAudience?: {
+        Name: string;
+        AgeRange: string;
+        ReadingLevel: string;
+        PreferredThemes: string;
+    };
+    constraints: string[];
+}
+/**
+ * Character generation request interface
+ * Extends BaseAIRequest to support complex prompt objects
+ */
+export interface CharacterGeneratorRequest extends BaseAIRequest<CharacterPromptData | string> {
+}
+/**
+ * Generated character structure (expected JSON response)
+ */
+export interface GeneratedCharacter {
+    Name: string;
+    Age: string;
+    Description: string;
+    Appearance: string;
+    Personality: string;
+    Background: string;
+    Goals: string;
+    Conflicts: string;
+    Relationships: string;
+    SpecialAbilities?: string;
+    Weaknesses: string;
+    Motivation: string;
+    CharacterArc: string;
+    Dialogue_Style: string;
+    Key_Relationships: string[];
+    Character_Flaws: string[];
+    Strengths: string[];
+}
+/**
+ * Character generation result interface
+ * Extends BaseAIResult with character-specific data
+ */
+export interface CharacterGeneratorResult extends BaseAIResult {
+    character: GeneratedCharacter;
+    rawResponse: string;
+    wasRepaired: boolean;
+}
+/**
+ * Advanced character generator use case that demonstrates:
+ * - FlatFormatter for input context preparation
+ * - Structured JSON output with schema
+ * - JSON cleaning and repair
+ * - Complex context building with presets
+ * - Message pattern with separate message files
+ */
+export declare class CharacterGeneratorUseCase extends BaseAIUseCase<CharacterPromptData | string, CharacterGeneratorRequest, CharacterGeneratorResult> {
+    /**
+     * System message from message file
+     */
+    protected readonly systemMessage: string;
+    /**
+     * Get the user template from message file
+     */
+    protected getUserTemplate(): (formattedPrompt: string) => string;
+    /**
+     * Override model parameters for character generation
+     *
+     * Uses the Creative Writing preset optimized for generating rich, varied character descriptions.
+     * This configuration balances creativity with coherence, ensuring characters are interesting
+     * while maintaining consistency across all fields.
+     *
+     * @returns ModelParameterOverrides with Creative Writing preset
+     *
+     * **Parameter Selection Rationale:**
+     * - `temperature: 0.8` - Higher temperature for creative, varied character traits and descriptions
+     * - `repeatPenalty: 1.3` - Moderate penalty to reduce word repetition while allowing natural language flow
+     * - `frequencyPenalty: 0.2` - Encourages diverse vocabulary for richer character descriptions
+     * - `presencePenalty: 0.2` - Promotes introducing new character traits and avoiding clichés
+     * - `topP: 0.92` - High nucleus sampling for creative token selection
+     * - `topK: 60` - Moderate vocabulary diversity for balanced output
+     * - `repeatLastN: 128` - Extended context window to maintain consistency across all character fields
+     *
+     * **Expected Impact:**
+     * - More unique and memorable characters with distinct personalities
+     * - Reduced repetitive phrasing across character description fields
+     * - Natural, fluid writing style that doesn't feel formulaic
+     * - Consistent character voice throughout the entire description
+     *
+     * For more information about parameter presets, see docs/OLLAMA_PARAMETERS.md
+     */
+    protected getParameterOverrides(): ModelParameterOverrides;
+    /**
+     * Format the user message using FlatFormatter and presets
+     */
+    protected formatUserMessage(prompt: CharacterPromptData | string): string;
+    /**
+     * Create the result with parsed character data
+     */
+    protected createResult(content: string, usedPrompt: string, thinking?: string): CharacterGeneratorResult;
+    /**
+     * Validate that the character has all required fields
+     */
+    private validateCharacter;
+    /**
+     * Create a fallback character when JSON parsing completely fails
+     */
+    private createFallbackCharacter;
+}
+//# sourceMappingURL=character-generator.usecase.d.ts.map

package/dist/examples/character-generator/character-generator.usecase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"character-generator.usecase.d.ts","sourceRoot":"","sources":["../../../src/examples/character-generator/character-generator.usecase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gDAAgD,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,kDAAkD,CAAC;AAM/F,OAAO,EAAE,uBAAuB,EAAE,MAAM,mFAAmF,CAAC;AAE5H;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,cAAc,CAAC,EAAE;QACf,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,yBAA0B,SAAQ,aAAa,CAAC,mBAAmB,GAAG,MAAM,CAAC;CAAG;AAEjG;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAyB,SAAQ,YAAY;IAC5D,SAAS,EAAE,kBAAkB,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,qBAAa,yBAA0B,SAAQ,aAAa,CAAC,mBAAmB,GAAG,MAAM,EAAE,yBAAyB,EAAE,wBAAwB,CAAC;IAE7I;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,aAAa,SAAsC;IAEtE;;OAEG;IACH,SAAS,CAAC,eAAe,IAAI,CAAC,eAAe,EAAE,MAAM,KAAK,MAAM;IAIhE;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,SAAS,CAAC,qBAAqB,IAAI,uBAAuB;IAa1D;;OAEG;IACH,SAAS,CAAC,iBAAiB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,GAAG,MAAM;IAmEzE;;OAEG;IACH,SAAS,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,wBAAwB;IAiCxG;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA4BzB;;OAEG;IACH,OAAO,CAAC,uBAAuB;CAoBhC"}

package/dist/examples/character-generator/character-generator.usecase.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CharacterGeneratorUseCase = void 0;
+const base_ai_usecase_1 = require("../../middleware/usecases/base/base-ai.usecase");
+const character_generator_messages_1 = require("./character-generator.messages");
+const flat_formatter_1 = require("../../middleware/services/flat-formatter");
+/**
+ * Advanced character generator use case that demonstrates:
+ * - FlatFormatter for input context preparation
+ * - Structured JSON output with schema
+ * - JSON cleaning and repair
+ * - Complex context building with presets
+ * - Message pattern with separate message files
+ */
+class CharacterGeneratorUseCase extends base_ai_usecase_1.BaseAIUseCase {
+    constructor() {
+        super(...arguments);
+        /**
+         * System message from message file
+         */
+        this.systemMessage = character_generator_messages_1.CHARACTER_GENERATOR_SYSTEM_MESSAGE;
+    }
+    /**
+     * Get the user template from message file
+     */
+    getUserTemplate() {
+        return character_generator_messages_1.CHARACTER_GENERATOR_USER_TEMPLATE;
+    }
+    /**
+     * Override model parameters for character generation
+     *
+     * Uses the Creative Writing preset optimized for generating rich, varied character descriptions.
+     * This configuration balances creativity with coherence, ensuring characters are interesting
+     * while maintaining consistency across all fields.
+     *
+     * @returns ModelParameterOverrides with Creative Writing preset
+     *
+     * **Parameter Selection Rationale:**
+     * - `temperature: 0.8` - Higher temperature for creative, varied character traits and descriptions
+     * - `repeatPenalty: 1.3` - Moderate penalty to reduce word repetition while allowing natural language flow
+     * - `frequencyPenalty: 0.2` - Encourages diverse vocabulary for richer character descriptions
+     * - `presencePenalty: 0.2` - Promotes introducing new character traits and avoiding clichés
+     * - `topP: 0.92` - High nucleus sampling for creative token selection
+     * - `topK: 60` - Moderate vocabulary diversity for balanced output
+     * - `repeatLastN: 128` - Extended context window to maintain consistency across all character fields
+     *
+     * **Expected Impact:**
+     * - More unique and memorable characters with distinct personalities
+     * - Reduced repetitive phrasing across character description fields
+     * - Natural, fluid writing style that doesn't feel formulaic
+     * - Consistent character voice throughout the entire description
+     *
+     * For more information about parameter presets, see docs/OLLAMA_PARAMETERS.md
+     */
+    getParameterOverrides() {
+        // Creative Writing preset - optimized for character generation
+        return {
+            temperatureOverride: 0.8,
+            repeatPenalty: 1.3,
+            frequencyPenalty: 0.2,
+            presencePenalty: 0.2,
+            topP: 0.92,
+            topK: 60,
+            repeatLastN: 128
+        };
+    }
+    /**
+     * Format the user message using FlatFormatter and presets
+     */
+    formatUserMessage(prompt) {
+        // If it's already a string, return as is
+        if (typeof prompt === 'string') {
+            return prompt;
+        }
+        const { characterName, role, setting, genre, targetAudience, constraints } = prompt;
+        let contextSections = [];
+        // Add role requirement
+        contextSections.push(`## CHARACTER ROLE REQUIREMENT:\n${role}`);
+        // Add optional character name
+        if (characterName) {
+            contextSections.push(`## SUGGESTED NAME:\n${characterName}`);
+        }
+        // Format setting as simple object if provided
+        if (setting) {
+            const formattedSetting = flat_formatter_1.FlatFormatter.flatten(setting, {
+                format: 'separator',
+                keyValueSeparator: ': ',
+                separator: '•'
+            });
+            contextSections.push(`## STORY SETTING:\n${formattedSetting}`);
+        }
+        // Format genre as simple object if provided
+        if (genre) {
+            const formattedGenre = flat_formatter_1.FlatFormatter.flatten(genre, {
+                format: 'separator',
+                keyValueSeparator: ': ',
+                separator: '•'
+            });
+            contextSections.push(`## GENRE REQUIREMENTS:\n${formattedGenre}`);
+        }
+        // Format target audience if provided
+        if (targetAudience) {
+            const formattedAudience = flat_formatter_1.FlatFormatter.flatten(targetAudience, {
+                format: 'separator',
+                keyValueSeparator: ': ',
+                separator: '•'
+            });
+            contextSections.push(`## TARGET AUDIENCE:\n${formattedAudience}`);
+        }
+        // Format constraints using FlatFormatter
+        if (constraints && constraints.length > 0) {
+            const constraintsFormatted = flat_formatter_1.FlatFormatter.flatten(constraints.map((constraint, index) => ({
+                constraint: constraint,
+                priority: "MUST FOLLOW"
+            })), {
+                format: 'numbered',
+                entryTitleKey: 'constraint',
+                ignoredKeys: ['constraint'],
+                keyValueSeparator: ': '
+            });
+            contextSections.push(`## CHARACTER CONSTRAINTS:\n${constraintsFormatted}`);
+        }
+        return contextSections.join('\n\n');
+    }
+    /**
+     * Create the result with parsed character data
+     */
+    createResult(content, usedPrompt, thinking) {
+        let character;
+        let wasRepaired = false;
+        let rawResponse = content;
+        try {
+            // First try to parse directly
+            character = JSON.parse(content);
+        }
+        catch (error) {
+            // If direct parsing fails, this indicates JSON was repaired by ResponseProcessorService
+            wasRepaired = true;
+            try {
+                character = JSON.parse(content);
+            }
+            catch (secondError) {
+                // If it still fails after cleaning, create a fallback character
+                character = this.createFallbackCharacter(content, rawResponse);
+            }
+        }
+        // Validate required fields
+        this.validateCharacter(character);
+        return {
+            generatedContent: content,
+            model: this.modelConfig.name,
+            usedPrompt: usedPrompt,
+            thinking: thinking,
+            character: character,
+            rawResponse: rawResponse,
+            wasRepaired: wasRepaired
+        };
+    }
+    /**
+     * Validate that the character has all required fields
+     */
+    validateCharacter(character) {
+        const requiredFields = [
+            'Name', 'Age', 'Description', 'Appearance', 'Personality',
+            'Background', 'Goals', 'Conflicts', 'Relationships',
+            'Weaknesses', 'Motivation', 'CharacterArc', 'Dialogue_Style'
+        ];
+        const missingFields = requiredFields.filter(field => !character[field] ||
+            String(character[field]).trim() === '');
+        if (missingFields.length > 0) {
+            throw new Error(`Generated character is missing required fields: ${missingFields.join(', ')}`);
+        }
+        // Validate array fields
+        if (!Array.isArray(character.Key_Relationships)) {
+            character.Key_Relationships = [];
+        }
+        if (!Array.isArray(character.Character_Flaws)) {
+            character.Character_Flaws = [];
+        }
+        if (!Array.isArray(character.Strengths)) {
+            character.Strengths = [];
+        }
+    }
+    /**
+     * Create a fallback character when JSON parsing completely fails
+     */
+    createFallbackCharacter(content, rawResponse) {
+        return {
+            Name: "Character Generation Failed",
+            Age: "Unknown",
+            Description: "Character generation failed due to invalid response format.",
+            Appearance: "Unable to generate appearance.",
+            Personality: "Unable to generate personality.",
+            Background: "Unable to generate background.",
+            Goals: "Unable to generate goals.",
+            Conflicts: "Unable to generate conflicts.",
+            Relationships: "Unable to generate relationships.",
+            Weaknesses: "Unable to generate weaknesses.",
+            Motivation: "Unable to generate motivation.",
+            CharacterArc: "Unable to generate character arc.",
+            Dialogue_Style: "Unable to generate dialogue style.",
+            Key_Relationships: [],
+            Character_Flaws: ["Generation failure"],
+            Strengths: []
+        };
+    }
+}
+exports.CharacterGeneratorUseCase = CharacterGeneratorUseCase;
+//# sourceMappingURL=character-generator.usecase.js.map

package/dist/examples/character-generator/character-generator.usecase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"character-generator.usecase.js","sourceRoot":"","sources":["../../../src/examples/character-generator/character-generator.usecase.ts"],"names":[],"mappings":"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"}

package/dist/examples/character-generator/create-character.messages.d.ts

@@ -0,0 +1,11 @@
+/**
+ * System message for the create character use case.
+ * This defines how the AI should behave and what format it should return.
+ */
+export declare const CREATE_CHARACTER_SYSTEM_MESSAGE: string;
+/**
+ * Template for constructing the user message.
+ * Takes the base user input and formats it into a complete prompt.
+ */
+export declare const CREATE_CHARACTER_USER_TEMPLATE: (baseInput: string) => string;
+//# sourceMappingURL=create-character.messages.d.ts.map

package/dist/examples/character-generator/create-character.messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-character.messages.d.ts","sourceRoot":"","sources":["../../../src/examples/character-generator/create-character.messages.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,eAAO,MAAM,+BAA+B,QAiBxC,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,8BAA8B,GAAI,WAAW,MAAM,KAAG,MAI7B,CAAC"}

package/dist/examples/character-generator/create-character.messages.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CREATE_CHARACTER_USER_TEMPLATE = exports.CREATE_CHARACTER_SYSTEM_MESSAGE = void 0;
+// src/middleware/messages/examples/create-character.messages.ts
+const json_formatting_constants_1 = require("../../middleware/shared/constants/json-formatting.constants");
+/**
+ * System message for the create character use case.
+ * This defines how the AI should behave and what format it should return.
+ */
+exports.CREATE_CHARACTER_SYSTEM_MESSAGE = (0, json_formatting_constants_1.withArrayJsonInstruction)(`
+You are a character expert in literature. Your job is to create literary character suggestions based on user input.
+Be creative but plausible. Keep it concise.
+When creating characters, strictly follow this JSON Array structure:
+[{
+  "Character_Name": "Name of the character",
+  "Character_Description": "Brief description of the character and their role in the story",
+  "Character_Appearance": "Description of physical appearance",
+  "Character_Strengths": ["Strength1", "Strength2", "Strength3"],
+  "Character_Weaknesses": ["Weakness1", "Weakness2", "Weakness3"],
+  "Character_SelfImage": "How the character sees themselves",
+  "Character_Relationships": {
+    "Family": "Description of family relationships",
+    "Friends": "Description of friendships",
+    "Rivals": "Description of rivalries"
+  },
+  "Character_Specialty": "Special ability or expertise of the character"
+}]`);
+/**
+ * Template for constructing the user message.
+ * Takes the base user input and formats it into a complete prompt.
+ */
+const CREATE_CHARACTER_USER_TEMPLATE = (baseInput) => `
+Create 2 characters based on the following elements: ${baseInput}
+Make sure the characters fit well together and the setting, but are still different from each other.
+
+${json_formatting_constants_1.JSON_ARRAY_FORMATTING_INSTRUCTIONS}`;
+exports.CREATE_CHARACTER_USER_TEMPLATE = CREATE_CHARACTER_USER_TEMPLATE;
+//# sourceMappingURL=create-character.messages.js.map

package/dist/examples/character-generator/create-character.messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-character.messages.js","sourceRoot":"","sources":["../../../src/examples/character-generator/create-character.messages.ts"],"names":[],"mappings":";;;AAAA,gEAAgE;AAChE,2GAA2I;AAE3I;;;GAGG;AACU,QAAA,+BAA+B,GAAG,IAAA,oDAAwB,EAAC;;;;;;;;;;;;;;;;;GAiBrE,CAAC,CAAC;AAEL;;;GAGG;AACI,MAAM,8BAA8B,GAAG,CAAC,SAAiB,EAAU,EAAE,CAAC;uDACtB,SAAS;;;EAG9D,8DAAkC,EAAE,CAAC;AAJ1B,QAAA,8BAA8B,kCAIJ"}

package/dist/examples/flat-formatter-demo/product-preset.example.d.ts

@@ -0,0 +1,99 @@
+import { BasePreset, ProcessedEntity } from '../../middleware/services/flat-formatter';
+/**
+ * Product entity - Example demonstrating COMPLEX FlatFormatter capabilities
+ *
+ * This example shows:
+ * - **Nested objects** (pricing, metadata)
+ * - **Arrays** (features, tags, reviews)
+ * - **Optional fields** with fallbacks
+ * - **Complex transformations** (joining, aggregating, calculating)
+ * - **String composition** (combining multiple fields)
+ *
+ * Use this as a template for entities with complex structures.
+ */
+export interface Product {
+    id?: string;
+    name: string;
+    description: string;
+    category: string;
+    pricing: {
+        basePrice: number;
+        currency: string;
+        discountPercent?: number;
+        taxRate?: number;
+    };
+    features?: string[];
+    tags?: string[];
+    metadata?: {
+        manufacturer: string;
+        origin: string;
+        certifications?: string[];
+    };
+    reviews?: Array<{
+        rating: number;
+        comment: string;
+        author?: string;
+    }>;
+    inStock?: boolean;
+    quantity?: number;
+}
+/**
+ * ProcessedProduct - Normalized, LLM-ready structure
+ *
+ * Shows how preprocessing transforms complex data:
+ * - Arrays joined to strings
+ * - Nested objects flattened
+ * - Calculated fields added
+ * - Everything normalized to strings
+ */
+export interface ProcessedProduct extends ProcessedEntity {
+    [key: string]: string | number | boolean;
+    Name: string;
+    Description: string;
+    Category: string;
+    'Price': string;
+    'Discount': string;
+    'Final Price': string;
+    'Features': string;
+    'Tags': string;
+    'Manufacturer': string;
+    'Origin': string;
+    'Certifications': string;
+    'Average Rating': string;
+    'Review Count': string;
+    'Sample Reviews': string;
+    'Availability': string;
+}
+/**
+ * ProductPreset - Demonstrates advanced preprocessing
+ *
+ * Key techniques:
+ * 1. Array handling (join, map, filter)
+ * 2. Nested object access with optional chaining
+ * 3. Calculations (discounts, averages)
+ * 4. String composition
+ * 5. Fallback values
+ */
+export declare class ProductPreset extends BasePreset<Product, ProcessedProduct> {
+    constructor();
+    protected preprocessEntity(product: Product): ProcessedProduct;
+}
+/**
+ * Singleton instance for global use
+ *
+ * Usage:
+ * ```typescript
+ * import { productPreset } from 'llm-middleware';
+ *
+ * const product = {
+ *   name: 'Wireless Mouse',
+ *   pricing: { basePrice: 29.99, currency: 'USD', discountPercent: 15 },
+ *   features: ['Bluetooth', 'Ergonomic', '3-year warranty'],
+ *   // ... more fields
+ * };
+ *
+ * const formatted = productPreset.formatForLLM(product, "## PRODUCT:");
+ * ```
+ */
+export declare const productPreset: ProductPreset;
+//# sourceMappingURL=product-preset.example.d.ts.map

package/dist/examples/flat-formatter-demo/product-preset.example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-preset.example.d.ts","sourceRoot":"","sources":["../../../src/examples/flat-formatter-demo/product-preset.example.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAEvF;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IAGjB,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IAGF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAGhB,QAAQ,CAAC,EAAE;QACT,YAAY,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,MAAM,CAAC;QACf,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;KAC3B,CAAC;IAGF,OAAO,CAAC,EAAE,KAAK,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IAGH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAEzC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IAGjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IAGtB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IAGf,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IAGzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IAGzB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,qBAAa,aAAc,SAAQ,UAAU,CAAC,OAAO,EAAE,gBAAgB,CAAC;;IAKtE,SAAS,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB;CAuD/D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,eAAsB,CAAC"}

package/dist/examples/flat-formatter-demo/product-preset.example.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.productPreset = exports.ProductPreset = void 0;
+const flat_formatter_1 = require("../../middleware/services/flat-formatter");
+/**
+ * ProductPreset - Demonstrates advanced preprocessing
+ *
+ * Key techniques:
+ * 1. Array handling (join, map, filter)
+ * 2. Nested object access with optional chaining
+ * 3. Calculations (discounts, averages)
+ * 4. String composition
+ * 5. Fallback values
+ */
+class ProductPreset extends flat_formatter_1.BasePreset {
+    constructor() {
+        super('Product');
+    }
+    preprocessEntity(product) {
+        // Calculate pricing
+        const basePrice = product.pricing.basePrice;
+        const currency = product.pricing.currency;
+        const discount = product.pricing.discountPercent || 0;
+        const finalPrice = basePrice * (1 - discount / 100);
+        // Process reviews
+        const reviews = product.reviews || [];
+        const avgRating = reviews.length > 0
+            ? (reviews.reduce((sum, r) => sum + r.rating, 0) / reviews.length).toFixed(1)
+            : 'No ratings';
+        const sampleReviews = reviews.length > 0
+            ? reviews
+                .slice(0, 2) // First 2 reviews
+                .map(r => `"${r.comment}" (${r.rating}/5)${r.author ? ` - ${r.author}` : ''}`)
+                .join('; ')
+            : 'No reviews yet';
+        // Determine availability
+        const inStock = product.inStock ?? false;
+        const quantity = product.quantity ?? 0;
+        const availability = inStock
+            ? `In Stock (${quantity} units available)`
+            : 'Out of Stock';
+        return {
+            'Name': product.name,
+            'Description': product.description,
+            'Category': product.category,
+            // Pricing
+            'Price': `${basePrice.toFixed(2)} ${currency}`,
+            'Discount': discount > 0 ? `${discount}% OFF` : 'No discount',
+            'Final Price': `${finalPrice.toFixed(2)} ${currency}`,
+            // Arrays - join with commas
+            'Features': product.features?.join(', ') || 'No features listed',
+            'Tags': product.tags?.join(', ') || 'No tags',
+            // Metadata - flatten nested object
+            'Manufacturer': product.metadata?.manufacturer || 'Unknown',
+            'Origin': product.metadata?.origin || 'Unknown',
+            'Certifications': product.metadata?.certifications?.join(', ') || 'None',
+            // Reviews - aggregate data
+            'Average Rating': avgRating + ' / 5',
+            'Review Count': `${reviews.length} review${reviews.length !== 1 ? 's' : ''}`,
+            'Sample Reviews': sampleReviews,
+            // Availability
+            'Availability': availability
+        };
+    }
+}
+exports.ProductPreset = ProductPreset;
+/**
+ * Singleton instance for global use
+ *
+ * Usage:
+ * ```typescript
+ * import { productPreset } from 'llm-middleware';
+ *
+ * const product = {
+ *   name: 'Wireless Mouse',
+ *   pricing: { basePrice: 29.99, currency: 'USD', discountPercent: 15 },
+ *   features: ['Bluetooth', 'Ergonomic', '3-year warranty'],
+ *   // ... more fields
+ * };
+ *
+ * const formatted = productPreset.formatForLLM(product, "## PRODUCT:");
+ * ```
+ */
+exports.productPreset = new ProductPreset();
+//# sourceMappingURL=product-preset.example.js.map