> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Glossary
> Canonical terminology for the KaireonAI platform. All documentation uses these terms consistently.
This glossary is the single source of truth for KaireonAI terminology. Every documentation page references these definitions. When in doubt, use the term exactly as it appears here.
## Core Entities
A decisioning candidate — a product, service, message, or action that can be recommended to a customer. Offers belong to a Category (and optionally a Sub-Category) and carry priority, budget, scheduling, decisioning gates, and custom field values.
**API field:** Referenced as `offer` in API requests and responses. Created via `POST /api/v1/offers`.
**DB note:** The database table was originally named `actions` (visible in baseline migrations). The current Prisma model is `Offer`, mapped to the `offers` table. Always use "Offer" in documentation and UI.
**Not to be confused with:** Creative (the content variant delivered through a specific Channel for an Offer).
A content variant attached to an Offer and a Channel. Creatives define what the customer actually sees — email HTML, push notification text, in-app modal content, banner images, etc. Each Offer can have multiple Creatives across different Channels and Placements. Creatives support A/B test variants with traffic weighting.
**API field:** Referenced as `creative` in API requests and responses. Created via `POST /api/v1/creatives`.
**DB note:** The database table was originally named `treatments` (visible in baseline migrations). The current Prisma model is `Creative`, mapped to the `creatives` table. Always use "Creative" in documentation and UI.
**Not to be confused with:** Offer (the business-level candidate) or Content Item (CMS-managed content from the Content module).
A top-level grouping for Offers (e.g., "Credit Cards", "Insurance", "Rewards"). Categories define custom fields — including computed fields with formulas — that apply to all Offers within them. Categories control display order and UI color theming.
**API field:** Referenced as `category` in Offer payloads. Managed via `POST /api/v1/categories`.
**DB note:** The database table was originally named `business_issues` (visible in baseline migrations). The current Prisma model is `Category`, mapped to the `categories` table. Always use "Category" in documentation and UI.
**Not to be confused with:** Sub-Category (a child grouping under a Category).
A child grouping under a Category (e.g., "Travel Rewards" under "Credit Cards"). Sub-Categories can define their own custom fields in addition to inheriting the parent Category's fields. Offers reference both a Category and optionally a Sub-Category.
**API field:** Referenced as `subCategory` in Offer payloads. Managed via `POST /api/v1/sub-categories`.
**DB note:** The database table was originally named `business_groups` (visible in baseline migrations). The current data model maps the sub-category entity to the `sub_categories` table. Always use "Sub-Category" in documentation and UI.
A delivery mechanism for Creatives — email, push notification, SMS, in-app, web, webhook, WhatsApp, or direct mail. Channels have a delivery mode (`api`, `file`, `integration`, or `manual`), an impression mode (`explicit` or `implicit`), and optional provider configuration (e.g., SES, Twilio). Channels contain one or more Placements.
**API field:** Referenced as `channel` in Creative and Placement payloads. Managed via `POST /api/v1/channels`.
A named slot within a Channel where a Creative can be displayed (e.g., "hero-banner", "sidebar-widget"). Placements define a slot type (banner, widget, etc.) and a maximum number of slots. They enable multi-placement responses from a single Recommend API call, allowing different Offers to fill different positions on a page.
**API field:** Referenced as `placement` in Creative payloads. Managed via `POST /api/v1/placements`.
**Not to be confused with:** Channel (the delivery mechanism that contains Placements).
A configured pipeline that takes a customer context and produces ranked, filtered Offer recommendations. Decision Flows contain nodes (Composable Pipeline) that process candidates through filtering, scoring, and ranking. Flows support versioning, auto-assembly, and A/B experiment configuration.
**API field:** Referenced as `decisionFlow` in API payloads. The `flowKey` parameter in the Recommend API selects which flow to execute. Managed via `POST /api/v1/decision-flows`.
**Always capitalize as two words:** "Decision Flow", not "decision flow" or "decision-flow" in prose.
## Pipeline Models
The Decision Flow execution model with 14 typed nodes arranged in 3 phases. You assemble flows by choosing which nodes to include and configuring each independently. The config is identified by `"version": 2` in the flow configuration.
**Phase 1 — Narrow:**
| Node | Description |
| ----------------- | --------------------------------------------------------------------- |
| `inventory` | Select candidate Offers by scope |
| `match_creatives` | Pair Offers with eligible Creatives for the requested Placement |
| `enrich` | Load customer data from schema tables into the evaluation context |
| `qualify` | Evaluate Decisioning Gates with AND/OR logic trees |
| `contact_policy` | Apply Contact Policy suppression rules |
| `filter` | Remove candidates by field conditions (eq, gt, contains, regex, etc.) |
**Phase 2 — Score & Rank:**
| Node | Description |
| ---------- | ------------------------------------------------------------------------------------------------------ |
| `score` | Assign scores with optional per-offer/category/channel model overrides and champion-challenger testing |
| `optimize` | Apply multi-objective portfolio optimization using saved profiles or inline weight sliders |
| `rank` | Order candidates by method: `topN`, `diversity`, `round_robin`, or `explore_exploit` |
| `group` | Allocate ranked candidates into Placement slots using optimal or greedy strategy |
**Phase 3 — Output:**
| Node | Description |
| ---------------- | ----------------------------------------------------------------------------- |
| `compute` | Evaluate formula-based computed fields with overrides and extras |
| `set_properties` | Attach static or formula-derived key-value properties to candidates |
| `response` | Configure response format (`standard` or `grouped`) and debug trace inclusion |
**Cross-phase:**
| Node | Description |
| ----------- | ---------------------------------------------------------------------- |
| `call_flow` | Invoke another Decision Flow and merge its results (mapped to Phase 1) |
All 16 node types are wired, including `enrich` (queries schema tables with Redis caching), `qualify` (evaluates decisioning gates with AND/OR logic trees), and `call_flow` (invokes sub-flows with depth limit and circular reference detection). The `optimize` node is deprecated and passes scores through unchanged — multi-objective weighting lives on the Score node via ranking profiles.
## APIs
The primary decisioning endpoint. Takes a customer context (customer ID, channel, placement, attributes) and returns ranked Offer recommendations with matched Creatives and personalization data.
**Endpoint:** `POST /api/v1/recommend`
**Key behaviors:**
* Executes the Decision Flow's composable pipeline configuration
* Enriches candidates with computed values from Category formulas
* Supports grouped response format that organizes results by Placement
* Records Decision Traces at the tenant's configured sample rate
* Applies Portfolio Optimization profiles when configured
**Always use:** "Recommend API" on first mention per page. "The Recommend endpoint" is acceptable in subsequent references.
The outcome recording endpoint. Records customer interactions — impressions, clicks, conversions, dismissals, and custom outcome types — and triggers downstream processing.
**Endpoint:** `POST /api/v1/respond`
**Key behaviors:**
* Records interactions in the interaction history
* Updates interaction summaries (aggregated counts per customer-offer-channel)
* Triggers incremental model updates for online-learning model types (Bayesian, Thompson Bandit, Epsilon-Greedy, Online Learner)
* Feeds data into Behavioral Metric aggregation
* Supports attribution tracking
**Always use:** "Respond API" on first mention per page.
## Decisioning Concepts
A rule that determines whether an Offer is eligible for a specific customer. Decisioning Gates evaluate customer attributes, segments, propensity scores, recency windows, or Behavioral Metrics. They run during the filter/qualification phase of the pipeline and can be scoped to global, segment, channel, category, subcategory, offer, or placement level.
**Six rule types:**
| Type | Description |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `segment_required` | Customer must belong to a specified segment |
| `attribute_condition` | Customer attribute must satisfy a condition (e.g., age >= 18) |
| `offer_attribute` | Offer-level field must satisfy a condition (e.g., `productType`, `margin`, custom fields) — the offer-side counterpart to `attribute_condition` |
| `propensity_threshold` | Model propensity score must exceed a minimum threshold |
| `recency_check` | Customer must have (or not have) recent interactions within a time window |
| `metric_condition` | A Behavioral Metric value must satisfy a condition (e.g., purchase\_count > 3) |
**Four stages:** Each rule carries a `stage` of `eligibility`, `fit`, `match`, or `ranking`. Eligibility and fit act as hard eligibility filters (a failing Offer is dropped); match applies a soft scoring multiplier (0.1–1.0) to surviving Offers; ranking-stage rules are persisted for authoring but are not yet applied to ordering.
**API field:** Managed via `POST /api/v1/qualification-rules`.
**Not to be confused with:** Filter Node (a Composable Pipeline node that filters by arbitrary field conditions) or Contact Policy (which suppresses already-qualified Offers based on frequency or budget constraints).
A rule that suppresses an already-qualified Offer based on contact frequency, cooldowns, budgets, or other constraints. Contact Policies run after Decisioning Gates in the pipeline. They can be scoped to global, offer, creative, or channel level.
**Fourteen rule types:**
| Type | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| `frequency_cap` | Maximum number of impressions within a time window |
| `cooldown` | Minimum time gap between consecutive contacts |
| `budget_exhausted` | Suppress when Offer budget is depleted |
| `outcome_based` | Suppress based on prior outcome (e.g., already converted) |
| `segment_exclusion` | Suppress for customers in a specific segment |
| `time_window` | Only allow contact during specific time windows |
| `mutual_exclusion` | Suppress when a conflicting Offer has already been shown |
| `cross_channel_cap` | Aggregate frequency cap across multiple Channels |
| `allow_override` | Explicit override that permits contact despite other suppression rules |
| `do_not_contact` | Unconditionally suppress the candidates this policy is scoped to (customer-level do-not-contact) |
| `category_suppression` | Suppress every Offer in a specified Category |
| `offer_category_cap` | Aggregate impression cap across all Offers in a Category |
| `customer_total_cap` | Cap total impressions to a customer across all Offers and Channels |
| `metric_condition` | Suppress when a Behavioral Metric value satisfies a condition |
**API field:** Managed via `POST /api/v1/contact-policies`.
**Not to be confused with:** Decisioning Gate (which determines initial eligibility rather than post-qualification suppression).
A custom aggregated metric computed from customer interaction history. Behavioral Metrics track counts, sums, averages, minimums, maximums, or ratios over configurable time windows (e.g., "number of email opens in the last 30 days"). They can be dimensioned by up to two fields (offer, channel, creative, or outcome type).
**Aggregate functions:** `count`, `sum`, `avg`, `min`, `max`, `ratio`
**Source fields:** `impressions`, `positive`, `negative`, `neutral`, `converts`, `totalValue`
**Compute modes:** `realtime` (for count and sum only) or `batch` (scheduled computation)
Behavioral Metrics feed into Decisioning Gates (via `metric_condition`) and Contact Policies, creating a feedback loop from customer behavior back into decisioning.
**API field:** Managed via `POST /api/v1/behavioral-metrics`.
**Not to be confused with:** Dashboard metrics (pre-built platform operational metrics) or Prometheus metrics (infrastructure monitoring).
The component that assigns a numeric score to each candidate Offer for a given customer. The platform supports nine scoring engine types, organized in a tier progression from simple to advanced:
| Engine Type | Description |
| --------------------- | ----------------------------------------------------------------------------------- |
| `scorecard` | Manual weight-based scoring using configurable field weights |
| `bayesian` | Prior-based scoring with incremental posterior updates from outcomes |
| `logistic_regression` | Weighted-sum + sigmoid logistic regression (L2-regularizable) |
| `gradient_boosted` | ML-based scoring using gradient-boosted decision trees |
| `thompson_bandit` | Multi-armed bandit using Thompson Sampling for explore/exploit balancing |
| `epsilon_greedy` | Multi-armed bandit using epsilon-greedy strategy with configurable exploration rate |
| `neural_cf` | Neural collaborative filtering for recommendation scoring |
| `online_learner` | Continuously learning model that updates with each interaction |
| `external_endpoint` | Delegates scoring to an external HTTP scoring endpoint |
Models of type `bayesian`, `thompson_bandit`, `epsilon_greedy`, and `online_learner` support incremental updates triggered by the Respond API.
**API field:** Model type is set via `modelType` in `POST /api/v1/algorithm-models`.
**Not to be confused with:** Portfolio Optimization (which combines multiple objective scores into a final composite score).
Multi-objective scoring that combines up to 5 dimensions into a single weighted composite score. Ranking profiles define the weight distribution across dimensions and are applied by the Score node (the deprecated Optimize node passes scores through unchanged).
**Five dimensions:**
| Dimension | Description |
| ------------ | -------------------------------------------------------------------- |
| `conversion` | Likelihood the customer will convert (default weight: 1.0) |
| `margin` | Profit margin or business value of the Offer |
| `fatigue` | Penalty for over-contacting the customer (higher = more suppression) |
| `fairness` | Ensures equitable distribution of Offers across customer segments |
| `recency` | Preference for Offers not recently shown to the customer |
The composite score is computed as a weighted average: each dimension's score is multiplied by its weight, summed, and divided by the total weight. If all weights are zero, the conversion score is used as the fallback.
**API field:** Ranking profiles are managed via `POST /api/v1/ranking-profiles` (see [Ranking Profiles API](/api-reference/ranking-profiles)). The `weights` field contains the dimension weights.
**Not to be confused with:** Scoring Engine (which produces the per-model propensity or relevance score that feeds into the conversion dimension of portfolio optimization).
A forensic record of how a specific Recommend API call was processed — which Offers were considered, which rules fired, what scores were assigned, and why the final ranking was produced. Decision Traces are sampled (not recorded for every request) at a rate configurable per tenant via `decisionTraceSampleRate` in tenant settings.
**API field:** Queried via `GET /api/v1/decision-traces`. The Recommend API response includes a `recommendationId` when a trace is captured.
**Not to be confused with:** Audit Log (the compliance and governance log of who changed what configuration, when).
The practice of using data, rules, and models to determine the optimal offer, message, or action to present to a specific customer at a specific moment in time. KaireonAI is a Next-Best-Action platform — the Recommend API is the runtime expression of this concept.
**Abbreviation:** "NBA" is acceptable after first use on a page. Always spell out "Next-Best-Action" on first reference.
**Not to be confused with:** Next-Best-Offer (a narrower term focused only on product offers — KaireonAI supports offers, messages, actions, and experiences).