# Foundation Events — full reference

> The foundation event is the contract the Golden Whale Foundation emits per
> player: one event per player, carrying their latest segmentations and the
> recommendations that follow from them. This file is the complete reference —
> every field, type, enum and constraint — plus segment meanings and an example
> payload. Only the **generic** schema is public; customer-specific flavours are
> confidential and not published. Schema version: **3.0.0** (draft-07 JSON Schema).
> Source: https://developer.goldenwhale.foundation/
> JSON Schema: https://developer.goldenwhale.foundation/schemas/foundation-event-3.0.0.schema.json
> Example payload: https://developer.goldenwhale.foundation/schemas/foundation-event.example.json

## Naming

The event is called a **foundation event**: it carries more than predictions
(trigger, recommendations, game suggestions). Versions up to and including 2.9.0
called it a *prediction event* — the same contract under the old name, renamed in
2.10.0.

Versions up to and including 2.13.0 named the value block `customerLTV`; 3.0.0
renames it to `value` and removes the deprecated `Player.siteId`. Docs for the
previous contract stay at /2.10.0/.

## What's new

### 3.0.0
- `customerLTV` renamed to `value`. Contents unchanged.
- `player.siteId` removed (deprecated since 2.9.0). Use `player.metadata`.

### 2.10.0
- Renamed prediction event to foundation event.
- New root field `trigger`: `scheduled` or `session`.
- `incentiveRecommendations[].triggerId` is a free-form string, was an enum
  (`daily` / `continuous`); cadence moved to the root `trigger`.
- `player.metadata` added, `player.siteId` deprecated.

## Overview

One event per player, carrying their latest segmentations and the recommendations
that follow from them.

Two patterns run through every event:

- **`current` / `previous`** — each segmentation carries the latest prediction and
  the one before, so you can act on *movement* between segments, not just the
  current state.
- **`Target` / `Control`** — every player is tagged (`player.group`), so
  model-driven treatment stays measurable against a holdout.

An event can carry: lifetime value, churn risk (overall and per-session),
incentive usage & guidance, reactivation potential, ranked incentive
recommendations, favourite game categories, and recommended games.

## Foundation event (root object)

Only `player` is required; every prediction/recommendation field is optional and
omitted when absent.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| player | Player | yes | The player this event is about. |
| trigger | enum: `scheduled`, `session` | no | What produced this event: `scheduled` (batch run) or `session` (real-time). All predictions in one event share this trigger. |
| value | lifeTimeValuePrediction | no | Lifetime-value segmentation. |
| churnRisk | churnRiskPrediction | no | Overall churn-risk segmentation. |
| sessionChurnRisk | sessionChurnRiskPrediction | no | In-session churn-risk segmentation. |
| incentiveUsage | incentiveUsagePrediction | no | How the player uses bonuses. |
| incentiveGuidance | incentiveGuidancePrediction | no | Recommended incentive posture. |
| reactivationPotential | reactivationPotentialPrediction | no | Likelihood of winning a lapsed player back. |
| incentiveRecommendations | array of incentiveRecommendation, max 3 items | no | Ranked incentive recommendations. |
| favoriteGameCategories | array of favoriteGameCategory, max 3 items | no | Ranked favourite game categories. |
| recommendedGames | array of recommendedGame, max 3 items | no | Ranked recommended games. |

## Kafka headers

Events delivered over Kafka carry a `trigger` message header with the same value
as the root `trigger` field, so consumers can route or filter without parsing the
payload.

| Header | Value |
| --- | --- |
| `trigger` | `scheduled` (batch run) or `session` (real-time), UTF-8 |

## Player

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | yes | Player identifier (GUID or numeric). |
| cohort | number | yes | Cohort number. |
| group | enum: `Target`, `Control` | yes | Experiment assignment, for measuring model impact against a holdout. |
| metadata | object (free-form) | no | Free-form, customer-specific key/value pairs (e.g. siteId, brand, region). Not validated by the schema. |

## Segmentation predictions

Each segmentation is a wrapper with `current` (required) and `previous` (optional),
where each entry has `score` (number), `sequence` (ordinal number), `segment`
(labelled enum) and `date` (ISO-8601 date-time).

### value → lifeTimeValuePrediction / lifeTimeValuePredictionEntry
- `score`: number — Life-Time Value score
- `sequence`: number, 1–4
- `segment`: `1. Low`, `2. Core`, `3. High`, `4. VIP`
- `date`: date-time

