Analytics compiler hierarchy and CallSight parity

Status: Current | Last reviewed: 2026-10-02

Analytics now supports rich annotation, embedding preparation, hierarchical reports, separate dataset memory pages and a cached opening briefing. This guide distinguishes the source behavior from the configurable Studio implementation. See validation for completed runs on the original data.

Studio pipeline

1. Bulk ingestion stores encrypted source and a durable per-file manifest.
2. Shared transcription and PII services prepare canonical ordered transcripts.
3. Annotation and embedding compilers operate on the prepared text. Rich annotations retain intent, primary/secondary drivers, constrained root causes, resolution, friction/escalation tags and scores, novelty, confidence, channel conflict and exact source-turn evidence. Server provenance includes compiler version, vocabulary version and profile hash.
4. A report job builds completed child windows before parent windows. Each parent recomputes population aggregates and uses its child narratives; it never sums overlapping tag counts into unique contacts.
5. Separate dataset memory synthesis consumes exact full-release aggregates, evidence and the completed hierarchy. Driver summary and executive summary are distinct outputs, not copies of one weekly narrative.
6. Publication freezes a typed analysis snapshot. Chat queries its operational relations, reports, evidence graph and prepared transcript release.
7. The briefing worker composes a landing view from published outputs on its own cadence. Interactive anomalies remain a separate runtime tool.

Configuration actually supported

Scope	Controls
Transcript preparation	Format, speaker mapping, search roles/language, transcription/redaction integrations, retention and request budgets
Rich annotation	Model, instructions, intent vocabulary, allowed driver/root-cause pairs, friction/escalation vocabularies, evidence requirements and chunk limits
Embeddings	Integration/model, dimensions, chunk size/overlap; query embeddings use the release's exact profile
Report hierarchy	Enabled/model, native or imported annotations, anchor, explicit from/through, named tiers (1–2,160 hours), child dependency and required child coverage
Report limits	Maximum windows, model-call budget, representative sample size, narrative instructions, memory-page enablement
Runtime analysis	Enabled tools, response model, answer review, diagnostic context relations, iteration/tool/output budgets, pinned snapshot
Anomalies	Baseline multiplier, across-group z threshold and minimum samples
Scenarios	Explicit cost per minute, billing category, affected area and containment cap
Briefing	Enabled, focus instructions and independent refresh cadence

The validated schemas are preparation-config.ts, report-config.ts and analysis-config.ts in apps/ai-manager/lib/analytics. Tiers use fixed elapsed UTC hours and an explicit anchor. Arbitrary calendar/timezone/DST windows and pluggable statistical detectors are not implemented. The demo backfill uses 6-hour → daily → weekly tiers; one-hour leaf tiers are also supported. Original imported reports retain their one-hour windows.

Storage, recovery and security

PostgreSQL stores immutable releases, typed operational rows, artifact bodies, version/parent lineage, citations, private chat state and durable job checkpoints. pgvector and full-text indexes serve retrieval; encrypted raw source uses the shared assets store. Models cannot access credentials or arbitrary relations. The Python bridge accepts fixed tool names and translates guarded Trino SELECTs to parameterized, tenant/snapshot-scoped PostgreSQL queries. Typed import rejects unknown columns and invalid values. RLS and composite foreign keys enforce scope.

Report signatures include the data/configuration and child inputs. Retries reuse completed windows and preserve consumed model calls. Budgets are reserved before provider requests. Ready snapshots reject mutation; dataset erasure can cascade through their contents. Report and briefing workers use leases and heartbeats. Operational source annotations can be imported for strict baseline comparisons; native recompilation is separately identified because a different model may classify a conversation differently.

Missing operational values stay unknown. A conversation's elapsed duration does not silently become AHT. Escalation-trigger aggregates use confirmed transfer flags. Native-only reports omit transfer rates when the source does not establish them. Canonical prepared text is authoritative for evidence; original source positions are preserved and extra legacy CI utterances are separately reported.

The current annotation, embedding, narrative and chat adapters use Studio OpenAI integrations. Transcription and managed redaction reuse the shared provider adapters. AWS is needed only to export the original data, not to serve a migrated snapshot. Additional generative providers require capability adapters rather than passing AWS credentials into the analytical runtime.

