aria-code 0.167.0__py3-none-win_amd64.whl

aria_bots/logistics/__init__.py

@@ -0,0 +1 @@
+"""Logistics tools: freight, carrier scoring and inventory policy, scoped per shipper."""

aria_bots/logistics/carriers.py

@@ -0,0 +1,253 @@
+"""Carrier scorecards, freight anomalies and savings for a 3PL, by lane.
+
+A raw on-time percentage ranks a carrier with 1 of 1 deliveries on time above
+one with 98 of 100, which is backwards. Carriers here are ranked by the lower
+bound of the Wilson score interval for their on-time rate, which is what the
+data actually supports: a carrier earns a high rank by being on time *often*,
+not by being on time once.
+
+    Wilson lower bound = (p̂ + z²/2n − z·√(p̂(1−p̂)/n + z²/4n²)) / (1 + z²/n)
+
+Freight anomalies use the modified z-score of cost per kg within a lane —
+median and median absolute deviation, so one outlier cannot hide itself by
+inflating the mean it is compared against (Iglewicz & Hoaglin, |Mᵢ| > 3.5):
+
+    Mᵢ = 0.6745 · (xᵢ − median) / MAD
+    Mᵢ = (xᵢ − median) / (1.253314 · MeanAD)     when MAD = 0
+
+The second form matters: on a contracted lane most shipments share one rate,
+which makes MAD zero, and those are the lanes where an overcharge is plainest.
+
+A savings opportunity is reported only when, on the same lane, an alternative
+carrier is both cheaper per kg *and* at least as reliable by the same lower
+bound, with enough shipments on both sides to say so. The estimate is volume
+× rate difference and nothing more; contract terms, surcharges, minimums and
+capacity are not modelled and the result says so.
+"""
+
+from __future__ import annotations
+
+import math
+import statistics
+from collections import defaultdict
+from statistics import NormalDist
+from typing import Any, Dict, List
+
+from .records import flag, load_records, number, text
+from .tenancy import TenancyError, owner_params_schema, scope_records
+
+DEFAULTS = {"confidence": 0.95, "min_shipments": 20}
+ANOMALY_THRESHOLD = 3.5
+OVERBILLED_WEIGHT_RATIO = 1.2
+MIN_LANE_ROWS_FOR_OUTLIERS = 5
+
+
+def wilson_lower_bound(successes: int, trials: int, confidence: float = 0.95) -> float | None:
+    if trials <= 0:
+        return None
+    z = NormalDist().inv_cdf(1 - (1 - confidence) / 2)
+    p = successes / trials
+    denominator = 1 + z * z / trials
+    centre = p + z * z / (2 * trials)
+    margin = z * math.sqrt(p * (1 - p) / trials + z * z / (4 * trials * trials))
+    return (centre - margin) / denominator
+
+
+def _count(n: int, one: str, many: str) -> str:
+    return f"{n} {one if n == 1 else many}"
+
+
+def _lane(record: Dict[str, Any], row: int) -> str:
+    origin = text(record, "origin", row)
+    destination = text(record, "destination", row)
+    return f"{origin}→{destination}" if origin and destination else "(all lanes)"
+
+
+def tool_score_carriers(params: Dict[str, Any]) -> Dict[str, Any]:
+    try:
+        records, source = load_records(params, "waybills")
+        records, scope = scope_records(records, params.get("owner_id"),
+                                       all_owners=bool(params.get("all_owners")))
+        confidence = float(params.get("confidence", DEFAULTS["confidence"]))
+        if not 0.5 <= confidence < 1:
+            raise ValueError("confidence must be at least 0.5 and below 1")
+        min_shipments = int(params.get("min_shipments", DEFAULTS["min_shipments"]))
+        if min_shipments < 1:
+            raise ValueError("min_shipments must be at least 1")
+
+        cells: Dict[tuple[str, str], Dict[str, Any]] = defaultdict(lambda: {
+            "shipments": 0, "total_cost": 0.0, "total_kg": 0.0, "cost_per_kg": [],
+            "on_time_known": 0, "on_time": 0, "exception_known": 0, "exceptions": 0,
+        })
+        lane_rates: Dict[str, List[tuple[float, Dict[str, Any], str]]] = defaultdict(list)
+        anomalies: List[Dict[str, Any]] = []
+
+        for row, record in enumerate(records, 1):
+            carrier = text(record, "carrier", row, required=True)
+            cost = number(record, "total_cost", row, required=True)
+            billed = number(record, "billed_weight_kg", row)
+            actual = number(record, "actual_weight_kg", row)
+            on_time = flag(record, "is_on_time", row)
+            exception = flag(record, "has_exception", row)
+            lane = _lane(record, row)
+            waybill = text(record, "waybill_no", row) or f"row {row}"
+
+            cell = cells[(lane, carrier)]
+            cell["shipments"] += 1
+            cell["total_cost"] += cost
+            weight = billed if billed else actual
+            if weight:
+                cell["total_kg"] += weight
+                rate = cost / weight
+                cell["cost_per_kg"].append(rate)
+                lane_rates[lane].append((rate, {"waybill_no": waybill, "carrier": carrier}, carrier))
+            if on_time is not None:
+                cell["on_time_known"] += 1
+                cell["on_time"] += int(on_time)
+            if exception is not None:
+                cell["exception_known"] += 1
+                cell["exceptions"] += int(exception)
+            if actual and billed and billed > actual * OVERBILLED_WEIGHT_RATIO:
+                anomalies.append({
+                    "waybill_no": waybill, "carrier": carrier, "lane": lane,
+                    "kind": "billed_weight",
+                    "detail": f"billed {billed:g} kg vs actual {actual:g} kg "
+                              f"(> {OVERBILLED_WEIGHT_RATIO - 1:.0%} over); check dimensional weight before disputing",
+                })
+
+        # Cost-per-kg outliers within each lane, expensive side only.
+        for lane, rows in lane_rates.items():
+            if len(rows) < MIN_LANE_ROWS_FOR_OUTLIERS:
+                continue
+            rates = [r for r, _, _ in rows]
+            median = statistics.median(rates)
+            deviations = [abs(r - median) for r in rates]
+            mad = statistics.median(deviations)
+            # When more than half the shipments share one rate — the normal
+            # case on a contracted lane — MAD is 0 and the modified z-score
+            # is undefined. Skipping the lane there would let a 6x overcharge
+            # through on exactly the lanes where one is easiest to see. Fall
+            # back to the mean absolute deviation, scaled so the threshold
+            # means the same thing (1.253314 · MeanAD estimates σ).
+            if mad > 0:
+                scale = mad / 0.6745
+            else:
+                mean_ad = statistics.fmean(deviations)
+                if mean_ad == 0:
+                    continue  # every shipment on the lane has the same rate
+                scale = 1.253314 * mean_ad
+            for rate, meta, carrier in rows:
+                score = (rate - median) / scale
+                if score > ANOMALY_THRESHOLD:
+                    anomalies.append({
+                        **meta, "lane": lane, "kind": "cost_per_kg",
+                        "detail": f"{rate:.2f}/kg vs lane median {median:.2f}/kg (modified z {score:.1f})",
+                    })
+
+        scorecard: List[Dict[str, Any]] = []
+        for (lane, carrier), cell in cells.items():
+            lower = wilson_lower_bound(cell["on_time"], cell["on_time_known"], confidence)
+            scorecard.append({
+                "lane": lane,
+                "carrier": carrier,
+                "shipments": cell["shipments"],
+                "on_time_rate": round(cell["on_time"] / cell["on_time_known"], 4) if cell["on_time_known"] else None,
+                "on_time_lower_bound": round(lower, 4) if lower is not None else None,
+                "on_time_sample": cell["on_time_known"],
+                "median_cost_per_kg": round(statistics.median(cell["cost_per_kg"]), 4) if cell["cost_per_kg"] else None,
+                "total_cost": round(cell["total_cost"], 2),
+                "total_kg": round(cell["total_kg"], 2),
+                "exception_rate": round(cell["exceptions"] / cell["exception_known"], 4) if cell["exception_known"] else None,
+                "rankable": cell["shipments"] >= min_shipments and lower is not None,
+            })
+
+        # Rank within each lane: reliability first, then price.
+        for lane in {c["lane"] for c in scorecard}:
+            ranked = sorted(
+                (c for c in scorecard if c["lane"] == lane and c["rankable"]),
+                key=lambda c: (-c["on_time_lower_bound"],
+                               c["median_cost_per_kg"] if c["median_cost_per_kg"] is not None else math.inf,
+                               c["carrier"]),
+            )
+            for position, entry in enumerate(ranked, 1):
+                entry["rank_in_lane"] = position
+        for entry in scorecard:
+            entry.setdefault("rank_in_lane", None)
+
+        savings: List[Dict[str, Any]] = []
+        for lane in {c["lane"] for c in scorecard}:
+            eligible = [c for c in scorecard if c["lane"] == lane and c["rankable"]
+                        and c["median_cost_per_kg"] is not None and c["total_kg"] > 0]
+            for current in eligible:
+                for alternative in eligible:
+                    if alternative is current:
+                        continue
+                    if (alternative["median_cost_per_kg"] < current["median_cost_per_kg"]
+                            and alternative["on_time_lower_bound"] >= current["on_time_lower_bound"]):
+                        estimate = current["total_kg"] * (current["median_cost_per_kg"] - alternative["median_cost_per_kg"])
+                        savings.append({
+                            "lane": lane,
+                            "from_carrier": current["carrier"],
+                            "to_carrier": alternative["carrier"],
+                            "volume_kg": current["total_kg"],
+                            "rate_difference_per_kg": round(current["median_cost_per_kg"] - alternative["median_cost_per_kg"], 4),
+                            "estimated_saving": round(estimate, 2),
+                        })
+        # Keep the best alternative per (lane, from_carrier).
+        best: Dict[tuple[str, str], Dict[str, Any]] = {}
+        for item in savings:
+            key = (item["lane"], item["from_carrier"])
+            if key not in best or item["estimated_saving"] > best[key]["estimated_saving"]:
+                best[key] = item
+        savings = sorted(best.values(), key=lambda s: -s["estimated_saving"])
+
+        scorecard.sort(key=lambda c: (c["lane"], c["rank_in_lane"] or math.inf, c["carrier"]))
+        assumptions = [
+            f"carriers ranked within each lane by the {confidence:.0%} Wilson lower bound of on-time rate, then median cost/kg",
+            f"only carrier-lane pairs with ≥ {min_shipments} shipments are ranked or used for savings",
+            "cost per kg uses billed weight where present, otherwise actual weight",
+            f"cost/kg anomaly: modified z-score > {ANOMALY_THRESHOLD} within the lane (lanes with ≥ {MIN_LANE_ROWS_FOR_OUTLIERS} weighed shipments); "
+            "MAD-based, falling back to 1.253314 × mean absolute deviation when MAD is 0",
+            f"weight anomaly: billed weight > {OVERBILLED_WEIGHT_RATIO:g} × actual",
+            "savings require the alternative to be cheaper per kg and at least as reliable; "
+            "estimate = volume × rate difference, excluding contract terms, surcharges, minimums and capacity",
+        ]
+        if scope["mode"] == "all_owners":
+            assumptions.insert(0, scope["marker"])
+
+        total_saving = round(sum(s["estimated_saving"] for s in savings), 2)
+        summary = (
+            f"{len(records)} waybills across {len({c['lane'] for c in scorecard})} lanes and "
+            f"{len({c['carrier'] for c in scorecard})} carriers ({source}); {_count(len(anomalies), 'anomaly', 'anomalies')} "
+            f"to check; {_count(len(savings), 'savings opportunity', 'savings opportunities')}, "
+            f"estimated {total_saving:,.2f} in total."
+        )
+        return {
+            "success": True,
+            "data": {"scope": scope, "scorecard": scorecard, "anomalies": anomalies,
+                     "savings": savings, "estimated_total_saving": total_saving,
+                     "assumptions": assumptions},
+            "source": source,
+            "summary": summary,
+        }
+    except (OSError, ValueError, TypeError, TenancyError) as exc:
+        return {"success": False, "error": str(exc)}
+
+
+SCHEMA = {
+    "name": "score_carriers",
+    "description": (
+        "Carrier scorecard by lane (on-time rate with a confidence lower bound, median cost/kg, "
+        "exception rate), freight cost anomalies and like-for-like savings, from supplied "
+        "waybills. Refuses to mix shippers' data unless told which one."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "file_path": {"type": "string", "description": "CSV or JSON file of waybills"},
+            "waybills": {"type": "array", "description": "Waybills: carrier, total_cost, origin, destination, billed_weight_kg, is_on_time"},
+            "min_shipments": {"type": "integer", "description": "Minimum shipments for a carrier-lane to be ranked, default 20"},
+            **owner_params_schema(),
+        },
+    },
+}

