feat!: Add ManagedResult, RunnerResult, and Runner protocol; rename invoke() to run()

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: jsonbailey

packages/sdk/server-ai/src/ldai/__init__.py

@@ -36,10 +36,13 @@
     AgentGraphRunner,
     AgentResult,
     AgentRunner,
+    ManagedResult,
+    Runner,
+    RunnerResult,
     ToolRegistry,
 )
 from ldai.providers.types import JudgeResult
-from ldai.tracker import AIGraphTracker
+from ldai.tracker import AIGraphTracker, LDAIMetricSummary
 
 __all__ = [
     'LDAIClient',
@@ -48,6 +51,10 @@
     'AgentGraphRunner',
     'AgentResult',
     'AgentGraphResult',
+    'ManagedResult',
+    'Runner',
+    'RunnerResult',
+    'LDAIMetricSummary',
     'ToolRegistry',
     'AIAgentConfig',
     'AIAgentConfigDefault',

packages/sdk/server-ai/src/ldai/managed_agent.py

@@ -1,43 +1,55 @@
 """ManagedAgent — LaunchDarkly managed wrapper for agent invocations."""
 
+from typing import Union
+
 from ldai.models import AIAgentConfig
 from ldai.providers import AgentResult, AgentRunner
+from ldai.providers.runner import Runner
+from ldai.providers.types import ManagedResult, RunnerResult
 
 
 class ManagedAgent:
     """
     LaunchDarkly managed wrapper for AI agent invocations.
 
-    Holds an AgentRunner. Handles tracking automatically via ``create_tracker()``.
+    Holds an AgentRunner or Runner. Handles tracking automatically via
+    ``create_tracker()``.
     Obtain an instance via ``LDAIClient.create_agent()``.
     """
 
     def __init__(
         self,
         ai_config: AIAgentConfig,
-        agent_runner: AgentRunner,
+        agent_runner: Union[Runner, AgentRunner],
     ):
         self._ai_config = ai_config
         self._agent_runner = agent_runner
 
-    async def run(self, input: str) -> AgentResult:
+    async def run(self, input: str) -> ManagedResult:
         """
         Run the agent with the given input string.
 
         :param input: The user prompt or input to the agent
-        :return: AgentResult containing the agent's output and metrics
+        :return: ManagedResult containing the agent's output and metric summary
         """
         tracker = self._ai_config.create_tracker()
-        return await tracker.track_metrics_of_async(
-            lambda result: result.metrics,
+        result: Union[RunnerResult, AgentResult] = await tracker.track_metrics_of_async(
+            lambda r: r.metrics,
             lambda: self._agent_runner.run(input),
         )
+        # Support both RunnerResult (content) and legacy AgentResult (output)
+        content = result.content if isinstance(result, RunnerResult) else result.output  # type: ignore[union-attr]
+        return ManagedResult(
+            content=content,
+            metrics=tracker.get_summary(),
+            raw=result.raw,
+        )
 
-    def get_agent_runner(self) -> AgentRunner:
+    def get_agent_runner(self) -> Union[Runner, AgentRunner]:
         """
-        Return the underlying AgentRunner for advanced use.
+        Return the underlying runner for advanced use.
 
-        :return: The AgentRunner instance.
+        :return: The Runner or AgentRunner instance.
         """
         return self._agent_runner
 

packages/sdk/server-ai/src/ldai/managed_model.py

@@ -1,41 +1,112 @@
 import asyncio
-from typing import List, Optional
+import warnings
+from typing import List, Union
 
 from ldai.models import AICompletionConfig, LDMessage
 from ldai.providers.model_runner import ModelRunner
-from ldai.providers.types import JudgeResult, ModelResponse
+from ldai.providers.runner import Runner
+from ldai.providers.types import JudgeResult, ManagedResult, ModelResponse, RunnerResult
 from ldai.tracker import LDAIConfigTracker
 
 
 class ManagedModel:
     """
     LaunchDarkly managed wrapper for AI model invocations.
 
-    Holds a ModelRunner. Handles conversation management, judge evaluation
-    dispatch, and tracking automatically via ``create_tracker()``.
+    Holds a Runner (or legacy ModelRunner). Handles conversation management,
+    judge evaluation dispatch, and tracking automatically via ``create_tracker()``.
     Obtain an instance via ``LDAIClient.create_model()``.
     """
 
     def __init__(
         self,
         ai_config: AICompletionConfig,
-        model_runner: ModelRunner,
+        model_runner: Union[Runner, ModelRunner],
     ):
         self._ai_config = ai_config
         self._model_runner = model_runner
         self._messages: List[LDMessage] = []
 
-    async def invoke(self, prompt: str) -> ModelResponse:
+    async def run(self, prompt: str) -> ManagedResult:
         """
-        Invoke the model with a prompt string.
+        Run the model with a prompt string.
 
         Appends the prompt to the conversation history, prepends any
         system messages from the config, delegates to the runner, and
         appends the response to the history.
 
+        :param prompt: The user prompt to send to the model
+        :return: ManagedResult containing the model's response, metric summary,
+            and an optional evaluations task
+        """
+        tracker = self._ai_config.create_tracker()
+
+        user_message = LDMessage(role='user', content=prompt)
+        self._messages.append(user_message)
+
+        config_messages = self._ai_config.messages or []
+        all_messages = config_messages + self._messages
+
+        result: Union[RunnerResult, ModelResponse] = await tracker.track_metrics_of_async(
+            lambda r: r.metrics,
+            lambda: self._invoke_runner(all_messages),
+        )
+
+        # Support both new RunnerResult and legacy ModelResponse
+        if isinstance(result, RunnerResult):
+            content = result.content
+            raw = result.raw
+            parsed = result.parsed
+            assistant_message = LDMessage(role='assistant', content=content)
+        else:
+            content = result.message.content
+            raw = getattr(result, 'raw', None)
+            parsed = getattr(result, 'parsed', None)
+            assistant_message = result.message
+
+        input_text = '\r\n'.join(m.content for m in self._messages) if self._messages else ''
+
+        evaluations_task = self._track_judge_results(tracker, input_text, content)
+
+        self._messages.append(assistant_message)
+
+        return ManagedResult(
+            content=content,
+            metrics=tracker.get_summary(),
+            raw=raw,
+            parsed=parsed,
+            evaluations=evaluations_task,
+        )
+
+    async def _invoke_runner(
+        self, all_messages: List[LDMessage]
+    ) -> Union[RunnerResult, ModelResponse]:
+        """
+        Delegate to the runner.  Supports both the new ``Runner`` protocol
+        (``run(messages) → RunnerResult``) and the legacy ``ModelRunner``
+        (``invoke_model(messages) → ModelResponse``).
+        """
+        if isinstance(self._model_runner, Runner):
+            return await self._model_runner.run(all_messages)
+        # Legacy ModelRunner path
+        return await self._model_runner.invoke_model(all_messages)  # type: ignore[union-attr]
+
+    async def invoke(self, prompt: str) -> ModelResponse:
+        """
+        Invoke the model with a prompt string.
+
+        .. deprecated::
+            Use :meth:`run` instead. This method will be removed in a future
+            release once the migration to :class:`ManagedResult` is complete.
+
         :param prompt: The user prompt to send to the model
         :return: ModelResponse containing the model's response and metrics
         """
+        warnings.warn(
+            "ManagedModel.invoke() is deprecated. Use run() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         tracker = self._ai_config.create_tracker()
 
         user_message = LDMessage(role='user', content=prompt)
@@ -44,9 +115,9 @@ async def invoke(self, prompt: str) -> ModelResponse:
         config_messages = self._ai_config.messages or []
         all_messages = config_messages + self._messages
 
-        response = await tracker.track_metrics_of_async(
+        response: ModelResponse = await tracker.track_metrics_of_async(
             lambda result: result.metrics,
-            lambda: self._model_runner.invoke_model(all_messages),
+            lambda: self._model_runner.invoke_model(all_messages),  # type: ignore[union-attr]
         )
 
         input_text = '\r\n'.join(m.content for m in self._messages) if self._messages else ''

packages/sdk/server-ai/src/ldai/providers/__init__.py

@@ -2,13 +2,16 @@
 from ldai.providers.agent_runner import AgentRunner
 from ldai.providers.ai_provider import AIProvider
 from ldai.providers.model_runner import ModelRunner
+from ldai.providers.runner import Runner
 from ldai.providers.runner_factory import RunnerFactory
 from ldai.providers.types import (
     AgentGraphResult,
     AgentResult,
     JudgeResult,
     LDAIMetrics,
+    ManagedResult,
     ModelResponse,
+    RunnerResult,
     StructuredResponse,
     ToolRegistry,
 )
@@ -21,9 +24,12 @@
     'AgentRunner',
     'JudgeResult',
     'LDAIMetrics',
+    'ManagedResult',
     'ModelResponse',
     'ModelRunner',
+    'Runner',
     'RunnerFactory',
+    'RunnerResult',
     'StructuredResponse',
     'ToolRegistry',
 ]

packages/sdk/server-ai/src/ldai/providers/runner.py

@@ -0,0 +1,37 @@
+"""Unified Runner protocol for AI providers."""
+
+from typing import Any, Dict, Optional, Protocol, runtime_checkable
+
+from ldai.providers.types import RunnerResult
+
+
+@runtime_checkable
+class Runner(Protocol):
+    """
+    Unified runtime capability interface for all AI provider runners.
+
+    A :class:`Runner` is a focused, configured object that performs a single
+    AI invocation.  Both model runners and agent runners implement this protocol.
+
+    :param input: The input to the runner (string prompt, list of messages, or
+        other provider-specific input type).
+    :param output_type: Optional JSON schema dict that requests structured output.
+        When provided, the runner populates :attr:`~RunnerResult.parsed` on the
+        returned :class:`RunnerResult`.
+    :return: :class:`RunnerResult` containing ``content``, ``metrics``, and
+        optionally ``raw`` and ``parsed``.
+    """
+
+    async def run(
+        self,
+        input: Any,
+        output_type: Optional[Dict[str, Any]] = None,
+    ) -> RunnerResult:
+        """
+        Execute the runner with the given input.
+
+        :param input: The input to the runner.
+        :param output_type: Optional JSON schema for structured output.
+        :return: RunnerResult containing content, metrics, raw, and parsed fields.
+        """
+        ...

packages/sdk/server-ai/src/ldai/providers/types.py

@@ -7,7 +7,7 @@
 from typing import Any, Callable, Dict, List, Optional
 
 from ldai.models import LDMessage
-from ldai.tracker import TokenUsage
+from ldai.tracker import LDAIMetricSummary, TokenUsage
 
 # Type alias for a registry of tools available to an agent.
 # Keys are tool names; values are the callable implementations.
@@ -38,10 +38,48 @@ def to_dict(self) -> Dict[str, Any]:
         return result
 
 
+@dataclass
+class RunnerResult:
+    """
+    Result returned by a :class:`~ldai.providers.runner.Runner` from a single
+    invocation.
+
+    This is the unified return type for all Runner implementations.
+    ``evaluations`` is intentionally absent — judge evaluations are dispatched
+    by the managed layer and live on :class:`ManagedResult`.
+    """
+    content: str
+    metrics: LDAIMetrics
+    raw: Optional[Any] = None
+    parsed: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class ManagedResult:
+    """
+    Result returned by the managed layer (:class:`~ldai.ManagedModel` /
+    :class:`~ldai.ManagedAgent`) after a single invocation.
+
+    ``metrics`` is an :class:`~ldai.tracker.LDAIMetricSummary` (from
+    ``tracker.get_summary()``) rather than a raw :class:`LDAIMetrics`.
+    ``evaluations`` is an optional asyncio Task that resolves to a list of
+    :class:`JudgeResult` instances when awaited.
+    """
+    content: str
+    metrics: LDAIMetricSummary
+    raw: Optional[Any] = None
+    parsed: Optional[Dict[str, Any]] = None
+    evaluations: Optional[asyncio.Task[List[JudgeResult]]] = None
+
+
 @dataclass
 class ModelResponse:
     """
     Response from a model invocation.
+
+    .. deprecated::
+        Use :class:`RunnerResult` (from a runner) and :class:`ManagedResult`
+        (from the managed layer) instead.
     """
     message: LDMessage
     metrics: LDAIMetrics
@@ -52,6 +90,9 @@ class ModelResponse:
 class StructuredResponse:
     """
     Structured response from AI models.
+
+    .. deprecated::
+        Structured output is now represented by :attr:`RunnerResult.parsed`.
     """
     data: Dict[str, Any]
     raw_response: str
@@ -96,6 +137,10 @@ def to_dict(self) -> Dict[str, Any]:
 class AgentResult:
     """
     Result from a single-agent run.
+
+    .. deprecated::
+        Use :class:`ManagedResult` (managed layer) or :class:`RunnerResult`
+        (runner layer) instead.
     """
     output: str
     raw: Any