Refactor(Tools): Implementation of Options & Strategies with Type-Stability focus

.gitignore

@@ -34,4 +34,5 @@ test/solution.json
 #reports/
 profiling/
 tmp/
-.agent/
+.agent/
+reports/

docs/api_reference.jl

@@ -65,6 +65,170 @@ function generate_api_reference(src_dir::String, ext_dir::String)
             filename="types",
         ),
         # ───────────────────────────────────────────────────────────────────
+        # Options Module - Public API
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory="options",
+            primary_modules=[
+                CTModels => src(
+                    "Options/Options.jl",
+                    "Options/option_value.jl",
+                    "Options/option_definition.jl",
+                    "Options/extraction.jl",
+                ),
+            ],
+            exclude=EXCLUDE_SYMBOLS,
+            public=true,
+            private=false,
+            title="Options - Public API",
+            title_in_menu="Options (Public)",
+            filename="options_public",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # Options Module - Internal API
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory="options",
+            primary_modules=[
+                CTModels => src(
+                    "Options/Options.jl",
+                    "Options/option_value.jl",
+                    "Options/option_definition.jl",
+                    "Options/extraction.jl",
+                ),
+            ],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="Options - Internal API",
+            title_in_menu="Options (Internal)",
+            filename="options_internal",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # Strategies Module - Contract (Public)
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory="strategies",
+            primary_modules=[
+                CTModels => src(
+                    "Strategies/Strategies.jl",
+                    "Strategies/contract/abstract_strategy.jl",
+                    "Strategies/contract/metadata.jl",
+                    "Strategies/contract/strategy_options.jl",
+                ),
+            ],
+            exclude=EXCLUDE_SYMBOLS,
+            public=true,
+            private=false,
+            title="Strategies - Contract (Public)",
+            title_in_menu="Strategies Contract (Public)",
+            filename="strategies_contract_public",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # Strategies Module - Contract (Internal)
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory="strategies",
+            primary_modules=[
+                CTModels => src(
+                    "Strategies/Strategies.jl",
+                    "Strategies/contract/abstract_strategy.jl",
+                    "Strategies/contract/metadata.jl",
+                    "Strategies/contract/strategy_options.jl",
+                ),
+            ],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="Strategies - Contract (Internal)",
+            title_in_menu="Strategies Contract (Internal)",
+            filename="strategies_contract_internal",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # Strategies Module - API (Public)
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory="strategies",
+            primary_modules=[
+                CTModels => src(
+                    "Strategies/api/builders.jl",
+                    "Strategies/api/configuration.jl",
+                    "Strategies/api/introspection.jl",
+                    "Strategies/api/registry.jl",
+                    "Strategies/api/utilities.jl",
+                    "Strategies/api/validation.jl",
+                ),
+            ],
+            exclude=EXCLUDE_SYMBOLS,
+            public=true,
+            private=false,
+            title="Strategies - API (Public)",
+            title_in_menu="Strategies API (Public)",
+            filename="strategies_api_public",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # Strategies Module - API (Internal)
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory="strategies",
+            primary_modules=[
+                CTModels => src(
+                    "Strategies/api/builders.jl",
+                    "Strategies/api/configuration.jl",
+                    "Strategies/api/introspection.jl",
+                    "Strategies/api/registry.jl",
+                    "Strategies/api/utilities.jl",
+                    "Strategies/api/validation.jl",
+                ),
+            ],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="Strategies - API (Internal)",
+            title_in_menu="Strategies API (Internal)",
+            filename="strategies_api_internal",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # Orchestration Module - Public API
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory="orchestration",
+            primary_modules=[
+                CTModels => src(
+                    "Orchestration/Orchestration.jl",
+                    "Orchestration/routing.jl",
+                    "Orchestration/disambiguation.jl",
+                    "Orchestration/method_builders.jl",
+                ),
+            ],
+            exclude=EXCLUDE_SYMBOLS,
+            public=true,
+            private=false,
+            title="Orchestration - Public API",
+            title_in_menu="Orchestration (Public)",
+            filename="orchestration_public",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # Orchestration Module - Internal API
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory="orchestration",
+            primary_modules=[
+                CTModels => src(
+                    "Orchestration/Orchestration.jl",
+                    "Orchestration/routing.jl",
+                    "Orchestration/disambiguation.jl",
+                    "Orchestration/method_builders.jl",
+                ),
+            ],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="Orchestration - Internal API",
+            title_in_menu="Orchestration (Internal)",
+            filename="orchestration_internal",
+        ),
+        # ───────────────────────────────────────────────────────────────────
         # Core: Default & Utils
         # ───────────────────────────────────────────────────────────────────
         CTBase.automatic_reference_documentation(;

docs/make.jl

@@ -64,13 +64,45 @@ with_api_reference(src_dir, ext_dir) do api_pages
         checkdocs=:none,
         pages=[
             "Introduction" => "index.md",
-            "Interfaces" => [
-                "OCP Tools" => "interfaces/ocp_tools.md",
-                "Optimization Problems" => "interfaces/optimization_problems.md",
-                "Optimization Modelers" => "interfaces/optimization_modelers.md",
-                "Solution Builders" => "interfaces/ocp_solution_builders.md",
+            "User Guide" => [
+                "Defining Problems" => "interfaces/optimization_problems.md",
+                "Building Solutions" => "interfaces/ocp_solution_builders.md",
+            ],
+            "Developer Guide" => [
+                "Tutorials" => [
+                    "Creating a Strategy" => "tutorials/creating_a_strategy.md",
+                    "Creating a Strategy Family" => "tutorials/creating_a_strategy_family.md",
+                ],
+                "Interfaces" => [
+                    "Strategies" => "interfaces/strategies.md",
+                    "Strategy Families" => "interfaces/strategy_families.md",
+                    "Orchestration & Routing" => "interfaces/orchestration.md",
+                    "Optimization Modelers" => "interfaces/optimization_modelers.md",
+                ],
+                "Examples" => [
+                    "Simple Strategy" => "examples/simple_strategy.md",
+                    "Strategy with Options" => "examples/strategy_with_options.md",
+                    "Strategy Family" => "examples/strategy_family.md",
+                    "Option Routing" => "examples/routing_example.md",
+                    "Integration Example" => "examples/integration_example.md",
+                    "Migration Example" => "examples/migration_example.md",
+                ],
+            ],
+            "API Reference" => [
+                "Public API" => [
+                    "Options" => "options/options_public.md",
+                    "Strategies (Contract)" => "strategies/strategies_contract_public.md",
+                    "Strategies (API)" => "strategies/strategies_api_public.md",
+                    "Orchestration" => "orchestration/orchestration_public.md",
+                ],
+                "Internal API" => [
+                    "Options (Internal)" => "options/options_internal.md",
+                    "Strategies Contract (Internal)" => "strategies/strategies_contract_internal.md",
+                    "Strategies API (Internal)" => "strategies/strategies_api_internal.md",
+                    "Orchestration (Internal)" => "orchestration/orchestration_internal.md",
+                ],
+                "Core & OCP" => api_pages,
             ],
-            "API Reference" => api_pages,
         ],
     )
 end

docs/src/examples/integration_example.md

@@ -0,0 +1,50 @@
+# Example: Integration
+
+This example demonstrates how strategies might be integrated into a larger system (like a `solve` function).
+
+```@example integration
+using CTModels.Strategies
+
+# Mock Registry and Family from previous examples
+abstract type IntegrationSolver <: AbstractStrategy end
+
+struct BasicSolver <: IntegrationSolver
+    options::StrategyOptions
+end
+Strategies.id(::Type{BasicSolver}) = :basic
+Strategies.metadata(::Type{BasicSolver}) = StrategyMetadata(
+    OptionDefinition(name=:verbose, type=Bool, default=false)
+)
+BasicSolver(;kw...) = BasicSolver(Strategies.build_strategy_options(BasicSolver; kw...))
+
+const REGISTRY = Strategies.create_registry(
+    IntegrationSolver => (BasicSolver,)
+)
+
+# Mock Solve Function
+function solve(problem; method=:basic, kwargs...)
+    # 1. Identify the strategy type from the method ID
+    # In a real app, 'method' might need disambiguation if multiple families exist
+    strategy_id = method
+
+    # 2. Build the strategy instance using the registry
+    # We pass 'kwargs' down to the strategy constructor
+    strategy = Strategies.build_strategy(
+        strategy_id, 
+        IntegrationSolver, 
+        REGISTRY; 
+        kwargs...
+    )
+
+    # 3. Use the strategy
+    println("Solving with ", Strategies.id(strategy))
+    if Strategies.option_value(strategy, :verbose)
+        println("... verbose output ...")
+    end
+
+    return "Solution"
+end
+
+# User calls solve
+solve("my_problem", method=:basic, verbose=true)
+```

docs/src/examples/migration_example.md

@@ -0,0 +1,47 @@
+# Example: Migration
+
+This example shows the before (AbstractOCPTool) and after (AbstractStrategy) code for the same component.
+
+## Legacy Implementation (AbstractOCPTool)
+
+```julia
+# Old Style (conceptual)
+struct OldTool <: AbstractOCPTool
+    options_values::NamedTuple
+    options_sources::NamedTuple
+end
+
+CTModels.get_symbol(::Type{OldTool}) = :mytool
+CTModels._option_specs(::Type{OldTool}) = (
+    max_iter = OptionSpec(type=Int, default=100),
+)
+
+function OldTool(; kwargs...)
+    vals, srcs = CTModels._build_ocp_tool_options(OldTool; kwargs...)
+    return OldTool(vals, srcs)
+end
+```
+
+## Modern Implementation (AbstractStrategy)
+
+```@example migration
+using CTModels.Strategies
+
+struct NewTool <: AbstractStrategy
+    options::StrategyOptions
+end
+
+Strategies.id(::Type{NewTool}) = :mytool
+Strategies.metadata(::Type{NewTool}) = StrategyMetadata(
+    OptionDefinition(name=:max_iter, type=Int, default=100)
+)
+
+function NewTool(; kwargs...)
+    opts = Strategies.build_strategy_options(NewTool; kwargs...)
+    return NewTool(opts)
+end
+
+# Verify
+t = NewTool(max_iter=200)
+println("New tool created with max_iter=", Strategies.option_value(t, :max_iter))
+```