analyze_natural_query

Instructions

Implementation Reference

• src/analytics.ts:185-311 (handler)

  The core handler function that processes natural language queries. It uses regex pattern matching to interpret the query intent (e.g., banking performance, risk assessment, comparisons) and executes the appropriate analytics workflows, database queries, and generates structured results with execution plans and suggestions.

  async analyzeNaturalQuery(query: string, context?: string): Promise<any> {
    const lowerQuery = query.toLowerCase();
    const analysis = {
      original_query: query,
      context: context,
      interpretation: '',
      suggested_actions: [],
      results: {},
      execution_plan: []
    };
  
    try {
      // Banking-related queries
      if (lowerQuery.match(/\b(bank|banking|financial)\b.*\b(grow|growth|performance|best|worst)\b/)) {
        analysis.interpretation = 'Banking sector performance analysis';
        analysis.execution_plan.push('Get banking sector companies', 'Analyze recent performance', 'Rank by growth');
        
        const bankingCompanies = await this.db.getCompaniesBySector('banking');
        const performances = await this.analyzeCompanyPerformances(bankingCompanies, 30);
        analysis.results = {
          sector: 'Banking',
          companies_analyzed: bankingCompanies.length,
          top_performers: performances.slice(0, 5),
          analysis_period: '30 days'
        };
      }
      
      // High risk queries
      else if (lowerQuery.match(/\b(risk|risky|governance|red flag)\b/)) {
        analysis.interpretation = 'Risk assessment analysis';
        analysis.execution_plan.push('Analyze governance risks', 'Check market risks', 'Generate risk report');
        
        const companies = await this.db.getAllCompanies();
        const interlocks = await this.db.getBoardInterlocks();
        const governanceRisks = await this.getGovernanceRiskFactors(companies, interlocks);
        
        analysis.results = {
          total_companies_analyzed: companies.length,
          governance_risks: governanceRisks,
          high_risk_companies: governanceRisks.governance_red_flags.filter(f => f.severity === 'high').length,
          recommendations: this.generateRiskRecommendations(governanceRisks)
        };
      }
      
      // Comparison queries
      else if (lowerQuery.match(/\b(compare|vs|versus|against)\b/)) {
        analysis.interpretation = 'Company comparison analysis';
        
        // Try to extract company names from the query
        const companyPatterns = [
          /\b(santander|san\.mc|san)\b/i,
          /\b(bbva|bbva\.mc)\b/i,
          /\b(iberdrola|ibe\.mc|ibe)\b/i,
          /\b(telefonica|tef\.mc|tef)\b/i,
          /\b(inditex|itx\.mc|itx)\b/i
        ];
        
        const foundCompanies = [];
        for (const pattern of companyPatterns) {
          if (lowerQuery.match(pattern)) {
            const match = lowerQuery.match(pattern);
            if (match) foundCompanies.push(match[0].toUpperCase());
          }
        }
        
        if (foundCompanies.length >= 2) {
          analysis.results = await this.compareCompanies(foundCompanies, ['all']);
        } else {
          analysis.results = {
            error: 'Could not identify companies to compare',
            suggestion: 'Try: "Compare Santander vs BBVA" or use company symbols like SAN.MC vs BBVA.MC'
          };
        }
      }
      
      // Sector performance queries
      else if (lowerQuery.match(/\b(sector|industry).*\b(performance|trend|growth)\b/)) {
        const sectorMatch = lowerQuery.match(/\b(banking|energy|telecom|textile|steel|aviation|infrastructure)\b/);
        const sector = sectorMatch ? sectorMatch[1] : 'energy'; // default to energy as example
        
        analysis.interpretation = `${sector} sector performance analysis`;
        const sectorResults = await this.getSectorCorrelationAnalysis(30);
        analysis.results = {
          ...sectorResults,
          focused_sector: sector
        };
      }
      
      // Price/trend queries
      else if (lowerQuery.match(/\b(price|trend|forecast|prediction)\b/)) {
        analysis.interpretation = 'Price trend analysis';
        const companies = await this.db.getAllCompanies();
        const topPerformers = await this.db.getTopPerformers(30, 10);
        
        analysis.results = {
          analysis_type: 'Price trends over 30 days',
          top_performers: topPerformers,
          trend_summary: this.generateTrendSummary(topPerformers)
        };
      }
      
      // General fallback
      else {
        analysis.interpretation = 'General market overview';
        const companies = await this.db.getAllCompanies();
        const recent_news = await this.db.getRecentNews(undefined, 5);
        const top_performers = await this.db.getTopPerformers(7, 5);
        
        analysis.results = {
          total_companies: companies.length,
          recent_market_news: recent_news.length,
          weekly_top_performers: top_performers,
          market_snapshot: 'Current IBEX 35 overview'
        };
      }
  
      analysis.suggested_actions = this.generateActionSuggestions(analysis.interpretation, analysis.results);
      
      return analysis;
    } catch (error) {
      return {
        ...analysis,
        error: `Failed to process natural language query: ${error}`,
        fallback_suggestion: 'Try using specific tool names like get_all_companies, get_recent_news, or get_board_interlocks'
      };
    }
  }

• src/index.ts:364-377 (schema)

  The input schema definition for the 'analyze_natural_query' tool, specifying the expected parameters: a required 'query' string and optional 'context' string.

  inputSchema: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: 'Natural language query (e.g., "Which banking stocks have grown most in the last month?", "Show me companies with high governance risk", "Compare energy sector performance")',
      },
      context: {
        type: 'string',
        description: 'Optional context or previous query results to build upon',
      },
    },
    required: ['query'],
  },

• src/index.ts:657-659 (registration)

  The switch case in the CallToolRequest handler that dispatches calls to 'analyze_natural_query' to the AnalyticsManager's analyzeNaturalQuery method.

  case 'analyze_natural_query':
    result = await this.analytics.analyzeNaturalQuery((args as any)?.query, (args as any)?.context);
    break;

• src/index.ts:361-378 (registration)

  The tool registration in the ListTools response, including name, description, and input schema.

  {
    name: 'analyze_natural_query',
    description: 'Process and execute complex natural language queries about companies, financials, governance, or markets',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Natural language query (e.g., "Which banking stocks have grown most in the last month?", "Show me companies with high governance risk", "Compare energy sector performance")',
        },
        context: {
          type: 'string',
          description: 'Optional context or previous query results to build upon',
        },
      },
      required: ['query'],
    },
  },

• dist/analytics.d.ts:11-11 (schema)

  TypeScript declaration of the analyzeNaturalQuery function signature.

  analyzeNaturalQuery(query: string, context?: string): Promise<any>;