anomx 0.2.0__py3-none-any.whl

anomx/__init__.py

@@ -0,0 +1,53 @@
+"""Anomx core library for time-series anomaly detection and reusable workflows."""
+
+from anomx.components import (
+    BaseAlgorithm,
+    BaseAnomalyModel,
+    BaseComponent,
+    BaseDetector,
+    BaseScorer,
+    IsolationForestModel,
+    PcaReconstructionModel,
+    PipelineOrchestrator,
+    RollingWindowForecastModel,
+    ThresholdDetector,
+    discover_component_payloads,
+)
+from anomx.data import BaseConnector, LocalFSConnector, TimeSeriesBatch
+from anomx.datasets import TimeSeriesDataset
+from anomx.detectors import AnomalyDetector, DetectionResult, MovingAverageDetector
+from anomx.models import (
+    Forecast,
+    ForecastingModel,
+    NaiveSeasonalModel,
+)
+from anomx.scorers import AnomalyScorer, ThresholdScorer, ZScoreScorer
+
+__all__ = [
+    "BaseAlgorithm",
+    "BaseAnomalyModel",
+    "BaseComponent",
+    "BaseConnector",
+    "BaseDetector",
+    "BaseScorer",
+    "AnomalyDetector",
+    "AnomalyScorer",
+    "DetectionResult",
+    "Forecast",
+    "ForecastingModel",
+    "IsolationForestModel",
+    "LocalFSConnector",
+    "MovingAverageDetector",
+    "NaiveSeasonalModel",
+    "PcaReconstructionModel",
+    "PipelineOrchestrator",
+    "RollingWindowForecastModel",
+    "ThresholdScorer",
+    "ThresholdDetector",
+    "TimeSeriesBatch",
+    "TimeSeriesDataset",
+    "ZScoreScorer",
+    "discover_component_payloads",
+]
+
+__version__ = "0.2.0"

anomx/__main__.py

@@ -0,0 +1,6 @@
+"""Run the Anomx command line interface."""
+
+from anomx.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

anomx/_shared.py

