hepyy-workflows 0.1.0__py3-none-any.whl

hepyy_workflows/__init__.py

@@ -0,0 +1,3 @@
+"""Source-neutral contracts and services for HEP workflows."""
+
+__version__ = "0.1.0.dev0"

hepyy_workflows/agent/__init__.py

@@ -0,0 +1,5 @@
+"""Optional narrow agent integration."""
+
+from .service import dispatch
+
+__all__ = ["dispatch"]

hepyy_workflows/agent/service.py

@@ -0,0 +1,80 @@
+"""Stable JSON operations for agents and ordinary automation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from hepyy_workflows.analysis.runner import prepare_recipe, run_recipe
+from hepyy_workflows.export.standalone import export_recipe
+from hepyy_workflows.readers.scaffold import scaffold_reader
+from hepyy_workflows.readers.service import (
+    draft_reader,
+    inspect_input,
+    preview_reader,
+    validate_reader,
+    write_draft,
+)
+from hepyy_workflows.reporting.report import build_report
+
+
+def _paths(values: list[str] | None) -> list[Path]:
+    return [Path(value) for value in values or []]
+
+
+def _error(error: Exception, code: str = "AGENT_FAILED") -> dict[str, Any]:
+    return {
+        "valid": False,
+        "diagnostics": [
+            {
+                "code": getattr(error, "code", code),
+                "path": getattr(error, "path", "/"),
+                "message": str(error),
+            }
+        ],
+    }
+
+
+def dispatch(method: str, params: dict[str, Any]) -> dict[str, Any]:
+    try:
+        if method == "inspect_input":
+            return inspect_input(Path(params["input"]))
+        if method == "draft_reader":
+            if "output" in params:
+                return write_draft(Path(params["input"]), Path(params["output"]))
+            draft, inspection = draft_reader(Path(params["input"]))
+            return {**inspection, "draft": draft}
+        if method == "validate_reader":
+            return validate_reader(Path(params["reader"]), _paths(params.get("inputs")))
+        if method == "preview_reader":
+            return preview_reader(
+                Path(params["reader"]), _paths(params.get("inputs")), int(params.get("events", 10))
+            )
+        if method == "validate_recipe":
+            _, _, prepared = prepare_recipe(Path(params["recipe"]), params.get("inputs"))
+            return {
+                "valid": True,
+                "inputs": {k: [str(p) for p in v] for k, v in prepared["paths"].items()},
+            }
+        if method == "run_analysis":
+            return run_recipe(
+                Path(params["recipe"]),
+                Path(params["output"]),
+                params.get("inputs"),
+                params.get("max_events"),
+            )
+        if method == "export_standalone":
+            return export_recipe(
+                Path(params["recipe"]), Path(params["output"]), params.get("inputs")
+            )
+        if method == "build_report":
+            return build_report(Path(params["results"]), Path(params["output"]))
+        if method == "scaffold_reader":
+            return scaffold_reader(params["name"], Path(params["output"]))
+        if method == "get_status":
+            return {"valid": True, "status": "idle", "diagnostics": []}
+        if method == "cancel_run":
+            return _error(ValueError("no asynchronous run is active"), "NO_ACTIVE_RUN")
+        return _error(ValueError(f"unknown method: {method}"), "METHOD_UNKNOWN")
+    except Exception as error:
+        return _error(error)

hepyy_workflows/agent/stdio.py

@@ -0,0 +1,54 @@
+"""Line-delimited JSON agent interface; no shell or arbitrary code endpoint."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from .service import dispatch
+
+_METHODS = (
+    "inspect_input",
+    "draft_reader",
+    "validate_reader",
+    "preview_reader",
+    "validate_recipe",
+    "run_analysis",
+    "export_standalone",
+    "build_report",
+    "scaffold_reader",
+    "get_status",
+    "cancel_run",
+)
+
+
+def serve_stdio() -> int:
+    for line in sys.stdin:
+        if not line.strip():
+            continue
+        try:
+            request = json.loads(line)
+            if not isinstance(request, dict) or not isinstance(request.get("method"), str):
+                raise ValueError("request needs a method")
+            method = request["method"]
+            if method == "initialize":
+                result = {
+                    "protocolVersion": "2025-03-26",
+                    "serverInfo": {"name": "hwf", "version": "1"},
+                }
+            elif method == "tools/list":
+                result = {
+                    "tools": [
+                        {"name": name, "description": f"HWF {name} operation"} for name in _METHODS
+                    ]
+                }
+            elif method == "tools/call":
+                params = request.get("params", {})
+                result = dispatch(params["name"], params.get("arguments", {}))
+            else:
+                result = dispatch(method, request.get("params", {}))
+            response = {"id": request.get("id"), "result": result}
+        except Exception as error:
+            response = {"id": None, "error": {"code": "REQUEST_INVALID", "message": str(error)}}
+        print(json.dumps(response, default=str), flush=True)
+    return 0

