@realtimex/folio 0.1.2

package/dist/api/src/routes/tts.js

@@ -0,0 +1,178 @@
+import { Router } from "express";
+import { SDKService } from "../services/SDKService.js";
+const router = Router();
+/**
+ * GET /api/tts/providers
+ * List available TTS providers and their configuration options
+ */
+router.get("/providers", async (req, res) => {
+    try {
+        const sdk = SDKService.getSDK();
+        if (!sdk) {
+            return res.status(503).json({
+                success: false,
+                error: "RealTimeX SDK not available. Please ensure RealTimeX Desktop is running."
+            });
+        }
+        // Check if TTS module is available
+        if (!sdk.tts) {
+            return res.status(503).json({
+                success: false,
+                error: "TTS module not available. Please ensure RealTimeX Desktop is running and updated to v1.2.3+."
+            });
+        }
+        const providers = await sdk.tts.listProviders();
+        res.json({
+            success: true,
+            providers
+        });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }
+    catch (error) {
+        console.error("[TTS API] Failed to list providers:", error);
+        res.status(503).json({
+            success: false,
+            error: error.message || "Failed to list TTS providers. Ensure RealTimeX Desktop is running."
+        });
+    }
+});
+/**
+ * POST /api/tts/speak
+ * Generate full audio buffer for text
+ * Body: { text: string, provider?: string, voice?: string, speed?: number }
+ */
+router.post("/speak", async (req, res) => {
+    try {
+        const { text, provider, voice, speed, quality } = req.body;
+        if (!text || typeof text !== "string") {
+            return res.status(400).json({
+                success: false,
+                error: "Text is required"
+            });
+        }
+        const sdk = SDKService.getSDK();
+        if (!sdk) {
+            return res.status(503).json({
+                success: false,
+                error: "RealTimeX SDK not available"
+            });
+        }
+        // Check if TTS module is available
+        if (!sdk.tts) {
+            return res.status(503).json({
+                success: false,
+                error: "TTS module not available. Please ensure RealTimeX Desktop is running and updated to v1.2.3+."
+            });
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const options = {};
+        if (provider)
+            options.provider = provider;
+        if (voice)
+            options.voice = voice;
+        if (speed)
+            options.speed = parseFloat(speed);
+        if (quality)
+            options.num_inference_steps = parseInt(quality);
+        const audioBuffer = await sdk.tts.speak(text, options);
+        // Return audio as binary
+        res.setHeader("Content-Type", "audio/mpeg");
+        res.send(Buffer.from(audioBuffer));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }
+    catch (error) {
+        console.error("[TTS API] Failed to generate speech:", error);
+        res.status(500).json({
+            success: false,
+            error: error.message || "Failed to generate speech"
+        });
+    }
+});
+/**
+ * POST /api/tts/stream
+ * Stream audio chunks via Server-Sent Events
+ * Body: { text: string, provider?: string, voice?: string, speed?: number }
+ */
+router.post("/stream", async (req, res) => {
+    try {
+        const { text, provider, voice, speed, quality } = req.body;
+        if (!text || typeof text !== "string") {
+            return res.status(400).json({
+                success: false,
+                error: "Text is required"
+            });
+        }
+        const sdk = SDKService.getSDK();
+        if (!sdk) {
+            return res.status(503).json({
+                success: false,
+                error: "RealTimeX SDK not available"
+            });
+        }
+        // Check if TTS module is available
+        if (!sdk.tts) {
+            return res.status(503).json({
+                success: false,
+                error: "TTS module not available. Please ensure RealTimeX Desktop is running and updated to v1.2.3+."
+            });
+        }
+        // Set up SSE
+        res.setHeader("Content-Type", "text/event-stream");
+        res.setHeader("Cache-Control", "no-cache");
+        res.setHeader("Connection", "keep-alive");
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const options = {};
+        if (provider)
+            options.provider = provider;
+        if (voice)
+            options.voice = voice;
+        if (speed)
+            options.speed = parseFloat(speed);
+        if (quality)
+            options.num_inference_steps = parseInt(quality);
+        // Send info event
+        res.write(`event: info\n`);
+        res.write(`data: ${JSON.stringify({ message: "Starting TTS generation..." })}\n\n`);
+        try {
+            // Stream chunks
+            for await (const chunk of sdk.tts.speakStream(text, options)) {
+                // Encode ArrayBuffer to base64
+                const base64Audio = Buffer.from(chunk.audio).toString("base64");
+                res.write(`event: chunk\n`);
+                res.write(`data: ${JSON.stringify({
+                    index: chunk.index,
+                    total: chunk.total,
+                    audio: base64Audio,
+                    mimeType: chunk.mimeType
+                })}\n\n`);
+            }
+            // Send done event
+            res.write(`event: done\n`);
+            res.write(`data: ${JSON.stringify({ message: "TTS generation complete" })}\n\n`);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        }
+        catch (streamError) {
+            res.write(`event: error\n`);
+            res.write(`data: ${JSON.stringify({ error: streamError.message })}\n\n`);
+        }
+        res.end();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }
+    catch (error) {
+        console.error("[TTS API] Failed to stream speech:", error);
+        // If headers not sent yet, send JSON error
+        if (!res.headersSent) {
+            res.status(500).json({
+                success: false,
+                error: error.message || "Failed to stream speech"
+            });
+        }
+        else {
+            // Send SSE error event
+            res.write(`event: error\n`);
+            res.write(`data: ${JSON.stringify({ error: error.message })}\n\n`);
+            res.end();
+        }
+    }
+});
+export default router;

package/dist/api/src/services/BaselineConfigService.js

@@ -0,0 +1,168 @@
+import { createLogger } from "../utils/logger.js";
+const logger = createLogger("BaselineConfigService");
+// ─── Default schema ───────────────────────────────────────────────────────────
+export const DEFAULT_BASELINE_FIELDS = [
+    {
+        key: "document_type",
+        type: "string",
+        description: 'Type of document (e.g. "invoice", "contract", "receipt", "report", "statement")',
+        enabled: true,
+        is_default: true,
+    },
+    {
+        key: "issuer",
+        type: "string",
+        description: "Person or organisation that sent or issued the document",
+        enabled: true,
+        is_default: true,
+    },
+    {
+        key: "recipient",
+        type: "string",
+        description: "Person or organisation the document is addressed to",
+        enabled: true,
+        is_default: true,
+    },
+    {
+        key: "date",
+        type: "date",
+        description: "Primary date on the document in ISO 8601 format (YYYY-MM-DD)",
+        enabled: true,
+        is_default: true,
+    },
+    {
+        key: "amount",
+        type: "currency",
+        description: "Primary monetary value if present (numeric, no currency symbol)",
+        enabled: true,
+        is_default: true,
+    },
+    {
+        key: "currency",
+        type: "string",
+        description: 'Three-letter currency code if present (e.g. "USD", "EUR", "GBP")',
+        enabled: true,
+        is_default: true,
+    },
+    {
+        key: "subject",
+        type: "string",
+        description: "One-sentence description of what this document is about",
+        enabled: true,
+        is_default: true,
+    },
+    {
+        key: "tags",
+        type: "string[]",
+        description: 'Semantic labels that describe this document (e.g. ["subscription", "renewal", "tax", "refund"])',
+        enabled: true,
+        is_default: true,
+    },
+    {
+        key: "suggested_filename",
+        type: "string",
+        description: 'A highly descriptive, concise filename for this document using the format: YYYY-MM-DD_Issuer_DocType. Do not include file extensions. If date is missing, omit it.',
+        enabled: true,
+        is_default: true,
+    }
+];
+// ─── Service ──────────────────────────────────────────────────────────────────
+export class BaselineConfigService {
+    /**
+     * Return the active config for a user.
+     * Returns null if none has been saved yet — callers should fall back to DEFAULT_BASELINE_FIELDS.
+     */
+    static async getActive(supabase, userId) {
+        const { data, error } = await supabase
+            .from("baseline_configs")
+            .select("*")
+            .eq("user_id", userId)
+            .eq("is_active", true)
+            .maybeSingle();
+        if (error) {
+            logger.warn("Failed to fetch active baseline config", { error });
+            return null;
+        }
+        return data;
+    }
+    /**
+     * Return all saved versions for a user, newest first.
+     */
+    static async list(supabase, userId) {
+        const { data, error } = await supabase
+            .from("baseline_configs")
+            .select("*")
+            .eq("user_id", userId)
+            .order("version", { ascending: false });
+        if (error)
+            throw new Error(`Failed to list baseline configs: ${error.message}`);
+        return (data ?? []);
+    }
+    /**
+     * Save a new config version.
+     * Always creates a new immutable row — never mutates existing versions.
+     * If activate=true, the new version is immediately set as active and the
+     * previous active version is deactivated.
+     */
+    static async save(supabase, userId, payload, activate) {
+        // Determine next version number for this user
+        const { data: latest } = await supabase
+            .from("baseline_configs")
+            .select("version")
+            .eq("user_id", userId)
+            .order("version", { ascending: false })
+            .limit(1)
+            .maybeSingle();
+        const nextVersion = (latest?.version ?? 0) + 1;
+        if (activate) {
+            // Deactivate all existing versions first
+            await supabase
+                .from("baseline_configs")
+                .update({ is_active: false })
+                .eq("user_id", userId);
+        }
+        const { data, error } = await supabase
+            .from("baseline_configs")
+            .insert({
+            user_id: userId,
+            version: nextVersion,
+            context: payload.context ?? null,
+            fields: payload.fields,
+            is_active: activate,
+        })
+            .select()
+            .single();
+        if (error || !data)
+            throw new Error(`Failed to save baseline config: ${error?.message}`);
+        logger.info(`Saved baseline config v${nextVersion} for user ${userId} (active: ${activate})`);
+        return data;
+    }
+    /**
+     * Activate a specific saved version.
+     * Deactivates all other versions for this user atomically.
+     */
+    static async activate(supabase, userId, id) {
+        // Verify the config belongs to this user
+        const { data: target } = await supabase
+            .from("baseline_configs")
+            .select("id, version")
+            .eq("id", id)
+            .eq("user_id", userId)
+            .maybeSingle();
+        if (!target)
+            return false;
+        // Deactivate all, then activate the target
+        await supabase
+            .from("baseline_configs")
+            .update({ is_active: false })
+            .eq("user_id", userId);
+        const { error } = await supabase
+            .from("baseline_configs")
+            .update({ is_active: true })
+            .eq("id", id);
+        if (error)
+            throw new Error(`Failed to activate baseline config: ${error.message}`);
+        logger.info(`Activated baseline config v${target.version} for user ${userId}`);
+        return true;
+    }
+}

package/dist/api/src/services/ChatService.js

@@ -0,0 +1,166 @@
+import { SDKService } from "./SDKService.js";
+import { RAGService } from "./RAGService.js";
+import { createLogger } from "../utils/logger.js";
+import { Actuator } from "../utils/Actuator.js";
+import { extractLlmResponse, previewLlmText } from "../utils/llmResponse.js";
+const logger = createLogger("ChatService");
+export class ChatService {
+    /**
+     * Send a message to an existing session, augment with RAG context if needed,
+     * and stream the AI response back into the database.
+     */
+    static async handleMessage(sessionId, userId, content, supabase) {
+        // 1. Get User/Session Settings (Models to use)
+        const { data: settings } = await supabase
+            .from("user_settings")
+            .select("llm_provider, llm_model, embedding_provider, embedding_model")
+            .eq("user_id", userId)
+            .maybeSingle();
+        const llmSettings = {
+            llm_provider: settings?.llm_provider ?? undefined,
+            llm_model: settings?.llm_model ?? undefined,
+        };
+        const embedSettings = {
+            embedding_provider: settings?.embedding_provider ?? undefined,
+            embedding_model: settings?.embedding_model ?? undefined,
+        };
+        // 2. Resolve Providers
+        const chatProvider = await SDKService.resolveChatProvider(llmSettings);
+        // 3. Save User Message
+        const { error: userMsgErr } = await supabase.from("chat_messages").insert({
+            session_id: sessionId,
+            user_id: userId,
+            role: "user",
+            content
+        });
+        if (userMsgErr) {
+            logger.error(`Failed to save user message for session ${sessionId}`, { error: userMsgErr });
+            throw new Error("Failed to save message");
+        }
+        // 4. Retrieve semantic context (Dynamic RAG)
+        let contextSources = [];
+        try {
+            Actuator.logEvent(null, userId, "analysis", "RAG Retrieval", {
+                action: "RAG query request",
+                session_id: sessionId,
+                top_k: 5,
+                threshold: 0.65,
+                embedding_provider: embedSettings.embedding_provider ?? "auto",
+                embedding_model: embedSettings.embedding_model ?? "auto",
+                query_preview: content.slice(0, 180),
+            }, supabase);
+            contextSources = await RAGService.searchDocuments(content, userId, supabase, { topK: 5, similarityThreshold: 0.65, settings: embedSettings });
+            Actuator.logEvent(null, userId, "analysis", "RAG Retrieval", {
+                action: "RAG query response",
+                session_id: sessionId,
+                hits: contextSources.length,
+                top_similarity: contextSources[0]?.similarity ?? null,
+                ingestion_ids: Array.from(new Set(contextSources.map((c) => c.ingestion_id))).slice(0, 5),
+            }, supabase);
+        }
+        catch (err) {
+            logger.warn(`Semantic search failed during chat. Proceeding without context.`, { error: err });
+            Actuator.logEvent(null, userId, "error", "RAG Retrieval", {
+                action: "RAG query failed",
+                session_id: sessionId,
+                error: err instanceof Error ? err.message : String(err),
+            }, supabase);
+        }
+        // 5. Fetch Chat History
+        const { data: history, error: historyError } = await supabase
+            .from("chat_messages")
+            .select("role, content")
+            .eq("session_id", sessionId)
+            .order("created_at", { ascending: false })
+            .limit(20);
+        if (historyError) {
+            logger.error(`Failed to fetch chat history for session ${sessionId}`, { error: historyError });
+            throw new Error("Failed to load chat history");
+        }
+        const chatHistory = (history || [])
+            .reverse()
+            .map((m) => ({
+            role: m.role,
+            content: String(m.content ?? "")
+        }));
+        // 6. Build the Augmented Prompt
+        let systemPrompt = `You are the Folio AI Agent, a brilliant and precise autonomous filing assistant.\n`;
+        systemPrompt += `You have been asked a question. `;
+        if (contextSources.length > 0) {
+            systemPrompt += `Below is exact extracted text from the user's documents retrieved via Semantic Search to answer the question. Cite the context when responding.\n\n`;
+            systemPrompt += `--- CONTEXT SOURCES ---\n`;
+            contextSources.forEach((c, idx) => {
+                systemPrompt += `[Source ${idx + 1}]:\n${c.content}\n\n`;
+            });
+            systemPrompt += `--- END CONTEXT ---\n`;
+        }
+        else {
+            systemPrompt += `No specific documents were retrieved for this query. Answer conversationally, but let the user know you couldn't find exact files matching their question.`;
+        }
+        const messagesForLLM = [
+            { role: "system", content: systemPrompt },
+            ...chatHistory
+        ];
+        // 7. Get AI Response via SDK
+        const sdk = SDKService.getSDK();
+        if (!sdk) {
+            throw new Error("RealTimeX SDK not available");
+        }
+        let replyContent = "I am unable to process that request.";
+        try {
+            Actuator.logEvent(null, userId, "analysis", "Chat", {
+                action: "LLM request (chat response)",
+                session_id: sessionId,
+                provider: chatProvider.provider,
+                model: chatProvider.model,
+                messages_count: messagesForLLM.length,
+                context_sources_count: contextSources.length,
+            }, supabase);
+            const completion = await sdk.llm.chat(messagesForLLM, {
+                provider: chatProvider.provider,
+                model: chatProvider.model,
+                temperature: 0.3
+            });
+            const raw = extractLlmResponse(completion);
+            Actuator.logEvent(null, userId, "analysis", "Chat", {
+                action: "LLM response (chat response)",
+                session_id: sessionId,
+                provider: chatProvider.provider,
+                model: chatProvider.model,
+                raw_length: raw.length,
+                raw_preview: previewLlmText(raw),
+            }, supabase);
+            if (raw.trim()) {
+                replyContent = raw;
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.error(`Chat completion failed for session ${sessionId}`, { error: err });
+            Actuator.logEvent(null, userId, "error", "Chat", {
+                action: "LLM chat failed",
+                session_id: sessionId,
+                provider: chatProvider.provider,
+                model: chatProvider.model,
+                error: msg,
+            }, supabase);
+            throw err;
+        }
+        // 8. Save Assistant Reply
+        const { data: aiMsg, error: aiMsgErr } = await supabase.from("chat_messages")
+            .insert({
+            session_id: sessionId,
+            user_id: userId,
+            role: "assistant",
+            content: replyContent,
+            context_sources: contextSources
+        })
+            .select("*")
+            .single();
+        if (aiMsgErr) {
+            logger.error(`Failed to save AI message for session ${sessionId}`, { error: aiMsgErr });
+            throw new Error("Failed to save AI response");
+        }
+        return aiMsg;
+    }
+}