@@ -0,0 +1,40 @@
+"""Shared helpers for package-internal normalization and dataframe handling."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import pandas as pd
+
+
+def normalize_text(value: object) -> str:
+    """Return a trimmed single-line string representation."""
+    return str(value or "").strip()
+
+
+def normalise_component_key(value: object) -> str:
+    """Normalize component identifiers into a stable snake-case-ish key."""
+    normalized = normalize_text(value).lower()
+    normalized = re.sub(r"[^a-z0-9]+", "_", normalized)
+    return normalized.strip("_")
+
+
+def ensure_dataframe(data: Any) -> pd.DataFrame:
+    """Convert a supported tabular payload into a DataFrame copy."""
+    if isinstance(data, pd.DataFrame):
+        return data.copy()
+    if isinstance(data, pd.Series):
+        return data.to_frame()
+    return pd.DataFrame(data)
+
+
+def dataframe_to_records(frame: pd.DataFrame) -> list[dict[str, Any]]:
+    """Serialize a DataFrame into JSON-friendly records."""
+    normalized = frame.copy()
+    for column in normalized.columns:
+        if pd.api.types.is_datetime64_any_dtype(normalized[column]):
+            normalized[column] = normalized[column].astype(str)
+    if isinstance(normalized.index, pd.DatetimeIndex):
+        normalized.index = normalized.index.astype(str)
+    return list(normalized.reset_index(drop=False).to_dict(orient="records"))

anomx/cli.py

@@ -0,0 +1,22 @@
+"""Command line entry points for Anomx."""
+
+from __future__ import annotations
+
+import argparse
+
+from anomx import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the CLI argument parser."""
+    parser = argparse.ArgumentParser(prog="anomx", description="Anomx time-series anomaly toolkit.")
+    parser.add_argument("--version", action="version", version=f"anomx {__version__}")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the CLI."""
+    parser = build_parser()
+    parser.parse_args(argv)
+    parser.print_help()
+    return 0

anomx/components/__init__.py

@@ -0,0 +1,29 @@
+"""Reusable anomaly-detection components and discovery helpers."""
+
+from anomx.components.base import BaseComponent, discover_component_payloads, iter_component_classes
+from anomx.components.algorithms import BaseAlgorithm, PipelineAlgorithm, PipelineOrchestrator
+from anomx.components.detection.detectors import BaseDetector, ThresholdDetector
+from anomx.components.detection.scorers import BaseScorer, ZScoreScorer
+from anomx.components.models import (
+    BaseAnomalyModel,
+    IsolationForestModel,
+    PcaReconstructionModel,
+    RollingWindowForecastModel,
+)
+
+__all__ = [
+    "BaseAlgorithm",
+    "BaseAnomalyModel",
+    "BaseComponent",
+    "BaseDetector",
+    "BaseScorer",
+    "IsolationForestModel",
+    "PcaReconstructionModel",
+    "PipelineAlgorithm",
+    "PipelineOrchestrator",
+    "RollingWindowForecastModel",
+    "ThresholdDetector",
+    "ZScoreScorer",
+    "discover_component_payloads",
+    "iter_component_classes",
+]

anomx/components/algorithms/__init__.py

@@ -0,0 +1,14 @@
+"""Algorithm components."""
+
+from anomx.components.algorithms.base import BaseAlgorithm
+from anomx.components.algorithms.contracts import JobResult, JobSpec, JobSummary
+from anomx.components.algorithms.offline import PipelineAlgorithm, PipelineOrchestrator
+
+__all__ = [
+    "BaseAlgorithm",
+    "JobResult",
+    "JobSpec",
+    "JobSummary",
+    "PipelineAlgorithm",
+    "PipelineOrchestrator",
+]

anomx/components/algorithms/base.py

@@ -0,0 +1,19 @@
+"""Base algorithm contract."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from anomx.components.algorithms.contracts import JobResult, JobSpec
+from anomx.components.base import BaseComponent
+
+
+class BaseAlgorithm(BaseComponent, ABC):
+    """Base class for reusable anomaly workflows."""
+
+    component_type = "algorithm"
+
+    @abstractmethod
+    def run_job(self, job_spec: JobSpec | dict[str, Any]) -> JobResult:
+        """Execute an anomaly-detection workflow."""

anomx/components/algorithms/contracts.py

