orchid-ai 1.0.0 → 1.1.0

package/dist/server/index.d.ts

@@ -3,5 +3,9 @@ export type { ServerOptions, CommandServer, TrainingConfig, AIProvider, Contextu
 export { setupCommandServer, createCommandConfig, formatErrorForUser, } from './server';
 export { CommandService, } from './service';
 export { ContextualCommandService, } from './contextual-service';
+export { MongoDBRAGPlugin, enrichContextWithRAG, } from './mongodb-rag';
+export type { MongoDBConnection, RAGConfig, RAGContext, LookupResult, FindOptions, VectorSearchOptions, } from './mongodb-rag';
+export { IntentDetectionPlugin, enrichContextWithIntent, } from './intent-detection';
+export type { IntentDetectionConfig, DetectedIntent, DataNeed, FieldOperation, } from './intent-detection';
 export { getTrainingDataConfig, CommandTrainingCollector, } from './training';
 export { createTrainingConfig, validateTrainingConfig, getExpectedFileStructure, } from './training-schema';

package/dist/server/index.esm.js

@@ -13902,6 +13902,536 @@ ${additionalContext}
     }
 }
 
+/**
+ * MongoDB RAG (Retrieval-Augmented Generation) Plugin
+ *
+ * This plugin analyzes user queries and automatically retrieves relevant data
+ * from MongoDB collections to enrich the AI context before generating responses.
+ *
+ * Features:
+ * - Automatic query intent detection
+ * - Dynamic collection lookups based on schema metadata
+ * - Configurable search strategies (vector, text, filter)
+ * - Database-agnostic interface (bring your own MongoDB connection)
+ */
+/**
+ * MongoDB RAG Plugin for ContextualCommandService
+ */
+class MongoDBRAGPlugin {
+    config;
+    constructor(config) {
+        this.config = {
+            maxDocuments: 10,
+            useVectorSearch: false,
+            verboseLogging: false,
+            ...config,
+        };
+    }
+    log(message, ...args) {
+        if (this.config.verboseLogging) {
+            console.log(`[MONGODB RAG]`, message, ...args);
+        }
+    }
+    /**
+     * Analyze user query and schema to determine what data needs to be retrieved
+     */
+    async analyzeAndRetrieve(userQuery, schema, currentFormData) {
+        this.log('🔍 Analyzing query for data retrieval needs...');
+        const lookups = [];
+        let queriesExecuted = 0;
+        // Extract collections from schema
+        const collectionsToQuery = this.extractCollectionsFromSchema(schema);
+        if (collectionsToQuery.length === 0) {
+            this.log('⚠️ No collections defined in schema');
+            return {
+                lookups: [],
+                enrichedContext: '',
+                queriesExecuted: 0,
+            };
+        }
+        this.log(`📚 Found ${collectionsToQuery.length} collections in schema:`, collectionsToQuery.map(c => c.name));
+        // Determine query intent and build MongoDB queries
+        const queryIntents = this.determineQueryIntent(userQuery, collectionsToQuery, currentFormData);
+        // Execute queries
+        for (const intent of queryIntents) {
+            try {
+                this.log(`🔎 Querying collection: ${intent.collection}`, intent.query);
+                const documents = await this.config.connection.find(intent.collection, intent.query, {
+                    limit: this.config.maxDocuments,
+                    sort: intent.sort,
+                    projection: intent.projection,
+                });
+                lookups.push({
+                    collection: intent.collection,
+                    documents,
+                    query: intent.query,
+                    count: documents.length,
+                });
+                queriesExecuted++;
+                this.log(`✅ Retrieved ${documents.length} documents from ${intent.collection}`);
+            }
+            catch (error) {
+                this.log(`❌ Error querying ${intent.collection}:`, error);
+            }
+        }
+        // Build enriched context
+        const enrichedContext = this.buildEnrichedContext(lookups, schema);
+        return {
+            lookups,
+            enrichedContext,
+            queriesExecuted,
+        };
+    }
+    /**
+     * Extract collections referenced in schema
+     */
+    extractCollectionsFromSchema(schema) {
+        const collections = new Map();
+        const processProperty = (fieldName, property) => {
+            if (property.collection) {
+                if (!collections.has(property.collection)) {
+                    collections.set(property.collection, {
+                        name: property.collection,
+                        fields: [],
+                        searchable: property.searchable || false,
+                        vectorField: property.vectorField,
+                    });
+                }
+                collections.get(property.collection).fields.push(fieldName);
+            }
+            // Handle nested objects
+            if (property.type === 'object' && property.properties) {
+                for (const [nestedName, nestedProp] of Object.entries(property.properties)) {
+                    processProperty(`${fieldName}.${nestedName}`, nestedProp);
+                }
+            }
+            // Handle arrays of objects
+            if (property.type === 'array' && property.items && typeof property.items === 'object') {
+                if (property.items.properties) {
+                    for (const [itemName, itemProp] of Object.entries(property.items.properties)) {
+                        processProperty(`${fieldName}.${itemName}`, itemProp);
+                    }
+                }
+            }
+        };
+        // Process all schema properties
+        if (schema.properties) {
+            for (const [fieldName, property] of Object.entries(schema.properties)) {
+                processProperty(fieldName, property);
+            }
+        }
+        return Array.from(collections.values());
+    }
+    /**
+     * Determine query intent from user input
+     */
+    determineQueryIntent(userQuery, collections, currentFormData) {
+        const intents = [];
+        const queryLower = userQuery.toLowerCase();
+        for (const collection of collections) {
+            // Build query based on current form data and user query
+            const query = {};
+            // Check if collection name is mentioned in query
+            const collectionMentioned = queryLower.includes(collection.name.toLowerCase());
+            // Check for specific keywords that indicate data lookup
+            const needsLookup = queryLower.includes('show') ||
+                queryLower.includes('list') ||
+                queryLower.includes('find') ||
+                queryLower.includes('get') ||
+                queryLower.includes('search') ||
+                queryLower.includes('available') ||
+                queryLower.includes('options') ||
+                collectionMentioned;
+            if (!needsLookup && !collectionMentioned) {
+                // Skip collections that aren't relevant to this query
+                continue;
+            }
+            // Add filters based on current form data
+            if (currentFormData) {
+                for (const field of collection.fields) {
+                    if (currentFormData[field] && typeof currentFormData[field] === 'string') {
+                        // Add partial text match for string fields
+                        query[field] = { $regex: currentFormData[field], $options: 'i' };
+                    }
+                }
+            }
+            // Extract potential search terms from query
+            const searchTerms = this.extractSearchTerms(queryLower);
+            if (searchTerms.length > 0 && collection.searchable) {
+                // Build text search query
+                query.$text = { $search: searchTerms.join(' ') };
+            }
+            // Add intent
+            intents.push({
+                collection: collection.name,
+                query: Object.keys(query).length > 0 ? query : {}, // Empty query = get all
+                sort: { _id: -1 }, // Most recent first
+                projection: undefined, // Get all fields
+            });
+        }
+        return intents;
+    }
+    /**
+     * Extract search terms from user query
+     */
+    extractSearchTerms(query) {
+        // Remove common words
+        const stopWords = ['the', 'a', 'an', 'in', 'on', 'at', 'for', 'to', 'of', 'with', 'show', 'me', 'list', 'find', 'get', 'search', 'available', 'options'];
+        const words = query
+            .toLowerCase()
+            .replace(/[^\w\s]/g, ' ')
+            .split(/\s+/)
+            .filter(word => word.length > 2 && !stopWords.includes(word));
+        return words;
+    }
+    /**
+     * Build enriched context from retrieved documents
+     */
+    buildEnrichedContext(lookups, schema) {
+        if (lookups.length === 0) {
+            return '';
+        }
+        let context = '\n## 📊 RETRIEVED DATA FROM DATABASE\n\n';
+        context += 'The following data was retrieved from your database to help answer the query:\n\n';
+        for (const lookup of lookups) {
+            if (lookup.documents.length === 0)
+                continue;
+            context += `### Collection: ${lookup.collection}\n`;
+            context += `Found ${lookup.documents.length} matching documents:\n\n`;
+            // Format documents for AI consumption
+            lookup.documents.forEach((doc, index) => {
+                context += `**Document ${index + 1}:**\n`;
+                context += '```json\n';
+                context += JSON.stringify(doc, null, 2);
+                context += '\n```\n\n';
+            });
+        }
+        context += '**IMPORTANT:** Use this retrieved data to provide accurate, data-driven suggestions. ';
+        context += 'Reference actual values from these documents rather than making up data.\n';
+        return context;
+    }
+    /**
+     * Generate embeddings for vector search (requires OpenAI API)
+     */
+    async generateEmbedding(text) {
+        if (!this.config.embeddingApiKey) {
+            throw new Error('Embedding API key not configured');
+        }
+        // This would use OpenAI embeddings API
+        // Implementation left as exercise - requires OpenAI SDK
+        throw new Error('Vector search not yet implemented');
+    }
+}
+/**
+ * Helper function to create RAG-enhanced additional context
+ */
+async function enrichContextWithRAG(ragPlugin, userQuery, schema, currentFormData, existingContext) {
+    const ragContext = await ragPlugin.analyzeAndRetrieve(userQuery, schema, currentFormData);
+    let enrichedContext = existingContext || '';
+    if (ragContext.enrichedContext) {
+        enrichedContext = ragContext.enrichedContext + '\n\n' + enrichedContext;
+    }
+    return enrichedContext;
+}
+
+/**
+ * Intent Detection Plugin for ContextualCommandService
+ *
+ * Uses the AI model to analyze user queries and detect intent, entities,
+ * and data retrieval needs before the main AI processing. This enables:
+ * - Faster responses with pre-fetched relevant data
+ * - More accurate AI suggestions based on real database values
+ * - Context-aware data retrieval
+ * - Automatic understanding of your domain without manual configuration
+ *
+ * The AI analyzes the query and schema to determine what data to retrieve.
+ */
+/**
+ * Intent Detection Plugin (AI-Powered)
+ */
+class IntentDetectionPlugin {
+    config;
+    aiModel;
+    constructor(config) {
+        this.config = {
+            verboseLogging: false,
+            temperature: 0.3, // Low temperature for consistent intent detection
+            ...config,
+        };
+        // Create AI model instance
+        this.aiModel = this.createModelInstance();
+    }
+    createModelInstance() {
+        const { provider, apiKey, model } = this.config;
+        switch (provider.toLowerCase()) {
+            case 'openai':
+                return {
+                    client: new OpenAI({ apiKey }),
+                    model: model || 'gpt-3.5-turbo',
+                    provider: 'openai',
+                };
+            case 'claude':
+                return {
+                    client: new Anthropic({ apiKey }),
+                    model: model || 'claude-3-haiku-20240307',
+                    provider: 'claude',
+                };
+            case 'gemini':
+                return {
+                    client: new GoogleGenerativeAI(apiKey),
+                    model: model || 'gemini-1.5-flash',
+                    provider: 'gemini',
+                };
+            default:
+                throw new Error(`Unsupported provider: ${provider}`);
+        }
+    }
+    log(message, ...args) {
+        if (this.config.verboseLogging) {
+            console.log(`[INTENT DETECTION]`, message, ...args);
+        }
+    }
+    /**
+     * Detect user intent from a query using AI
+     */
+    async detectIntent(query, currentFormData = {}, schema) {
+        this.log('🔍 AI Analyzing query:', query);
+        // Build prompt for AI
+        const systemPrompt = this.buildIntentAnalysisPrompt(schema);
+        const userPrompt = this.buildUserPrompt(query, currentFormData, schema);
+        try {
+            // Call AI to analyze intent
+            const response = await this.callAI(systemPrompt, userPrompt);
+            // Parse AI response
+            const intent = this.parseIntentResponse(response, query);
+            this.log('  Action:', intent.actionType);
+            this.log('  Entities:', intent.entities);
+            this.log('  Data needs:', intent.dataNeeds.map(d => d.collection));
+            this.log('  Confidence:', `${(intent.confidence * 100).toFixed(0)}%`);
+            return intent;
+        }
+        catch (error) {
+            this.log('❌ Error detecting intent:', error);
+            // Fallback to empty intent
+            return {
+                actionType: 'unknown',
+                entities: [],
+                dataNeeds: [],
+                fieldOperations: [],
+                confidence: 0.3,
+                query,
+            };
+        }
+    }
+    /**
+     * Build system prompt for intent analysis
+     */
+    buildIntentAnalysisPrompt(schema) {
+        let prompt = `You are an intent analysis assistant. Analyze user queries to determine:
+1. What action they want to perform
+2. What entities/data they're referencing
+3. What database collections should be queried for relevant data
+
+Common action types: create, update, search, view, delete, calculate, analyze, help
+
+Return your analysis as JSON with this exact structure:
+{
+  "actionType": "create|update|search|view|delete|calculate|analyze|help",
+  "entities": ["entity1", "entity2"],
+  "dataNeeds": [
+    {
+      "collection": "collection_name",
+      "reason": "why this data is needed",
+      "query": {},
+      "limit": 20
+    }
+  ],
+  "fieldOperations": [
+    {
+      "operation": "set|add|remove",
+      "field": "fieldName",
+      "value": "optional value"
+    }
+  ],
+  "confidence": 0.8
+}`;
+        if (schema) {
+            prompt += `\n\nAvailable schema (use 'collection' properties to determine what data to retrieve):
+\`\`\`json
+${JSON.stringify(schema, null, 2)}
+\`\`\`
+
+CRITICAL: For any field with a "collection" property, add it to dataNeeds if the user query references that field.`;
+        }
+        return prompt;
+    }
+    /**
+     * Build user prompt with query and context
+     */
+    buildUserPrompt(query, currentFormData, schema) {
+        let prompt = `User Query: "${query}"`;
+        if (Object.keys(currentFormData).length > 0) {
+            prompt += `\n\nCurrent Form Data:
+\`\`\`json
+${JSON.stringify(currentFormData, null, 2)}
+\`\`\``;
+        }
+        prompt += `\n\nAnalyze this query and return the JSON intent analysis.`;
+        return prompt;
+    }
+    /**
+     * Call AI model to analyze intent
+     */
+    async callAI(systemPrompt, userPrompt) {
+        const { client, model, provider } = this.aiModel;
+        switch (provider) {
+            case 'openai': {
+                const response = await client.chat.completions.create({
+                    model,
+                    messages: [
+                        { role: 'system', content: systemPrompt },
+                        { role: 'user', content: userPrompt },
+                    ],
+                    temperature: this.config.temperature,
+                    max_tokens: 1000,
+                });
+                return response.choices[0]?.message?.content || '{}';
+            }
+            case 'claude': {
+                const response = await client.messages.create({
+                    model,
+                    system: systemPrompt,
+                    messages: [{ role: 'user', content: userPrompt }],
+                    temperature: this.config.temperature,
+                    max_tokens: 1000,
+                });
+                const firstBlock = response.content[0];
+                return firstBlock && firstBlock.type === 'text' ? firstBlock.text : '{}';
+            }
+            case 'gemini': {
+                const geminiModel = client.getGenerativeModel({
+                    model,
+                    systemInstruction: systemPrompt,
+                    generationConfig: {
+                        temperature: this.config.temperature,
+                        maxOutputTokens: 1000,
+                    },
+                });
+                const result = await geminiModel.generateContent(userPrompt);
+                return result.response?.text() || '{}';
+            }
+            default:
+                throw new Error(`Unsupported provider: ${provider}`);
+        }
+    }
+    /**
+     * Parse AI response into DetectedIntent
+     */
+    parseIntentResponse(response, query) {
+        try {
+            // Extract JSON from response
+            const jsonMatch = response.match(/\{[\s\S]*\}/);
+            if (!jsonMatch) {
+                throw new Error('No JSON found in response');
+            }
+            const parsed = JSON.parse(jsonMatch[0]);
+            return {
+                actionType: parsed.actionType || 'unknown',
+                entities: Array.isArray(parsed.entities) ? parsed.entities : [],
+                dataNeeds: Array.isArray(parsed.dataNeeds) ? parsed.dataNeeds : [],
+                fieldOperations: Array.isArray(parsed.fieldOperations) ? parsed.fieldOperations : [],
+                confidence: typeof parsed.confidence === 'number' ? parsed.confidence : 0.5,
+                query,
+            };
+        }
+        catch (error) {
+            this.log('Failed to parse AI response:', response);
+            return {
+                actionType: 'unknown',
+                entities: [],
+                dataNeeds: [],
+                fieldOperations: [],
+                confidence: 0.3,
+                query,
+            };
+        }
+    }
+    /**
+     * Build enhanced context for AI from intent and retrieved data
+     */
+    buildContextFromIntent(intent, retrievedData) {
+        let context = '';
+        // Add user intent section
+        context += `\n## 🎯 USER INTENT\n`;
+        context += `The user wants to: **${intent.actionType}**\n`;
+        if (intent.entities.length > 0) {
+            context += `Entities mentioned: ${intent.entities.join(', ')}\n`;
+        }
+        context += `Confidence: ${(intent.confidence * 100).toFixed(0)}%\n`;
+        // Add field operations if any
+        if (intent.fieldOperations.length > 0) {
+            context += `\n### Specific Field Operations:\n`;
+            intent.fieldOperations.forEach(op => {
+                context += `- ${op.operation} ${op.field}`;
+                if (op.value)
+                    context += ` to "${op.value}"`;
+                context += '\n';
+            });
+        }
+        // Add retrieved data
+        if (retrievedData && Object.keys(retrievedData).length > 0) {
+            context += `\n## 📊 AVAILABLE DATA\n`;
+            for (const [collection, data] of Object.entries(retrievedData)) {
+                if (!data || data.length === 0)
+                    continue;
+                context += `\n### ${collection.toUpperCase()} (${data.length} items):\n`;
+                // Use custom formatter if available
+                if (this.config.contextFormatters && this.config.contextFormatters[collection]) {
+                    context += this.config.contextFormatters[collection](data);
+                }
+                else {
+                    // Default formatting: JSON
+                    context += '```json\n';
+                    context += JSON.stringify(data.slice(0, 5), null, 2); // Limit to first 5 items
+                    context += '\n```\n';
+                }
+            }
+            context += `\n**💡 TIP:** Use the actual data above in your suggestions instead of making up values.\n`;
+        }
+        return context;
+    }
+}
+/**
+ * Helper function to create intent-enhanced context (AI-Powered)
+ */
+async function enrichContextWithIntent(intentPlugin, dataRetriever, userQuery, schema, currentFormData, existingContext) {
+    // AI analyzes the query to detect intent
+    const intent = await intentPlugin.detectIntent(userQuery, currentFormData, schema);
+    // Retrieve data based on AI-detected needs
+    const retrievedData = {};
+    for (const need of intent.dataNeeds) {
+        try {
+            const data = await dataRetriever(need);
+            retrievedData[need.collection] = data;
+        }
+        catch (error) {
+            console.error(`Failed to retrieve data for ${need.collection}:`, error);
+            retrievedData[need.collection] = [];
+        }
+    }
+    // Build context from intent
+    const intentContext = intentPlugin.buildContextFromIntent(intent, retrievedData);
+    // Merge with existing context
+    let enrichedContext = existingContext || '';
+    if (intentContext) {
+        enrichedContext = intentContext + '\n\n' + enrichedContext;
+    }
+    return {
+        context: enrichedContext,
+        intent,
+    };
+}
+
 /**
  * Validate training configuration
  */
@@ -14004,5 +14534,5 @@ function getExpectedFileStructure() {
     };
 }
 
-export { CommandService, CommandTrainingCollector, ContextualCommandService, createCommandConfig, createTrainingConfig, formatErrorForUser, getExpectedFileStructure, getTrainingDataConfig, setupCommandServer, validateTrainingConfig };
+export { CommandService, CommandTrainingCollector, ContextualCommandService, IntentDetectionPlugin, MongoDBRAGPlugin, createCommandConfig, createTrainingConfig, enrichContextWithIntent, enrichContextWithRAG, formatErrorForUser, getExpectedFileStructure, getTrainingDataConfig, setupCommandServer, validateTrainingConfig };
 //# sourceMappingURL=index.esm.js.map