myavana-bot-test-core 2.2.0 → 2.3.0

package/src/agentMemory.js

@@ -0,0 +1,122 @@
+// agentMemory.js
+// Local Agent Memory (LAM) — a self-hosted, TAM-inspired long-term memory layer
+// built entirely on this Postgres instance (pgvector), so retrieval never leaves
+// the existing AWS/GCP infra. Extraction follows the same LLM-structured-extraction
+// pattern already used by postProcessConversation/classifyAndSavePersona.
+const ai = require('./ai');
+const { googleAI } = require('@genkit-ai/google-genai');
+const { pgClient } = require('./database');
+
+const EMBEDDER = googleAI.embedder('gemini-embedding-001'); // 768-dim output, matches agent_memories.embedding
+const DUPLICATE_DISTANCE_THRESHOLD = 0.15; // cosine distance below this = treat as the same memory
+
+async function embedText(text) {
+    const [{ embedding }] = await ai.embed({ embedder: EMBEDDER, content: text });
+    return `[${embedding.join(',')}]`;
+}
+
+const extractionPrompt = (chatHistory, latestMessage) => `
+You are extracting durable, long-term memory facts about a hair-care customer from a conversation, for future personalization.
+
+Only extract facts likely still true weeks or months from now (hair type/texture, product preferences or dislikes, allergies/sensitivities, long-term goals, established routines). Do NOT extract one-off statements, small talk, or anything already obviously covered by a generic hair-care questionnaire answer.
+
+Conversation history:
+${JSON.stringify(chatHistory)}
+
+User's latest message:
+"${latestMessage}"
+
+Return a JSON array (0 to 3 items) of objects: { "content": string, "memory_type": "fact" | "preference" | "episodic", "importance_score": number between 0 and 1 }. Return an empty array if nothing durable was mentioned.
+`;
+
+/**
+ * Extracts durable facts/preferences from the latest turn and stores them,
+ * deduping against the user's existing memories by embedding similarity.
+ * Non-blocking, best-effort — call from the async post-processing step.
+ *
+ * @param {string} userId
+ * @param {string} conversationId
+ * @param {Array<{role:string, content:string}>} chatHistory
+ */
+const extractAndStoreMemories = async (userId, conversationId, chatHistory) => {
+    try {
+        const latestUserTurn = [...chatHistory].reverse().find(m => m.role === 'user');
+        if (!latestUserTurn?.content) return;
+
+        const chat = ai.chat({
+            model: googleAI.model('gemini-3.6-flash'),
+            config: { temperature: 0.3 },
+        });
+        const { output } = await chat.send(extractionPrompt(chatHistory, latestUserTurn.content));
+
+        const candidates = Array.isArray(output) ? output : [];
+        for (const candidate of candidates) {
+            if (!candidate?.content) continue;
+            await upsertMemory(userId, conversationId, candidate);
+        }
+    } catch (err) {
+        console.error('Error extracting agent memories:', err);
+    }
+};
+
+async function upsertMemory(userId, conversationId, candidate) {
+    const vectorLiteral = await embedText(candidate.content);
+
+    const existing = await pgClient.query(
+        `SELECT id, embedding <=> $2::vector AS distance
+         FROM agent_memories
+         WHERE user_id = $1
+         ORDER BY embedding <=> $2::vector
+         LIMIT 1`,
+        [userId, vectorLiteral]
+    );
+
+    if (existing.rows.length > 0 && existing.rows[0].distance < DUPLICATE_DISTANCE_THRESHOLD) {
+        await pgClient.query(
+            `UPDATE agent_memories SET last_accessed_at = NOW(), access_count = access_count + 1 WHERE id = $1`,
+            [existing.rows[0].id]
+        );
+        return;
+    }
+
+    await pgClient.query(
+        `INSERT INTO agent_memories (user_id, memory_type, content, embedding, importance_score, source_conversation_id)
+         VALUES ($1, $2, $3, $4::vector, $5, $6)`,
+        [
+            userId,
+            candidate.memory_type || 'fact',
+            candidate.content,
+            vectorLiteral,
+            typeof candidate.importance_score === 'number' ? candidate.importance_score : 0.5,
+            conversationId,
+        ]
+    );
+}
+
+/**
+ * Retrieves the k memories most semantically relevant to queryText for this user.
+ *
+ * @param {string} userId
+ * @param {string} queryText - typically the current user message
+ * @param {number} [k=5]
+ * @returns {Promise<string[]>}
+ */
+const retrieveRelevantMemories = async (userId, queryText, k = 5) => {
+    if (!queryText) return [];
+    try {
+        const vectorLiteral = await embedText(queryText);
+        const res = await pgClient.query(
+            `SELECT content FROM agent_memories WHERE user_id = $1 ORDER BY embedding <=> $2::vector LIMIT $3`,
+            [userId, vectorLiteral, k]
+        );
+        return res.rows.map(row => row.content);
+    } catch (err) {
+        console.error('Error retrieving agent memories:', err);
+        return [];
+    }
+};
+
+module.exports = {
+    extractAndStoreMemories,
+    retrieveRelevantMemories,
+};