@@ -0,0 +1,49 @@
+"""Contracts shared by algorithm orchestrators."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class JobSpec:
+    connector: str
+    model: str
+    detector: str
+    scorer: str
+    config: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_mapping(cls, payload: dict[str, Any]) -> "JobSpec":
+        return cls(
+            connector=str(payload.get("connector") or "").strip(),
+            model=str(payload.get("model") or "").strip(),
+            detector=str(payload.get("detector") or "").strip(),
+            scorer=str(payload.get("scorer") or "").strip(),
+            config=dict(payload.get("config") or {}),
+        )
+
+
+@dataclass(frozen=True)
+class JobSummary:
+    rows_processed: int
+    anomaly_count: int
+    feature_columns: list[str] = field(default_factory=list)
+    score_column: str = "zscore"
+    duration_ms: int = 0
+
+
+@dataclass(frozen=True)
+class JobResult:
+    job_id: str
+    status: str
+    connector: str
+    model: str
+    scorer: str
+    detector: str
+    summary: JobSummary
+    records: list[dict[str, Any]] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

anomx/components/algorithms/offline/__init__.py

@@ -0,0 +1,28 @@
+"""Offline orchestration implementations."""
+
+from anomx.components.algorithms.offline.catalog import (
+    COMPONENT_IMPLEMENTATIONS,
+    CONNECTOR_IMPLEMENTATIONS,
+    DETECTOR_IMPLEMENTATIONS,
+    IMPLEMENTATION_CATALOGS,
+    MODEL_IMPLEMENTATIONS,
+    SCORER_IMPLEMENTATIONS,
+    ComponentClass,
+    ComponentKind,
+    resolve_implementation,
+)
+from anomx.components.algorithms.offline.pipeline import PipelineAlgorithm, PipelineOrchestrator
+
+__all__ = [
+    "COMPONENT_IMPLEMENTATIONS",
+    "CONNECTOR_IMPLEMENTATIONS",
+    "DETECTOR_IMPLEMENTATIONS",
+    "IMPLEMENTATION_CATALOGS",
+    "MODEL_IMPLEMENTATIONS",
+    "SCORER_IMPLEMENTATIONS",
+    "ComponentClass",
+    "ComponentKind",
+    "PipelineAlgorithm",
+    "PipelineOrchestrator",
+    "resolve_implementation",
+]

anomx/components/algorithms/offline/catalog.py

@@ -0,0 +1,58 @@
+"""Static implementation catalog for the default offline pipeline."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypeAlias
+
+from anomx._shared import normalise_component_key
+from anomx.components.detection.detectors import BaseDetector, ThresholdDetector
+from anomx.components.detection.scorers import BaseScorer, ZScoreScorer
+from anomx.components.models import (
+    BaseAnomalyModel,
+    IsolationForestModel,
+    PcaReconstructionModel,
+    RollingWindowForecastModel,
+)
+from anomx.data.connectors import BaseConnector, LocalFSConnector
+
+
+ComponentKind = Literal["connector", "model", "scorer", "detector"]
+ComponentClass: TypeAlias = type[Any]
+
+CONNECTOR_IMPLEMENTATIONS: dict[str, type[BaseConnector]] = {
+    "local_fs": LocalFSConnector,
+}
+
+MODEL_IMPLEMENTATIONS: dict[str, type[BaseAnomalyModel]] = {
+    "isolation_forest": IsolationForestModel,
+    "pca_reconstruction": PcaReconstructionModel,
+    "rolling_window_forecast": RollingWindowForecastModel,
+}
+
+SCORER_IMPLEMENTATIONS: dict[str, type[BaseScorer]] = {
+    "zscore": ZScoreScorer,
+}
+
+DETECTOR_IMPLEMENTATIONS: dict[str, type[BaseDetector]] = {
+    "threshold": ThresholdDetector,
+}
+
+IMPLEMENTATION_CATALOGS: dict[ComponentKind, dict[str, ComponentClass]] = {
+    "connector": CONNECTOR_IMPLEMENTATIONS,
+    "model": MODEL_IMPLEMENTATIONS,
+    "scorer": SCORER_IMPLEMENTATIONS,
+    "detector": DETECTOR_IMPLEMENTATIONS,
+}
+
+COMPONENT_IMPLEMENTATIONS = IMPLEMENTATION_CATALOGS
+
+
+def resolve_implementation(name: str, kind: ComponentKind) -> ComponentClass:
+    """Resolve one configured implementation from the static catalog."""
+    normalized_name = normalise_component_key(name)
+    catalog = IMPLEMENTATION_CATALOGS[kind]
+    implementation = catalog.get(normalized_name)
+    if implementation is not None:
+        return implementation
+    available = ", ".join(sorted(catalog)) or "none"
+    raise KeyError(f"Unknown {kind} implementation '{name}'. Available: {available}.")

anomx/components/algorithms/offline/pipeline.py

