docs(api): describe supported search rankers (#6395)

# What does this PR do?

Adds a schema description to `SearchRankingOptions.ranker` that lists
the currently supported ranking algorithms: `weighted`, `rrf`, `neural`,
and `classifier`.

The field remains `str | None`, so this is documentation-only and
preserves acceptance of other strings for OpenAI API compatibility. A
regression test verifies the generated Pydantic schema, and the
checked-in OpenAPI specifications are regenerated.

Closes #6176

## Test Plan

```bash
uv run ruff format --check src/ogx_api/vector_io/models.py tests/unit/providers/responses/builtin/test_openai_responses_file_search_ranking_options.py
uv run ruff check src/ogx_api/vector_io/models.py tests/unit/providers/responses/builtin/test_openai_responses_file_search_ranking_options.py
uv run pytest -q tests/unit/providers/responses/builtin/test_openai_responses_file_search_ranking_options.py
PYTHONUTF8=1 uv run ./scripts/run_openapi_generator.sh
```

Output:

```text
2 files already formatted
All checks passed!
2 passed in 0.05s

Stable schema is valid
Experimental schema is valid
Deprecated schema is valid
Combined (stainless) schema is valid
OpenAPI specification generated successfully!
Schemas: 430
Paths: 50
Operations: 70

{
  "anyOf": [{"type": "string"}, {"type": "null"}],
  "default": 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.",
  "title": "Ranker"
}
```

I also attempted the full pre-commit run twice; initialization could not
fetch `pre-commit-hooks` because the GitHub connection timed out/reset.
The relevant Ruff, pytest, schema validation, and generated-file checks
above completed locally.

---------

Signed-off-by: KXH <shepherdlaurie238@gmail.com>

Author: KXHXK

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?"