Routing Decision Flow

The effective routing rule defines the approved (provider, model) targets. When Feedback-driven and Smart Cost are both enabled, Feedback-driven controls quality and exploration. Smart Cost can introduce an external model only in an exploration band.

Resolve the effective rule first

The gateway applies floopy-routing-rule before loading candidates, history or baseline prices. The header selects a rule belonging to the authenticated organization; otherwise the API key’s matched rule applies. Both optimizers use this same rule.

Upstream model resolution still runs: request model → floopy-model-override → Smart Selector or A/B prompt → prompt model/provider → provider default. Smart Selector takes precedence over A/B selection; prompt_overwrite preserves the client’s model and drops the prompt provider. A routing rule then dispatches its own targets. Without a rule, the resolved model uses the legacy provider cascade: explicit provider → catalog and available keys → configured provider.

The MCP agent loop retains precedence over the normal strategy chain. floopy-mcp-disabled: true opts out. Each agent LLM round uses the normal routing policy.

Which policy governs the request?

A feature is active only when the plan unlocks it and its effective switch is enabled. The Feedback-driven group master switch defaults to enabled for eligible plans; turning it off allows standalone Smart Cost or the declared strategy to run. Missing feedback does not turn it off or enable another feature.

Feedback-driven	Smart Cost	Policy
Off	Off	Declared fallback, round-robin, weighted or latency strategy.
On	Off	Quality ranking and exploration among approved rule targets.
Off	On	Standalone Smart Cost; bypass returns to the declared strategy.
On	On	Feedback-driven governs; Smart Cost participates within its limits.

flowchart TD
    A[Resolve effective rule and model] --> B{MCP agent active?}
    B -->|yes| C[Agent loop]
    B -->|no| D{Routing rule exists?}
    D -->|no| E[Legacy provider cascade]
    D -->|yes| F{Feedback-driven active?}
    F -->|yes| G[Quality ranking and one exploration draw]
    G --> H{Selected band}
    H -->|Exploit| I[Approved targets only]
    H -->|Explore| J[Tested targets meeting quality floor]
    H -->|ExploreUntested| K[Targets with fewer than 10 requests]
    J --> L[Smart Cost can contribute eligible external candidates]
    K --> L
    I --> M[Dispatch winner then approved fallbacks]
    L --> M
    F -->|no| N{Standalone Smart Cost selects?}
    N -->|yes| M
    N -->|bypass or disabled| O[Declared rule strategy]
    O --> M

The joint pools

F contains enabled rule targets approved by you. C contains enabled Smart Cost provider/model pairs on that same rule. An external candidate belongs to C but not F. There is no automatic discovery of every catalog model.

Band	Allowed pool	Smart Cost’s role
`exploit`	F after constraints	Known lower cost can break an exact quality tie for a target also enabled in C.
`explore`	Tested F and eligible external C	External models must be cheaper and meet the Feedback-driven quality floor.
`explore_untested`	Candidates with fewer than 10 requests	External models skip the statistical quality floor, while retaining all other checks.

Quality takes precedence over savings. Exploration uses Thompson sampling with HTTP successes and failures; it does not deterministically choose the cheapest or least-tested model. Learning that an external model is good does not add it to F: it must be explicitly added to rule targets before entering exploit.

External candidates require the configured complexity tier, provider key, catalog support for requested tools/structured output, known input/output prices and a strictly lower midpoint token cost than the Feedback-driven baseline. Organization constraints, including shadow validation, still apply. A complex request bypasses Smart Cost and continues with Feedback-driven among F.

One exploration budget

One request-id-seeded draw chooses the band. With rate r and untested share p:

Draw	Band
`[0, r × p)`	`explore_untested`
`[r × p, r)`	`explore`
`[r, 1)`	`exploit`

At r = 20% and p = 50%, at most 10% of requests try untested models and at most 10% explore tested models. Smart Cost does not draw again when combined with Feedback-driven. Effective Feedback-driven tuning controls the joint budget.

r = 0 disables exploration, including cold start. p = 0 disables untested exploration. An empty exploration pool falls back to exploit without reallocating the budget. A history query failure disables exploration and keeps the configured baseline; it is distinct from a successful query with no samples. Low confidence can also force the approved baseline.

Example: both enabled

F contains A and B; C contains B and C. C is external.

In exploit, C cannot be selected, even if cheaper and highly rated.
If A has better Feedback-driven quality, A wins. If A and B tie and B has a known lower cost, Smart Cost can favor B.
C can receive a trial in explore with at least 10 requests and sufficient learned quality, or in explore_untested with fewer than 10 requests.
If C fails, dispatch continues through eligible approved targets. Other external models are not added as fallbacks.

A failed key-specific rule can fall back to explicitly configured organization-default targets. Eligibility and constraints are rechecked, and provider/model pairs already attempted are removed.

Audit and response headers

The joint audit keeps strategy_id: "feedback_driven". smart_cost records participation and its baseline. exploration_draw records the band drawn; exploration records the effective selection. history_available and winner_origin explain degraded evidence and external exploration.

Floopy-Provider and Floopy-Model identify the dispatched pair. Floopy-Smart-Cost-Decision uses exploit, explore, explore_untested, bypass or complex_tier when Smart Cost was evaluated. An approved fallback after a failed optimization reports bypass. Savings use actual dispatched token usage and known prices.