@@ -0,0 +1,74 @@
+"""Default offline train-score-detect orchestration."""
+
+from __future__ import annotations
+
+from time import perf_counter
+from typing import Any, cast
+from uuid import uuid4
+
+import pandas as pd
+
+from anomx._shared import dataframe_to_records, ensure_dataframe
+from anomx.components.algorithms.base import BaseAlgorithm
+from anomx.components.algorithms.contracts import JobResult, JobSpec, JobSummary
+from anomx.components.algorithms.offline.catalog import resolve_implementation
+
+
+class PipelineOrchestrator(BaseAlgorithm):
+    """Train, score, and classify a dataset with built-in library components."""
+
+    component_key = "pipeline"
+    component_name = "Pipeline"
+    component_description = "Default offline orchestration pipeline for model, scorer, and detector components."
+    component_config_schema = {
+        "connector": {"type": "object"},
+        "detector": {"type": "object"},
+        "model": {"type": "object"},
+        "scorer": {"type": "object"},
+    }
+
+    def run_job(self, job_spec: JobSpec | dict[str, Any]) -> JobResult:
+        spec = job_spec if isinstance(job_spec, JobSpec) else JobSpec.from_mapping(job_spec)
+        started_at = perf_counter()
+        config = spec.config
+
+        connector = cast(type, resolve_implementation(spec.connector, "connector"))()
+        model = cast(type, resolve_implementation(spec.model, "model"))(config.get("model", {}))
+        scorer = cast(type, resolve_implementation(spec.scorer, "scorer"))(config.get("scorer", {}))
+        detector = cast(type, resolve_implementation(spec.detector, "detector"))(config.get("detector", {}))
+
+        raw_data = connector.read(config.get("connector", {}))
+        frame = ensure_dataframe(raw_data)
+        model.fit(frame)
+        predictions = ensure_dataframe(model.predict(frame))
+        scored = ensure_dataframe(scorer.score(predictions))
+        detected = ensure_dataframe(detector.detect(scored))
+
+        feature_columns = list(config.get("model", {}).get("feature_columns") or [])
+        if not feature_columns:
+            feature_columns = frame.select_dtypes(include=["number"]).columns.tolist()
+
+        anomaly_series = detected.get("is_anomaly", pd.Series(dtype=bool))
+        score_column = "zscore" if "zscore" in detected.columns else "model_score"
+        anomaly_count = int(anomaly_series.sum())
+        duration_ms = int((perf_counter() - started_at) * 1000)
+
+        return JobResult(
+            job_id=str(uuid4()),
+            status="completed",
+            connector=spec.connector,
+            model=spec.model,
+            scorer=spec.scorer,
+            detector=spec.detector,
+            summary=JobSummary(
+                rows_processed=len(detected),
+                anomaly_count=anomaly_count,
+                feature_columns=feature_columns,
+                score_column=score_column,
+                duration_ms=duration_ms,
+            ),
+            records=dataframe_to_records(detected),
+        )
+
+
+PipelineAlgorithm = PipelineOrchestrator

anomx/components/base.py

