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

{polygres_sdk-0.2.1 → polygres_sdk-0.3.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.1.0/python-sdk-v1.methods.json
+  --baseline compatibility/0.2.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.2.1
+     polygres-sdk==0.3.0
    /tmp/polygres-sdk-testpypi/bin/python - <<'PY'
    import importlib.metadata
    from polygres import Polygres
@@ -74,12 +74,15 @@ 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.1
-git push origin polygres-sdk-v0.2.1
+git tag polygres-sdk-v0.3.0
+git push origin polygres-sdk-v0.3.0
 ```
 
 The `pypi` GitHub environment must be approved before the upload proceeds.
-Project URLs in `pyproject.toml` must use valid HTTPS URLs accepted by PyPI.
+After PyPI accepts the package, the workflow creates the matching GitHub
+Release from the version's changelog entry and attaches the wheel and source
+distribution. Project URLs in `pyproject.toml` must use valid HTTPS URLs
+accepted by PyPI.
 
 ## Scope
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: polygres-sdk
-Version: 0.2.1
+Version: 0.3.0
 Summary: Python SDK for Polygres
 Project-URL: Homepage, https://polygres.com
 Project-URL: Documentation, https://docs.polygres.com/sdk
@@ -285,13 +285,37 @@ print(connection.direct_url_without_password)
 
 Use a PostgreSQL driver such as psycopg or SQLAlchemy when your application needs a database connection. The Polygres SDK is an HTTP retrieval client and does not bundle a PostgreSQL driver.
 
+## Single-row writes
+
+Use `project.rows` for one JSON-native row. Context reconciliation is explicit:
+omit both Context options for a generic table, or select one collection so the
+same operation writes the row and creates its pgContext point.
+
+```python
+result = project.rows.upsert(
+    schema="public",
+    table="memories",
+    row={"id": "memory_123", "content": "Remember the deployment window."},
+    conflict_columns=["id"],
+    returning=["id"],
+    context_collection_id="2e172638-bd77-4a2c-bc42-406f4f2938d7",
+    idempotency_key="memory-123-v1",
+    wait_for_context=True,
+)
+```
+
+UUIDs and timestamps are JSON strings. Arrays and vectors are JSON arrays.
+Never automatically retry a row-only write after a timeout; its outcome may be
+ambiguous. A Context-backed request may be resumed only with the exact same
+payload and idempotency key.
+
 ## Version and support
 
-Package version: [`0.2.1`](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.2.1).
+Package version: [`0.3.0`](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.3.0).
 
 When contacting support, include the installed SDK version and the request ID.
 
-See the [SDK 0.2.1 release notes](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.2.1) for release changes.
+See the [SDK 0.3.0 release notes](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.3.0) for release changes.
 
 ## Optional Agent Skill
 

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

@@ -243,13 +243,37 @@ print(connection.direct_url_without_password)
 
 Use a PostgreSQL driver such as psycopg or SQLAlchemy when your application needs a database connection. The Polygres SDK is an HTTP retrieval client and does not bundle a PostgreSQL driver.
 
+## Single-row writes
+
+Use `project.rows` for one JSON-native row. Context reconciliation is explicit:
+omit both Context options for a generic table, or select one collection so the
+same operation writes the row and creates its pgContext point.
+
+```python
+result = project.rows.upsert(
+    schema="public",
+    table="memories",
+    row={"id": "memory_123", "content": "Remember the deployment window."},
+    conflict_columns=["id"],
+    returning=["id"],
+    context_collection_id="2e172638-bd77-4a2c-bc42-406f4f2938d7",
+    idempotency_key="memory-123-v1",
+    wait_for_context=True,
+)
+```
+
+UUIDs and timestamps are JSON strings. Arrays and vectors are JSON arrays.
+Never automatically retry a row-only write after a timeout; its outcome may be
+ambiguous. A Context-backed request may be resumed only with the exact same
+payload and idempotency key.
+
 ## Version and support
 
-Package version: [`0.2.1`](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.2.1).
+Package version: [`0.3.0`](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.3.0).
 
 When contacting support, include the installed SDK version and the request ID.
 
-See the [SDK 0.2.1 release notes](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.2.1) for release changes.
+See the [SDK 0.3.0 release notes](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.3.0) for release changes.
 
 ## Optional Agent Skill
 

polygres_sdk-0.3.0/compatibility/0.2.1/README.md

@@ -0,0 +1,8 @@
+# SDK compatibility baseline 0.2.1
+
+`python-sdk-v1.methods.json` is the explicit released 0.2.1 public network
+surface used by CI and release checks for 0.3.0. It is copied byte-for-byte
+from the generated method contract at the 0.2.1 release boundary.
+
+Release automation must name this file with `--baseline`; the compatibility
+tool refuses to infer a baseline from an arbitrary local artifact.

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

@@ -3653,7 +3653,8 @@
                 "limit",
                 "max_depth",
                 "relationship_types",
-                "start"
+                "start",
+                "target_table"
               ],
               "required_fields": [
                 "start"
@@ -3723,7 +3724,8 @@
                 "limit",
                 "max_depth",
                 "relationship_types",
-                "start"
+                "start",
+                "target_table"
               ],
               "required_fields": [
                 "start"
@@ -3862,7 +3864,8 @@
                 "limit",
                 "max_depth",
                 "relationship_types",
-                "start"
+                "start",
+                "target_table"
               ],
               "required_fields": [
                 "start"
@@ -4454,7 +4457,7 @@
       "stability": "stable"
     }
   ],
-  "openapi_sha256": "7a0960535e680ffd590776b2f6fea4188cb857c75bf5f5568680e6189f746b5f",
+  "openapi_sha256": "7dac7258e9dd8e7c92019025effee85ec71a19bca98154d20d7c00f7d8450f8a",
   "schema_version": 1,
   "sdk": "polygres-sdk",
   "sdk_version": "0.2.1"

{polygres_sdk-0.2.1 → polygres_sdk-0.3.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.2.1`
+- SDK package version: `0.3.0`
 - HTTP API family: `v1`
 - Default API behavior version: `2026-08-04`
 - Method specification schema: `1`
@@ -503,6 +503,47 @@ Run vector-first hybrid retrieval.
 page = project.hybrid.vector_first(embedding)
 ```
 
+## `project.rows`
+
+| SDK method | HTTP operation | Since | Retry | Pagination | Deprecated |
+| --- | --- | --- | --- | --- | --- |
+| `project.rows.ignore()` | `POST /v1/tables/{schema_name}/{table_name}/rows` (`runtime_write_row`) | `0.3.0` | `none` | `none` | No |
+| `project.rows.insert()` | `POST /v1/tables/{schema_name}/{table_name}/rows` (`runtime_write_row`) | `0.3.0` | `none` | `none` | No |
+| `project.rows.upsert()` | `POST /v1/tables/{schema_name}/{table_name}/rows` (`runtime_write_row`) | `0.3.0` | `none` | `none` | No |
+| `project.rows.validate()` | `POST /v1/tables/{schema_name}/{table_name}/rows/validate` (`runtime_validate_row_write`) | `0.3.0` | `read_only_post` | `none` | No |
+
+### `project.rows.ignore()`
+
+Insert one row and ignore a matching primary or unique conflict.
+
+```python
+result = project.rows.ignore(schema="public", table="events", row={"id": "1"}, conflict_columns=["id"])
+```
+
+### `project.rows.insert()`
+
+Insert one row into an eligible project-owned table.
+
+```python
+result = project.rows.insert(schema="public", table="events", row={"id": "1"})
+```
+
+### `project.rows.upsert()`
+
+Upsert one row through a primary or unique constraint.
+
+```python
+result = project.rows.upsert(schema="public", table="events", row={"id": "1"}, conflict_columns=["id"])
+```
+
+### `project.rows.validate()`
+
+Validate a single-row write without executing it.
+
+```python
+validation = project.rows.validate(schema="public", table="events", row={"id": "1"})
+```
+
 ## `project.text`
 
 | SDK method | HTTP operation | Since | Retry | Pagination | Deprecated |

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

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

{polygres_sdk-0.2.1 → polygres_sdk-0.3.0}/src/polygres/__init__.py

@@ -3,6 +3,7 @@ from polygres.client import Polygres
 from polygres.context_models import *  # noqa: F403
 from polygres.context_models import __all__ as _context_model_exports
 from polygres.errors import (
+    PolygresAmbiguousWriteError,
     PolygresAPIError,
     PolygresAuthError,
     PolygresError,
@@ -23,6 +24,9 @@ from polygres.models import (
     HybridResult,
     Page,
     RetrievalReadiness,
+    RowContextReconciliationResult,
+    RowWriteResult,
+    RowWriteValidation,
     TextResult,
     VectorResult,
 )
@@ -39,6 +43,7 @@ __all__ = [
     "Page",
     "Polygres",
     "PolygresAPIError",
+    "PolygresAmbiguousWriteError",
     "PolygresAuthError",
     "PolygresError",
     "PolygresMaintenanceError",
@@ -50,6 +55,9 @@ __all__ = [
     "PolygresVersionNotice",
     "PolygresVersionWarning",
     "RetrievalReadiness",
+    "RowContextReconciliationResult",
+    "RowWriteResult",
+    "RowWriteValidation",
     "TextResult",
     "VectorResult",
     "__version__",

{polygres_sdk-0.2.1 → polygres_sdk-0.3.0}/src/polygres/_vendor/polygres_lib/auth/enums.py

@@ -233,6 +233,7 @@ class RuntimeScope(str, Enum):
     HYBRID_READ = "hybrid:read"
     CONTEXT_READ = "context:read"
     CONTEXT_MANAGE = "context:manage"
+    ROWS_WRITE = "rows:write"
 
 
 class RuntimeClientKind(str, Enum):
@@ -366,6 +367,7 @@ class PolicyId(str, Enum):
     PROJECT_PERMISSION = "project_permission"
     PROJECT_API_KEY = "project_api_key"
     GATEWAY_RUNTIME = "gateway_runtime"
+    RUNTIME_ROW_WRITE = "runtime_row_write"
     CLI_FLOW = "cli_flow"
     RECOVERY_SESSION = "recovery_session"
     LEGACY_DEMO = "legacy_demo"

polygres_sdk-0.3.0/src/polygres/_vendor/polygres_lib/auth/errors.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from types import MappingProxyType
+from uuid import UUID
+
+from ..errors import ERROR_CATALOG, PolygresError, error_record
+from .enums import (
+    CliExitCode,
+    PasswordRequirement,
+    ProjectStatus,
+    ResetClass,
+    RetryClass,
+)
+
+
+class AuthErrorCategory(str, Enum):
+    VALIDATION = "validation"
+    AUTHENTICATION = "authentication"
+    AUTHORIZATION = "authorization"
+    ACCOUNT_GATE = "account_gate"
+    CONFLICT = "conflict"
+    RATE_LIMIT = "rate_limit"
+    DEPENDENCY = "dependency"
+    TERMINAL_SESSION = "terminal_session"
+    UNEXPECTED = "unexpected"
+
+
+class AuthErrorCode(str, Enum):
+    AUTH_REQUIRED = "AUTH_REQUIRED"
+    AUTH_MODE_NOT_ALLOWED = "AUTH_MODE_NOT_ALLOWED"
+    AUTH_NOT_CONFIGURED = "AUTH_NOT_CONFIGURED"
+    AUTH_INVALID_CREDENTIALS = "AUTH_INVALID_CREDENTIALS"
+    AUTH_EMAIL_REQUIRED = "AUTH_EMAIL_REQUIRED"
+    INVALID_TOKEN = "INVALID_TOKEN"
+    TOKEN_EXPIRED = "TOKEN_EXPIRED"
+    LOCAL_SESSION_CORRUPT = "LOCAL_SESSION_CORRUPT"
+    LOCAL_SESSION_RESET_LIMIT_REACHED = "LOCAL_SESSION_RESET_LIMIT_REACHED"
+    AUTH_PROVIDER_UNAVAILABLE = "AUTH_PROVIDER_UNAVAILABLE"
+    AUTH_PKCE_EXCHANGE_FAILED = "AUTH_PKCE_EXCHANGE_FAILED"
+    AUTH_PKCE_VERIFIER_MISSING = "AUTH_PKCE_VERIFIER_MISSING"
+    AUTH_ACTION_INVALID = "AUTH_ACTION_INVALID"
+    AUTH_ACTION_EXPIRED = "AUTH_ACTION_EXPIRED"
+    AUTH_RECOVERY_REQUIRED = "AUTH_RECOVERY_REQUIRED"
+    RECOVERY_GRANT_INVALID = "RECOVERY_GRANT_INVALID"
+    AUTH_REAUTHENTICATION_REQUIRED = "AUTH_REAUTHENTICATION_REQUIRED"
+    AUTH_REAUTHENTICATION_INVALID = "AUTH_REAUTHENTICATION_INVALID"
+    AUTH_PASSWORD_MODE_MISMATCH = "AUTH_PASSWORD_MODE_MISMATCH"
+    AUTH_WEAK_PASSWORD = "AUTH_WEAK_PASSWORD"
+    AUTH_IDENTITY_CHANGED = "AUTH_IDENTITY_CHANGED"
+    EMAIL_NOT_VERIFIED = "EMAIL_NOT_VERIFIED"
+    ACCOUNT_NOT_ELIGIBLE = "ACCOUNT_NOT_ELIGIBLE"
+    APPROVAL_REQUIRED = "APPROVAL_REQUIRED"
+    ADMIN_NOT_ALLOWED = "ADMIN_NOT_ALLOWED"
+    PERMISSION_DENIED = "PERMISSION_DENIED"
+    NOT_FOUND = "NOT_FOUND"
+    PROJECT_NOT_READY = "PROJECT_NOT_READY"
+    INVITATION_NOT_FOUND = "INVITATION_NOT_FOUND"
+    INVITATION_EMAIL_MISMATCH = "INVITATION_EMAIL_MISMATCH"
+    INVITATION_EXISTS = "INVITATION_EXISTS"
+    INVITATION_EXPIRED = "INVITATION_EXPIRED"
+    INVITATION_NOT_PENDING = "INVITATION_NOT_PENDING"
+    INVITATION_NOT_RESENDABLE = "INVITATION_NOT_RESENDABLE"
+    INVITATION_RESEND_TOO_SOON = "INVITATION_RESEND_TOO_SOON"
+    INVITATION_DELIVERY_FAILED = "INVITATION_DELIVERY_FAILED"
+    SELF_INVITE_NOT_ALLOWED = "SELF_INVITE_NOT_ALLOWED"
+    INVALID_INVITATION_ROLE = "INVALID_INVITATION_ROLE"
+    ORG_MEMBERSHIP_LIMIT_EXCEEDED = "ORG_MEMBERSHIP_LIMIT_EXCEEDED"
+    LEGAL_ACCEPTANCE_REQUIRED = "LEGAL_ACCEPTANCE_REQUIRED"
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    CLI_AUTH_NOT_CONFIGURED = "CLI_AUTH_NOT_CONFIGURED"
+    CLI_AUTH_SESSION_CREATE_FAILED = "CLI_AUTH_SESSION_CREATE_FAILED"
+    CLI_AUTH_SESSION_INVALID = "CLI_AUTH_SESSION_INVALID"
+    CLI_AUTH_SESSION_NOT_FOUND = "CLI_AUTH_SESSION_NOT_FOUND"
+    CLI_AUTH_SESSION_TERMINAL = "CLI_AUTH_SESSION_TERMINAL"
+    CLI_AUTH_DENIED = "CLI_AUTH_DENIED"
+    CLI_AUTH_EXPIRED = "CLI_AUTH_EXPIRED"
+    CLI_AUTH_TIMEOUT = "CLI_AUTH_TIMEOUT"
+    CLI_AUTH_RESPONSE_INVALID = "CLI_AUTH_RESPONSE_INVALID"
+    API_KEY_INVALID = "API_KEY_INVALID"
+    API_KEY_NOT_FOUND = "API_KEY_NOT_FOUND"
+    PROJECT_HEADER_REQUIRED = "PROJECT_HEADER_REQUIRED"
+    RUNTIME_API_KEY_SNAPSHOT_UNAVAILABLE = "RUNTIME_API_KEY_SNAPSHOT_UNAVAILABLE"
+    GATEWAY_RUNTIME_JWT_REQUIRED = "GATEWAY_RUNTIME_JWT_REQUIRED"
+    GATEWAY_RUNTIME_JWT_INVALID = "GATEWAY_RUNTIME_JWT_INVALID"
+    GATEWAY_RUNTIME_PROJECT_MISMATCH = "GATEWAY_RUNTIME_PROJECT_MISMATCH"
+    GATEWAY_RUNTIME_SCOPE_INVALID = "GATEWAY_RUNTIME_SCOPE_INVALID"
+    GATEWAY_RUNTIME_SCOPE_DENIED = "GATEWAY_RUNTIME_SCOPE_DENIED"
+    GATEWAY_RUNTIME_JWKS_UNAVAILABLE = "GATEWAY_RUNTIME_JWKS_UNAVAILABLE"
+    RUNTIME_HOST_INVALID = "RUNTIME_HOST_INVALID"
+    RUNTIME_ROUTING_HEADER_REJECTED = "RUNTIME_ROUTING_HEADER_REJECTED"
+    RUNTIME_PROJECT_NOT_FOUND = "RUNTIME_PROJECT_NOT_FOUND"
+    RUNTIME_PROJECT_NOT_READY = "RUNTIME_PROJECT_NOT_READY"
+    EMAIL_DELIVERY_FAILED = "EMAIL_DELIVERY_FAILED"
+    RATE_LIMITED = "RATE_LIMITED"
+    RATE_LIMIT_UNAVAILABLE = "RATE_LIMIT_UNAVAILABLE"
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+
+
+@dataclass(frozen=True, slots=True)
+class AuthErrorDescriptor:
+    code: AuthErrorCode
+    category: AuthErrorCategory
+    safe_message: str
+    message_key: str
+    http_status: int | None
+    cli_exit_code: CliExitCode
+    retry_class: RetryClass
+    reset_class: ResetClass
+    safe_detail_keys: frozenset[str]
+
+
+AUTH_ERROR_CATALOG: Mapping[AuthErrorCode, AuthErrorDescriptor] = MappingProxyType(
+    {
+        code: AuthErrorDescriptor(
+            code=code,
+            category=AuthErrorCategory(ERROR_CATALOG[code.value].category),
+            safe_message=ERROR_CATALOG[code.value].message,
+            message_key=ERROR_CATALOG[code.value].message_key,
+            http_status=ERROR_CATALOG[code.value].http_status,
+            cli_exit_code=CliExitCode(ERROR_CATALOG[code.value].cli_exit_code),
+            retry_class=RetryClass(ERROR_CATALOG[code.value].retry_class),
+            reset_class=ResetClass(ERROR_CATALOG[code.value].reset_class),
+            safe_detail_keys=ERROR_CATALOG[code.value].safe_detail_fields,
+        )
+        for code in AuthErrorCode
+    }
+)
+
+if set(AUTH_ERROR_CATALOG) != set(AuthErrorCode):
+    raise RuntimeError("global error catalog must define every AuthErrorCode exactly once")
+
+
+_FIELD_PATH = re.compile(r"^[a-z][a-z0-9_.]{0,127}$")
+
+
+def _validate_safe_details(code: AuthErrorCode, details: Mapping[str, object]) -> None:
+    if code is AuthErrorCode.VALIDATION_ERROR and details:
+        field = details.get("field")
+        if not isinstance(field, str) or _FIELD_PATH.fullmatch(field) is None:
+            raise ValueError("field must be a schema-owned field path")
+    elif code is AuthErrorCode.AUTH_WEAK_PASSWORD and details:
+        raw_requirements = details.get("requirements")
+        if not isinstance(raw_requirements, (list, tuple)):
+            raise ValueError("requirements must be present")
+        try:
+            requirements = tuple(PasswordRequirement(item) for item in raw_requirements)
+        except (TypeError, ValueError) as exc:
+            raise ValueError("unknown password requirement") from exc
+        canonical = tuple(item for item in PasswordRequirement if item in requirements)
+        if requirements != canonical:
+            raise ValueError("password requirements must be unique and canonical")
+        minimum = details.get("minimum_length")
+        if minimum is not None and (
+            PasswordRequirement.LENGTH not in requirements
+            or isinstance(minimum, bool)
+            or not isinstance(minimum, int)
+            or not 1 <= minimum <= 1024
+        ):
+            raise ValueError("minimum_length requires a known length requirement")
+    elif (
+        code in {AuthErrorCode.PROJECT_NOT_READY, AuthErrorCode.RUNTIME_PROJECT_NOT_READY}
+        and details
+    ):
+        try:
+            ProjectStatus(details.get("status"))
+        except (TypeError, ValueError) as exc:
+            raise ValueError("status must be a ProjectStatus") from exc
+    elif code is AuthErrorCode.INVITATION_RESEND_TOO_SOON and details:
+        timestamp = details.get("resend_available_at")
+        seconds = details.get("remaining_seconds")
+        if not isinstance(timestamp, str):
+            raise ValueError("resend_available_at must be an RFC 3339 timestamp")
+        try:
+            parsed = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+        except ValueError as exc:
+            raise ValueError("resend_available_at must be an RFC 3339 timestamp") from exc
+        if parsed.tzinfo is None or parsed.utcoffset() is None:
+            raise ValueError("resend_available_at must include a UTC offset")
+        if isinstance(seconds, bool) or not isinstance(seconds, int) or seconds < 0:
+            raise ValueError("remaining_seconds must be a non-negative integer")
+    elif code is AuthErrorCode.ORG_MEMBERSHIP_LIMIT_EXCEEDED and details:
+        try:
+            for key in ("current_organization_id", "invited_organization_id"):
+                raw = details[key]
+                if not isinstance(raw, str) or str(UUID(raw)) != raw:
+                    raise ValueError
+        except (KeyError, TypeError, ValueError) as exc:
+            raise ValueError("organization details must contain canonical UUIDs") from exc
+    elif code is AuthErrorCode.AUTH_IDENTITY_CHANGED and details:
+        for key in ("previous_epoch", "current_epoch"):
+            value = details.get(key)
+            if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+                raise ValueError("identity epochs must be non-negative integers")
+
+
+class AuthError(PolygresError):
+    def __init__(
+        self,
+        code: AuthErrorCode,
+        *,
+        details: Mapping[str, object] | None = None,
+        retry_after_seconds: int | None = None,
+    ) -> None:
+        descriptor = AUTH_ERROR_CATALOG[code]
+        supplied = dict(details or {})
+        unknown = supplied.keys() - descriptor.safe_detail_keys
+        if unknown:
+            raise ValueError(f"unsafe error detail keys: {sorted(unknown)!r}")
+        _validate_safe_details(code, supplied)
+        if retry_after_seconds is not None and (
+            isinstance(retry_after_seconds, bool)
+            or not isinstance(retry_after_seconds, int)
+            or not 0 <= retry_after_seconds <= 86_400
+            or descriptor.retry_class is RetryClass.NEVER
+        ):
+            raise ValueError("invalid retry_after_seconds for auth error")
+        super().__init__(error_record(code.value, details=supplied))
+        self.code = code
+        self.retry_class = descriptor.retry_class
+        self.reset_class = descriptor.reset_class
+        self.message_key = descriptor.message_key
+        self.retry_after_seconds = retry_after_seconds
+
+    def __repr__(self) -> str:
+        return f"AuthError(code={self.code.value!r})"

polygres_sdk-0.3.0/src/polygres/_vendor/polygres_lib/context/errors.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from ..errors import ERROR_CATALOG
+
+
+class ContextErrorCode(str, Enum):
+    REQUEST_INVALID = "CONTEXT_REQUEST_INVALID"
+    IDENTIFIER_INVALID = "CONTEXT_IDENTIFIER_INVALID"
+    SOURCE_INVALID = "CONTEXT_SOURCE_INVALID"
+    DELETE_CONFIRMATION_INVALID = "CONTEXT_DELETE_CONFIRMATION_INVALID"
+    POINT_KEY_INVALID = "CONTEXT_POINT_KEY_INVALID"
+    EMBEDDING_INVALID = "CONTEXT_EMBEDDING_INVALID"
+    FILTER_INVALID = "CONTEXT_FILTER_INVALID"
+    LIMIT_EXCEEDED = "CONTEXT_LIMIT_EXCEEDED"
+    GRAPH_START_REQUIRED = "CONTEXT_GRAPH_START_REQUIRED"
+    GRAPH_DIRECTION_INVALID = "CONTEXT_GRAPH_DIRECTION_INVALID"
+    RANKING_WEIGHTS_INVALID = "CONTEXT_RANKING_WEIGHTS_INVALID"
+    RESOURCE_NAMESPACE_MISMATCH = "CONTEXT_RESOURCE_NAMESPACE_MISMATCH"
+    COLLECTION_NOT_FOUND = "CONTEXT_COLLECTION_NOT_FOUND"
+    OPERATION_NOT_FOUND = "CONTEXT_OPERATION_NOT_FOUND"
+    COLLECTION_NOT_READY = "CONTEXT_COLLECTION_NOT_READY"
+    TEXT_COLUMN_REQUIRED = "CONTEXT_TEXT_COLUMN_REQUIRED"
+    GRAPH_NOT_READY = "CONTEXT_GRAPH_NOT_READY"
+    SOURCE_KEY_ALIGNMENT_INVALID = "CONTEXT_SOURCE_KEY_ALIGNMENT_INVALID"
+    CAPABILITY_UNAVAILABLE = "CONTEXT_CAPABILITY_UNAVAILABLE"
+    SOURCE_KEY_NOT_FOUND = "CONTEXT_SOURCE_KEY_NOT_FOUND"
+    SOURCE_VECTOR_INVALID = "CONTEXT_SOURCE_VECTOR_INVALID"
+    FILTER_REGISTRATION_CONFLICT = "CONTEXT_FILTER_REGISTRATION_CONFLICT"
+    POINT_CURSOR_INVALID = "CONTEXT_POINT_CURSOR_INVALID"
+    RECALL_UNAVAILABLE = "CONTEXT_RECALL_UNAVAILABLE"
+    COLLECTION_NAME_CONFLICT = "CONTEXT_COLLECTION_NAME_CONFLICT"
+    PREFLIGHT_BLOCKED = "CONTEXT_PREFLIGHT_BLOCKED"
+    OPERATION_CONFLICT = "CONTEXT_OPERATION_CONFLICT"
+    IDEMPOTENCY_CONFLICT = "CONTEXT_IDEMPOTENCY_CONFLICT"
+    OPERATION_NOT_CANCELLABLE = "CONTEXT_OPERATION_NOT_CANCELLABLE"
+    OPERATION_NOT_RETRYABLE = "CONTEXT_OPERATION_NOT_RETRYABLE"
+    OPERATION_CANCELLED = "CONTEXT_OPERATION_CANCELLED"
+    ONBOARDING_NOT_ELIGIBLE = "CONTEXT_ONBOARDING_NOT_ELIGIBLE"
+    ONBOARDING_NOT_AVAILABLE = "CONTEXT_ONBOARDING_NOT_AVAILABLE"
+    RUNTIME_UNSUPPORTED = "CONTEXT_RUNTIME_UNSUPPORTED"
+    EXTENSION_UNAVAILABLE = "CONTEXT_EXTENSION_UNAVAILABLE"
+    SOURCE_TABLE_UNSUPPORTED = "CONTEXT_SOURCE_TABLE_UNSUPPORTED"
+    SOURCE_KEY_REQUIRED = "CONTEXT_SOURCE_KEY_REQUIRED"
+    SOURCE_KEY_TYPE_UNSUPPORTED = "CONTEXT_SOURCE_KEY_TYPE_UNSUPPORTED"
+    SOURCE_KEY_TEXT_CONSTRAINT_REQUIRED = "CONTEXT_SOURCE_KEY_TEXT_CONSTRAINT_REQUIRED"
+    SOURCE_PRIVILEGE_REQUIRED = "CONTEXT_SOURCE_PRIVILEGE_REQUIRED"
+    VECTOR_COLUMN_MISSING = "CONTEXT_VECTOR_COLUMN_MISSING"
+    VECTOR_COLUMN_CONFLICT = "CONTEXT_VECTOR_COLUMN_CONFLICT"
+    VECTOR_TYPE_UNSUPPORTED = "CONTEXT_VECTOR_TYPE_UNSUPPORTED"
+    VECTOR_NULLABLE = "CONTEXT_VECTOR_NULLABLE"
+    VECTOR_DIMENSION_INVALID = "CONTEXT_VECTOR_DIMENSION_INVALID"
+    COSINE_ZERO_VECTOR = "CONTEXT_COSINE_ZERO_VECTOR"
+    RESULT_COLUMN_INVALID = "CONTEXT_RESULT_COLUMN_INVALID"
+    FILTER_COLUMN_INVALID = "CONTEXT_FILTER_COLUMN_INVALID"
+    JSONB_FILTER_PATH_INVALID = "CONTEXT_JSONB_FILTER_PATH_INVALID"
+    RESERVED_FILTER_CONFLICT = "CONTEXT_RESERVED_FILTER_CONFLICT"
+    TEXT_COLUMN_INVALID = "CONTEXT_TEXT_COLUMN_INVALID"
+    HNSW_UNSUPPORTED = "CONTEXT_HNSW_UNSUPPORTED"
+    INDEX_CONFLICT = "CONTEXT_INDEX_CONFLICT"
+    MEMORY_PRESSURE = "CONTEXT_MEMORY_PRESSURE"
+    PGVECTOR_SOURCE = "CONTEXT_PGVECTOR_SOURCE"
+    UNSUPPORTED_VECTOR_TYPE = "CONTEXT_UNSUPPORTED_VECTOR_TYPE"
+
+
+@dataclass(frozen=True, slots=True)
+class ContextErrorDescriptor:
+    status_code: int
+    message: str
+    safe_detail_fields: tuple[str, ...] = ()
+    retryable: bool = False
+    conflict: bool = False
+    availability: bool = False
+
+
+CONTEXT_ERROR_CATALOG: dict[ContextErrorCode, ContextErrorDescriptor] = {
+    code: ContextErrorDescriptor(
+        status_code=ERROR_CATALOG[code.value].http_status,
+        message=ERROR_CATALOG[code.value].message,
+        safe_detail_fields=tuple(sorted(ERROR_CATALOG[code.value].safe_detail_fields)),
+        retryable=ERROR_CATALOG[code.value].retry_class
+        in {"bounded_retry", "dependency_retry", "after_delay"},
+        conflict=ERROR_CATALOG[code.value].http_status == 409,
+        availability=(
+            "UNAVAILABLE" in code.value
+            or "NOT_READY" in code.value
+            or code is ContextErrorCode.MEMORY_PRESSURE
+        ),
+    )
+    for code in ContextErrorCode
+}
+
+if set(CONTEXT_ERROR_CATALOG) != set(ContextErrorCode):
+    raise RuntimeError("global error catalog must define every ContextErrorCode exactly once")
+
+
+__all__ = [
+    "CONTEXT_ERROR_CATALOG",
+    "ContextErrorCode",
+    "ContextErrorDescriptor",
+]

{polygres_sdk-0.2.1 → polygres_sdk-0.3.0}/src/polygres/_vendor/polygres_lib/context/models.py

@@ -511,6 +511,7 @@ class JointSearchRequest(GraphSearchBase):
 
 class ErrorBody(ContextResponse):
     code: str
+    variant: str | None = None
     message: str
     details: dict[str, Any]
 
@@ -749,6 +750,7 @@ class CollectionGetResponse(ContextResponse):
 
 class ContextOperationFailure(ContextResponse):
     code: str
+    variant: str | None = None
     message: str
     details: dict[str, Any]
     http_status: int
@@ -1080,9 +1082,7 @@ class ContextJointResult(ContextSearchResult):
             raise ValueError("graph-introduced results require null baseline fields")
         if self.introduced_by_graph and self.graph is None:
             raise ValueError("graph-introduced results require graph evidence")
-        if not self.introduced_by_graph and (
-            self.baseline_rank is None or self.rank_lift is None
-        ):
+        if not self.introduced_by_graph and (self.baseline_rank is None or self.rank_lift is None):
             raise ValueError("non-graph-introduced results require baseline fields")
         if not math.isclose(
             self.score,