expo-ai-kit 0.3.6 → 0.4.0

package/build/memory.d.ts

@@ -1,235 +0,0 @@
-/**
- * Chat Memory Management for On-Device AI Models
- *
- * WHY CLIENT-MANAGED MEMORY IS REQUIRED:
- * --------------------------------------
- * On-device AI models (Apple Foundation Models, local LLMs) are stateless.
- * Unlike cloud-based APIs that may maintain server-side conversation state,
- * on-device models have no session persistence or built-in memory.
- *
- * Each generation call accepts a single prompt string and returns a response
- * with no knowledge of previous interactions. To enable multi-turn conversations,
- * the client must:
- *
- * 1. Store all messages locally (this module handles that)
- * 2. Build a complete prompt containing the full conversation history
- * 3. Send the entire context on every generation request
- * 4. Manage memory limits to avoid exceeding model context windows
- *
- * This approach is framework-agnostic and works with React, React Native,
- * Expo, or any JavaScript/TypeScript environment.
- */
-import { LLMMessage, ChatMemoryOptions, ChatMemorySnapshot } from './types';
-/**
- * Build a single prompt string from an array of messages.
- *
- * Uses a simple, deterministic format optimized for on-device models:
- *
- * ```
- * SYSTEM: You are a helpful assistant.
- * USER: Hello!
- * ASSISTANT: Hi there!
- * USER: How are you?
- * ```
- *
- * This format is:
- * - Human-readable for debugging
- * - Token-efficient (minimal overhead)
- * - Deterministic (same input = same output)
- * - Compatible with most instruction-following models
- *
- * @param messages - Array of messages to convert to a prompt
- * @returns A single prompt string ready for generation
- *
- * @example
- * ```ts
- * const prompt = buildPrompt([
- *   { role: 'system', content: 'You are helpful.' },
- *   { role: 'user', content: 'Hi!' },
- *   { role: 'assistant', content: 'Hello!' },
- *   { role: 'user', content: 'What is 2+2?' }
- * ]);
- * // Returns:
- * // "SYSTEM: You are helpful.\nUSER: Hi!\nASSISTANT: Hello!\nUSER: What is 2+2?"
- * ```
- */
-export declare function buildPrompt(messages: LLMMessage[]): string;
-/**
- * ChatMemoryManager - Manages conversation history for stateless on-device AI models.
- *
- * IMPORTANT: On-device models have no built-in memory or session state.
- * This class stores messages client-side and provides methods to:
- * - Add user and assistant messages
- * - Build a complete prompt from conversation history
- * - Limit history to prevent context overflow
- * - Clear or reset the conversation
- *
- * The manager automatically trims old messages when the turn limit is exceeded,
- * keeping the most recent exchanges while preserving the system prompt.
- *
- * @example
- * ```ts
- * // Create a memory manager with a system prompt
- * const memory = new ChatMemoryManager({
- *   maxTurns: 5,
- *   systemPrompt: 'You are a helpful coding assistant.'
- * });
- *
- * // Add a user message
- * memory.addUserMessage('How do I reverse a string in JavaScript?');
- *
- * // Get the full prompt for generation
- * const prompt = memory.getPrompt();
- * // "SYSTEM: You are a helpful coding assistant.\nUSER: How do I reverse a string in JavaScript?"
- *
- * // After generation, add the assistant's response
- * const response = await generate(prompt);
- * memory.addAssistantMessage(response);
- *
- * // Continue the conversation
- * memory.addUserMessage('Can you show me with an arrow function?');
- * const nextPrompt = memory.getPrompt();
- * // Now includes the full conversation history
- * ```
- */
-export declare class ChatMemoryManager {
-    private messages;
-    private systemPrompt;
-    private maxTurns;
-    private contextWindow;
-    /**
-     * Create a new ChatMemoryManager.
-     *
-     * @param options - Configuration options
-     * @param options.maxTurns - Max turns to keep (default: 10). A turn = 1 user + 1 assistant message.
-     * @param options.systemPrompt - Optional system prompt to include in every prompt.
-     * @param options.contextWindow - Max tokens for context (default: Infinity). Trims oldest messages when exceeded.
-     */
-    constructor(options?: ChatMemoryOptions);
-    /**
-     * Add a user message to the conversation history.
-     *
-     * @param content - The user's message content
-     */
-    addUserMessage(content: string): void;
-    /**
-     * Add an assistant message to the conversation history.
-     * Call this after receiving a response from the model.
-     *
-     * @param content - The assistant's response content
-     */
-    addAssistantMessage(content: string): void;
-    /**
-     * Add a message with any role to the conversation history.
-     *
-     * @param message - The message to add
-     */
-    addMessage(message: LLMMessage): void;
-    /**
-     * Get the complete prompt string for the current conversation.
-     *
-     * This method builds a single prompt containing:
-     * 1. The system prompt (if set)
-     * 2. All conversation messages within the turn limit
-     *
-     * Send this prompt to the on-device model for generation.
-     *
-     * @returns The complete prompt string
-     */
-    getPrompt(): string;
-    /**
-     * Get all messages including the system prompt as an LLMMessage array.
-     *
-     * Useful if you need to pass messages to an API that accepts message arrays
-     * rather than a single prompt string.
-     *
-     * @returns Array of all messages including system prompt
-     */
-    getAllMessages(): LLMMessage[];
-    /**
-     * Get only the conversation messages (excludes system prompt).
-     *
-     * @returns Array of user and assistant messages
-     */
-    getMessages(): LLMMessage[];
-    /**
-     * Get a snapshot of the current memory state.
-     *
-     * Useful for debugging, persistence, or UI display.
-     *
-     * @returns Current memory state snapshot
-     */
-    getSnapshot(): ChatMemorySnapshot;
-    /**
-     * Get the current number of conversation turns.
-     *
-     * A turn is counted as a user message (assistant responses don't add turns).
-     * This reflects how many user interactions have occurred.
-     *
-     * @returns Number of turns in the current conversation
-     */
-    getTurnCount(): number;
-    /**
-     * Update the system prompt.
-     *
-     * The system prompt is preserved separately and never trimmed by turn limits.
-     *
-     * @param prompt - New system prompt, or undefined to clear
-     */
-    setSystemPrompt(prompt: string | undefined): void;
-    /**
-     * Get the current system prompt.
-     *
-     * @returns The system prompt or undefined if not set
-     */
-    getSystemPrompt(): string | undefined;
-    /**
-     * Update the maximum number of turns to retain.
-     *
-     * If the new limit is lower than current turn count, older messages
-     * will be trimmed immediately.
-     *
-     * @param maxTurns - New maximum turns
-     */
-    setMaxTurns(maxTurns: number): void;
-    /**
-     * Update the context window (max tokens).
-     *
-     * Called internally when setModel() switches to a model with a different
-     * context window. Can also be called manually.
-     *
-     * @param tokens - Maximum token budget. Use Infinity to disable token-based trimming.
-     */
-    setContextWindow(tokens: number): void;
-    /**
-     * Get the current context window setting.
-     */
-    getContextWindow(): number;
-    /**
-     * Clear all conversation messages but keep the system prompt.
-     *
-     * Use this to start a new conversation with the same assistant persona.
-     */
-    clear(): void;
-    /**
-     * Reset everything including the system prompt.
-     *
-     * Use this for a complete fresh start.
-     */
-    reset(): void;
-    /**
-     * Trim conversation history to stay within limits.
-     *
-     * This preserves the most recent messages while removing older ones.
-     * The system prompt is never affected by trimming.
-     *
-     * Trimming strategy:
-     * 1. Trim by turn count (maxTurns) -- remove oldest user+assistant pairs
-     * 2. Trim by token budget (contextWindow) -- remove oldest messages until under budget
-     * Whichever limit is hit first triggers trimming.
-     */
-    private trimHistory;
-    private trimByTurns;
-    private trimByTokens;
-}
-//# sourceMappingURL=memory.d.ts.map

