docs(api): describe supported search rankers

client-sdks/stainless/openapi.yml

@@ -13928,6 +13928,7 @@ components:
           anyOf:
           - type: string
           - type: 'null'
+          description: Name of the ranking algorithm. Supported values are "weighted", "rrf", "neural", and "classifier". Other string values are accepted for OpenAI API compatibility but are not supported.
         score_threshold:
           anyOf:
           - type: number

docs/static/deprecated-ogx-spec.yaml

@@ -7572,6 +7572,7 @@ components:
           anyOf:
           - type: string
           - type: 'null'
+          description: Name of the ranking algorithm. Supported values are "weighted", "rrf", "neural", and "classifier". Other string values are accepted for OpenAI API compatibility but are not supported.
         score_threshold:
           anyOf:
           - type: number

docs/static/experimental-ogx-spec.yaml

@@ -8942,6 +8942,7 @@ components:
           anyOf:
           - type: string
           - type: 'null'
+          description: Name of the ranking algorithm. Supported values are "weighted", "rrf", "neural", and "classifier". Other string values are accepted for OpenAI API compatibility but are not supported.
         score_threshold:
           anyOf:
           - type: number

docs/static/ogx-spec.yaml

@@ -12444,6 +12444,7 @@ components:
           anyOf:
           - type: string
           - type: 'null'
+          description: Name of the ranking algorithm. Supported values are "weighted", "rrf", "neural", and "classifier". Other string values are accepted for OpenAI API compatibility but are not supported.
         score_threshold:
           anyOf:
           - type: number

docs/static/stainless-ogx-spec.yaml

@@ -13928,6 +13928,7 @@ components:
           anyOf:
           - type: string
           - type: 'null'
+          description: Name of the ranking algorithm. Supported values are "weighted", "rrf", "neural", and "classifier". Other string values are accepted for OpenAI API compatibility but are not supported.
         score_threshold:
           anyOf:
           - type: number

src/ogx_api/vector_io/models.py

@@ -506,7 +506,13 @@ class SearchRankingOptions(BaseModel):
         weights contains "neural".
     """
 
-    ranker: str | None = None
+    ranker: str | None = Field(
+        default=None,
+        description=(
+            'Name of the ranking algorithm. Supported values are "weighted", "rrf", "neural", and '
+            '"classifier". Other string values are accepted for OpenAI API compatibility but are not supported.'
+        ),
+    )
     # NOTE: OpenAI File Search Tool requires threshold to be between 0 and 1, however
     # we don't guarantee that the score is between 0 and 1, so will leave this unconstrained
     # and let the provider handle it

tests/unit/providers/responses/builtin/test_openai_responses_file_search_ranking_options.py

@@ -10,6 +10,16 @@
 from ogx_api.vector_io import SearchRankingOptions, VectorStoreSearchResponsePage
 
 
+def test_ranking_options_schema_documents_supported_rankers():
+    """The API schema should explain which ranker values OGX supports."""
+    ranker_schema = SearchRankingOptions.model_json_schema()["properties"]["ranker"]
+
+    description = ranker_schema.get("description")
+    assert description
+    for ranker in ("weighted", "rrf", "neural", "classifier"):
+        assert ranker in description
+
+
 async def test_file_search_forwards_ranking_options_weights(mock_vector_io_api):
     """Test that file_search forwards ranking_options.weights to vector store search."""
     query = "What is machine learning?"