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

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

@@ -19,9 +19,30 @@ Run these before opening a pull request:
 ```bash
 pytest
 ruff check .
+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
 python -m build
+python tools/verify_distribution.py dist/*.whl dist/*.tar.gz
 ```
 
+The Runtime OpenAPI snapshot can be regenerated only from the Polygres
+monorepo, where `services/api` is available. An SDK-only checkout can validate
+the committed snapshot structure and canonical formatting, while the monorepo
+sync gate performs the byte-for-byte application comparison.
+
+Public methods stay hand-written and typed. Add non-wrapping binding metadata
+and a description plus safe example for every new network method, then
+regenerate the method JSON and reference page. Neither JSON artifact may be
+used to route requests.
+
+Use SemVer for the package. Before 1.0, breaking changes increment the minor
+version and require a topic note in `migrations`; additive public changes also
+increment the minor version. Internal fixes with unchanged public behavior use
+a patch release.
+
 ## Publishing
 
 Publishing uses GitHub Actions Trusted Publishing. Do not add PyPI API tokens
@@ -39,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.1.0
+     polygres-sdk==0.2.1
    /tmp/polygres-sdk-testpypi/bin/python - <<'PY'
    import importlib.metadata
    from polygres import Polygres
@@ -53,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.1.0
-git push origin polygres-sdk-v0.1.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.1/PKG-INFO

