ZEUS SDK

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

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

インストール

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

python -m pip install zeus-sdk

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

import zeus_sdk
print(zeus_sdk.__version__)

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

# 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の動作例です。実業務の精度を実証するものではありません。

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 と合成データの利用例を含めています。