AgentSessionManager.Routing.RoutingPolicy (AgentSessionManager v0.8.0)

Copy Markdown View Source

Routing policy for provider selection and failover attempts.

Strategies

  • :prefer (default) — order candidates by prefer list, then remaining. This preserves Phase 1 semantics.
  • :weighted — score each candidate using weights and health signals, then sort by descending score. Ties are broken by prefer order.

Weights

When strategy: :weighted, the weights map assigns a static score to each adapter id. Adapters not listed receive a default weight of 1.0. Health penalties (failure count) are subtracted from the weight to produce the final score.

Summary

Types

candidate()
candidate_id()
health_map()
strategy()
t()

Functions

attempt_limit(policy, candidate_count)
merge(base, overrides)
new(opts \\ [])
order_candidates(policy, candidates, opts \\ [])

Orders candidates according to the policy strategy.

score(policy, candidate_id, health)

Computes the weighted score for a single candidate.

Types

candidate()

@type candidate() :: %{:id => candidate_id(), optional(any()) => any()}

candidate_id()

@type candidate_id() :: String.t()

health_map()

@type health_map() :: %{
  optional(candidate_id()) => %{failure_count: non_neg_integer()}
}

strategy()

@type strategy() :: :prefer | :weighted

t()

@type t() :: %AgentSessionManager.Routing.RoutingPolicy{
  exclude: [candidate_id()],
  max_attempts: pos_integer(),
  prefer: [candidate_id()],
  strategy: strategy(),
  weights: %{optional(candidate_id()) => number()}
}

Functions

attempt_limit(policy, candidate_count)

@spec attempt_limit(t(), non_neg_integer()) :: non_neg_integer()

merge(base, overrides)

@spec merge(t(), keyword() | map()) :: t()

new(opts \\ [])

@spec new(keyword() | map()) :: t()

order_candidates(policy, candidates, opts \\ [])

@spec order_candidates(t(), [candidate()], keyword()) :: [candidate()]

Orders candidates according to the policy strategy.

  • :prefer — apply prefer/exclude filters and reorder by prefer list.
  • :weighted — score candidates using weights and optional health data, break ties with prefer order, then return sorted.

The opts keyword list may include:

  • :health — a map of %{adapter_id => %{failure_count: n}} used to penalize unhealthy adapters when strategy: :weighted.

score(policy, candidate_id, health)

@spec score(t(), candidate_id(), health_map()) :: float()

Computes the weighted score for a single candidate.

Score = weight(candidate_id) − failure_count * penalty_per_failure. The penalty per failure is 0.5 by default.