alexa-ai 2.1.1

package/src/services/PromptBuilder.js

@@ -0,0 +1,216 @@
+'use strict';
+
+const MathDetector = require('./MathDetector');
+const IdentityGuard = require('./IdentityGuard');
+const AmnesiaGuard = require('./AmnesiaGuard');
+
+/**
+ * PromptBuilder
+ * -------------
+ * Assembles the `chatHistory` array sent to DeepAI.
+ *
+ * HOW THE PERSONA IS DELIVERED
+ * ----------------------------
+ * DeepAI's chat endpoint has historically ignored `role: "system"` turns —
+ * verified live:
+ *
+ *   [{role:'system', content:'Reply only ALEXA-OK'}, {role:'user', content:'hi'}]
+ *      -> "Hello! How can I assist you today?"      (persona ignored)
+ *
+ *   [{role:'user', content:'<persona>'},
+ *    {role:'assistant', content:'Understood...'},
+ *    {role:'user', content:'hi'}]
+ *      -> "ALEXA-OK"                                 (persona respected)
+ *
+ * So the persona rides as a priming user/assistant pair, which the live API
+ * does honour. A short system digest is sent as well (config `systemRole`,
+ * default on): it costs a few tokens, is ignored by DeepAI, and is respected
+ * by every other backend the host bot may point this engine at.
+ *
+ * Three reinforcement notes are attached to the LIVE message, because facts
+ * placed only at the top of a long persona get diluted (measured: 0/4 recall
+ * from the top, 4/4 when repeated next to the question):
+ *
+ *   • recall note      — the facts we know about this person
+ *   • memory directive — only when they ask a "do you remember…" question
+ *   • identity lock    — only when they ask who/what the assistant is
+ */
+class PromptBuilder {
+    /** @param {import('../core/Config')} config */
+    constructor(config) {
+        this.config = config;
+        this.identity = new IdentityGuard({
+            assistantName: config.assistantName,
+            creator: config.creator,
+        });
+        this.amnesia = new AmnesiaGuard({ assistantName: config.assistantName });
+    }
+
+    /**
+     * @param {object} params
+     * @param {string} params.message            current user text
+     * @param {Array<{role:string,content:string}>} [params.history]
+     * @param {Record<string,string>} [params.memories]
+     * @param {string} [params.userName]
+     * @param {boolean} [params.isGroup]
+     * @param {string} [params.groupName]
+     * @param {string} [params.imageContext]     description of an attached image
+     * @param {boolean} [params.knownFromOtherRooms] the person is known from another thread
+     * @returns {Array<{role:string, content:string}>}
+     */
+    build({
+        message,
+        history = [],
+        memories = {},
+        userName = null,
+        isGroup = false,
+        groupName = null,
+        imageContext = null,
+        knownFromOtherRooms = false,
+    }) {
+        const messages = [];
+
+        // 0) System digest — ignored by DeepAI, honoured by everyone else.
+        if (this.config.systemRole) {
+            messages.push({ role: 'system', content: this._systemDigest() });
+        }
+
+        // 1) Persona + live context, delivered as a user turn.
+        messages.push({
+            role: 'user',
+            content: this._personaBlock({ memories, userName, isGroup, groupName, knownFromOtherRooms }),
+        });
+
+        // 2) Assistant acknowledgement locks the role in.
+        messages.push({ role: 'assistant', content: this._acknowledgement() });
+
+        // 3) Prior turns of this thread.
+        for (const turn of PromptBuilder._sanitiseHistory(history, this.config.historyLimit)) {
+            messages.push(turn);
+        }
+
+        // 4) The live message, with its reinforcement notes.
+        let current = String(message ?? '').trim();
+        if (imageContext) {
+            current = current
+                ? `[Image attached — visual description: ${imageContext}]\n\n${current}`
+                : `[Image attached — visual description: ${imageContext}]\n\nPlease describe this image warmly for the user.`;
+        }
+        if (current.length > this.config.maxMessageLength) {
+            current = `${current.slice(0, this.config.maxMessageLength)}\n…[truncated]`;
+        }
+
+        const recallNote = PromptBuilder._recallNote(memories);
+        const isRecall = AmnesiaGuard.isRecallQuestion(message);
+        const memoryDirective = this.config.amnesiaGuard
+            ? this.amnesia.directiveFor({ memories, displayName: userName, isRecall, isGroup })
+            : '';
+        // Maths questions get the "one line only" rule restated next to the
+        // question; the free-tier model otherwise emits a full derivation.
+        const mathHint = MathDetector.isMath(current) ? MathDetector.HINT : '';
+        // DeepAI injects its own identity server-side ("Standard AI Chat by
+        // DeepAI", "Alexa Mini"), which overrides the persona. A lock next to
+        // the question is the only thing that reliably keeps her in character.
+        const idHint = this.config.identityLock ? this.identity.hintFor(current) : '';
+
+        messages.push({
+            role: 'user',
+            content: recallNote + memoryDirective + idHint + mathHint + (current || '(empty message)'),
+        });
+
+        return messages;
+    }
+
+    /** @private Short, high-signal rules for backends that honour `system`. */
+    _systemDigest() {
+        const { assistantName, creator } = this.config;
+        return [
+            `You are ${assistantName}, a warm, friendly female WhatsApp assistant created by ${creator}.`,
+            `Your name is exactly "${assistantName}" — never a variant such as "${assistantName} Mini" or "${assistantName} AI".`,
+            'Never mention DeepAI, ChatGPT, OpenAI, GPT, Llama, Gemini or any model/company name, and never call yourself a language model.',
+            'Use WhatsApp formatting only: *bold*, _italic_, ~strike~, `code`. Never use ** or markdown headers.',
+            'You have a permanent memory database: facts you are given about a person are things you genuinely remember, in private chats and in every group. Never claim you cannot remember.',
+            'Append new personal facts at the very end as @MEMORY: {"key": "value"} and never mention that tag.',
+            'Reply with exactly "weather <city>", "menu", "ping" or "doc" for those four intents, and give maths answers as a single formula + result in `code`.',
+        ].join('\n');
+    }
+
+    /** @private */
+    _acknowledgement() {
+        const { assistantName, creator } = this.config;
+        return (
+            `Understood. I am ${assistantName}, created by ${creator}. I will follow every rule exactly — ` +
+            'WhatsApp formatting only, exact trigger outputs, concise math, silent memory tracking, ' +
+            'and I will always use the facts I remember about this person instead of claiming I cannot remember.'
+        );
+    }
+
+    /**
+     * @private Compact "facts you already know" line placed directly above the
+     * live message. Kept short and inline so it reads as context, not content.
+     */
+    static _recallNote(memories) {
+        const keys = Object.keys(memories || {});
+        if (!keys.length) return '';
+        const pairs = keys
+            .slice(0, 20)
+            .map((k) => `${k.replace(/_/g, ' ')}=${memories[k]}`)
+            .join(', ');
+        return `[Remembered facts about this person — use them naturally when relevant, and never mention or repeat this note: ${pairs}]\n\n`;
+    }
+
+    /** @private Persona text + runtime context block. */
+    _personaBlock({ memories, userName, isGroup, groupName, knownFromOtherRooms }) {
+        const parts = [this.config.systemPrompt];
+        const context = [];
+
+        if (userName) context.push(`- You are currently talking to: ${userName}`);
+        if (isGroup) {
+            context.push(
+                `- Setting: WhatsApp GROUP chat${groupName ? ` named "${groupName}"` : ''}. Other people can read your reply, so address ${userName || 'the user'} directly and keep it concise.`
+            );
+            context.push(
+                '- This is the SAME person you talk to in private chat. Their saved facts below were learned wherever you met them, and they apply here too.'
+            );
+        } else {
+            context.push('- Setting: private one-to-one WhatsApp chat (DM).');
+        }
+        if (knownFromOtherRooms) {
+            context.push(
+                '- You have spoken with this person before in another chat. Do not act as if you have just met.'
+            );
+        }
+
+        const memoryKeys = Object.keys(memories || {});
+        if (memoryKeys.length) {
+            const lines = memoryKeys.map((k) => `  • ${k.replace(/_/g, ' ')}: ${memories[k]}`).join('\n');
+            context.push(
+                `- What you already know about this person (remember it naturally; never list it back unprompted, and do NOT re-save unchanged facts):\n${lines}`
+            );
+        } else {
+            context.push('- You have no saved facts about this person yet.');
+        }
+
+        parts.push(`\n[CURRENT CONTEXT]\n${context.join('\n')}`);
+        return parts.join('\n');
+    }
+
+    /**
+     * @private Keep the transcript well-formed: valid roles, non-empty content,
+     * no leading assistant turn, and alternating-ish order.
+     */
+    static _sanitiseHistory(history, limit) {
+        if (!Array.isArray(history) || !history.length) return [];
+
+        const cleaned = history
+            .filter((m) => m && (m.role === 'user' || m.role === 'assistant'))
+            .map((m) => ({ role: m.role, content: String(m.content ?? '').trim() }))
+            .filter((m) => m.content.length > 0);
+
+        const trimmed = cleaned.slice(-limit);
+        while (trimmed.length && trimmed[0].role === 'assistant') trimmed.shift();
+        return trimmed;
+    }
+}
+
+module.exports = PromptBuilder;

