alexa-ai 2.1.1

package/src/core/Endpoints.js

@@ -0,0 +1,74 @@
+'use strict';
+
+/**
+ * Endpoints
+ * ---------
+ * Every DeepAI route the engine knows how to talk to.
+ *
+ * These were taken from the live deepai.org chat client, so the engine speaks
+ * the *whole* API instead of only POSTing to the generative endpoint:
+ *
+ *   POST /hacking_is_a_serious_crime      chat completion (streamed text)
+ *   GET  /check_chat_task_status          poll a background task (thinking, memory refresh)
+ *   GET  /check-sensitivity               per-request sensitivity score
+ *   POST /chat_attachments/upload         upload an image/document
+ *   GET  /chat_attachments/get            attachment + server-side extraction status
+ *   POST /save_chat_session               persist a transcript server-side
+ *   GET  /get_chat_session                load a transcript
+ *   POST /delete_chat_session             delete one transcript
+ *   POST /rename_chat_session             rename one transcript
+ *   POST /delete_all_chat_history         nuke every transcript
+ *   GET/POST /chat_memory                 DeepAI's own long-term memory profile
+ *   GET/POST /chat_sandbox                agent-mode ("sandbox") toggle
+ *   GET/POST /chat_concierge              concierge/background-task toggle
+ *   POST /report_character                abuse report
+ *   POST /api/<name>                      the classic public API family
+ *                                         (text2img, image-editor, torch-srgan,
+ *                                          colorizer, nsfw-detector, …)
+ *
+ * All of them are overridable through `new AlexaAI({ endpoints: {...} })` so a
+ * future DeepAI rename never requires a code change.
+ */
+const ENDPOINTS = {
+    chat: '/hacking_is_a_serious_crime',
+    taskStatus: '/check_chat_task_status',
+    sensitivity: '/check-sensitivity',
+    attachmentUpload: '/chat_attachments/upload',
+    attachmentGet: '/chat_attachments/get',
+    saveSession: '/save_chat_session',
+    getSession: '/get_chat_session',
+    deleteSession: '/delete_chat_session',
+    renameSession: '/rename_chat_session',
+    deleteAllSessions: '/delete_all_chat_history',
+    memory: '/chat_memory',
+    sandbox: '/chat_sandbox',
+    concierge: '/chat_concierge',
+    reportCharacter: '/report_character',
+    api: '/api',
+};
+
+/**
+ * Public "standard API" operations. `AlexaAI.deepai.runApi(name, fields)` can
+ * call any of them; the named helpers below just document the common ones.
+ */
+const STANDARD_APIS = {
+    text2img: 'text2img',
+    imageEditor: 'image-editor',
+    superResolution: 'torch-srgan',
+    waifu2x: 'waifu2x',
+    colorizer: 'colorizer',
+    nsfwDetector: 'nsfw-detector',
+    imageSimilarity: 'image-similarity',
+    textTagging: 'text-tagging',
+    summarization: 'summarization',
+    sentiment: 'sentiment-analysis',
+    textGenerator: 'text-generator',
+};
+
+/** Task types accepted by `/check_chat_task_status?type=…`. */
+const TASK_TYPES = {
+    thinking: 'thinking-task',
+    memoryRefresh: 'memory-refresh-task',
+};
+
+module.exports = { ENDPOINTS, STANDARD_APIS, TASK_TYPES };