How the original processing works

Conversation annotation

The annotator uses dataset-specific taxonomies. An intent leaf describes what the caller asks for; the driver and its allowed root cause describe why the conversation occurs. Frictions and escalation triggers are separate multi-label fields. For example, a flight-change request can have a digital-channel-failure driver and a research-hold friction.

Annotations also carry evidence spans, model/prompt/taxonomy provenance, confidence and prototypicality scores for representative examples. Prototypicality measures how well a conversation illustrates its tag; confidence measures whether the classification is supported. The model-assigned novelty score is a separate signal, not a statistical significance test.

The original model prompt sees the first 40 nonempty turns. Preserve the richer output contract without copying that truncation. Synthetic fixture annotations can bypass model generation through expected_annotation; retain their provenance and keep them separate from independently inferred annotations.

Hierarchical trend compilation

There are three hardcoded tiers: per_interval (one hour), daily and weekly. Each has its own Step Functions state machine: compute window → compile trend → load trend → load citations. These are independent jobs; the main ingestion state machine does not automatically execute the complete trend hierarchy.

At the hourly level the compiler queries annotations for the window and the immediately preceding equal-duration window. It gathers driver/root-cause, friction and escalation counts, sampled conversation summaries and evidence. The annotation selection favors confident examples and includes novelty and escalation candidates; the final prompt bounds summaries and quotes.

Daily and weekly compilation read the child report bodies and query the underlying annotations again for the parent window and its comparison window. The parent narrative therefore has both child context and parent-level facts. The model writes a short explanation of changes and unusual patterns. Code renders the structured aggregate block and creates window-scoped metric citations; the model receives allowed citation IDs before writing its prose.

The compiler records child versions in the parent input signature, skips an already active version and backfills parent links onto consumed children. Child coverage is not enforced: a parent can use the available children without proving that every expected child window exists.

The automatic weekly calculation uses completed Monday-based weeks. Explicit window bounds override that calculation; the demo documentation describes historical Friday–Thursday backfills. All three trend schedules are disabled in the checked-in Terraform, intentionally for the historical demo. Opening the chat application reads existing artifacts; it does not rerun this pipeline.

Executive summaries, briefing and live analysis

compile_memory creates a dataset-wide executive-summary artifact from annotation aggregates, selected conversation summaries and, when present, the latest weekly report. Its structured KPIs and citations accompany generated prose. This is a different artifact from the opening briefing.

The opening-briefing prompt explicitly reads the latest daily and weekly reports and excludes memory-page reads. It then composes the top focus, secondary findings and performance strip. The API caches completed event streams for 24 hours per profile/dataset/manual cache version. Generation happens on a cache miss, not on a durable briefing schedule.

Interactive chat can also query the warehouse and run detect_anomalies. That tool supports volume, AHT, containment, escalation, repeat-call and CSAT across dimensions such as hub, queue, channel, intent, driver and root cause. It compares recent values with an earlier baseline, computes a z-score of the changes across groups, and flags absolute scores of at least 1.5. For the leading flagged group, it searches the daily series for the split with the largest difference between before/after means.

That is a separate runtime tool, not a statistical detector built into every hourly/daily/weekly compiler stage. The repository explicitly defers adding anomalies to compiled trends. Likewise, the intent taxonomy hierarchy and the time-window hierarchy are distinct; the source does not implement arbitrary hierarchical topic discovery.

Source evidence and validation

Source revision: 720c2a48c3d7599ec2d987cdff0283e5fea1d83b in trueserve-cciq. The original compiler is aws-conversation-intelligence/lambda_src/compiler_handler.py; the interactive tools live under contact-center-iq/backend/tools.

analysis.integration.test.ts exercises the real hierarchy, restart checkpoints, legacy release compatibility, exact transfer-scoped citations, immutable imports, tenant isolation and erasure in a disposable PostgreSQL database. Python tests cover SQL scoping, unsafe-query rejection and array/date translation. Provider and demo runs, including measured side-by-side results, are in validation.