refactor: address review feedback on docstrings

Author: jsonbailey

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

@@ -11,15 +11,7 @@ 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``.
+    AI invocation.
     """
 
     async def run(

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

@@ -16,22 +16,19 @@
 
 @dataclass
 class LDAIMetrics:
-    """
-    Metrics information for AI operations that includes success status, token
-    usage, and optional enrichment fields populated by runners.
-
-    ``tool_calls`` is a list of tool-call names observed during the invocation
-    (populated by agent runners that execute tool loops).
+    """Contains metrics for a single AI invocation."""
 
-    ``duration_ms`` is the wall-clock duration of the runner invocation in
-    milliseconds, when measured by the runner itself rather than externally.
-    When set, the tracker uses this value directly instead of measuring elapsed
-    time.
-    """
     success: bool
+    """Whether the invocation succeeded."""
+
     usage: Optional[TokenUsage] = None
+    """Optional token usage information."""
+
     tool_calls: Optional[List[str]] = None
+    """Ordered list of tool-call names observed during the invocation."""
+
     duration_ms: Optional[int] = None
+    """Wall-clock duration of the runner invocation in milliseconds."""
 
     def to_dict(self) -> Dict[str, Any]:
         """
@@ -55,36 +52,39 @@ def to_dict(self) -> Dict[str, Any]:
 
 @dataclass
 class RunnerResult:
-    """
-    Result returned by a :class:`~ldai.providers.runner.Runner` from a single
-    invocation.
+    """Contains the result of a single AI model 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
+    """The text content returned by the model."""
+
     metrics: LDAIMetrics
+    """Metrics for this invocation."""
+
     raw: Optional[Any] = None
+    """Optional provider-native response object for advanced consumers."""
+
     parsed: Optional[Dict[str, Any]] = None
+    """Optional parsed structured output, populated when ``output_type`` was supplied."""
 
 
 @dataclass
 class ManagedResult:
-    """
-    Result returned by the managed layer (:class:`~ldai.ManagedModel` /
-    :class:`~ldai.ManagedAgent`) after a single invocation.
+    """Contains the result of a managed AI invocation, including metrics and optional judge evaluations."""
 
-    ``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
+    """The text content returned by the model."""
+
     metrics: LDAIMetricSummary
+    """Aggregated metric summary from the tracker for this invocation."""
+
     raw: Optional[Any] = None
+    """Optional provider-native response object for advanced consumers."""
+
     parsed: Optional[Dict[str, Any]] = None
+    """Optional parsed structured output, populated when ``output_type`` was supplied."""
+
     evaluations: Optional[asyncio.Task[List[JudgeResult]]] = None
+    """Optional asyncio Task that resolves to the list of :class:`JudgeResult` instances when awaited."""
 
 
 @dataclass
@@ -116,16 +116,28 @@ class StructuredResponse:
 
 @dataclass
 class JudgeResult:
-    """
-    Result from a judge evaluation.
-    """
+    """Contains the result of a single judge evaluation."""
+
     judge_config_key: Optional[str] = None
+    """The configuration key of the judge that produced this result."""
+
     success: bool = False
+    """Whether the judge evaluation completed successfully."""
+
     error_message: Optional[str] = None
-    sampled: bool = False  # True when the evaluation was sampled and run
+    """Error message describing why the evaluation failed, if any."""
+
+    sampled: bool = False
+    """True when the evaluation was sampled and run."""
+
     metric_key: Optional[str] = None
+    """The metric key under which this judge's score is reported."""
+
     score: Optional[float] = None
+    """The numeric score (0-1) returned by the judge."""
+
     reasoning: Optional[str] = None
+    """The judge's reasoning text accompanying the score."""
 
     def to_dict(self) -> Dict[str, Any]:
         """
@@ -164,10 +176,16 @@ class AgentResult:
 
 @dataclass
 class AgentGraphResult:
-    """
-    Result from an agent graph run.
-    """
+    """Contains the result of an agent graph run."""
+
     output: str
+    """The agent graph's final output content."""
+
     raw: Any
+    """The provider-native response object from the graph run."""
+
     metrics: LDAIMetrics
+    """Metrics recorded during the graph run."""
+
     evaluations: Optional[List[JudgeResult]] = None
+    """Optional list of judge evaluation results produced for the graph run."""

packages/sdk/server-ai/tests/test_managed_agent.py

@@ -6,8 +6,7 @@
 from ldai import LDAIClient, ManagedAgent
 from ldai.managed_agent import ManagedAgent
 from ldai.models import AIAgentConfig, AIAgentConfigDefault, ModelConfig, ProviderConfig
-from ldai.providers import AgentResult
-from ldai.providers.types import LDAIMetrics, ManagedResult
+from ldai.providers.types import LDAIMetrics, ManagedResult, RunnerResult
 from ldai.tracker import LDAIMetricSummary
 
 from ldclient import Config, Context, LDClient
