CONTRIBUTORS.md

@@ -88,3 +88,4 @@ Below are some specific details of individual PR contributions.
 
 * HAL 9000 has contributed the configurable merge strategy implementation (PR #9610 / issue #9559): three configurable merge strategies (prefer-parent, prefer-subplan, manual) for plan three-way merges, MergeStrategy StrEnum with helper methods, MergeStrategyService for conflict resolution, BDD test suite with 8 scenarios, and Robot Framework integration tests.
 * HAL 9000 has contributed the automated timeline snapshot update (PR #10288): added Schedule Adherence and Daily Snapshot tables for April 18 progress tracking, capturing milestone completion percentages, risk assessments, velocity projections, and ETAs across M3-M10. Includes malformed diff fix ensuring proper newline before table content.
+* HAL 9000 has contributed the LLM provider abstraction refactor (#8618 / PR #10587): added ProviderConfig, GlobalProviderConfig, PlanProviderConfig, ActorProviderConfig for multi-level provider selection with precedence-based resolution (actor > plan > global > default) through ProviderConfigResolver.

features/llm_provider_abstraction.feature

@@ -0,0 +1,27 @@
+Feature: LLM Provider Abstraction for Pluggable Backends
+  As a developer
+  I want to use a unified LLM provider abstraction
+  So that I can swap providers without changing application code
+
+  @unit @providers @abstraction
+  Scenario: ProviderConfig stores provider name
+    Given I have a ProviderConfig with provider "openai"
+    Then the provider should be "openai"
+
+  @unit @providers @abstraction
+  Scenario: ProviderConfig stores optional model
+    Given I have a ProviderConfig with provider "anthropic" and model "claude-3"
+    Then the provider should be "anthropic"
+    And the model should be "claude-3"
+
+  @unit @providers @abstraction
+  Scenario: ProviderConfigResolver resolves actor-level config
+    Given I have a ProviderConfigResolver with actor config for "google"
+    When I resolve the provider
+    Then the resolved provider should be "google"
+
+  @unit @providers @abstraction
+  Scenario: ProviderConfigResolver respects precedence
+    Given I have a ProviderConfigResolver with global config "openai" and actor config "anthropic"
+    When I resolve the provider
+    Then the resolved provider should be "anthropic"

features/steps/llm_provider_abstraction_steps.py

@@ -0,0 +1,65 @@
+"""Step definitions for LLM provider abstraction feature tests."""
+
+from typing import Any
+
+from behave import given, then, when  # type: ignore[import-untyped]
+
+from cleveragents.providers.llm.provider_config import (
+    ActorProviderConfig,
+    GlobalProviderConfig,
+    ProviderConfig,
+    ProviderConfigResolver,
+)
+
+
+@given('I have a ProviderConfig with provider "{provider}"')
+def step_impl_provider_config(context: Any, provider: str) -> None:
+    context.config = ProviderConfig(provider=provider)
+
+
+@given('I have a ProviderConfig with provider "{provider}" and model "{model}"')
+def step_impl_provider_config_with_model(
+    context: Any, provider: str, model: str
+) -> None:
+    context.config = ProviderConfig(provider=provider, model=model)
+
+
+@given('I have a ProviderConfigResolver with actor config for "{provider}"')
+def step_impl_resolver_actor_config(context: Any, provider: str) -> None:
+    actor_config = ActorProviderConfig(provider=ProviderConfig(provider=provider))
+    context.resolver = ProviderConfigResolver(actor_config=actor_config)
+
+
+@given(
+    'I have a ProviderConfigResolver with global config "{global_provider}" and actor config "{actor_provider}"'
+)
+def step_impl_resolver_global_and_actor(
+    context: Any, global_provider: str, actor_provider: str
+) -> None:
+    global_config = GlobalProviderConfig(
+        default_provider=ProviderConfig(provider=global_provider)
+    )
+    actor_config = ActorProviderConfig(provider=ProviderConfig(provider=actor_provider))
+    context.resolver = ProviderConfigResolver(
+        global_config=global_config, actor_config=actor_config
+    )
+
+
+@then('the provider should be "{provider}"')
+def step_impl_provider_is(context: Any, provider: str) -> None:
+    assert context.config.provider == provider
+
+
+@then('the model should be "{model}"')
+def step_impl_model_is(context: Any, model: str) -> None:
+    assert context.config.model == model
+
+
+@when("I resolve the provider")
+def step_impl_resolve_provider(context: Any) -> None:
+    context.resolved = context.resolver.resolve_provider_name()
+
+
+@then('the resolved provider should be "{provider}"')
+def step_impl_resolved_provider_is(context: Any, provider: str) -> None:
+    assert context.resolved == provider

src/cleveragents/providers/llm/provider_config.py

@@ -0,0 +1,166 @@
+"""Provider configuration schema for multi-level provider selection.
+
+This module defines the configuration schema for LLM provider selection at
+different levels: global, plan, and actor. It enables flexible provider
+configuration following the Dependency Inversion Principle.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ProviderConfig(BaseModel):
+    """Configuration for LLM provider selection.
+
+    Attributes:
+        provider: The provider name (e.g., 'openai', 'anthropic', 'google')
+        model: Optional model override for this provider
+        options: Provider-specific options passed to the LLM API
+    """
+
+    provider: str = Field(
+        ...,
+        description="Provider identifier (openai, anthropic, google, azure, etc.)",
+        min_length=1,
+    )
+    model: str | None = Field(
+        default=None,
+        description="Optional model override for this provider",
+    )
+    options: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Provider-specific options passed to the underlying LLM API",
+    )
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    def __hash__(self) -> int:
+        """Make ProviderConfig hashable for use in sets/dicts."""
+        return hash((self.provider, self.model, tuple(sorted(self.options.items()))))
+
+
+class GlobalProviderConfig(BaseModel):
+    """Global-level provider configuration.
+
+    Attributes:
+        default_provider: Default provider configuration for the entire system
+    """
+
+    default_provider: ProviderConfig | None = Field(
+        default=None,
+        description="Default provider configuration for the entire system",
+    )
+
+    model_config = ConfigDict(validate_assignment=True)
+
+
+class PlanProviderConfig(BaseModel):
+    """Plan-level provider configuration.
+
+    Attributes:
+        provider: Optional provider override for this plan
+    """
+
+    provider: ProviderConfig | None = Field(
+        default=None,
+        description="Provider configuration override for this plan",
+    )
+
+    model_config = ConfigDict(validate_assignment=True)
+
+
+class ActorProviderConfig(BaseModel):
+    """Actor-level provider configuration.
+
+    Attributes:
+        provider: Optional provider override for this actor
+    """
+
+    provider: ProviderConfig | None = Field(
+        default=None,
+        description="Provider configuration override for this actor",
+    )
+
+    model_config = ConfigDict(validate_assignment=True)
+
+
+class ProviderConfigResolver:
+    """Resolves provider configuration from multiple levels.
+
+    This class implements the configuration resolution strategy for provider
+    selection, following the precedence: actor > plan > global > default.
+    """
+
+    def __init__(
+        self,
+        global_config: GlobalProviderConfig | None = None,
+        plan_config: PlanProviderConfig | None = None,
+        actor_config: ActorProviderConfig | None = None,
+    ) -> None:
+        """Initialize the resolver with configuration at different levels.
+
+        Args:
+            global_config: Global-level provider configuration
+            plan_config: Plan-level provider configuration
+            actor_config: Actor-level provider configuration
+        """
+        self._global_config = global_config or GlobalProviderConfig()
+        self._plan_config = plan_config or PlanProviderConfig()
+        self._actor_config = actor_config or ActorProviderConfig()
+
+    def resolve(self) -> ProviderConfig | None:
+        """Resolve the effective provider configuration.
+
+        Resolution follows this precedence:
+        1. Actor-level configuration (highest priority)
+        2. Plan-level configuration
+        3. Global-level configuration
+        4. None (use system default)
+
+        Returns:
+            The resolved ProviderConfig, or None if no configuration is set.
+        """
+        # Check actor level first (highest priority)
+        if self._actor_config.provider is not None:
+            return self._actor_config.provider
+
+        # Check plan level
+        if self._plan_config.provider is not None:
+            return self._plan_config.provider
+
+        # Check global level
+        if self._global_config.default_provider is not None:
+            return self._global_config.default_provider
+
+        # No configuration found
+        return None
+
+    def resolve_provider_name(self) -> str | None:
+        """Resolve the effective provider name.
+
+        Returns:
+            The provider name, or None if no configuration is set.
+        """
+        config = self.resolve()
+        return config.provider if config else None
+
+    def resolve_model(self) -> str | None:
+        """Resolve the effective model name.
+
+        Returns:
+            The model name, or None if no model override is configured.
+        """
+        config = self.resolve()
+        return config.model if config else None
+
+    def resolve_options(self) -> dict[str, Any]:
+        """Resolve the effective provider options.
+
+        Returns:
+            A dictionary of provider-specific options.
+        """
+        config = self.resolve()
+        return config.options if config else {}