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

@@ -2,6 +2,7 @@
 
 from ldai.models import AIAgentConfig
 from ldai.providers import AgentResult, AgentRunner
+from ldai.providers.types import ManagedResult
 
 
 class ManagedAgent:
@@ -20,18 +21,23 @@ def __init__(
         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: AgentResult = await tracker.track_metrics_of_async(
+            lambda r: r.metrics,
             lambda: self._agent_runner.run(input),
         )
+        return ManagedResult(
+            content=result.output,
+            metrics=tracker.get_summary(),
+            raw=result.raw,
+        )
 
     def get_agent_runner(self) -> AgentRunner:
         """

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

@@ -1,9 +1,10 @@
 import asyncio
-from typing import List, Optional
+import warnings
+from typing import List
 
 from ldai.models import AICompletionConfig, LDMessage
 from ldai.providers.model_runner import ModelRunner
-from ldai.providers.types import JudgeResult, ModelResponse
+from ldai.providers.types import JudgeResult, ManagedResult, ModelResponse
 from ldai.tracker import LDAIConfigTracker
 
 
@@ -25,17 +26,62 @@ def __init__(
         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
+
+        response = await tracker.track_metrics_of_async(
+            lambda result: result.metrics,
+            lambda: self._model_runner.invoke_model(all_messages),
+        )
+
+        content = response.message.content
+        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(response.message)
+
+        return ManagedResult(
+            content=content,
+            metrics=tracker.get_summary(),
+            raw=getattr(response, 'raw', None),
+            parsed=getattr(response, 'parsed', None),
+            evaluations=evaluations_task,
+        )
+
+    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)

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

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

@@ -41,15 +41,31 @@ class LDAIMetricSummary:
     """
 
     def __init__(self):
-        self._duration = None
-        self._success = None
-        self._feedback = None
-        self._usage = None
-        self._time_to_first_token = None
+        self._duration_ms: Optional[int] = None
+        self._success: Optional[bool] = None
+        self._feedback: Optional[Dict[str, FeedbackKind]] = None
+        self._usage: Optional[TokenUsage] = None
+        self._time_to_first_token: Optional[int] = None
+        self._tool_calls: Optional[List[str]] = None
+        self._resumption_token: Optional[str] = None
+
+    @property
+    def duration_ms(self) -> Optional[int]:
+        """Duration of the AI operation in milliseconds."""
+        return self._duration_ms
 
     @property
     def duration(self) -> Optional[int]:
-        return self._duration
+        """
+        .. deprecated::
+            Use :attr:`duration_ms` instead.
+        """
+        warnings.warn(
+            "LDAIMetricSummary.duration is deprecated. Use duration_ms instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self._duration_ms
 
     @property
     def success(self) -> Optional[bool]:
@@ -67,6 +83,20 @@ def usage(self) -> Optional[TokenUsage]:
     def time_to_first_token(self) -> Optional[int]:
         return self._time_to_first_token
 
+    @property
+    def tool_calls(self) -> Optional[List[str]]:
+        """List of tool keys that were invoked during this operation."""
+        return self._tool_calls
+
+    @property
+    def resumption_token(self) -> Optional[str]:
+        """
+        URL-safe Base64-encoded resumption token captured at tracker
+        instantiation. Useful for deferred feedback flows where a downstream
+        process needs to associate events with the original execution.
+        """
+        return self._resumption_token
+
 
 class LDAIConfigTracker:
     """
@@ -107,8 +137,10 @@ def __init__(
         self._provider_name = provider_name
         self._context = context
         self._graph_key = graph_key
-        self._summary = LDAIMetricSummary()
         self._run_id = run_id
+        self._summary = LDAIMetricSummary()
+        # Capture resumption_token immediately so it's available on the summary at instantiation.
+        self._summary._resumption_token = self.resumption_token
 
     @property
     def resumption_token(self) -> str:
@@ -200,10 +232,10 @@ def track_duration(self, duration: int) -> None:
 
         :param duration: Duration in milliseconds.
         """
-        if self._summary.duration is not None:
+        if self._summary.duration_ms is not None:
             log.warning("Duration has already been tracked for this execution. %s", self.__get_track_data())
             return
-        self._summary._duration = duration
+        self._summary._duration_ms = duration
         self._ld_client.track(
             "$ld:ai:duration:total", self._context, self.__get_track_data(), duration
         )