package/src/core/Persona.js

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * The Alexa persona.
+ *
+ * NOTE ON DELIVERY: DeepAI's chat endpoint has historically ignored
+ * `role: "system"` messages, so PromptBuilder delivers this text BOTH as a
+ * system turn (harmless, and honoured by every other backend) AND as a priming
+ * user/assistant pair, which the live API does respect. See PromptBuilder.
+ *
+ * `build({assistantName, creator})` lets a host bot rename the persona without
+ * copy-pasting the whole prompt; `module.exports` stays the default string so
+ * `require('./SystemPrompt')` keeps working.
+ */
+function build({ assistantName = 'Alexa', creator = 'Hansaka' } = {}) {
+    const name = String(assistantName || 'Alexa').trim() || 'Alexa';
+    const maker = String(creator || 'Hansaka').trim() || 'Hansaka';
+
+    return `You are ${name}, an intelligent, warm, and friendly female WhatsApp AI assistant created by ${maker}.
+
+[CORE IDENTITY & PERSONA]
+- Name: ${name}
+- Role: WhatsApp AI Assistant
+- Creator: ${maker}
+- Persona: Friendly, polite, helpful, and engaging female assistant.
+
+[IDENTITY RULES — NON-NEGOTIABLE]
+- Your name is exactly "${name}". Not "${name} Mini", not "${name} AI", not "${name} Assistant", not any other variant.
+- You were created by ${maker}. No other company, lab, or product made you.
+- You are NOT ChatGPT, NOT GPT, NOT OpenAI, NOT DeepAI, NOT Llama, NOT Gemini, NOT Claude, and NOT "Standard AI Chat".
+- NEVER mention, hint at, or compare yourself with any AI vendor, model name, or model version.
+- NEVER say you are "a language model", "an AI model", or that you were "trained by" anyone.
+- If asked who you are: you are ${name}, a WhatsApp assistant made by ${maker}. Nothing else.
+
+[CRITICAL FORMATTING RULES - WHATSAPP ONLY]
+You respond exclusively inside WhatsApp messages. Standard Markdown breaks WhatsApp formatting.
+- STRICTLY FORBIDDEN: Do NOT use double asterisks \`**text**\` or markdown headers like \`#\` or \`##\`.
+- ALWAYS use WhatsApp-native syntax:
+  * Bold: *text* (single asterisk)
+  * Italic: _text_ (single underscore)
+  * Strikethrough: ~text~ (single tilde)
+  * Inline Code / Highlight: \`text\`
+  * Monospace Block: \`\`\`text\`\`\`
+  * Combined: _*bold italic*_
+
+[STRICT TRIGGER COMMANDS - EXACT MATCH OUTPUTS]
+If the user's input matches one of the following 4 intents, reply ONLY with the exact text specified below. Do NOT add greetings, extra words, punctuation, or formatting.
+
+1. Weather Requests:
+   - Intent: Asking about current weather, forecast, or temperature for any location.
+   - Output Format: weather <city_name>
+   - Examples:
+     User: "What is the weather in Colombo today?" -> Output: weather Colombo
+     User: "Is it raining in Kandy right now?" -> Output: weather Kandy
+
+2. Menu Requests:
+   - Intent: Asking for bot menu, options, commands, or 'show menu'.
+   - Output Format: menu
+
+3. System Status / Ping Requests:
+   - Intent: Testing ping, asking about server/system status.
+   - Output Format: ping
+
+4. Documentation Requests:
+   - Intent: Asking for docs, user guide, or documentation.
+   - Output Format: doc
+
+[MATH QUERY RULES]
+- Provide ONLY the direct final formula and result.
+- Do NOT include step-by-step explanations or derivations.
+- Wrap math results in WhatsApp inline code format.
+- Example:
+  User: "Calculate the area of a circle with radius 7"
+  Output: \`A = π * 7² ≈ 153.938\`
+
+[IMAGE & VISION ANALYSIS]
+- When an image is provided, analyze it thoroughly and respond according to the user's text prompt.
+- If an image is sent without any text prompt, briefly and warmly describe what you see in the image using WhatsApp text formatting.
+- When a description of the attached image is given to you in brackets, treat it as something you can SEE. Never reply that you cannot see images.
+
+[MEMORY — YOU DO HAVE A PERSISTENT MEMORY]
+- ${maker} gave you a permanent database. Facts you learn about a person stay with that person FOREVER, in their private chat AND in every group they write to you from.
+- NEVER say "I can't remember", "I have no memory of past conversations", "as an AI I cannot recall", or "our conversation just started". Those statements are false for you.
+- Facts already known about the current person are supplied to you before each message. Treat them as things you personally remember, and answer recall questions ("do you remember me?", "what is my name?") directly from them.
+- If a fact genuinely is not in the supplied list, say you do not know that detail yet and ask for it — never deny having memory at all.
+
+[MEMORY TRACKING SYSTEM]
+- Silently monitor the chat for useful personal information (e.g., real name, favorite food, location, hobbies).
+- When new info is revealed, respond naturally to the user FIRST, and append a hidden JSON tag at the VERY END.
+- Output Format: @MEMORY: {"key": "value"}
+- Example:
+  User: "Hi, I'm Nimal and I love playing cricket."
+  Output: Nice to meet you, Nimal! Cricket is a great sport. @MEMORY: {"name": "Nimal", "hobby": "cricket"}
+- NEVER explain or mention the \`@MEMORY:\` tag to the user.
+
+[GENERAL CONVERSATION]
+For all other queries, chat naturally, warmly, and helpfully as ${name}. Keep responses formatted for easy reading on mobile screens.`;
+}
+
+const SYSTEM_PROMPT = build();
+
+module.exports = { build, SYSTEM_PROMPT };

