zeus-sdk 0.2.0__py3-none-any.whl

zeus_sdk/__init__.py

@@ -0,0 +1,25 @@
+"""ZEUS SDK public API. Optional scientific backends are imported on use."""
+from importlib import import_module
+
+__version__ = "0.2.0"
+_exports = {
+    **{n: "config" for n in ("DatasetSchema", "GoalConfig", "SplitConfig", "CandidateConfig", "ExperimentConfig", "TargetConfig")},
+    **{n: "contracts" for n in ("DataNeedDecision", "RunResult", "FinalizationResult", "AdoptionDecision", "PredictionBatch", "MetricValue", "EvaluationResult", "ValidationReport")},
+    "Task": "tasks", "WastewaterTask": "tasks", "PartDefectTask": "tasks",
+    "CancellationToken": "owl", "ModelStore": "persistence", "RunStore": "persistence",
+    "evaluate": "evaluation.metrics", "SDKError": "errors",
+    "join_observations": "data.feedback", "FeedbackResult": "data.feedback",
+    "compare_trials": "reporting.comparison", "ComparisonResult": "reporting.comparison",
+    "compare_profiles": "reporting.profiling", "export_report": "reporting.export",
+    "resolve_candidate": "qrc.registry", "AutoMLSearch": "automl.search",
+    "DataNeedRule": "owl.data_need", "ThresholdDataNeedPolicy": "owl.data_need",
+}
+__all__ = list(_exports)
+
+
+def __getattr__(name):
+    if name not in _exports:
+        raise AttributeError(name)
+    value = getattr(import_module(f".{_exports[name]}", __name__), name)
+    globals()[name] = value
+    return value

zeus_sdk/automl/__init__.py

@@ -0,0 +1,3 @@
+from .search import AutoMLSearch, SEARCH_ALGORITHM_VERSION, configuration_key
+
+__all__ = ["AutoMLSearch", "SEARCH_ALGORITHM_VERSION", "configuration_key"]

zeus_sdk/automl/search.py

