Polygres Sdk

Polygres SDK

Build Python application code against the public polygres-sdk package and a project's Runtime API. Use $polygres-cli instead for human authentication, control-plane project administration, imports, migrations, and API-key management.

For an interactive grounded answer, prefer available Polygres MCP tools. Read references/mcp-tool-contract.md and references/mcp-grounded-context.md, then use the discovered read catalog. Continue with the SDK workflow for persistent Python application integration, backend-owned automation, or an MCP fallback.

Workflow

1. Inspect pyproject.toml, requirements files, and existing client setup.
2. Confirm the installed polygres-sdk and polygres-cli versions before live or end-to-end testing. If testing a Polygres source checkout, create an isolated environment, reinstall both packages from that checkout under its dependency-installation policy, and verify their versions and import origins. Do not substitute PyPI packages for the checkout under test.
3. Outside a source checkout, compare both installed versions with the application requirements or current skill compatibility record. Obtain approval before installing or changing dependencies.
4. Resolve POLYGRES_API_KEY and POLYGRES_RUNTIME_URL from server-side environment configuration. Never log or embed either value.
5. Confirm that the URL is the per-project Runtime API URL, not the Polygres control-plane URL or a direct or pooled Postgres URL.
6. Resolve project mode before selecting a namespace. For a synced project, construct client.project(project_mode="synced") and read references/synced-projects.md.
7. Check project.readiness() before relying on graph, existing vector, or legacy hybrid retrieval. For new semantic retrieval, prefer Polygres AI Context: call project.context.get_capabilities() and then inspect collection status or verification. Use project.connection_info() only for passwordless connection metadata.
8. Keep every pgContext call on the flat project.context namespace. Prefer $polygres-cli for interactive setup. Use SDK mutations for explicit, backend-owned automation, return them immediately, and wait only when the application workflow requires a terminal result.
9. Choose one focused retrieval call. Use real row IDs returned by the SDK or verified application data; never invent graph identifiers.
10. Bound depth, candidate counts, result limits, pagination, and application token budget. Apply authorization before retrieval because filters are not an authorization boundary.
11. Preserve result provenance, request IDs, and typed models through RAG assembly. Deduplicate before constructing context.
12. Handle the documented exception hierarchy and test success, malformed responses, fuzzy or empty queries, invalid dimensions, and transient errors.

Reference routing

• Read references/client-setup.md for installation, environment variables, endpoint selection, readiness, and passwordless connection information.
• Read references/synced-projects.md for synced-project API-key limits, unavailable write and database surfaces, source-authoritative writes, and CLI or dashboard control-plane handoff.
• Read references/graph-retrieval.md for graph calls, real row-ID discovery, direction, depth, and fan-out limits.
• Read references/vector-and-text.md for existing vector compatibility, TSVector, fuzzy retrieval, filters, thresholds, and dimension checks.
• Read references/hybrid-and-rag.md for graph-first, vector-first, joint retrieval, chaining, provenance, deduplication, and context budgets.
• Read references/context.md for pgContext collection identity, multiple named vectors and defaults, explicit operations, point lifecycle, retrieval modes, and Joint versus rank fusion.
• Read references/rows.md for validated single-row insert, upsert, ignore, retry, ambiguous-commit, and pipeline checkpoint behavior.
• Read references/errors-pagination-testing.md for typed models, cursors, automatic pagination, exceptions, retries, and mocked tests.
• Read references/mcp-grounded-context.md for interactive grounded answers through the available MCP Context tools.

Boundaries

• Use only public SDK methods. Never reverse-engineer a private endpoint or private route, and never call the control-plane from application retrieval code.
• Use project.context for backend-owned pgContext collection configuration. Activate $polygres-cli for interactive human workflows and control-plane work.
• Use project.vector only with a previously registered, enabled configuration that is effectively Ready. HNSW requires its exact physical index to be Ready; index_kind: none can serve exact scan without HNSW. Do not infer a registration from a physical-only index or design new setup around vector-configuration creation; use project.context.create_collection() instead.
• Do not pass pgvector configuration IDs to pgContext methods or imply that Polygres generates source or query embeddings.
• Never print headers, environment variables, API keys, or database secrets.
• Treat connection_info() as passwordless metadata. It does not return a database password. Never call it for a synced project.
• Never use project.rows for a synced project or use rows validation as a capability probe. Mutate the source database instead.
• Do not claim a query is authorized merely because it includes filters.
• Do not retry validation, authentication, or permission errors blindly.
• Do not hide partial pagination, malformed payloads, timeouts, or request IDs.

Completion report

State project mode and the Runtime API context without secrets, retrieval strategy, filters and bounds, pagination behavior, provenance fields retained, tests run, and any readiness or configuration work still required through $polygres-cli.