aria_bots/logistics/freight.py

@@ -0,0 +1,154 @@
+"""Auditable freight analysis from supplied waybills or an existing local database."""
+
+from __future__ import annotations
+
+import csv
+import json
+import math
+import pathlib
+import sqlite3
+from collections import defaultdict
+from contextlib import closing
+from typing import Any, Dict, List
+
+
+def _number(record: dict[str, Any], field: str, row: int, *, required: bool = False) -> float | None:
+    value = record.get(field)
+    if value is None or value == "":
+        if required:
+            raise ValueError(f"Row {row}: {field} is required")
+        return None
+    if isinstance(value, bool):
+        raise ValueError(f"Row {row}: {field} must be a number")
+    try:
+        number = float(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"Row {row}: {field} must be a number") from exc
+    if not math.isfinite(number) or number < 0:
+        raise ValueError(f"Row {row}: {field} must be finite and non-negative")
+    return number
+
+
+def _on_time(value: Any, row: int) -> bool | None:
+    if value is None or value == "":
+        return None
+    if isinstance(value, bool):
+        return value
+    if value in (0, 1):
+        return bool(value)
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"true", "yes", "1"}:
+            return True
+        if normalized in {"false", "no", "0"}:
+            return False
+    raise ValueError(f"Row {row}: is_on_time must be a boolean")
+
+
+def tool_analyze_logistics_data(params: Dict[str, Any]) -> Dict[str, Any]:
+    """Analyze actual records. Empty input never produces representative data."""
+    try:
+        file_path = params.get("file_path")
+        records = params.get("waybills")
+        if file_path and records is not None:
+            raise ValueError("Provide either file_path or waybills, not both")
+        if file_path:
+            path = pathlib.Path(file_path).expanduser().resolve()
+            if path.suffix.lower() == ".json":
+                content = json.loads(path.read_text(encoding="utf-8"))
+                records = content if isinstance(content, list) else content.get("waybills") if isinstance(content, dict) else None
+            elif path.suffix.lower() == ".csv":
+                with path.open(encoding="utf-8-sig", newline="") as handle:
+                    records = list(csv.DictReader(handle))
+            else:
+                raise ValueError("Only CSV and JSON waybill files are supported")
+            source = str(path)
+            data_source = f"file:{path.name}"
+        elif records is None:
+            path = pathlib.Path.home() / ".aria" / "erp_warehouse.db"
+            if not path.is_file():
+                raise ValueError("No waybills supplied and no local logistics database found")
+            with closing(sqlite3.connect(f"{path.as_uri()}?mode=ro", uri=True)) as connection:
+                connection.row_factory = sqlite3.Row
+                records = [dict(row) for row in connection.execute("SELECT * FROM logistics_waybills")]
+            source = str(path)
+            data_source = "local logistics database"
+        else:
+            source = "provided_waybills"
+            data_source = "caller-supplied records"
+
+        if not isinstance(records, list) or not records:
+            raise ValueError("No waybill records available for analysis")
+
+        # Before this, every shipper's waybills were summed into one spend
+        # figure and one carrier table — a 3PL report built from all its
+        # clients' commercial data. See logistics_tenancy for the rules.
+        from .tenancy import scope_records
+        records, scope = scope_records(records, params.get("owner_id"),
+                                       all_owners=bool(params.get("all_owners")))
+
+        spend = 0.0
+        known_delivery = 0
+        on_time = 0
+        carriers: dict[str, dict[str, Any]] = defaultdict(lambda: {"count": 0, "total_spend": 0.0, "known_delivery_count": 0, "on_time_count": 0})
+        anomalies: list[dict[str, Any]] = []
+        for row, record in enumerate(records, 1):
+            if not isinstance(record, dict):
+                raise ValueError(f"Row {row}: waybill must be an object")
+            cost = _number(record, "total_cost", row, required=True)
+            assert cost is not None
+            actual = _number(record, "actual_weight_kg", row)
+            billed = _number(record, "billed_weight_kg", row)
+            timely = _on_time(record.get("is_on_time"), row)
+            carrier = str(record.get("carrier") or "Unknown")
+            spend += cost
+            carriers[carrier]["count"] += 1
+            carriers[carrier]["total_spend"] += cost
+            if timely is not None:
+                known_delivery += 1
+                on_time += int(timely)
+                carriers[carrier]["known_delivery_count"] += 1
+                carriers[carrier]["on_time_count"] += int(timely)
+            if actual is not None and billed is not None and actual > 0 and billed > actual * 1.2:
+                anomalies.append({"waybill_no": record.get("waybill_no"), "carrier": carrier, "actual_weight_kg": actual, "billed_weight_kg": billed, "reason": "Billed weight exceeds actual weight by more than 20%; verify dimensional weight before disputing"})
+
+        metrics = []
+        for carrier, item in sorted(carriers.items()):
+            item["total_spend"] = round(item["total_spend"], 2)
+            item["on_time_rate"] = round(item["on_time_count"] / item["known_delivery_count"] * 100, 2) if item["known_delivery_count"] else None
+            metrics.append({"carrier": carrier, **item})
+        rate = round(on_time / known_delivery * 100, 2) if known_delivery else None
+        result = {"scope": scope, "total_waybills": len(records), "total_freight_spend": round(spend, 2), "overall_on_time_rate": rate, "known_delivery_count": known_delivery, "carrier_metrics": metrics, "billing_anomalies": anomalies, "data_source": data_source}
+        rate_label = f"{rate}%" if rate is not None else "不可得（无准时状态记录）"
+        return {"success": True, "data": result, "source": source, "summary": f"已审计 {len(records)} 单运单（来源：{data_source}），运费总计 ¥{spend:,.2f}，已知准时交付率 {rate_label}，发现 {len(anomalies)} 笔需核实的计费重量异常。"}
+    except (OSError, sqlite3.Error, ValueError, TypeError, json.JSONDecodeError) as exc:
+        # TenancyError is a ValueError, so a refusal to mix shippers lands here.
+        return {"success": False, "error": str(exc)}
+
+
+def register_logistics_tools(tools_dict: Dict[str, Any], schemas_list: List[Dict[str, Any]]) -> int:
+    """Register the logistics analyses as local tools."""
+    from .tenancy import owner_params_schema
+
+    tools_dict["analyze_logistics_data"] = (tool_analyze_logistics_data, "Analyze supplied freight waybills and billing anomalies")
+    schemas_list.append({
+        "name": "analyze_logistics_data",
+        "description": "Analyze actual waybills from supplied records, a CSV/JSON file, or an existing local database",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "file_path": {"type": "string", "description": "CSV or JSON waybill file path"},
+                "waybills": {"type": "array", "description": "Waybill records with total_cost"},
+                **owner_params_schema(),
+            },
+        },
+    })
+
+    from .carriers import SCHEMA as _carrier_schema, tool_score_carriers
+    from .inventory import SCHEMA as _inventory_schema, tool_plan_inventory_policy
+
+    tools_dict["plan_inventory_policy"] = (tool_plan_inventory_policy, _inventory_schema["description"])
+    schemas_list.append(_inventory_schema)
+    tools_dict["score_carriers"] = (tool_score_carriers, _carrier_schema["description"])
+    schemas_list.append(_carrier_schema)
+    return 3

