polygres-sdk

Polygres SDK

使用公开的 polygres-sdk 包和项目的 Runtime API 编写 Python 应用代码。对于用户身份验证、控制平面项目管理、导入、迁移和 API 密钥管理，请改用 $polygres-cli。

如需交互式的、有依据的回答，请优先使用可用的 Polygres MCP 工具。阅读 references/mcp-tool-contract.md 和 references/mcp-grounded-context.md，然后使用发现的读取目录。 对于持久化 Python 应用集成、由后端负责的自动化，或 MCP 回退方案，请继续使用 SDK 工作流。

工作流

1. 检查 pyproject.toml、requirements 文件和现有客户端设置。
2. 在进行实时或端到端测试之前，确认已安装的 polygres-sdk 和 polygres-cli 版本。如果要测试 Polygres 源代码检出版本，请创建隔离环境，按照其依赖安装策略从该检出版本重新安装两个包，并验证它们的版本和导入来源。不要用 PyPI 包替代正在测试的检出版本。
3. 如果不在源代码检出环境中，请将两个已安装版本与应用要求或当前技能兼容性记录进行比较。安装或更改依赖项之前，先获得批准。
4. 从服务端环境配置中解析 POLYGRES_API_KEY 和 POLYGRES_RUNTIME_URL。切勿记录或嵌入这两个值。
5. 确认该 URL 是每个项目的 Runtime API URL，而不是 Polygres 控制平面 URL，也不是直接或池化的 Postgres URL。
6. 在选择命名空间之前，先确定项目模式。对于同步项目，构造 client.project(project_mode="synced")，并阅读 references/synced-projects.md。
7. 在依赖图、现有向量或旧版混合检索之前，先检查 project.readiness()。对于新的语义检索，优先使用 Polygres AI Context：调用 project.context.get_capabilities()，然后检查集合状态或验证结果。仅将 project.connection_info() 用于获取无密码连接元数据。
8. 所有 pgContext 调用都必须使用扁平的 project.context 命名空间。交互式设置优先使用 $polygres-cli。仅在明确的、由后端负责的自动化场景中使用 SDK 执行变更，执行后立即返回结果；只有应用工作流需要最终结果时才等待。
9. 选择一个专注的检索调用。使用 SDK 返回的真实行 ID 或经验证的应用数据；切勿编造图标识符。
10. 限定深度、候选数量、结果限制、分页和应用令牌预算。检索前应用授权，因为筛选条件并非授权边界。
11. 在组装 RAG 时保留结果来源、请求 ID 和类型化模型。构建上下文之前先去重。
12. 处理文档说明的异常层级，并测试成功、格式错误的响应、模糊或空查询、无效维度以及瞬时错误。

参考资料导航

• 阅读 references/client-setup.md，了解安装、环境变量、端点选择、就绪状态和无密码连接信息。
• 阅读 references/synced-projects.md，了解同步项目的 API 密钥限制、不可用的写入和数据库功能、以源为准的写入，以及 CLI 或仪表板控制平面移交。
• 阅读 references/graph-retrieval.md，了解图调用、真实行 ID 的发现、方向、深度和扇出限制。
• 阅读 references/vector-and-text.md，了解现有向量兼容性、TSVector、模糊检索、筛选条件、阈值和维度检查。
• 阅读 references/hybrid-and-rag.md，了解图优先、向量优先、联合检索、链式调用、溯源、去重和上下文预算。
• 阅读 references/context.md，了解 pgContext 集合标识、多个命名向量和默认值、显式操作、点生命周期、检索模式，以及 Joint 与排名融合。
• 阅读 references/rows.md，了解经验证的单行插入、upsert、忽略、重试、提交状态不明，以及管道检查点行为。
• 阅读 references/errors-pagination-testing.md，了解类型化模型、游标、自动分页、异常、重试和模拟测试。
• 阅读 references/mcp-grounded-context.md，了解如何通过可用的 MCP Context 工具获取交互式、有依据的回答。

边界

• 仅使用公开的 SDK 方法。切勿逆向工程私有端点或私有路由，也切勿在应用检索代码中调用控制平面。
• 使用 project.context 配置由后端管理的 pgContext 集合。交互式人工工作流和控制平面操作请启用 $polygres-cli。
• 仅在已注册、已启用且实际处于 Ready 状态的配置下使用 project.vector。HNSW 要求其对应的物理索引确切处于 Ready 状态；index_kind: none 可执行精确扫描，无需 HNSW。不要根据仅有的物理索引推断配置已注册，也不要围绕创建向量配置来设计新的设置；请改用 project.context.create_collection()。
• 不要将 pgvector 配置 ID 传递给 pgContext 方法，也不要暗示 Polygres 会生成源嵌入或查询嵌入。
• 切勿输出标头、环境变量、API 密钥或数据库机密。
• 将 connection_info() 视为无密码元数据。它不会返回数据库密码。切勿对同步项目调用它。
• 切勿对同步项目使用 project.rows，也不要将行验证用作能力探测。请改为修改源数据库。
• 不要仅仅因为查询包含筛选条件就声称该查询已获授权。
• 切勿盲目重试验证、身份验证或权限错误。
• 不要隐藏分页不完整、载荷格式错误、超时或请求 ID。

完成报告

说明项目模式和 Runtime API 上下文（不包含机密）、检索策略、筛选条件和边界、分页行为、保留的溯源字段、运行的测试，以及仍需通过 $polygres-cli 完成的就绪状态或配置工作。