package/build/memory.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,UAAU,EAAW,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAKrF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,MAAM,CAe1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,iBAAiB;IAE5B,OAAO,CAAC,QAAQ,CAAoB;IAGpC,OAAO,CAAC,YAAY,CAAqB;IAGzC,OAAO,CAAC,QAAQ,CAAS;IAGzB,OAAO,CAAC,aAAa,CAAS;IAE9B;;;;;;;OAOG;gBACS,OAAO,GAAE,iBAAsB;IAM3C;;;;OAIG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAKrC;;;;;OAKG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK1C;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI;IAUrC;;;;;;;;;;OAUG;IACH,SAAS,IAAI,MAAM;IAKnB;;;;;;;OAOG;IACH,cAAc,IAAI,UAAU,EAAE;IAY9B;;;;OAIG;IACH,WAAW,IAAI,UAAU,EAAE;IAI3B;;;;;;OAMG;IACH,WAAW,IAAI,kBAAkB;IASjC;;;;;;;OAOG;IACH,YAAY,IAAI,MAAM;IAItB;;;;;;OAMG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAIjD;;;;OAIG;IACH,eAAe,IAAI,MAAM,GAAG,SAAS;IAIrC;;;;;;;OAOG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAKnC;;;;;;;OAOG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAKtC;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAIb;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAKb;;;;;;;;;;OAUG;IACH,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,WAAW;IA2BnB,OAAO,CAAC,YAAY;CAsBrB"}

