feat(api): add new replicate.search() method (beta)

...and remove the old replicate.models.search() method from the MCP server, so tools will not have to decide between the two.

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 35
+configured_endpoints: 36
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/replicate%2Freplicate-client-87c7c57bd75c54990c679c9e87d009851cdff572815a55d1b6ee4d4ee20adaa1.yml
 openapi_spec_hash: d987f14befa536004eece7b49caad993
-config_hash: b1b4f5d24ba07b4667ffe7b9dec081e3
+config_hash: aeed03640ab6ab81b9c732cf0b9c727c

api.md

@@ -1,3 +1,15 @@
+# Replicate
+
+Types:
+
+```python
+from replicate.types import SearchResponse
+```
+
+Methods:
+
+- <code title="get /search">replicate.<a href="./src/replicate/_client.py">search</a>(\*\*<a href="src/replicate/types/client_search_params.py">params</a>) -> <a href="./src/replicate/types/search_response.py">SearchResponse</a></code>
+
 # Collections
 
 Types:

src/replicate/_client.py

@@ -27,25 +27,42 @@
 
 from . import _exceptions
 from ._qs import Querystring
+from .types import client_search_params
 from ._types import (
     NOT_GIVEN,
+    Body,
     Omit,
+    Query,
+    Headers,
     Timeout,
     NotGiven,
     Transport,
     ProxiesTypes,
     RequestOptions,
 )
-from ._utils import is_given, get_async_library
+from ._utils import (
+    is_given,
+    maybe_transform,
+    get_async_library,
+    async_maybe_transform,
+)
 from ._compat import cached_property
 from ._version import __version__
+from ._response import (
+    to_raw_response_wrapper,
+    to_streamed_response_wrapper,
+    async_to_raw_response_wrapper,
+    async_to_streamed_response_wrapper,
+)
 from ._streaming import Stream as Stream, AsyncStream as AsyncStream
 from ._exceptions import APIStatusError, ReplicateError
 from ._base_client import (
     DEFAULT_MAX_RETRIES,
     SyncAPIClient,
     AsyncAPIClient,
+    make_request_options,
 )
+from .types.search_response import SearchResponse
 
 if TYPE_CHECKING:
     from .resources import files, models, account, hardware, webhooks, trainings, collections, deployments, predictions