hepyy_workflows/analysis/__init__.py

@@ -0,0 +1,5 @@
+"""Generic recipe analysis services."""
+
+from .runner import RecipeError, prepare_recipe, run_recipe
+
+__all__ = ["RecipeError", "prepare_recipe", "run_recipe"]

hepyy_workflows/analysis/expressions.py

@@ -0,0 +1,184 @@
+"""Small, side-effect-free expression evaluator for recipe values."""
+
+from __future__ import annotations
+
+import ast
+import math
+import operator
+from functools import lru_cache
+from typing import Any
+
+
+class ExpressionError(ValueError):
+    pass
+
+
+def wrapped_angle(value: float) -> float:
+    return math.atan2(math.sin(value), math.cos(value))
+
+
+_FUNCTIONS = {
+    "abs": abs,
+    "sqrt": math.sqrt,
+    "log": math.log,
+    "log10": math.log10,
+    "sin": math.sin,
+    "cos": math.cos,
+    "tan": math.tan,
+    "atan2": math.atan2,
+    "hypot": math.hypot,
+    "wrapped_angle": wrapped_angle,
+    "isfinite": math.isfinite,
+    "min": min,
+    "max": max,
+}
+_BINARY = {
+    ast.Add: operator.add,
+    ast.Sub: operator.sub,
+    ast.Mult: operator.mul,
+    ast.Div: operator.truediv,
+    ast.Pow: math.pow,
+    ast.Mod: operator.mod,
+}
+_COMPARE = {
+    ast.Eq: operator.eq,
+    ast.NotEq: operator.ne,
+    ast.Lt: operator.lt,
+    ast.LtE: operator.le,
+    ast.Gt: operator.gt,
+    ast.GtE: operator.ge,
+    ast.Is: operator.is_,
+    ast.IsNot: operator.is_not,
+}
+
+
+@lru_cache(maxsize=1024)
+def compile_expression(source: str) -> ast.Expression:
+    try:
+        tree = ast.parse(source, mode="eval")
+    except SyntaxError as exc:
+        raise ExpressionError(f"invalid expression {source!r}: {exc.msg}") from exc
+    _check(tree.body)
+    return tree
+
+
+def referenced_names(source: str) -> set[str]:
+    """Return field/parameter roots, excluding whitelisted function names."""
+
+    tree = compile_expression(source)
+    names = {node.id for node in ast.walk(tree) if isinstance(node, ast.Name)}
+    calls = {
+        node.func.id
+        for node in ast.walk(tree)
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Name)
+    }
+    return names - calls
+
+
+def _path(node: ast.AST) -> str | None:
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        parent = _path(node.value)
+        return None if parent is None else parent + "." + node.attr
+    return None
+
+
+def _check(node: ast.AST) -> None:
+    if isinstance(node, ast.Constant):
+        if not isinstance(node.value, (int, float, str, bool, type(None))):
+            raise ExpressionError("unsupported literal")
+    elif isinstance(node, (ast.Name, ast.Attribute)):
+        if _path(node) is None or any(part.startswith("_") for part in _path(node).split(".")):
+            raise ExpressionError("private or dynamic field access is forbidden")
+    elif isinstance(node, ast.BinOp) and type(node.op) in _BINARY:
+        _check(node.left)
+        _check(node.right)
+    elif isinstance(node, ast.UnaryOp) and isinstance(node.op, (ast.USub, ast.UAdd, ast.Not)):
+        _check(node.operand)
+    elif isinstance(node, ast.BoolOp) and isinstance(node.op, (ast.And, ast.Or)):
+        for value in node.values:
+            _check(value)
+    elif isinstance(node, ast.Compare) and all(type(op) in _COMPARE for op in node.ops):
+        _check(node.left)
+        for item in node.comparators:
+            _check(item)
+    elif isinstance(node, ast.Call) and isinstance(node.func, ast.Name):
+        if node.func.id not in _FUNCTIONS or node.keywords:
+            raise ExpressionError("function is not allowed")
+        for item in node.args:
+            _check(item)
+    else:
+        raise ExpressionError(f"unsupported expression element: {type(node).__name__}")
+
+
+def field(context: dict, path: str) -> Any:
+    if path in context:
+        return context[path]
+    parts = path.split(".")
+    for start in range(len(parts), 0, -1):
+        prefix = ".".join(parts[:start])
+        if prefix in context:
+            value = context[prefix]
+            for part in parts[start:]:
+                if not isinstance(value, dict):
+                    return None
+                value = value.get(part)
+            return value
+    return None
+
+
+def evaluate(source: str, context: dict) -> Any:
+    tree = compile_expression(source)
+
+    def visit(node: ast.AST) -> Any:
+        if isinstance(node, ast.Constant):
+            return node.value
+        if isinstance(node, (ast.Name, ast.Attribute)):
+            return field(context, _path(node))
+        if isinstance(node, ast.BinOp):
+            left, right = visit(node.left), visit(node.right)
+            if left is None or right is None:
+                return None
+            if not isinstance(left, (int, float)) or not isinstance(right, (int, float)):
+                return None
+            try:
+                value = _BINARY[type(node.op)](left, right)
+            except (ArithmeticError, OverflowError, TypeError, ValueError):
+                return None
+            return value if not isinstance(value, float) or math.isfinite(value) else None
+        if isinstance(node, ast.UnaryOp):
+            value = visit(node.operand)
+            if isinstance(node.op, ast.Not):
+                return not bool(value)
+            return None if value is None else (-value if isinstance(node.op, ast.USub) else +value)
+        if isinstance(node, ast.BoolOp):
+            if isinstance(node.op, ast.And):
+                return all(bool(visit(item)) for item in node.values)
+            return any(bool(visit(item)) for item in node.values)
+        if isinstance(node, ast.Compare):
+            left = visit(node.left)
+            for op, right_node in zip(node.ops, node.comparators, strict=True):
+                right = visit(right_node)
+                if left is None or right is None:
+                    if not isinstance(op, (ast.Is, ast.IsNot, ast.Eq, ast.NotEq)):
+                        return False
+                try:
+                    if not _COMPARE[type(op)](left, right):
+                        return False
+                except TypeError:
+                    return False
+                left = right
+            return True
+        if isinstance(node, ast.Call):
+            args = [visit(item) for item in node.args]
+            if any(item is None for item in args):
+                return None
+            try:
+                value = _FUNCTIONS[node.func.id](*args)
+            except (ArithmeticError, OverflowError, TypeError, ValueError):
+                return None
+            return value if not isinstance(value, float) or math.isfinite(value) else None
+        raise AssertionError("expression was not checked")
+
+    return visit(tree.body)