package/src/agentTools.js

@@ -0,0 +1,236 @@
+// agentTools.js
+// Defines Genkit tools that the AI can call during conversations.
+//
+// Two categories:
+//   Global tools  — stateless DB lookups, registered once at module load.
+//   Dynamic tools — user-scoped actions (saveHairGoal, getUserHairProfile)
+//                   created per-request so userId is bound in the closure,
+//                   not supplied by the model (avoids hallucination risk).
+//
+// Usage in index.js:
+//   const { globalTools, createUserTools } = require('...agentTools');
+//   const tools = [...globalTools, ...createUserTools(userId)];
+//   session.chat({ ..., tools });
+
+const { z } = require('zod');
+const ai = require('./ai');
+const { pgClient } = require('./database');
+
+// ---------------------------------------------------------------------------
+// Global tools (no user context — safe to register once)
+// ---------------------------------------------------------------------------
+
+/**
+ * Search Myavana services and partner products by keyword.
+ * ILIKE match against name, description, and category columns.
+ * Partner products are stored in a separate table once available.
+ */
+const searchServices = ai.defineTool(
+    {
+        name: 'searchServices',
+        description:
+            'Search Myavana services and partner products by keyword, hair concern, or category. ' +
+            'Call this when the user asks what services Myavana offers, asks for product or service recommendations, ' +
+            'or mentions a specific concern (e.g. "moisture", "curl analysis", "damage repair", "membership"). ' +
+            'Returns matching service/product names, descriptions, and any pricing or URL info available.',
+        inputSchema: z.object({
+            query: z.string().describe(
+                'Search keyword — hair concern, service type, or product name ' +
+                '(e.g. "moisture treatment", "analysis", "subscription")'
+            ),
+            limit: z.number().int().min(1).max(10).optional().describe(
+                'Max number of results to return (default 5)'
+            ),
+        }),
+        outputSchema: z.array(z.record(z.unknown())),
+    },
+    async ({ query, limit = 5 }) => {
+        const pattern = `%${query}%`;
+        try {
+            // Search Myavana services
+            const servicesResult = await pgClient.query(
+                `SELECT * FROM products
+                 WHERE product_name ILIKE $1
+                    OR description   ILIKE $1
+                    OR category      ILIKE $1
+                 LIMIT $2`,
+                [pattern, limit]
+            );
+
+            // Search partner products if table exists
+            let partnerRows = [];
+            try {
+                const partnerResult = await pgClient.query(
+                    `SELECT *, 'partner' AS source FROM partner_products
+                     WHERE product_name ILIKE $1
+                        OR description  ILIKE $1
+                        OR brand_name   ILIKE $1
+                     LIMIT $2`,
+                    [pattern, limit]
+                );
+                partnerRows = partnerResult.rows;
+            } catch {
+                // partner_products table doesn't exist yet — skip silently
+            }
+
+            const combined = [...servicesResult.rows, ...partnerRows].slice(0, limit);
+            return combined.length > 0
+                ? combined
+                : [{ message: `No services or products found matching "${query}".` }];
+        } catch (err) {
+            console.error('searchServices tool error:', err.message);
+            return [{ error: 'Service search temporarily unavailable.' }];
+        }
+    }
+);
+
+/**
+ * Search FAQs by keyword.
+ * ILIKE match against both question and answer text so the AI can ground
+ * brand-specific factual answers rather than guessing.
+ */
+const lookupFAQ = ai.defineTool(
+    {
+        name: 'lookupFAQ',
+        description:
+            'Look up Myavana FAQ entries by keyword. ' +
+            'Call this when the user asks a factual question about Myavana (pricing, policies, how something works, ' +
+            'shipping, cancellations, what is included in a service) where you want to ground your answer in ' +
+            'official content rather than inference.',
+        inputSchema: z.object({
+            query: z.string().describe(
+                'The topic or question to search for in FAQs (e.g. "cancel subscription", "how does analysis work")'
+            ),
+            limit: z.number().int().min(1).max(5).optional().describe(
+                'Max results to return (default 3)'
+            ),
+        }),
+        outputSchema: z.array(z.object({
+            question: z.string().optional(),
+            answer:   z.string().optional(),
+        }).passthrough()),
+    },
+    async ({ query, limit = 3 }) => {
+        const pattern = `%${query}%`;
+        try {
+            const result = await pgClient.query(
+                `SELECT * FROM faqs
+                 WHERE question ILIKE $1 OR answer ILIKE $1
+                 LIMIT $2`,
+                [pattern, limit]
+            );
+            return result.rows.length > 0
+                ? result.rows
+                : [{ question: query, answer: `No FAQ found for "${query}". Answer based on your knowledge.` }];
+        } catch (err) {
+            console.error('lookupFAQ tool error:', err.message);
+            return [{ error: 'FAQ lookup temporarily unavailable.' }];
+        }
+    }
+);
+
+// ---------------------------------------------------------------------------
+// Dynamic tools (per-request, userId bound in closure)
+// ---------------------------------------------------------------------------
+
+/**
+ * Factory — call once per request to get user-scoped tools.
+ * @param {string} userId
+ * @returns {import('genkit').ToolAction[]}
+ */
+function createUserTools(userId) {
+    /**
+     * Save a hair goal the user has explicitly stated.
+     * Appended to user_preferences.hair_priorities JSONB so it persists across sessions.
+     */
+    const saveHairGoal = ai.dynamicTool(
+        {
+            name: 'saveHairGoal',
+            description:
+                'Save a specific hair goal the user has clearly stated they want to achieve. ' +
+                'Call this when the user explicitly says something like "my goal is...", "I want to...", ' +
+                '"I\'m trying to...", or "I\'d love to achieve...". ' +
+                'Do NOT call this for vague preferences — only concrete, stated goals. ' +
+                'Confirm to the user that their goal has been saved.',
+            inputSchema: z.object({
+                goal: z.string().describe(
+                    'The specific hair goal stated by the user, in their own words ' +
+                    '(e.g. "grow hair 4 inches by December", "retain moisture without frizz", "transition to natural")'
+                ),
+            }),
+            outputSchema: z.object({ saved: z.boolean(), goal: z.string() }),
+        },
+        async ({ goal }) => {
+            try {
+                await pgClient.query(
+                    `INSERT INTO user_preferences (user_id, hair_priorities)
+                     VALUES ($1, $2::jsonb)
+                     ON CONFLICT (user_id) DO UPDATE SET
+                       hair_priorities = COALESCE(user_preferences.hair_priorities, '{}') || $2::jsonb`,
+                    [
+                        userId,
+                        JSON.stringify({
+                            goals: goal,
+                            savedAt: new Date().toISOString(),
+                        }),
+                    ]
+                );
+                console.log(`🎯 Hair goal saved for ${userId}: ${goal}`);
+                return { saved: true, goal };
+            } catch (err) {
+                console.error('saveHairGoal tool error:', err.message);
+                return { saved: false, goal };
+            }
+        }
+    );
+
+    /**
+     * Fetch the user's current hair profile from the DB.
+     * Useful mid-conversation when the cached system prompt may be stale (>24h old)
+     * and the user's hair type or concerns have been updated since.
+     */
+    const getUserHairProfile = ai.dynamicTool(
+        {
+            name: 'getUserHairProfile',
+            description:
+                'Retrieve the current hair profile on file for this user: hair type, texture, concerns, goals, ' +
+                'porosity, and other stored attributes. ' +
+                'Call this when you need to personalize a recommendation but are unsure whether your context ' +
+                'has the most up-to-date profile, or when the user references a characteristic you don\'t have.',
+            inputSchema: z.object({}),
+            outputSchema: z.record(z.unknown()),
+        },
+        async () => {
+            try {
+                const result = await pgClient.query(
+                    `SELECT hair_type, hair_concerns, hair_texture, porosity, elasticity, density,
+                            curl_pattern, hair_goals, hair_concerns, damage_level_self_reported,
+                            confidence_level_inferred, experimenting_interest
+                     FROM users WHERE user_id = $1`,
+                    [userId]
+                );
+                if (result.rows.length === 0) {
+                    return { message: 'No hair profile on file yet for this user.' };
+                }
+                // Strip null fields to keep context concise
+                const profile = Object.fromEntries(
+                    Object.entries(result.rows[0]).filter(([, v]) => v !== null && v !== undefined)
+                );
+                return Object.keys(profile).length > 0
+                    ? profile
+                    : { message: 'Hair profile exists but no attributes recorded yet.' };
+            } catch (err) {
+                console.error('getUserHairProfile tool error:', err.message);
+                return { error: 'Hair profile temporarily unavailable.' };
+            }
+        }
+    );
+
+    return [saveHairGoal, getUserHairProfile];
+}
+
+// ---------------------------------------------------------------------------
+
+const globalTools = [searchServices, lookupFAQ];
+
+module.exports = { globalTools, createUserTools };