### churnRisk → churnRiskPrediction / churnRiskPredictionEntry
- `score`: number, 0–1
- `sequence`: number, 1–4
- `segment`: `1. Low`, `2. Medium`, `3. High`, `4. Dormant`
- `date`: date-time

### sessionChurnRisk → sessionChurnRiskPrediction / sessionChurnRiskPredictionEntry
- `score`: number, 0–1 — in-session churn risk
- `sequence`: number, 1–4
- `segment`: `1. Low`, `2. Medium`, `3. High`, `4. Dormant`
- `date`: date-time

### incentiveUsage → incentiveUsagePrediction / incentiveUsagePredictionEntry
- `score`: number
- `sequence`: number, 1–4
- `segment`: `0. No bonus usage`, `1. Normal bonus usage`, `2. Increased bonus usage`, `3. Bonus abuser`
- `date`: date-time

### incentiveGuidance → incentiveGuidancePrediction / incentiveGuidancePredictionEntry
- `score`: number
- `sequence`: number, 1–4
- `segment`: `1. Increase Incentives`, `2. Continue Incentives`, `3. Limit Incentives`, `4. Avoid Incentives`
- `date`: date-time

### reactivationPotential → reactivationPotentialPrediction / reactivationPotentialPredictionEntry
- `score`: number, 0–1
- `sequence`: number, 1–3
- `segment`: `1. Low Potential`, `2. Medium Potential`, `3. High Potential`
- `date`: date-time

## Recommendation arrays

### incentiveRecommendation — items of `incentiveRecommendations`
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| recommendationId | string | yes | Unique identifier for this recommendation emission |
| rank | number | yes | 1-based rank of the recommendation for the player |
| score | number | yes | |
| incentiveId | string | yes | Identifier of the recommended incentive type |
| incentiveName | string | yes | |
| amount | number | yes | |
| triggerId | string | no | Identifier of the trigger this recommendation came from. Changed in 2.10.0: was an enum (`daily`/`continuous`); cadence now lives on the root `trigger` field. |

### favoriteGameCategory — items of `favoriteGameCategories` (all fields required)
| Field | Type |
| --- | --- |
| rank | number |
| score | number |
| categoryId | string |
| categoryName | string |

### recommendedGame — items of `recommendedGames` (all fields required)
| Field | Type |
| --- | --- |
| rank | number |
| score | number |
| gameId | string |
| gameName | string |
| categoryId | string |
| categoryName | string |

## Example payload

```json
{
  "player": {
    "id": "PLAYER-ID-AS-GUID-OR-NUMERIC-123",
    "cohort": 1,
    "group": "Target",
    "metadata": {
      "siteId": 123,
      "brand": "golden-whale-casino",
      "region": "EU"
    }
  },
  "trigger": "scheduled",
  "value": {
    "current": {
      "score": 1234.45,
      "sequence": 4,
      "segment": "4. VIP",
      "date": "2023-11-20T13:45:00+02:00"
    },
    "previous": {
      "score": 1230.45,
      "sequence": 4,
      "segment": "4. VIP",
      "date": "2023-11-19T13:45:00+02:00"
    }
  },
  "sessionChurnRisk": {
    "current": {
      "score": 0.2,
      "sequence": 2,
      "segment": "2. Medium",
      "date": "2023-11-20T13:45:00+02:00"
    },
    "previous": {
      "score": 0.19634,
      "sequence": 1,
      "segment": "1. Low",
      "date": "2023-11-12T13:45:00+02:00"
    }
  },
  "churnRisk": {
    "current": {
      "score": 0.89634,
      "sequence": 3,
      "segment": "3. High",
      "date": "2023-11-20T13:45:00+02:00"
    }
  },
  "incentiveUsage": {
    "current": {
      "score": 4,
      "sequence": 4,
      "segment": "3. Bonus abuser",
      "date": "2023-11-20T13:45:00+02:00"
    }
  },
  "incentiveGuidance": {
    "current": {
      "score": 2,
      "sequence": 2,
      "segment": "2. Continue Incentives",
      "date": "2023-11-20T13:45:00+02:00"
    },
    "previous": {
      "score": 1,
      "sequence": 1,
      "segment": "1. Increase Incentives",
      "date": "2023-11-19T13:45:00+02:00"
    }
  },
  "reactivationPotential": {
    "current": {
      "score": 0.78,
      "sequence": 3,
      "segment": "3. High Potential",
      "date": "2023-11-20T13:45:00+02:00"
    }
  },
  "incentiveRecommendations": [
    {
      "recommendationId": "d164def1-c3c2-401e-8a09-1928f8765b0d",
      "rank": 1,
      "score": 87.17,
      "incentiveId": "1",
      "incentiveName": "Freebet",
      "amount": 2000
    },
    {
      "recommendationId": "24f4d856-b42d-4f38-ac62-cdbc6a0e85a8",
      "rank": 2,
      "score": 72.9,
      "incentiveId": "1",
      "incentiveName": "Freebet",
      "amount": 200
    }
  ],
  "favoriteGameCategories": [
    {
      "rank": 1,
      "score": 0.9876,
      "categoryId": "C-1",
      "categoryName": "Casino"
    }
  ],
  "recommendedGames": [
    {
      "rank": 1,
      "score": 0.7654,
      "gameId": "G-123",
      "gameName": "Golden Whale Super Spinner",
      "categoryId": "C-1",
      "categoryName": "Casino"
    }
  ]
}
```

