Skip to main content

AI Insight Engine

The AI Insight Engine​

Version: 1.0 Date: September 11, 2025

1. Feature Overview & Objective​

The AI Insight Engine is the core intelligence layer of the ChainAlign platform. Its objective is to provide a suite of well-defined backend services that the frontend can consume to deliver proactive, contextual, and actionable insights on every page. These services will translate the complex outputs of the various AI models and business logic engines into simple, intuitive user experiences, from the personalized Home Screen to the executive "Live Slide" [cite: your feedback, Your previous message].

2. Core Design Principles​

  • Insight-Driven, Not Data-Driven: Every service must return a conclusion or a story, not just raw data. This is the foundation of the "Live McKinsey Slide" philosophy [cite: your feedback, Your previous message].

  • Context is King: Services must be context-aware, taking inputs like the user's role, the current S&OP cycle step, and the live conversation to deliver relevant information.

  • The "10-Second Rule": The outputs of these services must be designed for instant comprehension by an executive [cite: your feedback].

3. Key Insight Services for Frontend Consumption​

Here is the definitive list of key services your frontend will consume to power its intelligent features.

3.1. The PageContextInsightService​

  • a. Objective: To act as the primary workhorse for proactively populating any given page with relevant, high-level insights. This service is the "brains" behind the personalized Home Screen and the various workbenches.

  • b. How it Works: The frontend makes a single call to this service upon loading a page, providing the context. The service then orchestrates calls to the backend engines.

    • Frontend Request: GET /api/insights/page-context?page=Home&role=DemandPlanner

    • Backend Orchestration:

      1. Identifies the user's role and the current S&OP cycle status.

      2. Queries the Vector Database Service for relevant historical insights [cite: your list].

      3. Queries the Data Governance & Quality Service for relevant data health alerts [cite: your list].

      4. Uses the Insight Generation Service to generate fresh descriptive and diagnostic insights based on the current data [cite: your list].

    • Backend Response (JSON): A structured payload containing a prioritized list of insights, alerts, and news items for the "Background Intelligence" panel and "Action Required" list on the Home Screen [cite: your feedback].

3.2. The ActionTitleService​

  • a. Objective: To generate the dynamic, McKinsey-style "Action Title" for the executive-facing dashboards. This is a specialized, high-value service [cite: Your previous message, your feedback].

  • b. How it Works: This service takes a snapshot of the most critical data for a given plan and uses Gemini to craft a narrative headline.

    • Frontend Request: POST /api/insights/action-title with a JSON payload of the key KPIs for the "Recommendation Package."

    • Backend Orchestration: The service formats the KPIs into a structured prompt for the Insight Generation Service (Gemini), instructing it to return a single, executive-ready sentence summarizing the core decision and its trade-offs.

    • Backend Response (JSON): { "title": "Production capacity must increase 23% to meet Q1 demand without $2.3M revenue risk" } [cite: opspilot_dashboard_mockup.html].

3.3. The ConversationalInsightService (RAG)​

  • a. Objective: To power the real-time, in-meeting "Contextual Insight Cards" based on the live conversation.

  • b. How it Works: This service is triggered continuously by the live transcription feed.

    • Frontend Request: A WebSocket event or API call sends the latest transcript chunk to the backend: POST /api/insights/from-conversation with { "text": "Let's discuss the Widget Pro Max forecast accuracy..." }.

    • Backend Orchestration: This triggers the full RAG workflow. It uses the Embedding Service to vectorize the user's speech, queries the Vector Database Service to retrieve relevant historical context, and then uses the Insight Generation Service to generate a concise, relevant insight [cite: your list, Your previous message].

    • Backend Response (JSON): A structured "Insight Card" object is pushed back to the client via the real-time channel.

3.4. The IntelligentChartingService​

  • a. Objective: To offload the logic of chart design from the frontend, ensuring every visualization is a clear "visual argument" [cite: Your previous message].

  • b. How it Works: The frontend sends the raw data and a goal, and the backend returns the full chart configuration.

    • Frontend Request: POST /api/insights/chart with a payload like { "goal": "show_variance", "data": [...] }.

    • Backend Orchestration: The Intelligent Charting Engine Service analyzes the data and the goal. It selects the optimal chart type (e.g., Waterfall for variance), defines the color strategy (e.g., muted gray for baseline, amber for the gap), and generates the "Action Title" and annotations for the chart [cite: your list, your feedback].

    • Backend Response (JSON): A full configuration object that a frontend library like Recharts can use to render the chart, no client-side design logic needed.

3.5. The ScenarioImpactService​

  • a. Objective: To provide an interface for the frontend to run "what-if" scenarios and get back the full impact analysis.

  • b. How it Works: This is the primary interface to the powerful Constraint Intelligence Engine [cite: your list].

    • Frontend Request: POST /api/scenario/run with a payload defining the scenario parameters (e.g., { "action": "increase_safety_stock", "value": "30%" }).

    • Backend Orchestration: The service calls the Constraint Intelligence Engine Service to run both the deterministic calculations and the full Monte Carlo simulation [cite: your list]. It also calls the Plan Integrity Service to ensure the scenario is valid [cite: your list].

    • Backend Response (JSON): A detailed, structured object containing the side-by-side comparison data for the "Decision-Focused Layout" and the full probabilistic results [cite: your feedback].

This suite of services provides a clear and powerful architecture for your frontend to consume, allowing you to build that magical, intelligent, and deeply trusted S&OP experience on every single page.​

Backend Enhancements Supporting AI Insight Engine (as of September 11, 2025)​

Significant foundational work has been completed in the backend to support these intelligent services:

  1. Zep Memory Integration: Implemented for persistent conversation history, crucial for contextual AI interactions.
  2. Enhanced Data Ingestion & Governance:
    • Flexible ingestion from Google Sheets, PostgreSQL, and CSV.
    • AI-assisted data understanding and mapping (including PII identification) in mappingAssistant.js.
    • Robust input validation (performAutomatedSanityCheck in ingestionService.js).
  3. Immutable Audit Trail: audit_log table, logAuditEvent function, and integration into critical actions (connections, data ingestion).
  4. Role-Based Access Control (RBAC): Comprehensive database schemas for users, roles, and permissions, with verifyToken and checkPermission middleware for secure access control.
  5. AI Insight Engine (RAG Core):
    • pgvector extension enabled and insights table created for vector storage.
    • embeddingService.js implemented for Gemini-powered text embeddings.
    • vectorDbService.js implemented for storing and retrieving similar insights.

These backend components provide the robust foundation for the intelligent features described in this document.​