@realtimex/folio 0.1.2

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

@@ -0,0 +1,295 @@
+import crypto from "node:crypto";
+import { SDKService } from "./SDKService.js";
+import { createLogger } from "../utils/logger.js";
+const logger = createLogger("RAGService");
+export class RAGService {
+    static MAX_CONCURRENT_EMBED_JOBS = (() => {
+        const parsed = Number.parseInt(process.env.RAG_MAX_CONCURRENT_EMBED_JOBS ?? "2", 10);
+        return Number.isFinite(parsed) && parsed > 0 ? parsed : 2;
+    })();
+    static activeEmbedJobs = 0;
+    static embedJobWaiters = [];
+    static async acquireEmbedJobSlot() {
+        while (this.activeEmbedJobs >= this.MAX_CONCURRENT_EMBED_JOBS) {
+            await new Promise((resolve) => this.embedJobWaiters.push(resolve));
+        }
+        this.activeEmbedJobs += 1;
+    }
+    static releaseEmbedJobSlot() {
+        this.activeEmbedJobs = Math.max(0, this.activeEmbedJobs - 1);
+        const waiter = this.embedJobWaiters.shift();
+        if (waiter)
+            waiter();
+    }
+    static async resolveEmbeddingModel(settings = {}) {
+        const { provider, model } = await SDKService.resolveEmbedProvider(settings);
+        return { provider, model };
+    }
+    static async embedTextWithResolvedModel(text, resolvedModel) {
+        const sdk = SDKService.getSDK();
+        if (!sdk) {
+            throw new Error("RealTimeX SDK not available for embedding");
+        }
+        const response = await sdk.llm.embed(text, {
+            provider: resolvedModel.provider,
+            model: resolvedModel.model
+        });
+        const embedding = response.embeddings?.[0];
+        if (!embedding) {
+            throw new Error("No embedding returned from SDK");
+        }
+        return embedding;
+    }
+    /**
+     * Splits a large text into smaller semantic chunks (roughly by paragraphs).
+     */
+    static chunkText(text, maxChunkLength = 1000) {
+        if (!text || text.trim().length === 0)
+            return [];
+        const paragraphs = text.split(/\n\s*\n/);
+        const chunks = [];
+        let currentChunk = "";
+        for (const paragraph of paragraphs) {
+            const p = paragraph.trim();
+            if (!p)
+                continue;
+            if (p.length > maxChunkLength) {
+                // Flush pending chunk before splitting an oversized paragraph
+                if (currentChunk.length > 0) {
+                    chunks.push(currentChunk.trim());
+                    currentChunk = "";
+                }
+                // Hard split oversized paragraphs to prevent SDK payload rejection
+                let i = 0;
+                while (i < p.length) {
+                    chunks.push(p.slice(i, i + maxChunkLength));
+                    i += maxChunkLength;
+                }
+                continue;
+            }
+            if (currentChunk.length + p.length > maxChunkLength && currentChunk.length > 0) {
+                chunks.push(currentChunk.trim());
+                currentChunk = "";
+            }
+            currentChunk += (currentChunk.length > 0 ? "\n\n" : "") + p;
+        }
+        if (currentChunk.trim().length > 0) {
+            chunks.push(currentChunk.trim());
+        }
+        return chunks;
+    }
+    /**
+     * Generate an embedding for a text string using RealTimeX SDK
+     */
+    static async embedText(text, settings) {
+        const resolvedModel = await this.resolveEmbeddingModel(settings || {});
+        logger.debug(`Generating embedding using ${resolvedModel.provider}/${resolvedModel.model}`);
+        return this.embedTextWithResolvedModel(text, resolvedModel);
+    }
+    /**
+     * Process an ingested document's raw text: chunk it, embed it, and store in DB.
+     */
+    static async chunkAndEmbed(ingestionId, userId, rawText, supabase, settings) {
+        if (rawText.startsWith("[VLM_IMAGE_DATA:")) {
+            logger.info(`Skipping chunking and embedding for VLM base64 image data (Ingestion: ${ingestionId})`);
+            return;
+        }
+        const chunks = this.chunkText(rawText);
+        if (chunks.length === 0) {
+            logger.info(`No text to chunk for ingestion ${ingestionId}`);
+            return;
+        }
+        const resolvedModel = await this.resolveEmbeddingModel(settings || {});
+        logger.info(`Extracted ${chunks.length} chunks for ingestion ${ingestionId}. Embedding with ${resolvedModel.provider}/${resolvedModel.model}...`);
+        // Global gate: background fire-and-forget jobs are bounded process-wide.
+        await this.acquireEmbedJobSlot();
+        try {
+            // To avoid provider throttling, process chunks sequentially inside each job.
+            for (const [index, content] of chunks.entries()) {
+                try {
+                    // Content hash is model-agnostic. Model identity is tracked in dedicated columns.
+                    const hash = crypto.createHash("sha256").update(content).digest("hex");
+                    // Check if this chunk already exists for this ingestion and this model.
+                    const { data: existing } = await supabase
+                        .from("document_chunks")
+                        .select("id")
+                        .eq("ingestion_id", ingestionId)
+                        .eq("content_hash", hash)
+                        .eq("embedding_provider", resolvedModel.provider)
+                        .eq("embedding_model", resolvedModel.model)
+                        .maybeSingle();
+                    if (existing) {
+                        continue; // Skip duplicate chunk
+                    }
+                    // Spread requests slightly to reduce burstiness against embedding APIs.
+                    await new Promise((r) => setTimeout(r, 100));
+                    const embedding = await this.embedTextWithResolvedModel(content, resolvedModel);
+                    const vector_dim = embedding.length;
+                    const { error } = await supabase.from("document_chunks").insert({
+                        user_id: userId,
+                        ingestion_id: ingestionId,
+                        content,
+                        content_hash: hash,
+                        embedding_provider: resolvedModel.provider,
+                        embedding_model: resolvedModel.model,
+                        embedding,
+                        vector_dim
+                    });
+                    if (error) {
+                        logger.error(`Failed to insert chunk ${index + 1}/${chunks.length} for ${ingestionId}`, { error });
+                    }
+                }
+                catch (err) {
+                    logger.error(`Failed to process chunk ${index + 1}/${chunks.length} for ${ingestionId}`, {
+                        error: err instanceof Error ? err.message : String(err)
+                    });
+                }
+            }
+        }
+        finally {
+            this.releaseEmbedJobSlot();
+        }
+        logger.info(`Successfully stored semantic chunks for ingestion ${ingestionId}`);
+    }
+    /**
+     * Semantically search the document chunks using dynamic pgvector partial indexing.
+     */
+    static async runSearchForModel(args) {
+        const { userId, supabase, modelScope, queryEmbedding, queryDim, similarityThreshold, topK } = args;
+        const { data, error } = await supabase.rpc("search_documents", {
+            p_user_id: userId,
+            p_embedding_provider: modelScope.provider,
+            p_embedding_model: modelScope.model,
+            query_embedding: queryEmbedding,
+            match_threshold: similarityThreshold,
+            match_count: topK,
+            query_dim: queryDim
+        });
+        if (error) {
+            throw new Error(`Knowledge base search failed for ${modelScope.provider}/${modelScope.model}: ${error.message}`);
+        }
+        return (data || []);
+    }
+    static async listUserModelScopes(userId, supabase) {
+        const { data, error } = await supabase
+            .from("document_chunks")
+            .select("embedding_provider, embedding_model, vector_dim, created_at")
+            .eq("user_id", userId)
+            .order("created_at", { ascending: false })
+            .limit(2000);
+        if (error) {
+            logger.warn("Failed to list user embedding scopes for RAG fallback", { error });
+            return [];
+        }
+        const scopes = new Map();
+        for (const row of data || []) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const provider = String(row.embedding_provider || "").trim();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const model = String(row.embedding_model || "").trim();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const vector_dim = Number(row.vector_dim);
+            if (!provider || !model)
+                continue;
+            const key = `${provider}::${model}`;
+            if (!scopes.has(key)) {
+                scopes.set(key, {
+                    provider,
+                    model,
+                    vector_dim: Number.isFinite(vector_dim) && vector_dim > 0 ? vector_dim : undefined
+                });
+            }
+        }
+        return Array.from(scopes.values());
+    }
+    static async searchDocuments(query, userId, supabase, options = {}) {
+        const { topK = 5, similarityThreshold = 0.7, settings } = options;
+        const minThreshold = Math.max(0.1, Math.min(similarityThreshold, 0.4));
+        const thresholdLevels = Array.from(new Set([similarityThreshold, minThreshold]));
+        const preferred = await this.resolveEmbeddingModel(settings || {});
+        const preferredScope = { provider: preferred.provider, model: preferred.model };
+        const embeddingCache = new Map();
+        const collected = new Map();
+        const trySearch = async (scope, threshold) => {
+            const cacheKey = `${scope.provider}::${scope.model}`;
+            let cached = embeddingCache.get(cacheKey);
+            if (!cached) {
+                const queryEmbedding = await this.embedTextWithResolvedModel(query, {
+                    provider: scope.provider,
+                    model: scope.model,
+                });
+                cached = { queryEmbedding, queryDim: queryEmbedding.length };
+                embeddingCache.set(cacheKey, cached);
+            }
+            const { queryEmbedding, queryDim } = cached;
+            if (scope.vector_dim && scope.vector_dim !== queryDim) {
+                logger.warn("Skipping model scope due to vector dimension mismatch", {
+                    scope,
+                    queryDim
+                });
+                return 0;
+            }
+            logger.info(`Searching knowledge base (${scope.provider}/${scope.model}, dim=${queryDim}, topK=${topK}, threshold=${threshold})`);
+            const hits = await this.runSearchForModel({
+                userId,
+                supabase,
+                modelScope: scope,
+                queryEmbedding,
+                queryDim,
+                similarityThreshold: threshold,
+                topK
+            });
+            for (const hit of hits) {
+                if (!collected.has(hit.id)) {
+                    collected.set(hit.id, hit);
+                }
+                else {
+                    const existing = collected.get(hit.id);
+                    if (hit.similarity > existing.similarity) {
+                        collected.set(hit.id, hit);
+                    }
+                }
+            }
+            return hits.length;
+        };
+        try {
+            for (const threshold of thresholdLevels) {
+                const hits = await trySearch(preferredScope, threshold);
+                if (hits > 0) {
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            logger.error("Semantic search failed for preferred embedding scope", {
+                provider: preferredScope.provider,
+                model: preferredScope.model,
+                error
+            });
+        }
+        if (collected.size === 0) {
+            const scopes = await this.listUserModelScopes(userId, supabase);
+            const fallbackScopes = scopes.filter((scope) => !(scope.provider === preferredScope.provider && scope.model === preferredScope.model));
+            for (const scope of fallbackScopes) {
+                try {
+                    for (const threshold of thresholdLevels) {
+                        await trySearch(scope, threshold);
+                        if (collected.size >= topK)
+                            break;
+                    }
+                }
+                catch (error) {
+                    logger.warn("Semantic search failed for fallback embedding scope", {
+                        scope,
+                        error
+                    });
+                }
+                if (collected.size >= topK)
+                    break;
+            }
+        }
+        return Array.from(collected.values())
+            .sort((a, b) => b.similarity - a.similarity)
+            .slice(0, topK);
+    }
+}

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

@@ -0,0 +1,212 @@
+import { RealtimeXSDK } from "@realtimex/sdk";
+import { createLogger } from "../utils/logger.js";
+const logger = createLogger("SDKService");
+export class SDKService {
+    static instance = null;
+    static initAttempted = false;
+    // Default provider/model configuration
+    // realtimexai routes through RealTimeX Desktop to user's configured providers
+    static DEFAULT_LLM_PROVIDER = "realtimexai";
+    static DEFAULT_LLM_MODEL = "gpt-4o-mini";
+    static DEFAULT_EMBED_PROVIDER = "realtimexai";
+    static DEFAULT_EMBED_MODEL = "text-embedding-3-small";
+    static initialize() {
+        if (!this.instance && !this.initAttempted) {
+            this.initAttempted = true;
+            try {
+                this.instance = new RealtimeXSDK({
+                    realtimex: {
+                        // @ts-ignore Desktop dev bridge key
+                        apiKey: "SXKX93J-QSWMB04-K9E0GRE-J5DA8J0"
+                    },
+                    permissions: [
+                        "api.agents", // List agents
+                        "api.workspaces", // List workspaces
+                        "api.threads", // List threads
+                        "webhook.trigger", // Trigger agents
+                        "activities.read", // Read activities
+                        "activities.write", // Write activities
+                        "llm.chat", // Chat completion
+                        "llm.embed", // Generate embeddings
+                        "llm.providers", // List LLM providers (chat, embed)
+                        "vectors.read", // Query vectors
+                        "vectors.write", // Store vectors
+                    ]
+                });
+                logger.info("RealTimeX SDK initialized successfully");
+                // @ts-ignore ping available in desktop bridge
+                this.instance.ping?.().catch(() => {
+                    logger.warn("Desktop ping failed during startup");
+                });
+            }
+            catch (error) {
+                logger.error("Failed to initialize SDK", {
+                    error: error instanceof Error ? error.message : String(error)
+                });
+                this.instance = null;
+            }
+        }
+        return this.instance;
+    }
+    static getSDK() {
+        if (!this.instance && !this.initAttempted) {
+            this.initialize();
+        }
+        return this.instance;
+    }
+    static async isAvailable() {
+        try {
+            const sdk = this.getSDK();
+            if (!sdk)
+                return false;
+            // Try to ping first (faster)
+            try {
+                // @ts-ignore ping available in desktop bridge
+                await sdk.ping();
+                return true;
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            }
+            catch (e) {
+                // Fallback to providers check if ping not available/fails
+                await sdk.llm.chatProviders();
+                return true;
+            }
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        }
+        catch (error) {
+            logger.warn("SDK not available", { error: error.message });
+            return false;
+        }
+    }
+    /**
+     * Helper to wrap a promise with a timeout
+     */
+    static async withTimeout(promise, timeoutMs, errorMessage) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let timeoutHandle;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutHandle = setTimeout(() => reject(new Error(errorMessage)), timeoutMs);
+        });
+        try {
+            const result = await Promise.race([promise, timeoutPromise]);
+            return result;
+        }
+        finally {
+            clearTimeout(timeoutHandle);
+        }
+    }
+    // Cache for default providers (avoid repeated SDK calls)
+    static defaultChatProvider = null;
+    static defaultEmbedProvider = null;
+    /**
+     * Get default chat provider/model from SDK dynamically
+     */
+    static async getDefaultChatProvider() {
+        // Return cached if available
+        if (this.defaultChatProvider) {
+            return this.defaultChatProvider;
+        }
+        const sdk = this.getSDK();
+        if (!sdk) {
+            return {
+                provider: this.DEFAULT_LLM_PROVIDER,
+                model: this.DEFAULT_LLM_MODEL,
+                isDefaultFallback: true
+            };
+        }
+        try {
+            const { providers } = await this.withTimeout(sdk.llm.chatProviders(), 30000, "Chat providers fetch timed out");
+            if (!providers || providers.length === 0) {
+                throw new Error("No LLM providers available");
+            }
+            const preferred = providers.find((item) => item.provider === this.DEFAULT_LLM_PROVIDER);
+            const chosen = preferred || providers[0];
+            const model = chosen.models?.[0]?.id || this.DEFAULT_LLM_MODEL;
+            this.defaultChatProvider = {
+                provider: chosen.provider,
+                model,
+                isDefaultFallback: !preferred
+            };
+            return this.defaultChatProvider;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        }
+        catch (error) {
+            logger.warn("Failed to get default chat provider from SDK", error);
+            return {
+                provider: this.DEFAULT_LLM_PROVIDER,
+                model: this.DEFAULT_LLM_MODEL,
+                isDefaultFallback: true
+            };
+        }
+    }
+    /**
+     * Get default embedding provider/model from SDK dynamically
+     */
+    static async getDefaultEmbedProvider() {
+        if (this.defaultEmbedProvider) {
+            return this.defaultEmbedProvider;
+        }
+        const sdk = this.getSDK();
+        if (!sdk) {
+            return {
+                provider: this.DEFAULT_EMBED_PROVIDER,
+                model: this.DEFAULT_EMBED_MODEL,
+                isDefaultFallback: true
+            };
+        }
+        try {
+            const { providers } = await this.withTimeout(sdk.llm.embedProviders(), 30000, "Embed providers fetch timed out");
+            if (!providers || providers.length === 0) {
+                throw new Error("No embedding providers available");
+            }
+            const preferred = providers.find((p) => p.provider === this.DEFAULT_EMBED_PROVIDER);
+            const chosen = preferred || providers[0];
+            const model = chosen.models?.[0]?.id || this.DEFAULT_EMBED_MODEL;
+            this.defaultEmbedProvider = {
+                provider: chosen.provider,
+                model,
+                isDefaultFallback: !preferred
+            };
+            return this.defaultEmbedProvider;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        }
+        catch (error) {
+            logger.warn("Failed to get default embed provider from SDK", error);
+            return {
+                provider: this.DEFAULT_EMBED_PROVIDER,
+                model: this.DEFAULT_EMBED_MODEL,
+                isDefaultFallback: true
+            };
+        }
+    }
+    /**
+     * Resolve LLM provider/model - use settings if available, otherwise use defaults
+     */
+    static async resolveChatProvider(settings) {
+        if (settings.llm_provider && settings.llm_model) {
+            return {
+                provider: settings.llm_provider,
+                model: settings.llm_model,
+                isDefaultFallback: false
+            };
+        }
+        return await this.getDefaultChatProvider();
+    }
+    /**
+     * Resolve embedding provider/model - use settings if available, otherwise use defaults
+     */
+    static async resolveEmbedProvider(settings) {
+        if (settings.embedding_provider && settings.embedding_model) {
+            return {
+                provider: settings.embedding_provider,
+                model: settings.embedding_model,
+                isDefaultFallback: false
+            };
+        }
+        return await this.getDefaultEmbedProvider();
+    }
+    static clearProviderCache() {
+        this.defaultChatProvider = null;
+        this.defaultEmbedProvider = null;
+    }
+}

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