package/build/memory.js

@@ -1,353 +0,0 @@
-/**
- * Chat Memory Management for On-Device AI Models
- *
- * WHY CLIENT-MANAGED MEMORY IS REQUIRED:
- * --------------------------------------
- * On-device AI models (Apple Foundation Models, local LLMs) are stateless.
- * Unlike cloud-based APIs that may maintain server-side conversation state,
- * on-device models have no session persistence or built-in memory.
- *
- * Each generation call accepts a single prompt string and returns a response
- * with no knowledge of previous interactions. To enable multi-turn conversations,
- * the client must:
- *
- * 1. Store all messages locally (this module handles that)
- * 2. Build a complete prompt containing the full conversation history
- * 3. Send the entire context on every generation request
- * 4. Manage memory limits to avoid exceeding model context windows
- *
- * This approach is framework-agnostic and works with React, React Native,
- * Expo, or any JavaScript/TypeScript environment.
- */
-// Default maximum turns if not specified
-const DEFAULT_MAX_TURNS = 10;
-/**
- * Build a single prompt string from an array of messages.
- *
- * Uses a simple, deterministic format optimized for on-device models:
- *
- * ```
- * SYSTEM: You are a helpful assistant.
- * USER: Hello!
- * ASSISTANT: Hi there!
- * USER: How are you?
- * ```
- *
- * This format is:
- * - Human-readable for debugging
- * - Token-efficient (minimal overhead)
- * - Deterministic (same input = same output)
- * - Compatible with most instruction-following models
- *
- * @param messages - Array of messages to convert to a prompt
- * @returns A single prompt string ready for generation
- *
- * @example
- * ```ts
- * const prompt = buildPrompt([
- *   { role: 'system', content: 'You are helpful.' },
- *   { role: 'user', content: 'Hi!' },
- *   { role: 'assistant', content: 'Hello!' },
- *   { role: 'user', content: 'What is 2+2?' }
- * ]);
- * // Returns:
- * // "SYSTEM: You are helpful.\nUSER: Hi!\nASSISTANT: Hello!\nUSER: What is 2+2?"
- * ```
- */
-export function buildPrompt(messages) {
-    if (!messages || messages.length === 0) {
-        return '';
-    }
-    // Map role to uppercase label for clarity
-    const roleLabels = {
-        system: 'SYSTEM',
-        user: 'USER',
-        assistant: 'ASSISTANT',
-    };
-    return messages
-        .map((msg) => `${roleLabels[msg.role]}: ${msg.content}`)
-        .join('\n');
-}
-/**
- * ChatMemoryManager - Manages conversation history for stateless on-device AI models.
- *
- * IMPORTANT: On-device models have no built-in memory or session state.
- * This class stores messages client-side and provides methods to:
- * - Add user and assistant messages
- * - Build a complete prompt from conversation history
- * - Limit history to prevent context overflow
- * - Clear or reset the conversation
- *
- * The manager automatically trims old messages when the turn limit is exceeded,
- * keeping the most recent exchanges while preserving the system prompt.
- *
- * @example
- * ```ts
- * // Create a memory manager with a system prompt
- * const memory = new ChatMemoryManager({
- *   maxTurns: 5,
- *   systemPrompt: 'You are a helpful coding assistant.'
- * });
- *
- * // Add a user message
- * memory.addUserMessage('How do I reverse a string in JavaScript?');
- *
- * // Get the full prompt for generation
- * const prompt = memory.getPrompt();
- * // "SYSTEM: You are a helpful coding assistant.\nUSER: How do I reverse a string in JavaScript?"
- *
- * // After generation, add the assistant's response
- * const response = await generate(prompt);
- * memory.addAssistantMessage(response);
- *
- * // Continue the conversation
- * memory.addUserMessage('Can you show me with an arrow function?');
- * const nextPrompt = memory.getPrompt();
- * // Now includes the full conversation history
- * ```
- */
-export class ChatMemoryManager {
-    // Internal storage for conversation messages (excluding system prompt)
-    messages = [];
-    // Optional system prompt, stored separately to ensure it's never trimmed
-    systemPrompt;
-    // Maximum conversation turns to retain
-    maxTurns;
-    // Maximum context window in tokens. Infinity means no token-based trimming.
-    contextWindow;
-    /**
-     * Create a new ChatMemoryManager.
-     *
-     * @param options - Configuration options
-     * @param options.maxTurns - Max turns to keep (default: 10). A turn = 1 user + 1 assistant message.
-     * @param options.systemPrompt - Optional system prompt to include in every prompt.
-     * @param options.contextWindow - Max tokens for context (default: Infinity). Trims oldest messages when exceeded.
-     */
-    constructor(options = {}) {
-        this.maxTurns = options.maxTurns ?? DEFAULT_MAX_TURNS;
-        this.systemPrompt = options.systemPrompt;
-        this.contextWindow = options.contextWindow ?? Infinity;
-    }
-    /**
-     * Add a user message to the conversation history.
-     *
-     * @param content - The user's message content
-     */
-    addUserMessage(content) {
-        this.messages.push({ role: 'user', content });
-        this.trimHistory();
-    }
-    /**
-     * Add an assistant message to the conversation history.
-     * Call this after receiving a response from the model.
-     *
-     * @param content - The assistant's response content
-     */
-    addAssistantMessage(content) {
-        this.messages.push({ role: 'assistant', content });
-        this.trimHistory();
-    }
-    /**
-     * Add a message with any role to the conversation history.
-     *
-     * @param message - The message to add
-     */
-    addMessage(message) {
-        // System messages update the system prompt instead of adding to history
-        if (message.role === 'system') {
-            this.systemPrompt = message.content;
-            return;
-        }
-        this.messages.push(message);
-        this.trimHistory();
-    }
-    /**
-     * Get the complete prompt string for the current conversation.
-     *
-     * This method builds a single prompt containing:
-     * 1. The system prompt (if set)
-     * 2. All conversation messages within the turn limit
-     *
-     * Send this prompt to the on-device model for generation.
-     *
-     * @returns The complete prompt string
-     */
-    getPrompt() {
-        const allMessages = this.getAllMessages();
-        return buildPrompt(allMessages);
-    }
-    /**
-     * Get all messages including the system prompt as an LLMMessage array.
-     *
-     * Useful if you need to pass messages to an API that accepts message arrays
-     * rather than a single prompt string.
-     *
-     * @returns Array of all messages including system prompt
-     */
-    getAllMessages() {
-        const result = [];
-        // System prompt always comes first (if present)
-        if (this.systemPrompt) {
-            result.push({ role: 'system', content: this.systemPrompt });
-        }
-        result.push(...this.messages);
-        return result;
-    }
-    /**
-     * Get only the conversation messages (excludes system prompt).
-     *
-     * @returns Array of user and assistant messages
-     */
-    getMessages() {
-        return [...this.messages];
-    }
-    /**
-     * Get a snapshot of the current memory state.
-     *
-     * Useful for debugging, persistence, or UI display.
-     *
-     * @returns Current memory state snapshot
-     */
-    getSnapshot() {
-        return {
-            messages: this.getAllMessages(),
-            systemPrompt: this.systemPrompt,
-            turnCount: this.getTurnCount(),
-            maxTurns: this.maxTurns,
-        };
-    }
-    /**
-     * Get the current number of conversation turns.
-     *
-     * A turn is counted as a user message (assistant responses don't add turns).
-     * This reflects how many user interactions have occurred.
-     *
-     * @returns Number of turns in the current conversation
-     */
-    getTurnCount() {
-        return this.messages.filter((m) => m.role === 'user').length;
-    }
-    /**
-     * Update the system prompt.
-     *
-     * The system prompt is preserved separately and never trimmed by turn limits.
-     *
-     * @param prompt - New system prompt, or undefined to clear
-     */
-    setSystemPrompt(prompt) {
-        this.systemPrompt = prompt;
-    }
-    /**
-     * Get the current system prompt.
-     *
-     * @returns The system prompt or undefined if not set
-     */
-    getSystemPrompt() {
-        return this.systemPrompt;
-    }
-    /**
-     * Update the maximum number of turns to retain.
-     *
-     * If the new limit is lower than current turn count, older messages
-     * will be trimmed immediately.
-     *
-     * @param maxTurns - New maximum turns
-     */
-    setMaxTurns(maxTurns) {
-        this.maxTurns = maxTurns;
-        this.trimHistory();
-    }
-    /**
-     * Update the context window (max tokens).
-     *
-     * Called internally when setModel() switches to a model with a different
-     * context window. Can also be called manually.
-     *
-     * @param tokens - Maximum token budget. Use Infinity to disable token-based trimming.
-     */
-    setContextWindow(tokens) {
-        this.contextWindow = tokens;
-        this.trimHistory();
-    }
-    /**
-     * Get the current context window setting.
-     */
-    getContextWindow() {
-        return this.contextWindow;
-    }
-    /**
-     * Clear all conversation messages but keep the system prompt.
-     *
-     * Use this to start a new conversation with the same assistant persona.
-     */
-    clear() {
-        this.messages = [];
-    }
-    /**
-     * Reset everything including the system prompt.
-     *
-     * Use this for a complete fresh start.
-     */
-    reset() {
-        this.messages = [];
-        this.systemPrompt = undefined;
-    }
-    /**
-     * Trim conversation history to stay within limits.
-     *
-     * This preserves the most recent messages while removing older ones.
-     * The system prompt is never affected by trimming.
-     *
-     * Trimming strategy:
-     * 1. Trim by turn count (maxTurns) -- remove oldest user+assistant pairs
-     * 2. Trim by token budget (contextWindow) -- remove oldest messages until under budget
-     * Whichever limit is hit first triggers trimming.
-     */
-    trimHistory() {
-        // Step 1: Trim by turn count
-        this.trimByTurns();
-        // Step 2: Trim by context window (if set)
-        if (this.contextWindow !== Infinity) {
-            this.trimByTokens();
-        }
-    }
-    trimByTurns() {
-        const userMessageIndices = [];
-        this.messages.forEach((msg, idx) => {
-            if (msg.role === 'user') {
-                userMessageIndices.push(idx);
-            }
-        });
-        const turnsToRemove = userMessageIndices.length - this.maxTurns;
-        if (turnsToRemove <= 0) {
-            return;
-        }
-        const lastTurnToRemoveIdx = userMessageIndices[turnsToRemove - 1];
-        let cutIndex = lastTurnToRemoveIdx + 1;
-        while (cutIndex < this.messages.length &&
-            this.messages[cutIndex].role === 'assistant') {
-            cutIndex++;
-        }
-        this.messages = this.messages.slice(cutIndex);
-    }
-    trimByTokens() {
-        // TODO: chars/4 is a rough heuristic. Different models use different
-        // tokenizers (SentencePiece for Gemma, BPE for others). If precision
-        // matters, consider per-model tokenizer config. For now this is
-        // conservative enough for trimming.
-        const estimateTokens = (text) => Math.ceil(text.length / 4);
-        const systemTokens = this.systemPrompt
-            ? estimateTokens(this.systemPrompt)
-            : 0;
-        let totalTokens = systemTokens;
-        for (const msg of this.messages) {
-            totalTokens += estimateTokens(msg.content);
-        }
-        // Remove oldest messages until we're under budget
-        while (totalTokens > this.contextWindow && this.messages.length > 0) {
-            const removed = this.messages.shift();
-            totalTokens -= estimateTokens(removed.content);
-        }
-    }
-}
-//# sourceMappingURL=memory.js.map

