zeus-sdk 0.2.0__tar.gz

zeus_sdk-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.zeus/
+models/
+examples/output/
+.DS_Store
+
+/output/

zeus_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,135 @@
+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` と合成データの利用例を含めています。

zeus_sdk-0.2.0/README-PYPI.md

@@ -0,0 +1,103 @@
+# 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` と合成データの利用例を含めています。

zeus_sdk-0.2.0/docs/api.md

@@ -0,0 +1,183 @@
+# 公開APIの使い方（0.2.0）
+
+配布名は`zeus-sdk`、Pythonパッケージ名は`zeus_sdk`です。インストール後は`.py`とJupyter Notebookから同じAPIを呼び出します。
+
+## 基本の流れ
+
+```mermaid
+flowchart TD
+    A[DatasetSchemaと目標・採用基準を設定] --> B[Task.validate / profile]
+    B --> C[Task.optimize]
+    C --> D{実行状態}
+    D -->|目標達成| E[Task.finalize: 未使用データで一度だけ評価]
+    D -->|追加データ必要| F[理由と取得項目を確認]
+    D -->|予算・中断・失敗| G[候補と履歴を確認]
+    E --> H{利用者の判断}
+    H -->|保留・不採用| I[Task.record_decision]
+    H -->|基準合格後に採用| J[Task.adopt]
+    J --> K[ModelStore.save / load]
+    K --> L[model.predict / explain]
+```
+
+## 設定
+
+| 設定 | 用途 |
+| --- | --- |
+| `DatasetSchema(features, target, id_column="id", time_column=None, group_column=None, positive_label=1, required_features=(), excluded_features=())` | 入力候補列、正解列、行ID、系列の時刻・区切り、分類の正例、必須・除外列を明示 |
+| `GoalConfig(metric, target, direction)` | 検証目標または最終採用基準。`direction="le"`は以下、`"ge"`は以上 |
+| `SplitConfig(train_fraction=.6, validation_fraction=.2, strategy="chronological", gap_rows=0, gap_seconds=0)` | 残りを最終評価へ固定。`group`は系列単位、`random`は利用者が独立同分布を判断した場合のみ |
+| `CandidateConfig(candidate_id, parameters={}, features=None, alpha=1., threshold=.5)` | 方式、方式別パラメータ、候補列、Ridge強度／Logisticの逆正則化に対応する値、分類閾値 |
+| `ExperimentConfig(goal, candidates, split=..., max_trials=10, time_limit_seconds=300., seed=42, acceptance=None)` | 有限の改善候補集合と実行上限。最終評価前に`acceptance`の指定が必要 |
+| `TargetConfig(mode="direct", horizon_rows=0, base_column=None)` | 排水回帰の`delta`指定では、各系列の指定行数先の正解から現在基準値を引いて学習。基準値と正解には別の列を指定 |
+
+学習時だけに決めた成型・列選択を推論にも使います。未来にしか取得できない値を入力列に入れないことは、データを渡す利用者の責任です。センサー名から取得可能時刻を推測する機能はありません。
+
+## タスクと戻り値
+
+`WastewaterTask(schema, target=None, project_root=".")`は回帰、`PartDefectTask(schema, project_root=".")`は二値分類です。名前以外の業種判定はなく、同じ入力・目的変数の契約を満たせば他分野でも利用できます。多クラス分類・画像の自動特徴抽出はこの版の対象外です。
+
+| 呼出し | 戻り値・効果 |
+| --- | --- |
+| `task.validate(frame, mode="TRAIN")` | `ValidationReport.valid`と`issues`。予測前は`mode="PREDICT"`で正解列不要 |
+| `task.profile(data)` | `ProfileResult.tables`と`metadata`。`export(path, plots=True)`でCSV・PNGを出力（plotsは任意依存） |
+| `task.optimize(data, config, cancellation=None, data_need_policy=None)` | `RunResult`。`status`, `reason`, `trials`, `goal_candidate`, `best_candidate`, `best_qrc_candidate`, `evaluation_context` |
+| `task.finalize(run.goal_candidate, run.evaluation_context)` | `FinalizationResult`。校正なしは学習＋検証で再学習。校正・閾値選択ありは基底モデルを学習側、校正を検証側に分離したまま再構成し、最終評価。`metrics`と`acceptance_passed`を確認 |
+| `task.record_decision(final, "held", "理由")` | 保留。`"rejected"`で不採用。過去の判断は削除しない |
+| `task.adopt(final)` | 基準に合格した最終評価済みモデルを返し、採用判断を記録。設備の運用切替えは行わない |
+
+状態は`GOAL_MET`、`NEEDS_DATA`、`BUDGET_EXHAUSTED`、`CANCELLED`、`FAILED`です。探索候補の枯渇は`FAILED`／`SEARCH_EXHAUSTED`であり、センサー不足と決めつけません。時間上限と中断は試行間と学習・前処理・予測・評価の段階間で確認し、実行中の数値計算を強制終了する保証はありません。
+
+`cancellation`は標準の`CancellationToken`、引数なしの関数、`requested`属性／メソッド、または`is_set()`を持つオブジェクトを受け付けます。状態はPythonの`bool`で返します。複数の形式を持つ場合は、関数呼出し、`requested`、`is_set()`の順に判定します。OWLと試行内は同じ判定関数を使い、非対応の形式や真偽値以外の戻り値は`TypeError`で通知します。
+
+追加情報の判断を渡す例:
+
+```python
+from zeus_sdk import DataNeedDecision
+
+def policy(history):
+    # 業務上の根拠に応じて選ぶ。以下は形式の説明用。
+    return DataNeedDecision(
+        status="required", reason="検査担当者が上流温度の欠測を確認したため",
+        evidence={"source": "検査記録のIDをここに指定"},
+        required_items=["上流温度の測定値"],
+    )
+# run = task.optimize(data, config, data_need_policy=policy)
+```
+
+根拠・取得項目を指定しない`required`や不正な戻り値は実行失敗として記録します。
+
+## モデルの保存・利用
+
+```python
+from zeus_sdk import ModelStore
+
+# model = task.adopt(final)
+# store = ModelStore()
+# store.save(model, "models/accepted.zeusmodel")
+# model = store.load("models/accepted.zeusmodel", project_root="receiving-project")
+# prediction = model.predict(incoming, batch_size=256)
+# prediction.frame.to_csv("predictions.csv", index=False)
+# explanation = model.explain(incoming)
+# if explanation.status == "SUCCESS":
+#     explanation.export("explanation", plots=True)
+```
+
+保存物に作成元の記録先を引き継ぎません。`load(..., project_root=...)`で復元先の推論履歴を記録します。省略すると復元モデルは記録先を持たず、実行記録を`PredictionBatch.execution`で返します。保存済みモデルは信頼する作成元のものだけを読み込んでください。Pythonのminor版・SDK・数値ライブラリ版が違う保存物は明示的に拒否します。
+
+`predict`のバッチ指定は読出し計算の分割です。QRC特徴量は全入力をメモリ内で計算します。`model.open_session("識別名")`では過去入力を再生し、複数回の入力で系列を継続します。`session.reset(history=...)`で履歴を入れ直し、`session.close()`で終了の実行記録を返します。バッチ内・前回入力・初期履歴をまたぐ時刻の逆転と重複を拒否します。一つのセッションは一つのgroupに固定されます。中断・失敗時には`SDKError.result`から完了行と実行情報を取り出せます。未完了行を推定値で埋めません。
+
+明示した初期履歴は、遅延特徴量の設定がない状態付きQRCでも再生します。`close()`の記録保存に失敗しても履歴を解放してセッションを閉じ、`SDKError(code="INFERENCE_RECORD_FAILED")`を返します。この場合の`result`は終了サマリーの`InferenceRecord`で、`environment.close_record_error`に記録失敗が残ります。再度の`close()`は同じサマリーを返し、記録の再試行は行いません。
+
+時間特徴量・状態付きQRCへ初期履歴を渡す場合は、`schema.time_column`が必要で、未指定ならセッション作成時に`INVALID_HISTORY`を返します。時間特徴量を使わない通常のridge/logisticは時刻列がなくてもセッションを使えます。その場合の初期履歴はID重複の検査に使い、履歴依存のない予測器へは渡しません。
+
+変化量モデルは現在観測時刻と行数先の予測を区別します。不規則系列の将来時刻を秒数へ換算しません。最終評価用に作成した正解では予測先時刻を検査しますが、将来の行の時刻が未知のオンライン入力にはその時刻を生成できません。
+
+SHAPは学習済み読出しの特徴空間を説明します。`metadata.output_space`を確認してください。分類の寄与はlog-odds、`predictions`はラベルと確率です。変化量モデルの寄与は差分、予測値は復元した絶対値です。
+
+## 復旧と制約
+
+Markdownの表示だけに失敗したときは`task.store.refresh_reports()`を使います。最終評価を再実行して直すことはしません。保存失敗と、保存は完了したが記録に失敗した状態は、エラーコード・`details.model_published`・`result`で区別します。
+
+目標達成候補と採用基準があり最終評価できるコンテキストは、その`Task`インスタンスのメモリ内に元データを保持します。中断・予算停止・失敗など最終評価できない実行では、Taskは学習・検証・最終評価の分割DataFrameを保持しません。試行の性質確認に必要な加工前プロファイルは返却した`RunResult`が所有し、結果を保持する間はそのメモリを使用します。プロセス再起動後に途中から再開するAPIはありません。完了結果と使用台帳はSQLiteに残りますが、コンテキストの再構築機能は未実装です。曖昧に中断した評価予約は再利用せず、新たな未使用データで実験を開始します。
+
+
+## 0.2で追加した設定と操作
+
+`DatasetSchema`は`column_map={元の列名:標準名}`、`dtypes`、`units`、`csv_encoding`、`datetime_format`、`time_zone`、`allowed_labels`、`label_time_column`、`target_time_column`を受け付けます。入力の日時を宣言したタイムゾーンで解釈してUTCに揃えます。`units`は宣言の記録と入力メタデータとの照合であり、数値から物理単位を推測しません。
+
+推論では、列名対応表に正解列や結果確定時刻の対応があっても、その入力列は不要です。必須の特徴量・ID・観測時刻・グループは引き続き検査し、元の列名と標準名が同時に存在する曖昧な入力は拒否します。
+
+```python
+plan = CandidateConfig(
+    "logistic",
+    preprocessing={"smoothing_window": 2},
+    feature_spec={"lags": [1, 2], "differences": [1], "rolling_windows": [3],
+                  "selection": "correlation", "top_k": 4},
+    calibration="isotonic", threshold_rule="f1",
+)
+```
+
+この外部成型・特徴量設定は`ridge`／`logistic`で使います。QRCはそれぞれの元実装が担当する成型・特徴量を使い、所有者が衝突する指定を拒否します。相関選択は学習データで決めます。検証・最終評価の履歴参照行は全候補の最大必要行数に合わせ、採点行を共通にします。`isotonic`／`f1`を使う分類では検証に両クラスが必要です。校正に使った検証値は候補選択用であり、独立な性能推定は未使用の最終評価で行います。
+
+| 操作 | 結果 |
+| --- | --- |
+| `task.compare(run)` | 回帰MAE／分類F1で条件が一致する試行を順位付け。全体最良とQRC内最良を別に返す |
+| `compare_trials(run.trials, metric="mae")` | 記録済みの指標定義・向き・評価行・条件と照合。不一致は比較不能として理由を返す |
+| `task.profile_trial(run, trial_id)` | 元の学習入力と、その試行で実際に得た読出し入力の性質を比較。HQRC完成予測器も、実際の読出し学習行列と行対応を確認して集計する |
+| `result.export(path, plots=True)` | 比較・性質確認のCSV、metadata.json、任意のPNG。`plots`依存が必要 |
+| `model.predict(inputs, history=prefix, batch_size=256, max_memory_bytes=...)` | 観測済みの過去履歴を特徴量計算に使う。履歴は採点・返却行に含めない |
+| `model.open_session("id", history=prefix)` | 過去履歴を再生して逐次予測。一括との一致を確認済み |
+| `task.join_observations(inputs, predictions, observations)` | 確認済み実測だけを`FeedbackResult.frame`へ。`rejected`と`pending`は理由付きで別に返す |
+| `resolve_candidate("periodic_hqrc")` | 対応タスク・方式版・ステージ担当・保存／セッション対応などの能力を確認 |
+
+履歴を必要とする特徴量では`history`を必ず渡し、各グループについて必要行数と時刻順を守ります。メモリ検査は入力・履歴・作業配列の概算とOSの利用可能メモリ、指定した上限を比較します。DataFrameは複製前、ファイルは読込前に概算し、読込後にも再検査します。超過は失敗として記録します。ファイルの事前概算はサイズ倍率による目安で、展開サイズやパーサーの使用量を強制制限しません。読込前に拒否したファイルは行数が未確定なので、実行記録の`input_count`を0とします。推定は実メモリ使用量の上限保証ではなく、他プロセスによる変化や元ライブラリの全ての一時領域までは予測できません。
+
+FeedbackSpatialと完成予測器3方式は、QRC生成前にも資源検査を行います。推定メモリ上限は512 MiBと空きメモリの4分の1の小さい方です（空き量取得不能時は512 MiB）。量子ビット数・virtual nodes・reservoir数から計算量と出力幅も制限します。これは極端な設定の早期拒否のための実装上の制限であり、OSによる強制メモリ上限や実行時間保証ではありません。元QRCの通常設定と計算手順は維持しています。
+
+実測照合では、入力に正解列を混ぜず、予測に`id`・`model_id`・`target_time`、実測に`id`・正解列・`target_time`・`label_source`（`measured`／`inspected`）・`confirmed_at`を渡します。予測値を実測の代わりには使いません。将来ラベルの照合結果は`TargetConfig(mode="delta", horizon_rows=..., base_column=..., label_alignment="prealigned")`と`DatasetSchema(target_time_column="target_time", ...)`で使います。照合結果の由来・確定時刻・対応済みマーカーを保持し、再度の行シフトを防ぎます。
+
+`periodic_hqrc`／`enhanced_hqrc`／`enhanced_hqrc_1_1`は、有限値の単一入力列と単一学習系列の回帰に対応します。`parameters`の`n_qubits`（3以上）・`dt`・`scale`・`para`、Enhancedの`alpha`・`bases`、1.1の`d_embed`・`tau`を明示できます。初期状態をseedで固定し、元の`fit`・`predict`・`kanf`を使います。新しい読出しを後付けしません。SHAPは完成予測器には非対応です。
+
+保存形式は0.2で`format_version=2`になり、学習／校正行、特徴量、候補版と担当、必要なQulacs版を記録します。0.1のアーカイブを0.2として読み替えません。旧環境で扱うか、新しい学習と未使用データの評価から作り直します。旧台帳にはID／時刻キーがないため、新しい版の再利用検査と同一の保護範囲にはなりません。
+
+実行可能な一連の例は[`examples/design_workflow.py`](../examples/design_workflow.py)と同名Notebookにあります。[設計・実装対応表](design-implementation.md)に章別の実装と制約を記録しています。
+
+
+OWLの範囲は`ExperimentConfig.allowed_changes={"alpha": [0.1, 1.0], ...}`で候補設定の許可値をさらに絞れます。既定では列挙した全候補が対象です。改善方針は履歴から次に試す段階を選び、その段階に合う未試行候補だけをAutoMLへ渡します。有限候補内の決定規則であり、業務原因を診断したという意味ではありません。試す段階、規則版、参照した試行、実際の変更を履歴に残します。
+
+
+## 追加情報判定と実行コンテキストの解放
+
+`DataNeedRule`と`ThresholdDataNeedPolicy`は利用者が指定した数値条件を検証結果・試行診断へ適用します。業務上の閾値は自動で決めません。例えば合成例で「学習行数が25未満なら実測データ追加」と決める場合:
+
+```python
+from zeus_sdk import DataNeedRule, ThresholdDataNeedPolicy
+policy = ThresholdDataNeedPolicy((DataNeedRule(
+    "minimum-training-demo", "diagnostics.postprocessed_profile.metadata.rows",
+    "lt", 25, "required", "例示の学習件数条件を満たしていないため",
+    ("追加の実測・検査済み学習データ",),
+),))
+# run = task.optimize(data, config, data_need_policy=policy)
+```
+
+ルールは宣言順で評価します。途中の根拠が欠ける場合は後続の許可ルールへ進まず`undetermined`とします。候補枯渇や精度未達だけで、センサー不足とは判定しません。
+
+`task.release_run(run)`は、そのTaskが保持する実行コンテキストを解放します。返値は解放時`True`、既にない場合`False`です。解放後はそのrunの`finalize`・`profile_trial`を呼べません。必要な最終評価・プロファイル出力が済んでから呼んでください。既に取得した最終結果・モデル、ディスク上の履歴、最終評価データの使用台帳は保持されます。`RunResult`やモデルを呼出し元が保持している場合、そのメモリまでは解放しません。
+
+同一Task・推論セッションへの操作は直列に実行してください。`release_run`を最終評価中に呼ばないでください。FeedbackSpatialの元実装はプロセス全体のBLASスレッド設定を一時変更します。ホストとBLAS設定を独立させる必要がある場合は別プロセスで実行してください。SDKはホストの数値処理との並行動作や強制停止を保証するものではありません。
+
+開発環境の検証コマンド:
+
+```bash
+python -m pytest
+python scripts/verify_notebooks.py --output notebook-results
+python scripts/verify_resources.py --cycles 1000 --release-runs --output resource-results.json
+```
+
+Notebook検証は実際のJupyterカーネルを使います。Colabの検証とは別です。資源検証は合成データと有限回の実測で、長時間運用のメモリ上限やリーク不存在を保証しません。
+
+### 履歴生成時のメモリと復旧
+
+履歴の表示は確定した順序番号までを16件ずつ読み、一時SQLiteにペイロードと索引を置いてMarkdownを逐次生成します。生成中も元DBの読込み接続をページごとに閉じます。履歴全文や全件索引をPythonのメモリに保持しませんが、単一ペイロード・読込みページ・SQLiteの作業領域は必要です。プロセス全体のメモリ上限保証ではなく、履歴に応じて一時ディスク使用量と生成時間は増えます。公開`RunStore.events()`は従来どおり全イベントのリストを返します。
+
+Markdownはファイル単位で原子的に置換します。2ファイルの同時更新保証はないため、表示失敗時は確定順序番号を確認し、`refresh_reports()`で再生成してください。実行・評価をやり直して復旧しないでください。

