adaptive-sdk 0.1.14__py3-none-any.whl → 0.12.1__py3-none-any.whl

adaptive_sdk/resources/abtests.py

@@ -91,6 +91,7 @@ class ABTests(SyncAPIResource, UseCaseResource):  # type: ignore[misc]
         Args:
             active: Filter on active or inactive AB tests.
             status: Filter on one of the possible AB test status.
+            use_case: Use case key. Falls back to client's default if not provided.
         """
         if status:
             status_input = AbcampaignStatus(status.upper())
@@ -187,6 +188,7 @@ class AsyncABTests(AsyncAPIResource, UseCaseResource):  # type: ignore[misc]
         Args:
             active: Filter on active or inactive AB tests.
             status: Filter on one of the possible AB test status.
+            use_case: Use case key. Falls back to client's default if not provided.
         """
         if status:
             status_input = AbcampaignStatus(status.upper())

adaptive_sdk/resources/base_resource.py

@@ -1,4 +1,5 @@
 from __future__ import annotations
+
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -20,10 +21,23 @@ class AsyncAPIResource:
 
 
 class UseCaseResource:
+    """Mixin class for resources that operate within a use case context."""
+
     def __init__(self, client: UseCaseClient) -> None:
         self._client = client
 
     def use_case_key(self, use_case: str | None) -> str:
+        """Get the use case key, falling back to the client's default.
+
+        Args:
+            use_case: Optional explicit use case key.
+
+        Returns:
+            The resolved use case key.
+
+        Raises:
+            ValueError: If no use case is provided and no default is set.
+        """
         target_use_case = use_case or self._client.default_use_case
         if target_use_case is None:
             raise ValueError(
@@ -36,6 +50,14 @@ or explicitly pass `use_case` as an input parameter."""
         return target_use_case
 
     def optional_use_case_key(self, use_case: str | None) -> str | None:
+        """Get the use case key if available, or None.
+
+        Args:
+            use_case: Optional explicit use case key.
+
+        Returns:
+            The use case key if provided or default is set, otherwise None.
+        """
         if use_case:
             return use_case
         elif self._client.default_use_case:

adaptive_sdk/resources/chat.py

@@ -1,23 +1,26 @@
 from __future__ import annotations
+
 import json
-from loguru import logger
-from uuid import UUID
 from typing import (
-    Dict,
-    List,
+    TYPE_CHECKING,
     AsyncGenerator,
+    Dict,
     Generator,
+    List,
     Literal,
     overload,
-    TYPE_CHECKING,
 )
+from uuid import UUID
+
+from loguru import logger
 from typing_extensions import override
+
 from adaptive_sdk import input_types
 from adaptive_sdk.error_handling import rest_error_handler
 from adaptive_sdk.rest import rest_types
 from adaptive_sdk.utils import convert_optional_UUID, get_full_model_path
 
-from .base_resource import SyncAPIResource, AsyncAPIResource, UseCaseResource
+from .base_resource import AsyncAPIResource, SyncAPIResource, UseCaseResource
 
 if TYPE_CHECKING:
     from adaptive_sdk.client import Adaptive, AsyncAdaptive
@@ -102,11 +105,14 @@ class Chat(SyncAPIResource, UseCaseResource):  # type: ignore[misc]
             top_p: Threshold for top-p sampling.
             stream_include_usage: If set, an additional chunk will be streamed with the token usage statistics for
                 the entire request.
+            session_id: Session ID to group related interactions.
+            use_case: Use case key. Falls back to client's default if not provided.
             user: ID of user making request. If not `None`, will be logged as metadata for the request.
             ab_campaign: AB test key. If set, request will be guaranteed to count towards AB test results,
                 no matter the configured `traffic_split`.
             n: Number of chat completions to generate for each input messages.
             labels: Key-value pairs of interaction labels.
+            store: Whether to store the interaction for future reference. Stores by default.
 
         Examples:
         ```
@@ -237,13 +243,16 @@ class AsyncChat(AsyncAPIResource, UseCaseResource):  # type: ignore[misc]
             max_tokens: Maximum # of tokens allowed to generate.
             temperature: Sampling temperature.
             top_p: Threshold for top-p sampling.
-            stream_include_usage: If set, an additional chunk will be streamed with the token usaage statistics for
+            stream_include_usage: If set, an additional chunk will be streamed with the token usage statistics for
                 the entire request.
+            session_id: Session ID to group related interactions.
+            use_case: Use case key. Falls back to client's default if not provided.
             user: ID of user making request. If not `None`, will be logged as metadata for the request.
             ab_campaign: AB test key. If set, request will be guaranteed to count towards AB test results,
                 no matter the configured `traffic_split`.
             n: Number of chat completions to generate for each input messages.
             labels: Key-value pairs of interaction labels.
+            store: Whether to store the interaction for future reference. Stores by default.
 
         Examples:
         ```

adaptive_sdk/resources/compute_pools.py

@@ -1,12 +1,14 @@
 # type: ignore
 
 from __future__ import annotations
+
 from typing import TYPE_CHECKING
+
 from pydantic import BaseModel
 
-from adaptive_sdk.graphql_client import ResizePartitionInput, HarmonyStatus
+from adaptive_sdk.graphql_client import HarmonyStatus, ResizePartitionInput
 
-from .base_resource import SyncAPIResource, AsyncAPIResource, UseCaseResource
+from .base_resource import AsyncAPIResource, SyncAPIResource, UseCaseResource
 
 if TYPE_CHECKING:
     from adaptive_sdk.client import Adaptive, AsyncAdaptive
@@ -28,6 +30,11 @@ class ComputePools(SyncAPIResource, UseCaseResource):
         UseCaseResource.__init__(self, client)
 
     def list(self):
+        """List all compute pools available in the system.
+
+        Returns:
+            A list of compute pool objects.
+        """
         return self._gql_client.list_compute_pools().compute_pools
 
     def resize_inference_partition(self, compute_pool_key: str, size: int) -> list[ResizeResult]:
@@ -52,7 +59,7 @@ class ComputePools(SyncAPIResource, UseCaseResource):
                     _ = self._gql_client.resize_inference_partition(input)
                     resize_results.append(ResizeResult(harmony_group_key=hg.key, success=True))
                 except Exception as e:
-                    resize_results.append(ResizeResult(harmony_group_key=hg.key, success=False, error_message=str(e)))
+                    resize_results.append(ResizeResult(harmony_group_key=hg.key, success=False, error=str(e)))
 
         return resize_results
 
@@ -67,6 +74,11 @@ class AsyncComputePools(AsyncAPIResource, UseCaseResource):
         UseCaseResource.__init__(self, client)
 
     async def list(self):
+        """List all compute pools available in the system.
+
+        Returns:
+            A list of compute pool objects.
+        """
         return (await self._gql_client.list_compute_pools()).compute_pools
 
     async def resize_inference_partition(self, compute_pool_key: str, size: int) -> list[ResizeResult]:
@@ -91,6 +103,6 @@ class AsyncComputePools(AsyncAPIResource, UseCaseResource):
                     _ = await self._gql_client.resize_inference_partition(input)
                     resize_results.append(ResizeResult(harmony_group_key=hg.key, success=True))
                 except Exception as e:
-                    resize_results.append(ResizeResult(harmony_group_key=hg.key, success=False, error_message=str(e)))
+                    resize_results.append(ResizeResult(harmony_group_key=hg.key, success=False, error=str(e)))
 
         return resize_results

adaptive_sdk/resources/embeddings.py

@@ -1,12 +1,13 @@
 from __future__ import annotations
-from typing import Literal, TYPE_CHECKING
+
+from typing import TYPE_CHECKING, Literal
 from uuid import UUID
-from typing_extensions import override
+
 from adaptive_sdk.error_handling import rest_error_handler
 from adaptive_sdk.rest import rest_types
 from adaptive_sdk.utils import convert_optional_UUID, get_full_model_path
 
-from .base_resource import SyncAPIResource, AsyncAPIResource, UseCaseResource
+from .base_resource import AsyncAPIResource, SyncAPIResource, UseCaseResource
 
 if TYPE_CHECKING:
     from adaptive_sdk.client import Adaptive, AsyncAdaptive
@@ -51,7 +52,8 @@ class Embeddings(SyncAPIResource, UseCaseResource):  # type: ignore[misc]
             user=convert_optional_UUID(user),
         )
         r = self._rest_client.post(
-            ROUTE, data=emb_input.model_dump_json(exclude_none=True), headers={"Content-Type": "application/json"}  # type: ignore
+            ROUTE,
+            json=emb_input.model_dump_json(exclude_none=True),
         )
         rest_error_handler(r)
         return rest_types.EmbeddingsResponseList.model_validate(r.json())
@@ -69,7 +71,7 @@ class AsyncEmbeddings(AsyncAPIResource, UseCaseResource):  # type: ignore[misc]
     async def create(
         self,
         input: str,
-        model_key: str | None = None,
+        model: str | None = None,
         encoding_format: Literal["Float", "Base64"] = "Float",
         use_case: str | None = None,
         user: str | UUID | None = None,
@@ -82,18 +84,20 @@ class AsyncEmbeddings(AsyncAPIResource, UseCaseResource):  # type: ignore[misc]
             model: Target model key for inference. If `None`, the requests will be routed to the use case's default model.
                 Request will error if default model is not an embedding model.
             encoding_format: Encoding format of response.
+            use_case: Use case key. Falls back to client's default if not provided.
             user: ID of user making the requests. If not `None`, will be logged as metadata for the request.
         """
         encoding_format_enum = rest_types.EmbeddingsEncodingFormat(encoding_format)
         emb_input = rest_types.GenerateEmbeddingsInput(
             input=input,
-            model=get_full_model_path(self.use_case_key(use_case), model_key),
+            model=get_full_model_path(self.use_case_key(use_case), model),
             encoding_format=encoding_format_enum,
             dimensions=None,
             user=convert_optional_UUID(user),
         )
         r = await self._rest_client.post(
-            ROUTE, data=emb_input.model_dump_json(exclude_none=True), headers={"Content-Type": "application/json"}  # type: ignore
+            ROUTE,
+            json=emb_input.model_dump_json(exclude_none=True),
         )
         rest_error_handler(r)
         return rest_types.EmbeddingsResponseList.model_validate(r.json())

adaptive_sdk/resources/feedback.py

@@ -1,25 +1,29 @@
 from __future__ import annotations
-from typing import Literal, Sequence, List, Dict, TYPE_CHECKING
+
+from typing import TYPE_CHECKING, Dict, List, Literal, Sequence
 from uuid import UUID
+
 from typing_extensions import override
+
 from adaptive_sdk import input_types
 from adaptive_sdk.error_handling import rest_error_handler
 from adaptive_sdk.graphql_client import (
+    MetricCreate,
     MetricData,
     MetricDataAdmin,
-    MetricCreate,
     MetricKind,
-    MetricScoringType,
-    MetricWithContextData,
     MetricLink,
+    MetricScoringType,
     MetricUnlink,
+    MetricWithContextData,
 )
 from adaptive_sdk.rest import rest_types
 from adaptive_sdk.utils import (
     convert_optional_UUID,
     validate_comparison_completion,
 )
-from .base_resource import SyncAPIResource, AsyncAPIResource, UseCaseResource
+
+from .base_resource import AsyncAPIResource, SyncAPIResource, UseCaseResource
 
 if TYPE_CHECKING:
     from adaptive_sdk.client import Adaptive, AsyncAdaptive
@@ -41,10 +45,8 @@ class Feedback(SyncAPIResource, UseCaseResource):  # type: ignore
     def register_key(
         self,
         key: str,
-        kind: Literal["scalar", "bool"] = "scalar",
-        scoring_type: Literal[
-            "higher_is_better", "lower_is_better"
-        ] = "higher_is_better",
+        kind: Literal["scalar", "bool"],
+        scoring_type: Literal["higher_is_better", "lower_is_better"] = "higher_is_better",
         name: str | None = None,
         description: str | None = None,
     ) -> MetricData:
@@ -58,7 +60,7 @@ class Feedback(SyncAPIResource, UseCaseResource):  # type: ignore
                 If `"scalar"`, you can log any integer or float value.
             scoring_type: Indication of what good means for this feeback key; a higher numeric value (or `True`)
                 , or a lower numeric value (or `False`).
-            name Human-readable feedback name that will render in the UI. If `None`, will be the same as `key`.
+            name: Human-readable feedback name that will render in the UI. If `None`, will be the same as `key`.
             description: Description of intended purpose or nuances of feedback. Will render in the UI.
         """
         input = MetricCreate(
@@ -140,9 +142,7 @@ class Feedback(SyncAPIResource, UseCaseResource):  # type: ignore
             user_id=convert_optional_UUID(user),
             details=details,
         )
-        r = self._rest_client.post(
-            FEEDBACK_ROUTE, json=input.model_dump(exclude_none=True)
-        )
+        r = self._rest_client.post(FEEDBACK_ROUTE, json=input.model_dump(exclude_none=True))
         rest_error_handler(r)
         return rest_types.FeedbackOutput.model_validate(r.json())
 
@@ -171,9 +171,7 @@ class Feedback(SyncAPIResource, UseCaseResource):  # type: ignore
             tied: Indicator if both completions tied as equally bad or equally good.
         """
 
-        clean_preffered_completion = validate_comparison_completion(
-            preferred_completion
-        )
+        clean_preffered_completion = validate_comparison_completion(preferred_completion)
         clean_other_completion = validate_comparison_completion(other_completion)
         input_messages = [rest_types.ChatMessage(**m) for m in messages] if messages else None  # type: ignore
 
@@ -186,9 +184,7 @@ class Feedback(SyncAPIResource, UseCaseResource):  # type: ignore
             tied=rest_types.ComparisonTie(tied) if tied else None,
             use_case=self.use_case_key(use_case),
         )
