lantern-harness 0.1.0__py3-none-any.whl

harness/__init__.py

@@ -0,0 +1,53 @@
+"""Public API for the minimal multi-step execution engine."""
+
+from .agent import Agent, Harness
+from .context import (
+    ContextBundle,
+    ExecutionContext,
+    MissingContextFileError,
+    load_context_files,
+)
+from .contracts import Contract, ContractViolationError
+from .core import (
+    Flow,
+    GotoTargetError,
+    MaxJumpsExceeded,
+    Runtime,
+    Step,
+    StepExecutionError,
+)
+from .routing import Goto
+from .flow_loader import FlowLoadError, load_flow
+from .governance import PolicyDecision, PolicyEngine, PolicyRule, PolicyViolation
+from .anomaly import Baseline, find_anomalies
+from .trace_viewer import load_traces, print_trace
+from .tracing import Tracer
+
+__all__ = [
+    "Agent",
+    "Baseline",
+    "ContextBundle",
+    "Contract",
+    "ContractViolationError",
+    "ExecutionContext",
+    "Flow",
+    "FlowLoadError",
+    "Goto",
+    "GotoTargetError",
+    "Harness",
+    "MaxJumpsExceeded",
+    "MissingContextFileError",
+    "PolicyDecision",
+    "PolicyEngine",
+    "PolicyRule",
+    "PolicyViolation",
+    "Runtime",
+    "Step",
+    "StepExecutionError",
+    "Tracer",
+    "find_anomalies",
+    "load_context_files",
+    "load_flow",
+    "load_traces",
+    "print_trace",
+]

harness/agent.py

