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.

​
What it does

Given a per-offer period target + current actual + fraction of period elapsed, goal-seek projects end-of-period delivery and applies a score multiplier to push toward the target. 
projectedEndOfPeriod = currentActual / fractionOfPeriodElapsed
gap = target − projectedEndOfPeriod
adjustmentFraction = clamp(kp · (gap / target), −maxAdj, +maxAdj)
multiplier = clamp(1 + adjustmentFraction, 0.5, 1.5)
  • kp = proportional gain (default 1.0)
  • maxAdjustmentPct = signed clamp (default 0.5)
  • The final multiplier is bounded [0.5, 1.5] so goal-seek can rotate rank order but cannot overwhelm or eliminate scores.
The control law is intentionally simple — proportional, no integral, no derivative. Anti-windup comes from the multiplier clamp, not from a separate accumulator.

​
Configuration

Two layers, mirroring pacing:
  1. Tenant flag: 
    { "arbitration": { "goalSeekEnabled": true } }
  2. Per-offer goal config on the Offer record under goal: 
    {
  "goal": {
    "target": 5000,
    "currentActual": 1200,
    "fractionOfPeriodElapsed": 0.4,
    "kp": 1.0,
    "maxAdjustmentPct": 0.5
  }
}
kp and maxAdjustmentPct are optional with the defaults shown.

​
When goal-seek applies vs no-ops

  • Flag off → wire never runs.
  • Flag on AND offer has well-formed goal.target / currentActual / fractionOfPeriodElapsed (all numeric) → multiplier applied, goalSeekAgg.applied++.
  • Flag on AND offer’s goal config is missing or has wrong types → goalSeekAgg.awaitingConfig++. Score is preserved.

​
What gets logged

Per batch run with the flag on: 
INFO goalseek.applied {
  runId, tenantId,
  applied, awaitingConfig
}
When the flag is off, nothing is logged for goal-seek.

​
Honest limits

  • No automatic period tracking. The wire reads currentActual + fractionOfPeriodElapsed straight off the offer. Operators must refresh those fields on a cadence that matches their target’s granularity (e.g., a midnight cron for daily targets).
  • No multi-objective coupling. Goal-seek runs after pacing (when both flags are on), so the multipliers compound. Operators who want either-or semantics should enable only one flag at a time.
  • Per-offer only. Cross-offer goals (e.g., “$10k portfolio daily revenue”) are not modeled in V1.

​
Operational checklist

  • Set kp conservatively at first (1.0 is the floor). Aggressive gains can produce oscillation when paired with the bandit.
  • maxAdjustmentPct = 0.3 (instead of the default 0.5) is a safer starting cap when running goal-seek alongside other multipliers.
  • Watch the projected vs actual delta in the offer’s daily report. If goal-seek is driving but the offer never reaches target, raise kp or check whether qualification rules are upstream blockers that goal-seek cannot influence.

​
Cross-references

  • arbitration-budget-pacing.mdx — same wire location; pacing applies BEFORE goal-seek when both flags are on.
  • arbitration-exp3ix.mdx
  • arbitration-lagrangian.mdx