polygres-sdk 0.2.0__tar.gz → 0.2.1__tar.gz

{polygres_sdk-0.2.0 → polygres_sdk-0.2.1}/CONTRIBUTING.md

@@ -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.2.0
+     polygres-sdk==0.2.1
    /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.2.0
-git push origin polygres-sdk-v0.2.0
+git tag polygres-sdk-v0.2.1
+git push origin polygres-sdk-v0.2.1
 ```
 
 The `pypi` GitHub environment must be approved before the upload proceeds.

{polygres_sdk-0.2.0 → polygres_sdk-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: polygres-sdk
-Version: 0.2.0
+Version: 0.2.1
 Summary: Python SDK for Polygres
 Project-URL: Homepage, https://polygres.com
 Project-URL: Documentation, https://docs.polygres.com/sdk
@@ -287,11 +287,11 @@ Use a PostgreSQL driver such as psycopg or SQLAlchemy when your application need
 
 ## Version and support
 
-Package version: [`0.2.0`](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.2.0).
+Package version: [`0.2.1`](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.2.1).
 
 When contacting support, include the installed SDK version and the request ID.
 
-See the [SDK 0.2.0 release notes](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.2.0) for release changes.
+See the [SDK 0.2.1 release notes](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.2.1) for release changes.
 
 ## Optional Agent Skill
 

{polygres_sdk-0.2.0 → polygres_sdk-0.2.1}/README.md

@@ -245,11 +245,11 @@ Use a PostgreSQL driver such as psycopg or SQLAlchemy when your application need
 
 ## Version and support
 
-Package version: [`0.2.0`](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.2.0).
+Package version: [`0.2.1`](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.2.1).
 
 When contacting support, include the installed SDK version and the request ID.
 
-See the [SDK 0.2.0 release notes](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.2.0) for release changes.
+See the [SDK 0.2.1 release notes](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.2.1) for release changes.
 
 ## Optional Agent Skill
 

{polygres_sdk-0.2.0 → polygres_sdk-0.2.1}/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.2.0`
+- SDK package version: `0.2.1`
 - HTTP API family: `v1`
 - Default API behavior version: `2026-08-04`
 - Method specification schema: `1`