@@ -0,0 +1,170 @@
+"""Component metadata helpers and discovery."""
+
+from __future__ import annotations
+
+import inspect
+import pkgutil
+import re
+from importlib import import_module
+from pathlib import Path
+from typing import Any, ClassVar
+
+from anomx._shared import normalise_component_key, normalize_text
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[3]
+COMPONENT_PACKAGE_NAMES = (
+    "anomx.components.algorithms",
+    "anomx.components.detection",
+    "anomx.components.models",
+)
+
+
+def humanize_component_name(value: str | None) -> str:
+    normalized_value = str(value or "").strip()
+    if not normalized_value:
+        return ""
+    return re.sub(r"(?<!^)(?=[A-Z])", " ", normalized_value).strip()
+
+
+def read_component_source_path(component_class: type[object]) -> str:
+    source_path = inspect.getsourcefile(component_class) or inspect.getfile(component_class)
+    resolved_path = Path(source_path).resolve()
+    try:
+        return str(resolved_path.relative_to(PROJECT_ROOT))
+    except ValueError:
+        return str(resolved_path)
+
+
+class BaseComponent:
+    """Common metadata surface for installable algorithm components."""
+
+    component_type: ClassVar[str | None] = None
+    component_key: ClassVar[str] = ""
+    component_name: ClassVar[str] = ""
+    component_description: ClassVar[str] = ""
+    component_docs: ClassVar[str] = ""
+    component_image_path: ClassVar[str] = ""
+    component_status: ClassVar[str] = "active"
+    component_default_config: ClassVar[dict[str, Any]] = {}
+    component_config_schema: ClassVar[dict[str, Any]] = {}
+    component_code_version: ClassVar[str] = ""
+
+    @classmethod
+    def is_component_abstract(cls) -> bool:
+        return inspect.isabstract(cls) or not cls.get_component_type()
+
+    @classmethod
+    def get_component_type(cls) -> str:
+        return normalize_text(getattr(cls, "component_type", "")) or ""
+
+    @classmethod
+    def get_component_key(cls) -> str:
+        value = getattr(cls, "component_key", "") or cls.get_component_name() or cls.__name__
+        return normalise_component_key(value)
+
+    @classmethod
+    def get_component_name(cls) -> str:
+        explicit_name = normalize_text(getattr(cls, "component_name", ""))
+        return explicit_name or humanize_component_name(cls.__name__)
+
+    @classmethod
+    def get_component_docs(cls) -> str:
+        explicit_docs = normalize_text(getattr(cls, "component_docs", ""))
+        if explicit_docs:
+            return explicit_docs
+        return normalize_text(inspect.getdoc(cls))
+
+    @classmethod
+    def get_component_description(cls) -> str:
+        explicit_description = normalize_text(getattr(cls, "component_description", ""))
+        if explicit_description:
+            return explicit_description
+        docs = cls.get_component_docs()
+        if not docs:
+            return ""
+        return normalize_text(docs.split("\n\n", 1)[0])
+
+    @classmethod
+    def get_component_image_path(cls) -> str:
+        return normalize_text(getattr(cls, "component_image_path", ""))
+
+    @classmethod
+    def get_component_status(cls) -> str:
+        return normalize_text(getattr(cls, "component_status", "")) or "active"
+
+    @classmethod
+    def get_component_default_config(cls) -> dict[str, Any]:
+        value = getattr(cls, "component_default_config", {})
+        return dict(value) if isinstance(value, dict) else {}
+
+    @classmethod
+    def get_component_config_schema(cls) -> dict[str, Any]:
+        value = getattr(cls, "component_config_schema", {})
+        return dict(value) if isinstance(value, dict) else {}
+
+    @classmethod
+    def get_component_code_version(cls) -> str:
+        return normalize_text(getattr(cls, "component_code_version", ""))
+
+    @classmethod
+    def get_component_source_path(cls) -> str:
+        return read_component_source_path(cls)
+
+    @classmethod
+    def get_component_definition_payload(cls) -> dict[str, Any]:
+        return {
+            "code_version": cls.get_component_code_version(),
+            "component_type": cls.get_component_type(),
+            "config_schema": cls.get_component_config_schema(),
+            "default_config": cls.get_component_default_config(),
+            "description": cls.get_component_description(),
+            "docs": cls.get_component_docs(),
+            "image_path": cls.get_component_image_path(),
+            "key": cls.get_component_key(),
+            "name": cls.get_component_name(),
+            "python_class": cls.__name__,
+            "python_module": cls.__module__,
+            "source_path": cls.get_component_source_path(),
+            "status": cls.get_component_status(),
+        }
+
+
+def import_component_modules(package_names: tuple[str, ...] = COMPONENT_PACKAGE_NAMES) -> None:
+    """Import every module below the configured component packages."""
+    for package_name in package_names:
+        package = import_module(package_name)
+        package_paths = getattr(package, "__path__", None)
+        if package_paths is None:
+            continue
+        for module_info in pkgutil.walk_packages(package_paths, f"{package.__name__}."):
+            import_module(module_info.name)
+
+
+def iter_component_classes(package_names: tuple[str, ...] = COMPONENT_PACKAGE_NAMES):
+    """Yield every non-abstract component class in the package set."""
+    import_component_modules(package_names=package_names)
+    seen_classes: set[type[object]] = set()
+    pending_classes: list[type[object]] = [BaseComponent]
+
+    while pending_classes:
+        current_class = pending_classes.pop()
+        for subclass in current_class.__subclasses__():
+            if subclass in seen_classes:
+                continue
+            seen_classes.add(subclass)
+            pending_classes.append(subclass)
+            if subclass.is_component_abstract():
+                continue
+            yield subclass
+
+
+def discover_component_payloads(package_names: tuple[str, ...] = COMPONENT_PACKAGE_NAMES) -> list[dict[str, Any]]:
+    """Discover all concrete components and return stable metadata payloads."""
+    payloads_by_key: dict[str, dict[str, Any]] = {}
+    for component_class in iter_component_classes(package_names=package_names):
+        payload = component_class.get_component_definition_payload()
+        payload_key = payload["key"]
+        if payload_key:
+            payloads_by_key[payload_key] = payload
+    return [payloads_by_key[key] for key in sorted(payloads_by_key)]

