Core Entities
Offer
Offer
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, qualification rules, 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).Creative
Creative
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).Category
Category
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).Sub-Category
Sub-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 Prisma model is SubCategory, mapped to the sub_categories table. Always use “Sub-Category” in documentation and UI.Channel
Channel
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.Placement
Placement
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).Decision Flow
Decision Flow
A configured pipeline that takes a customer context and produces ranked, filtered Offer recommendations. Decision Flows contain stages (Fixed-Stage Pipeline) or 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
Fixed-Stage Pipeline (v1)
Fixed-Stage Pipeline (v1)
The original Decision Flow execution model with 7 fixed stages executed in order:
- Inventory — Select candidate Offers by scope (all, category, or manual list)
- Enrichment — Load customer data from schema tables
- Filter — Apply qualification rules and contact policies
- Qualification — Evaluate eligibility rules
- Contact Policy — Apply frequency caps and suppression
- Scoring — Assign scores using the configured method
- Ranking — Produce the final ordered list
DecisionFlowConfig schema with stages.inventory, stages.filter, stages.scoring, and stages.ranking blocks.When to reference as “v1”: In technical and architecture documentation, “(v1)” can follow the full name on first use. In user-facing guides, prefer “Fixed-Stage Pipeline” without the version label.Not to be confused with: Composable Pipeline (the newer, flexible model with individual node types).Composable Pipeline (v2)
Composable Pipeline (v2)
The modular Decision Flow execution model with 13 typed nodes arranged in 3 phases. Users assemble flows by choosing which nodes to include and configuring each independently. The v2 config is identified by
Phase 2 — Score & Rank:
Phase 3 — Output:
Cross-phase:
Current status: Shipped. Three nodes are stubs that validate configuration and log warnings but do not execute full logic yet:
"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 Qualification Rules with AND/OR logic trees |
contact_policy | Apply Contact Policy suppression rules |
filter | Remove candidates by field conditions (eq, gt, contains, regex, etc.) |
| Node | Description |
|---|---|
score | Assign scores with optional per-offer/category/channel model overrides and champion-challenger testing |
rank | Order candidates by method: topN, diversity, round_robin, or explore_exploit |
group | Allocate ranked candidates into Placement slots using priority_fill strategy |
| 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 |
| Node | Description |
|---|---|
call_flow | Invoke another Decision Flow and merge its results (mapped to Phase 1) |
enrich, call_flow, and qualify. All other nodes are fully implemented.When to reference as “v2”: In technical and architecture documentation, “(v2)” can follow the full name on first use.APIs
Recommend API
Recommend API
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/recommendKey behaviors:- Detects whether the Decision Flow uses a v1 or v2 pipeline configuration and dispatches accordingly
- Enriches candidates with computed values from Category formulas
- Supports grouped response format (v2) that organizes results by Placement
- Records Decision Traces at the tenant’s configured sample rate
- Applies Arbitration profiles when configured
Respond API
Respond API
The outcome recording endpoint. Records customer interactions — impressions, clicks, conversions, dismissals, and custom outcome types — and triggers downstream processing.Endpoint:
POST /api/v1/respondKey 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
Decisioning Concepts
Qualification Rule
Qualification Rule
A rule that determines whether an Offer is eligible for a specific customer. Qualification Rules 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.Five rule types:
Two stages: Rules operate at either the
| Type | Description |
|---|---|
segment_required | Customer must belong to a specified segment |
attribute_condition | Customer attribute must satisfy a condition (e.g., age >= 18) |
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) |
qualification stage (hard eligibility) or the fit stage (soft preference scoring).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).Contact Policy
Contact Policy
A rule that suppresses an already-qualified Offer based on contact frequency, cooldowns, budgets, or other constraints. Contact Policies run after Qualification Rules in the pipeline. They can be scoped to global, offer, creative, or channel level.Nine rule types:
API field: Managed via
| 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 |
POST /api/v1/contact-policies.Not to be confused with: Qualification Rule (which determines initial eligibility rather than post-qualification suppression).Behavioral Metric
Behavioral Metric
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, ratioSource fields: impressions, positive, negative, neutral, converts, totalValueCompute modes: realtime (for count and sum only) or batch (scheduled computation)Behavioral Metrics feed into Qualification Rules (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).Scoring Engine
Scoring Engine
The component that assigns a numeric score to each candidate Offer for a given customer. The platform supports seven scoring engine types, organized in a tier progression from simple to advanced:
Models of type
| Engine Type | Description |
|---|---|
scorecard | Manual weight-based scoring using configurable field weights |
bayesian | Prior-based scoring with incremental posterior updates from outcomes |
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 |
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: Arbitration (which combines multiple objective scores into a final composite score).Arbitration
Arbitration
Multi-objective scoring that combines up to 5 dimensions into a single weighted composite score. Arbitration allows balancing competing business objectives when ranking Offers. Profiles define the weight distribution across dimensions.Five dimensions:
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: Arbitration profiles are managed via
| 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 |
POST /api/v1/arbitration-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 arbitration).Decision Trace
Decision Trace
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 traceId when a trace is captured.Not to be confused with: Audit Log (the compliance and governance log of who changed what configuration, when).Next-Best-Action
Next-Best-Action
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).