Spectre.Router.Candidate (Spectre v0.3.0)

A single routing signal produced by a router evidence provider.

Candidates let router plugs report what they know without deciding the final route. The arbitrator can then compare hard regex matches, classifier scores, semantic cache hits, and other evidence with one common shape.

Summary

Types

strength()

t()

Functions

from_result(result, rule, provider, opts \\ [])

Builds a candidate from an adapter result map.

from_rule(rule, provider, raw, opts \\ [])

Builds a candidate from a compiled rule match.

new(attrs)

Builds a candidate from normalized attributes.

to_route(candidate, labels \\ [])

Converts the winning candidate into a Spectre route.

Types

strength()

@type strength() :: :hard | :strong | :medium | :weak

t()

@type t() :: %Spectre.Router.Candidate{
  accepted?: boolean(),
  flow: atom() | nil,
  handler: Spectre.Rule.handler() | nil,
  label: atom() | nil,
  margin: float() | nil,
  matched: term(),
  metadata: map() | nil,
  owner: module() | nil,
  provider: atom(),
  raw: term(),
  rule: Spectre.Rule.t() | nil,
  scope: Spectre.Definition.scope() | nil,
  score: float() | nil,
  strength: strength(),
  terminal?: boolean()
}

Functions

from_result(result, rule, provider, opts \\ [])

@spec from_result(
  map() | Spectre.Route.t(),
  Spectre.Rule.t() | nil,
  atom(),
  keyword()
) :: t()

Builds a candidate from an adapter result map.

candidate =
  Spectre.Router.Candidate.from_result(%{label: :help, confidence: 0.94}, rule, :classifier)

from_rule(rule, provider, raw, opts \\ [])

@spec from_rule(Spectre.Rule.t(), atom(), String.t(), keyword()) :: t()

Builds a candidate from a compiled rule match.

candidate = Spectre.Router.Candidate.from_rule(rule, :regex, input.text)

new(attrs)

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

Builds a candidate from normalized attributes.

Unknown keys are ignored. Prefer from_rule/4 or from_result/4 at adapter boundaries because they derive rule ownership, evidence strength, and score fields consistently.

candidate =
  Spectre.Router.Candidate.new(%{
    label: :HELP,
    provider: :custom,
    score: 0.9,
    accepted?: true
  })

to_route(candidate, labels \\ [])

@spec to_route(t(), [atom()]) :: Spectre.Route.t()

Converts the winning candidate into a Spectre route.

route = Spectre.Router.Candidate.to_route(candidate, [:help, :fallback])