Skip to main content

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.

KaireonAI applies offer rules in four strictly-ordered stages. The first three are stored as qualification rule records with a stage discriminator. The fourth (Ranking) is performed by arbitration profiles.

​
Stages

  1. Eligibility — Hard pass/fail. Legal, compliance, do-not-contact. Failure blocks the offer immediately.
  2. Fit Filters — Product-fit checks. Whether the offer could logically apply to this customer at all.
  3. Match Scoring — Customer-fit multipliers. Given the offer is eligible and fits, how strong a match is it for this customer right now.
  4. Ranking — Multi-objective scoring across the eligible, fitting, matched candidates.
Stages 1–3 are authored on the Decisioning Gates page in the studio sidebar. Stage 4 is configured under Scoring Strategies.

​
Authoring rules

The studio surface at /studio/qualification-rules (label: Decisioning Gates) lists every rule in the tenant. A pill row at the top filters by stage:
  • All — every rule regardless of stage
  • Eligibility — hard gates only
  • Fit Filters — product-fit only
  • Match Scoring — soft-scoring multipliers only
Each rule row exposes the rule type, scope assignments, priority, and the stage classification. Click any row to edit; click + New Decisioning Rule to author a new one.

​
Selecting a stage

The rule editor surfaces a 3-button stage selector. Pick the stage that best matches the rule’s intent:
  • Use Eligibility for legal/compliance gates that block the offer entirely.
  • Use Fit Filters for product-fit checks (e.g. customer doesn’t already own the offer).
  • Use Match Scoring for soft scoring (e.g. propensity threshold, recency boost).
The default rule type lookup adapts to the stage: segment_required, attribute_condition, metric_condition default to Eligibility; propensity_threshold, recency_check default to Match.

​
API

GET /api/v1/qualification-rules?stage=eligibility|fit|match filters by stage. Each returned row is enriched with a classifier-derived decisioningStage field so the UI can render the stage label without re-classifying client-side. POST /api/v1/qualification-rules accepts a body matching the create-qualification-rule request schema. The stage field is one of eligibility | fit | match; omit it to default to eligibility.

​
Migrating from legacy stage names

Tenants whose data was created before this rename may have rows with legacy stage values. The classifier transparently maps them so existing data keeps working:
LegacyCurrent
qualificationeligibility
applicabilityfit
suitabilitymatch
To physically migrate the rows in the database (recommended for tidiness), run: 
cd platform && npx tsx ../tools/scripts/migrate-decisioning-stage.ts --tenant <tenantId> --apply
The script defaults to dry-run; pass --apply to mutate. It returns a JSON summary of how many rows were updated per legacy value.

​
Effective Rules — inheritance view per offer

Each offer rolls up rules from four scope levels: 
global → category → subcategory → offer
A qualification rule (or contact policy) attached to a category applies to every offer in that category; a rule attached to a subcategory narrows that further; a rule attached to an offer applies only to that offer; a rule with scope = "global" applies to every offer in the tenant. Channel and creative scopes are intentionally excluded from this view. They evaluate at decision time and require a specific channel/creative the offer is being delivered through. Operators inspect those via Decision Traces.

​
Where to find it

Open any offer in /studio/actions, click into the detail view, and click Effective Rules in the top action bar. The page renders two tables — Contact Policies and Decisioning Rules — each annotated with the matched scope (global / category / subcategory / offer).

​
API

GET /api/v1/offers/:id/effective-rules
Returns: 
{
  "offerId": "<uuid>",
  "categoryId": "<uuid>|null",
  "subCategoryId": "<uuid>|null",
  "contactPolicies": [
    {
      "id": "<uuid>",
      "name": "Daily frequency cap",
      "ruleType": "frequency_cap",
      "config": { "maxPerDay": 3 },
      "priority": 80,
      "status": "active",
      "source": "contact_policy",
      "stage": null,
      "matchedScope": { "scope": "category", "scopeId": "<uuid>" }
    }
  ],
  "qualificationRules": [
    {
      "id": "<uuid>",
      "name": "US residents only",
      "ruleType": "segment_required",
      "config": { "segmentId": "<uuid>" },
      "priority": 100,
      "status": "active",
      "source": "qualification_rule",
      "stage": "eligibility",
      "matchedScope": { "scope": "global", "scopeId": null }
    }
  ]
}
The endpoint requires any of the admin, editor, or viewer roles. Both lists are sorted by priority descending. The matchedScope field tells the UI why the rule applies (e.g., “rule X applies because of category Y”); legacy single-scope rows that haven’t been migrated to the multi-scope scopes[] relation still resolve correctly.