hh-wonderfish-ai-sdk

文書概要

wonderfish-cp-sdkは、すべてのProduct Serviceが同じ内容を実装することになる連携処理だけを担います。Control Planeを呼び出す側と、Control Planeから呼び出される側の両方を提供します。責務の境界はProduct Service SDK仕様書3章に定めます。

ディレクトリ

src/wonderfish_cp/           SDKのPythonソース
src/wonderfish_cp/inbound/   Control Planeから呼び出されるPS-inbound router
src/wonderfish_cp/external/  Product Serviceの外部API middleware
src/wonderfish_cp/discovery.py Product Service間の業務Resource検索Token検証
src/wonderfish_cp/adapters/  保存先Portの実装（インメモリ、SQLAlchemy）
tests/                       テスト
contracts/                   Control Planeから取り込んだOpenAPI（契約の正本の写し）
docs/DetailDesign/           SDK仕様書
docs/サンプルアプリ機能一覧.md  疎通確認用サンプルアプリの機能一覧
docs/サンプルアプリ開発手順書.md  同アプリの作成順序
docs/サンプルアプリシステム構成図.md  同アプリの配置と通信経路
docs/サンプルアプリ結合試験項目書.md  同アプリを使うDEV結合試験の入力、順序、期待結果、証跡
deployment/                  DEV環境での疎通確認用サンプルProduct Serviceの構築・削除資材

deployment/は配布物に含めません。手順はサンプルProduct Serviceデプロイ手順に定めます。

主な公開インターフェースを次に示します。詳細はProduct Service SDK仕様書に定めます。

wonderfish_cpのimportはextraを必要としません。wonderfish_cp.inbound、wonderfish_cp.external、wonderfish_cp.testingはextra inboundを、wonderfish_cp.adapters.sqlalchemyはextra sqlalchemyを必要とします。

契約の正本はcontracts/README.mdが示すControl Planeリポジトリの2つのOpenAPIです。本リポジトリのcontracts/はその写しであり、手で編集しません。

前提

開発者はPython 3.12を使用します。

導入

Product Serviceは、Public PyPIからversionを固定して取得します。範囲指定にしません。連携仕様の変更をSDKのversion更新として検知するためです。

pip install "wonderfish-cp-sdk[inbound,sqlalchemy]==7.1.0"

extraのinboundはPS-inbound routerに、sqlalchemyは保存先Portの参照実装に必要です。組み込み手順はProduct Service SDK仕様書6章に定めます。

Python 3.12以上を使用します。versionの意味はProduct Service SDK仕様書18章に定めます。

セキュリティ上の問題の連絡

脆弱性または秘密情報の露出を発見した場合は、公開のIssueへ詳細を書かず、support@happyhack.co.jpへ連絡してください。

本SDKはApache License 2.0で提供します。ライセンス本文は配布wheelに含まれます。

ローカル検証

開発者はリポジトリルートで次を実行します。

python -m pip install --require-hashes -r requirements-dev.lock
python -m ruff check src tests deployment .github/scripts
python -m compileall -q src tests deployment .github/scripts
python -m pytest
python -m pip install -e . "uvicorn[standard]"
python deployment/sample/smoke.py

テストはネットワーク、外部データベース、コンテナのいずれも必要としません。SQLAlchemy adapterの契約テストは一時ディレクトリのSQLiteファイルを使用します。

Control Plane側の前提

SDKをリリースする前に、Control Planeが満たしていなければならない条件はProduct Service SDK仕様書19章に定めます。

7.1.0はAgentツール接続候補を含む41 operation版です。contracts/に取り込んだControl PlaneのOpenAPIを正本とし、契約にない要求・応答をSDK側で補完しません。