@realtimex/folio 0.1.2

package/api/src/routes/tts.ts

@@ -0,0 +1,190 @@
+import { Request, Response, 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: Request, res: Response) => {
+    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: any) {
+        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: Request, res: Response) => {
+    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: any = {};
+        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: any) {
+        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: Request, res: Response) => {
+    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: any = {};
+        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: any) {
+            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: any) {
+        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/api/src/services/BaselineConfigService.ts

@@ -0,0 +1,208 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+import { createLogger } from "../utils/logger.js";
+
+const logger = createLogger("BaselineConfigService");
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface BaselineField {
+    key: string;
+    type: "string" | "number" | "date" | "currency" | "string[]";
+    description: string;
+    enabled: boolean;
+    is_default: boolean; // default fields can be disabled but not deleted
+}
+
+export interface BaselineConfig {
+    id: string;
+    user_id: string;
+    version: number;
+    context: string | null;
+    fields: BaselineField[];
+    is_active: boolean;
+    created_at: string;
+}
+
+// ─── Default schema ───────────────────────────────────────────────────────────
+
+export const DEFAULT_BASELINE_FIELDS: BaselineField[] = [
+    {
+        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: SupabaseClient, userId: string): Promise<BaselineConfig | null> {
+        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 as BaselineConfig | null;
+    }
+
+    /**
+     * Return all saved versions for a user, newest first.
+     */
+    static async list(supabase: SupabaseClient, userId: string): Promise<BaselineConfig[]> {
+        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 ?? []) as BaselineConfig[];
+    }
+
+    /**
+     * 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: SupabaseClient,
+        userId: string,
+        payload: { context?: string | null; fields: BaselineField[] },
+        activate: boolean
+    ): Promise<BaselineConfig> {
+        // 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 as BaselineConfig;
+    }
+
+    /**
+     * Activate a specific saved version.
+     * Deactivates all other versions for this user atomically.
+     */
+    static async activate(supabase: SupabaseClient, userId: string, id: string): Promise<boolean> {
+        // 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/api/src/services/ChatService.ts

@@ -0,0 +1,204 @@
+import { SupabaseClient } from "@supabase/supabase-js";
+import { SDKService } from "./SDKService.js";
+import { RAGService, RetrievedChunk } 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 interface Message {
+    id: string;
+    role: "user" | "assistant" | "system";
+    content: string;
+    context_sources?: RetrievedChunk[];
+    created_at: string;
+}
+
+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: string,
+        userId: string,
+        content: string,
+        supabase: SupabaseClient
+    ): Promise<Message> {
+        // 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: RetrievedChunk[] = [];
+        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: Array<{ role: "user" | "assistant" | "system"; content: string }> = (history || [])
+            .reverse()
+            .map((m) => ({
+                role: m.role as "user" | "assistant" | "system",
+                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: Array<{ role: "user" | "assistant" | "system"; content: string }> = [
+            { 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 as Message;
+    }
+}