aria_bots/logistics/inventory.py

@@ -0,0 +1,242 @@
+"""Inventory policy for a 3PL: when to reorder, how much, and what is stuck.
+
+Everything here is a standard, published formula, applied to the records the
+caller supplies, with the formula and every threshold written into the result
+so a client can recompute any number by hand:
+
+    z            = Φ⁻¹(service level)
+    safety stock = z · √(L·σ_d² + d̄²·σ_L²)        demand and lead-time variability
+    reorder point= d̄·L + safety stock
+    order-up-to  = reorder point + d̄·R              R = review period
+    order qty    = order-up-to − inventory position, when position ≤ reorder point
+    position     = on hand + on order − backordered
+
+ABC ranks a shipper's SKUs by annual consumption value (Pareto 80/95), XYZ by
+the coefficient of variation of daily demand (0.5 / 1.0). Movement status
+comes from days since last movement (30 slow, 90 dead).
+
+What it will not do is guess. A SKU with less demand history than
+`min_history_days` gets no safety stock and no reorder point — it is reported
+as insufficient history, because a policy computed from a handful of days
+would be confidently wrong, and a reorder quantity is money.
+"""
+
+from __future__ import annotations
+
+import math
+import statistics
+from collections import defaultdict
+from statistics import NormalDist
+from typing import Any, Dict, List
+
+from .records import load_records, number, series, text
+from .tenancy import OWNER_FIELD, TenancyError, owner_params_schema, scope_records
+
+DEFAULTS = {
+    "service_level": 0.95,
+    "review_period_days": 7.0,
+    "min_history_days": 14,
+    "slow_days": 30.0,
+    "dead_days": 90.0,
+    "excess_cover_days": 180.0,
+}
+ABC_BOUNDS = (0.80, 0.95)
+XYZ_BOUNDS = (0.5, 1.0)
+
+
+def _setting(params: Dict[str, Any], key: str) -> float:
+    value = params.get(key, DEFAULTS[key])
+    try:
+        value = float(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{key} must be a number") from exc
+    if not math.isfinite(value) or value < 0:
+        raise ValueError(f"{key} must be finite and non-negative")
+    return value
+
+
+def _demand(record: Dict[str, Any], row: int) -> tuple[float, float, int] | None:
+    """(mean, sample std, days of history), from a daily series or from aggregates."""
+    history = series(record, "daily_demand", row)
+    if history is not None:
+        if len(history) < 2:
+            return (history[0] if history else 0.0), 0.0, len(history)
+        return statistics.fmean(history), statistics.stdev(history), len(history)
+    mean = number(record, "demand_mean", row)
+    if mean is None:
+        return None
+    std = number(record, "demand_std", row) or 0.0
+    days = number(record, "demand_days", row)
+    return mean, std, int(days) if days is not None else 0
+
+
+def _abc(items: List[Dict[str, Any]]) -> None:
+    """Assign ABC within each shipper's portfolio, by annual consumption value."""
+    by_owner: Dict[str, List[Dict[str, Any]]] = defaultdict(list)
+    for item in items:
+        if item["annual_value"] is not None:
+            by_owner[item.get(OWNER_FIELD) or ""].append(item)
+    for group in by_owner.values():
+        total = sum(i["annual_value"] for i in group)
+        if total <= 0:
+            continue
+        cumulative = 0.0
+        for item in sorted(group, key=lambda i: (-i["annual_value"], i["sku"])):
+            share_before = cumulative / total
+            item["abc"] = "A" if share_before < ABC_BOUNDS[0] else "B" if share_before < ABC_BOUNDS[1] else "C"
+            cumulative += item["annual_value"]
+
+
+def tool_plan_inventory_policy(params: Dict[str, Any]) -> Dict[str, Any]:
+    try:
+        records, source = load_records(params, "skus")
+        records, scope = scope_records(records, params.get("owner_id"),
+                                       all_owners=bool(params.get("all_owners")))
+
+        service_level = _setting(params, "service_level")
+        if not 0.5 <= service_level < 1:
+            raise ValueError("service_level must be at least 0.5 and below 1")
+        review = _setting(params, "review_period_days")
+        min_history = int(_setting(params, "min_history_days"))
+        slow_days = _setting(params, "slow_days")
+        dead_days = _setting(params, "dead_days")
+        excess_days = _setting(params, "excess_cover_days")
+        z = NormalDist().inv_cdf(service_level)
+
+        items: List[Dict[str, Any]] = []
+        for row, record in enumerate(records, 1):
+            sku = text(record, "sku", row, required=True)
+            on_hand = number(record, "on_hand", row, required=True)
+            on_order = number(record, "on_order", row) or 0.0
+            backorder = number(record, "backorder", row) or 0.0
+            lead = number(record, "lead_time_days", row, required=True, positive=True)
+            lead_std = number(record, "lead_time_std_days", row) or 0.0
+            unit_cost = number(record, "unit_cost", row)
+            idle_days = number(record, "days_since_last_movement", row)
+            demand = _demand(record, row)
+            if demand is None:
+                raise ValueError(f"Row {row}: daily_demand (or demand_mean) is required")
+            mean, std, history_days = demand
+            position = on_hand + on_order - backorder
+
+            item: Dict[str, Any] = {
+                OWNER_FIELD: text(record, OWNER_FIELD, row) or None,
+                "warehouse_id": text(record, "warehouse_id", row) or None,
+                "sku": sku,
+                "on_hand": on_hand,
+                "inventory_position": round(position, 2),
+                "avg_daily_demand": round(mean, 4),
+                "demand_std": round(std, 4),
+                "history_days": history_days,
+                "lead_time_days": lead,
+                "safety_stock": None,
+                "reorder_point": None,
+                "order_up_to": None,
+                "suggested_order_qty": 0,
+                "days_of_cover": round(on_hand / mean, 1) if mean > 0 else None,
+                "abc": None,
+                "xyz": None,
+                "movement": None,
+                "flags": [],
+                "annual_value": round(mean * 365 * unit_cost, 2) if unit_cost is not None else None,
+            }
+
+            if mean > 0:
+                cv = std / mean
+                item["xyz"] = "X" if cv <= XYZ_BOUNDS[0] else "Y" if cv <= XYZ_BOUNDS[1] else "Z"
+
+            if idle_days is not None:
+                item["movement"] = ("dead" if idle_days >= dead_days
+                                    else "slow" if idle_days >= slow_days else "active")
+
+            if mean == 0:
+                item["action"] = "no_demand"
+                if on_hand > 0:
+                    item["flags"].append("stock held with no demand in the history")
+            elif history_days < min_history:
+                item["action"] = "insufficient_history"
+                item["flags"].append(
+                    f"{history_days} days of demand history; at least {min_history} are needed "
+                    f"for a safety stock that means anything"
+                )
+            else:
+                safety = z * math.sqrt(lead * std ** 2 + mean ** 2 * lead_std ** 2)
+                reorder_point = mean * lead + safety
+                order_up_to = reorder_point + mean * review
+                # Rounded up: a fractional unit cannot be held, and rounding the
+                # buffer down would quietly lower the service level.
+                item["safety_stock"] = math.ceil(safety)
+                item["reorder_point"] = math.ceil(reorder_point)
+                item["order_up_to"] = math.ceil(order_up_to)
+                if position <= reorder_point:
+                    item["action"] = "reorder"
+                    item["suggested_order_qty"] = max(0, math.ceil(order_up_to - position))
+                else:
+                    item["action"] = "ok"
+
+            if item["days_of_cover"] is not None and item["days_of_cover"] > excess_days:
+                item["flags"].append(f"{item['days_of_cover']:g} days of cover exceeds {excess_days:g}")
+            items.append(item)
+
+        _abc(items)
+
+        order = {"reorder": 0, "insufficient_history": 1, "no_demand": 2, "ok": 3}
+        items.sort(key=lambda i: (order[i["action"]],
+                                  i["days_of_cover"] if i["days_of_cover"] is not None else math.inf,
+                                  i["sku"]))
+
+        counts = defaultdict(int)
+        for item in items:
+            counts[item["action"]] += 1
+        dead = sum(1 for i in items if i["movement"] == "dead")
+        slow = sum(1 for i in items if i["movement"] == "slow")
+
+        assumptions = [
+            f"service level {service_level:.1%} → z = {z:.3f}",
+            "safety stock = z·√(L·σ_d² + d̄²·σ_L²); reorder point = d̄·L + safety stock",
+            f"order-up-to = reorder point + d̄·{review:g} (review period, days)",
+            "inventory position = on hand + on order − backordered",
+            "safety stock, reorder point and order quantity rounded up to whole units",
+            f"no policy below {min_history} days of demand history",
+            f"ABC by annual consumption value within each shipper (A < {ABC_BOUNDS[0]:.0%}, B < {ABC_BOUNDS[1]:.0%} cumulative)",
+            f"XYZ by demand CV (X ≤ {XYZ_BOUNDS[0]}, Y ≤ {XYZ_BOUNDS[1]}, Z above)",
+            f"movement: slow ≥ {slow_days:g} days idle, dead ≥ {dead_days:g}",
+            "capacity, MOQs, case packs and supplier terms are not modelled",
+        ]
+        if scope["mode"] == "all_owners":
+            assumptions.insert(0, scope["marker"])
+
+        summary = (
+            f"{len(items)} {'SKU' if len(items) == 1 else 'SKUs'} analysed ({source}): {counts['reorder']} to reorder, "
+            f"{counts['insufficient_history']} with too little history, {counts['no_demand']} "
+            f"with no demand; {dead} dead and {slow} slow-moving."
+        )
+        return {
+            "success": True,
+            "data": {"scope": scope, "items": items, "counts": dict(counts),
+                     "dead_stock": dead, "slow_stock": slow, "assumptions": assumptions},
+            "source": source,
+            "summary": summary,
+        }
+    except (OSError, ValueError, TypeError, TenancyError) as exc:
+        return {"success": False, "error": str(exc)}
+
+
+SCHEMA = {
+    "name": "plan_inventory_policy",
+    "description": (
+        "Reorder points, safety stock, order quantities, ABC/XYZ classes and dead/slow stock "
+        "for a shipper's SKUs, from supplied demand history and lead times. Formulas are "
+        "stated in the result. Refuses to mix shippers' data unless told which one."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "file_path": {"type": "string", "description": "CSV or JSON file of SKU records"},
+            "skus": {"type": "array", "description": "SKU records: sku, on_hand, lead_time_days, daily_demand"},
+            "service_level": {"type": "number", "description": "Target cycle service level, default 0.95"},
+            "review_period_days": {"type": "number", "description": "Days between reviews, default 7"},
+            **owner_params_schema(),
+        },
+    },
+}