## Example payload as CSV

The same event flattened to one CSV row. `FoundationEvent.model_dump_csv()`
emits header + one row: nested objects become `_`-joined snake_case columns,
bounded lists widen into 1-based indexed columns (`incentive_recommendations_1_score`,
capped at three via `maxItems`), and unbounded values such as free-form
`metadata` stay one JSON-text column. The column set is derived from the model,
not the event, so every row carries every column. Downloadable at
/foundation-event.example.csv

```csv
player_id,player_cohort,player_group,player_metadata,trigger,value_current_score,value_current_sequence,value_current_date,value_current_segment,value_previous_score,value_previous_sequence,value_previous_date,value_previous_segment,churn_risk_current_score,churn_risk_current_sequence,churn_risk_current_date,churn_risk_current_segment,churn_risk_previous_score,churn_risk_previous_sequence,churn_risk_previous_date,churn_risk_previous_segment,session_churn_risk_current_score,session_churn_risk_current_sequence,session_churn_risk_current_date,session_churn_risk_current_segment,session_churn_risk_previous_score,session_churn_risk_previous_sequence,session_churn_risk_previous_date,session_churn_risk_previous_segment,incentive_usage_current_score,incentive_usage_current_sequence,incentive_usage_current_date,incentive_usage_current_segment,incentive_usage_previous_score,incentive_usage_previous_sequence,incentive_usage_previous_date,incentive_usage_previous_segment,incentive_guidance_current_score,incentive_guidance_current_sequence,incentive_guidance_current_date,incentive_guidance_current_segment,incentive_guidance_previous_score,incentive_guidance_previous_sequence,incentive_guidance_previous_date,incentive_guidance_previous_segment,incentive_recommendations_1_recommendation_id,incentive_recommendations_1_rank,incentive_recommendations_1_score,incentive_recommendations_1_incentive_id,incentive_recommendations_1_incentive_name,incentive_recommendations_1_amount,incentive_recommendations_1_trigger_id,incentive_recommendations_1_metadata,incentive_recommendations_2_recommendation_id,incentive_recommendations_2_rank,incentive_recommendations_2_score,incentive_recommendations_2_incentive_id,incentive_recommendations_2_incentive_name,incentive_recommendations_2_amount,incentive_recommendations_2_trigger_id,incentive_recommendations_2_metadata,incentive_recommendations_3_recommendation_id,incentive_recommendations_3_rank,incentive_recommendations_3_score,incentive_recommendations_3_incentive_id,incentive_recommendations_3_incentive_name,incentive_recommendations_3_amount,incentive_recommendations_3_trigger_id,incentive_recommendations_3_metadata,reactivation_potential_current_score,reactivation_potential_current_sequence,reactivation_potential_current_date,reactivation_potential_current_segment,reactivation_potential_previous_score,reactivation_potential_previous_sequence,reactivation_potential_previous_date,reactivation_potential_previous_segment,favorite_game_categories_1_rank,favorite_game_categories_1_score,favorite_game_categories_1_category_id,favorite_game_categories_1_category_name,favorite_game_categories_2_rank,favorite_game_categories_2_score,favorite_game_categories_2_category_id,favorite_game_categories_2_category_name,favorite_game_categories_3_rank,favorite_game_categories_3_score,favorite_game_categories_3_category_id,favorite_game_categories_3_category_name,recommended_games_1_rank,recommended_games_1_score,recommended_games_1_game_id,recommended_games_1_game_name,recommended_games_1_category_id,recommended_games_1_category_name,recommended_games_2_rank,recommended_games_2_score,recommended_games_2_game_id,recommended_games_2_game_name,recommended_games_2_category_id,recommended_games_2_category_name,recommended_games_3_rank,recommended_games_3_score,recommended_games_3_game_id,recommended_games_3_game_name,recommended_games_3_category_id,recommended_games_3_category_name
PLAYER-ID-AS-GUID-OR-NUMERIC-123,1,Target,"{""siteId"":123,""brand"":""golden-whale-casino"",""region"":""EU""}",scheduled,1234.45,4,2023-11-20T13:45:00+02:00,4. VIP,1230.45,4,2023-11-19T13:45:00+02:00,4. VIP,0.89634,3,2023-11-20T13:45:00+02:00,3. High,,,,,0.2,2,2023-11-20T13:45:00+02:00,2. Medium,0.19634,1,2023-11-12T13:45:00+02:00,1. Low,4.0,4,2023-11-20T13:45:00+02:00,3. Bonus abuser,,,,,2.0,2,2023-11-20T13:45:00+02:00,2. Continue Incentives,1.0,1,2023-11-19T13:45:00+02:00,1. Increase Incentives,d164def1-c3c2-401e-8a09-1928f8765b0d,1,87.17,1,Freebet,2000.0,,,24f4d856-b42d-4f38-ac62-cdbc6a0e85a8,2,72.9,1,Freebet,200.0,,,,,,,,,,,0.78,3,2023-11-20T13:45:00+02:00,3. High Potential,,,,,1.0,0.9876,C-1,Casino,,,,,,,,,1.0,0.7654,G-123,Golden Whale Super Spinner,C-1,Casino,,,,,,,,,,,,
```