package/build/memory.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"memory.js","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Chat Memory Management for On-Device AI Models\n *\n * WHY CLIENT-MANAGED MEMORY IS REQUIRED:\n * --------------------------------------\n * On-device AI models (Apple Foundation Models, local LLMs) are stateless.\n * Unlike cloud-based APIs that may maintain server-side conversation state,\n * on-device models have no session persistence or built-in memory.\n *\n * Each generation call accepts a single prompt string and returns a response\n * with no knowledge of previous interactions. To enable multi-turn conversations,\n * the client must:\n *\n * 1. Store all messages locally (this module handles that)\n * 2. Build a complete prompt containing the full conversation history\n * 3. Send the entire context on every generation request\n * 4. Manage memory limits to avoid exceeding model context windows\n *\n * This approach is framework-agnostic and works with React, React Native,\n * Expo, or any JavaScript/TypeScript environment.\n */\n\nimport { LLMMessage, LLMRole, ChatMemoryOptions, ChatMemorySnapshot } from './types';\n\n// Default maximum turns if not specified\nconst DEFAULT_MAX_TURNS = 10;\n\n/**\n * Build a single prompt string from an array of messages.\n *\n * Uses a simple, deterministic format optimized for on-device models:\n *\n * ```\n * SYSTEM: You are a helpful assistant.\n * USER: Hello!\n * ASSISTANT: Hi there!\n * USER: How are you?\n * ```\n *\n * This format is:\n * - Human-readable for debugging\n * - Token-efficient (minimal overhead)\n * - Deterministic (same input = same output)\n * - Compatible with most instruction-following models\n *\n * @param messages - Array of messages to convert to a prompt\n * @returns A single prompt string ready for generation\n *\n * @example\n * ```ts\n * const prompt = buildPrompt([\n *   { role: 'system', content: 'You are helpful.' },\n *   { role: 'user', content: 'Hi!' },\n *   { role: 'assistant', content: 'Hello!' },\n *   { role: 'user', content: 'What is 2+2?' }\n * ]);\n * // Returns:\n * // \"SYSTEM: You are helpful.\\nUSER: Hi!\\nASSISTANT: Hello!\\nUSER: What is 2+2?\"\n * ```\n */\nexport function buildPrompt(messages: LLMMessage[]): string {\n  if (!messages || messages.length === 0) {\n    return '';\n  }\n\n  // Map role to uppercase label for clarity\n  const roleLabels: Record<LLMRole, string> = {\n    system: 'SYSTEM',\n    user: 'USER',\n    assistant: 'ASSISTANT',\n  };\n\n  return messages\n    .map((msg) => `${roleLabels[msg.role]}: ${msg.content}`)\n    .join('\\n');\n}\n\n/**\n * ChatMemoryManager - Manages conversation history for stateless on-device AI models.\n *\n * IMPORTANT: On-device models have no built-in memory or session state.\n * This class stores messages client-side and provides methods to:\n * - Add user and assistant messages\n * - Build a complete prompt from conversation history\n * - Limit history to prevent context overflow\n * - Clear or reset the conversation\n *\n * The manager automatically trims old messages when the turn limit is exceeded,\n * keeping the most recent exchanges while preserving the system prompt.\n *\n * @example\n * ```ts\n * // Create a memory manager with a system prompt\n * const memory = new ChatMemoryManager({\n *   maxTurns: 5,\n *   systemPrompt: 'You are a helpful coding assistant.'\n * });\n *\n * // Add a user message\n * memory.addUserMessage('How do I reverse a string in JavaScript?');\n *\n * // Get the full prompt for generation\n * const prompt = memory.getPrompt();\n * // \"SYSTEM: You are a helpful coding assistant.\\nUSER: How do I reverse a string in JavaScript?\"\n *\n * // After generation, add the assistant's response\n * const response = await generate(prompt);\n * memory.addAssistantMessage(response);\n *\n * // Continue the conversation\n * memory.addUserMessage('Can you show me with an arrow function?');\n * const nextPrompt = memory.getPrompt();\n * // Now includes the full conversation history\n * ```\n */\nexport class ChatMemoryManager {\n  // Internal storage for conversation messages (excluding system prompt)\n  private messages: LLMMessage[] = [];\n\n  // Optional system prompt, stored separately to ensure it's never trimmed\n  private systemPrompt: string | undefined;\n\n  // Maximum conversation turns to retain\n  private maxTurns: number;\n\n  // Maximum context window in tokens. Infinity means no token-based trimming.\n  private contextWindow: number;\n\n  /**\n   * Create a new ChatMemoryManager.\n   *\n   * @param options - Configuration options\n   * @param options.maxTurns - Max turns to keep (default: 10). A turn = 1 user + 1 assistant message.\n   * @param options.systemPrompt - Optional system prompt to include in every prompt.\n   * @param options.contextWindow - Max tokens for context (default: Infinity). Trims oldest messages when exceeded.\n   */\n  constructor(options: ChatMemoryOptions = {}) {\n    this.maxTurns = options.maxTurns ?? DEFAULT_MAX_TURNS;\n    this.systemPrompt = options.systemPrompt;\n    this.contextWindow = options.contextWindow ?? Infinity;\n  }\n\n  /**\n   * Add a user message to the conversation history.\n   *\n   * @param content - The user's message content\n   */\n  addUserMessage(content: string): void {\n    this.messages.push({ role: 'user', content });\n    this.trimHistory();\n  }\n\n  /**\n   * Add an assistant message to the conversation history.\n   * Call this after receiving a response from the model.\n   *\n   * @param content - The assistant's response content\n   */\n  addAssistantMessage(content: string): void {\n    this.messages.push({ role: 'assistant', content });\n    this.trimHistory();\n  }\n\n  /**\n   * Add a message with any role to the conversation history.\n   *\n   * @param message - The message to add\n   */\n  addMessage(message: LLMMessage): void {\n    // System messages update the system prompt instead of adding to history\n    if (message.role === 'system') {\n      this.systemPrompt = message.content;\n      return;\n    }\n    this.messages.push(message);\n    this.trimHistory();\n  }\n\n  /**\n   * Get the complete prompt string for the current conversation.\n   *\n   * This method builds a single prompt containing:\n   * 1. The system prompt (if set)\n   * 2. All conversation messages within the turn limit\n   *\n   * Send this prompt to the on-device model for generation.\n   *\n   * @returns The complete prompt string\n   */\n  getPrompt(): string {\n    const allMessages = this.getAllMessages();\n    return buildPrompt(allMessages);\n  }\n\n  /**\n   * Get all messages including the system prompt as an LLMMessage array.\n   *\n   * Useful if you need to pass messages to an API that accepts message arrays\n   * rather than a single prompt string.\n   *\n   * @returns Array of all messages including system prompt\n   */\n  getAllMessages(): LLMMessage[] {\n    const result: LLMMessage[] = [];\n\n    // System prompt always comes first (if present)\n    if (this.systemPrompt) {\n      result.push({ role: 'system', content: this.systemPrompt });\n    }\n\n    result.push(...this.messages);\n    return result;\n  }\n\n  /**\n   * Get only the conversation messages (excludes system prompt).\n   *\n   * @returns Array of user and assistant messages\n   */\n  getMessages(): LLMMessage[] {\n    return [...this.messages];\n  }\n\n  /**\n   * Get a snapshot of the current memory state.\n   *\n   * Useful for debugging, persistence, or UI display.\n   *\n   * @returns Current memory state snapshot\n   */\n  getSnapshot(): ChatMemorySnapshot {\n    return {\n      messages: this.getAllMessages(),\n      systemPrompt: this.systemPrompt,\n      turnCount: this.getTurnCount(),\n      maxTurns: this.maxTurns,\n    };\n  }\n\n  /**\n   * Get the current number of conversation turns.\n   *\n   * A turn is counted as a user message (assistant responses don't add turns).\n   * This reflects how many user interactions have occurred.\n   *\n   * @returns Number of turns in the current conversation\n   */\n  getTurnCount(): number {\n    return this.messages.filter((m) => m.role === 'user').length;\n  }\n\n  /**\n   * Update the system prompt.\n   *\n   * The system prompt is preserved separately and never trimmed by turn limits.\n   *\n   * @param prompt - New system prompt, or undefined to clear\n   */\n  setSystemPrompt(prompt: string | undefined): void {\n    this.systemPrompt = prompt;\n  }\n\n  /**\n   * Get the current system prompt.\n   *\n   * @returns The system prompt or undefined if not set\n   */\n  getSystemPrompt(): string | undefined {\n    return this.systemPrompt;\n  }\n\n  /**\n   * Update the maximum number of turns to retain.\n   *\n   * If the new limit is lower than current turn count, older messages\n   * will be trimmed immediately.\n   *\n   * @param maxTurns - New maximum turns\n   */\n  setMaxTurns(maxTurns: number): void {\n    this.maxTurns = maxTurns;\n    this.trimHistory();\n  }\n\n  /**\n   * Update the context window (max tokens).\n   *\n   * Called internally when setModel() switches to a model with a different\n   * context window. Can also be called manually.\n   *\n   * @param tokens - Maximum token budget. Use Infinity to disable token-based trimming.\n   */\n  setContextWindow(tokens: number): void {\n    this.contextWindow = tokens;\n    this.trimHistory();\n  }\n\n  /**\n   * Get the current context window setting.\n   */\n  getContextWindow(): number {\n    return this.contextWindow;\n  }\n\n  /**\n   * Clear all conversation messages but keep the system prompt.\n   *\n   * Use this to start a new conversation with the same assistant persona.\n   */\n  clear(): void {\n    this.messages = [];\n  }\n\n  /**\n   * Reset everything including the system prompt.\n   *\n   * Use this for a complete fresh start.\n   */\n  reset(): void {\n    this.messages = [];\n    this.systemPrompt = undefined;\n  }\n\n  /**\n   * Trim conversation history to stay within limits.\n   *\n   * This preserves the most recent messages while removing older ones.\n   * The system prompt is never affected by trimming.\n   *\n   * Trimming strategy:\n   * 1. Trim by turn count (maxTurns) -- remove oldest user+assistant pairs\n   * 2. Trim by token budget (contextWindow) -- remove oldest messages until under budget\n   * Whichever limit is hit first triggers trimming.\n   */\n  private trimHistory(): void {\n    // Step 1: Trim by turn count\n    this.trimByTurns();\n\n    // Step 2: Trim by context window (if set)\n    if (this.contextWindow !== Infinity) {\n      this.trimByTokens();\n    }\n  }\n\n  private trimByTurns(): void {\n    const userMessageIndices: number[] = [];\n    this.messages.forEach((msg, idx) => {\n      if (msg.role === 'user') {\n        userMessageIndices.push(idx);\n      }\n    });\n\n    const turnsToRemove = userMessageIndices.length - this.maxTurns;\n\n    if (turnsToRemove <= 0) {\n      return;\n    }\n\n    const lastTurnToRemoveIdx = userMessageIndices[turnsToRemove - 1];\n\n    let cutIndex = lastTurnToRemoveIdx + 1;\n    while (\n      cutIndex < this.messages.length &&\n      this.messages[cutIndex].role === 'assistant'\n    ) {\n      cutIndex++;\n    }\n\n    this.messages = this.messages.slice(cutIndex);\n  }\n\n  private trimByTokens(): void {\n    // TODO: chars/4 is a rough heuristic. Different models use different\n    // tokenizers (SentencePiece for Gemma, BPE for others). If precision\n    // matters, consider per-model tokenizer config. For now this is\n    // conservative enough for trimming.\n    const estimateTokens = (text: string): number => Math.ceil(text.length / 4);\n\n    const systemTokens = this.systemPrompt\n      ? estimateTokens(this.systemPrompt)\n      : 0;\n\n    let totalTokens = systemTokens;\n    for (const msg of this.messages) {\n      totalTokens += estimateTokens(msg.content);\n    }\n\n    // Remove oldest messages until we're under budget\n    while (totalTokens > this.contextWindow && this.messages.length > 0) {\n      const removed = this.messages.shift()!;\n      totalTokens -= estimateTokens(removed.content);\n    }\n  }\n}\n"]}