@@ -190,6 +190,13 @@ Return pgContext capabilities for this Runtime.
 capabilities = project.context.get_capabilities()
 ```
 
+Context retrieval methods fetch this response lazily on their first call and
+cache it on the project Context namespace. They validate the requested mode,
+dimensions, result and candidate limits, graph depth, and relationship-type
+count before sending the retrieval request. Calling `get_capabilities()`
+explicitly refreshes the cache. Cached capabilities expire after 60 seconds,
+and an unavailable capability is refreshed on the next attempted call.
+
 ### `project.context.get_collection()`
 
 Return one Context collection by UUID.

{polygres_sdk-0.2.0 → polygres_sdk-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "polygres-sdk"
-version = "0.2.0"
+version = "0.2.1"
 description = "Python SDK for Polygres"
 readme = "README.md"
 requires-python = ">=3.10"

{polygres_sdk-0.2.0 → polygres_sdk-0.2.1}/src/polygres/client.py

@@ -42,7 +42,7 @@ from polygres.models import (
     TextResult,
     VectorResult,
 )
-from polygres.version_notices import emit_version_notice
+from polygres.version_notices import check_central_version_notices, emit_version_notice
 
 PROJECT_RE = re.compile(r"^p[a-z0-9]{23}$")
 RETRY_STATUSES = {408, 429, 500, 502, 503, 504}
@@ -350,6 +350,7 @@ class Polygres:
                 if deadline is not None and time.monotonic() >= deadline:
                     raise _deadline_error(method, path)
             emit_version_notice(response.headers, current_version=__version__)
+            check_central_version_notices(current_version=__version__)
             if error is not None:
                 raise error
             payload = response.json()

{polygres_sdk-0.2.0 → polygres_sdk-0.2.1}/src/polygres/context.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
+import time
+from dataclasses import dataclass, field
 from enum import Enum
 from typing import TYPE_CHECKING, Any, TypeVar
 from uuid import UUID
@@ -74,14 +75,28 @@ if TYPE_CHECKING:
 ResponseT = TypeVar("ResponseT", bound=BaseModel)
 RequestTimeout = float | httpx.Timeout | None
 _UNSET = object()
+_CAPABILITY_CACHE_TTL_SECONDS = 60.0
 
 
 @dataclass
 class ContextNamespace:
     _project: Project
+    _capabilities_cache: CapabilitiesResponse | None = field(
+        init=False,
+        default=None,
+        repr=False,
+    )
+    _capabilities_cached_at: float | None = field(init=False, default=None, repr=False)
 
     def get_capabilities(self, *, timeout: RequestTimeout = None) -> CapabilitiesResponse:
-        return self._get_model("/context/capabilities", CapabilitiesResponse, timeout=timeout)
+        capabilities = self._get_model(
+            "/context/capabilities",
+            CapabilitiesResponse,
+            timeout=timeout,
+        )
+        self._capabilities_cache = capabilities
+        self._capabilities_cached_at = time.monotonic()
+        return capabilities
 
     def get_onboarding(self, *, timeout: RequestTimeout = None) -> ContextOnboardingResponse:
         """Return cached pgContext onboarding state without running discovery."""
@@ -459,6 +474,7 @@ class ContextNamespace:
     ) -> Page[PointMapping]:
         collection_uuid = context_uuid(collection_id, field="collection_id")
         _page_limit(limit, field="limit")
+        self._validate_capability_request("point_scroll", {}, timeout=timeout)
         response = self._get_model(
             f"/context/collections/{collection_uuid}/points",
             PointScrollResponse,
@@ -670,6 +686,7 @@ class ContextNamespace:
             CountRequest,
             {"collection": context_collection(collection), "filter": filter},
         )
+        self._validate_capability_request("count", payload, timeout=timeout)
         return self._post_model(
             "/context/count", payload, CountResponse, timeout=timeout, retryable=True
         )
@@ -692,6 +709,12 @@ class ContextNamespace:
                 "limit": limit,
             },
         )
+        self._validate_capability_request(
+            "facets",
+            payload,
+            timeout=timeout,
+            validate_limits=False,
+        )
         return self._post_model(
             "/context/facets", payload, FacetsResponse, timeout=timeout, retryable=True
         )
@@ -708,6 +731,7 @@ class ContextNamespace:
     ) -> RankedResponse:
         return self._ranked(
             "/context/search",
+            "dense_search",
             DenseSearchRequest,
             {
                 "collection": context_collection(collection),
@@ -732,6 +756,7 @@ class ContextNamespace:
     ) -> RankedResponse:
         return self._ranked(
             "/context/grouped-search",
+            "grouped_search",
             GroupedSearchRequest,
             {
                 "collection": context_collection(collection),
@@ -766,6 +791,7 @@ class ContextNamespace:
                 "minimum_recall": minimum_recall,
             },
         )
+        self._validate_capability_request("recall_check", payload, timeout=timeout)
         return self._post_model(
             "/context/recall-check",
             payload,
@@ -786,6 +812,7 @@ class ContextNamespace:
     ) -> RankedResponse:
         return self._ranked(
             "/context/hybrid/text",
+            "text_hybrid",
             TextHybridSearchRequest,
             {
                 "collection": context_collection(collection),
@@ -814,6 +841,7 @@ class ContextNamespace:
     ) -> RankedResponse:
         return self._ranked(
             "/context/hybrid/graph-first",
+            "graph_first",
             GraphFirstSearchRequest,
             {
                 "collection": context_collection(collection),
@@ -847,6 +875,7 @@ class ContextNamespace:
     ) -> RankedResponse:
         return self._ranked(
             "/context/hybrid/vector-first",
+            "vector_first",
             VectorFirstSearchRequest,
             {
                 "collection": context_collection(collection),
@@ -883,6 +912,7 @@ class ContextNamespace:
     ) -> RankedResponse:
         return self._ranked(
             "/context/hybrid/rank-fusion",
+            "rank_fusion",
             RankFusionSearchRequest,
             {
                 "collection": context_collection(collection),
@@ -947,6 +977,7 @@ class ContextNamespace:
                 "limit": limit,
             },
         )
+        self._validate_capability_request("joint", payload, timeout=timeout)
         return self._post_model(
             "/context/hybrid/joint",
             payload,
@@ -1010,13 +1041,43 @@ class ContextNamespace:
     def _ranked(
         self,
         path: str,
+        capability: str,
         request_model: type[BaseModel],
         request: dict[str, Any],
         timeout: RequestTimeout,
     ) -> RankedResponse:
         _, payload = context_model(request_model, request)
+        self._validate_capability_request(capability, payload, timeout=timeout)
         return self._post_model(path, payload, RankedResponse, timeout=timeout, retryable=False)
 
+    def _validate_capability_request(
+        self,
+        capability: str,
+        payload: dict[str, Any],
+        *,
+        timeout: RequestTimeout,
+        validate_limits: bool = True,
+    ) -> None:
+        capabilities = self._capabilities_cache
+        cached_at = self._capabilities_cached_at
+        expired = cached_at is None or time.monotonic() - cached_at >= _CAPABILITY_CACHE_TTL_SECONDS
+        if capabilities is None or expired or not bool(getattr(capabilities, capability)):
+            capabilities = self.get_capabilities(timeout=timeout)
+        if not bool(getattr(capabilities, capability)):
+            blocker = getattr(capabilities, f"{capability}_blocker")
+            blocker_message = getattr(
+                capabilities,
+                f"{capability}_blocker_message",
+                None,
+            )
+            raise PolygresValidationError(
+                blocker_message or f"Context {capability.replace('_', ' ')} is unavailable.",
+                code="CONTEXT_CAPABILITY_UNAVAILABLE",
+                details={"capability": capability, "blocker": blocker},
+            )
+        if validate_limits:
+            _validate_capability_limits(capabilities, payload)
+
     def _get_model(
         self,
         path: str,
@@ -1061,6 +1122,53 @@ class ContextNamespace:
         return _operation_response(response)
 
 
+def _validate_capability_limits(
+    capabilities: CapabilitiesResponse,
+    payload: dict[str, Any],
+) -> None:
+    limit_fields = (
+        ("limit", "max_search_limit"),
+        ("context_limit", "max_context_limit"),
+        ("graph_limit", "max_graph_limit"),
+        ("seed_limit", "max_joint_seed_limit"),
+        ("traversal_limit", "max_joint_traversal_limit"),
+        ("max_depth", "max_graph_depth"),
+    )
+    for field_name, capability_field in limit_fields:
+        value = payload.get(field_name)
+        if value is None:
+            continue
+        maximum = int(getattr(capabilities, capability_field))
+        if int(value) > maximum:
+            raise PolygresValidationError(
+                f"{field_name} must be {maximum} or less for this project",
+                code="CONTEXT_LIMIT_EXCEEDED",
+                details={"field": field_name, "limit": maximum},
+            )
+
+    embedding = payload.get("embedding")
+    if isinstance(embedding, list) and len(embedding) > capabilities.max_dimensions:
+        raise PolygresValidationError(
+            f"embedding must contain at most {capabilities.max_dimensions} dimensions",
+            code="CONTEXT_LIMIT_EXCEEDED",
+            details={"field": "embedding", "limit": capabilities.max_dimensions},
+        )
+
+    relationship_types = payload.get("relationship_types")
+    if (
+        isinstance(relationship_types, list)
+        and len(relationship_types) > capabilities.max_relationship_types
+    ):
+        raise PolygresValidationError(
+            "relationship_types exceeds this project's capability limit",
+            code="CONTEXT_LIMIT_EXCEEDED",
+            details={
+                "field": "relationship_types",
+                "limit": capabilities.max_relationship_types,
+            },
+        )
+
+
 def _attach_context_method_metadata() -> None:
     bindings = (
         (

{polygres_sdk-0.2.0 → polygres_sdk-0.2.1}/src/polygres/models.py

@@ -248,6 +248,7 @@ class TextResult:
     properties: dict[str, Any]
     score: float
     similarity: float | None = None
+    key: dict[str, str] | None = None
 
     @classmethod
     def from_api(cls, payload: dict[str, Any]) -> TextResult:
@@ -258,6 +259,7 @@ class TextResult:
             properties=dict(payload.get("properties", {})),
             score=float(payload["score"]),
             similarity=payload.get("similarity"),
+            key=(dict(payload["key"]) if isinstance(payload.get("key"), dict) else None),
         )
 
     def to_dict(self) -> dict[str, Any]:

{polygres_sdk-0.2.0 → polygres_sdk-0.2.1}/src/polygres/spec/python-sdk-v1.methods.json

@@ -178,6 +178,14 @@
       "reason": "Readiness checks are operational endpoints; the SDK uses retrieval readiness instead.",
       "review_date": "2027-02-04"
     },
+    {
+      "method": "POST",
+      "operation_id": "reindex_text_configuration_v1_text_configurations__config_id__reindex_post",
+      "owner": "Runtime Platform",
+      "path": "/v1/text/configurations/{config_id}/reindex",
+      "reason": "Text reindexing is a setup operation managed outside the retrieval SDK.",
+      "review_date": "2027-02-04"
+    },
     {
       "method": "POST",
       "operation_id": "reindex_vector_configuration_v1_vector_configurations__config_id__reindex_post",
@@ -201,6 +209,14 @@
       "path": "/v1/vector/configurations/{config_id}/compatibility-engine/{target_engine}",
       "reason": "Per-configuration compatibility engine selection is an operator rollback control, not an application retrieval method.",
       "review_date": "2027-02-04"
+    },
+    {
+      "method": "GET",
+      "operation_id": "text_configuration_diagnostics_v1_text_configurations__config_id__diagnostics_get",
+      "owner": "Runtime Platform",
+      "path": "/v1/text/configurations/{config_id}/diagnostics",
+      "reason": "Text index diagnostics are managed through the dashboard and control-plane workflow.",
+      "review_date": "2027-02-04"
     }
   ],
   "methods": [
@@ -4438,8 +4454,8 @@
       "stability": "stable"
     }
   ],
-  "openapi_sha256": "bc828889aee0beb04d6c35cfd351d54d02ed547039a30d8316a4faa70cf8bc55",
+  "openapi_sha256": "7a0960535e680ffd590776b2f6fea4188cb857c75bf5f5568680e6189f746b5f",
   "schema_version": 1,
   "sdk": "polygres-sdk",
-  "sdk_version": "0.2.0"
+  "sdk_version": "0.2.1"
 }