@@ -0,0 +1,72 @@
+import { createClient } from "@supabase/supabase-js";
+import { config } from "../config/index.js";
+import { createLogger } from "../utils/logger.js";
+const logger = createLogger("SupabaseService");
+let serverClient = null;
+let lastConfigHash = "";
+export function isValidUrl(url) {
+    return url.startsWith("http://") || url.startsWith("https://");
+}
+function isValidAnonKey(key) {
+    return key.startsWith("eyJ") || key.startsWith("sb_publishable_");
+}
+function getConfigHash() {
+    return `${config.supabase.url}_${config.supabase.anonKey}`;
+}
+export function getServerSupabase(forceRefresh = false) {
+    const currentHash = getConfigHash();
+    if (serverClient && !forceRefresh && currentHash === lastConfigHash) {
+        return serverClient;
+    }
+    const url = config.supabase.url;
+    const key = config.supabase.anonKey;
+    if (!url || !key || !isValidUrl(url)) {
+        return null;
+    }
+    try {
+        serverClient = createClient(url, key, {
+            auth: {
+                autoRefreshToken: false,
+                persistSession: false
+            }
+        });
+        lastConfigHash = currentHash;
+        logger.info("Server Supabase client initialized");
+        return serverClient;
+    }
+    catch (error) {
+        logger.error("Failed to initialize server Supabase client", {
+            error: error instanceof Error ? error.message : String(error)
+        });
+        return null;
+    }
+}
+export function getServiceRoleSupabase() {
+    const url = config.supabase.url;
+    const key = config.supabase.serviceRoleKey;
+    if (!url || !key || !isValidUrl(url)) {
+        return null;
+    }
+    try {
+        return createClient(url, key, {
+            auth: {
+                autoRefreshToken: false,
+                persistSession: false
+            }
+        });
+    }
+    catch (error) {
+        logger.error("Failed to initialize service-role Supabase client", {
+            error: error instanceof Error ? error.message : String(error)
+        });
+        return null;
+    }
+}
+export function getSupabaseConfigFromHeaders(headers) {
+    const url = String(headers["x-supabase-url"] || "");
+    const anonKey = String(headers["x-supabase-anon-key"] || "");
+    if (!url || !anonKey || !isValidUrl(url) || !isValidAnonKey(anonKey)) {
+        return null;
+    }
+    return { url, anonKey };
+}