-        r = self._rest_client.post(
-            PREFERENCE_ROUTE, json=input.model_dump(exclude_none=True)
-        )
+        r = self._rest_client.post(PREFERENCE_ROUTE, json=input.model_dump(exclude_none=True))
         rest_error_handler(r)
         return rest_types.ComparisonOutput.model_validate(r.json())
 
@@ -206,9 +202,7 @@ class AsyncFeedback(AsyncAPIResource, UseCaseResource):  # type: ignore[misc]
         self,
         key: str,
         kind: Literal["scalar", "bool"],
-        scoring_type: Literal[
-            "higher_is_better", "lower_is_better"
-        ] = "higher_is_better",
+        scoring_type: Literal["higher_is_better", "lower_is_better"] = "higher_is_better",
         name: str | None = None,
         description: str | None = None,
     ) -> MetricData:
@@ -295,7 +289,7 @@ class AsyncFeedback(AsyncAPIResource, UseCaseResource):  # type: ignore[misc]
             value: The feedback values.
             completion_id: The completion_id to attach the feedback to.
             feedback_key: The feedback key to log against.
-            user: ID of user submitting feedback. If not `None`, will be logged as metadata for the request.
+            user_id: ID of user submitting feedback. If not `None`, will be logged as metadata for the request.
             details: Textual details for the feedback. Can be used to provide further context on the feedback `value`.
         """
         input = rest_types.AddFeedbackRequest(
@@ -305,9 +299,7 @@ class AsyncFeedback(AsyncAPIResource, UseCaseResource):  # type: ignore[misc]
             user_id=convert_optional_UUID(user_id),
             details=details,
         )
-        r = await self._rest_client.post(
-            FEEDBACK_ROUTE, json=input.model_dump(exclude_none=True)
-        )
+        r = await self._rest_client.post(FEEDBACK_ROUTE, json=input.model_dump(exclude_none=True))
         rest_error_handler(r)
         return rest_types.FeedbackOutput.model_validate(r.json())
 
@@ -330,15 +322,14 @@ class AsyncFeedback(AsyncAPIResource, UseCaseResource):  # type: ignore[misc]
                 corresponding the a valid model key and its attributed completion.
             other_completion: Can be a completion_id or a dict with keys `model` and `text`,
                 corresponding the a valid model key and its attributed completion.
-            user: ID of user submitting feedback.
+            user_id: ID of user submitting feedback.
             messages: Input chat messages, each dict with keys `role` and `content`.
                 Ignored if `preferred_` and `other_completion` are completion_ids.
             tied: Indicator if both completions tied as equally bad or equally good.
+            use_case: Use case key. Falls back to client's default if not provided.
 
         """
