From ef7e999df135cf56513389d80901dbf8a0ffbd3a Mon Sep 17 00:00:00 2001 From: CleverThis Date: Thu, 9 Apr 2026 11:38:06 +0000 Subject: [PATCH] docs(spec): align AIProviderInterface with implementation (generate_changes/stream_changes) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Relates to #5801 The spec defined AIProviderInterface as a model factory with create_chat_model() and create_embedding_model() methods. The implementation uses a higher-level plan-execution interface with generate_changes() and stream_changes(). The implementation's approach is more appropriate — it directly handles plan execution rather than exposing raw LangChain model creation. The ProviderRegistry manages provider selection and configuration at a higher level. Updated AIProviderInterface to match the actual implementation: - provider_name -> name (property) - capabilities -> model_id (property) - create_chat_model() -> generate_changes() (plan execution) - create_embedding_model() -> stream_changes() (streaming plan execution) Also updated the description: auto-discovery of langchain-* packages is not implemented; instead, providers are discovered based on configured API keys. --- docs/specification.md | 49 ++++++++++++++++++++++++++++++------------- 1 file changed, 35 insertions(+), 14 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index 4accaad8..b8e6ca46 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -46427,31 +46427,52 @@ Actors can be extended through: 1. **YAML-defined agents**: Single LLM actors with custom system prompts, temperature settings, tool bindings, and capability constraints. 2. **YAML-defined graphs**: LangGraph topologies with multiple actors and tool nodes connected by edges, conditional routing, and parallel execution groups. -3. **Provider extension**: New LLM providers can be added by implementing the `AIProviderInterface` protocol and registering with the `ProviderRegistry`. The registry uses auto-discovery to detect installed `langchain-*` packages. +3. **Provider extension**: New LLM providers can be added by implementing the `AIProviderInterface` protocol and registering with the `ProviderRegistry`. The registry discovers configured providers based on available API keys and environment variables. -
from typing import Protocol
+
from collections.abc import Callable, Iterator
+from typing import Protocol
 
 class AIProviderInterface(Protocol):
-    """Protocol for LLM provider implementations."""
+    """Protocol for AI providers that generate code changes.
+
+    Implementations handle plan execution directly, generating changes
+    based on the plan, project context, and actor configuration.
+    Supported providers: openai, anthropic, google, gemini, azure,
+    openrouter, cohere, groq, together.
+    """
 
     @property
-    def provider_name(self) -> str: ...
+    def name(self) -> str: ...
+    """Provider name (e.g., 'openai', 'anthropic')."""
 
     @property
-    def capabilities(self) -> ProviderCapabilities: ...
+    def model_id(self) -> str: ...
+    """Model identifier (e.g., 'gpt-4o', 'claude-3-5-sonnet-20241022')."""
 
-    def create_chat_model(
+    def generate_changes(
         self,
-        model: str,
-        temperature: float = 0.7,
-        **kwargs,
-    ) -> BaseChatModel: ...
+        project: Project,
+        plan: Plan,
+        contexts: list[Context],
+        actor_context: ActorInvocationContext | None = None,
+        progress_callback: Callable[[int], None] | None = None,
+    ) -> ProviderResponse: ...
+    """Generate code changes based on the plan and context."""
 
-    def create_embedding_model(
+    def stream_changes(
         self,
-        model: str,
-        **kwargs,
-    ) -> BaseEmbeddings: ...
+        project: Project,
+        plan: Plan,
+        contexts: list[Context],
+        actor_context: ActorInvocationContext | None = None,
+        progress_callback: Callable[[int], None] | None = None,
+    ) -> Iterator[dict[str, object]]: ...
+    """Stream workflow events while generating changes.
+
+    Yields dicts keyed by workflow node name. Finishes with a
+    ``"__end__"`` event containing a ``ProviderResponse`` under
+    the ``response`` key.
+    """
 

 
 #### Custom Resource Types