@@ -0,0 +1,48 @@
+"""Beginner-friendly façade over the Runtime/Flow/Step primitives."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from .core import Flow, Runtime, Step
+
+
+class Agent(Protocol):
+    """Documentary protocol for a single-input agent.
+
+    This is duck-typing documentation only. An agent does NOT need to inherit
+    from this protocol, import it, or reference any Lantern type in its own
+    code — any object with a ``run(input)`` method (or any plain callable)
+    satisfies the expectation at runtime.
+    """
+
+    def run(self, input: Any) -> Any: ...
+
+
+class Harness:
+    """Wrap a single agent/callable or an existing :class:`Flow` behind ``run``.
+
+    ``Harness(agent)`` builds a one-step flow around ``agent.run`` (or the
+    callable itself) and delegates to :class:`Runtime`. ``Harness(flow)`` wraps
+    a multi-step flow directly. All :class:`Runtime` keyword options are
+    accepted and forwarded unchanged, so checkpointing, tracing, retries, run
+    ids, and jump limits all keep working.
+    """
+
+    def __init__(self, agent_or_flow: Any, **runtime_options: Any) -> None:
+        if isinstance(agent_or_flow, Flow):
+            self._flow = agent_or_flow
+        elif callable(getattr(agent_or_flow, "run", None)):
+            self._flow = Flow([Step("agent", agent_or_flow.run)])
+        elif callable(agent_or_flow):
+            self._flow = Flow([Step("agent", agent_or_flow)])
+        else:
+            raise TypeError(
+                "Harness expects an object with a callable .run() method, a "
+                "plain callable, or a Flow instance."
+            )
+        self._runtime = Runtime(**runtime_options)
+
+    def run(self, input: Any) -> Any:
+        """Run the wrapped agent/flow with ``input`` and return its result."""
+        return self._runtime.run(self._flow, input)

harness/anomaly.py

@@ -0,0 +1,175 @@
+"""Cross-run baseline comparison and anomaly detection from JSONL traces.
+
+A trace record produced by :class:`Tracer` contains ``run_id``, ``step_name``,
+``duration_ms``, ``succeeded``, and ``error``. This module compares one new
+trace against statistics learned from past successful traces.
+"""
+
+from __future__ import annotations
+
+import statistics
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from .trace_viewer import load_traces
+
+
+class Baseline:
+    """Duration statistics for step names observed in past successful runs.
+
+    A *successful run* is a ``run_id`` whose every record has ``succeeded``
+    equal to ``True``. Failed runs (or runs containing any failed attempt) are
+    excluded from the baseline because their timings describe broken work and
+    would skew the "normal" duration statistics.
+    """
+
+    def __init__(self, trace_files: Iterable[str | Path]) -> None:
+        self._durations: dict[str, list[float]] = {}
+        successful_runs = 0
+
+        for trace_file in trace_files:
+            for run_records in _group_by_run(load_traces(trace_file)).values():
+                if not _is_successful_run(run_records):
+                    continue
+                successful_runs += 1
+                for record in run_records:
+                    step_name = record.get("step_name")
+                    duration = record.get("duration_ms")
+                    if not isinstance(step_name, str) or not isinstance(
+                        duration, (int, float)
+                    ):
+                        continue
+                    self._durations.setdefault(step_name, []).append(float(duration))
+
+        if successful_runs == 0:
+            raise ValueError(
+                "Baseline requires at least one fully successful run; "
+                "none of the provided trace files contained one."
+            )
+
+        # Sample standard deviation (n-1) is used because the traces are a
+        # sample of all possible runs. A single data point has no spread, so
+        # its standard deviation is stored as 0.0 rather than dividing by zero.
+        self._averages = {
+            name: statistics.mean(durations)
+            for name, durations in self._durations.items()
+        }
+        self._stddevs = {
+            name: statistics.stdev(durations) if len(durations) >= 2 else 0.0
+            for name, durations in self._durations.items()
+        }
+
+    @property
+    def known_step_names(self) -> frozenset[str]:
+        """Return the set of step names observed in successful baseline runs."""
+        return frozenset(self._durations)
+
+    def is_known(self, step_name: str) -> bool:
+        """Return whether ``step_name`` appeared in any successful baseline run."""
+        return step_name in self._durations
+
+    def sample_count(self, step_name: str) -> int:
+        """Return how many successful occurrences were recorded for ``step_name``."""
+        return len(self._durations.get(step_name, ()))
+
+    def average_duration_ms(self, step_name: str) -> float | None:
+        """Return the average duration in milliseconds for ``step_name``."""
+        return self._averages.get(step_name)
+
+    def stddev_duration_ms(self, step_name: str) -> float | None:
+        """Return the standard deviation of durations for ``step_name``."""
+        return self._stddevs.get(step_name)
+
+
+def find_anomalies(new_trace_path: str | Path, baseline: Baseline) -> list[dict[str, Any]]:
+    """Compare a new trace against ``baseline`` and return anomaly findings.
+
+    Each finding is a dict with ``step_name``, ``reason``, and ``severity``.
+    Severity scheme:
+
+    * ``"critical"`` — the step failed (``succeeded`` is not ``True``).
+    * ``"warning"``  — the step succeeded but took more than 2 standard
+      deviations longer than its baseline average (only checked when the
+      baseline has at least 2 data points for that step, since a standard
+      deviation is not meaningful from a single point).
+    * ``"info"``     — the step name was not seen in any baseline run.
+
+    A failed record is reported only as a failure (``critical``): a failed
+    attempt's duration is not comparable to successful baseline timings, and a
+    failure already demands attention, so extra "slow"/"unrecognized" findings
+    would only add noise.
+    """
+    if not isinstance(baseline, Baseline):
+        raise TypeError("baseline must be a Baseline instance.")
+
+    findings: list[dict[str, Any]] = []
+    for record in load_traces(new_trace_path):
+        step_name = record.get("step_name")
+        if not isinstance(step_name, str) or not step_name:
+            continue
+
+        if record.get("succeeded") is not True:
+            error = record.get("error") or "no error recorded"
+            findings.append(
+                {
+                    "step_name": step_name,
+                    "reason": f"Step '{step_name}' failed: {error}",
+                    "severity": "critical",
+                }
+            )
+            continue
+
+        if not baseline.is_known(step_name):
+            findings.append(
+                {
+                    "step_name": step_name,
+                    "reason": f"Step '{step_name}' was not seen in any baseline run.",
+                    "severity": "info",
+                }
+            )
+            continue
+
+        if baseline.sample_count(step_name) >= 2:
+            duration = record.get("duration_ms")
+            if isinstance(duration, (int, float)):
+                average = baseline.average_duration_ms(step_name)
+                stddev = baseline.stddev_duration_ms(step_name)
+                if (
+                    average is not None
+                    and stddev is not None
+                    and duration > average + 2 * stddev
+                ):
+                    findings.append(
+                        {
+                            "step_name": step_name,
+                            "reason": (
+                                f"Step '{step_name}' took {duration:.3f} ms, more than "
+                                f"2 standard deviations above its baseline average of "
+                                f"{average:.3f} ms."
+                            ),
+                            "severity": "warning",
+                        }
+                    )
+
+    return findings
+
+
+def _group_by_run(
+    records: Iterable[dict[str, Any]],
+) -> dict[str, list[dict[str, Any]]]:
+    """Group trace records by their ``run_id``, preserving first-seen order."""
+    runs: dict[str, list[dict[str, Any]]] = {}
+    for record in records:
+        run_id = record.get("run_id")
+        if run_id is None:
+            continue
+        runs.setdefault(run_id, []).append(record)
+    return runs
+
+
+def _is_successful_run(records: list[dict[str, Any]]) -> bool:
+    """Return whether every record in a run reports ``succeeded`` as ``True``."""
+    return bool(records) and all(
+        record.get("succeeded") is True for record in records
+    )

harness/context.py

@@ -0,0 +1,100 @@
+"""Agent Context Bundling: mechanical injection plus auditability.
+
+Lantern guarantees that a step's declared context files were actually read,
+delivered to any function that opts in via a ``context`` parameter, and
+recorded in the trace (file paths plus SHA-256 hashes). It does NOT guarantee
+that the agent complied with the content of those files — that is the
+agent/prompt's responsibility. Nothing in this module implies rule-following
+enforcement.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+class MissingContextFileError(FileNotFoundError):
+    """Raised when a declared context file cannot be found."""
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        super().__init__(f"Context file not found: {path}")
+
+
+@dataclass(frozen=True)
+class ExecutionContext:
+    """Execution metadata that is separate from a step's user input.
+
+    The harness owns this object and passes it to a function only when that
+    function explicitly opts in by declaring a ``context`` parameter. Simple
+    functions and BYO agents never see it. New kinds of context (memory,
+    experience, trace, metadata) can be added here without changing the
+    user-facing input contract.
+    """
+
+    rules: ContextBundle | None = None
+    skills: ContextBundle | None = None
+    memory: ContextBundle | None = None
+    experience: ContextBundle | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def as_text(self) -> str:
+        """Concatenate all available context files into one string."""
+        sections: list[str] = []
+        for bundle in (self.rules, self.skills, self.memory, self.experience):
+            if bundle is not None:
+                sections.append(bundle.as_text())
+        return "\n\n".join(sections)
+
+    def audit_entries(self) -> list[dict[str, str]]:
+        """Return the combined ``(path, hash)`` entries for tracing."""
+        entries: list[dict[str, str]] = []
+        for bundle in (self.rules, self.skills, self.memory, self.experience):
+            if bundle is not None:
+                entries.extend(bundle.audit_entries())
+        return entries
+
+
+@dataclass(frozen=True)
+class ContextBundle:
+    """The contents and hashes of a set of context files.
+
+    ``files`` is a list of ``(file_path, content, content_hash)`` tuples. The
+    hash is the SHA-256 hex digest of the UTF-8 encoded file content.
+    """
+
+    files: list[tuple[str, str, str]]
+
+    def as_text(self) -> str:
+        """Concatenate all files with clear per-file separators."""
+        return "\n\n".join(
+            f"--- {file_path} ---\n{content}"
+            for file_path, content, _ in self.files
+        )
+
+    def audit_entries(self) -> list[dict[str, str]]:
+        """Return ``(path, hash)`` pairs for trace auditability."""
+        return [
+            {"path": file_path, "hash": content_hash}
+            for file_path, _, content_hash in self.files
+        ]
+
+
+def load_context_files(paths: list[str]) -> ContextBundle:
+    """Read each file and compute its SHA-256 hash.
+
+    Raises :class:`MissingContextFileError` naming the exact path if any file
+    does not exist.
+    """
+    files: list[tuple[str, str, str]] = []
+    for path_str in paths:
+        path = Path(path_str)
+        if not path.is_file():
+            raise MissingContextFileError(path_str)
+        content = path.read_text(encoding="utf-8")
+        content_hash = hashlib.sha256(content.encode("utf-8")).hexdigest()
+        files.append((path_str, content, content_hash))
+    return ContextBundle(files)

