Metadata-Version: 2.4
Name: wonderfish-cp-sdk
Version: 5.0.0
License-Expression: Apache-2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: azure-identity<2,>=1.25.3
Requires-Dist: httpx<1,>=0.28
Requires-Dist: pydantic<3,>=2.13.4
Requires-Dist: pyjwt[crypto]<3,>=2.13.0
Provides-Extra: inbound
Requires-Dist: fastapi<1,>=0.141.1; extra == "inbound"
Provides-Extra: sqlalchemy
Requires-Dist: sqlalchemy<3,>=2.0; extra == "sqlalchemy"
Provides-Extra: dev
Requires-Dist: build==1.6.0; extra == "dev"
Requires-Dist: jeepney==0.9.0; sys_platform == "linux" and extra == "dev"
Requires-Dist: jsonschema==4.26.0; extra == "dev"
Requires-Dist: pip-audit==2.10.1; extra == "dev"
Requires-Dist: python-multipart<1,>=0.0.20; extra == "dev"
Requires-Dist: pytest<10,>=9.1.1; extra == "dev"
Requires-Dist: ruff==0.15.20; extra == "dev"
Requires-Dist: setuptools==83.0.0; extra == "dev"
Requires-Dist: secretstorage==3.5.0; sys_platform == "linux" and extra == "dev"
Requires-Dist: twine==7.0.0; extra == "dev"
Dynamic: license-file

# hh-wonderfish-ai-sdk

## 文書概要

| 項目 | 内容 |
|---|---|
| 目的 | Product ServiceがWonderfish Control Planeと連携するためのPythonライブラリ`wonderfish-cp-sdk`の、取得方法、ローカル検証手順、リポジトリ構成を示す |
| 対象読者 | SDKの開発者、SDKを組み込むProduct Serviceの開発者、レビュー担当者 |
| 対象範囲 | 本リポジトリのPythonソース、テスト、契約文書、設計書 |
| 対象外 | Control Plane本体の実装、各Product Service本体の実装、Azureへのデプロイ、Secret値 |

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

## ディレクトリ

```text
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/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デプロイ手順](<./deployment/docs/サンプルProduct Serviceデプロイ手順.md>)に定めます。

主な公開インターフェースを次に示します。詳細は[Product Service SDK仕様書](<./docs/DetailDesign/Product Service SDK仕様書.md>)に定めます。

| 用途 | 入口 | 仕様書 |
|---|---|---|
| Control Planeの呼び出し（36 operation） | `ControlPlaneClient` | 9章 |
| Integration App、Identity、API Role Assignmentの管理 | `ControlPlaneClient`の9 method | 5.3、9.2 |
| 認可から消費の確定まで | `ControlPlaneClient.authorize`、`AuthorizationSession` | 10章 |
| 外部API経路の消費 | `ControlPlaneClient.verify_decision`、`DecisionView.build_usage_fact` | 10.4 |
| Usage Factの送信 | `UsageFactSender` | 10.3 |
| Catalog snapshotと接続先の解決 | `CatalogCache` | 11章 |
| Control Planeからの5 endpoint | `wonderfish_cp.inbound.create_control_plane_router` | 12章 |
| 通知のハンドラ | `wonderfish_cp.inbound.NotificationRouter` | 13章 |
| 外部APIの認証・認可 | `wonderfish_cp.external.ExternalAuthorizationMiddleware` | 8.4 |
| 保存先 | `wonderfish_cp.ports`の4 Protocol、`wonderfish_cp.adapters` | 14章 |
| 準備完了の報告と起動時検査 | `ReadinessReporter`、`wonderfish_cp.conformance` | 6.2、6.3 |
| 試験用のControl Plane | `wonderfish_cp.testing.FakeControlPlane` | 17章 |

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

契約の正本は[contracts/README.md](./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]==5.0.0"
```

extraの`inbound`はPS-inbound routerに、`sqlalchemy`は保存先Portの参照実装に必要です。組み込み手順は[Product Service SDK仕様書](<./docs/DetailDesign/Product Service SDK仕様書.md>)6章に定めます。

Python 3.12以上を使用します。versionの意味は[Product Service SDK仕様書](<./docs/DetailDesign/Product Service SDK仕様書.md>)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仕様書](<./docs/DetailDesign/Product Service SDK仕様書.md>)19章に定めます。

19章のOpenAPI条件は、`contracts/`の取得時点ですべて満たされています。契約テストは取り込んだ文書をそのまま検査し、要求・応答の差を吸収しません。

先行・追随の関係にある項目はありません。
