Public API

High-level orchestration utilities.

This module provides the glue between actions (problem-level options) and strategies (algorithmic components) by handling option routing, disambiguation, and helper builders.

Public API

• route_all_options: Strategy-aware option router with disambiguation support
• extract_strategy_ids, build_strategy_to_family_map, build_option_ownership_map: Helpers used by the router
• build_strategy_from_resolved, option_names_from_resolved: Builders based on resolved method information
• ResolvedMethod: Struct containing resolved method information from disambiguation
• resolve_method: Function that resolves method tokens to strategy families and IDs

See also: Options, Strategies

struct ResolvedMethod{T<:Tuple, I<:NamedTuple}

Resolved representation of a method tuple for strategy-aware option routing.

ResolvedMethod contains precomputed lookups derived from a method tuple and a set of families. It is intended to be created via resolve_method and then reused by routing and builder utilities.

Fields

• tokens::T: The original method tokens.
• ids_by_family::I: Family-wise strategy IDs extracted from tokens.
• strategy_to_family::Dict{Symbol, Symbol}: Reverse map strategy_id => family_name.
• strategy_ids::Tuple{Vararg{Symbol}}: Tuple of active strategy IDs.
• parameter::Union{Nothing, Type{<:Strategies.AbstractStrategyParameter}}: Optional global parameter extracted from the method tuple.

Notes

• This type is internal to CTSolvers.Orchestration.

See also: resolve_method, route_all_options

build_option_ownership_map(
    resolved::CTSolvers.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTSolvers.Strategies.StrategyRegistry
) -> Dict{Symbol, Set{Symbol}}

Build a mapping from option names to the families that own them.

This function analyzes the metadata of all strategies in the method to determine which family (or families) define each option. Options that appear in multiple families are considered ambiguous and require disambiguation.

Arguments

• resolved::ResolvedMethod: Resolved method information (active strategies)
• families::NamedTuple: NamedTuple mapping family names to abstract types
• registry::Strategies.StrategyRegistry: Strategy registry

Returns

• Dict{Symbol, Set{Symbol}}: Dictionary mapping optionname => Set{familyname}

Example

resolved = resolve_method(method, families, registry)
map = build_option_ownership_map(resolved, families, registry)

Notes

• Options appearing in only one family can be auto-routed
• Options appearing in multiple families require disambiguation syntax
• Options not appearing in any family will trigger an error during routing

See also: build_strategy_to_family_map, route_all_options

build_strategy_from_resolved(
    resolved::CTSolvers.Orchestration.ResolvedMethod,
    family_name::Symbol,
    families::NamedTuple,
    registry::CTSolvers.Strategies.StrategyRegistry;
    mode,
    kwargs...
) -> Any

Build the active strategy instance of a given family from a resolved method.

This function is the resolved-method counterpart of strategy construction. It is intended to be used after option routing, where the method tuple has already been validated and resolved by resolve_method.

Arguments

• resolved::ResolvedMethod: Output of resolve_method
• family_name::Symbol: Family key in families (e.g. :solver, :modeler)
• families::NamedTuple: Mapping family_name => family_type used for resolution
• registry::Strategies.StrategyRegistry: Strategy registry
• mode::Symbol=:strict: Validation mode for option extraction (:strict or :permissive)
• kwargs...: Options to pass to the strategy constructor

Returns

• Concrete strategy instance for the selected ID (parameterized if required)

Throws

• CTBase.Exceptions.IncorrectArgument: If the active strategy is parameterized but resolved.parameter is nothing

Example

resolved = resolve_method(method, families, registry)
solver = build_strategy_from_resolved(resolved, :solver, families, registry; mode=:strict, kwargs...)

See also: resolve_method, Strategies.build_strategy, option_names_from_resolved

build_strategy_to_family_map(
    resolved::CTSolvers.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTSolvers.Strategies.StrategyRegistry
) -> Dict{Symbol, Symbol}

Build a mapping from strategy IDs to family names.

This helper function creates a reverse lookup dictionary that maps each strategy ID in the method to its corresponding family name. This is used by the routing system to determine which family owns each strategy.

Arguments

• resolved::ResolvedMethod: Resolved method information (active strategy IDs)
• families::NamedTuple: NamedTuple mapping family names to abstract types
• registry::Strategies.StrategyRegistry: Strategy registry

Returns

• Dict{Symbol, Symbol}: Dictionary mapping strategy ID => family name

Example

resolved = resolve_method(method, families, registry)
map = build_strategy_to_family_map(resolved, families, registry)

See also: build_option_ownership_map, extract_strategy_ids

extract_strategy_ids(
    raw::CTSolvers.Strategies.RoutedOption,
    resolved::CTSolvers.Orchestration.ResolvedMethod
) -> Vector{Tuple{Any, Symbol}}

Extract strategy IDs from a routed option.

This function processes a RoutedOption created by route_to and validates that all specified strategy IDs are present in the method tuple.

Arguments

• raw::Strategies.RoutedOption: The routed option to process
• resolved::ResolvedMethod: Resolved method information (active strategy IDs)

Returns

• Vector{Tuple{Any, Symbol}}: Vector of (value, strategy_id) pairs

Throws

• Exceptions.IncorrectArgument: If a strategy ID in the routed option is not present in the method tuple

Example

resolved = resolve_method(method, families, registry)
routed = route_to(solver=100, modeler=50)
ids = extract_strategy_ids(routed, resolved)

See also: route_to, RoutedOption, extract_strategy_ids(::Any, ::ResolvedMethod)

extract_strategy_ids(
    raw,
    resolved::CTSolvers.Orchestration.ResolvedMethod
) -> Vector{Tuple{Any, Symbol}}