harness/contracts.py

@@ -0,0 +1,67 @@
+"""Pydantic-backed input and output contracts for steps."""
+
+from __future__ import annotations
+
+import types
+from dataclasses import dataclass
+from typing import Any, Union, get_origin
+
+from pydantic import BaseModel, TypeAdapter, ValidationError
+
+
+def is_base_model_type(model: Any) -> bool:
+    """Return whether ``model`` is a Pydantic ``BaseModel`` subclass."""
+    return isinstance(model, type) and issubclass(model, BaseModel)
+
+
+def is_union_type(model: Any) -> bool:
+    """Return whether ``model`` is a typing ``Union`` of multiple types."""
+    return get_origin(model) is Union or isinstance(model, types.UnionType)
+
+
+@dataclass(frozen=True)
+class Contract:
+    """The Pydantic models that define a step's input and output shapes."""
+
+    input_model: type[BaseModel]
+    output_model: Any
+
+    def __post_init__(self) -> None:
+        if not is_base_model_type(self.input_model):
+            raise TypeError("input_model must be a Pydantic BaseModel subclass.")
+        if not is_base_model_type(self.output_model) and not is_union_type(
+            self.output_model
+        ):
+            raise TypeError(
+                "output_model must be a Pydantic BaseModel subclass or a Union of them."
+            )
+
+
+class ContractViolationError(ValueError):
+    """Raised when a step value does not satisfy one side of its contract."""
+
+    def __init__(self, step_name: str, direction: str, cause: ValidationError) -> None:
+        self.step_name = step_name
+        self.direction = direction
+        self.cause = cause
+        super().__init__(
+            f"Contract violation in step '{step_name}' for {direction}: {cause}"
+        )
+
+
+def validate_value(
+    value: Any,
+    model: Any,
+    *,
+    step_name: str,
+    direction: str,
+) -> Any:
+    """Validate a value and add step context to Pydantic validation errors.
+
+    ``model`` may be a ``BaseModel`` subclass or a ``Union`` (which can include
+    dataclasses such as :class:`Goto`); ``TypeAdapter`` validates both.
+    """
+    try:
+        return TypeAdapter(model).validate_python(value)
+    except ValidationError as error:
+        raise ContractViolationError(step_name, direction, error) from error