-        clean_preffered_completion = validate_comparison_completion(
-            preferred_completion
-        )
+        clean_preffered_completion = validate_comparison_completion(preferred_completion)
         clean_other_completion = validate_comparison_completion(other_completion)
         input_messages = [rest_types.ChatMessage(**m) for m in messages] if messages else None  # type: ignore
 
@@ -351,8 +342,6 @@ class AsyncFeedback(AsyncAPIResource, UseCaseResource):  # type: ignore[misc]
             tied=rest_types.ComparisonTie(tied) if tied else None,
             use_case=self.use_case_key(use_case),
         )
-        r = await self._rest_client.post(
-            PREFERENCE_ROUTE, json=input.model_dump(exclude_none=True)
-        )
+        r = await self._rest_client.post(PREFERENCE_ROUTE, json=input.model_dump(exclude_none=True))
         rest_error_handler(r)
         return rest_types.ComparisonOutput.model_validate(r.json())

adaptive_sdk/resources/interactions.py

@@ -76,11 +76,13 @@ class Interactions(SyncAPIResource, UseCaseResource):  # type: ignore[misc]
         Create/log an interaction.
 
         Args:
-            model: Model key.
             messages: Input chat messages, each dict should have keys `role` and `content`.
             completion: Model completion.
+            model: Model key.
             feedbacks: List of feedbacks, each dict should with keys `feedback_key`, `value` and optional(`details`).
             user: ID of user making the request. If not `None`, will be logged as metadata for the interaction.
+            session_id: Session ID to group related interactions.
+            use_case: Use case key. Falls back to client's default if not provided.
             ab_campaign: AB test key. If set, provided `feedbacks` will count towards AB test results.
             labels: Key-value pairs of interaction labels.
             created_at: Timestamp of interaction creation or ingestion.
@@ -187,14 +189,15 @@ class AsyncInteractions(AsyncAPIResource, UseCaseResource):  # type: ignore[misc
         Create/log an interaction.
 
         Args:
-            model: Model key.
             messages: Input chat messages, each dict should have keys `role` and `content`.
             completion: Model completion.
+            model: Model key.
             feedbacks: List of feedbacks, each dict should with keys `feedback_key`, `value` and optional(`details`).
             user: ID of user making the request. If not `None`, will be logged as metadata for the interaction.
+            session_id: Session ID to group related interactions.
+            use_case: Use case key. Falls back to client's default if not provided.
             ab_campaign: AB test key. If set, provided `feedbacks` will count towards AB test results.
             labels: Key-value pairs of interaction labels.
-            created_at: Timestamp of interaction creation or ingestion.
         """
         input_messages, input_feedbacks = _prepare_add_interactions_inputs(messages, feedbacks)
 

adaptive_sdk/resources/jobs.py

@@ -1,19 +1,19 @@
 from __future__ import annotations
-from typing import TYPE_CHECKING, Literal, Any, cast
+
+from typing import TYPE_CHECKING, Any, Literal, cast
 
 from adaptive_sdk.graphql_client import (
     CursorPageInput,
     JobInput,
-    ListJobsJobs,
-    ListJobsFilterInput,
     JobKind,
+    ListJobsFilterInput,
+    ListJobsJobs,
     ListJobsJobsNodes,
 )
-
-
-from .base_resource import SyncAPIResource, AsyncAPIResource, UseCaseResource
 from adaptive_sdk.output_types import JobDataPlus
 
+from .base_resource import AsyncAPIResource, SyncAPIResource, UseCaseResource
+
 if TYPE_CHECKING:
     from adaptive_sdk.client import Adaptive, AsyncAdaptive
 
@@ -28,6 +28,14 @@ class Jobs(SyncAPIResource, UseCaseResource):  # type: ignore[misc]
         UseCaseResource.__init__(self, client)
 
     def get(self, job_id: str) -> JobDataPlus | None:
+        """Get the details of a specific job.
+
+        Args:
+            job_id: The ID of the job to retrieve.
+
+        Returns:
+            The job data if found, otherwise None.
+        """
         job_data = self._gql_client.describe_job(id=job_id).job
         return JobDataPlus.from_job_data(job_data) if job_data else None
 
@@ -51,6 +59,19 @@ class Jobs(SyncAPIResource, UseCaseResource):  # type: ignore[misc]
         ) = None,
         use_case: str | None = None,
     ) -> ListJobsJobs:
+        """List jobs with pagination and filtering options.
+
+        Args:
+            first: Number of jobs to return from the beginning.
+            last: Number of jobs to return from the end.
+            after: Cursor for forward pagination.
+            before: Cursor for backward pagination.
+            kind: Filter by job types.
+            use_case: Filter by use case key.
+
+        Returns:
+            A paginated list of jobs.
+        """
         use_case = self.optional_use_case_key(use_case)
         page = CursorPageInput(first=first, last=last, after=after, before=before)
         validated_filter = ListJobsFilterInput(
@@ -74,6 +95,19 @@ class Jobs(SyncAPIResource, UseCaseResource):  # type: ignore[misc]
         use_case: str | None = None,
         compute_pool: str | None = None,
     ) -> JobDataPlus:
+        """Run a job using a specified recipe.
+
+        Args:
+            recipe_key: The key of the recipe to run.
+            num_gpus: Number of GPUs to allocate for the job.
+            args: Optional arguments to pass to the recipe; must match the recipe schema.
+            name: Optional human-readable name for the job.
+            use_case: Use case key for the job.
+            compute_pool: Optional compute pool key to run the job on.
+
+        Returns:
+            The created job data.
+        """
         args = args or {}
         job_data = self._gql_client.create_job(
             input=JobInput(
@@ -88,6 +122,14 @@ class Jobs(SyncAPIResource, UseCaseResource):  # type: ignore[misc]
         return JobDataPlus.from_job_data(job_data)
 
     def cancel(self, job_id: str) -> JobDataPlus:
+        """Cancel a running job.
+
+        Args:
+            job_id: The ID of the job to cancel.
+
+        Returns:
+            The updated job data after cancellation.
+        """
         job_data = self._gql_client.cancel_job(job_id=job_id).cancel_job
         return JobDataPlus.from_job_data(job_data)
 
@@ -102,6 +144,14 @@ class AsyncJobs(AsyncAPIResource, UseCaseResource):  # type: ignore[misc]
         UseCaseResource.__init__(self, client)
 
     async def get(self, job_id: str) -> JobDataPlus | None:
+        """Get the details of a specific job.
+
+        Args:
+            job_id: The ID of the job to retrieve.
+
+        Returns:
+            The job data if found, otherwise None.
+        """
         job_data = (await self._gql_client.describe_job(id=job_id)).job
         return JobDataPlus.from_job_data(job_data) if job_data else None
 
@@ -125,6 +175,19 @@ class AsyncJobs(AsyncAPIResource, UseCaseResource):  # type: ignore[misc]
         ) = None,
         use_case: str | None = None,
     ) -> ListJobsJobs:
+        """List jobs with pagination and filtering options.
+
+        Args:
+            first: Number of jobs to return from the beginning.
+            last: Number of jobs to return from the end.
+            after: Cursor for forward pagination.
+            before: Cursor for backward pagination.
+            kind: Filter by job types.
+            use_case: Filter by use case key.
+
+        Returns:
+            A paginated list of jobs.
+        """
         page = CursorPageInput(first=first, last=last, after=after, before=before)
         validated_filter = ListJobsFilterInput(
             useCase=self.use_case_key(use_case),
@@ -146,6 +209,19 @@ class AsyncJobs(AsyncAPIResource, UseCaseResource):  # type: ignore[misc]
         use_case: str | None = None,
         compute_pool: str | None = None,
     ) -> JobDataPlus:
+        """Run a job using a specified recipe.
+
+        Args:
+            recipe_key: The key of the recipe to run.
+            num_gpus: Number of GPUs to allocate for the job.
+            args: Optional arguments to pass to the recipe.
+            name: Optional human-readable name for the job.
+            use_case: Use case key for the job.
+            compute_pool: Optional compute pool key to run the job on.
+
+        Returns:
+            The created job data.
+        """
         args = args or {}
         job_data = (
             await self._gql_client.create_job(
@@ -162,5 +238,13 @@ class AsyncJobs(AsyncAPIResource, UseCaseResource):  # type: ignore[misc]
         return JobDataPlus.from_job_data(job_data)
 
     async def cancel(self, job_id: str) -> JobDataPlus:
+        """Cancel a running job.
+
+        Args:
+            job_id: The ID of the job to cancel.
+
+        Returns:
+            The updated job data after cancellation.
+        """
         job_data = (await self._gql_client.cancel_job(job_id=job_id)).cancel_job
         return JobDataPlus.from_job_data(job_data)

adaptive_sdk/resources/models.py

@@ -224,9 +224,10 @@ class Models(SyncAPIResource, UseCaseResource):  # type: ignore[misc]
 
         Args:
             model: Model key.
-            wait: If the model is not deployed already, attaching it to the use case will automatically deploy it.
-                If `True`, this call blocks until model is `Online`.
-            make_default: Make the model the use case's default on attachment.
+            use_case: Use case key. Falls back to client's default if not provided.
+
+        Returns:
+            True if the model was successfully attached.
         """
 
         input = AddModelToUseCaseInput(
@@ -243,6 +244,18 @@ class Models(SyncAPIResource, UseCaseResource):  # type: ignore[misc]
         use_case: str | None = None,
         placement: input_types.ModelPlacementInput | None = None,
     ) -> ModelServiceData:
