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]==9.3.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ファイルを使用します。

HTTPモックへのローカル接続

9.3.0のWFCP_AUTH_MODE=localで、CPリポジトリの共有HTTPモックへ接続できます。必要な環境変数・公開APIは仕様書7.1を参照してください。通常のMI接続は既定のままです。

公開前の組み合わせは、SDKをpython -m build --wheel --no-isolationでビルドし、各ProductServiceの検証環境へpython -m pip install --no-deps /path/to/wonderfish_cp_sdk-9.3.0-py3-none-any.whlで導入して確認します。SDKの通常試験はネットワーク不要で、実HTTP／Dockerとの結合試験はProductService統合側で行います。

Control Plane側の前提

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

9.3.0は小数15桁ポイント・executorによる直接消費・Ownerによる未使用予約解放・worker向けBinding参照に対応する42 operation版です。Control Planeのmigration 0008以降を先に適用し、worker参照にはGET /internal/v1/runtime/bindingsを提供する環境を使用してください。通貨の既定はJPYです。業務DBと未配送要求の切り替えは仕様書10.6に従います。contracts/に取り込んだOpenAPIを正本とします。