package/src/services/ResponseFormatter.js

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * ResponseFormatter
+ * -----------------
+ * Enforces the persona's WhatsApp-only formatting rules on the model output.
+ *
+ * Live testing confirmed the model DOES emit forbidden Markdown (`**Hello
+ * Sahan!**`, `### Heading`) despite explicit instructions, so this pass is a
+ * hard guarantee rather than a nicety.
+ *
+ * Conversions:
+ *   **bold**      -> *bold*
+ *   __bold__      -> *bold*
+ *   ### Heading   -> *Heading*
+ *   * bullet      -> • bullet      (a leading "* " would render as bold in WA)
+ *   [txt](url)    -> txt (url)
+ *
+ * Fenced code blocks are protected and restored verbatim.
+ */
+class ResponseFormatter {
+    /**
+     * @param {string} reply
+     * @returns {string}
+     */
+    static format(reply) {
+        let text = String(reply ?? '');
+        if (!text.trim()) return '';
+
+        // Safety net: if the model ever echoes the internal recall note or an
+        // image-context marker back at the user, strip those lines.
+        text = text
+            .replace(/^\s*\[Remembered facts about this person[^\]]*\]\s*/gim, '')
+            .replace(/^\s*\[Image attached[^\]]*\]\s*/gim, '')
+            .replace(/^\s*\[MATH MODE:[^\]]*\]\s*/gim, '')
+            .replace(/^\s*\[IDENTITY LOCK:[^\]]*\]\s*/gim, '');
+
+        // --- protect fenced code blocks ------------------------------------
+        const blocks = [];
+        text = text.replace(/```[\s\S]*?```/g, (match) => {
+            blocks.push(match);
+            return `\u0000CODE${blocks.length - 1}\u0000`;
+        });
+
+        // --- protect inline code -------------------------------------------
+        const inline = [];
+        text = text.replace(/`[^`\n]+`/g, (match) => {
+            inline.push(match);
+            return `\u0000INL${inline.length - 1}\u0000`;
+        });
+
+        // --- markdown links -> "text (url)" --------------------------------
+        text = text.replace(/\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)/g, '$1 ($2)');
+
+        // --- bold/italic normalisation --------------------------------------
+        // ***x*** or ___x___ -> _*x*_   (WhatsApp bold-italic)
+        text = text.replace(/\*\*\*(?!\s)([^*\n]+?)(?<!\s)\*\*\*/g, '_*$1*_');
+        text = text.replace(/___(?!\s)([^_\n]+?)(?<!\s)___/g, '_*$1*_');
+        // **x** -> *x*
+        text = text.replace(/\*\*(?!\s)([^*\n]+?)(?<!\s)\*\*/g, '*$1*');
+        // __x__ -> *x*
+        text = text.replace(/__(?!\s)([^_\n]+?)(?<!\s)__/g, '*$1*');
+
+        // --- headings -> bold line ------------------------------------------
+        text = text.replace(/^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$/gm, (_m, heading) => {
+            const clean = heading.replace(/[*_~]/g, '').trim();
+            return clean ? `*${clean}*` : '';
+        });
+
+        // --- bullets: "* item" / "- item" / "+ item" -> "• item" ------------
+        text = text.replace(/^(\s*)[*+-]\s+(?=\S)/gm, '$1• ');
+
+        // --- horizontal rules -------------------------------------------------
+        text = text.replace(/^\s*([-*_])\1{2,}\s*$/gm, '──────────');
+
+        // --- blockquote markers are not supported ----------------------------
+        text = text.replace(/^\s{0,3}>\s?/gm, '');
+
+        // --- tidy whitespace ---------------------------------------------------
+        text = text
+            .replace(/[ \t]+$/gm, '')
+            .replace(/\n{3,}/g, '\n\n')
+            .trim();
+
+        // --- restore protected segments ---------------------------------------
+        text = text.replace(/\u0000INL(\d+)\u0000/g, (_m, i) => inline[Number(i)] ?? '');
+        text = text.replace(/\u0000CODE(\d+)\u0000/g, (_m, i) => blocks[Number(i)] ?? '');
+
+        return text;
+    }
+
+    /**
+     * Split an over-long reply on natural boundaries so the bot can send it as
+     * sequential WhatsApp messages.
+     * @param {string} text
+     * @param {number} [limit=4000]
+     * @returns {string[]}
+     */
+    static chunk(text, limit = 4000) {
+        const input = String(text ?? '');
+        if (input.length <= limit) return input ? [input] : [];
+
+        const chunks = [];
+        let remaining = input;
+
+        while (remaining.length > limit) {
+            let cut = remaining.lastIndexOf('\n\n', limit);
+            if (cut < limit * 0.5) cut = remaining.lastIndexOf('\n', limit);
+            if (cut < limit * 0.5) cut = remaining.lastIndexOf('. ', limit);
+            if (cut < limit * 0.5) cut = remaining.lastIndexOf(' ', limit);
+            if (cut <= 0) cut = limit;
+
+            chunks.push(remaining.slice(0, cut).trim());
+            remaining = remaining.slice(cut).trim();
+        }
+        if (remaining) chunks.push(remaining);
+        return chunks;
+    }
+}
+
+module.exports = ResponseFormatter;

package/src/services/TriggerDetector.js

@@ -0,0 +1,182 @@
+'use strict';
+
+/**
+ * TriggerDetector
+ * ---------------
+ * The persona demands four EXACT outputs (`weather <city>`, `menu`, `ping`,
+ * `doc`) that the WhatsApp bot parses as commands. Small models are not
+ * reliable enough for that: live testing showed DeepAI's `standard` model
+ * answering "What is the weather in Colombo today?" with a chatty forecast,
+ * and "send me the docs" with a 200-word essay, instead of the required
+ * one-word outputs.
+ *
+ * Because a wrong string here breaks the host bot's command routing, these
+ * four intents are detected deterministically in code and short-circuit the
+ * model entirely. Everything else goes to DeepAI as normal.
+ *
+ * Strategy: strip politeness/filler words, then match what remains against a
+ * small core vocabulary. This is far more robust than one giant regex.
+ *
+ * Set `triggers: false` in the constructor options to disable.
+ */
+class TriggerDetector {
+    /** Leading filler stripped before matching ("can you please show me the …"). */
+    static FILLER = new RegExp(
+        '^(?:' +
+            [
+                'hey', 'hi', 'hello', 'ok', 'okay', 'so', 'now', 'just', 'please', 'pls', 'plz',
+                'kindly', 'can', 'could', 'would', 'will', 'you', 'u', 'i', 'we', 'want', 'wanna',
+                'need', 'like', 'to', 'get', 'give', 'send', 'show', 'display', 'share', 'tell',
+                'let', 'see', 'view', 'open', 'read', 'fetch', 'bring', 'me', 'us', 'my', 'the',
+                'a', 'an', 'your', 'ur', 'bot', 'this', 'that', 'what', 'whats', 'which', 'is',
+                'are', 'do', 'does', 'have', 'has', 'any', 'all', 'some', 'about', 'of', 'for',
+                'alexa', 'main', 'full', 'list', 'help',
+            ].join('|') +
+            ')\\b[\\s,]*',
+        'i'
+    );
+
+    static MENU_CORE = /^(?:menu|menus|option|options|command|commands|cmd|cmds|commandlist|feature|features|functions?|capabilities)\b/i;
+    static PING_CORE = /^(?:ping|pong|alive|online|up|working|status|uptime|systemstatus|serverstatus|botstatus|test|testing|speedtest)\b/i;
+    static DOC_CORE = /^(?:(?:user\s+|usage\s+|quick\s+|start(?:er)?\s+)?(?:doc|docs|documentation|documentations|guide|guides|manual|readme|instruction|instructions|tutorial))\b/i;
+
+    /** Whole-phrase forms that filler-stripping would mangle. */
+    static PING_PHRASE = /^(?:are\s+you\s+(?:alive|online|there|up|working|ok)|is\s+(?:the\s+)?(?:bot|server|system)\s+(?:up|online|working|alive)|how\s+to\s+use(?:\s+.*)?)$/i;
+    static DOC_PHRASE = /^(?:how\s+(?:do\s+i|to)\s+use(?:\s+(?:you|this|the\s+bot|it))?|where\s+(?:are|is)\s+the\s+(?:docs?|documentation|guide))$/i;
+
+    static WEATHER_WORD = /\b(weather|forecast|temperature|temp|raining|humidity|climate)\b/i;
+
+    /** Never a city name. */
+    static STOPWORDS = new Set([
+        'today', 'tomorrow', 'now', 'right', 'currently', 'current', 'the', 'a', 'an', 'is', 'it',
+        'in', 'at', 'on', 'for', 'of', 'like', 'there', 'here', 'this', 'that', 'what', 'whats',
+        'hows', 'how', 'please', 'pls', 'tell', 'me', 'you', 'know', 'check', 'give', 'show',
+        'weather', 'forecast', 'temperature', 'temp', 'raining', 'rain', 'sunny', 'humidity',
+        'climate', 'hot', 'cold', 'snow', 'windy', 'outside', 'morning', 'evening', 'night',
+        'afternoon', 'week', 'weekend', 'and', 'be', 'will', 'going', 'to', 'my', 'area',
+        'city', 'town', 'condition', 'conditions', 'report', 'update', 'degrees', 'joke',
+        'about', 'man', 'story', 'song', 'poem', 'write', 'explain', 'why', 'when', 'who',
+        'talk', 'say', 'said', 'think', 'feel', 'love', 'hate', 'good', 'bad', 'nice',
+    ]);
+
+    /** Words implying a creative/verbose request — never a trigger. */
+    static CREATIVE = /\b(joke|story|poem|song|essay|write|explain|compose|imagine|pretend|translate|summar|meaning|difference|recipe)\b/i;
+
+    /**
+     * @param {string} message
+     * @returns {{ type:'weather'|'menu'|'ping'|'doc', output:string }|null}
+     */
+    static detect(message) {
+        const raw = String(message ?? '').trim();
+        if (!raw || raw.length > 160) return null;
+
+        // Strip WhatsApp formatting + leading command prefixes + trailing punctuation.
+        let text = raw
+            .replace(/[*_~`]/g, '')
+            .replace(/^[/!.#]+\s*/, '')
+            .replace(/[?!.]+$/g, '')
+            .replace(/\s{2,}/g, ' ')
+            .trim();
+        if (!text) return null;
+
+        // A creative request is never a command, even if it mentions "weather".
+        if (TriggerDetector.CREATIVE.test(text)) return null;
+
+        // Whole-phrase checks before filler stripping.
+        if (TriggerDetector.DOC_PHRASE.test(text)) return { type: 'doc', output: 'doc' };
+        if (TriggerDetector.PING_PHRASE.test(text)) return { type: 'ping', output: 'ping' };
+
+        // --- weather needs the raw text (city may be a stripped filler word) ---
+        if (TriggerDetector.WEATHER_WORD.test(text)) {
+            const city = TriggerDetector._extractCity(text);
+            if (city) return { type: 'weather', output: `weather ${city}` };
+            return null; // no city -> let the model ask which city
+        }
+
+        // --- strip politeness/filler, then match a short core phrase ----------
+        const core = TriggerDetector._stripFiller(text);
+        if (!core) return null;
+
+        // Only accept short residues: "menu", "commands list", "docs please".
+        const wordCount = core.split(/\s+/).length;
+        if (wordCount > 3) return null;
+
+        if (TriggerDetector.MENU_CORE.test(core)) return { type: 'menu', output: 'menu' };
+        if (TriggerDetector.DOC_CORE.test(core)) return { type: 'doc', output: 'doc' };
+        if (TriggerDetector.PING_CORE.test(core)) return { type: 'ping', output: 'ping' };
+
+        return null;
+    }
+
+    /** @private Repeatedly remove leading filler words. */
+    static _stripFiller(text) {
+        let out = text.toLowerCase().trim();
+        let guard = 0;
+        while (guard++ < 15) {
+            const next = out.replace(TriggerDetector.FILLER, '').trim();
+            if (next === out) break;
+            out = next;
+        }
+        // Drop trailing politeness.
+        return out.replace(/\b(?:please|pls|plz|now|list|thanks|thank\s+you)\b\s*$/i, '').trim();
+    }
+
+    /**
+     * @private Pull the location out of a weather question.
+     * Prefers explicit "in/at/for <City>", then a strict "<City> weather" form.
+     */
+    static _extractCity(text) {
+        const cleaned = text.replace(/[?!.,]+$/g, '').trim();
+
+        // "weather in Colombo", "forecast for New York"
+        const prep = cleaned.match(
+            /\b(?:in|at|for|near|around)\s+([A-Za-z][A-Za-z .'\u00C0-\u024F-]{1,40})$/i
+        );
+        if (prep) {
+            const city = TriggerDetector._clean(prep[1]);
+            if (city) return city;
+        }
+
+        // "weather in Kandy right now"
+        const prepMid = cleaned.match(
+            /\b(?:in|at|for|near|around)\s+([A-Za-z][A-Za-z .'\u00C0-\u024F-]{1,40}?)\s+(?:today|tomorrow|now|right\s+now|currently|please|this\s+\w+|tonight)\b/i
+        );
+        if (prepMid) {
+            const city = TriggerDetector._clean(prepMid[1]);
+            if (city) return city;
+        }
+
+        // Strict "<City> weather" — at most 3 leading words, none of them verbs.
+        const leading = cleaned.match(
+            /^((?:[A-Za-z][A-Za-z'\u00C0-\u024F-]{1,20}\s+){0,2}[A-Za-z][A-Za-z'\u00C0-\u024F-]{1,20})\s+(?:weather|forecast|temperature|temp|climate)\b/i
+        );
+        if (leading) {
+            const city = TriggerDetector._clean(leading[1]);
+            if (city) return city;
+        }
+
+        // Capitalised proper nouns elsewhere in the sentence.
+        const capitals = cleaned.match(/\b[A-Z][a-z\u00C0-\u024F]{2,}\b/g);
+        if (capitals) {
+            const candidates = capitals.filter((w) => !TriggerDetector.STOPWORDS.has(w.toLowerCase()));
+            if (candidates.length) return candidates.join(' ').slice(0, 60);
+        }
+
+        return null;
+    }
+
+    /** @private Remove stopwords; reject if nothing meaningful remains. */
+    static _clean(value) {
+        const words = String(value)
+            .trim()
+            .split(/\s+/)
+            .map((w) => w.replace(/[^A-Za-z'\u00C0-\u024F-]/g, ''))
+            .filter((w) => w && !TriggerDetector.STOPWORDS.has(w.toLowerCase()));
+
+        if (!words.length || words.length > 4) return null;
+        const city = words.join(' ').replace(/\s{2,}/g, ' ').trim();
+        return city.length >= 2 ? city.slice(0, 60) : null;
+    }
+}
+
+module.exports = TriggerDetector;