zeus_sdk-0.2.0/examples/design_workflow.ipynb

@@ -0,0 +1,94 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# ZEUS SDK 0.2 詳細設計の動作例\n",
+        "合成データによる校正・レポート・保存・逐次予測・実測照合の確認。業務精度の実証ではありません。SDKをインストールしてから実行します。"
+      ],
+      "id": "fb9978fd0095"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": [
+        "\"\"\"Synthetic 0.2 design workflow; no manufacturing accuracy claim.\"\"\"\n",
+        "from pathlib import Path\n",
+        "from uuid import uuid4\n",
+        "import numpy as np\n",
+        "import pandas as pd\n",
+        "from zeus_sdk import (CandidateConfig, DatasetSchema, ExperimentConfig, GoalConfig,\n",
+        "                      ModelStore, PartDefectTask)\n",
+        "\n",
+        "\n",
+        "def sample(start, count):\n",
+        "    rows = np.arange(start, start + count)\n",
+        "    x = np.sin(rows / 3)\n",
+        "    return pd.DataFrame({\"id\": rows, \"time\": pd.date_range(\"2026-01-01\", periods=start + count, freq=\"h\")[start:],\n",
+        "                         \"x\": x, \"label\": (x > 0).astype(int)})\n",
+        "\n",
+        "\n",
+        "def main(output_root=None):\n",
+        "    project = Path(output_root or \"examples/output/design\") / uuid4().hex[:8]\n",
+        "    schema = DatasetSchema((\"x\",), \"label\", time_column=\"time\", allowed_labels=(0, 1), required_features=(\"x\",))\n",
+        "    task = PartDefectTask(schema, project_root=project)\n",
+        "    training = sample(0, 120)\n",
+        "    task.validate(training).raise_for_errors()\n",
+        "    task.profile(training).export(project / \"profiles\" / \"input\")\n",
+        "    plan = CandidateConfig(\"logistic\", feature_spec={\"lags\": [1], \"rolling_windows\": [3]},\n",
+        "                           calibration=\"isotonic\", threshold_rule=\"f1\")\n",
+        "    # Loose demo gates, not real acceptance criteria.\n",
+        "    config = ExperimentConfig(GoalConfig(\"f1\", 0., \"ge\"), (plan,), acceptance=GoalConfig(\"f1\", 0., \"ge\"))\n",
+        "    run = task.optimize(training, config)\n",
+        "    assert run.status == \"GOAL_MET\", run.reason\n",
+        "    task.compare(run).export(project / \"comparison\")\n",
+        "    task.profile_trial(run, run.goal_candidate.trial_id).export(project / \"profiles\" / \"selected\")\n",
+        "    final = task.finalize(run.goal_candidate, run.evaluation_context)\n",
+        "    task.record_decision(final, \"held\", \"Synthetic example: inspect final evaluation before adoption\")\n",
+        "    model = task.adopt(final)\n",
+        "    assert set(model.training_manifest[\"training_row_ids\"]).isdisjoint(model.calibration_manifest[\"calibration_row_ids\"])\n",
+        "    archive = ModelStore().save(model, project / \"accepted.zeusmodel\")\n",
+        "    restored = ModelStore().load(archive, project_root=project)\n",
+        "    # New observations have never been used by the final evaluation.\n",
+        "    future = sample(120, 20)\n",
+        "    inputs = future.drop(columns=\"label\")\n",
+        "    history = training.iloc[-2:].drop(columns=\"label\")\n",
+        "    prediction = restored.predict(inputs, history=history, batch_size=5)\n",
+        "    session = restored.open_session(\"new-production-session\", history=history)\n",
+        "    sequential = pd.concat([session.predict(inputs.iloc[:10]).frame, session.predict(inputs.iloc[10:]).frame], ignore_index=True)\n",
+        "    pd.testing.assert_frame_equal(prediction.frame, sequential)\n",
+        "    session.close()\n",
+        "    # These inspected labels are simulated fixture values, not measured evidence.\n",
+        "    observations = future[[\"id\", \"label\"]].assign(target_time=future.time,\n",
+        "        label_source=\"inspected\", confirmed_at=future.time + pd.to_timedelta(1, unit=\"min\"))\n",
+        "    feedback = task.join_observations(inputs, prediction, observations)\n",
+        "    assert feedback.ready and len(feedback.frame) == len(inputs)\n",
+        "    assert feedback.rejected.empty and feedback.pending.empty\n",
+        "    feedback.frame.to_csv(project / \"confirmed_feedback.csv\", index=False)\n",
+        "    prediction.frame.to_csv(project / \"predictions.csv\", index=False)\n",
+        "    print(f\"Verified calibration, reports, persistence, session replay and feedback: {ascii(str(project))}\")\n",
+        "    return project\n",
+        "\n",
+        "\n",
+        "main()\n"
+      ],
+      "id": "4b9402e9e2f2"
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.12"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