@@ -64,20 +63,20 @@ async def test_run_delegates_to_agent_runner(self):
         mock_config = MagicMock(spec=AIAgentConfig)
         mock_tracker = MagicMock()
         mock_tracker.track_metrics_of_async = AsyncMock(
-            return_value=AgentResult(
-                output="Test response",
-                raw=None,
+            return_value=RunnerResult(
+                content="Test response",
                 metrics=LDAIMetrics(success=True, usage=None),
+                raw=None,
             )
         )
         mock_tracker.get_summary = MagicMock(return_value=_make_summary(True))
         mock_config.create_tracker = MagicMock(return_value=mock_tracker)
         mock_runner = MagicMock()
         mock_runner.run = AsyncMock(
-            return_value=AgentResult(
-                output="Test response",
-                raw=None,
+            return_value=RunnerResult(
+                content="Test response",
                 metrics=LDAIMetrics(success=True, usage=None),
+                raw=None,
             )
         )
 
@@ -96,10 +95,10 @@ async def test_run_uses_create_tracker_for_fresh_tracker(self):
         mock_config = MagicMock(spec=AIAgentConfig)
         fresh_tracker = MagicMock()
         fresh_tracker.track_metrics_of_async = AsyncMock(
-            return_value=AgentResult(
-                output="Fresh tracker response",
-                raw=None,
+            return_value=RunnerResult(
+                content="Fresh tracker response",
                 metrics=LDAIMetrics(success=True, usage=None),
+                raw=None,
             )
         )
         fresh_tracker.get_summary = MagicMock(return_value=_make_summary(True))
@@ -163,7 +162,7 @@ async def test_returns_managed_agent_when_runner_available(self, ldai_client: LD
 
         mock_runner = MagicMock()
         mock_runner.run = AsyncMock(
-            return_value=AgentResult(output="Hello!", raw=None, metrics=LDAIMetrics(success=True, usage=None))
+            return_value=RunnerResult(content="Hello!", metrics=LDAIMetrics(success=True, usage=None), raw=None)
         )
 
         original = rf.RunnerFactory.create_agent

packages/sdk/server-ai/tests/test_managed_model.py

@@ -9,11 +9,18 @@
 from ldai.evaluator import Evaluator
 from ldai.managed_model import ManagedModel
 from ldai.models import AICompletionConfig, LDMessage, ModelConfig, ProviderConfig
-from ldai.providers.types import JudgeResult, LDAIMetrics, ManagedResult, ModelResponse
+from ldai.providers.types import JudgeResult, LDAIMetrics, ManagedResult, ModelResponse, RunnerResult
 from ldai.tracker import LDAIConfigTracker, LDAIMetricSummary
 
 
 
+def _make_runner_result(content: str = 'response text') -> RunnerResult:
+    return RunnerResult(
+        content=content,
+        metrics=LDAIMetrics(success=True, usage=None),
+    )
+
+
 def _make_model_response(content: str = 'response text') -> ModelResponse:
     return ModelResponse(
         message=LDMessage(role='assistant', content=content),
@@ -30,7 +37,7 @@ def _make_summary() -> LDAIMetricSummary:
 def _make_config_with_tracker(evaluator: Evaluator) -> tuple[AICompletionConfig, MagicMock]:
     """Build an AICompletionConfig with a fully-mocked tracker."""
     mock_tracker = MagicMock(spec=LDAIConfigTracker)
-    mock_tracker.track_metrics_of_async = AsyncMock(return_value=_make_model_response())
+    mock_tracker.track_metrics_of_async = AsyncMock(return_value=_make_runner_result())
     mock_tracker.get_summary = MagicMock(return_value=_make_summary())
     config = AICompletionConfig(
         key='test-config',
@@ -56,10 +63,10 @@ async def test_run_returns_managed_result(self):
         )
 
         mock_runner = MagicMock()
-        mock_runner.invoke_model = AsyncMock(return_value=_make_model_response('hi'))
+        mock_runner.invoke_model = AsyncMock(return_value=_make_runner_result('hi'))
 
         mock_tracker = MagicMock(spec=LDAIConfigTracker)
-        mock_tracker.track_metrics_of_async = AsyncMock(return_value=_make_model_response('hi'))
+        mock_tracker.track_metrics_of_async = AsyncMock(return_value=_make_runner_result('hi'))
         mock_tracker.get_summary = MagicMock(return_value=_make_summary())
         config = AICompletionConfig(
             key='test-config',
@@ -96,7 +103,7 @@ async def _slow_evaluate(input_text: str, output_text: str) -> List[JudgeResult]
         )
 
         mock_runner = MagicMock()
-        mock_runner.invoke_model = AsyncMock(return_value=_make_model_response())
+        mock_runner.invoke_model = AsyncMock(return_value=_make_runner_result())
 
         config, _tracker = _make_config_with_tracker(evaluator)
         model = ManagedModel(config, mock_runner)
@@ -130,7 +137,7 @@ async def _evaluate_coro(input_text: str, output_text: str) -> List[JudgeResult]
         )
 
         mock_runner = MagicMock()
-        mock_runner.invoke_model = AsyncMock(return_value=_make_model_response())
+        mock_runner.invoke_model = AsyncMock(return_value=_make_runner_result())
 
         config, _tracker = _make_config_with_tracker(evaluator)
         model = ManagedModel(config, mock_runner)
@@ -160,7 +167,7 @@ async def _evaluate_coro(input_text: str, output_text: str) -> List[JudgeResult]
         )
 
         mock_runner = MagicMock()
-        mock_runner.invoke_model = AsyncMock(return_value=_make_model_response())
+        mock_runner.invoke_model = AsyncMock(return_value=_make_runner_result())
 
         config, mock_tracker = _make_config_with_tracker(evaluator)
         mock_tracker.track_judge_result = MagicMock()
@@ -195,7 +202,7 @@ async def _evaluate_coro(input_text: str, output_text: str) -> List[JudgeResult]
         )
 
         mock_runner = MagicMock()
-        mock_runner.invoke_model = AsyncMock(return_value=_make_model_response())
+        mock_runner.invoke_model = AsyncMock(return_value=_make_runner_result())
 
         config, mock_tracker = _make_config_with_tracker(evaluator)
         mock_tracker.track_judge_result = MagicMock()
@@ -212,7 +219,7 @@ async def test_noop_evaluator_returns_empty_list(self):
         evaluator = Evaluator.noop()
 
         mock_runner = MagicMock()
-        mock_runner.invoke_model = AsyncMock(return_value=_make_model_response())
+        mock_runner.invoke_model = AsyncMock(return_value=_make_runner_result())
 
         config, _tracker = _make_config_with_tracker(evaluator)
         model = ManagedModel(config, mock_runner)
@@ -232,7 +239,9 @@ async def test_invoke_emits_deprecation_warning(self):
         mock_runner = MagicMock()
         mock_runner.invoke_model = AsyncMock(return_value=_make_model_response())
 
-        config, _tracker = _make_config_with_tracker(evaluator)
+        config, mock_tracker = _make_config_with_tracker(evaluator)
+        # invoke() expects a ModelResponse from the tracker, not a RunnerResult.
+        mock_tracker.track_metrics_of_async = AsyncMock(return_value=_make_model_response())
         model = ManagedModel(config, mock_runner)
 
         with pytest.warns(DeprecationWarning, match=r"ManagedModel\.invoke\(\) is deprecated"):

packages/sdk/server-ai/tests/test_runner_abcs.py

@@ -1,17 +1,17 @@
 import pytest
 
-from ldai.providers import AgentGraphResult, AgentGraphRunner, AgentResult, AgentRunner, ToolRegistry
-from ldai.providers.types import LDAIMetrics
+from ldai.providers import AgentGraphResult, AgentGraphRunner, AgentRunner, ToolRegistry
+from ldai.providers.types import LDAIMetrics, RunnerResult
 
 
 # --- Concrete test doubles ---
 
 class ConcreteAgentRunner:
     async def run(self, input):
-        return AgentResult(
-            output=f"agent response to: {input}",
-            raw={"raw": input},
+        return RunnerResult(
+            content=f"agent response to: {input}",
             metrics=LDAIMetrics(success=True),
+            raw={"raw": input},
         )
 
 
@@ -39,20 +39,20 @@ def test_agent_runner_structural_check_fails_when_run_missing():
 
 
 @pytest.mark.asyncio
-async def test_agent_runner_run_returns_agent_result():
+async def test_agent_runner_run_returns_runner_result():
     runner = ConcreteAgentRunner()
     result = await runner.run("hello")
-    assert isinstance(result, AgentResult)
-    assert result.output == "agent response to: hello"
+    assert isinstance(result, RunnerResult)
+    assert result.content == "agent response to: hello"
     assert result.raw == {"raw": "hello"}
     assert result.metrics.success is True
 
 
 @pytest.mark.asyncio
-async def test_agent_result_fields():
+async def test_runner_result_fields():
     metrics = LDAIMetrics(success=True)
-    result = AgentResult(output="done", raw={"key": "val"}, metrics=metrics)
-    assert result.output == "done"
+    result = RunnerResult(content="done", metrics=metrics, raw={"key": "val"})
+    assert result.content == "done"
     assert result.raw == {"key": "val"}
     assert result.metrics is metrics
 
@@ -103,6 +103,6 @@ def test_top_level_exports():
     import ldai
     assert hasattr(ldai, 'AgentRunner')
     assert hasattr(ldai, 'AgentGraphRunner')
-    assert hasattr(ldai, 'AgentResult')
     assert hasattr(ldai, 'AgentGraphResult')
+    assert hasattr(ldai, 'RunnerResult')
     assert hasattr(ldai, 'ToolRegistry')