Poseidon Analytics Engine: The AI Brain Behind Hercules Works Survey Analytics

Poseidon is the AI/ML analytics backend for the Hercules Works survey platform. When a survey is created in Hercules and answered by verified Indian consumers through the SuperJ app, Poseidon ingests the responses, builds a complete structural understanding of the survey (questions, types, skip logic, demographic axes), and turns natural-language questions into verified, charted, narrative-ready insights.

Built On. FastAPI, LangGraph, Google Gemini, DuckDB, Parquet, PostgreSQL. Python 3.11+ backend running in containers on Google Cloud.

Core Capabilities. Three concrete capabilities:

1. Natural-language chat analytics — ask questions in plain English, get verified answers in 1-3 seconds. The user types 'what is NPS by city tier?' and Poseidon returns the answer with a chart, a confidence score, and 2-3 follow-up suggestions.

2. Live streaming with persistence — the same pipeline, streamed as Server-Sent Events with a 0-100% progress bar. The backend job continues if the browser refreshes — the result is persisted and recovered on reconnect.

3. Long-form research reports — a single API call produces a 20-50 page research-grade report in Markdown, HTML, and PDF, structured around the research brief. The 18-node report pipeline runs in 5 phases with 2 conditional retry loops for quality.

The Philosophy. Schema-first, formula-driven analytics. Other tools feed raw data to an LLM and ask it to figure out the structure. Poseidon builds a typed Survey Knowledge Graph at ingestion time, and every query traverses the graph. The LLM is involved only in interpretation and narrative. Every number is verified.

The Differentiator Stack. Three-layer numerical verification (deterministic claim verifier + structural output validator + LLM self-critique). Semantic cache (78% hit rate on production traffic, sub-200ms responses). Survey Knowledge Graph (built once, traversed for every query). DuckDB on Parquet (10-20x faster than Pandas). India-first design (trained on Indian consumer data, 8+ Indian languages, cultural calibration). See advanced survey analytics for the user-facing capability.

When you type a question in the Hercules chat, Poseidon runs it through a 5-phase LangGraph pipeline. Every analytics page should explain this in some form, because it is the single most important thing that distinguishes Poseidon from generic 'ask your CSV' tools.

Phase 1 — Initialization.

• Load the Parquet schema (the shape of the data, not the rows themselves).
• Check if the question is actually relevant to the loaded survey. If the user asks about pricing but the survey is about shampoo, Poseidon refuses rather than hallucinating.
• Rewrite ambiguous queries for precision.
• Check a semantic cache (vector embeddings, threshold 0.88). If a similar prior query exists and the data fingerprint hasn't changed, return the cached result instantly.

Phase 2 — Routing. The query is classified along two axes:

• Intent — analytics, clarification (the user is being conversational), or greeting/chitchat.
• Complexity — SIMPLE / MODERATE / COMPLEX.

Internal routing distribution: roughly 78% cache hit, 11% SIMPLE, 7% MODERATE, 4% COMPLEX.

Phase 3 — Analysis (parallel sub-agents). Three agents run in parallel on every non-trivial query:

1. Data Profiler — runs DuckDB SQL to produce per-column statistics: row count, null count, cardinality, min/max/mean/median, top-5 values. The LLM never sees raw rows. It receives only this summary dict.
2. Column Selector — walks the Survey Knowledge Graph to find the exact columns that match the concepts in the query, with confidence tags (EXTRACTED = certain, INFERRED = fuzzy match, AMBIGUOUS = needs clarification).
3. Quality Checker — flags data completeness issues, outlier risk, sample-size concerns, attention-check failures, etc.

Only after the graph-resolved structural understanding is complete does the Code Generator receive the column names and the formula template. The LLM assembles SQL — it does not invent arithmetic.

Phase 4 — Verification (three independent layers). Every number in every answer passes through:

1. Numerical Claim Verifier — regex extracts every number in the generated answer. Each number is independently re-computed via a fresh DuckDB SQL query. If the value is off by more than 0.5 units (configurable tolerance), the answer is flagged and the pipeline retries. This layer is fully deterministic — no LLM.
2. Output Validator — structural checks: percentages must sum to ~100 (within rounding), NPS must be in [−100, +100], rating means must be within the declared scale, no nulls in primary result columns.
3. Self-Critique — a separate LLM pass reviews the narrative against the verified numbers. Checks for unsupported claims, internal contradictions, causal language where only correlation exists, and missing context (e.g. percentages without a base size N). Returns a score 0-10; scores below threshold trigger a revised narrative.

Internal benchmark: 99.1% numerical accuracy vs ground-truth SQL; 97.4% pass on structural validation; 94.8% pass on self-critique.

Phase 5 — Reporting.

• Cache the verified result (so the next time the user asks a similar question, it returns instantly).
• Generate the report payload (the chat answer + chart data + verification metadata).
• Run the Self-Critique node for the narrative (this is the second pass; the first was on the numbers).
• Assign a Confidence Score (low / medium / high) that the UI displays to the user.
• Generate 2-3 Quick Suggestions — the clickable follow-up questions that appear under the answer.

The Survey Knowledge Graph is the most powerful technical differentiator between Poseidon and generic AI analytics tools. Other tools feed raw survey data to an LLM and ask it to figure out the structure. Poseidon builds a typed graph at ingestion time, and every query traverses that graph.

Node Types.

Edge Types.

• Question → Column (maps_to): the question maps to this column in the data.
• Column → Formula (formula): this column type is valid input for this formula (e.g., nps_score → NPS_FORMULA).
• Question → Question (routed_from): a conditional skip-logic edge. Critical for denominator correction — when querying a conditional question, the graph supplies the correct WHERE clause so the base size is correct.
• Formula → Demographic Axis (slice_by): the formula is parameterized to accept this demographic as a GROUP BY.

Confidence Tags on Edges.

• EXTRACTED — relationship is directly declared (e.g., question type is nps, so the NPS formula edge is certain).
• INFERRED — fuzzy-match resolved the relationship with a confidence score; reviewable.
• AMBIGUOUS — multiple formulas are potentially valid (e.g., a numeric column that could be a scale or a raw count); Poseidon asks for clarification rather than guessing.

Why It Matters. The Survey Knowledge Graph is what allows Poseidon to produce correct answers consistently. The LLM is never asked to figure out the structure from raw data — it only sees the graph. This eliminates the most common AI analytics failure mode (denominator errors, scale confusion, off-by-one issues, scale misclassification) and produces analysis that's audit-grade.