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

{polygres_sdk-0.2.1 → polygres_sdk-0.4.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.3.0/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.4.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.4.0
+git push origin polygres-sdk-v0.4.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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: polygres-sdk
-Version: 0.2.1
+Version: 0.4.0
 Summary: Python SDK for Polygres
 Project-URL: Homepage, https://polygres.com
 Project-URL: Documentation, https://docs.polygres.com/sdk
@@ -81,6 +81,23 @@ print(readiness.graph, readiness.vector, readiness.hybrid)
 
 Use the Runtime API URL with the SDK. Do not use a direct or pooled PostgreSQL connection string.
 
+## Synchronized PostgreSQL projects
+
+For a synchronized project, the Runtime does not expose connection information.
+That surface raises `PolygresPermissionError` with code
+`SYNCED_PROJECT_SURFACE_UNAVAILABLE`. Readiness, `project.vector`,
+`project.hybrid`, graph, text-search, and pgContext remain available after
+synchronization is ready.
+
+If your application already has the authoritative control-plane project payload,
+pass its mode to the SDK to reject a connection-information call before building
+a Runtime request. The Runtime enforces the same boundary when no mode hint is
+supplied.
+
+```python
+project = client.project(project_mode="synced")
+```
+
 ## Choose a retrieval method
 
 | Need | Method |
@@ -97,6 +114,41 @@ 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.
 
+## pgContext-aligned names
+
+SDK 0.4.0 adds pgContext 0.2.0 terminology while keeping every SDK 0.3.0
+Context method available. Existing applications can upgrade without changing
+their calls.
+
+The stable pgContext 0.2.0 inventory is fully classified and has no missing SDK
+entries. Database-native vector operators remain SQL-only, and five
+backend-wide or privileged instrumentation functions remain available through
+direct SQL rather than the project-scoped Runtime API. See the
+[migration and coverage notes](migrations/pgcontext-0.2.0-names.md).
+
+```python
+operation = project.context.register_vector(
+    collection_id,
+    "title_embedding",
+    768,
+)
+project.context.register_filter_column(
+    collection_id,
+    "tenant_id",
+    "tenant_id",
+)
+results = project.context.query(
+    "support_docs",
+    query_embedding,
+    query="refund policy",
+)
+```
+
+The earlier `add_vector()`, `add_filter_column()`, and `text_hybrid()` names
+remain silent compatibility aliases with unchanged behavior. See the
+[pgContext naming migration](migrations/pgcontext-0.2.0-names.md) for the full
+mapping.
+
 ## Vector retrieval
 
 Generate the query embedding with the same model and dimensions used by the saved vector configuration.
@@ -274,7 +326,9 @@ Keep the request ID when reporting a problem. Never log or send the Project API
 
 ## Connection information
 
-`connection_info()` returns project hosts and passwordless connection strings. It never returns the database password.
+For a standard project, `connection_info()` returns project hosts and passwordless
+connection strings. It never returns the database password. It raises
+`PolygresPermissionError` for a synchronized project.
 
 ```python
 connection = project.connection_info()
@@ -285,13 +339,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.4.0`](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.4.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.4.0 release notes](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.4.0) for release changes.
 
 ## Optional Agent Skill
 

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

@@ -39,6 +39,23 @@ print(readiness.graph, readiness.vector, readiness.hybrid)
 
 Use the Runtime API URL with the SDK. Do not use a direct or pooled PostgreSQL connection string.
 
+## Synchronized PostgreSQL projects
+
+For a synchronized project, the Runtime does not expose connection information.
+That surface raises `PolygresPermissionError` with code
+`SYNCED_PROJECT_SURFACE_UNAVAILABLE`. Readiness, `project.vector`,
+`project.hybrid`, graph, text-search, and pgContext remain available after
+synchronization is ready.
+
+If your application already has the authoritative control-plane project payload,
+pass its mode to the SDK to reject a connection-information call before building
+a Runtime request. The Runtime enforces the same boundary when no mode hint is
+supplied.
+
+```python
+project = client.project(project_mode="synced")
+```
+
 ## Choose a retrieval method
 
 | Need | Method |
@@ -55,6 +72,41 @@ 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.
 
+## pgContext-aligned names
+
+SDK 0.4.0 adds pgContext 0.2.0 terminology while keeping every SDK 0.3.0
+Context method available. Existing applications can upgrade without changing
+their calls.
+
+The stable pgContext 0.2.0 inventory is fully classified and has no missing SDK
+entries. Database-native vector operators remain SQL-only, and five
+backend-wide or privileged instrumentation functions remain available through
+direct SQL rather than the project-scoped Runtime API. See the
+[migration and coverage notes](migrations/pgcontext-0.2.0-names.md).
+
+```python
+operation = project.context.register_vector(
+    collection_id,
+    "title_embedding",
+    768,
+)
+project.context.register_filter_column(
+    collection_id,
+    "tenant_id",
+    "tenant_id",
+)
+results = project.context.query(
+    "support_docs",
+    query_embedding,
+    query="refund policy",
+)
+```
+
+The earlier `add_vector()`, `add_filter_column()`, and `text_hybrid()` names
+remain silent compatibility aliases with unchanged behavior. See the
+[pgContext naming migration](migrations/pgcontext-0.2.0-names.md) for the full
+mapping.
+
 ## Vector retrieval
 
 Generate the query embedding with the same model and dimensions used by the saved vector configuration.
@@ -232,7 +284,9 @@ Keep the request ID when reporting a problem. Never log or send the Project API
 
 ## Connection information
 
-`connection_info()` returns project hosts and passwordless connection strings. It never returns the database password.
+For a standard project, `connection_info()` returns project hosts and passwordless
+connection strings. It never returns the database password. It raises
+`PolygresPermissionError` for a synchronized project.
 
 ```python
 connection = project.connection_info()
@@ -243,13 +297,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.4.0`](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.4.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.4.0 release notes](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.4.0) for release changes.
 
 ## Optional Agent Skill
 

polygres_sdk-0.4.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.4.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.4.0/compatibility/0.3.0/README.md

@@ -0,0 +1,10 @@
+# SDK compatibility baseline 0.3.0
+
+`python-sdk-v1.methods.json` is the explicit released SDK 0.3.0 public network
+surface. It is copied byte-for-byte from the generated method contract at the
+0.3.0 release boundary.
+
+SDK 0.4.0 compatibility and release checks must name this file with
+`--baseline`. The compatibility tool must classify the pgContext-aligned method
+names as additive and must report no removals or breaking changes to this
+baseline.