Metadata-Version: 2.4
Name: zeus-sdk
Version: 0.2.0
Summary: ZEUS Python SDK for auditable QRC experiments, prediction, and model decisions
Keywords: machine-learning,quantum-reservoir-computing,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.11
Requires-Dist: filelock<4,>=3.13
Requires-Dist: numpy<3,>=1.24
Requires-Dist: pandas<3,>=2.2
Requires-Dist: psutil<8,>=5.9
Requires-Dist: scikit-learn<2,>=1.3
Requires-Dist: scipy<2,>=1.11
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: ipykernel<8,>=6; extra == 'dev'
Requires-Dist: nbclient<1,>=0.10; extra == 'dev'
Requires-Dist: nbformat<6,>=5; extra == 'dev'
Requires-Dist: pytest<10,>=8; extra == 'dev'
Requires-Dist: ruff<1,>=0.9; extra == 'dev'
Provides-Extra: explain
Requires-Dist: shap<1,>=0.45; extra == 'explain'
Provides-Extra: plots
Requires-Dist: matplotlib<4,>=3.8; extra == 'plots'
Provides-Extra: qrc
Requires-Dist: qulacs<0.7,>=0.6.14; extra == 'qrc'
Description-Content-Type: text/markdown

# ZEUS SDK

Pythonからデータの加工、学習、評価、予測、モデル保存を行うSDKです。
回帰・二値分類、量子リザバー計算（QRC）のCPUシミュレーター、
有限の候補を比較するOWL改善ループを提供します。

初期提供版です。対応範囲と制約を確認して利用してください。

## インストール

Python **3.11または3.12** の仮想環境を使用してください。

```bash
python -m pip install zeus-sdk
```

配布パッケージ名は `zeus-sdk`、Pythonで読み込む名前は `zeus_sdk` です。

```python
import zeus_sdk
print(zeus_sdk.__version__)
```

基本導入では回帰・二値分類の基準モデルとFeedbackSpatial／Residual QRCを利用できます。
追加機能は必要に応じて導入してください。

```bash
# PeriodicHQRC / EnhancedHQRC
python -m pip install "zeus-sdk[qrc]"

# SHAPによる対応モデルの説明、グラフ出力
python -m pip install "zeus-sdk[explain,plots]"

# すべての追加機能
python -m pip install "zeus-sdk[qrc,explain,plots]"
```

## 小さな回帰の例

合成データを用いたAPIの動作例です。実業務の精度を実証するものではありません。

```python
import numpy as np
import pandas as pd
from zeus_sdk import (
    WastewaterTask, DatasetSchema, CandidateConfig,
    ExperimentConfig, GoalConfig, ModelStore,
)

x = np.linspace(0, 10, 60)
data = pd.DataFrame({
    "id": np.arange(60),
    "time": pd.date_range("2026-01-01", periods=60, freq="h"),
    "sensor": x,
    "target": 2 * x + 1,
})
task = WastewaterTask(
    DatasetSchema(features=("sensor",), target="target", time_column="time"),
    project_root="zeus-example",
)
config = ExperimentConfig(
    goal=GoalConfig("mae", 100.0, "le"),
    acceptance=GoalConfig("mae", 100.0, "le"),
    candidates=(CandidateConfig("ridge"),),
    max_trials=1,
)
run = task.optimize(data, config)
print(run.status, run.reason)

if run.status == "GOAL_MET":
    final = task.finalize(run.goal_candidate, run.evaluation_context)
    if final.acceptance_passed:
        # この例の緩い基準で採用する操作。実業務では結果を確認して判断します。
        model = task.adopt(final)
        predictions = model.predict(data.drop(columns="target"))
        print(predictions.frame.head())
        # 既存ファイルの上書きは既定で拒否します。
        ModelStore().save(model, "zeus-example/model.zeusmodel")
```

同じ管理領域で最終評価済みのデータを再利用することは拒否します。
この例を最初から再実行するときは、新しい `project_root` と保存先を指定してください。

`project_root/reports/` に次のMarkdown履歴を作成します。

- `owl_improvement_history.md`: 試行、設定変更、検証結果、停止理由。
- `evaluated_model_history.md`: 最終評価、採用・保留・不採用の判断履歴。

分類は `PartDefectTask` を使います。用途別クラス名にかかわらず、対応する回帰・二値分類の入力契約を満たすデータを扱えます。入力の単位、正解ラベルの意味、採用基準は利用者が指定します。

## 対応範囲と制約

- `DataNeedRule`／`ThresholdDataNeedPolicy`で、明示した根拠と閾値に基づく追加情報判定を設定できます。
- OWLは許可された候補を比較します。目標達成、追加情報要求、予算上限、中断、失敗を区別します。
- 学習・検証・最終評価を分離し、予測値を正解ラベルとして扱いません。
- 量子実機バックエンドは未実装です。QRC候補はCPUシミュレーターです。
- 完成予測器のHQRC候補は単一入力系列の回帰に対応します。すべてのQRCがすべてのタスク・説明方式に対応するわけではありません。
- メモリ検査は概算です。一定メモリのストリーミング、OSのメモリ上限、ネイティブ計算の強制中断は保証しません。
- `task.release_run(run)`で不要になった実行コンテキストを解放できます。解放後はそのrunの最終評価・試行プロファイルを呼べません。
- モデル保存物はpickleを含みます。信頼できる作成元のものだけを読み込んでください。
- 対応するSDK・Python・依存ライブラリの版を確認して保存物を読み込みます。

ソース配布には `docs/api.md` と合成データの利用例を含めています。
