madcop 0.1.0__py3-none-any.whl

madcop/__init__.py

@@ -0,0 +1,3 @@
+"""madcop: a pluggable LangGraph framework for supply chain anomaly orchestration."""
+
+__version__ = "0.1.0"

madcop/__main__.py

@@ -0,0 +1,123 @@
+"""madcop CLI entry point.
+
+Two demo scenarios today:
+  python -m madcop run coldchain              # W1 — print the event stream
+  python -m madcop run anomalies coldchain    # W2 — run anomaly detection
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .adapters.wms import WMSAdapter
+from .anomaly.rules import default_detector
+from .rca.graph import explain, trace
+from .rca.seed import build_coldchain_seed
+
+
+def _format_event(idx: int, total: int, ev) -> str:
+    ts = ev.parsed_timestamp.strftime("%H:%M:%S")
+    val = f"{ev.value:>6.1f}°C" if ev.value is not None else "    —  "
+    sev = "·" * ev.severity
+    return f"  [{idx:>2}/{total}] {ts}  {val}  sev{ev.severity} {sev}  {ev.attributes.get('note', '')}"
+
+
+def run_coldchain() -> int:
+    """W1 demo: print the WMS cold-chain event stream."""
+    adapter = WMSAdapter()
+    events = sorted(adapter.fetch(), key=lambda e: e.parsed_timestamp)
+    if not events:
+        print("(no events)", file=sys.stderr)
+        return 1
+    print(f"cold-chain timeline for {events[0].subject_id}")
+    print(f"  threshold: {adapter.COLD_CHAIN_THRESHOLD_C}°C")
+    print()
+    for i, ev in enumerate(events, 1):
+        print(_format_event(i, len(events), ev))
+    breaches = [e for e in events if e.value is not None and e.value > adapter.COLD_CHAIN_THRESHOLD_C]
+    print()
+    print(f"  → {len(breaches)} threshold breach(es) detected")
+    return 0
+
+
+def run_anomalies_coldchain() -> int:
+    """W2 demo: run all 5 anomaly rules on the cold-chain stream."""
+    adapter = WMSAdapter()
+    events = sorted(adapter.fetch(), key=lambda e: e.parsed_timestamp)
+    detector = default_detector()
+    findings = list(detector.run(events))
+    print(f"madcop anomaly report — subject={events[0].subject_id if events else 'N/A'}")
+    print(f"  events: {len(events)}   rules: {len(detector.rules)}   findings: {len(findings)}")
+    print()
+    if not findings:
+        print("  (no anomalies)")
+        return 0
+    for i, f in enumerate(findings, 1):
+        print(f"  [{i}/{len(findings)}] sev{f.severity}  {f.rule_id}")
+        print(f"            {f.summary}")
+    return 0
+
+
+def run_rca_coldchain() -> int:
+    """W3 demo: detect anomalies and trace each to a root-cause decision."""
+    from rich.console import Console
+    from rich.panel import Panel
+
+    console = Console()
+    events = sorted(WMSAdapter().fetch(), key=lambda e: e.parsed_timestamp)
+    findings = list(default_detector().run(events))
+    g = build_coldchain_seed()
+
+    console.print(f"[bold]madcop RCA demo[/] — {len(findings)} finding(s) on {events[0].subject_id}\n")
+    if not findings:
+        console.print("  [dim](no findings to trace)[/]")
+        return 0
+    for i, f in enumerate(findings, 1):
+        console.print(f"[cyan]━━━ finding {i}/{len(findings)} ━━━[/]")
+        console.print(f"  rule:    [yellow]{f.rule_id}[/]")
+        console.print(f"  summary: {f.summary}")
+        chain = trace(f, g)
+        if not chain.steps:
+            console.print("  [dim](no causal chain — subject not in knowledge graph)[/]")
+            continue
+        console.print(f"  chain:   [bold]{len(chain.steps)}[/] step(s), root cause:")
+        console.print(Panel(explain(chain), title="root cause", border_style="red"))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="madcop",
+        description="madcop — the supply chain cop that goes mad for anomalies.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    # run <scenario>
+    run_p = sub.add_parser("run", help="Run a scenario")
+    run_sub = run_p.add_subparsers(dest="scenario", required=True)
+    run_sub.add_parser("coldchain", help="W1: print the cold-chain event stream")
+    run_sub.add_parser("anomalies", help="W2: run anomaly detection on the cold-chain stream")
+    run_sub.add_parser("rca",       help="W3: detect anomalies and trace each to a root cause")
+
+    # demo <scenario> — alias for `run`
+    demo_p = sub.add_parser("demo", help="Alias for `run`")
+    demo_sub = demo_p.add_subparsers(dest="scenario", required=True)
+    demo_sub.add_parser("coldchain", help="W1: print the cold-chain event stream")
+    demo_sub.add_parser("anomalies", help="W2: run anomaly detection on the cold-chain stream")
+    demo_sub.add_parser("rca",       help="W3: detect anomalies and trace each to a root cause")
+
+    args = parser.parse_args(argv)
+    if args.cmd in ("run", "demo"):
+        if args.scenario == "coldchain":
+            return run_coldchain()
+        if args.scenario == "anomalies":
+            return run_anomalies_coldchain()
+        if args.scenario == "rca":
+            return run_rca_coldchain()
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

madcop/adapters/base.py

@@ -0,0 +1,82 @@
+"""Adapter contract — the seam between the outside world and `UnifiedEvent`.
+
+Every system (OMS / TMS / WMS / BMS / future) ships an adapter that implements
+`BaseAdapter`. Two responsibilities, and only two:
+
+1. **Pull** raw data from a system (HTTP, DB, file, etc.) and yield `UnifiedEvent`s.
+2. **Push** actions back to the system (e.g. re-route shipment, mark exception).
+
+We deliberately keep the adapter small. Logic that *reads* the event stream
+lives in the anomaly engine. Logic that *acts* on decisions lives in the
+strategy router. The adapter is just a translator.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Iterator
+
+from ..event import SourceSystem, UnifiedEvent
+
+
+class BaseAdapter(ABC):
+    """The contract every system adapter must satisfy.
+
+    Adapters are stateful objects (they hold a connection, an API key, a
+    file handle). They are constructed once per session and called repeatedly.
+    """
+
+    source_system: SourceSystem  # set by subclass
+
+    @abstractmethod
+    def fetch(self, *, since: str | None = None, subject_id: str | None = None) -> Iterator[UnifiedEvent]:
+        """Yield events from the upstream system, optionally filtered.
+
+        `since` is a UTC ISO 8601 string. If given, only events with
+        `timestamp >= since` should be returned.
+
+        `subject_id`, if given, restricts to events about a single business
+        object (an order, a SKU, a shipment, a contract). Adapters that
+        cannot filter server-side should filter in-memory after fetching.
+
+        Yields events in **any order** — the LangGraph orchestrator sorts
+        by timestamp.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def execute(self, action: "Action") -> dict:
+        """Push an action back to the system. Returns the system's response.
+
+        See `Action` for the schema. Adapters that cannot perform an action
+        (e.g. WMS can't change a contract) should raise
+        `UnsupportedActionError`.
+        """
+        raise NotImplementedError
+
+    def health_check(self) -> bool:
+        """Optional. Default: assume healthy. Override for real wire checks."""
+        return True
+
+
+class UnsupportedActionError(NotImplementedError):
+    """Raised when an adapter is asked to perform an action outside its scope."""
+
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class Action:
+    """A command the strategy router wants executed against an adapter.
+
+    The action is **adapter-agnostic**: the router does not know which system
+    will run it. The router picks an adapter based on `target_system` and the
+    adapter translates the rest.
+    """
+
+    target_system: SourceSystem
+    action_type: str                          # free-form, adapter-defined vocabulary
+    subject_id: str                           # what the action is about
+    parameters: Mapping[str, Any]             # adapter-specific args

madcop/adapters/wms.py

@@ -0,0 +1,94 @@
+"""WMS mock adapter — cold-chain temperature monitoring.
+
+W1 deliverable: 1 of 4 mock adapters. This one is real-enough to drive a
+cold-chain anomaly demo. Future weeks add OMS, TMS, BMS as separate files
+following the same shape.
+
+The "data" is hardcoded. That's intentional — a real wire adapter would swap
+`fetch()` for an HTTP call, but the **shape** is what the framework depends
+on, and the shape lives in `BaseAdapter`.
+
+Scenario: a 冷链 (cold-chain) shipment from 广州仓 → 上海仓 on 2026-06-15.
+- 08:00 dispatch, setpoint -18°C
+- 12:00 routine reading, -17.8°C
+- 14:30 reading: -14.2°C (!!! threshold breach, severity 4)
+- 15:00 reading: -13.8°C
+- 15:30 reading: -17.5°C (recovered — driver opened the door, not equipment)
+- 18:42 delivered, last reading -17.6°C
+"""
+
+from __future__ import annotations
+
+from typing import Iterator
+
+from ..event import EventType, SourceSystem, UnifiedEvent, make_event
+from .base import Action, BaseAdapter, UnsupportedActionError
+
+
+class WMSAdapter(BaseAdapter):
+    """WMS adapter (mock). Cold-chain temperature stream for one shipment."""
+
+    source_system = SourceSystem.WMS
+
+    # Cold-chain threshold, in °C. Anything above this for any reading is
+    # an anomaly. We hardcode it here; in a real adapter it would come from
+    # the WMS product master.
+    COLD_CHAIN_THRESHOLD_C = -15.0
+
+    def __init__(self, shipment_id: str = "SHIP-2026-0615-CG-SH"):
+        self.shipment_id = shipment_id
+
+    def fetch(
+        self,
+        *,
+        since: str | None = None,
+        subject_id: str | None = None,
+    ) -> Iterator[UnifiedEvent]:
+        # The data: a single shipment's temperature stream.
+        # In a real adapter this would come from `requests.get(...)` or a DB
+        # query. Here it's a static list so the demo is reproducible.
+        raw = [
+            # (timestamp,           value,  severity,  attributes)
+            ("2026-06-15T08:00:00Z", -18.0, 1, {"setpoint_c": -18.0, "phase": "dispatch"}),
+            ("2026-06-15T12:00:00Z", -17.8, 1, {"setpoint_c": -18.0, "phase": "in_transit"}),
+            ("2026-06-15T14:30:00Z", -14.2, 4, {"setpoint_c": -18.0, "phase": "in_transit",
+                                                "note": "threshold breach"}),
+            ("2026-06-15T15:00:00Z", -13.8, 5, {"setpoint_c": -18.0, "phase": "in_transit",
+                                                "note": "still rising"}),
+            ("2026-06-15T15:30:00Z", -17.5, 1, {"setpoint_c": -18.0, "phase": "in_transit",
+                                                "note": "recovered — door opened at 15:25"}),
+            ("2026-06-15T18:42:00Z", -17.6, 1, {"setpoint_c": -18.0, "phase": "delivered"}),
+        ]
+        for ts, value, sev, attrs in raw:
+            if subject_id and subject_id != self.shipment_id:
+                continue
+            yield make_event(
+                timestamp=ts,
+                source_system=SourceSystem.WMS,
+                event_type=EventType.TEMPERATURE_READING,
+                subject_id=self.shipment_id,
+                value=value,
+                attributes=attrs,
+                severity=sev,
+            )
+
+    def execute(self, action: Action) -> dict:
+        # WMS can mark exceptions, request re-icing, dispatch a recovery team.
+        # Anything else is out of scope.
+        supported = {"mark_exception", "request_re_ice", "dispatch_recovery"}
+        if action.action_type not in supported:
+            raise UnsupportedActionError(
+                f"WMSAdapter does not support action {action.action_type!r}; "
+                f"supported: {sorted(supported)}"
+            )
+        # Mock: just echo.
+        return {
+            "ok": True,
+            "system": "wms",
+            "action": action.action_type,
+            "subject_id": action.subject_id,
+            "parameters": dict(action.parameters),
+        }
+
+    def health_check(self) -> bool:
+        return True

madcop/anomaly/detector.py

@@ -0,0 +1,88 @@
+"""L2 — Anomaly detection.
+
+The detector is a thin orchestrator over a list of `BaseRule` instances. Each
+rule inspects the event stream and either fires or stays silent. The detector
+collects fired rules and returns a list of `AnomalyFinding`s.
+
+Design choices:
+
+- Rules are **stateless** and **per-event**. A rule that needs a window
+  (e.g. "breach sustained for >15 min") does its own windowing internally.
+  This is simple and correct, at the cost of some redundant work. Optimize
+  later if needed.
+- A single event can fire multiple rules. We do not deduplicate. Different
+  rules signal different concerns (a single breach can be both a temperature
+  rule AND a sustained-duration rule).
+- Rules have a `rule_id` so downstream consumers (the strategy router in W5,
+  the weekly report in W7) can identify them in feedback logs.
+- `severity` here is the **rule's** severity, distinct from the event's
+  adapter-set severity. The orchestrator will eventually combine them; for
+  W2, the rule severity is what we surface.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Iterable, Sequence
+
+from ..event import UnifiedEvent
+
+
+@dataclass(frozen=True)
+class AnomalyFinding:
+    """A single rule's verdict on a single event (or window)."""
+    rule_id: str
+    subject_id: str
+    timestamp: str                          # when the anomaly was observed
+    severity: int                           # 1..5, set by the rule
+    summary: str                            # one-line human description
+    details: dict = field(default_factory=dict)
+
+
+class BaseRule(ABC):
+    """A single anomaly detection rule.
+
+    Rules are constructed once and reused. They must be **idempotent**:
+    calling `evaluate()` twice with the same event must yield the same result.
+    """
+
+    rule_id: str                            # set by subclass
+    description: str                        # one-line human description
+
+    @abstractmethod
+    def evaluate(self, event: UnifiedEvent) -> AnomalyFinding | None:
+        """Return an `AnomalyFinding` if this rule fires, else `None`."""
+        raise NotImplementedError
+
+
+class Detector:
+    """Runs a set of rules over a stream of events.
+
+    Usage:
+        detector = Detector([ColdChainTemperature(threshold_c=-15.0)])
+        findings = list(detector.run(events))
+    """
+
+    def __init__(self, rules: Sequence[BaseRule]):
+        if not rules:
+            raise ValueError("Detector requires at least one rule")
+        self._rules = list(rules)
+
+    @property
+    def rules(self) -> Sequence[BaseRule]:
+        return tuple(self._rules)
+
+    def evaluate_event(self, event: UnifiedEvent) -> list[AnomalyFinding]:
+        """Run all rules on a single event. Returns findings (may be empty)."""
+        return [
+            f for f in (r.evaluate(event) for r in self._rules)
+            if f is not None
+        ]
+
+    def run(self, events: Iterable[UnifiedEvent]) -> Iterable[AnomalyFinding]:
+        """Stream findings as we iterate events. Order: rule order per event,
+        event order across the stream."""
+        for ev in events:
+            for f in self.evaluate_event(ev):
+                yield f