# Insights and Ask

PlayerPal reads your KPIs for you and points out what changed, where the change
is concentrated, and where you stand against anonymous peers. Every insight is
computed by fixed rules and statistical tests over figures you can already see,
with the same privacy thresholds applied. No language model computes a number
or writes the text.

[Available]

## How it works

```mermaid
flowchart LR
  K[Your KPIs<br/>privacy floors applied] --> D[Detectors<br/>fixed rules and tests]
  D --> R[Ranking<br/>importance score]
  R --> S[Insights and<br/>executive summary]
  K --> A[Ask PlayerPal<br/>fixed analytics functions]
```

1. **Inputs.** Overview KPIs, players and lifecycle figures, breakdowns by
   market, game and counterpart, and your published benchmark position. These
   are the same figures the API returns, after suppression.
2. **Detectors.** Six detectors look for material movements and patterns.
   Each records its evidence, its method and a confidence score.
3. **Ranking.** Insights are ranked by magnitude × population × business
   weight × confidence × freshness. Up to 12 are returned.
4. **Summary.** A templated executive summary picks three lead insights (a
   positive, a risk and an opportunity where available) and labels the period
   "Positive momentum", "Mixed signals" or "Needs attention".

## Insight types

| Detector | Insight types | What it reports |
|---|---|---|
| Movement | `<kpi>_up`, `<kpi>_down` | A KPI moved materially against the previous period: at least 8% relative, or 2 percentage points for rates |
| Driver | `growth_concentration`, `decline_concentration` | The market, game or counterpart carrying at least 30% of the net change in active players |
| Retention | `retention_gap`, `retention_strength` | A segment whose D7 retention is at most 0.75×, or at least 1.25×, that of your other segments |
| Portfolio | `high_potential_game` | A game with above-median retention but below-median reach |
| Benchmark | `benchmark_strength`, `benchmark_gap` | A top- or bottom-quartile position against anonymous peers, from published segments only |
| Anomaly | `activity_spike`, `activity_dip` | One of the last 14 days far outside the 14 days before it (robust z-score of at least 3.5 and a change of at least 25%) |

Each insight is also tagged with a presentation category (growth, decline,
risk, opportunity, anomaly, benchmark, retention, driver, lifecycle, loyalty or
commercial), and carries suggested next steps and follow-up questions. The
next steps are suggestions to test, not instructions.

A separate "watching" list shows up to six smaller moves (from 3%, or 1
percentage point) that did not reach the main threshold.

## Confidence

Confidence is 1 minus the p-value of a two-sided test, so 0.95 means a change
this large would appear by chance about 1 time in 20.

| Figure | Test |
|---|---|
| Counts, such as active players | Poisson test of now against before |
| Rates with a known base, such as retention | Two-proportion z-test against the rate's real base |
| Averages and rates without a known base | Grows with sample size, capped at 0.85 |
| Rates whose base is under 50 players | Never reported |

Each insight shows its confidence as high (0.95 or more), medium (0.85 or more)
or low, with the reasons: sample size, how many days of data arrived, and
whether the pattern holds across markets.

## Wording

Insight text describes association and concentration only: "concentrated
in", "coincides with". It never claims a cause. Where a finding suggests an
action, it is framed as something to test.

## Ask PlayerPal

[Available]

Ask answers plain-language questions about your data. It matches each question
to one of a fixed set of analytics functions and returns a headline, supporting
points, an optional table, follow-up questions and a note on what the answer is
based on. Each answer is computed from the same functions as the dashboards,
with the same privacy thresholds.

| Question topic | Example | What it runs |
|---|---|---|
| What changed | "What changed compared with last month?" | The top movement, risk and driver insights |
| Valuable games | "Which game is driving the most valuable players?" | Games ranked by gameplay GGR per player, with D7 retention |
| Counterparts | "Which operators are underperforming?" | Counterparts whose D7 retention sits below your median |
| Acquisition | "Where should we focus player acquisition?" | Markets that retain above your average but hold a small share of players |
| Cross-promotion | "Which games should we cross-promote?" | Which other games your largest title's players also play |
| Dormancy | "Why are players becoming dormant?" | Lifecycle movement into the dormant state |
| Network | "Where do we outperform the network?" | Your published benchmark position |
| Market retention | "Why is retention different in Finland?" | D7 retention in that market, by game and counterpart |

Questions are read up to 300 characters. A question that matches none of these
topics gets a clear "can't answer that one yet" response and a list of
questions it can answer. It never guesses.

## What it does not do

- **No language model.** Matching is by keywords and the text is templated.
  Ask does not understand arbitrary phrasing.
- **No free-form queries.** No question reaches the database directly; only
  the fixed functions run.
- **No new numbers.** Every figure in an answer is one the analytics API
  already returns to you.
- **No individual players or named peers.** Suppressed segments stay
  suppressed, and benchmark answers give quartile bands only.
- **No causal claims.** Answers show where a difference is concentrated, not
  why it happened.

## Planned: language-model rephrasing

[Planned]

A language model may later rephrase insights and Ask answers in more natural
language. It would only reword the structured results; it would not compute or
change a number. This is not built.

## Availability

Insights and Ask are available through the [KPI API](../developers/kpi-api.mdx)
with the same credential as your other KPIs. Insights can be scoped to one
market, game or counterpart, and each insight can be fetched on its own with
its evidence. The partner portal's insights workspace is
[in development](./overview.mdx#partner-portal-analytics).

## Related

  - [Metric dictionary](./metrics.mdx): 
    Definitions behind every figure an insight uses.
  
  - [Privacy thresholds](./privacy-thresholds.mdx): 
    The floors every insight inherits.
  
  - [Partner analytics](./overview.mdx): 
    Visibility tiers and where to get your figures.