indiciumforge-workflow 2.0.0__tar.gz

indiciumforge_workflow-2.0.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: indiciumforge-workflow
+Version: 2.0.0
+Summary: Workflow services for IndiciumForge: market gate, daily review, workflow chain.
+Author: IndiciumForge contributors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Cavaradossi/indiciumforge
+Project-URL: Repository, https://github.com/Cavaradossi/indiciumforge
+Project-URL: Documentation, https://github.com/Cavaradossi/indiciumforge/tree/master/docs
+Project-URL: Issues, https://github.com/Cavaradossi/indiciumforge/issues
+Project-URL: Changelog, https://github.com/Cavaradossi/indiciumforge/blob/master/RELEASE_NOTES.md
+Keywords: workflow,market-gate,research,audit,open-core
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: indiciumforge-core<3.0.0,>=2.0.0
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tabulate>=0.9
+
+# indiciumforge-workflow
+
+Workflow services (market gate, daily review, workflow chain) for [IndiciumForge](https://github.com/Cavaradossi/indiciumforge).
+
+Research audit workflows only — not investment advice, not live trading.
+
+## Install
+
+PyPI publish is pending. Install from the monorepo (requires `indiciumforge-core`):
+
+```bash
+pip install -e packages/indiciumforge-core -e packages/indiciumforge-workflow
+```
+
+See [docs/PYPI_RELEASE_CHECKLIST.md](https://github.com/Cavaradossi/indiciumforge/blob/master/docs/PYPI_RELEASE_CHECKLIST.md).

indiciumforge_workflow-2.0.0/README.md

@@ -0,0 +1,15 @@
+# indiciumforge-workflow
+
+Workflow services (market gate, daily review, workflow chain) for [IndiciumForge](https://github.com/Cavaradossi/indiciumforge).
+
+Research audit workflows only — not investment advice, not live trading.
+
+## Install
+
+PyPI publish is pending. Install from the monorepo (requires `indiciumforge-core`):
+
+```bash
+pip install -e packages/indiciumforge-core -e packages/indiciumforge-workflow
+```
+
+See [docs/PYPI_RELEASE_CHECKLIST.md](https://github.com/Cavaradossi/indiciumforge/blob/master/docs/PYPI_RELEASE_CHECKLIST.md).

indiciumforge_workflow-2.0.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "indiciumforge-workflow"
+version = "2.0.0"
+description = "Workflow services for IndiciumForge: market gate, daily review, workflow chain."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "IndiciumForge contributors" }]
+keywords = ["workflow", "market-gate", "research", "audit", "open-core"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  "indiciumforge-core>=2.0.0,<3.0.0",
+  "pandas>=2.0",
+  "pyyaml>=6.0",
+  "tabulate>=0.9",
+]
+
+[project.urls]
+Homepage = "https://github.com/Cavaradossi/indiciumforge"
+Repository = "https://github.com/Cavaradossi/indiciumforge"
+Documentation = "https://github.com/Cavaradossi/indiciumforge/tree/master/docs"
+Issues = "https://github.com/Cavaradossi/indiciumforge/issues"
+Changelog = "https://github.com/Cavaradossi/indiciumforge/blob/master/RELEASE_NOTES.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]

indiciumforge_workflow-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

indiciumforge_workflow-2.0.0/src/indiciumforge_workflow/__init__.py

@@ -0,0 +1 @@
+"""Workflow services for IndiciumForge."""

indiciumforge_workflow-2.0.0/src/indiciumforge_workflow/e2e/__init__.py

@@ -0,0 +1 @@
+"""Synthetic end-to-end workflow orchestration."""

indiciumforge_workflow-2.0.0/src/indiciumforge_workflow/e2e/synthetic.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import json
+import shutil
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from indiciumforge_core.artifacts.manifest import (
+    validate_daily_review_stage,
+    validate_market_gate_stage,
+)
+from indiciumforge_core.artifacts.paths import (
+    daily_review_dir,
+    market_gate_stage_dir,
+    synthetic_e2e_summary_path,
+    workflow_root,
+)
+
+from indiciumforge_workflow.market_awareness.runner import run_daily_review_skeleton
+from indiciumforge_workflow.market_gate.runner import run_market_gate
+
+SYNTHETIC_E2E_SUMMARY_SCHEMA = "indiciumforge.synthetic_e2e_summary.v1"
+
+
+@dataclass(frozen=True)
+class SyntheticE2EResult:
+    trade_date: date
+    daily_review_stage_dir: Path
+    market_gate_stage_dir: Path
+    summary_path: Path
+    daily_review_audit_ok: bool
+    market_gate_audit_ok: bool
+    audit_ok: bool
+    warnings: tuple[str, ...]
+
+
+def _seed_preopen_review(
+    artifact_root: Path,
+    trade_date: date,
+    preopen_review_fixture: Path,
+) -> Path:
+    target_dir = workflow_root(artifact_root, trade_date) / "preopen"
+    target_dir.mkdir(parents=True, exist_ok=True)
+    target_path = target_dir / "buy_point_review_internal.csv"
+    shutil.copy2(preopen_review_fixture, target_path)
+    return target_path
+
+
+def _write_summary(
+    path: Path,
+    *,
+    trade_date: date,
+    daily_review_stage_dir: Path,
+    market_gate_stage_dir: Path,
+    daily_review_audit_ok: bool,
+    market_gate_audit_ok: bool,
+    daily_review_fixture: Path,
+    preopen_review_fixture: Path,
+    warnings: list[str],
+) -> None:
+    payload: dict[str, Any] = {
+        "schema": SYNTHETIC_E2E_SUMMARY_SCHEMA,
+        "trade_date": trade_date.isoformat(),
+        "provenance": {
+            "mode": "synthetic_e2e",
+            "fixtures": {
+                "daily_review": str(daily_review_fixture),
+                "preopen_review": str(preopen_review_fixture),
+            },
+        },
+        "stages": {
+            "daily_review": {
+                "dir": str(daily_review_stage_dir),
+                "audit_ok": daily_review_audit_ok,
+            },
+            "market_gate": {
+                "dir": str(market_gate_stage_dir),
+                "audit_ok": market_gate_audit_ok,
+            },
+        },
+        "audit_ok": daily_review_audit_ok and market_gate_audit_ok,
+        "warnings": warnings,
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8-sig")
+
+
+def run_synthetic_e2e(
+    *,
+    trade_date: date,
+    artifact_root: Path,
+    daily_review_fixture: Path,
+    preopen_review_fixture: Path,
+) -> SyntheticE2EResult:
+    if not daily_review_fixture.is_file():
+        raise FileNotFoundError(f"missing daily-review fixture: {daily_review_fixture}")
+    if not preopen_review_fixture.is_file():
+        raise FileNotFoundError(f"missing preopen review fixture: {preopen_review_fixture}")
+
+    warnings: list[str] = []
+    trade_date_iso = trade_date.isoformat()
+
+    _seed_preopen_review(artifact_root, trade_date, preopen_review_fixture)
+
+    daily_result = run_daily_review_skeleton(
+        trade_date=trade_date,
+        artifact_root=artifact_root,
+        fixture_path=daily_review_fixture,
+    )
+    warnings.extend(daily_result.warnings)
+
+    gate_result = run_market_gate(trade_date=trade_date, artifact_root=artifact_root)
+    warnings.extend(gate_result.warnings)
+
+    dr_stage_dir = daily_review_dir(artifact_root, trade_date)
+    mg_stage_dir = market_gate_stage_dir(artifact_root, trade_date)
+
+    daily_manifest = validate_daily_review_stage(
+        dr_stage_dir,
+        expected_trade_date=trade_date_iso,
+    )
+    gate_manifest = validate_market_gate_stage(
+        mg_stage_dir,
+        expected_trade_date=trade_date_iso,
+    )
+
+    daily_review_audit_ok = daily_manifest.ok
+    market_gate_audit_ok = gate_manifest.ok
+    audit_ok = daily_review_audit_ok and market_gate_audit_ok
+
+    summary_path = synthetic_e2e_summary_path(artifact_root, trade_date)
+    _write_summary(
+        summary_path,
+        trade_date=trade_date,
+        daily_review_stage_dir=dr_stage_dir,
+        market_gate_stage_dir=mg_stage_dir,
+        daily_review_audit_ok=daily_review_audit_ok,
+        market_gate_audit_ok=market_gate_audit_ok,
+        daily_review_fixture=daily_review_fixture,
+        preopen_review_fixture=preopen_review_fixture,
+        warnings=warnings,
+    )
+
+    return SyntheticE2EResult(
+        trade_date=trade_date,
+        daily_review_stage_dir=dr_stage_dir,
+        market_gate_stage_dir=mg_stage_dir,
+        summary_path=summary_path,
+        daily_review_audit_ok=daily_review_audit_ok,
+        market_gate_audit_ok=market_gate_audit_ok,
+        audit_ok=audit_ok,
+        warnings=tuple(warnings),
+    )

indiciumforge_workflow-2.0.0/src/indiciumforge_workflow/factor_scan/__init__.py

@@ -0,0 +1,11 @@
+from indiciumforge_workflow.factor_scan.runner import (
+    FactorScanStageConfig,
+    FactorScanStageResult,
+    run_factor_scan_stage,
+)
+
+__all__ = [
+    "FactorScanStageConfig",
+    "FactorScanStageResult",
+    "run_factor_scan_stage",
+]

indiciumforge_workflow-2.0.0/src/indiciumforge_workflow/factor_scan/runner.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+
+from indiciumforge_core.artifacts.paths import factor_scan_dir
+from indiciumforge_core.domain.models import AssetID
+from indiciumforge_core.factors.artifacts import write_factor_scan_bundle, write_factor_scan_state
+from indiciumforge_core.factors.pack import LoadedFactorPack, load_factor_pack
+from indiciumforge_core.factors.scan import FactorScanRunner
+from indiciumforge_core.providers.local_fixture import LocalFixtureProvider
+from indiciumforge_core.providers.registry import ProviderRegistry
+
+
+@dataclass(frozen=True)
+class FactorScanStageConfig:
+    pack_config: Path | None = None
+    detectors_config: Path | None = None
+    include_entry_points: bool = False
+    ohlcv_fixture_root: Path | None = None
+    asset_fixture_list: Path | None = None
+    assets: tuple[AssetID, ...] = ()
+    asset_universe_source: str = "fixture_asset_list"
+
+
+@dataclass(frozen=True)
+class FactorScanStageResult:
+    stage_dir: Path
+    pack: LoadedFactorPack
+    signal_count: int
+    detector_count: int
+    warnings: tuple[str, ...]
+
+
+def run_factor_scan_stage(
+    *,
+    trade_date: date,
+    artifact_root: Path,
+    config: FactorScanStageConfig,
+) -> FactorScanStageResult:
+    if not config.assets:
+        raise ValueError("factor scan stage requires at least one asset")
+
+    if config.ohlcv_fixture_root is None:
+        raise ValueError("factor scan stage requires ohlcv_fixture_root")
+
+    loaded = load_factor_pack(
+        pack_config=config.pack_config,
+        detectors_config=config.detectors_config,
+        include_entry_points=config.include_entry_points,
+    )
+    provider_registry = ProviderRegistry(
+        [LocalFixtureProvider(config.ohlcv_fixture_root)]
+    )
+    runner = FactorScanRunner(provider_registry, loaded.registry)
+    result = runner.scan(list(config.assets), trade_date)
+
+    stage_dir = factor_scan_dir(artifact_root, trade_date)
+    write_factor_scan_bundle(stage_dir, trade_date, result)
+    write_factor_scan_state(
+        stage_dir,
+        trade_date=trade_date,
+        pack_id=loaded.pack_id,
+        detector_names=loaded.registry.list_detectors(),
+        asset_universe_source=config.asset_universe_source,
+        signal_count=len(result.signals),
+        warning_count=len(result.warnings),
+    )
+
+    return FactorScanStageResult(
+        stage_dir=stage_dir,
+        pack=loaded,
+        signal_count=len(result.signals),
+        detector_count=len(loaded.registry.list_detectors()),
+        warnings=result.warnings,
+    )

indiciumforge_workflow-2.0.0/src/indiciumforge_workflow/market_awareness/__init__.py

@@ -0,0 +1,35 @@
+from indiciumforge_workflow.market_awareness.artifacts import (
+    THEME_STATE_RANKING_COLUMNS,
+    theme_state_rows_to_frame,
+    write_daily_review_state,
+    write_theme_state_ranking,
+)
+from indiciumforge_workflow.market_awareness.classifier import (
+    classify_theme_state,
+    classify_theme_states,
+)
+from indiciumforge_workflow.market_awareness.fixtures import (
+    ThemeFixtureLoadError,
+    load_theme_sector_fixture,
+)
+from indiciumforge_workflow.market_awareness.models import (
+    DailyReviewResult,
+    ThemeSectorMetrics,
+    ThemeStateRow,
+)
+from indiciumforge_workflow.market_awareness.runner import run_daily_review_skeleton
+
+__all__ = [
+    "DailyReviewResult",
+    "THEME_STATE_RANKING_COLUMNS",
+    "ThemeFixtureLoadError",
+    "ThemeSectorMetrics",
+    "ThemeStateRow",
+    "classify_theme_state",
+    "classify_theme_states",
+    "load_theme_sector_fixture",
+    "run_daily_review_skeleton",
+    "theme_state_rows_to_frame",
+    "write_daily_review_state",
+    "write_theme_state_ranking",
+]

indiciumforge_workflow-2.0.0/src/indiciumforge_workflow/market_awareness/artifacts.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import json
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+from indiciumforge_core.labels.market_gate import MARKET_DAILY, MARKET_ZH
+from indiciumforge_core.market.theme_rules import THEME_STATE_RULE_VERSION, THEME_STATE_RULES
+
+from indiciumforge_workflow.market_awareness.models import ThemeStateRow
+
+THEME_STATE_RANKING_COLUMNS: tuple[str, ...] = (
+    MARKET_ZH["theme_name"],
+    MARKET_DAILY["status"],
+    MARKET_DAILY["daily_state"],
+    MARKET_DAILY["mid_state"],
+    MARKET_DAILY["risk_state"],
+    MARKET_DAILY["divergence_state"],
+)
+
+
+def theme_state_rows_to_frame(rows: list[ThemeStateRow]) -> pd.DataFrame:
+    records = [
+        {
+            MARKET_ZH["theme_name"]: row.theme_name,
+            MARKET_DAILY["status"]: row.status,
+            MARKET_DAILY["daily_state"]: row.daily_state,
+            MARKET_DAILY["mid_state"]: row.mid_state,
+            MARKET_DAILY["risk_state"]: row.risk_state,
+            MARKET_DAILY["divergence_state"]: row.divergence_state,
+        }
+        for row in rows
+    ]
+    if not records:
+        return pd.DataFrame(columns=list(THEME_STATE_RANKING_COLUMNS))
+    return pd.DataFrame(records)
+
+
+def write_theme_state_ranking(path: Path, rows: list[ThemeStateRow]) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    frame = theme_state_rows_to_frame(rows)
+    frame.to_csv(path, index=False, encoding="utf-8-sig")
+    return path
+
+
+def write_daily_review_state(
+    path: Path,
+    *,
+    trade_date: date,
+    theme_state_ranking_path: Path,
+    fixture_name: str,
+    warnings: list[str] | None = None,
+) -> Path:
+    payload: dict[str, Any] = {
+        "schema": "indiciumforge.market_daily_review_state.v1",
+        "trade_date": trade_date.isoformat(),
+        "theme_state_rule_version": THEME_STATE_RULE_VERSION,
+        "theme_state_rules": dict(THEME_STATE_RULES),
+        "paths": {"theme_state_ranking": str(theme_state_ranking_path)},
+        "warnings": warnings or [],
+        "provenance": {
+            "source": "synthetic_fixture",
+            "fixture": fixture_name,
+        },
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8-sig")
+    return path

indiciumforge_workflow-2.0.0/src/indiciumforge_workflow/market_awareness/classifier.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from indiciumforge_core.labels.market_gate import MARKET_DAILY, MARKET_ZH
+from indiciumforge_core.market.theme_rules import THEME_STATE_RULES
+
+from indiciumforge_workflow.market_awareness.models import ThemeSectorMetrics, ThemeStateRow
+
+
+def classify_theme_state(
+    metrics: ThemeSectorMetrics,
+    rules: dict[str, float | int] | None = None,
+) -> ThemeStateRow:
+    rule_set = rules or THEME_STATE_RULES
+    neutral = MARKET_ZH["neutral_theme"]
+    no_risk = MARKET_DAILY["normal_risk"]
+    no_div = MARKET_DAILY["normal_divergence"]
+
+    if _is_hard_weak(metrics, rule_set):
+        hard_weak = MARKET_DAILY["hard_weak"]
+        return ThemeStateRow(
+            theme_name=metrics.theme_name,
+            status=hard_weak,
+            daily_state=MARKET_DAILY["daily_weak"],
+            mid_state=neutral,
+            risk_state=hard_weak,
+            divergence_state=no_div,
+        )
+
+    if _is_divergent(metrics, rule_set):
+        return ThemeStateRow(
+            theme_name=metrics.theme_name,
+            status=MARKET_DAILY["divergent"],
+            daily_state=MARKET_DAILY["daily_weak"],
+            mid_state=neutral,
+            risk_state=no_risk,
+            divergence_state=MARKET_DAILY["divergent"],
+        )
+
+    if _is_turn_weak(metrics, rule_set):
+        return ThemeStateRow(
+            theme_name=metrics.theme_name,
+            status=MARKET_DAILY["mid_strong_daily_weak"],
+            daily_state=MARKET_DAILY["daily_weak"],
+            mid_state=MARKET_DAILY["mid_strong"],
+            risk_state=no_risk,
+            divergence_state=no_div,
+        )
+
+    if _is_daily_strong(metrics, rule_set):
+        daily_strong = MARKET_DAILY["daily_strong"]
+        return ThemeStateRow(
+            theme_name=metrics.theme_name,
+            status=daily_strong,
+            daily_state=daily_strong,
+            mid_state=neutral,
+            risk_state=no_risk,
+            divergence_state=no_div,
+        )
+
+    return ThemeStateRow(
+        theme_name=metrics.theme_name,
+        status=neutral,
+        daily_state=MARKET_DAILY["daily_weak"],
+        mid_state=neutral,
+        risk_state=no_risk,
+        divergence_state=no_div,
+    )
+
+
+def classify_theme_states(
+    metrics_list: list[ThemeSectorMetrics],
+    rules: dict[str, float | int] | None = None,
+) -> list[ThemeStateRow]:
+    return [classify_theme_state(metrics, rules) for metrics in metrics_list]
+
+
+def _is_hard_weak(metrics: ThemeSectorMetrics, rules: dict[str, float | int]) -> bool:
+    if metrics.sample_count < int(rules["min_sample"]):
+        return False
+    return (
+        metrics.median_1d <= float(rules["hard_weak_max_1d_median"])
+        and metrics.up_rate <= float(rules["hard_weak_max_up_rate"])
+        and metrics.le_minus5_ratio >= float(rules["hard_weak_min_le_minus5_ratio"])
+        and metrics.limit_down_count >= int(rules["hard_weak_min_limit_down_count"])
+    )
+
+
+def _is_divergent(metrics: ThemeSectorMetrics, rules: dict[str, float | int]) -> bool:
+    if metrics.sample_count < int(rules["min_sample"]):
+        return False
+    return (
+        metrics.limit_up_count >= int(rules["divergent_min_limit_up_count"])
+        and metrics.ge5_ratio >= float(rules["divergent_min_ge5_ratio"])
+        and metrics.median_1d <= float(rules["divergent_max_1d_median"])
+        and metrics.up_rate <= float(rules["divergent_max_up_rate"])
+        and metrics.le_minus5_ratio >= float(rules["divergent_min_le_minus5_ratio"])
+    )
+
+
+def _is_turn_weak(metrics: ThemeSectorMetrics, rules: dict[str, float | int]) -> bool:
+    if metrics.sample_count < int(rules["min_sample"]):
+        return False
+    mid_strong = metrics.median_3d >= float(rules["daily_strong_min_1d_median"])
+    return mid_strong and (
+        metrics.median_1d <= float(rules["turn_weak_max_1d_median"])
+        and metrics.up_rate <= float(rules["turn_weak_max_up_rate"])
+        and metrics.le_minus5_ratio >= float(rules["turn_weak_min_le_minus5_ratio"])
+    )
+
+
+def _is_daily_strong(metrics: ThemeSectorMetrics, rules: dict[str, float | int]) -> bool:
+    min_sample = int(rules["strong_min_sample"])
+    if metrics.sample_count < min_sample:
+        return False
+    return (
+        metrics.median_1d >= float(rules["daily_strong_min_1d_median"])
+        and metrics.relative_1d >= float(rules["daily_strong_min_relative_1d"])
+        and metrics.up_rate >= float(rules["daily_strong_min_up_rate"])
+        and metrics.ge5_ratio >= float(rules["daily_strong_min_ge5_ratio"])
+        and metrics.limit_up_count >= int(rules["daily_strong_min_limit_up_count"])
+    )

indiciumforge_workflow-2.0.0/src/indiciumforge_workflow/market_awareness/fixtures.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from indiciumforge_workflow.market_awareness.models import ThemeSectorMetrics
+
+
+class ThemeFixtureLoadError(ValueError):
+    """Raised when a theme sector fixture cannot be parsed."""
+
+
+def load_theme_sector_fixture(path: Path) -> tuple[date, list[ThemeSectorMetrics]]:
+    payload = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ThemeFixtureLoadError("fixture root must be a mapping")
+
+    trade_date_raw = payload.get("trade_date")
+    if not trade_date_raw:
+        raise ThemeFixtureLoadError("fixture requires trade_date")
+    trade_date = date.fromisoformat(str(trade_date_raw))
+
+    themes = payload.get("themes")
+    if not isinstance(themes, list) or not themes:
+        raise ThemeFixtureLoadError("fixture requires non-empty themes list")
+
+    metrics: list[ThemeSectorMetrics] = []
+    for index, entry in enumerate(themes):
+        if not isinstance(entry, dict):
+            raise ThemeFixtureLoadError(f"theme entry {index} must be a mapping")
+        metrics.append(_parse_theme_entry(entry, index))
+    return trade_date, metrics
+
+
+def _parse_theme_entry(entry: dict[str, Any], index: int) -> ThemeSectorMetrics:
+    theme_name = entry.get("theme_name")
+    if not theme_name:
+        raise ThemeFixtureLoadError(f"theme entry {index} missing theme_name")
+    required = ("sample_count", "median_1d", "median_3d", "up_rate")
+    for field in required:
+        if field not in entry:
+            raise ThemeFixtureLoadError(f"theme entry {index} missing {field}")
+    return ThemeSectorMetrics(
+        theme_name=str(theme_name),
+        sample_count=int(entry["sample_count"]),
+        median_1d=float(entry["median_1d"]),
+        median_3d=float(entry["median_3d"]),
+        up_rate=float(entry["up_rate"]),
+        relative_1d=float(entry.get("relative_1d", 0.0)),
+        ge5_ratio=float(entry.get("ge5_ratio", 0.0)),
+        le_minus5_ratio=float(entry.get("le_minus5_ratio", 0.0)),
+        limit_up_count=int(entry.get("limit_up_count", 0)),
+        limit_down_count=int(entry.get("limit_down_count", 0)),
+    )

indiciumforge_workflow-2.0.0/src/indiciumforge_workflow/market_awareness/models.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class ThemeSectorMetrics:
+    theme_name: str
+    sample_count: int
+    median_1d: float
+    median_3d: float
+    up_rate: float
+    relative_1d: float = 0.0
+    ge5_ratio: float = 0.0
+    le_minus5_ratio: float = 0.0
+    limit_up_count: int = 0
+    limit_down_count: int = 0
+
+
+@dataclass(frozen=True)
+class ThemeStateRow:
+    theme_name: str
+    status: str
+    daily_state: str
+    mid_state: str
+    risk_state: str
+    divergence_state: str
+
+
+@dataclass(frozen=True)
+class DailyReviewResult:
+    trade_date: date
+    rows: tuple[ThemeStateRow, ...]
+    warnings: tuple[str, ...] = ()
+    fixture_path: Path | None = None
+    theme_state_ranking_path: Path | None = None
+    state_path: Path | None = None