polygres-sdk 0.4.0__tar.gz → 0.5.0__tar.gz

polygres_sdk-0.5.0/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+All notable changes to `polygres-sdk` are documented in this file.
+
+## Unreleased
+
+## 0.5.0 - 2026-09-12
+
+### Added
+
+- Pass text to existing Context, vector, and hybrid searches to generate query
+  embeddings with the configured model. Existing vector calls retain their
+  arguments and response types.
+- Build nearest query-plan branches with text and embed them during execution.
+- Control query credit usage and reuse embedding attempts across retries and
+  paginated results with idempotency keys.
+
+
+### Changed
+
+- Refresh the packaged Runtime API reference and validate compatibility against
+  the published SDK 0.4.1 contract.
+- Include the changelog in source distributions.
+
+Existing SDK methods and query-vector workflows remain available. Configure
+embedding generation through the dashboard, CLI, or MCP.
+
+## 0.4.1 - 2026-08-25
+
+### Changed
+
+- Updated the bundled public error catalog so durable Context collection sync,
+  timeout, connection, memory, storage, and index failures use their canonical
+  messages, statuses, retry guidance, and safe recovery details.
+
+### Compatibility
+
+- Existing SDK methods, signatures, request behavior, and exception classes are
+  unchanged from SDK 0.4.0.
+
+## 0.4.0 - 2026-08-16
+
+### Added
+
+- Added pgContext 0.2.0-aligned names for vector and filter registration,
+  collection deletion, point scrolling, facets, and dense plus full-text
+  queries.
+- Added a frozen SDK 0.3.0 method-contract baseline for compatibility checks.
+- Added a pinned, CI-checked pgContext 0.2.0 compatibility inventory that
+  records aligned, managed, safely partial, SQL-only, deferred privileged, and
+  experimental items with no ambiguous missing stable signatures.
+- Added typed collection aliases, limits, vector configuration, bulk points,
+  payload mutation, candidate and raw-vector search, recommendation,
+  discovery, exploration, query-plan builders and execution, index
+  diagnostics, collection telemetry, query statistics, model versions, and
+  embedding migrations.
+- Added additive pgContext compatibility counts to Context capabilities.
+
+### Compatibility
+
+- Existing SDK 0.3.0 method names remain available with unchanged signatures,
+  HTTP requests, response types, exceptions, idempotency, and retry behavior.
+- Aligned names delegate silently to the existing SDK 0.3.0 implementations.
+  Upgrading without changing application code does not select new behavior.
+
+### Changed
+
+- Added synchronized-project mode handling: `connection_info()` raises
+  `PolygresPermissionError` with `SYNCED_PROJECT_SURFACE_UNAVAILABLE` while
+  readiness, vector, hybrid, graph, text-search, and pgContext stay available.
+
+## 0.3.0 - 2026-08-14
+
+### Added
+
+- Added `project.rows.validate()`, `insert()`, `upsert()`, and `ignore()` for
+  single-row Runtime writes with typed results and stable validation errors.
+- Added explicit pgContext reconciliation to row writes, including completed,
+  pending, and partial-failure outcomes backed by durable operations.
+- Added `PolygresAmbiguousWriteError` for write outcomes that cannot be proven.
+
+### Changed
+
+- Row mutations are sent exactly once. Automatic transport and status retries
+  are disabled unless an exact Context-backed idempotency replay is requested.
+
+## 0.2.1 - 2026-08-12
+
+### Changed
+
+- pgContext retrieval methods now check the project's supported operations and
+  query limits before sending a request.
+- Capability checks cover result and candidate limits, embedding dimensions,
+  graph depth, and relationship-type limits while preserving existing method
+  signatures.
+- The bundled Runtime API contract now includes the completed text-search
+  configuration and diagnostics operations.
+- Release notices are now checked through the central Polygres API, so future
+  SDK update notices no longer require project Runtime API restarts.
+
+## 0.2.0 - 2026-08-09
+
+### Added
+
+- Added the `project.context` namespace for configuring, managing, and querying pgContext collections.
+- Added `PolygresVersionWarning` for available SDK upgrades.
+- Added `PolygresMaintenanceError` so applications can handle maintenance windows separately from other API failures.
+
+### Changed
+
+- The retired vector-configuration creation error is exposed as
+  `PolygresValidationError` with pgContext replacement details.
+
+### Fixed
+
+- Improved validation and handling of vector result metrics.
+- Vector queries now correctly handle identifiers using the source table's configured ID types.
+- API errors now provide clearer recovery guidance.
+- Restored Python 3.10 compatibility for retry timing and version-notice date parsing.
+
+## 0.1.0 - 2026-07-09
+
+### Added
+
+- Initial standalone `polygres-sdk` package.
+- Added Runtime API clients for graph, vector, text, and hybrid retrieval.
+- Added typed results, cursor pagination, automatic page iteration, readiness checks, passwordless connection information, and structured API exceptions.