@@ -354,6 +371,70 @@ def copy(
     # client.with_options(timeout=10).foo.create(...)
     with_options = copy
 
+    def search(
+        self,
+        *,
+        query: str,
+        limit: int | NotGiven = NOT_GIVEN,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+    ) -> SearchResponse:
+        """
+        Search for public models, collections, and docs using a text query.
+
+        For models, the response includes all model data, plus a new `metadata` object
+        with the following fields:
+
+        - `generated_description`: A longer and more detailed AI-generated description
+          of the model
+        - `tags`: An array of tags for the model
+        - `score`: A score for the model's relevance to the search query
+
+        Example cURL request:
+
+        ```console
+        curl -s \\
+          -H "Authorization: Bearer $REPLICATE_API_TOKEN" \\
+          "https://api.replicate.com/v1/search?query=nano+banana"
+        ```
+
+        Note: This search API is currently in beta and may change in future versions.
+
+        Args:
+          query: The search query string
+
+          limit: Maximum number of model results to return (1-50, defaults to 20)
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return self.get(
+            "/search",
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=maybe_transform(
+                    {
+                        "query": query,
+                        "limit": limit,
+                    },
+                    client_search_params.ClientSearchParams,
+                ),
+            ),
+            cast_to=SearchResponse,
+        )
+
     @override
     def _make_status_error(
         self,
@@ -665,6 +746,70 @@ def copy(
     # client.with_options(timeout=10).foo.create(...)
     with_options = copy
 
+    async def search(
+        self,
+        *,
+        query: str,
+        limit: int | NotGiven = NOT_GIVEN,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+    ) -> SearchResponse:
+        """
+        Search for public models, collections, and docs using a text query.
+
+        For models, the response includes all model data, plus a new `metadata` object
+        with the following fields:
+
+        - `generated_description`: A longer and more detailed AI-generated description
+          of the model
+        - `tags`: An array of tags for the model
+        - `score`: A score for the model's relevance to the search query
+
+        Example cURL request:
+
+        ```console
+        curl -s \\
+          -H "Authorization: Bearer $REPLICATE_API_TOKEN" \\
+          "https://api.replicate.com/v1/search?query=nano+banana"
+        ```
+
+        Note: This search API is currently in beta and may change in future versions.
+
+        Args:
+          query: The search query string
+
+          limit: Maximum number of model results to return (1-50, defaults to 20)
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return await self.get(
+            "/search",
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=await async_maybe_transform(
+                    {
+                        "query": query,
+                        "limit": limit,
+                    },
+                    client_search_params.ClientSearchParams,
+                ),
+            ),
+            cast_to=SearchResponse,
+        )
+
     @override
     def _make_status_error(
         self,
@@ -705,6 +850,10 @@ class ReplicateWithRawResponse:
     def __init__(self, client: Replicate) -> None:
         self._client = client
 
+        self.search = to_raw_response_wrapper(
+            client.search,
+        )
+
     @cached_property
     def collections(self) -> collections.CollectionsResourceWithRawResponse:
         from .resources.collections import CollectionsResourceWithRawResponse
@@ -766,6 +915,10 @@ class AsyncReplicateWithRawResponse:
     def __init__(self, client: AsyncReplicate) -> None:
         self._client = client
 
+        self.search = async_to_raw_response_wrapper(
+            client.search,
+        )
+
     @cached_property
     def collections(self) -> collections.AsyncCollectionsResourceWithRawResponse:
         from .resources.collections import AsyncCollectionsResourceWithRawResponse
@@ -827,6 +980,10 @@ class ReplicateWithStreamedResponse:
     def __init__(self, client: Replicate) -> None:
         self._client = client
 
+        self.search = to_streamed_response_wrapper(
+            client.search,
+        )
+
     @cached_property
     def collections(self) -> collections.CollectionsResourceWithStreamingResponse:
         from .resources.collections import CollectionsResourceWithStreamingResponse
@@ -888,6 +1045,10 @@ class AsyncReplicateWithStreamedResponse:
     def __init__(self, client: AsyncReplicate) -> None:
         self._client = client
 
+        self.search = async_to_streamed_response_wrapper(
+            client.search,
+        )
+
     @cached_property
     def collections(self) -> collections.AsyncCollectionsResourceWithStreamingResponse:
         from .resources.collections import AsyncCollectionsResourceWithStreamingResponse

src/replicate/types/__init__.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from .prediction import Prediction as Prediction
+from .search_response import SearchResponse as SearchResponse
 from .file_get_response import FileGetResponse as FileGetResponse
 from .file_create_params import FileCreateParams as FileCreateParams
 from .file_list_response import FileListResponse as FileListResponse
@@ -11,6 +12,7 @@
 from .model_list_response import ModelListResponse as ModelListResponse
 from .model_search_params import ModelSearchParams as ModelSearchParams
 from .account_get_response import AccountGetResponse as AccountGetResponse
+from .client_search_params import ClientSearchParams as ClientSearchParams
 from .file_create_response import FileCreateResponse as FileCreateResponse
 from .file_download_params import FileDownloadParams as FileDownloadParams
 from .model_create_response import ModelCreateResponse as ModelCreateResponse

src/replicate/types/client_search_params.py

@@ -0,0 +1,15 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Required, TypedDict
+
+__all__ = ["ClientSearchParams"]
+
+
+class ClientSearchParams(TypedDict, total=False):
+    query: Required[str]
+    """The search query string"""
+
+    limit: int
+    """Maximum number of model results to return (1-50, defaults to 20)"""

src/replicate/types/search_response.py

@@ -0,0 +1,109 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import List, Optional
+from typing_extensions import Literal
+
+from .._models import BaseModel
+
+__all__ = ["SearchResponse", "Collection", "Model", "ModelMetadata", "ModelModel", "Page"]
+
+
+class Collection(BaseModel):
+    description: str
+    """A description of the collection"""
+
+    name: str
+    """The name of the collection"""
+
+    slug: str
+    """The slug of the collection (lowercase with dashes)"""
+
+    models: Optional[List[str]] = None
+    """Array of model names in the collection"""
+
+
+class ModelMetadata(BaseModel):
+    generated_description: Optional[str] = None
+    """AI-generated detailed description of the model"""
+
+    score: Optional[float] = None
+    """Search relevance score"""
+
+    tags: Optional[List[str]] = None
+    """Array of descriptive tags for the model"""
+
+
+class ModelModel(BaseModel):
+    cover_image_url: Optional[str] = None
+    """A URL for the model's cover image"""
+
+    default_example: Optional[object] = None
+    """The model's default example prediction"""
+
+    description: Optional[str] = None
+    """A description of the model"""
+
+    github_url: Optional[str] = None
+    """A URL for the model's source code on GitHub"""
+
+    is_official: Optional[bool] = None
+    """Boolean indicating whether the model is officially maintained by Replicate.
+
+    Official models are always on, have stable API interfaces, and predictable
+    pricing.
+    """
+
+    latest_version: Optional[object] = None
+    """The model's latest version"""
+
+    license_url: Optional[str] = None
+    """A URL for the model's license"""
+
+    name: Optional[str] = None
+    """The name of the model"""
+
+    owner: Optional[str] = None
+    """The name of the user or organization that owns the model"""
+
+    paper_url: Optional[str] = None
+    """A URL for the model's paper"""
+
+    run_count: Optional[int] = None
+    """The number of times the model has been run"""
+
+    url: Optional[str] = None
+    """The URL of the model on Replicate"""
+
+    visibility: Optional[Literal["public", "private"]] = None
+    """Whether the model is public or private"""
+
+
+class Model(BaseModel):
+    metadata: ModelMetadata
+
+    model: ModelModel
+
+
+class Page(BaseModel):
+    href: str
+    """URL path to the page"""
+
+    name: str
+    """Title of the page"""
+
+
+class SearchResponse(BaseModel):
+    collections: List[Collection]
+    """Array of collections that match the search query"""
+
+    models: List[Model]
+    """
+    Array of models that match the search query, each containing model data and
+    extra metadata
+    """
+
+    pages: List[Page]
+    """Array of Replicate documentation pages that match the search query"""
+
+    query: str
+    """The search term that was evaluated"""