rag_query

Instructions

Implementation Reference

• src/handlers/tools.ts:1221-1270 (handler)

  Handler for the rag_query tool. Extracts 'question' from args, uses the RAGIntegrator singleton to perform a cache-first (LAZY-RAG) query, and returns the result with cache hit/miss status and elapsed time.

  private async handleRagQuery(args: any): Promise<CallToolResult> {
    const { question } = args;
  
    if (!question) {
      return {
        content: [{
          type: 'text',
          text: '❌ Question is required'
        }],
        isError: true
      };
    }
  
    try {
      const rag = getRAGIntegrator();
  
      if (!rag.isConfigured()) {
        return {
          content: [{
            type: 'text',
            text: '❌ XAI_API_KEY not configured. Set the environment variable to enable RAG queries.'
          }],
          isError: true
        };
      }
  
      const result = await rag.query(question);
  
      const status = result.cached ? '⚡ CACHE HIT' : '🔄 API CALL';
      const elapsed = result.cached
        ? `${(result.elapsed * 1000).toFixed(3)}ms`
        : `${result.elapsed.toFixed(2)}s`;
  
      return {
        content: [{
          type: 'text',
          text: `${status} (${elapsed})\n\n${result.answer}`
        }]
      };
    } catch (error: unknown) {
      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
      return {
        content: [{
          type: 'text',
          text: `❌ RAG Query Failed: ${errorMessage}`
        }],
        isError: true
      };
    }
  }

• src/handlers/tools.ts:221-232 (schema)

  Tool schema definition: name ('rag_query'), description, and inputSchema requiring a 'question' string.

  // RAG Tools - LAZY-RAG Cache + xAI Collections
  {
    name: 'rag_query',
    description: 'Ask a question with RAG-enhanced context from xAI Collections. Uses LAZY-RAG cache for 100,000x speedup on repeated queries.',
    inputSchema: {
      type: 'object',
      properties: {
        question: { type: 'string', description: 'Question to ask' }
      },
      required: ['question']
    }
  },

• src/handlers/tools.ts:295-300 (registration)

  Registration in the callTool switch-case that dispatches 'rag_query' to handleRagQuery.

  case 'rag_query':
    return await this.handleRagQuery(args);
  case 'rag_cache_stats':
    return await this.handleRagCacheStats(args);
  case 'rag_cache_clear':
    return await this.handleRagCacheClear(args);

• src/rag/index.ts:57-88 (helper)

  RAGIntegrator.query() - Core LAZY-RAG pattern: cache-first lookup via SHA256 key, then fallback to xAI API call with caching of the result.

  async query(question: string): Promise<RAGQueryResult> {
    const start = Date.now();
    const cacheKey = this.cache.generateKey(question, 'query', this.collectionId);
  
    // Check cache first
    const cached = this.cache.get(cacheKey);
    if (cached !== undefined) {
      return {
        answer: cached,
        cached: true,
        elapsed: (Date.now() - start) / 1000,
        cacheKey
      };
    }
  
    // Cache miss - call API
    if (!this.client) {
      throw new Error('XAI_API_KEY not configured');
    }
  
    const answer = await this.client.queryWithContext({ question });
  
    // Store in cache
    this.cache.set(cacheKey, answer);
  
    return {
      answer,
      cached: false,
      elapsed: (Date.now() - start) / 1000,
      cacheKey
    };
  }

• src/rag/xai-client.ts:84-130 (helper)

  XAIClient.queryWithContext() - Sends a chat completion request with a system prompt providing FAF project context and the user's question to the xAI API.

    async queryWithContext(params: {
      question: string;
      systemPrompt?: string;
      context?: string;
    }): Promise<string> {
      const systemContent = params.systemPrompt || this.getDefaultSystemPrompt(params.context);
  
      const messages: ChatMessage[] = [
        { role: 'system', content: systemContent },
        { role: 'user', content: params.question }
      ];
  
      const response = await this.chat(messages);
      return response.content;
    }
  
    /**
     * Default system prompt with FAF project context
     */
    private getDefaultSystemPrompt(additionalContext?: string): string {
      let prompt = `You are a helpful assistant with access to FAF (Foundational AI-context Format) project context.
  
  FAF Project Context:
  - Project: xai-faf-rag
  - Birth Certificate ID: FAF-2026-XAIFAFRA-WXGD
  - FAF Version: 2.5.0
  - Purpose: Cache-first RAG using Grok Collections
  - Tech Stack: Python + Rust, xai-sdk, LAZY-RAG cache layer
  - Collection: FAF Elite Palace
  - Key Features: LAZY-RAG caching (0.003ms hits), Collections search, .faf file sync
  
  Answer questions accurately based on this context. Be concise.`;
  
      if (additionalContext) {
        prompt += `\n\nAdditional Context:\n${additionalContext}`;
      }
  
      return prompt;
    }
  
    /**
     * Check if API key is configured
     */
    isConfigured(): boolean {
      return !!this.apiKey && this.apiKey.length > 0;
    }
  }