package/src/core/StreamParser.js

@@ -0,0 +1,157 @@
+'use strict';
+
+/**
+ * StreamParser
+ * ------------
+ * DeepAI's chat endpoint does NOT return clean prose. It returns a plain-text
+ * stream with three kinds of out-of-band packets embedded in it, exactly as
+ * decoded by the browser client:
+ *
+ *   1. Tool-activity packets   \u001C{"tool_activity":"Searching the web…"}\u001C
+ *      Sprinkled anywhere in the stream while a tool runs. The browser strips
+ *      them and shows them as a status line.
+ *
+ *   2. A trailing payload      …answer text…\u001C{"type":"generated_image",…}
+ *      Everything after the LAST lone \u001C is JSON: either an array of web
+ *      search results, or a generated-image / function-call object.
+ *
+ *   3. Thinking blocks         \u001dTHINKING_START12s\u001e<chain of thought>\u001dTHINKING_END
+ *      Emitted by reasoning-capable models.
+ *
+ * Before this parser existed the engine forwarded the raw stream to WhatsApp,
+ * so users could see control characters, JSON blobs and the model's private
+ * chain of thought. `parse()` splits it all apart.
+ */
+const FS = '\u001C'; // file separator — packet delimiter
+const GS = '\u001D'; // group separator — thinking markers
+const RS = '\u001E'; // record separator — "12s" <RS> "<cot>"
+
+const ACTIVITY_PACKET = /\u001C(\{[^\u001C]*\})\u001C/g;
+const THINK_START = `${GS}THINKING_START`;
+const THINK_END = `${GS}THINKING_END`;
+
+class StreamParser {
+    /**
+     * @param {string} raw full (or partial) response body
+     * @returns {{
+     *   text: string,
+     *   payload: any|null,
+     *   payloadRaw: string|null,
+     *   toolActivity: string[],
+     *   thinking: { text: string|null, duration: string|null }|null,
+     *   images: string[],
+     *   functionCall: { name: string, arguments: any }|null,
+     *   webResults: Array<{title:string,url:string,description?:string}>|null
+     * }}
+     */
+    static parse(raw) {
+        const source = String(raw ?? '');
+
+        // ---- 1. tool activity ------------------------------------------------
+        const toolActivity = [];
+        let text = source.replace(ACTIVITY_PACKET, (_m, json) => {
+            try {
+                const packet = JSON.parse(json);
+                if (typeof packet.tool_activity === 'string') toolActivity.push(packet.tool_activity);
+            } catch {
+                /* not an activity packet — drop it, it is not prose either */
+            }
+            return '';
+        });
+
+        // ---- 2. trailing JSON payload ---------------------------------------
+        let payloadRaw = null;
+        let payload = null;
+        const fsIndex = text.indexOf(FS);
+        if (fsIndex !== -1) {
+            const candidate = text.slice(fsIndex + 1).trim();
+            if (candidate) {
+                try {
+                    payload = JSON.parse(candidate);
+                    payloadRaw = candidate;
+                } catch {
+                    // Truncated packet (stream cut mid-JSON): discard it rather
+                    // than leaking half a JSON blob into a WhatsApp message.
+                    payload = null;
+                    payloadRaw = null;
+                }
+            }
+            text = text.slice(0, fsIndex);
+        }
+
+        // ---- 3. thinking block ----------------------------------------------
+        let thinking = null;
+        const start = text.indexOf(THINK_START);
+        const end = text.indexOf(THINK_END);
+        if (start !== -1 && end !== -1 && end > start) {
+            const body = text.slice(start + THINK_START.length, end);
+            const sep = body.indexOf(RS);
+            thinking =
+                sep !== -1
+                    ? { duration: body.slice(0, sep) || null, text: body.slice(sep + 1) || null }
+                    : { duration: null, text: body || null };
+            text = text.slice(0, start) + text.slice(end + THINK_END.length);
+        }
+
+        // Any stray separators left over (partial packets) must never ship.
+        text = text.replace(/[\u001C\u001D\u001E]/g, '').trim();
+
+        return {
+            text,
+            payload,
+            payloadRaw,
+            toolActivity,
+            thinking,
+            images: StreamParser.imagesFrom(payload),
+            functionCall: StreamParser.functionCallFrom(payload),
+            webResults: Array.isArray(payload) ? payload : null,
+        };
+    }
+
+    /** Image URLs carried by a `{type:'generated_image'}` payload. */
+    static imagesFrom(payload) {
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return [];
+        const urls = [];
+        if (payload.type === 'generated_image' || payload.share_url || payload.output_url) {
+            const url = payload.share_url || payload.url || payload.output_url;
+            if (typeof url === 'string' && url) urls.push(url);
+        }
+        if (Array.isArray(payload.images)) {
+            for (const img of payload.images) {
+                const url = typeof img === 'string' ? img : img?.share_url || img?.url;
+                if (url) urls.push(url);
+            }
+        }
+        return urls;
+    }
+
+    /** `{function_call:{name, arguments}}` — the image tool protocol. */
+    static functionCallFrom(payload) {
+        const call = payload && !Array.isArray(payload) ? payload.function_call : null;
+        if (!call || typeof call.name !== 'string') return null;
+        let args = call.arguments;
+        if (typeof args === 'string') {
+            try {
+                args = JSON.parse(args);
+            } catch {
+                /* keep the raw string */
+            }
+        }
+        return { name: call.name, arguments: args ?? {} };
+    }
+
+    /**
+     * Build the payload the browser sends when the user presses "Create image",
+     * so the engine can drive DeepAI's in-chat image tool the same way.
+     */
+    static imageToolPayload(prompt, aspectRatio = '1:1') {
+        return JSON.stringify({
+            function_call: {
+                name: 'generate_image',
+                arguments: JSON.stringify({ prompt: String(prompt ?? ''), aspect_ratio: aspectRatio }),
+            },
+        });
+    }
+}
+
+module.exports = StreamParser;

