The orchestration layer that turns a Recommend API request into ranked, personalized offers.
A Decision Flow is the brain of KaireonAI. Every time you need to decide which offer to show a customer, a Decision Flow runs behind the scenes. It loads the eligible inventory, pulls in customer context, filters out anything that should not be shown, scores what remains using ML models, and returns a ranked list of personalized recommendations — all in under 200ms.Think of it as a pipeline with a clear contract: a customer walks in one end, and the best offers come out the other.
Decision Flows are executed through the Recommend API. Pass a decisionFlowId in the request body and the engine does the rest.
Decision Flows use a composable pipeline with 16 node types organized across 3 phases. You assemble a pipeline by choosing which nodes to include and configuring each through a visual canvas editor.
The PRIE formula is KaireonAI’s multiplicative scoring model. It produces a single priority score from four dimensions:
Priority = P x R x I x E
The multiplicative structure means a zero in any dimension eliminates the candidate entirely. This prevents irrelevant high-value offers from surfacing and ensures all four dimensions must be satisfied.
Impact vs. Emphasis: Impact (businessValue) captures objective business value — how much is the offer worth if the customer converts. Emphasis (priority) is a subjective lever for marketers to boost or suppress offers based on campaign strategy. See Offers — Business Value for details.
Flow-level weights — Configured on the Score node, these control how much each factor matters relative to the others. Weights must sum to 1.0. They are global tuning knobs for your decisioning strategy.
Per-offer factor values — Each offer provides its own values for each dimension. These are the raw inputs that get weighted and multiplied together.
Two Starbucks offers scored for the same customer, with flow-level weights P=0.4, R=0.2, I=0.2, E=0.2:
Factor
BOGO Frappuccino
Earn 3x Stars
P (model score)
0.85
0.60
R (context)
0.70
0.90
I (businessValue=80)
0.80
0.40
E (priority=70)
0.70
0.90
PRIE score
0.85 x 0.70 x 0.80 x 0.70 = 0.333
0.60 x 0.90 x 0.40 x 0.90 = 0.194
BOGO Frappuccino wins despite lower relevance and emphasis, because its higher propensity and business value outweigh the other factors.
When explain=true is passed to the Recommend API, each decision in the response includes an arbitrationScores object with the individual PRIE factor values (propensity, relevance, impact, emphasis) and the final composite score. This makes it easy to debug why one offer outranked another without needing to reconstruct the math manually.
You can add overrides scoped to a specific offer, category, subcategory, or channel. Each override can specify a different model AND custom PRIE weights.
Override Scope
Example Use Case
Offer
Use a specialized model for a high-value offer
Category
Different PRIE weights for beverages vs. merchandise
Subcategory
Boost emphasis weight for seasonal items
Channel
Lower propensity weight for email where model accuracy is lower
The resolveScoreConfig() function checks the candidate’s channel against the overrides array. First match wins; no match falls back to the default config.
Extension Points let you inject custom logic at three critical moments in the pipeline without modifying the core flow. They appear as dashed-border placeholder nodes on the canvas and are no-op when unconfigured.
Hook
Phase
When It Fires
Use Cases
pre_score
Before scoring
After enrichment and filtering
External API enrichment, last-minute filters, real-time features
score_override
During scoring
After built-in scorer runs
Replace/adjust scores with an external model, champion-challenger
Extension points are the recommended way to integrate external ML models for score adjustment. Use score_override to call your model and blend or replace the built-in score.
Arbitration Influencers create a feedback loop between past customer outcomes and future scoring. When a customer has positive interactions with offers in a category, other offers in that same category receive a score boost. Negative outcomes lead to a demotion.
KaireonAI supports an always-on control group for measuring the true incremental lift of your Decision Flows. A configurable percentage of Recommend API calls receive randomized scores instead of model-driven scores, creating a baseline for lift measurement.
Deterministic assignment — Hash of customerId + date decides group membership. Same customer, same day, same group.
Random scoring — Control group requests still run the full pipeline (enrichment, qualification, contact policies), but scores are randomized.
Response flag — The response includes controlGroup: true | false for downstream analytics segmentation.
Setting
Type
Range
Default
Description
controlGroupPercent
integer
0—10
2
Percentage of Recommend calls in the control group
A 2% default means roughly 2 out of every 100 calls get randomized scores — enough for statistically meaningful lift measurement without materially impacting business outcomes.
The NBA Kill Switch is a tenant-level safety control that instantly disables Decision Flow execution across your entire tenant.Setting:nbaEnabled (boolean, default true) in Settings > General.When nbaEnabled = false:
Recommend API bypasses all Decision Flow execution
Offers are returned ranked by priority only (simple ordering)
No enrichment, scoring, filtering, or contact policy evaluation occurs
Response includes "mode": "fallback" flag
The kill switch is for emergency use — for example, if a flow misconfiguration is causing production errors. It does not disable the Recommend API itself; it only simplifies ranking to a safe fallback.
KaireonAI reduces manual wiring by automatically creating FlowRoutes when you add channels and placements.
First flow created is automatically marked as the default
New channel — FlowRoute created to the default flow
New placement — FlowRoute created to the default flow
New channels and placements are immediately functional without manual routing setup. Override any auto-created route by editing it in the Decision Flow configuration or the Channel detail page.
Auto-routing only creates routes to the default flow. To route a channel to a different flow, create the route manually or change the default flow first.
When autoAssembly is enabled (the default), the flow’s inventory updates automatically as your catalog changes. Creating a new offer, activating a creative, or adding a qualification rule triggers reassembly.Assembly triggers: Offers (created/activated/archived), Creatives (created/linked), Channels, Sub-categories, Qualification rules, Contact policies.Each trigger is logged in the flow’s assemblyLog with a timestamp, source entity, and changes applied. Set autoAssembly: false for full manual control.
The response includes per-customer recommendations plus an aggregate summary with avgOffersPerCustomer, topOffers, and categoryDistribution.
Batch decisioning runs the same pipeline as real-time Recommend — enrichment, qualification, contact policies, scoring, and ranking all apply. The only difference is iteration over a segment instead of a single customer.
When you need to balance competing business objectives (revenue vs. customer experience vs. margin), the Optimize node produces a single composite score:
Walk through a complete Recommend API call to see how each stage transforms the candidate list.Setup: 5 active offers (offer-A through offer-E), 1 Decision Flow, customer C-4821 with credit_score = 745, PRIE scoring with a scorecard model, ranking: topN, maxCandidates = 2.
