Analyzing past studies

The five analysis modes

Step 1 — Attach the study

How you attach depends on what form the study is in.

A) It's a file (deck, PDF, survey export, spreadsheet)

Import it into a grounded Source. Supported: PDF, DOCX, PPTX, XLSX, CSV, TXT, MD (and Google-native docs from a connected drive).

{ "instanceId": "drive_main", "fileId": "1AbC...", "attachToProjectId": "proj_q3_research" }
# → a Source(file) with extracted text/tables, provenance + freshness, grounded into the vector store.
# List what you've imported:
POST /api/v1/tools/list_storage_sources   { }

Don't have it on a connected drive? Upload the bytes directly through the Files API (POST /api/v1/files) and analyze it there, or paste the transcript straight into mine_insights (next section) — no import needed.

B) It's a transcript you already have

You don't need to import anything — pass the turns straight in. The shape is the same for chat, a focus group, a debate, or a diary arc: an array of { speaker, text }.

C) It's a prior Mavera study

It already has a studyId and computed aggregates. Reference it directly in synthesize_insight, compare_studies, or detect_drift — no re-import.

Step 2 — Run the analysis (pick a mode)

Mode 1 · Mine a transcript → structured chartables + signals

The workhorse for "I have the words, give me the structure." Every chart number is derived from the text — never invented.

{
  "turns": [
    { "speaker": "Maya",  "text": "The onboarding felt endless. I almost gave up at step four." },
    { "speaker": "Devin", "text": "Same — but once it clicked the value was obvious." },
    { "speaker": "Priya", "text": "I never trusted the numbers it showed me." }
  ],
  "topic": "onboarding friction",
  "useLlm": true,
  "llmMode": "identify"
}

Returns two clearly-separated layers:

Tunables: maxSignals, minStrength (filter weak signals), topic (focuses theme extraction).

Mode 2 · Synthesize a finished study → a typed Insight

When the study already has computed aggregates, this writes the defensible insight around those numbers. It produces no statistics and rejects any uncited number in the prose.

{ "aggregates": "agg_set_q3pricing", "studyRunId": "run_8842" }
# → { insight: { headline, confidence, confidenceRationale,
#                keyFindings:[{ text, aggregateId }],     ← every finding cites a number
#                drivers:[{theme,support}], objections:[...], recommendations:[...] } }

confidence is derived in code from CI width × grounding strength × N × freshness — not the model's vibe. The confidenceRationale tells you which aggregate set the ceiling.

Mode 3 · Compare studies → meta-analysis

Same metric, two or more studies (over time, or across audiences). Reads each study's computed aggregate as fact and pools them.

{ "studyIds": ["run_apr","run_may","run_jun"], "metric": "purchase_intent", "groupBy": "time" }
# → { pooled: {mean, ci, n},
#     perStudy: [{ studyId, label, value, weight }],     ← inverse-variance weights
#     betweenStudy: [{ a, b, significance:{pValue,...} }], ← every pair tested
#     trend: [...],
#     heterogeneity: { iSquared, tauSquared } }            ← warns when studies disagree too much

If heterogeneity.iSquared > 0.5 the studies disagree enough that a single pooled number is misleading — the tool flags it. That honesty is the point: it won't hand you a clean average over apples and oranges.

Mode 4 · Detect drift → did it move?

{ "metric": "nps", "baselineRunId": "run_q1", "currentRunId": "run_q2", "threshold": { "sigma": 1 } }
# → { delta, deltaZ, significance, direction: "up|down|flat",
#     classification: "stable | moved | reversed" }

This is the node inside scheduled trackers — wire it to a cron and get alerted only when a metric actually moves past your σ threshold (see Studies & trackers).

Mode 5 · Back-test accuracy → how right were we?

The flywheel. When the real-world metric lands, measure how well the synthetic prediction held up — per test type — and publish a track record.

{ "testType": "pricing", "feedBack": true }
# → correlation / MAE / bias of pre-launch predictions vs the realized metric.
# Track record any time:
POST /api/v1/tools/get_parity_history   { }
# → latest overall parity per study type — "how much did these claims hold up".

Related: run_parity_check scores a synthetic run against a real benchmark on the same questions (Pearson/Spearman); validate_with_humans routes a slice to real panelists for a hybrid check.

Step 3 — Export the structured analysis

Any Insight or Study becomes a board-ready artifact — with uncertainty preserved (CI whiskers), cited findings, and an optional evidence appendix.

{ "source": "insight_3391", "format": "pptx", "includeEvidenceAppendix": true }
# format ∈ pptx | sheets | pdf  →  a real, downloadable file (see Files API for download).

Two pipelines worth memorizing

Old transcript → structured read → deck

mine_insights (turns)  →  synthesize_insight (the computed stats)  →  export_deck (pptx)

Two runs over time → did it hold up → alert

compare_studies (trend)  →  detect_drift (baseline vs current)  →  measure_synthetic_accuracy (vs realized)