## Segment meanings

The segment **values** below match the published schema. The **described meanings**
are a first draft inferred from the names and still need product review before they
should be treated as authoritative.

### Lifetime value (`value`) — higher score/sequence = greater lifetime value
- `1. Low` — Lowest-value players; minimal expected spend.
- `2. Core` — Mid-tier players forming the bulk of the base.
- `3. High` — High-value players with strong expected spend.
- `4. VIP` — Top-value players; highest expected lifetime value.

### Churn risk (`churnRisk`) — score 0–1; higher = greater churn risk
- `1. Low` — Low probability of churning; engaged players.
- `2. Medium` — Moderate churn probability; watch for disengagement.
- `3. High` — High probability of churning soon.
- `4. Dormant` — Players treated as already lapsed / inactive.

### Session churn risk (`sessionChurnRisk`) — score 0–1; higher = greater in-session churn risk
- `1. Low` — Low probability of ending the current session early.
- `2. Medium` — Moderate probability of leaving the session.
- `3. High` — High probability of ending the session soon.
- `4. Dormant` — Session treated as effectively ended / no longer active.

### Incentive usage (`incentiveUsage`) — higher = heavier (potentially abusive) bonus usage
- `0. No bonus usage` — Player does not engage with bonuses at all.
- `1. Normal bonus usage` — Healthy, expected level of bonus usage.
- `2. Increased bonus usage` — Above-average bonus usage; lean toward exploitation.
- `3. Bonus abuser` — Usage pattern consistent with bonus abuse.

### Incentive guidance (`incentiveGuidance`) — recommended posture, not a risk score
- `1. Increase Incentives` — Recommend offering more incentives to this player.
- `2. Continue Incentives` — Maintain the current level of incentives.
- `3. Limit Incentives` — Pull back; offer fewer or smaller incentives.
- `4. Avoid Incentives` — Do not offer incentives to this player.

### Reactivation potential (`reactivationPotential`) — score 0–1; higher = greater reactivation potential
- `1. Low Potential` — Low likelihood of being won back if lapsed.
- `2. Medium Potential` — Moderate likelihood of reactivating.
- `3. High Potential` — Strong likelihood of reactivating with the right treatment.