Polygres SDK 的用途是让 Python 应用代码通过公开的 polygres-sdk 包连接项目的 Runtime API，实现持久化的应用集成与后端自动化；需要人工认证、控制面项目管理、导入、迁移和 API 密钥管理时，改用 $polygres-cli。若只需交互式有据回答，优先使用可用的 Polygres MCP 工具。
使用方式：先检查 pyproject.toml、requirements 文件与现有客户端配置，确认已安装的 polygres-sdk 与 polygres-cli 版本后再做在线或端到端测试。若测试 Polygres 源码检出，应在隔离环境中按该检出的依赖安装策略重装两个包并核验版本与导入来源，不要用 PyPI 包替代被测检出。在源码检出之外，需把两个已安装版本与应用要求或兼容记录比对，安装或更改依赖前须获批准。从服务器端环境配置读取 POLYGRES_API_KEY 与 POLYGRES_RUNTIME_URL，切勿记录或嵌入其值，并确认该 URL 是每项目 Runtime API 地址，而非控制面或 Postgres 直连/池化地址。选择命名空间前先确定项目模式；synced 项目应构造 client.project(project_mode="synced")。依赖图、已有向量或旧式混合检索前须检查 project.readiness()；新语义检索优先用 Polygres AI Context，调用 project.context.get_capabilities() 后再查看集合状态。pgContext 调用应保持在扁平的 project.context 命名空间。选择单一聚焦检索调用，使用 SDK 返回的真实行 ID，限定深度、候选数、结果上限、分页与 token 预算；授权须在检索前完成，过滤条件不是授权边界。保留结果溯源与请求 ID，去重后再组装上下文，并处理已文档化的异常层级。
限制：只用公开 SDK 方法，不逆向私有端点，不在应用检索代码中调用控制面；不打印头部、环境变量、API 密钥或数据库机密；connection_info() 仅为无密码元数据，不对 synced 项目调用，也不用于 synced 项目的 project.rows；不把 pgvector 配置 ID 传给 pgContext 方法；不盲目重试校验、认证或权限错误。