hepyy_workflows/analysis/histograms.py

@@ -0,0 +1,166 @@
+"""Streaming weighted histograms with event-clustered covariance."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+
+class HistogramError(ValueError):
+    pass
+
+
+def axis_edges(spec: dict, observed: tuple[float, float] | None = None) -> np.ndarray:
+    bins = spec["bins"]
+    if "edges" in bins:
+        if len(bins["edges"]) > 4097:
+            raise HistogramError("axis has more than 4096 bins")
+        edges = np.asarray(bins["edges"], dtype=float)
+    else:
+        if "automatic" in bins:
+            if observed is None:
+                raise HistogramError("automatic axis requires a bounded discovery pass")
+            definition = bins["automatic"]
+            low, high = observed
+            if low == high:
+                low, high = (
+                    (low / math.sqrt(10), high * math.sqrt(10))
+                    if low > 0
+                    else (low - 0.5, high + 0.5)
+                )
+        else:
+            definition = bins
+            low, high = float(definition["low"]), float(definition["high"])
+        if definition["count"] > 4096:
+            raise HistogramError("axis has more than 4096 bins")
+        if definition.get("scale", "linear") == "log":
+            if low <= 0:
+                raise HistogramError("logarithmic axis requires positive limits")
+            edges = np.geomspace(low, high, definition["count"] + 1)
+        else:
+            edges = np.linspace(low, high, definition["count"] + 1)
+    if len(edges) < 2 or not np.all(np.isfinite(edges)) or not np.all(np.diff(edges) > 0):
+        raise HistogramError("axis edges must be finite and strictly increasing")
+    return edges
+
+
+@dataclass(slots=True)
+class Flow:
+    count: int = 0
+    sumw: float = 0.0
+    sumw2: float = 0.0
+
+    def add(self, weight: float) -> None:
+        self.count += 1
+        self.sumw += weight
+        self.sumw2 += weight * weight
+
+
+class Histogram:
+    """One reducer keyed by histogram, categories and optional slice."""
+
+    def __init__(self, axes: list[np.ndarray]) -> None:
+        self.axes = axes
+        self.shape = tuple(len(axis) - 1 for axis in axes)
+        self.size = math.prod(self.shape)
+        if not 1 <= self.size <= 256:
+            raise HistogramError("histogram must have 1 to 256 cells for covariance")
+        self.count = np.zeros(self.size, dtype=np.int64)
+        self.sumw = np.zeros(self.size)
+        self.sumw2 = np.zeros(self.size)
+        self.event_cross = np.zeros((self.size, self.size))
+        self.event_total_cross = np.zeros(self.size)
+        self.event_total2 = 0.0
+        self.events = 0
+        self.entries = 0
+        self.flows = {name: Flow() for name in ("underflow", "overflow", "invalid")}
+
+    def _cell(self, values: tuple[Any, ...]) -> int | str:
+        if len(values) != len(self.axes):
+            return "invalid"
+        if any(not isinstance(value, (int, float)) or not math.isfinite(value) for value in values):
+            return "invalid"
+        indices = []
+        for value, edges in zip(values, self.axes, strict=True):
+            if value < edges[0]:
+                return "underflow"
+            if value > edges[-1]:
+                return "overflow"
+            indices.append(
+                min(int(np.searchsorted(edges, value, side="right") - 1), len(edges) - 2)
+            )
+        return int(np.ravel_multi_index(tuple(indices), self.shape))
+
+    def add_event(self, entries: list[tuple[tuple[Any, ...], float]]) -> None:
+        contribution = np.zeros(self.size)
+        for values, weight in entries:
+            self.entries += 1
+            if not isinstance(weight, (int, float)) or not math.isfinite(weight):
+                self.flows["invalid"].count += 1
+                continue
+            cell = self._cell(values)
+            if isinstance(cell, str):
+                self.flows[cell].add(float(weight))
+            else:
+                self.count[cell] += 1
+                self.sumw[cell] += weight
+                self.sumw2[cell] += weight * weight
+                contribution[cell] += weight
+        active = np.flatnonzero(contribution)
+        if len(active):
+            self.event_cross[np.ix_(active, active)] += np.outer(
+                contribution[active], contribution[active]
+            )
+        total = float(contribution.sum())
+        self.event_total_cross += contribution * total
+        self.event_total2 += total * total
+        self.events += 1
+
+    def result(self) -> dict:
+        total = float(self.sumw.sum())
+        widths = np.diff(self.axes[0])
+        if len(self.axes) == 2:
+            widths = np.outer(widths, np.diff(self.axes[1])).reshape(-1)
+        if total == 0:
+            normalized = density = normalized_error = density_error = None
+            covariance = None
+        else:
+            normalized_values = self.sumw / total
+            normalized = normalized_values.tolist()
+            density = (normalized_values / widths).tolist()
+            if self.events > 1:
+                residual = (
+                    self.event_cross
+                    - np.outer(self.event_total_cross, normalized_values)
+                    - np.outer(normalized_values, self.event_total_cross)
+                    + self.event_total2 * np.outer(normalized_values, normalized_values)
+                )
+                covariance_array = self.events / (self.events - 1) * residual / total**2
+                covariance = covariance_array.tolist()
+                normalized_error = np.sqrt(np.maximum(np.diag(covariance_array), 0)).tolist()
+                density_error = (np.asarray(normalized_error) / widths).tolist()
+            else:
+                covariance = normalized_error = density_error = None
+        return {
+            "edges": [axis.tolist() for axis in self.axes],
+            "shape": self.shape,
+            "count": self.count.tolist(),
+            "sumw": self.sumw.tolist(),
+            "sumw2": self.sumw2.tolist(),
+            "error": np.sqrt(np.diag(self.event_cross)).tolist(),
+            "normalized": normalized,
+            "normalized_error": normalized_error,
+            "density": density,
+            "density_error": density_error,
+            "normalized_covariance": covariance,
+            "flows": {
+                name: {"count": flow.count, "sumw": flow.sumw, "sumw2": flow.sumw2}
+                for name, flow in self.flows.items()
+            },
+            "entries": self.entries,
+            "events": self.events,
+            "uncertainty": "event-clustered",
+        }