feat(python): add opt-in request batching to TypeSafeReranker (#4316)

Adds opt-in `batch_size=40`: 80 non-null candidates use **2 requests
instead of 80**. Default `batch_size=1` preserves the existing payload.
Each batched question sees only its document and the shared query;
instructions/criteria stay unchanged. Prompts referencing
`state.document` need adaptation. Concurrency still limits requests;
retries remain SDK-managed. Batch-local IDs and ordered results preserve
duplicate documents; invalid IDs/probabilities raise without fallback.

Validation: **124 automated tests passed**, plus live search
integrations in both modes. A **100-query live subset test of the
initial implementation** (6,851 candidate pairs; `jev-1.13.0`, SDK
0.7.1, concurrency 32) passed: unbatched/batched calls **6,851/199**,
median **877/351 ms**, p95 **9,446/598 ms**. Hybrid Hit@5/Hit@10 was
**83%/89% vs 84%/90%**; vector/FTS results and exact configuration are
in the [test
report](https://github.com/lancedb/lancedb/blob/typesafe-request-batching/python/benchmarks/typesafe_batching.md).
Ruff and MkDocs passed. The simplified batching flow also passed a fresh
four-query live check: 292 candidate pairs, with 292 unbatched versus 8
batched calls.

Builds on #4209; motivated by [research
#7](https://github.com/lancedb/research/pull/7).

docs/src/python/python.md

@@ -379,6 +379,29 @@ still work. Queries return descriptors. Call
 
 ## Reranking
 
+`TypeSafeReranker` supports opt-in request batching:
+
+```python
+from lancedb.rerankers import TypeSafeReranker
+
+reranker = TypeSafeReranker(batch_size=40, max_concurrency=8)
+```
+
+The default `batch_size=1` keeps the query and document in request state and
+sends one request per non-null candidate. With `batch_size=40`, 80 non-null
+candidates require two requests. `max_concurrency` still limits simultaneous
+requests, and the SDK handles retries.
+
+In batched mode, state contains only `{"query": query}`. Each independent
+question contains `{"question": instructions, "document": document}` in its
+structured instructions, so it sees only its own document and the shared query.
+Custom instructions and criteria are kept verbatim: adapt prompts that explicitly
+reference request-state fields such as `state.document` before enabling batching.
+Null documents retain a zero score without an API call; empty strings are scored.
+API failures, mismatched answer IDs, and invalid probabilities raise errors.
+Batching changes the payload and can affect model scores; compare quality and
+latency on your workload before opting in.
+
 ::: lancedb.rerankers
     options:
       show_root_heading: false