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. 検索呼び出しは、目的に合ったものを 1 つ選びます。SDK が返した実際の行 ID、または検証済みのアプリケーションデータを使用し、グラフ識別子を作り出さないでください。
10. 深度、候補数、結果数の上限、ページネーション、アプリケーションのトークン予算に上限を設けます。フィルターは認可の境界ではないため、検索前に認可を適用してください。
11. RAG の組み立てでは、結果の来歴、リクエスト ID、型付きモデルを保持します。コンテキストを構築する前に重複を除去してください。
12. ドキュメント化された例外階層に従って処理し、成功、不正な形式のレスポンス、曖昧または空のクエリ、無効な次元数、一時的なエラーをテストします。

リファレンスの参照先

• インストール、環境変数、エンドポイントの選択、準備状態、パスワードレス接続に関する情報は、references/client-setup.md を参照してください。
• 同期済みプロジェクトの API キーの制限、利用できない書き込み機能とデータベース機能、ソースを正とする書き込み、CLI またはダッシュボードへのコントロールプレーンの引き継ぎについては、references/synced-projects.md を参照してください。
• グラフの呼び出し、実際の行 ID の特定、方向、深さ、ファンアウトの上限については、references/graph-retrieval.md を参照してください。
• 既存のベクトルとの互換性、TSVector、ファジー検索、フィルター、しきい値、次元チェックについては、references/vector-and-text.md を参照してください。
• グラフ優先、ベクトル優先、統合検索、連鎖、出典情報、重複排除、コンテキスト予算については、references/hybrid-and-rag.md を参照してください。
• pgContext のコレクション識別情報、複数の名前付きベクトルとデフォルト、明示的な操作、ポイントのライフサイクル、検索モード、Joint とランク融合の違いについては、references/context.md を参照してください。
• 検証済みの単一行の挿入、アップサート、無視、再試行、コミット結果が不明な場合の動作、パイプラインのチェックポイント動作については、references/rows.md を参照してください。
• 型付きモデル、カーソル、自動ページネーション、例外、再試行、モックテストについては、references/errors-pagination-testing.md を参照してください。
• 利用可能な MCP Context ツールを使った、対話形式の根拠に基づく回答については、references/mcp-grounded-context.md を参照してください。

境界

• 公開 SDK メソッドのみを使用してください。プライベートエンドポイントやプライベートルートをリバースエンジニアリングしたり、アプリケーションの検索コードからコントロールプレーンを呼び出したりしてはいけません。
• バックエンドが管理する pgContext コレクションの設定には、project.context を使用してください。対話形式の人間向けワークフローやコントロールプレーンでの作業には、$polygres-cli を有効にしてください。
• project.vector は、事前に登録され、有効化され、実質的に Ready である設定に限り使用してください。HNSW には、正確な物理インデックスが Ready であることが必要です。index_kind: none では、HNSW を使わずに厳密スキャンを実行できます。物理インデックスのみから設定の登録を推測したり、ベクトル設定の作成を前提として新たなセットアップを設計したりしないでください。代わりに、project.context.create_collection() を使用してください。
• pgvector の設定 ID を pgContext メソッドに渡したり、Polygres がソースまたはクエリの埋め込みを生成すると示唆したりしてはいけません。
• ヘッダー、環境変数、API キー、データベースの秘密情報を表示してはいけません。
• connection_info() はパスワードレスのメタデータとして扱ってください。データベースのパスワードは返しません。同期済みプロジェクトに対して呼び出してはいけません。
• 同期済みプロジェクトに project.rows を使用したり、機能確認のために行の検証を使用したりしてはいけません。代わりに、ソースデータベースを変更してください。
• フィルターが含まれているという理由だけで、クエリが認可されていると主張してはいけません。
• 検証、認証、権限エラーを、むやみに再試行してはいけません。
• ページネーションの一部未取得、不正なペイロード、タイムアウト、リクエスト ID を隠してはいけません。

完了レポート

秘密情報を含めずに、プロジェクトのモードと Runtime API のコンテキスト、検索戦略、フィルターと上限、ページネーションの動作、保持した出典情報のフィールド、実施したテスト、$polygres-cli を通じて引き続き必要な準備状態の確認や設定作業を記載してください。