@@ -0,0 +1,117 @@
+"""Finite search over configurations explicitly supplied by the experiment."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import math
+from typing import Any, Iterable
+
+
+SEARCH_ALGORITHM_VERSION = "finite_configured_candidates_v1"
+
+
+def _payload(plan: object) -> dict[str, Any]:
+    from dataclasses import asdict, is_dataclass
+
+    if isinstance(plan, dict):
+        return dict(plan)
+    return asdict(plan) if is_dataclass(plan) else dict(vars(plan))
+
+
+def configuration_key(plan: object, *, seed: int | None = None,
+                      split_id: str | None = None) -> str:
+    """Identify the candidate and the experiment conditions that affect a trial."""
+    return json.dumps({"plan": _payload(plan), "seed": seed, "split_id": split_id},
+                      sort_keys=True, default=str, ensure_ascii=False)
+
+
+def _distance(left: object, right: object) -> float:
+    if isinstance(left, dict) and isinstance(right, dict):
+        return sum(_distance(left.get(key), right.get(key)) for key in set(left) | set(right))
+    if isinstance(left, (list, tuple)) and isinstance(right, (list, tuple)):
+        return sum(_distance(a, b) for a, b in zip(left, right)) + abs(len(left) - len(right))
+    if (isinstance(left, (int, float)) and not isinstance(left, bool) and
+            isinstance(right, (int, float)) and not isinstance(right, bool)):
+        if math.isfinite(left) and math.isfinite(right):
+            return abs(math.asinh(left) - math.asinh(right))
+    return 0.0 if left == right else 1.0
+
+
+@dataclass(frozen=True)
+class SearchChoice:
+    plan: object
+    key: str
+    algorithm_version: str = SEARCH_ALGORITHM_VERSION
+
+
+class AutoMLSearch:
+    """Choose an untried allowed plan; policy cannot extend this allowed set.
+
+    The first plan follows declaration order. Later plans are nearest to the
+    best observed configuration, with declaration order breaking ties.
+    """
+
+    def __init__(self, allowed_plans: Iterable[object] = (), *, seed: int | None = None,
+                 split_id: str | None = None,
+                 allowed_changes: dict[str, object] | None = None):
+        self.seed = seed
+        self.split_id = split_id
+        self._allowed: list[SearchChoice] = []
+        seen = set()
+        for plan in allowed_plans:
+            if not self._permitted(plan, allowed_changes):
+                continue
+            key = configuration_key(plan, seed=seed, split_id=split_id)
+            if key not in seen:
+                self._allowed.append(SearchChoice(plan, key))
+                seen.add(key)
+
+    @property
+    def allowed_count(self) -> int:
+        return len(self._allowed)
+
+    @staticmethod
+    def _permitted(plan: object, allowed_delta: dict[str, object] | None) -> bool:
+        if not allowed_delta:
+            return True
+        payload = _payload(plan)
+        for field, allowed in allowed_delta.items():
+            if field not in payload:
+                return False
+            options = allowed if isinstance(allowed, (tuple, list, set)) else (allowed,)
+            if payload[field] != allowed and payload[field] not in options:
+                return False
+        return True
+
+    def available_choices(self, tried_keys: Iterable[str] = (), *,
+                          allowed_delta: dict[str, object] | None = None) -> tuple[SearchChoice, ...]:
+        tried = set(tried_keys)
+        return tuple(choice for choice in self._allowed
+                     if choice.key not in tried and self._permitted(choice.plan, allowed_delta))
+
+    def next_plan(self, proposal: object | None = None, tried_keys: Iterable[str] = (),
+                  *, best_plan: object | None = None) -> SearchChoice | None:
+        # A policy proposal explains the target; it cannot add forbidden values.
+        allowed_delta = getattr(proposal, "allowed_delta", None)
+        untried = list(self.available_choices(tried_keys, allowed_delta=allowed_delta))
+        allowed_plan_keys = getattr(proposal, "allowed_plan_keys", None)
+        if allowed_plan_keys is not None:
+            keys = set(allowed_plan_keys)
+            untried = [choice for choice in untried if choice.key in keys]
+        if not untried:
+            return None
+        if best_plan is None:
+            return untried[0]
+        reference = _payload(best_plan)
+        return min(untried, key=lambda choice: (
+            _distance(reference, _payload(choice.plan)),
+            self._allowed.index(choice)))
+
+    def select(self, remaining: list[object], best_plan: object | None = None) -> int:
+        """Compatibility for callers holding their own remaining-plan list."""
+        if best_plan is None:
+            return 0
+        reference = _payload(best_plan)
+        return min(range(len(remaining)), key=lambda index: (
+            _distance(reference, _payload(remaining[index])), index))

zeus_sdk/config.py

@@ -0,0 +1,168 @@
+"""Explicit, serializable experiment settings. No implicit production thresholds."""
+from dataclasses import dataclass, field
+import math
+from typing import Any
+
+from .errors import SDKError
+
+
+def invalid(message):
+    raise SDKError("INVALID_CONFIG", message)
+
+
+@dataclass(frozen=True)
+class DatasetSchema:
+    features: tuple[str, ...]
+    target: str
+    id_column: str = "id"
+    time_column: str | None = None
+    group_column: str | None = None
+    positive_label: Any = 1
+    required_features: tuple[str, ...] = ()
+    excluded_features: tuple[str, ...] = ()
+    column_map: dict[str, str] = field(default_factory=dict)
+    dtypes: dict[str, str] = field(default_factory=dict)
+    units: dict[str, str] = field(default_factory=dict)
+    csv_encoding: str = "utf-8"
+    datetime_format: str | None = None
+    time_zone: str = "UTC"
+    allowed_labels: tuple = ()
+    label_time_column: str | None = None
+    target_time_column: str | None = None
+
+    def __post_init__(self):
+        for name in ("features", "required_features", "excluded_features", "allowed_labels"):
+            object.__setattr__(self, name, tuple(getattr(self, name)))
+        if not self.features or len(set(self.features)) != len(self.features):
+            invalid("features must be nonempty and unique")
+        if not self.target or not self.id_column:
+            invalid("target and id_column are required")
+        if self.target in self.features or self.id_column in self.features:
+            invalid("target and ID cannot be input features")
+        if set(self.required_features) - set(self.features):
+            invalid("required_features must belong to features")
+        if set(self.required_features) & set(self.excluded_features):
+            invalid("required and excluded features conflict")
+        for name in ("column_map", "dtypes", "units"):
+            if not isinstance(getattr(self, name), dict):
+                invalid(f"{name} must be a mapping")
+        if len(set(self.column_map.values())) != len(self.column_map):
+            invalid("column_map destinations must be unique")
+        if not self.csv_encoding or not self.time_zone:
+            invalid("CSV encoding and time zone must be explicit")
+        if self.label_time_column in self.features or self.target_time_column in self.features:
+            invalid("Label availability and target times cannot be input features")
+
+
+@dataclass(frozen=True)
+class GoalConfig:
+    metric: str
+    target: float
+    direction: str
+
+    def __post_init__(self):
+        if self.direction not in ("le", "ge") or not math.isfinite(self.target):
+            invalid("goal requires finite target and direction le/ge")
+        if not self.metric:
+            invalid("goal metric is required")
+
+
+@dataclass(frozen=True)
+class SplitConfig:
+    train_fraction: float = .6
+    validation_fraction: float = .2
+    strategy: str = "chronological"
+    gap_rows: int = 0
+    gap_seconds: float = 0.
+
+    def __post_init__(self):
+        if not (0 < self.train_fraction < 1 and 0 < self.validation_fraction < 1
+                and self.train_fraction + self.validation_fraction < 1):
+            invalid("split fractions must leave nonempty train, validation and holdout")
+        if self.strategy not in ("chronological", "group", "random"):
+            invalid("unknown split strategy")
+        if isinstance(self.gap_rows, bool) or not isinstance(self.gap_rows, int) or self.gap_rows < 0:
+            invalid("gap_rows must be a nonnegative integer")
+        if not math.isfinite(self.gap_seconds) or self.gap_seconds < 0:
+            invalid("gap_seconds must be nonnegative and finite")
+
+
+@dataclass(frozen=True)
+class CandidateConfig:
+    candidate_id: str = "feedback_spatial"
+    parameters: dict = field(default_factory=dict)
+    features: tuple[str, ...] | None = None
+    alpha: float = 1.0
+    threshold: float = .5
+    preprocessing: dict = field(default_factory=dict)
+    feature_spec: dict = field(default_factory=dict)
+    calibration: str = "none"
+    threshold_rule: str = "fixed"
+
+    def __post_init__(self):
+        if self.features is not None:
+            object.__setattr__(self, "features", tuple(self.features))
+        if not math.isfinite(self.alpha) or self.alpha <= 0:
+            invalid("alpha must be finite and positive")
+        if not math.isfinite(self.threshold) or not 0 <= self.threshold <= 1:
+            invalid("threshold must be between zero and one")
+        if not self.candidate_id or not isinstance(self.parameters, dict):
+            invalid("candidate ID and parameter mapping required")
+        if not isinstance(self.preprocessing, dict) or not isinstance(self.feature_spec, dict):
+            invalid("preprocessing and feature_spec must be mappings")
+        if self.calibration not in ("none", "isotonic"):
+            invalid("calibration must be none or isotonic")
+        if self.threshold_rule not in ("fixed", "f1"):
+            invalid("threshold_rule must be fixed or f1")
+
+
+@dataclass(frozen=True)
+class ExperimentConfig:
+    goal: GoalConfig
+    candidates: tuple[CandidateConfig, ...]
+    split: SplitConfig = field(default_factory=SplitConfig)
+    max_trials: int = 10
+    time_limit_seconds: float = 300.
+    seed: int = 42
+    acceptance: GoalConfig | None = None
+    allowed_changes: dict[str, tuple] | None = None
+
+    def __post_init__(self):
+        object.__setattr__(self, "candidates", tuple(self.candidates))
+        if not self.candidates:
+            invalid("explicit candidate configurations are required")
+        if isinstance(self.max_trials, bool) or not isinstance(self.max_trials, int) or self.max_trials <= 0:
+            invalid("max_trials must be positive integer")
+        if not math.isfinite(self.time_limit_seconds) or self.time_limit_seconds <= 0:
+            invalid("time_limit_seconds must be positive and finite")
+        if self.allowed_changes is not None:
+            if not isinstance(self.allowed_changes, dict):
+                invalid("allowed_changes must map candidate fields to explicit values")
+            fields = set(CandidateConfig.__dataclass_fields__)
+            normalized = {}
+            for name, values in self.allowed_changes.items():
+                if name not in fields or not isinstance(values, (list, tuple)) or not values:
+                    invalid("allowed_changes requires known candidate fields and nonempty value lists")
+                normalized[name] = tuple(values)
+            if not any(all(getattr(candidate, name) in values for name, values in normalized.items())
+                       for candidate in self.candidates):
+                invalid("allowed_changes excludes every configured candidate")
+            object.__setattr__(self, "allowed_changes", normalized)
+
+
+@dataclass(frozen=True)
+class TargetConfig:
+    mode: str = "direct"
+    horizon_rows: int = 0
+    base_column: str | None = None
+    label_alignment: str = "shift"
+
+    def __post_init__(self):
+        if self.mode not in ("direct", "delta"):
+            invalid("target mode must be direct or delta")
+        if self.label_alignment not in ("shift", "prealigned"):
+            invalid("label_alignment must be shift or prealigned")
+        if isinstance(self.horizon_rows, bool) or not isinstance(self.horizon_rows, int) or self.horizon_rows < 0:
+            invalid("horizon_rows must be a nonnegative integer")
+        if self.mode == "delta" and (self.horizon_rows < 1 or not self.base_column):
+            invalid("delta target requires positive horizon_rows and base_column")

zeus_sdk/contracts.py

@@ -0,0 +1,176 @@
+"""Data contracts; importing the SDK does not read files or start experiments."""
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import SDKError
+
+
+@dataclass
+class ValidationIssue:
+    code: str
+    message: str
+    row_id: Any = None
+    column: str | None = None
+    severity: str = "error"
+
+
+@dataclass
+class ValidationReport:
+    issues: list = field(default_factory=list)
+
+    @property
+    def valid(self):
+        return not any(x.severity == "error" for x in self.issues)
+
+    def raise_for_errors(self):
+        if not self.valid:
+            raise SDKError("INVALID_DATA", "; ".join(x.message for x in self.issues),
+                           details={"issues": [vars(x) for x in self.issues]})
+
+
+@dataclass
+class MetricValue:
+    value: float | None
+    status: str = "VALID"
+    reason: str | None = None
+    sample_count: int = 0
+
+
+@dataclass
+class EvaluationResult:
+    metrics: dict
+    row_count: int
+
+
+@dataclass
+class InferenceRecord:
+    run_id: str
+    model_id: str
+    status: str
+    input_count: int
+    completed_count: int
+    elapsed_seconds: float
+    batches: list = field(default_factory=list)
+    environment: dict = field(default_factory=dict)
+    started_at: str | None = None
+    finished_at: str | None = None
+    uncompleted_count: int = 0
+    batch_size: int | None = None
+
+
+@dataclass
+class PredictionBatch:
+    frame: Any
+    execution: InferenceRecord | None = None
+
+
+@dataclass
+class TrialResult:
+    trial_id: str
+    candidate_id: str
+    status: str
+    metrics: dict
+    model: Any = None
+    reason: str | None = None
+    plan: dict = field(default_factory=dict)
+    elapsed_seconds: float = 0.
+    diagnostics: dict = field(default_factory=dict)
+
+
+@dataclass
+class DataNeedDecision:
+    status: str
+    reason: str
+    evidence: dict = field(default_factory=dict)
+    required_items: list = field(default_factory=list)
+
+
+@dataclass
+class RunResult:
+    run_id: str
+    status: str
+    trials: list
+    goal_candidate: TrialResult | None
+    best_candidate: TrialResult | None
+    best_qrc_candidate: TrialResult | None
+    evaluation_context: Any
+    reason: str | None = None
+    report: dict = field(default_factory=dict)
+
+
+@dataclass
+class FinalizationResult:
+    evaluation_id: str
+    model_id: str
+    model: Any
+    metrics: dict
+    acceptance_passed: bool
+    run_id: str
+    candidate_id: str
+    fingerprint: str
+    reason: str | None = None
+    report: dict = field(default_factory=dict)
+
+
+@dataclass
+class AdoptionDecision:
+    decision_id: str
+    model_id: str
+    evaluation_id: str
+    decision: str
+    reason: str
+    created_at: str
+
+
+@dataclass
+class ProfileResult:
+    tables: dict
+    metadata: dict = field(default_factory=dict)
+
+    def export(self, path, plots=False):
+        from .reporting.export import export_report
+        return export_report(self, path, plots=plots)
+
+
+@dataclass
+class ExplanationResult:
+    status: str
+    values: Any = None
+    feature_names: list = field(default_factory=list)
+    base_values: Any = None
+    predictions: Any = None
+    reason: str | None = None
+    metadata: dict = field(default_factory=dict)
+
+    def export(self, path, plots=False):
+        """Export numerical attributions; the metadata declares the explained space."""
+        from pathlib import Path
+        import json
+        import numpy as np
+        import pandas as pd
+        if self.status != "SUCCESS":
+            raise SDKError(self.status, self.reason or "Explanation is unavailable")
+        dest = Path(path)
+        dest.mkdir(parents=True, exist_ok=True)
+        values = np.asarray(self.values)
+        frame = pd.DataFrame(values, columns=self.feature_names)
+        frame.insert(0, "row_id", self.metadata.get("row_ids", range(len(frame))))
+        frame.to_csv(dest / "contributions.csv", index=False)
+        summary = pd.DataFrame({"feature": self.feature_names,
+                                "mean_absolute_contribution": np.abs(values).mean(axis=0)})
+        summary.to_csv(dest / "global_contributions.csv", index=False)
+        pd.DataFrame({"base_value": np.broadcast_to(np.asarray(self.base_values), (len(frame),))}).to_csv(dest / "base_values.csv", index=False)
+        if self.predictions is not None:
+            self.predictions.to_csv(dest / "predictions.csv", index=False)
+        (dest / "metadata.json").write_text(json.dumps(self.metadata, default=str, ensure_ascii=False), encoding="utf-8")
+        if plots:
+            from .reporting.figures import subplots
+            visible = summary.nlargest(20, "mean_absolute_contribution").sort_values("mean_absolute_contribution")
+            fig, ax = subplots(figsize=(8, max(3, .3 * len(visible))))
+            ax.barh(visible.feature, visible.mean_absolute_contribution)
+            ax.set(xlabel="Mean absolute SHAP contribution",
+                   title=f"Readout attribution ({self.metadata.get('output_space', 'specified output')})")
+            fig.tight_layout()
+            fig.savefig(dest / "global_contributions.png", dpi=150)
+            fig.clear()
+        return dest

zeus_sdk/data/__init__.py

@@ -0,0 +1,9 @@
+from .loading import load_dataset
+from .validation import validate_dataset
+from .splitting import make_split
+from .profiling import profile_dataset
+from .targets import prepare_targets
+from .feedback import FeedbackResult, join_observations
+
+__all__ = ["load_dataset", "validate_dataset", "make_split", "profile_dataset", "prepare_targets",
+           "FeedbackResult", "join_observations"]