anomx/components/detection/__init__.py

@@ -0,0 +1,11 @@
+"""Detection components."""
+
+from anomx.components.detection.detectors import BaseDetector, ThresholdDetector
+from anomx.components.detection.scorers import BaseScorer, ZScoreScorer
+
+__all__ = [
+    "BaseDetector",
+    "BaseScorer",
+    "ThresholdDetector",
+    "ZScoreScorer",
+]

anomx/components/detection/detectors/__init__.py

@@ -0,0 +1,9 @@
+"""Detector components."""
+
+from anomx.components.detection.detectors.base import BaseDetector
+from anomx.components.detection.detectors.threshold import ThresholdDetector
+
+__all__ = [
+    "BaseDetector",
+    "ThresholdDetector",
+]

anomx/components/detection/detectors/base.py

@@ -0,0 +1,18 @@
+"""Base detector contract for component pipelines."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from anomx.components.base import BaseComponent
+
+
+class BaseDetector(BaseComponent, ABC):
+    """Convert scores into anomaly labels."""
+
+    component_type = "detector"
+
+    @abstractmethod
+    def detect(self, predictions: Any) -> Any:
+        """Return predictions with anomaly labels."""

anomx/components/detection/detectors/threshold.py

@@ -0,0 +1,40 @@
+"""Threshold-based detector component."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from anomx._shared import ensure_dataframe
+from anomx.components.detection.detectors.base import BaseDetector
+
+
+class ThresholdDetector(BaseDetector):
+    """Flag anomalies whenever a score column crosses a fixed threshold."""
+
+    component_key = "threshold"
+    component_name = "Threshold Detector"
+    component_default_config = {
+        "source_column": "zscore",
+        "threshold": 1.5,
+    }
+    component_config_schema = {
+        "source_column": {"type": "string"},
+        "threshold": {"type": "number"},
+    }
+
+    def __init__(self, config: dict[str, Any] | None = None) -> None:
+        self.config = config or {}
+
+    def detect(self, predictions: Any) -> pd.DataFrame:
+        frame = ensure_dataframe(predictions)
+        source_column = str(self.config.get("source_column", "zscore"))
+        threshold = float(self.config.get("threshold", 1.5))
+        if source_column not in frame.columns:
+            raise KeyError(f"Source column '{source_column}' does not exist in detector input.")
+
+        result = frame.copy()
+        result["is_anomaly"] = result[source_column].astype(float).abs() >= threshold
+        result["severity"] = result[source_column].astype(float).abs().round(4)
+        return result

anomx/components/detection/scorers/__init__.py

@@ -0,0 +1,9 @@
+"""Scorer components."""
+
+from anomx.components.detection.scorers.base import BaseScorer
+from anomx.components.detection.scorers.zscore import ZScoreScorer
+
+__all__ = [
+    "BaseScorer",
+    "ZScoreScorer",
+]