package/src/ai.js

@@ -8,7 +8,7 @@ const ai = genkit({
     plugins: [googleAI({
         apiKey: config.genkitApiKey,
     })],
-    model: googleAI.model('gemini-3-flash-preview'),
+    model: googleAI.model('gemini-3.7-flash'),
 });
 
 module.exports = ai;

package/src/cacheManager.js

@@ -28,7 +28,11 @@ class CacheManager {
     }
 
     /**
-     * Check cache validity across all storage layers
+     * Fast check for a valid Gemini cache across all storage layers (PG → Redis → memory).
+     * Call this before constructPrompt() — if hasValidCache is true, skip prompt construction.
+     *
+     * @param {string} userId
+     * @returns {Promise<{hasValidCache, cacheName, needsRefresh, reason, source}>}
      */
     async checkCacheValidity(userId) {
         console.log('🔍 Quick cache check for user:', userId);
@@ -112,7 +116,13 @@ class CacheManager {
     }
 
     /**
-     * Get or create cache
+     * Returns the existing valid Gemini cache name for this user, or creates a new one
+     * from the provided system prompt string. Saves to all available storage layers.
+     *
+     * @param {string} userId
+     * @param {string} systemPrompt - Full system instruction text to cache
+     * @returns {Promise<{cacheName: string|null, isNewCache: boolean, error?: string}>}
+     *   cacheName is null if cache creation failed — caller should fall back to sending full prompt
      */
     async getOrCreateCache(userId, systemPrompt) {
         console.log('🔍 ===== CACHE MANAGER: GET OR CREATE =====');
@@ -138,7 +148,7 @@ class CacheManager {
             // Create new cache
             console.log('🆕 Creating new Gemini cache...');
             const cacheStartTime = performance.now();
-            const modelName = "gemini-3-flash-preview";
+            const modelName = "gemini-3.7-flash";
             
             const cache = await cacheAi.caches.create({
                 model: modelName,
@@ -314,10 +324,10 @@ class CacheManager {
         
         try {
             const key = `gemini_cache:${userId}`;
-            await redisClient.setex(
-                key, 
-                this.CACHE_TTL_SECONDS, 
-                JSON.stringify(cacheData)
+            await redisClient.set(
+                key,
+                JSON.stringify(cacheData),
+                { EX: this.CACHE_TTL_SECONDS }
             );
             console.log('✅ Redis save successful');
             return true;

package/src/config.js

@@ -27,7 +27,7 @@ module.exports = {
     },
     genkitApiKey: process.env.GENKIT_API_KEY,
     openaiApiKey: process.env.OPENAI_API_KEY,
-    defaultModel: 'gemini15Flash',
-    experimentalModel: 'gemini20FlashExp',
+    defaultModel: 'gemini-3.7-flash',
+    experimentalModel: 'gemini-3.7-flash',
     temperature: 1.1,
 };

package/src/conversation.js

@@ -28,7 +28,7 @@ const generateConversationSummary = async (chatHistory) => {
     }
     const summaryPrompt = `Summarize the following conversation, getting all important information, especially the user's hair details, name, and location: ${JSON.stringify(chatHistory)}`;
     const { text } = await ai.chat({
-        model: googleAI.model('gemini-2.5-flash'),
+        model: googleAI.model('gemini-3.6-flash'),
         system: summaryPrompt,
     });
     return text;

package/src/conversationDriver.js

@@ -0,0 +1,230 @@
+// conversationDriver.js
+// Analyzes conversation state and generates per-message behavioral directives
+// that guide how the AI should engage — not just what to say, but what to DO.
+//
+// Injected as a small context block via buildMessageContext(), alongside
+// the persona block from personaClassifier.
+//
+// The goal: make the AI a conversation driver, not just a responder.
+
+// ---------------------------------------------------------------------------
+// Stage definitions — mirrors the 8-stage framework in system.js
+// ---------------------------------------------------------------------------
+
+const STAGES = {
+    1: { name: 'something-new',     label: 'Something New' },
+    2: { name: 'rocking-this',      label: 'Rocking This' },
+    3: { name: 'experimenting',     label: 'Experimenting' },
+    4: { name: 'boredom',           label: 'Boredom' },
+    5: { name: 'desperation',       label: 'Desperation' },
+    6: { name: 'damage-protection', label: 'Damage/Protection' },
+    7: { name: 'repair-decision',   label: 'Repair/Decision' },
+    8: { name: 'hair-nirvana',      label: 'Hair Nirvana' },
+};
+
+// Keywords used to infer stage from recent messages (subset of system.js table)
+const STAGE_KEYWORDS = [
+    { stage: 8, words: ['nirvana', 'love my routine', 'healthy and happy', 'low maintenance', 'carefree', 'content', 'maintaining my hair'] },
+    { stage: 7, words: ['repairing', 'restoring', 'healing', 'new direction', 'making progress', 'growing out'] },
+    { stage: 6, words: ['damage', 'heat damage', 'protective style', 'split ends', 'overprocessed', 'breakage', 'weak hair'] },
+    { stage: 5, words: ['desperate', 'overwhelmed', 'hate my hair', "don't know what to do", 'frustrated', 'give up', 'stressed', 'hopeless'] },
+    { stage: 4, words: ['bored', 'need a change', 'stale', 'want something different', 'tired of my hair', 'ready for something new'] },
+    { stage: 3, words: ['experimenting', 'trying new things', 'curious about', 'exploring', 'want to try', 'different styles'] },
+    { stage: 2, words: ['love my hair', 'happy with it', 'feeling good', "i'm rocking", 'in my element', 'confident'] },
+    { stage: 1, words: ['big chop', 'new color', 'first time', 'starting over', 'fresh start', 'just cut my hair', 'new style'] },
+];
+
+// ---------------------------------------------------------------------------
+// Analysis helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Infer the most likely stage from recent user messages.
+ * Scans last 4 user messages — recent context is more reliable than old.
+ * Returns the highest-priority (lowest number wins ties) matched stage, or null.
+ *
+ * @param {Array<{role:string, content:string}>} chatHistory
+ * @returns {number|null}
+ */
+function inferStage(chatHistory) {
+    const recentUserMessages = chatHistory
+        .filter(m => m.role === 'user')
+        .slice(-4)
+        .map(m => (m.content || '').toLowerCase());
+
+    const combined = recentUserMessages.join(' ');
+    if (!combined) return null;
+
+    for (const { stage, words } of STAGE_KEYWORDS) {
+        if (words.some(w => combined.includes(w))) return stage;
+    }
+    return null;
+}
+
+/**
+ * Count how many of the last N AI turns ended with a question.
+ * Rough but effective: any turn containing '?' is considered a question turn.
+ *
+ * @param {Array<{role:string, content:string}>} chatHistory
+ * @param {number} lookback  How many recent AI turns to check (default 3)
+ * @returns {{ total: number, withQuestion: number, lastTurnHadQuestion: boolean }}
+ */
+function analyzeAIQuestions(chatHistory, lookback = 3) {
+    const aiTurns = chatHistory
+        .filter(m => m.role === 'model' || m.role === 'assistant')
+        .slice(-lookback);
+
+    const withQuestion = aiTurns.filter(m => (m.content || '').includes('?')).length;
+    const lastTurnHadQuestion = aiTurns.length > 0
+        ? (aiTurns[aiTurns.length - 1].content || '').includes('?')
+        : false;
+
+    return { total: aiTurns.length, withQuestion, lastTurnHadQuestion };
+}
+
+/**
+ * Returns rough conversation depth category.
+ *
+ * @param {Array} chatHistory
+ * @returns {'opening'|'exploring'|'deepening'|'action-ready'}
+ */
+function getDepthCategory(chatHistory) {
+    const userTurns = chatHistory.filter(m => m.role === 'user').length;
+    if (userTurns <= 1)  return 'opening';
+    if (userTurns <= 3)  return 'exploring';
+    if (userTurns <= 7)  return 'deepening';
+    return 'action-ready';
+}
+
+// ---------------------------------------------------------------------------
+// Directive builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Generates a short behavioral directive string based on conversation state.
+ * Returns empty string when the conversation needs no additional steering.
+ *
+ * @param {object}      opts
+ * @param {number|null} opts.stage          - Inferred stage number (1–8) or null
+ * @param {string}      opts.depth          - 'opening'|'exploring'|'deepening'|'action-ready'
+ * @param {object}      opts.questionStats  - From analyzeAIQuestions()
+ * @param {string|null} opts.personaType    - From personaClassifier (optional)
+ * @param {string|null} opts.trendSummary   - Short trend names string from trendManager (optional)
+ * @returns {string}
+ */
+function buildDrivingDirective({ stage, depth, questionStats, personaType, trendSummary = null }) {
+    const parts = [];
+
+    // Opening: always gather profile info if we don't have a stage read yet
+    if (depth === 'opening' && stage === null) {
+        parts.push('ask one open question to understand their hair type or primary concern — do not assume');
+    }
+
+    // Exploring: AI should be asking questions to understand, not just informing
+    else if (depth === 'exploring') {
+        if (!questionStats.lastTurnHadQuestion) {
+            parts.push('end your response with a specific follow-up question to learn more about their routine or goals');
+        }
+        if (stage !== null) {
+            parts.push(`stage context: ${STAGES[stage]?.label} — tailor your depth and tone accordingly`);
+        }
+    }
+
+    // Deepening: AI has enough info — guide toward insight or next step
+    else if (depth === 'deepening') {
+        if (questionStats.withQuestion === 0) {
+            // Stagnating — use a trend as a new angle if available
+            if (trendSummary) {
+                parts.push(`conversation needs new momentum — introduce a trending topic (${trendSummary}) as a natural next angle`);
+            } else {
+                parts.push('the conversation needs forward momentum — ask something that surfaces a new dimension (routine, history, environment, goals)');
+            }
+        } else if (stage === 3 && trendSummary) {
+            // Experimenting + trend: give them concrete options to try
+            parts.push(`user is experimenting — reference a trending technique (${trendSummary}) as one option worth exploring`);
+        } else if (stage === 4 && trendSummary) {
+            // Boredom + trend: use trend as the inspiration for change
+            parts.push(`user is bored — use a current trend (${trendSummary}) as inspiration to spark excitement about a change`);
+        } else if (stage !== null && stage >= 5 && stage <= 7) {
+            // High-need stages — gently surface Myavana solutions
+            parts.push('user is in a high-need phase — after addressing their question, briefly introduce a relevant Myavana service as a natural next step (do not push)');
+        }
+    }
+
+    // Action-ready: longer conversation — move toward a decision or commitment
+    else if (depth === 'action-ready') {
+        if (stage !== null && stage >= 5 && stage <= 7) {
+            if (trendSummary) {
+                parts.push(`well-developed conversation — guide toward a concrete action; a trending approach (${trendSummary}) could be the bridge to a Myavana service`);
+            } else {
+                parts.push('this is a well-developed conversation — guide the user toward a concrete action: a Myavana service, a specific routine step, or a commitment to try something');
+            }
+        } else if (stage === 8) {
+            parts.push('user is thriving — celebrate their progress and offer maintenance tips; keep the energy positive and light');
+        } else if (trendSummary) {
+            parts.push(`offer a specific personalized recommendation; consider whether a trending technique (${trendSummary}) is relevant to their situation`);
+        } else {
+            parts.push('this conversation is deep enough to offer a specific personalized recommendation; do not stay generic');
+        }
+    }
+
+    // Cross-cutting: overwhelmed users should not be pushed toward action too soon
+    if (personaType === 'overwhelmed' && parts.some(p => p.includes('action') || p.includes('service') || p.includes('trending'))) {
+        const idx = parts.findIndex(p => p.includes('action') || p.includes('service') || p.includes('trending'));
+        if (idx !== -1) {
+            parts[idx] = 'when the moment feels right, gently surface one option — but lead with empathy first';
+        }
+    }
+
+    if (parts.length === 0) return '';
+    return `[Conversation driver: ${parts.join('; ')}]\n`;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Analyses chat history and returns a driving directive string to inject
+ * into the message context. Returns empty string when nothing needed.
+ *
+ * @param {Array<{role:string, content:string}>} chatHistory
+ * @param {string|null} personaType   - From personaClassifier (optional)
+ * @param {string|null} trendSummary  - Trend names from trendManager (optional)
+ * @returns {string}
+ */
+function getConversationDirective(chatHistory, personaType = null, trendSummary = null) {
+    if (!chatHistory || chatHistory.length === 0) {
+        return '[Conversation driver: this is the very first message — warmly open with a question about their hair type or what brings them in today]\n';
+    }
+
+    const stage         = inferStage(chatHistory);
+    const depth         = getDepthCategory(chatHistory);
+    const questionStats = analyzeAIQuestions(chatHistory);
+
+    return buildDrivingDirective({ stage, depth, questionStats, personaType, trendSummary });
+}
+
+/**
+ * Convenience — extracts just the trend summary string from a trend context block.
+ * e.g. "[Trending in hair care: scalp detoxing; rice water]\n" → "scalp detoxing; rice water"
+ *
+ * @param {string} trendContext  - Full trend block from trendManager.getTrendContext()
+ * @returns {string|null}
+ */
+function extractTrendSummary(trendContext) {
+    if (!trendContext) return null;
+    const match = trendContext.match(/\[Trending in hair care: (.+?)\]/);
+    return match ? match[1] : null;
+}
+
+module.exports = {
+    getConversationDirective,
+    extractTrendSummary,
+    // Exported for testing
+    inferStage,
+    analyzeAIQuestions,
+    getDepthCategory,
+    buildDrivingDirective,
+    STAGES,
+};