zeus_sdk-0.2.0/examples/design_workflow.py

@@ -0,0 +1,60 @@
+"""Synthetic 0.2 design workflow; no manufacturing accuracy claim."""
+from pathlib import Path
+from uuid import uuid4
+import numpy as np
+import pandas as pd
+from zeus_sdk import (CandidateConfig, DatasetSchema, ExperimentConfig, GoalConfig,
+                      ModelStore, PartDefectTask)
+
+
+def sample(start, count):
+    rows = np.arange(start, start + count)
+    x = np.sin(rows / 3)
+    return pd.DataFrame({"id": rows, "time": pd.date_range("2026-01-01", periods=start + count, freq="h")[start:],
+                         "x": x, "label": (x > 0).astype(int)})
+
+
+def main(output_root=None):
+    project = Path(output_root or "examples/output/design") / uuid4().hex[:8]
+    schema = DatasetSchema(("x",), "label", time_column="time", allowed_labels=(0, 1), required_features=("x",))
+    task = PartDefectTask(schema, project_root=project)
+    training = sample(0, 120)
+    task.validate(training).raise_for_errors()
+    task.profile(training).export(project / "profiles" / "input")
+    plan = CandidateConfig("logistic", feature_spec={"lags": [1], "rolling_windows": [3]},
+                           calibration="isotonic", threshold_rule="f1")
+    # Loose demo gates, not real acceptance criteria.
+    config = ExperimentConfig(GoalConfig("f1", 0., "ge"), (plan,), acceptance=GoalConfig("f1", 0., "ge"))
+    run = task.optimize(training, config)
+    assert run.status == "GOAL_MET", run.reason
+    task.compare(run).export(project / "comparison")
+    task.profile_trial(run, run.goal_candidate.trial_id).export(project / "profiles" / "selected")
+    final = task.finalize(run.goal_candidate, run.evaluation_context)
+    task.record_decision(final, "held", "Synthetic example: inspect final evaluation before adoption")
+    model = task.adopt(final)
+    assert set(model.training_manifest["training_row_ids"]).isdisjoint(model.calibration_manifest["calibration_row_ids"])
+    archive = ModelStore().save(model, project / "accepted.zeusmodel")
+    restored = ModelStore().load(archive, project_root=project)
+    # New observations have never been used by the final evaluation.
+    future = sample(120, 20)
+    inputs = future.drop(columns="label")
+    history = training.iloc[-2:].drop(columns="label")
+    prediction = restored.predict(inputs, history=history, batch_size=5)
+    session = restored.open_session("new-production-session", history=history)
+    sequential = pd.concat([session.predict(inputs.iloc[:10]).frame, session.predict(inputs.iloc[10:]).frame], ignore_index=True)
+    pd.testing.assert_frame_equal(prediction.frame, sequential)
+    session.close()
+    # These inspected labels are simulated fixture values, not measured evidence.
+    observations = future[["id", "label"]].assign(target_time=future.time,
+        label_source="inspected", confirmed_at=future.time + pd.to_timedelta(1, unit="min"))
+    feedback = task.join_observations(inputs, prediction, observations)
+    assert feedback.ready and len(feedback.frame) == len(inputs)
+    assert feedback.rejected.empty and feedback.pending.empty
+    feedback.frame.to_csv(project / "confirmed_feedback.csv", index=False)
+    prediction.frame.to_csv(project / "predictions.csv", index=False)
+    print(f"Verified calibration, reports, persistence, session replay and feedback: {ascii(str(project))}")
+    return project
+
+
+if __name__ == "__main__":
+    main()