mixle.inference.orchestration module

Learned orchestration from telemetry.

The static placement policy decides local-versus-pool execution from rules. LearnedPolicy can improve that decision from historical telemetry rows of the form (features, choice, outcome). For a new feature vector it looks up nearby historical decisions, estimates which choice had lower realized cost, and uses the learned choice only when there is enough comparable evidence.

When the nearby history is sparse or ambiguous, the policy defers to the static fallback. Promotion is a separate operation: it requires isolated realized holdout outcomes, common support, paired or propensity-aware evaluation, and an uncertainty-adjusted improvement threshold.

class LearnedPolicy(keys, vecs, choices, costs, static, mean=<factory>, scale=<factory>, k=8, min_neighbors=4, margin=0.02)

Bases: object

A history-based placement policy that defers to a static teacher where it lacks evidence.

Parameters:

• keys (list[str])

• vecs (ndarray)

• choices (list[str])

• costs (ndarray)

• static (Callable[[dict[str, Any]], str])

• mean (ndarray)

• scale (ndarray)

• k (int)

• min_neighbors (int)

• margin (float)

decide(features)

Return (choice, learned) – the learned pick when confident, else the static fallback.

Parameters:

features (dict[str, Any])

Return type:

tuple[str, bool]

evaluate(rows, *, cost_key='cost')

Compare policies on the same contexts with actually observed action costs.

A context contributes only when both the learned and static selected actions have realized outcomes in the supplied holdout panel. No training-neighbor estimate is substituted for a missing outcome.

Parameters:

• rows (list[tuple[dict[str, Any], str, dict[str, Any]]])

• cost_key (str)

Return type:

dict[str, Any]

class LearnedAcquisition(keys, vecs, values, static, mean=<factory>, scale=<factory>, k=8, min_neighbors=4)

Bases: object

A history-based action scorer for the reasoner: learns which actions pay off, else defers.

Drop-in for mixle.substrate.act.score_action() (call it as scorer=policy in investigate). From route telemetry – each row a fired action’s (features={kind,cost,overlap}, value) – it estimates the expected yield of an action in a query’s feature region and scores it yield / cost. Where nearby history is too thin, it falls back to the static lexical scorer. This is an abstention rule, not a guarantee that learned decisions are never worse.

Parameters:

• keys (list[str])

• vecs (ndarray)

• values (ndarray)

• static (Callable[[Any, str], float])

• mean (ndarray)

• scale (ndarray)

• k (int)

• min_neighbors (int)

expected_yield(features)

Estimated yield of an action with these features, or None when history is too thin to say.

Parameters:

features (dict[str, Any])

Return type:

float | None

learn_action_policy(rows, static_scorer=None, *, value_key='value', k=8, min_neighbors=4)

Learn a reasoner acquisition policy from route telemetry (features, kind, outcome) rows.

static_scorer is the fall-back when history is thin (default mixle.substrate.act.score_action()). value_key names the outcome field to MAXIMIZE (default "value" – did the action yield evidence). Returns a LearnedAcquisition usable directly as investigate(..., scorer=policy).

Parameters:

• rows (list[tuple[dict[str, Any], str, dict[str, Any]]])

• static_scorer (Callable[[Any, str], float] | None)

• value_key (str)

• k (int)

• min_neighbors (int)

Return type:

LearnedAcquisition

learn_placement_policy(rows, static_policy, *, cost_key='cost', k=8, min_neighbors=4)

Learn a placement policy from telemetry (features, choice, outcome) rows (see module docstring).

static_policy maps a feature dict to a choice and is the fall-back when history is too thin. cost_key names the outcome field to minimize (default "cost"). Feature standardization and the neighbor index are built from the rows; LearnedPolicy.decide() and evaluate follow.

Parameters:

• rows (list[tuple[dict[str, Any], str, dict[str, Any]]])

• static_policy (Callable[[dict[str, Any]], str])

• cost_key (str)

• k (int)

• min_neighbors (int)

Return type:

LearnedPolicy

learn_schedule_policy(rows, static_policy, *, latency_key='latency', k=8, min_neighbors=4)

Learned pool scheduling (J4): when work is pool-eligible, learn where and when it actually runs fastest.

The same evidence-gated shape as placement, keyed on realized latency instead of dollar cost: rows are (features, choice, outcome) where features describe the moment (queue depth, job size, local load), choice is the scheduling decision (“run_local” / “queue_pool” / “defer”), and the outcome’s latency is what the decision actually cost in wall-clock. Where nearby history is thin, the returned policy defers to the static scheduler.

Parameters:

• rows (list[tuple[dict[str, Any], str, dict[str, Any]]])

• static_policy (Callable[[dict[str, Any]], str])

• latency_key (str)

• k (int)

• min_neighbors (int)

Return type:

LearnedPolicy

meta_improve(rows, static_policy, *, holdout_rows=None, cost_key='cost', holdout_frac=0.3, seed=0, k=8, min_neighbors=4, propensity_key='propensities', min_propensity=0.05, min_overlap=0.8, confidence_level=0.95, min_improvement=0.0)

Learn from telemetry and promote only with isolated, supported holdout evidence.

Repeated outcomes for the same feature context are kept in one split. Evaluation first uses paired realized outcomes when both policies’ selected actions were observed for the same context. If a complete propensity map is logged instead, inverse-propensity evaluation is available. Promotion requires minimum overlap and the one-sided confidence bound on learned - static to beat the requested improvement threshold. Returns:

{promoted, policy, receipt: {learned_mean_cost, static_mean_cost,
 mean_cost_difference, upper_confidence_bound, overlap_fraction, n}}

policy is learned only when promoted; otherwise it is exactly static_policy. The receipt records either decision.

Parameters:

• rows (list[tuple[dict[str, Any], str, dict[str, Any]]])

• static_policy (Callable[[dict[str, Any]], str])

• holdout_rows (list[tuple[dict[str, Any], str, dict[str, Any]]] | None)

• cost_key (str)

• holdout_frac (float)

• seed (int)

• k (int)

• min_neighbors (int)

• propensity_key (str)

• min_propensity (float)

• min_overlap (float)

• confidence_level (float)

• min_improvement (float)

Return type:

dict[str, Any]