@@ -0,0 +1,304 @@
+Metadata-Version: 2.5
+Name: polygres-sdk
+Version: 0.2.1
+Summary: Python SDK for Polygres
+Project-URL: Homepage, https://polygres.com
+Project-URL: Documentation, https://docs.polygres.com/sdk
+Project-URL: Repository, https://github.com/Evokoa/polygres-sdk
+Project-URL: Changelog, https://github.com/Evokoa/polygres-sdk/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Evokoa/polygres-sdk/issues
+Project-URL: Support, https://polygres.com
+Author: Polygres
+Maintainer-email: Polygres <support@polygres.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: graph-search,hybrid-search,polygres,postgres,postgresql,retrieval,vector-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == 'dev'
+Requires-Dist: hatchling>=1.26.3; extra == 'dev'
+Requires-Dist: jsonschema<5,>=4.23; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: respx>=0.21.1; extra == 'dev'
+Requires-Dist: ruff>=0.8.4; extra == 'dev'
+Requires-Dist: tomli>=2.0.1; (python_version < '3.11') and extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Polygres Python SDK
+
+Build Python applications with Polygres graph, vector, text, and hybrid retrieval.
+
+The SDK connects to one project's Runtime API using a Polygres API key. It does not open PostgreSQL connections or expose database passwords.
+
+- [Documentation](https://docs.polygres.com)
+- [Polygres](https://polygres.com)
+- [Discord](https://discord.gg/GnHR8ezuwG)
+
+## Install
+
+The SDK requires Python 3.10 or newer.
+
+```bash
+pip install polygres-sdk
+```
+
+The SDK is a Python library and does not install the `polygres` terminal command. Install `polygres-cli` separately for project setup, imports, migrations, and retrieval configuration.
+
+## Quick start
+
+Create a Project API Key in **Settings** and copy the Runtime API URL from the project's **Connect** page. Store both values in your application's secret configuration.
+
+```python
+import os
+
+from polygres import Polygres
+
+client = Polygres(
+    api_key=os.environ["POLYGRES_API_KEY"],
+    runtime_url=os.environ["POLYGRES_RUNTIME_URL"],
+)
+project = client.project()
+
+readiness = project.readiness()
+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.
+
+## Choose a retrieval method
+
+| Need | Method |
+| --- | --- |
+| Search by semantic similarity | `project.vector.search()` |
+| Find rows similar to an existing row | `project.vector.similar_to()` |
+| Search text with PostgreSQL full-text search | `project.text.tsvector()` |
+| Tolerate misspellings in short text | `project.text.fuzzy()` |
+| Traverse relationships | `project.graph.expand()` or `project.graph.related()` |
+| Combine graph and vector relevance | `project.hybrid.*` |
+
+The corresponding graph, vector, or text configuration must be ready before the application sends retrieval requests.
+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.
+
+## Vector retrieval
+
+Generate the query embedding with the same model and dimensions used by the saved vector configuration.
+
+```python
+query_embedding = [0.1] * 768
+
+page = project.vector.search(
+    query_embedding,
+    config="documents_embedding",
+    filters={"status": "published"},
+    min_similarity=0.75,
+    limit=10,
+)
+
+for result in page.results:
+    print(result.id, result.score, result.properties)
+```
+
+Find rows similar to an existing row without generating another embedding:
+
+```python
+page = project.vector.similar_to(
+    row_id="doc_123",
+    config="documents_embedding",
+    limit=10,
+)
+```
+
+## Text retrieval
+
+Full-text search:
+
+```python
+page = project.text.tsvector(
+    "refund policy",
+    config="documents_body_tsv",
+    filters={"status": "published"},
+    limit=10,
+)
+```
+
+Fuzzy text search:
+
+```python
+page = project.text.fuzzy(
+    "acme corpration",
+    config="customer_name_fuzzy",
+    limit=10,
+)
+```
+
+## Graph retrieval
+
+Graph methods start from real rows in graph-registered tables. Use an ID from trusted application data or a previous retrieval result.
+
+```python
+start = {
+    "schema": "public",
+    "table": "documents",
+    "id": "doc_123",
+}
+
+page = project.graph.expand(
+    start,
+    max_depth=2,
+    direction="any",
+    limit=20,
+)
+
+for result in page.results:
+    print(result.node.id, result.depth, result.readable_path)
+```
+
+Other graph methods include:
+
+```python
+neighbors = project.graph.neighborhood(start, radius=2, limit=20)
+related = project.graph.related(start, limit=20)
+
+target = {"schema": "public", "table": "documents", "id": "doc_456"}
+paths = project.graph.path(start, target, max_depth=3)
+connections = project.graph.connection([start, target], max_depth=3)
+```
+
+If a graph method returns `Node not found`, confirm that the row exists, its table is registered, and the graph was rebuilt after the latest relevant changes.
+
+## Hybrid retrieval
+
+Graph-first retrieval starts from a known row and adds vector relevance:
+
+```python
+page = project.hybrid.graph_first(
+    start,
+    embedding=query_embedding,
+    config="documents_embedding",
+    max_depth=2,
+    limit=10,
+)
+```
+
+Vector-first retrieval finds semantic candidates before expanding graph context:
+
+```python
+page = project.hybrid.vector_first(
+    query_embedding,
+    config="documents_embedding",
+    vector_limit=20,
+    max_depth=1,
+    limit=10,
+)
+```
+
+Joint retrieval lets vector and graph rankings contribute independently:
+
+```python
+page = project.hybrid.joint(
+    query_embedding,
+    start,
+    config="documents_embedding",
+    vector_weight=0.7,
+    graph_weight=0.3,
+    max_depth=2,
+    limit=10,
+)
+```
+
+## Pagination
+
+Retrieval methods return a `Page` with `results`, `has_more`, and `next_cursor`.
+
+```python
+page = project.vector.search(
+    query_embedding,
+    config="documents_embedding",
+    limit=25,
+)
+
+for result in page.results:
+    print(result.id)
+
+if page.has_more:
+    next_page = project.vector.search(
+        query_embedding,
+        config="documents_embedding",
+        limit=25,
+        cursor=page.next_cursor,
+    )
+```
+
+Use `auto_paging_iter()` when you want the SDK to follow every page:
+
+```python
+for result in page.auto_paging_iter():
+    print(result.id, result.score)
+```
+
+## Error handling
+
+SDK exceptions include the HTTP status, stable error code, safe details, and request ID when available.
+
+```python
+from polygres import PolygresAPIError
+
+try:
+    page = project.graph.expand(start, max_depth=2)
+except PolygresAPIError as exc:
+    print(exc.status_code)
+    print(exc.code)
+    print(exc.request_id)
+    print(exc.details)
+```
+
+Keep the request ID when reporting a problem. Never log or send the Project API Key.
+
+## Connection information
+
+`connection_info()` returns project hosts and passwordless connection strings. It never returns the database password.
+
+```python
+connection = project.connection_info()
+print(connection.direct_host)
+print(connection.pooled_host)
+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.
+
+## Version and support
+
+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.1 release notes](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.2.1) for release changes.
+
+## Optional Agent Skill
+
+The `polygres-sdk` Agent Skill helps compatible coding agents write and review Polygres application code.
+
+```bash
+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.

polygres_sdk-0.2.1/README.md

@@ -0,0 +1,262 @@
+# Polygres Python SDK
+
+Build Python applications with Polygres graph, vector, text, and hybrid retrieval.
+
+The SDK connects to one project's Runtime API using a Polygres API key. It does not open PostgreSQL connections or expose database passwords.
+
+- [Documentation](https://docs.polygres.com)
+- [Polygres](https://polygres.com)
+- [Discord](https://discord.gg/GnHR8ezuwG)
+
+## Install
+
+The SDK requires Python 3.10 or newer.
+
+```bash
+pip install polygres-sdk
+```
+
+The SDK is a Python library and does not install the `polygres` terminal command. Install `polygres-cli` separately for project setup, imports, migrations, and retrieval configuration.
+
+## Quick start
+
+Create a Project API Key in **Settings** and copy the Runtime API URL from the project's **Connect** page. Store both values in your application's secret configuration.
+
+```python
+import os
+
+from polygres import Polygres
+
+client = Polygres(
+    api_key=os.environ["POLYGRES_API_KEY"],
+    runtime_url=os.environ["POLYGRES_RUNTIME_URL"],
+)
+project = client.project()
+
+readiness = project.readiness()
+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.
+
+## Choose a retrieval method
+
+| Need | Method |
+| --- | --- |
+| Search by semantic similarity | `project.vector.search()` |
+| Find rows similar to an existing row | `project.vector.similar_to()` |
+| Search text with PostgreSQL full-text search | `project.text.tsvector()` |
+| Tolerate misspellings in short text | `project.text.fuzzy()` |
+| Traverse relationships | `project.graph.expand()` or `project.graph.related()` |
+| Combine graph and vector relevance | `project.hybrid.*` |
+
+The corresponding graph, vector, or text configuration must be ready before the application sends retrieval requests.
+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.
+
+## Vector retrieval
+
+Generate the query embedding with the same model and dimensions used by the saved vector configuration.
+
+```python
+query_embedding = [0.1] * 768
+
+page = project.vector.search(
+    query_embedding,
+    config="documents_embedding",
+    filters={"status": "published"},
+    min_similarity=0.75,
+    limit=10,
+)
+
+for result in page.results:
+    print(result.id, result.score, result.properties)
+```
+
+Find rows similar to an existing row without generating another embedding:
+
+```python
+page = project.vector.similar_to(
+    row_id="doc_123",
+    config="documents_embedding",
+    limit=10,
+)
+```
+
+## Text retrieval
+
+Full-text search:
+
+```python
+page = project.text.tsvector(
+    "refund policy",
+    config="documents_body_tsv",
+    filters={"status": "published"},
+    limit=10,
+)
+```
+
+Fuzzy text search:
+
+```python
+page = project.text.fuzzy(
+    "acme corpration",
+    config="customer_name_fuzzy",
+    limit=10,
+)
+```
+
+## Graph retrieval
+
+Graph methods start from real rows in graph-registered tables. Use an ID from trusted application data or a previous retrieval result.
+
+```python
+start = {
+    "schema": "public",
+    "table": "documents",
+    "id": "doc_123",
+}
+
+page = project.graph.expand(
+    start,
+    max_depth=2,
+    direction="any",
+    limit=20,
+)
+
+for result in page.results:
+    print(result.node.id, result.depth, result.readable_path)
+```
+
+Other graph methods include:
+
+```python
+neighbors = project.graph.neighborhood(start, radius=2, limit=20)
+related = project.graph.related(start, limit=20)
+
+target = {"schema": "public", "table": "documents", "id": "doc_456"}
+paths = project.graph.path(start, target, max_depth=3)
+connections = project.graph.connection([start, target], max_depth=3)
+```
+
+If a graph method returns `Node not found`, confirm that the row exists, its table is registered, and the graph was rebuilt after the latest relevant changes.
+
+## Hybrid retrieval
+
+Graph-first retrieval starts from a known row and adds vector relevance:
+
+```python
+page = project.hybrid.graph_first(
+    start,
+    embedding=query_embedding,
+    config="documents_embedding",
+    max_depth=2,
+    limit=10,
+)
+```
+
+Vector-first retrieval finds semantic candidates before expanding graph context:
+
+```python
+page = project.hybrid.vector_first(
+    query_embedding,
+    config="documents_embedding",
+    vector_limit=20,
+    max_depth=1,
+    limit=10,
+)
+```
+
+Joint retrieval lets vector and graph rankings contribute independently:
+
+```python
+page = project.hybrid.joint(
+    query_embedding,
+    start,
+    config="documents_embedding",
+    vector_weight=0.7,
+    graph_weight=0.3,
+    max_depth=2,
+    limit=10,
+)
+```
+
+## Pagination
+
+Retrieval methods return a `Page` with `results`, `has_more`, and `next_cursor`.
+
+```python
+page = project.vector.search(
+    query_embedding,
+    config="documents_embedding",
+    limit=25,
+)
+
+for result in page.results:
+    print(result.id)
+
+if page.has_more:
+    next_page = project.vector.search(
+        query_embedding,
+        config="documents_embedding",
+        limit=25,
+        cursor=page.next_cursor,
+    )
+```
+
+Use `auto_paging_iter()` when you want the SDK to follow every page:
+
+```python
+for result in page.auto_paging_iter():
+    print(result.id, result.score)
+```
+
+## Error handling
+
+SDK exceptions include the HTTP status, stable error code, safe details, and request ID when available.
+
+```python
+from polygres import PolygresAPIError
+
+try:
+    page = project.graph.expand(start, max_depth=2)
+except PolygresAPIError as exc:
+    print(exc.status_code)
+    print(exc.code)
+    print(exc.request_id)
+    print(exc.details)
+```
+
+Keep the request ID when reporting a problem. Never log or send the Project API Key.
+
+## Connection information
+
+`connection_info()` returns project hosts and passwordless connection strings. It never returns the database password.
+
+```python
+connection = project.connection_info()
+print(connection.direct_host)
+print(connection.pooled_host)
+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.
+
+## Version and support
+
+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.1 release notes](https://github.com/Evokoa/polygres-sdk/releases/tag/polygres-sdk-v0.2.1) for release changes.
+
+## Optional Agent Skill
+
+The `polygres-sdk` Agent Skill helps compatible coding agents write and review Polygres application code.
+
+```bash
+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.

polygres_sdk-0.2.1/compatibility/0.1.0/README.md

@@ -0,0 +1,10 @@
+# SDK compatibility baseline 0.1.0
+
+`python-sdk-v1.methods.json` is the explicit released 0.1.0 public network
+surface used by CI and release checks for 0.2.0. It records the original
+retrieval methods and marks Context operations as unavailable in that release.
+The baseline uses the first formal stable operation identities because
+generated FastAPI function names were not a published SDK contract in 0.1.0.
+
+Release automation must name this file with `--baseline`; the compatibility
+tool refuses to infer a baseline from an arbitrary local artifact.