Documentation
Tutorials
AGENT_GUIDE API_REFERENCE ARCHITECTURE AUTHENTICATION CHANGELOG EXAMPLES GETTING_STARTED HOSTED_SERVER HTTP_TRANSPORT SECURITY TODO TOOLS_REFERENCE

Class

AIQueryGenerator

AIQueryGenerator()

AI Query Generator class

Constructor

# new AIQueryGenerator()

Methods

# _buildFallbackSummary()

Build fallback summary when AI fails

# _buildMarkdownTable()

Build a markdown table from results Ensures exact values are included for frontend matching

# _buildSystemPrompt()

Build system prompt for query generation Loads from external markdown file with dynamic schema/examples injection

# async _callAI(systemPrompt, userMessage, maxTokens, options)

Call the AI API

Parameters:
Name Type Default Description
systemPrompt string

System prompt
userMessage string

User message
maxTokens number 1000

Max tokens for response
options Object

Additional options
jsonMode boolean

Enable JSON mode (requires prompt to mention "json")

# _cleanUserId()

Clean user ID (email) for room queries Rooms store cleaned userIds with special chars replaced

# _ensureInitialized()

Initialize AI client lazily Uses shared getAIClient utility for OpenAI/xAI support

# _fixAggregationPipeline()

Fix aggregation pipeline issues like $round/$divide inside $group MongoDB $group stage only accepts accumulators ($sum, $avg, $min, $max, etc.) $round and $divide are expressions, not accumulators

# _formatDate()

Format a date value for display

# _getResourceTypeLabel()

Get human-readable label for resourceType

# _injectSecurityBounds(querySpec, ctx) → {Object}

Inject mandatory security bounds into query This is the critical security layer - AI cannot bypass this

Parameters:
Name Type Description
querySpec Object

Generated query specification
ctx Object

Security context

Query with security bounds

Object

# _parseResponse()

Parse AI response into query specification

# _replaceDatePlaceholders()

Replace date placeholders with ISO date strings Date objects are created later by convertDates() in server.js right before execution

# _stripSecurityFields()

Strip security-related fields from query object. The AI sometimes includes userId, apiKey, etc. even though the prompt says not to. These fields are injected automatically by the security layer, so we remove them here.

# _stripSecurityFieldsFromAggregation()

Strip security-related fields from aggregation pipeline

# _validateQuerySafety()

SECURITY: Validate query for dangerous MongoDB operators These operators could allow code execution, data exfiltration, or writes

# async generateQuery(naturalQuery, securityContext) → {Promise.<Object>}

Generate a MongoDB query from natural language

Parameters:
Name Type Description
naturalQuery string

User's natural language question
securityContext Object

User context for security injection

Generated query with security bounds

Promise.<Object>

# async generateSummary()

Generate a summary of query results using AI

IMPORTANT: For clickable results, the summary MUST include:

  • A markdown table with item names/dates that match the structured results
  • Exact field values (names, dates) that the frontend can match