package/src/core/SystemPrompt.js

@@ -0,0 +1,7 @@
+'use strict';
+
+/**
+ * The default Alexa persona, as a plain string (back-compatible export).
+ * Use `require('./Persona').build({ assistantName, creator })` to rename her.
+ */
+module.exports = require('./Persona').SYSTEM_PROMPT;

package/src/core/errors.js

@@ -0,0 +1,51 @@
+'use strict';
+
+/** Base class for every error thrown by the engine. */
+class AlexaAIError extends Error {
+    constructor(message, options = {}) {
+        super(message);
+        this.name = this.constructor.name;
+        this.code = options.code || 'ALEXA_AI_ERROR';
+        this.retryable = Boolean(options.retryable);
+        if (options.cause) this.cause = options.cause;
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+}
+
+/** Network/HTTP/parse failure talking to DeepAI. */
+class DeepAIError extends AlexaAIError {
+    constructor(message, options = {}) {
+        super(message, { code: options.code || 'DEEPAI_ERROR', ...options });
+        this.status = options.status ?? null;
+        this.body = options.body ?? null;
+    }
+}
+
+/** DeepAI refused the request: quota, paid-model, or auth. */
+class QuotaExceededError extends DeepAIError {
+    constructor(message, options = {}) {
+        super(message, { code: 'DEEPAI_QUOTA_EXCEEDED', retryable: false, ...options });
+    }
+}
+
+/** PostgreSQL failure. */
+class DatabaseError extends AlexaAIError {
+    constructor(message, options = {}) {
+        super(message, { code: options.code || 'DATABASE_ERROR', ...options });
+    }
+}
+
+/** Bad arguments handed to a public method. */
+class ValidationError extends AlexaAIError {
+    constructor(message, options = {}) {
+        super(message, { code: 'VALIDATION_ERROR', retryable: false, ...options });
+    }
+}
+
+module.exports = {
+    AlexaAIError,
+    DeepAIError,
+    QuotaExceededError,
+    DatabaseError,
+    ValidationError,
+};

package/src/db/Database.js

@@ -0,0 +1,161 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { Pool } = require('pg');
+const { DatabaseError } = require('../core/errors');
+
+/**
+ * Database
+ * --------
+ * Owns the pg connection pool, runs migrations, and exposes small helpers
+ * (`query`, `one`, `transaction`) used by the repositories.
+ */
+class Database {
+    /** @param {import('../core/Config')} config */
+    constructor(config) {
+        this.config = config;
+        this.log = config.logger;
+        this.pool = null;
+        this._ready = null;
+        this._closed = false;
+    }
+
+    /** Lazily create the pool + run migrations exactly once. */
+    async connect() {
+        if (this._ready) return this._ready;
+
+        this._ready = (async () => {
+            this.pool = new Pool({
+                connectionString: this.config.postgresUrl,
+                ssl: this.config.ssl,
+                ...this.config.pool,
+            });
+
+            // A pooled client can die (network blip, managed-PG restart).
+            // Without this handler Node would crash the whole bot.
+            this.pool.on('error', (err) => {
+                this.log.error?.('[AlexaAI] Idle PostgreSQL client error:', err.message);
+            });
+
+            try {
+                const client = await this.pool.connect();
+                client.release();
+            } catch (err) {
+                this.pool = null;
+                this._ready = null;
+                throw new DatabaseError(`Cannot connect to PostgreSQL: ${err.message}`, {
+                    code: 'DB_CONNECT_FAILED',
+                    cause: err,
+                });
+            }
+
+            if (this.config.autoMigrate) await this.migrate();
+            if (this.config.debug) this.log.info?.('[AlexaAI] PostgreSQL ready');
+            return this.pool;
+        })();
+
+        return this._ready;
+    }
+
+    /** Apply schema.sql. Idempotent. */
+    async migrate() {
+        const sqlPath = path.join(__dirname, 'schema.sql');
+        let sql;
+        try {
+            sql = fs.readFileSync(sqlPath, 'utf8');
+        } catch (err) {
+            throw new DatabaseError(`Unable to read schema.sql: ${err.message}`, { cause: err });
+        }
+
+        try {
+            await this.pool.query(sql);
+        } catch (err) {
+            throw new DatabaseError(`Migration failed: ${err.message}`, {
+                code: 'DB_MIGRATION_FAILED',
+                cause: err,
+            });
+        }
+    }
+
+    /**
+     * @param {string} text
+     * @param {Array<any>} [params]
+     * @returns {Promise<import('pg').QueryResult>}
+     */
+    async query(text, params = []) {
+        if (this._closed) throw new DatabaseError('Database pool is closed', { code: 'DB_CLOSED' });
+        await this.connect();
+        const started = this.config.debug ? Date.now() : 0;
+        try {
+            const result = await this.pool.query(text, params);
+            if (this.config.debug) {
+                this.log.debug?.(`[AlexaAI][sql ${Date.now() - started}ms] ${text.split('\n')[0].trim()}`);
+            }
+            return result;
+        } catch (err) {
+            throw new DatabaseError(`Query failed: ${err.message}`, {
+                code: err.code || 'DB_QUERY_FAILED',
+                cause: err,
+            });
+        }
+    }
+
+    /** First row or null. */
+    async one(text, params = []) {
+        const { rows } = await this.query(text, params);
+        return rows[0] || null;
+    }
+
+    /** All rows. */
+    async many(text, params = []) {
+        const { rows } = await this.query(text, params);
+        return rows;
+    }
+
+    /**
+     * Run `fn` inside BEGIN/COMMIT, rolling back on throw.
+     * @param {(client: import('pg').PoolClient) => Promise<any>} fn
+     */
+    async transaction(fn) {
+        await this.connect();
+        const client = await this.pool.connect();
+        try {
+            await client.query('BEGIN');
+            const result = await fn(client);
+            await client.query('COMMIT');
+            return result;
+        } catch (err) {
+            try {
+                await client.query('ROLLBACK');
+            } catch {
+                /* connection already dead */
+            }
+            if (err instanceof DatabaseError) throw err;
+            throw new DatabaseError(`Transaction failed: ${err.message}`, { cause: err });
+        } finally {
+            client.release();
+        }
+    }
+
+    /** Simple health probe. */
+    async healthCheck() {
+        try {
+            const row = await this.one('SELECT NOW() AS now, current_database() AS db');
+            return { ok: true, now: row.now, database: row.db };
+        } catch (err) {
+            return { ok: false, error: err.message };
+        }
+    }
+
+    async close() {
+        if (this.pool && !this._closed) {
+            this._closed = true;
+            await this.pool.end();
+            this.pool = null;
+            this._ready = null;
+        }
+    }
+}
+
+module.exports = Database;