From 9162e8390f8bdd0461e2b9e929b9777d06c57503 Mon Sep 17 00:00:00 2001
From: theQuert <leo.lee@apertis.ai>
Date: Wed, 7 Oct 2026 08:19:47 +0800
Subject: [PATCH] fix(rerank): mark rerank.create() as unavailable

The Apertis API does not serve POST /v1/rerank, so every call returns a 404.
Mark both create() methods with typing_extensions.deprecated, so callers get
a DeprecationWarning and type checkers flag the call, and say so in the
docstring and README. The resource and its request/response contract stay
in place for when the endpoint ships.

Closes #6

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Uy5vXsRpMhug7v3XwTMZHv
---
 README.md                   |  9 +++++++--
 apertis/resources/rerank.py | 13 +++++++++++++
 tests/test_rerank.py        | 30 +++++++++++++++++++++++++++++-
 3 files changed, 49 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 6fd323c..a838be0 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,7 @@ print(response.choices[0].message.content)
 - **Extended Thinking**: Deep thinking for complex problems
 - **Messages API**: Anthropic-native message format
 - **Responses API**: OpenAI Responses API format
-- **Rerank API**: Document reranking for RAG
+- **Rerank API**: Document reranking for RAG (not currently available, see below)
 - **Models API**: List and retrieve available models
 - **Type Hints**: Full type annotations for IDE support
 - **Automatic Retries**: Built-in retry logic for transient errors
@@ -426,7 +426,9 @@ response = client.responses.create(
 
 ### Rerank API
 
-Rerank documents for RAG applications:
+> **Not currently available.** The Apertis API does not serve `POST /v1/rerank` yet, so
+> `client.rerank.create()` returns a 404 `NotFoundError` and emits a `DeprecationWarning`.
+> The interface below is kept for when the endpoint ships.
 
 ```python
 results = client.rerank.create(
@@ -533,6 +535,7 @@ Any model available on [Apertis AI](https://apertis.ai), including:
 - `text-embedding-3-small`, `text-embedding-3-large`
 
 ### Rerank Models
+Listed in the model catalog, but not callable until the rerank endpoint ships.
 - `BAAI/bge-reranker-v2-m3`
 - `Qwen/Qwen3-Reranker-0.6B`, `Qwen/Qwen3-Reranker-4B`, `Qwen/Qwen3-Reranker-8B`
 
@@ -553,6 +556,8 @@ the `publish` confirmation value.
 
 ### Unreleased
 - Add `parallel_tool_calls` and `max_completion_tokens` to `chat.completions.create()`.
+- Mark `rerank.create()` as unavailable: it emits a `DeprecationWarning`, because the
+  Apertis API does not serve `POST /v1/rerank`.
 
 ### v0.3.0
 - Add the current Apertis Web Search request fields and typed top-level sources while
diff --git a/apertis/resources/rerank.py b/apertis/resources/rerank.py
index f5766e6..df6dc51 100644
--- a/apertis/resources/rerank.py
+++ b/apertis/resources/rerank.py
@@ -4,8 +4,16 @@
 
 from typing import TYPE_CHECKING, Any, Dict, List, Optional, Sequence
 
+from typing_extensions import deprecated
+
 from apertis.types.rerank import RerankResponse
 
+# ponytail: drop the decorator once the gateway serves POST /v1/rerank.
+_UNAVAILABLE = (
+    "client.rerank is not currently available: the Apertis API does not serve "
+    "POST /v1/rerank, so calls return 404."
+)
+
 if TYPE_CHECKING:
     from apertis._base_client import AsyncClient, SyncClient
 
@@ -16,6 +24,7 @@ class Rerank:
     def __init__(self, client: SyncClient) -> None:
         self._client = client
 
+    @deprecated(_UNAVAILABLE)
     def create(
         self,
         *,
@@ -27,6 +36,9 @@ def create(
     ) -> RerankResponse:
         """Rerank documents by relevance to a query.
 
+        Not currently available: the Apertis API does not serve POST /v1/rerank,
+        so this call returns a 404 NotFoundError.
+
         Args:
             model: ID of the rerank model to use.
             query: The query to rank documents against.
@@ -56,6 +68,7 @@ class AsyncRerank:
     def __init__(self, client: AsyncClient) -> None:
         self._client = client
 
+    @deprecated(_UNAVAILABLE)
     async def create(
         self,
         *,
diff --git a/tests/test_rerank.py b/tests/test_rerank.py
index 0c31d12..72078c6 100644
--- a/tests/test_rerank.py
+++ b/tests/test_rerank.py
@@ -6,7 +6,35 @@
 import pytest
 import respx
 
-from apertis import Apertis
+from apertis import Apertis, AsyncApertis
+
+# Rerank is marked unavailable (see TestRerankUnavailable); the remaining tests
+# still pin the request/response contract for when the gateway routes it.
+pytestmark = pytest.mark.filterwarnings("ignore:client.rerank:DeprecationWarning")
+
+
+class TestRerankUnavailable:
+    """The gateway has no /v1/rerank route, so the resource must not look supported."""
+
+    @respx.mock
+    def test_sync_create_warns(self, client: Apertis) -> None:
+        respx.post("https://api.apertis.ai/v1/rerank").mock(
+            return_value=httpx.Response(
+                200, json={"object": "list", "model": "m", "results": []}
+            )
+        )
+        with pytest.warns(DeprecationWarning, match="not currently available"):
+            client.rerank.create(model="m", query="q", documents=["d"])
+
+    @respx.mock
+    async def test_async_create_warns(self, async_client: AsyncApertis) -> None:
+        respx.post("https://api.apertis.ai/v1/rerank").mock(
+            return_value=httpx.Response(
+                200, json={"object": "list", "model": "m", "results": []}
+            )
+        )
+        with pytest.warns(DeprecationWarning, match="not currently available"):
+            await async_client.rerank.create(model="m", query="q", documents=["d"])
 
 
 class TestRerankCreate: