add score_and_complete and download_logs methods to scenario runs, and update docstrings to not leak internals

Author: sid-rl

src/runloop_api_client/sdk/async_scenario.py

@@ -11,24 +11,24 @@
 
 
 class AsyncScenario:
-    """Async wrapper around a scenario resource.
+    """A scenario for evaluating agent performance (async).
 
     Provides async methods for retrieving scenario details, updating the scenario,
-    and starting scenario runs.
+    and starting scenario runs. Obtain instances via ``runloop.scenario.from_id()``
+    or ``runloop.scenario.list()``.
 
     Example:
-        >>> scenario = sdk.scenario.from_id("scn-xxx")
+        >>> scenario = runloop.scenario.from_id("scn-xxx")
         >>> info = await scenario.get_info()
         >>> run = await scenario.run(run_name="test-run")
-        >>> devbox = run.devbox
     """
 
     def __init__(self, client: AsyncRunloop, scenario_id: str) -> None:
-        """Initialize the wrapper.
+        """Create an AsyncScenario instance.
 
-        :param client: Generated AsyncRunloop client
+        :param client: AsyncRunloop client instance
         :type client: AsyncRunloop
-        :param scenario_id: Scenario ID returned by the API
+        :param scenario_id: Scenario ID
         :type scenario_id: str
         """
         self._client = client
@@ -53,7 +53,7 @@ async def get_info(
     ) -> ScenarioView:
         """Retrieve current scenario details.
 
-        :param options: Optional request configuration
+        :param options: See :typeddict:`~runloop_api_client.sdk._types.BaseRequestOptions` for available options
         :return: Current scenario info
         :rtype: ScenarioView
         """
@@ -70,7 +70,7 @@ async def update(
 
         Only provided fields will be updated.
 
-        :param params: See SDKScenarioUpdateParams for available parameters
+        :param params: See :typeddict:`~runloop_api_client.sdk._types.SDKScenarioUpdateParams` for available parameters
         :return: Updated scenario info
         :rtype: ScenarioView
         """
@@ -83,14 +83,14 @@ async def run_async(
         self,
         **params: Unpack[SDKScenarioRunAsyncParams],
     ) -> AsyncScenarioRun:
-        """Start a new scenario run.
+        """Start a new scenario run without waiting for the devbox.
 
-        Creates a new scenario run and returns a wrapper for managing it.
-        The underlying devbox may still be starting; call await_env_ready()
-        on the returned AsyncScenarioRun to wait for it to be ready.
+        Creates a new scenario run and returns immediately. The devbox may still
+        be starting; call ``await_env_ready()`` on the returned AsyncScenarioRun
+        to wait for it to be ready.
 
-        :param params: See SDKScenarioRunParams for available parameters
-        :return: Wrapper for the new scenario run
+        :param params: See :typeddict:`~runloop_api_client.sdk._types.SDKScenarioRunAsyncParams` for available parameters
+        :return: AsyncScenarioRun instance for managing the run
         :rtype: AsyncScenarioRun
         """
         run_view = await self._client.scenarios.start_run(
@@ -103,12 +103,12 @@ async def run(
         self,
         **params: Unpack[SDKScenarioRunParams],
     ) -> AsyncScenarioRun:
-        """Start a new scenario run and wait for environment to be ready.
+        """Start a new scenario run and wait for the devbox to be ready.
 
         Convenience method that starts a run and waits for the devbox to be ready.
 
-        :param params: See SDKScenarioRunParams for available parameters
-        :return: Wrapper for the scenario run with ready environment
+        :param params: See :typeddict:`~runloop_api_client.sdk._types.SDKScenarioRunParams` for available parameters
+        :return: AsyncScenarioRun instance with ready devbox
         :rtype: AsyncScenarioRun
         """
         run_view = await self._client.scenarios.start_run_and_await_env_ready(

src/runloop_api_client/sdk/async_scenario_run.py

@@ -2,42 +2,42 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Optional
+import os
+from typing import Union, Optional
+from functools import cached_property
 from typing_extensions import Unpack, override
 
 from ..types import ScenarioRunView
-from ._types import BaseRequestOptions, LongRequestOptions
+from ._types import BaseRequestOptions, LongRequestOptions, PollingRequestOptions
 from .._client import AsyncRunloop
-from ..lib.polling import PollingConfig
+from ._helpers import filter_params
+from .async_devbox import AsyncDevbox
 from ..types.scoring_contract_result_view import ScoringContractResultView
 
-if TYPE_CHECKING:
-    from .async_devbox import AsyncDevbox
-
 
 class AsyncScenarioRun:
-    """Async wrapper around a running scenario with devbox access.
+    """A running scenario with devbox access (async).
 
     Provides async methods for managing the scenario run lifecycle, accessing
-    the underlying devbox, and retrieving scoring results.
+    the devbox, and retrieving scoring results. Obtain instances via
+    ``scenario.run()`` or ``scenario.run_async()``.
 
     Example:
-        >>> scenario = await sdk.scenario.from_id("scn-xxx")
-        >>> run = await scenario.run()
+        >>> scenario = runloop.scenario.from_id("scn-xxx")
+        >>> run = await scenario.run_async()
         >>> await run.await_env_ready()
         >>> devbox = run.devbox
         >>> # ... agent does work on the devbox ...
-        >>> await run.score()
-        >>> await run.await_scored()
-        >>> result = await run.get_score()
+        >>> await run.score_and_await()
+        >>> score = await run.get_score()
     """
 
     def __init__(self, client: AsyncRunloop, run_id: str, devbox_id: str) -> None:
-        """Initialize the wrapper.
+        """Create an AsyncScenarioRun instance.
 
-        :param client: Generated AsyncRunloop client
+        :param client: AsyncRunloop client instance
         :type client: AsyncRunloop
-        :param run_id: ScenarioRun ID returned by the API
+        :param run_id: Scenario run ID
         :type run_id: str
         :param devbox_id: Devbox ID associated with this run
         :type devbox_id: str
@@ -68,17 +68,15 @@ def devbox_id(self) -> str:
         """
         return self._devbox_id
 
-    @property
-    def devbox(self) -> "AsyncDevbox":
-        """Return an AsyncDevbox wrapper for the underlying devbox.
+    @cached_property
+    def devbox(self) -> AsyncDevbox:
+        """The devbox instance for this scenario run.
 
         Use this to interact with the devbox environment during the scenario run.
 
-        :return: AsyncDevbox wrapper instance
+        :return: AsyncDevbox instance
         :rtype: AsyncDevbox
         """
-        from .async_devbox import AsyncDevbox
-
         return AsyncDevbox(self._client, self._devbox_id)
 
     async def get_info(
@@ -87,7 +85,7 @@ async def get_info(
     ) -> ScenarioRunView:
         """Retrieve current scenario run status and metadata.
 
-        :param options: Optional request configuration
+        :param options: See :typeddict:`~runloop_api_client.sdk._types.BaseRequestOptions` for available options
         :return: Current scenario run state info
         :rtype: ScenarioRunView
         """
@@ -98,22 +96,18 @@ async def get_info(
 
     async def await_env_ready(
         self,
-        *,
-        polling_config: PollingConfig | None = None,
-        **options: Unpack[BaseRequestOptions],
+        **options: Unpack[PollingRequestOptions],
     ) -> ScenarioRunView:
         """Wait for the scenario environment (devbox) to be ready.
 
         Blocks until the devbox reaches running state.
 
-        :param polling_config: Optional polling configuration
-        :type polling_config: PollingConfig | None
-        :param options: Optional request configuration
+        :param options: See :typeddict:`~runloop_api_client.sdk._types.PollingRequestOptions` for available options
         :return: Scenario run state after environment is ready
         :rtype: ScenarioRunView
         """
-        await self._client.devboxes.await_running(self._devbox_id, polling_config=polling_config)
-        return await self.get_info(**options)
+        await self._client.devboxes.await_running(self._devbox_id, polling_config=options.get("polling_config"))
+        return await self.get_info(**filter_params(options, PollingRequestOptions))
 
     async def score(
         self,
@@ -123,7 +117,7 @@ async def score(
 
         This triggers the scoring process using the scenario's scoring contract.
 
-        :param options: Optional long-running request configuration
+        :param options: See :typeddict:`~runloop_api_client.sdk._types.LongRequestOptions` for available options
         :return: Updated scenario run state
         :rtype: ScenarioRunView
         """
@@ -134,45 +128,53 @@ async def score(
 
     async def await_scored(
         self,
-        *,
-        polling_config: PollingConfig | None = None,
-        **options: Unpack[BaseRequestOptions],
+        **options: Unpack[PollingRequestOptions],
     ) -> ScenarioRunView:
         """Wait for the scenario run to be scored.
 
         Blocks until scoring is complete.
 
-        :param polling_config: Optional polling configuration
-        :type polling_config: PollingConfig | None
-        :param options: Optional request configuration
+        :param options: See :typeddict:`~runloop_api_client.sdk._types.PollingRequestOptions` for available options
         :return: Scored scenario run state
         :rtype: ScenarioRunView
         """
         return await self._client.scenarios.runs.await_scored(
             self._id,
-            polling_config=polling_config,
             **options,
         )
 
     async def score_and_await(
         self,
-        *,
-        polling_config: PollingConfig | None = None,
-        **options: Unpack[BaseRequestOptions],
+        **options: Unpack[PollingRequestOptions],
     ) -> ScenarioRunView:
         """Submit for scoring and wait for completion.
 
         Convenience method that calls score() then await_scored().
 
-        :param polling_config: Optional polling configuration
-        :type polling_config: PollingConfig | None
-        :param options: Optional request configuration
+        :param options: See :typeddict:`~runloop_api_client.sdk._types.PollingRequestOptions` for available options
         :return: Scored scenario run state
         :rtype: ScenarioRunView
         """
         return await self._client.scenarios.runs.score_and_await(
             self._id,
-            polling_config=polling_config,
+            **options,
+        )
+
+    async def score_and_complete(
+        self,
+        **options: Unpack[PollingRequestOptions],
+    ) -> ScenarioRunView:
+        """Score the run, wait for scoring, then complete and shutdown.
+
+        Convenience method that scores the scenario run, waits for scoring to
+        finish, then completes the run and shuts down the devbox.
+
+        :param options: See :typeddict:`~runloop_api_client.sdk._types.PollingRequestOptions` for available options
+        :return: Completed scenario run state with scoring results
+        :rtype: ScenarioRunView
+        """
+        return await self._client.scenarios.runs.score_and_complete(
+            self._id,
             **options,
         )
 
@@ -182,7 +184,7 @@ async def complete(
     ) -> ScenarioRunView:
         """Complete the scenario run and shutdown the devbox.
 
-        :param options: Optional long-running request configuration
+        :param options: See :typeddict:`~runloop_api_client.sdk._types.LongRequestOptions` for available options
         :return: Final scenario run state
         :rtype: ScenarioRunView
         """
@@ -197,7 +199,7 @@ async def cancel(
     ) -> ScenarioRunView:
         """Cancel the scenario run and shutdown the devbox.
 
-        :param options: Optional long-running request configuration
+        :param options: See :typeddict:`~runloop_api_client.sdk._types.LongRequestOptions` for available options
         :return: Cancelled scenario run state
         :rtype: ScenarioRunView
         """
@@ -206,16 +208,34 @@ async def cancel(
             **options,
         )
 
+    async def download_logs(
+        self,
+        file: Union[str, os.PathLike[str]],
+        **options: Unpack[LongRequestOptions],
+    ) -> None:
+        """Download all logs for this scenario run to a zip file.
+
+        Downloads a zip archive containing all logs from the scenario run's
+        associated devbox.
+
+        :param file: Path where the zip file will be written
+        :type file: str | os.PathLike[str]
+        :param options: See :typeddict:`~runloop_api_client.sdk._types.LongRequestOptions` for available options
+        """
+        response = await self._client.scenarios.runs.download_logs(self._id, **options)
+        await response.write_to_file(file)
+
     async def get_score(
         self,
         **options: Unpack[BaseRequestOptions],
     ) -> Optional[ScoringContractResultView]:
         """Get the scoring result for this run.
 
-        Returns None if the run has not been scored yet.
+        Returns None if the run has not been scored yet. Always makes an API
+        call to retrieve the current scoring result.
 
-        :param options: Optional request configuration
-        :return: Scoring result or None
+        :param options: See :typeddict:`~runloop_api_client.sdk._types.BaseRequestOptions` for available options
+        :return: Scoring result or None if not yet scored
         :rtype: Optional[ScoringContractResultView]
         """
         info = await self.get_info(**options)