Extract strategy IDs from a non-routed option.

This fallback method handles option values that do not use disambiguation syntax. It returns nothing to indicate that no routing information is present.

Arguments

• raw: The raw option value to analyze (any type)
• resolved::ResolvedMethod: Resolved method information (unused in this method)

Returns

• nothing: Always returns nothing since no disambiguation syntax is detected

Example

resolved = resolve_method(method, families, registry)
result = extract_strategy_ids(100, resolved)  # Returns nothing

See also: extract_strategy_ids(::Strategies.RoutedOption, ::ResolvedMethod), route_to

option_names_from_resolved(
    resolved::CTSolvers.Orchestration.ResolvedMethod,
    family_name::Symbol,
    families::NamedTuple,
    registry::CTSolvers.Strategies.StrategyRegistry
) -> Tuple

Return the option names for the active strategy of a given family in a resolved method.

This function is the resolved-method counterpart of strategy option introspection. It avoids re-parsing the method tuple by using resolved.ids_by_family and the global resolved.parameter.

Arguments

• resolved::ResolvedMethod: Output of resolve_method
• family_name::Symbol: Family key in families (e.g. :solver, :modeler)
• families::NamedTuple: Mapping family_name => family_type used for resolution
• registry::Strategies.StrategyRegistry: Strategy registry

Returns

• Tuple{Vararg{Symbol}}: Option names for the active strategy

Throws

• CTBase.Exceptions.IncorrectArgument: If the active strategy is parameterized but resolved.parameter is nothing

Example

resolved = resolve_method(method, families, registry)
names = option_names_from_resolved(resolved, :solver, families, registry)

See also: resolve_method, build_strategy_from_resolved, Strategies.option_names

resolve_method(
    method::Tuple{Vararg{Symbol}},
    families::NamedTuple,
    registry::CTSolvers.Strategies.StrategyRegistry
) -> CTSolvers.Orchestration.ResolvedMethod{T} where T<:Tuple{Vararg{Symbol}}

Resolve a method tuple into a ResolvedMethod for routing and builders.

This function extracts one strategy ID per family (using the Strategies contract), builds reverse lookup maps, and extracts a global strategy parameter (if present).

Arguments

• method::Tuple{Vararg{Symbol}}: Method tokens, e.g. (:collocation, :adnlp, :ipopt).
• families::NamedTuple: Mapping family_name => family_type used for ID extraction.
• registry::Strategies.StrategyRegistry: Strategy registry.

Returns

• ResolvedMethod: Precomputed lookups derived from method.

Throws

• CTBase.Exceptions.IncorrectArgument: If a family strategy ID cannot be extracted from method.

Example

resolved = resolve_method(method, families, registry)
resolved.strategy_ids

See also: extract_strategy_ids, build_strategy_to_family_map

route_all_options(
    method::Tuple{Vararg{Symbol}},
    families::NamedTuple,
    action_defs::Vector{<:CTSolvers.Options.OptionDefinition},
    kwargs::NamedTuple,
    registry::CTSolvers.Strategies.StrategyRegistry;
    source_mode
) -> NamedTuple{(:action, :strategies), <:Tuple{NamedTuple, NamedTuple}}

Route all options with support for disambiguation and multi-strategy routing.

This is the main orchestration function that separates action options from strategy options and routes each strategy option to the appropriate family. It supports automatic routing for unambiguous options and explicit disambiguation syntax for options that appear in multiple strategies.

Arguments

• method::Tuple{Vararg{Symbol}}: Complete method tuple (e.g., (:collocation, :adnlp, :ipopt))
• families::NamedTuple: NamedTuple mapping family names to AbstractStrategy types
• action_defs::Vector{Options.OptionDefinition}: Definitions for action-specific options
• kwargs::NamedTuple: All keyword arguments (action + strategy options mixed)
• registry::Strategies.StrategyRegistry: Strategy registry
• source_mode::Symbol=:description: Controls error verbosity (:description for user-facing, :explicit for internal)

Returns

NamedTuple with two fields:

• action::NamedTuple: NamedTuple of action options (with OptionValue wrappers)
• strategies::NamedTuple: NamedTuple of strategy options per family (raw values, may contain BypassValue wrappers for bypassed options)

Disambiguation Syntax

Auto-routing (unambiguous):

solve(ocp, :collocation, :adnlp, :ipopt; grid_size=100)
# grid_size only belongs to discretizer => auto-route

Single strategy (disambiguate):

solve(ocp, :collocation, :adnlp, :ipopt; backend = route_to(adnlp=:sparse))
# backend belongs to both modeler and solver => disambiguate to :adnlp

Multi-strategy (set for multiple):

solve(ocp, :collocation, :adnlp, :ipopt; 
    backend = route_to(adnlp=:sparse, ipopt=:cpu)
)
# Set backend to :sparse for modeler AND :cpu for solver

Bypass validation (unknown backend option):

solve(ocp, :collocation, :adnlp, :ipopt;
    custom_opt = route_to(ipopt=bypass(42))
)
# BypassValue(42) is routed to solver and accepted unconditionally

Throws

• CTBase.Exceptions.IncorrectArgument: If an option is unknown, ambiguous without disambiguation, or routed to the wrong strategy

Example

method = (:collocation, :adnlp, :ipopt)
families = (discretizer = DiscretizerFamily, modeler = ModelerFamily, solver = SolverFamily)
action_defs = Options.OptionDefinition[]
kwargs = (grid_size=100, backend=Strategies.route_to(adnlp=:sparse))
routed = route_all_options(method, families, action_defs, kwargs, registry)

See also: extract_strategy_ids, build_strategy_to_family_map, build_option_ownership_map