update scorer and scorer ops docstrings to be more helpful while not exposing system internals

Author: sid-rl

src/runloop_api_client/sdk/async_.py

@@ -479,63 +479,50 @@ async def upload_from_bytes(
 
 
 class AsyncScorerOps:
-    """High-level async manager for creating and managing scenario scorers.
-
-    Accessed via ``runloop.scorer`` from :class:`AsyncRunloopSDK`, provides
-    coroutines to create, list, and access scorers.
+    """Create and manage custom scorers (async). Access via ``runloop.scorer``.
 
     Example:
         >>> runloop = AsyncRunloopSDK()
         >>> scorer = await runloop.scorer.create(type="my_scorer", bash_script="echo 'score=1.0'")
-        >>> scorers = await runloop.scorer.list()
+        >>> all_scorers = await runloop.scorer.list()
     """
 
     def __init__(self, client: AsyncRunloop) -> None:
-        """Initialize the manager.
+        """Initialize AsyncScorerOps.
 
-        :param client: Generated AsyncRunloop client to wrap
+        :param client: AsyncRunloop client instance
         :type client: AsyncRunloop
         """
         self._client = client
 
-    async def create(
-        self,
-        **params: Unpack[SDKScorerCreateParams],
-    ) -> AsyncScorer:
-        """Create a new scenario scorer.
+    async def create(self, **params: Unpack[SDKScorerCreateParams]) -> AsyncScorer:
+        """Create a new scorer with the given type and bash script.
 
         :param params: See :typeddict:`~runloop_api_client.sdk._types.SDKScorerCreateParams` for available parameters
-        :return: Wrapper bound to the newly created scorer
+        :return: The newly created scorer
         :rtype: AsyncScorer
         """
-        response = await self._client.scenarios.scorers.create(
-            **params,
-        )
+        response = await self._client.scenarios.scorers.create(**params)
         return AsyncScorer(self._client, response.id)
 
     def from_id(self, scorer_id: str) -> AsyncScorer:
-        """Return a scorer wrapper for the given ID.
+        """Get an AsyncScorer instance for an existing scorer ID.
 
-        :param scorer_id: Scorer ID to wrap
+        :param scorer_id: ID of the scorer
         :type scorer_id: str
-        :return: Wrapper for the scorer resource
+        :return: AsyncScorer instance for the given ID
         :rtype: AsyncScorer
         """
         return AsyncScorer(self._client, scorer_id)
 
-    async def list(
-        self,
-        **params: Unpack[SDKScorerListParams],
-    ) -> list[AsyncScorer]:
-        """List all scenario scorers.
+    async def list(self, **params: Unpack[SDKScorerListParams]) -> list[AsyncScorer]:
+        """List all scorers, optionally filtered by parameters.
 
         :param params: See :typeddict:`~runloop_api_client.sdk._types.SDKScorerListParams` for available parameters
-        :return: List of scorer wrappers
+        :return: List of scorers
         :rtype: list[AsyncScorer]
         """
-        page = await self._client.scenarios.scorers.list(
-            **params,
-        )
+        page = await self._client.scenarios.scorers.list(**params)
         return [AsyncScorer(self._client, item.id) async for item in page]
 
 

src/runloop_api_client/sdk/async_scorer.py

@@ -14,18 +14,23 @@
 
 
 class AsyncScorer:
-    """Asynchronous wrapper around a scenario scorer resource."""
+    """A custom scorer for evaluating scenario outputs (async).
 
-    def __init__(
-        self,
-        client: AsyncRunloop,
-        scorer_id: str,
-    ) -> None:
-        """Initialize the wrapper.
+    Scorers define bash scripts that produce a score (0.0-1.0) for scenario runs.
+    Obtain instances via ``runloop.scorer.create()`` or ``runloop.scorer.from_id()``.
 
-        :param client: Generated AsyncRunloop client
+    Example:
+        >>> runloop = AsyncRunloopSDK()
+        >>> scorer = await runloop.scorer.create(type="my_scorer", bash_script="echo 'score=1.0'")
+        >>> await scorer.validate(scoring_context={"output": "test"})
+    """
+
+    def __init__(self, client: AsyncRunloop, scorer_id: str) -> None:
+        """Create an AsyncScorer instance.
+
+        :param client: AsyncRunloop client instance
         :type client: AsyncRunloop
-        :param scorer_id: Scorer ID returned by the API
+        :param scorer_id: ID of the scorer
         :type scorer_id: str
         """
         self._client = client
@@ -37,54 +42,36 @@ def __repr__(self) -> str:
 
     @property
     def id(self) -> str:
-        """Return the scorer ID.
+        """The scorer's unique identifier.
 
-        :return: Unique scorer ID
+        :return: Scorer ID
         :rtype: str
         """
         return self._id
 
-    async def get_info(
-        self,
-        **options: Unpack[BaseRequestOptions],
-    ) -> ScorerRetrieveResponse:
-        """Retrieve the latest scorer details.
+    async def get_info(self, **options: Unpack[BaseRequestOptions]) -> ScorerRetrieveResponse:
+        """Fetch current scorer details from the API.
 
-        :param options: Optional request configuration
-        :return: API response describing the scorer
+        :param options: See :typeddict:`~runloop_api_client.sdk._types.BaseRequestOptions` for available options
+        :return: Current scorer details
         :rtype: ScorerRetrieveResponse
         """
-        return await self._client.scenarios.scorers.retrieve(
-            self._id,
-            **options,
-        )
+        return await self._client.scenarios.scorers.retrieve(self._id, **options)
 
-    async def update(
-        self,
-        **params: Unpack[SDKScorerUpdateParams],
-    ) -> ScorerUpdateResponse:
-        """Update the scorer.
+    async def update(self, **params: Unpack[SDKScorerUpdateParams]) -> ScorerUpdateResponse:
+        """Update the scorer's type or bash script.
 
         :param params: See :typeddict:`~runloop_api_client.sdk._types.SDKScorerUpdateParams` for available parameters
-        :return: API response with updated scorer details
+        :return: Updated scorer details
         :rtype: ScorerUpdateResponse
         """
-        return await self._client.scenarios.scorers.update(
-            self._id,
-            **params,
-        )
+        return await self._client.scenarios.scorers.update(self._id, **params)
 
-    async def validate(
-        self,
-        **params: Unpack[SDKScorerValidateParams],
-    ) -> ScorerValidateResponse:
-        """Validate the scorer with a given context.
+    async def validate(self, **params: Unpack[SDKScorerValidateParams]) -> ScorerValidateResponse:
+        """Run the scorer against the provided context and return the result.
 
         :param params: See :typeddict:`~runloop_api_client.sdk._types.SDKScorerValidateParams` for available parameters
-        :return: API response with validation results
+        :return: Validation result with score
         :rtype: ScorerValidateResponse
         """
-        return await self._client.scenarios.scorers.validate(
-            self._id,
-            **params,
-        )
+        return await self._client.scenarios.scorers.validate(self._id, **params)

src/runloop_api_client/sdk/scorer.py

@@ -14,18 +14,23 @@
 
 
 class Scorer:
-    """Synchronous wrapper around a scenario scorer resource."""
+    """A custom scorer for evaluating scenario outputs.
 
-    def __init__(
-        self,
-        client: Runloop,
-        scorer_id: str,
-    ) -> None:
-        """Initialize the wrapper.
+    Scorers define bash scripts that produce a score (0.0-1.0) for scenario runs.
+    Obtain instances via ``runloop.scorer.create()`` or ``runloop.scorer.from_id()``.
 
-        :param client: Generated Runloop client
+    Example:
+        >>> runloop = RunloopSDK()
+        >>> scorer = runloop.scorer.create(type="my_scorer", bash_script="echo 'score=1.0'")
+        >>> scorer.validate(scoring_context={"output": "test"})
+    """
+
+    def __init__(self, client: Runloop, scorer_id: str) -> None:
+        """Create a Scorer instance.
+
+        :param client: Runloop client instance
         :type client: Runloop
-        :param scorer_id: Scorer ID returned by the API
+        :param scorer_id: ID of the scorer
         :type scorer_id: str
         """
         self._client = client
@@ -37,54 +42,36 @@ def __repr__(self) -> str:
 
     @property
     def id(self) -> str:
-        """Return the scorer ID.
+        """The scorer's unique identifier.
 
-        :return: Unique scorer ID
+        :return: Scorer ID
         :rtype: str
         """
         return self._id
 
-    def get_info(
-        self,
-        **options: Unpack[BaseRequestOptions],
-    ) -> ScorerRetrieveResponse:
-        """Retrieve the latest scorer details.
+    def get_info(self, **options: Unpack[BaseRequestOptions]) -> ScorerRetrieveResponse:
+        """Fetch current scorer details from the API.
 
-        :param options: Optional request configuration
-        :return: API response describing the scorer
+        :param options: See :typeddict:`~runloop_api_client.sdk._types.BaseRequestOptions` for available options
+        :return: Current scorer details
         :rtype: ScorerRetrieveResponse
         """
-        return self._client.scenarios.scorers.retrieve(
-            self._id,
-            **options,
-        )
+        return self._client.scenarios.scorers.retrieve(self._id, **options)
 
-    def update(
-        self,
-        **params: Unpack[SDKScorerUpdateParams],
-    ) -> ScorerUpdateResponse:
-        """Update the scorer.
+    def update(self, **params: Unpack[SDKScorerUpdateParams]) -> ScorerUpdateResponse:
+        """Update the scorer's type or bash script.
 
         :param params: See :typeddict:`~runloop_api_client.sdk._types.SDKScorerUpdateParams` for available parameters
-        :return: API response with updated scorer details
+        :return: Updated scorer details
         :rtype: ScorerUpdateResponse
         """
-        return self._client.scenarios.scorers.update(
-            self._id,
-            **params,
-        )
+        return self._client.scenarios.scorers.update(self._id, **params)
 
-    def validate(
-        self,
-        **params: Unpack[SDKScorerValidateParams],
-    ) -> ScorerValidateResponse:
-        """Validate the scorer with a given context.
+    def validate(self, **params: Unpack[SDKScorerValidateParams]) -> ScorerValidateResponse:
+        """Run the scorer against the provided context and return the result.
 
         :param params: See :typeddict:`~runloop_api_client.sdk._types.SDKScorerValidateParams` for available parameters
-        :return: API response with validation results
+        :return: Validation result with score
         :rtype: ScorerValidateResponse
         """
-        return self._client.scenarios.scorers.validate(
-            self._id,
-            **params,
-        )
+        return self._client.scenarios.scorers.validate(self._id, **params)

src/runloop_api_client/sdk/sync.py

@@ -474,63 +474,50 @@ def upload_from_bytes(
 
 
 class ScorerOps:
-    """High-level manager for creating and managing scenario scorers.
-
-    Accessed via ``runloop.scorer`` from :class:`RunloopSDK`, provides methods
-    to create, list, and access scorers.
+    """Create and manage custom scorers. Access via ``runloop.scorer``.
 
     Example:
         >>> runloop = RunloopSDK()
         >>> scorer = runloop.scorer.create(type="my_scorer", bash_script="echo 'score=1.0'")
-        >>> scorers = runloop.scorer.list()
+        >>> all_scorers = runloop.scorer.list()
     """
 
     def __init__(self, client: Runloop) -> None:
-        """Initialize the manager.
+        """Initialize ScorerOps.
 
-        :param client: Generated Runloop client to wrap
+        :param client: Runloop client instance
         :type client: Runloop
         """
         self._client = client
 
-    def create(
-        self,
-        **params: Unpack[SDKScorerCreateParams],
-    ) -> Scorer:
-        """Create a new scenario scorer.
+    def create(self, **params: Unpack[SDKScorerCreateParams]) -> Scorer:
+        """Create a new scorer with the given type and bash script.
 
         :param params: See :typeddict:`~runloop_api_client.sdk._types.SDKScorerCreateParams` for available parameters
-        :return: Wrapper bound to the newly created scorer
+        :return: The newly created scorer
         :rtype: Scorer
         """
-        response = self._client.scenarios.scorers.create(
-            **params,
-        )
+        response = self._client.scenarios.scorers.create(**params)
         return Scorer(self._client, response.id)
 
     def from_id(self, scorer_id: str) -> Scorer:
-        """Return a scorer wrapper for the given ID.
+        """Get a Scorer instance for an existing scorer ID.
 
-        :param scorer_id: Scorer ID to wrap
+        :param scorer_id: ID of the scorer
         :type scorer_id: str
-        :return: Wrapper for the scorer resource
+        :return: Scorer instance for the given ID
         :rtype: Scorer
         """
         return Scorer(self._client, scorer_id)
 
-    def list(
-        self,
-        **params: Unpack[SDKScorerListParams],
-    ) -> list[Scorer]:
-        """List all scenario scorers.
+    def list(self, **params: Unpack[SDKScorerListParams]) -> list[Scorer]:
+        """List all scorers, optionally filtered by parameters.
 
         :param params: See :typeddict:`~runloop_api_client.sdk._types.SDKScorerListParams` for available parameters
-        :return: List of scorer wrappers
+        :return: List of scorers
         :rtype: list[Scorer]
         """
-        page = self._client.scenarios.scorers.list(
-            **params,
-        )
+        page = self._client.scenarios.scorers.list(**params)
         return [Scorer(self._client, item.id) for item in page]