{polygres_sdk-0.4.0 → polygres_sdk-0.5.0}/CONTRIBUTING.md

@@ -23,7 +23,7 @@ python tools/generate_runtime_openapi_snapshot.py --check
 python tools/generate_sdk_method_spec.py --check
 python tools/generate_sdk_method_spec.py --validate-only
 python tools/check_sdk_compatibility.py \
-  --baseline compatibility/0.3.0/python-sdk-v1.methods.json
+  --baseline compatibility/0.4.1/python-sdk-v1.methods.json
 python -m build
 python tools/verify_distribution.py dist/*.whl dist/*.tar.gz
 ```
@@ -60,7 +60,7 @@ Release rehearsal happens first on TestPyPI:
    /tmp/polygres-sdk-testpypi/bin/python -m pip install \
      --index-url https://test.pypi.org/simple/ \
      --extra-index-url https://pypi.org/simple/ \
-     polygres-sdk==0.4.0
+     polygres-sdk==0.5.0
    /tmp/polygres-sdk-testpypi/bin/python - <<'PY'
    import importlib.metadata
    from polygres import Polygres
@@ -74,8 +74,8 @@ Publish to PyPI only after the same commit has passed TestPyPI validation. Push
 a release tag from the public repository:
 
 ```bash
-git tag polygres-sdk-v0.4.0
-git push origin polygres-sdk-v0.4.0
+git tag polygres-sdk-v0.5.0
+git push origin polygres-sdk-v0.5.0
 ```
 
 The `pypi` GitHub environment must be approved before the upload proceeds.

{polygres_sdk-0.4.0 → polygres_sdk-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: polygres-sdk
-Version: 0.4.0
+Version: 0.5.0
 Summary: Python SDK for Polygres
 Project-URL: Homepage, https://polygres.com
 Project-URL: Documentation, https://docs.polygres.com/sdk
@@ -114,6 +114,56 @@ New vector setup uses `project.context.create_collection()` with a native
 `pgcontext.vector` column. Existing `project.vector` retrieval methods remain available
 for applications using previously registered vector configurations.
 
+## Query with text
+
+Pass `text` to an existing search method to have Polygres generate the query
+embedding using the model configured for the selected vector:
+
+```python
+results = project.context.search(
+    "articles",
+    text="How does replication work?",
+    vector_name="content",
+    idempotency_key="replication-question-001",
+)
+
+for result in results.results:
+    print(result.properties)
+```
+
+Omit `vector_name` to use the collection's default vector. Set up generation
+and the linked collection through the dashboard, CLI, or MCP first. The
+selected vector must have an unambiguous association with its embedding model.
+
+Existing calls that pass `embedding` continue to work. Supply either text or a
+vector. For `context.query()` and `context.text_hybrid()`, omit the embedding
+to generate it from the existing `query` argument:
+
+```python
+results = project.context.query("articles", query="replication failures")
+```
+
+Text input is also available on Context grouped, candidate, graph-first,
+vector-first, rank-fusion, and joint searches, plus `vector.search()` and the
+`hybrid` query methods. On `context.joint()`, `text` supplies the semantic input
+and `query` remains the separate lexical input. Responses retain their existing
+types, filters, ranking options, and pagination behavior.
+
+For query plans, build `context.query_nearest(text="replication")` and pass the
+plan to `context.execute_query()`. The builder makes no network requests;
+generation happens during execution.
+
+Text queries use the project's query embedding allowance. Organization credits
+are used only with `use_credits=True` and project spending permission. Passing
+an explicit vector does not consume embedding allowance. Reuse an idempotency
+key when retrying the same query across separate calls. Automatic retries and
+pagination reuse the original embedding attempt. Set `timeout` to control the
+request budget, including embedding generation. Query plans accept credit,
+idempotency, and timeout options on `execute_query()`.
+
+This requires a Runtime that supports query embedding generation. SDK 0.5.0
+checks that support before sending text queries.
+
 ## pgContext-aligned names
 
 SDK 0.4.0 adds pgContext 0.2.0 terminology while keeping every SDK 0.3.0
@@ -365,11 +415,11 @@ payload and idempotency key.
 
 ## Version and support
 
-Package version: [`0.4.0`](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.4.0).
+Package version: [`0.5.0`](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.5.0).
 
 When contacting support, include the installed SDK version and the request ID.
 
-See the [SDK 0.4.0 release notes](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.4.0) for release changes.
+See the [SDK 0.5.0 release notes](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.5.0) for release changes.
 
 ## Optional Agent Skill
 
@@ -380,3 +430,11 @@ npx skills add Evokoa/polygres-skills --skill polygres-sdk
 ```
 
 See the [Agent Skills repository](https://github.com/Evokoa/polygres-skills) for Codex and Claude Code installation options.
+
+
+## Managed automatic embeddings
+
+Configure watched text, optionally reuse compatible existing vectors, and generate
+query embeddings with the pinned model. See the [automatic embeddings guide](https://docs.polygres.com/platform/automatic-embeddings) for preview, creation,
+processing, Context handoff, quotas, and recovery. Availability requires an enabled
+model catalog and quota policy in the connected environment.

{polygres_sdk-0.4.0 → polygres_sdk-0.5.0}/README.md

@@ -72,6 +72,56 @@ New vector setup uses `project.context.create_collection()` with a native
 `pgcontext.vector` column. Existing `project.vector` retrieval methods remain available
 for applications using previously registered vector configurations.
 
+## Query with text
+
+Pass `text` to an existing search method to have Polygres generate the query
+embedding using the model configured for the selected vector:
+
+```python
+results = project.context.search(
+    "articles",
+    text="How does replication work?",
+    vector_name="content",
+    idempotency_key="replication-question-001",
+)
+
+for result in results.results:
+    print(result.properties)
+```
+
+Omit `vector_name` to use the collection's default vector. Set up generation
+and the linked collection through the dashboard, CLI, or MCP first. The
+selected vector must have an unambiguous association with its embedding model.
+
+Existing calls that pass `embedding` continue to work. Supply either text or a
+vector. For `context.query()` and `context.text_hybrid()`, omit the embedding
+to generate it from the existing `query` argument:
+
+```python
+results = project.context.query("articles", query="replication failures")
+```
+
+Text input is also available on Context grouped, candidate, graph-first,
+vector-first, rank-fusion, and joint searches, plus `vector.search()` and the
+`hybrid` query methods. On `context.joint()`, `text` supplies the semantic input
+and `query` remains the separate lexical input. Responses retain their existing
+types, filters, ranking options, and pagination behavior.
+
+For query plans, build `context.query_nearest(text="replication")` and pass the
+plan to `context.execute_query()`. The builder makes no network requests;
+generation happens during execution.
+
+Text queries use the project's query embedding allowance. Organization credits
+are used only with `use_credits=True` and project spending permission. Passing
+an explicit vector does not consume embedding allowance. Reuse an idempotency
+key when retrying the same query across separate calls. Automatic retries and
+pagination reuse the original embedding attempt. Set `timeout` to control the
+request budget, including embedding generation. Query plans accept credit,
+idempotency, and timeout options on `execute_query()`.
+
+This requires a Runtime that supports query embedding generation. SDK 0.5.0
+checks that support before sending text queries.
+
 ## pgContext-aligned names
 
 SDK 0.4.0 adds pgContext 0.2.0 terminology while keeping every SDK 0.3.0
@@ -323,11 +373,11 @@ payload and idempotency key.
 
 ## Version and support
 
-Package version: [`0.4.0`](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.4.0).
+Package version: [`0.5.0`](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.5.0).
 
 When contacting support, include the installed SDK version and the request ID.
 
-See the [SDK 0.4.0 release notes](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.4.0) for release changes.
+See the [SDK 0.5.0 release notes](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.5.0) for release changes.
 
 ## Optional Agent Skill
 
@@ -338,3 +388,11 @@ npx skills add Evokoa/polygres-skills --skill polygres-sdk
 ```
 
 See the [Agent Skills repository](https://github.com/Evokoa/polygres-skills) for Codex and Claude Code installation options.
+
+
+## Managed automatic embeddings
+
+Configure watched text, optionally reuse compatible existing vectors, and generate
+query embeddings with the pinned model. See the [automatic embeddings guide](https://docs.polygres.com/platform/automatic-embeddings) for preview, creation,
+processing, Context handoff, quotas, and recovery. Availability requires an enabled
+model catalog and quota policy in the connected environment.

polygres_sdk-0.5.0/compatibility/0.4.1/README.md

@@ -0,0 +1,7 @@
+# SDK 0.4.1 compatibility baseline
+
+Method contract copied unchanged from the published `polygres_sdk-0.4.1-py3-none-any.whl`.
+
+Source: https://files.pythonhosted.org/packages/8a/c8/81225a4b8dafbac19b4ad3e5b7643a424655dde444dcdaa7e1626d0ccea0/polygres_sdk-0.4.1-py3-none-any.whl
+
+Wheel SHA-256: `5fea5a6cc73c90a44361e6f3200f0554e77d44ab0f4250c4da858633a8f25337`

{polygres_sdk-0.4.0/src/polygres/spec → polygres_sdk-0.5.0/compatibility/0.4.1}/python-sdk-v1.methods.json

@@ -8079,5 +8079,5 @@
   "openapi_sha256": "db23d7178d295d7bac0b5168061c59fcbcf6eb96e1e12bc2e21670452b8cb506",
   "schema_version": 1,
   "sdk": "polygres-sdk",
-  "sdk_version": "0.4.0"
+  "sdk_version": "0.4.1"
 }

{polygres_sdk-0.4.0 → polygres_sdk-0.5.0}/docs/reference-v1.md

@@ -2,7 +2,7 @@
 
 This file is generated. Edit Python method metadata, docstrings, or the Runtime OpenAPI contract instead.
 
-- SDK package version: `0.4.0`
+- SDK package version: `0.5.0`
 - HTTP API family: `v1`
 - Default API behavior version: `2026-08-04`
 - Method specification schema: `1`
@@ -204,6 +204,12 @@ Search within explicit candidate point IDs.
 result = project.context.candidate_search("support", embedding, [1, 2])
 ```
 
+SDK 0.5.0 supports configured query embedding generation through text input.
+Existing vector inputs retain their behavior. Text execution accepts optional
+credit usage and idempotency keys; automatic retries reuse the same attempt.
+Query-plan builders remain local; generation happens in execute_query().
+See the README's Query with text section for method-specific input rules.
+
 ### `project.context.clear_payload()`
 
 Clear all registered payload fields.
@@ -388,6 +394,12 @@ Execute a validated pgContext query plan.
 results = project.context.execute_query("support", plan)
 ```
 
+SDK 0.5.0 supports configured query embedding generation through text input.
+Existing vector inputs retain their behavior. Text execution accepts optional
+credit usage and idempotency keys; automatic retries reuse the same attempt.
+Query-plan builders remain local; generation happens in execute_query().
+See the README's Query with text section for method-specific input rules.
+
 ### `project.context.explain()`
 
 Explain the stable dense plus full-text pgContext query.
@@ -491,6 +503,12 @@ Run graph-first Context hybrid retrieval.
 results = project.context.graph_first("support", embedding, start=start)
 ```
 
+SDK 0.5.0 supports configured query embedding generation through text input.
+Existing vector inputs retain their behavior. Text execution accepts optional
+credit usage and idempotency keys; automatic retries reuse the same attempt.
+Query-plan builders remain local; generation happens in execute_query().
+See the README's Query with text section for method-specific input rules.
+
 ### `project.context.grouped_search()`
 
 Run grouped dense Context retrieval.
@@ -499,6 +517,12 @@ Run grouped dense Context retrieval.
 results = project.context.grouped_search("support", embedding, group_by="tenant_id")
 ```
 
+SDK 0.5.0 supports configured query embedding generation through text input.
+Existing vector inputs retain their behavior. Text execution accepts optional
+credit usage and idempotency keys; automatic retries reuse the same attempt.
+Query-plan builders remain local; generation happens in execute_query().
+See the README's Query with text section for method-specific input rules.
+
 ### `project.context.index_advisor()`
 
 Return collection filter-index recommendations.
@@ -531,6 +555,12 @@ Run coupled Context and graph joint retrieval.
 results = project.context.joint("support", embedding)
 ```
 
+SDK 0.5.0 supports configured query embedding generation through text input.
+Existing vector inputs retain their behavior. Text execution accepts optional
+credit usage and idempotency keys; automatic retries reuse the same attempt.
+Query-plan builders remain local; generation happens in execute_query().
+See the README's Query with text section for method-specific input rules.
+
 ### `project.context.list_collections()`
 
 List Context collections with cursor pagination.
@@ -587,6 +617,12 @@ Run the stable pgContext dense plus full-text query.
 results = project.context.query("support", embedding, query="refund")
 ```
 
+SDK 0.5.0 supports configured query embedding generation through text input.
+Existing vector inputs retain their behavior. Text execution accepts optional
+credit usage and idempotency keys; automatic retries reuse the same attempt.
+Query-plan builders remain local; generation happens in execute_query().
+See the README's Query with text section for method-specific input rules.
+
 ### `project.context.query_cohort_stats()`
 
 Return collection-scoped query cohort statistics.
@@ -651,6 +687,12 @@ Build a dense nearest query plan.
 plan = project.context.query_nearest(embedding, limit=20)
 ```
 
+SDK 0.5.0 supports configured query embedding generation through text input.
+Existing vector inputs retain their behavior. Text execution accepts optional
+credit usage and idempotency keys; automatic retries reuse the same attempt.
+Query-plan builders remain local; generation happens in execute_query().
+See the README's Query with text section for method-specific input rules.
+
 ### `project.context.query_prefetch()`
 
 Build a query plan that prefetches multiple branches.
@@ -707,6 +749,12 @@ Fuse Context and graph rankings.
 results = project.context.rank_fusion("support", embedding, start=start)
 ```
 
+SDK 0.5.0 supports configured query embedding generation through text input.
+Existing vector inputs retain their behavior. Text execution accepts optional
+credit usage and idempotency keys; automatic retries reuse the same attempt.
+Query-plan builders remain local; generation happens in execute_query().
+See the README's Query with text section for method-specific input rules.
+
 ### `project.context.raw_vector_search()`
 
 Search an explicit array of dense vectors.
@@ -819,6 +867,12 @@ Run dense Context retrieval.
 results = project.context.search("support", embedding)
 ```
 
+SDK 0.5.0 supports configured query embedding generation through text input.
+Existing vector inputs retain their behavior. Text execution accepts optional
+credit usage and idempotency keys; automatic retries reuse the same attempt.
+Query-plan builders remain local; generation happens in execute_query().
+See the README's Query with text section for method-specific input rules.
+
 ### `project.context.set_default_collection()`
 
 Make a Context collection the project default.
@@ -851,6 +905,12 @@ Run dense and lexical Context retrieval.
 results = project.context.text_hybrid("support", embedding, query="refund")
 ```
 
+SDK 0.5.0 supports configured query embedding generation through text input.
+Existing vector inputs retain their behavior. Text execution accepts optional
+credit usage and idempotency keys; automatic retries reuse the same attempt.
+Query-plan builders remain local; generation happens in execute_query().
+See the README's Query with text section for method-specific input rules.
+
 ### `project.context.update_collection()`
 
 Update mutable Context collection settings.
@@ -891,6 +951,12 @@ Run vector-first Context hybrid retrieval.
 results = project.context.vector_first("support", embedding)
 ```
 
+SDK 0.5.0 supports configured query embedding generation through text input.
+Existing vector inputs retain their behavior. Text execution accepts optional
+credit usage and idempotency keys; automatic retries reuse the same attempt.
+Query-plan builders remain local; generation happens in execute_query().
+See the README's Query with text section for method-specific input rules.
+
 ### `project.context.verify_collection()`
 
 Verify the physical state of a Context collection.
@@ -973,6 +1039,12 @@ Run graph-first hybrid retrieval.
 page = project.hybrid.graph_first(start, embedding)
 ```
 
+SDK 0.5.0 supports configured query embedding generation through text input.
+Existing vector inputs retain their behavior. Text execution accepts optional
+credit usage and idempotency keys; automatic retries reuse the same attempt.
+Query-plan builders remain local; generation happens in execute_query().
+See the README's Query with text section for method-specific input rules.
+
 ### `project.hybrid.joint()`
 
 Run joint vector and graph retrieval.
@@ -981,6 +1053,12 @@ Run joint vector and graph retrieval.
 page = project.hybrid.joint(embedding, start)
 ```
 
+SDK 0.5.0 supports configured query embedding generation through text input.
+Existing vector inputs retain their behavior. Text execution accepts optional
+credit usage and idempotency keys; automatic retries reuse the same attempt.
+Query-plan builders remain local; generation happens in execute_query().
+See the README's Query with text section for method-specific input rules.
+
 ### `project.hybrid.vector_first()`
 
 Run vector-first hybrid retrieval.
@@ -989,6 +1067,12 @@ Run vector-first hybrid retrieval.
 page = project.hybrid.vector_first(embedding)
 ```
 
+SDK 0.5.0 supports configured query embedding generation through text input.
+Existing vector inputs retain their behavior. Text execution accepts optional
+credit usage and idempotency keys; automatic retries reuse the same attempt.
+Query-plan builders remain local; generation happens in execute_query().
+See the README's Query with text section for method-specific input rules.
+
 ## `project.rows`
 
 | SDK method | HTTP operation | Since | Retry | Pagination | Deprecated |
@@ -1068,6 +1152,12 @@ Search a configured vector index with an embedding.
 page = project.vector.search(embedding)
 ```
 
+SDK 0.5.0 supports configured query embedding generation through text input.
+Existing vector inputs retain their behavior. Text execution accepts optional
+credit usage and idempotency keys; automatic retries reuse the same attempt.
+Query-plan builders remain local; generation happens in execute_query().
+See the README's Query with text section for method-specific input rules.
+
 ### `project.vector.similar_to()`
 
 Find rows similar to an existing indexed row.

{polygres_sdk-0.4.0 → polygres_sdk-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "polygres-sdk"
-version = "0.4.0"
+version = "0.5.0"
 description = "Python SDK for Polygres"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -69,6 +69,7 @@ packages = ["src/polygres"]
 
 [tool.hatch.build.targets.sdist]
 include = [
+  "/CHANGELOG.md",
   "/CONTRIBUTING.md",
   "/LICENSE",
   "/README.md",

polygres_sdk-0.5.0/src/polygres/_query_input.py

@@ -0,0 +1,50 @@
+"""Private query input validation and retry identity handling."""
+
+from uuid import uuid4
+
+from pydantic import ValidationError
+
+from polygres._vendor.polygres_lib.context.models import DenseSearchRequest
+from polygres.errors import PolygresValidationError
+
+
+def validate_query_input(embedding, text, use_credits):
+    try:
+        DenseSearchRequest(
+            collection="query", embedding=embedding, text=text, use_credits=use_credits
+        )
+    except ValidationError as exc:
+        raise PolygresValidationError(str(exc)) from exc
+
+
+def contains_query_text(payload):
+    if not isinstance(payload, dict):
+        return False
+    if payload.get("text") is not None:
+        return True
+    if "plan" in payload:
+        return contains_query_text(payload["plan"])
+    if "kind" in payload:
+        return contains_query_text(payload.get("branch")) or any(
+            contains_query_text(child) for child in payload.get("branches", [])
+        )
+    return False
+
+
+def query_transport(payload, idempotency_key=None):
+    if not contains_query_text(payload):
+        # Keep vector-only wire payloads compatible with earlier Runtime versions.
+        return {k: v for k, v in payload.items() if k not in {"text", "use_credits"}}, None
+    key = idempotency_key or str(uuid4())
+    if not isinstance(key, str) or not key.strip() or len(key) > 200:
+        raise PolygresValidationError("idempotency_key must contain 1 to 200 characters")
+    return payload, {"Idempotency-Key": key}
+
+
+def query_deadline(timeout):
+    import time
+
+    import httpx
+
+    seconds = timeout.read if isinstance(timeout, httpx.Timeout) else timeout
+    return None if seconds is None else time.monotonic() + float(seconds)