+        """Deploy a model for inference in the specified use case.
+
+        Args:
+            model: Model key.
+            wait: If `True`, block until the model is online.
+            make_default: Make the model the use case's default after deployment.
+            use_case: Use case key.
+            placement: Optional placement configuration for the model.
+
+        Returns:
+            The model service data after deployment.
+        """
         input = DeployModelInput(
             model=model,
             useCase=self.use_case_key(use_case),
@@ -424,6 +437,10 @@ class AsyncModels(AsyncAPIResource, UseCaseResource):  # type: ignore[misc]
 
         Args:
             model: Model key.
+            use_case: Use case key. Falls back to client's default if not provided.
+
+        Returns:
+            The updated model service data.
         """
         return await self.update(model=model, use_case=use_case)
 

adaptive_sdk/resources/permissions.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
+
 from typing import TYPE_CHECKING, List
 
 from adaptive_sdk.graphql_client import ListPermissions
 
-from .base_resource import SyncAPIResource, AsyncAPIResource, UseCaseResource
+from .base_resource import AsyncAPIResource, SyncAPIResource, UseCaseResource
 
 if TYPE_CHECKING:
     from adaptive_sdk.client import Adaptive, AsyncAdaptive
@@ -19,6 +20,11 @@ class Permissions(SyncAPIResource, UseCaseResource):  # type: ignore[misc]
         UseCaseResource.__init__(self, client)
 
     def list(self) -> List[str]:
+        """List all available permissions in the system.
+
+        Returns:
+            A list of permission identifiers.
+        """
         return self._gql_client.list_permissions().permissions
 
 
@@ -32,4 +38,9 @@ class AsyncPermissions(AsyncAPIResource, UseCaseResource):  # type: ignore[misc]
         UseCaseResource.__init__(self, client)
 
     async def list(self) -> List[str]:
+        """List all available permissions in the system.
+
+        Returns:
+            A list of permission identifiers.
+        """
         return (await self._gql_client.list_permissions()).permissions