microloop 0.3.0__cp310-abi3-win_amd64.whl

microloop/__init__.py

@@ -0,0 +1,236 @@
+"""
+Microloop — Keep agents making progress.
+
+A local reliability runtime for autonomous agents. It watches an agent's
+execution trajectory, detects when the agent is looping, stalled, regressing,
+or operating on stale state, and reports a configured intervention.
+
+The public API is intentionally small: ``Monitor``, ``Policy``, ``Event``,
+``Decision`` and ``InterventionAction``. The host owns the agent loop; Microloop
+only observes it and returns instructions.
+
+``SCHEMA_VERSION`` is the trajectory schema the ``microloop`` CLI reads. It is
+not enforced here: the runtime ``Event`` has no version field and ignores unknown
+keys, so ``Monitor.observe`` accepts any payload. Version checking happens at the
+file boundary in :mod:`microloop.cli`.
+"""
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from .microloop_core import Monitor as _CoreMonitor
+from .microloop_core import Policy as _CorePolicy
+from .microloop_core import version as _version
+
+__version__: str = _version()
+SCHEMA_VERSION = "0.3.0"
+
+__all__ = [
+    "Decision",
+    "Event",
+    "InterventionAction",
+    "Monitor",
+    "Policy",
+    "ProgressState",
+    "SCHEMA_VERSION",
+    "__version__",
+]
+
+
+class InterventionAction:
+    """What the host is advised to do. Compare with plain strings."""
+
+    Observe = "observe"
+    Replan = "replan"
+    Stop = "stop"
+
+
+class ProgressState:
+    """Trajectory progress classification."""
+
+    Healthy = "healthy"
+    Warning = "warning"
+    Stalled = "stalled"
+    Regressing = "regressing"
+
+
+@dataclass
+class Event:
+    """One agent step."""
+
+    step: int
+    action: str
+    observation: str
+    state: Mapping[str, str] | None = None
+    metrics: Mapping[str, float] | None = None
+    metadata: Mapping[str, str] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "step": self.step,
+            "action": self.action,
+            "observation": self.observation,
+        }
+        if self.state is not None:
+            payload["state"] = dict(self.state)
+        if self.metrics is not None:
+            payload["metrics"] = dict(self.metrics)
+        if self.metadata is not None:
+            payload["metadata"] = dict(self.metadata)
+        return payload
+
+
+@dataclass
+class Decision:
+    """The runtime's classification of one step."""
+
+    step: int
+    status: str
+    reasons: list[str] = field(default_factory=list)
+    evidence: list[dict[str, Any]] = field(default_factory=list)
+    intervention: str = InterventionAction.Observe
+    severity: float = 0.0
+    verified_progress: bool = False
+    feedback: str | None = None
+
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, Any]) -> Decision:
+        return cls(
+            step=int(payload["step"]),
+            status=str(payload["status"]),
+            reasons=[str(reason) for reason in payload.get("reasons", [])],
+            evidence=list(payload.get("evidence", [])),
+            intervention=str(payload.get("intervention", InterventionAction.Observe)),
+            severity=float(payload.get("severity", 0.0)),
+            verified_progress=bool(payload.get("verified_progress", False)),
+            feedback=payload.get("feedback"),
+        )
+
+    @property
+    def should_intervene(self) -> bool:
+        """True when the policy advises an action other than ``observe``."""
+        return self.intervention != InterventionAction.Observe
+
+    @property
+    def recovery_context(self) -> str:
+        """Recovery prompt to inject when intervening, or an empty string."""
+        return self.feedback or ""
+
+
+class Policy:
+    """
+    Recovery policy: maps a progress state to an intervention.
+
+    Defaults to observation-only. Automatic ``replan`` or ``stop`` requires an
+    explicit opt-in.
+    """
+
+    def __init__(
+        self,
+        *,
+        healthy: str = InterventionAction.Observe,
+        warning: str = InterventionAction.Observe,
+        stalled: str = InterventionAction.Observe,
+        regressing: str = InterventionAction.Observe,
+        cooldown_steps: int = 5,
+        max_interventions: int = 2,
+        stop_at_step: int | None = None,
+    ) -> None:
+        config: dict[str, Any] = {
+            "healthy": healthy,
+            "warning": warning,
+            "stalled": stalled,
+            "regressing": regressing,
+            "cooldown_steps": cooldown_steps,
+            "max_interventions": max_interventions,
+        }
+        if stop_at_step is not None:
+            config["stop_at_step"] = stop_at_step
+        self._config = config
+        self._inner = _CorePolicy(json.dumps(config))
+
+    def evaluate(self, decision: Decision) -> str:
+        if not isinstance(decision, Decision):
+            raise TypeError("Policy.evaluate expects a Decision")
+        payload = {
+            "step": decision.step,
+            "status": decision.status,
+            "reasons": decision.reasons,
+            "evidence": decision.evidence,
+            "intervention": decision.intervention,
+            "severity": decision.severity,
+            "verified_progress": decision.verified_progress,
+        }
+        return json.loads(self._inner.evaluate_json(json.dumps(payload)))
+
+
+class Monitor:
+    """
+    Trajectory progress monitor.
+
+    Defaults to observation-only. Automatic ``replan`` or ``stop`` requires an
+    explicit :class:`Policy`.
+    """
+
+    def __init__(
+        self,
+        *,
+        window: int = 32,
+        repetitions: int = 3,
+        stagnation_steps: int = 8,
+        verification_samples: int = 3,
+        normalization: bool = True,
+        policy: Policy | None = None,
+    ) -> None:
+        config = {
+            "window": window,
+            "repetitions": repetitions,
+            "stagnation_steps": stagnation_steps,
+            "verification_samples": verification_samples,
+            "normalization": normalization,
+        }
+        policy_json = json.dumps(policy._config) if policy is not None else None
+        self._inner = _CoreMonitor(json.dumps(config), policy_json)
+        self._step = 0
+
+    def observe(
+        self,
+        action: str,
+        observation: str,
+        *,
+        state: Mapping[str, str] | None = None,
+        metrics: Mapping[str, float] | None = None,
+        metadata: Mapping[str, str] | None = None,
+        step: int | None = None,
+    ) -> Decision:
+        """Observe one step and return its :class:`Decision`."""
+        if step is None:
+            self._step += 1
+            step = self._step
+        else:
+            self._step = max(self._step, step)
+        event = Event(
+            step=step,
+            action=action,
+            observation=observation,
+            state=state,
+            metrics=metrics,
+            metadata=metadata,
+        )
+        return Decision.from_dict(
+            json.loads(self._inner.observe_json(json.dumps(event.to_dict())))
+        )
+
+    def observe_event(self, event: Event) -> Decision:
+        """Observe a pre-built :class:`Event` (used by the CLI)."""
+        return self.observe(
+            action=event.action,
+            observation=event.observation,
+            state=event.state,
+            metrics=event.metrics,
+            metadata=event.metadata,
+            step=event.step,
+        )

microloop/cli.py

@@ -0,0 +1,317 @@
+"""Microloop CLI: inspect, replay, monitor and doctor.
+
+Reads schema 0.3.0 trajectory JSONL and streams it through the native runtime.
+``monitor`` can follow a live file as an agent appends steps.
+
+``replay`` re-runs *recorded events* through the current Microloop engine. It
+does not reproduce the original agent execution: no model is called and no tools
+run. A trajectory recorded by an older engine may therefore classify differently
+today.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import platform
+import sys
+import time
+from typing import Any
+
+from . import (
+    SCHEMA_VERSION,
+    Event,
+    InterventionAction,
+    Monitor,
+    Policy,
+    ProgressState,
+    __version__,
+)
+
+# Trajectory schema major version this runtime can read. A different major
+# version changes the meaning of fields, so it is rejected rather than guessed.
+_SCHEMA_MAJOR = int(SCHEMA_VERSION.split(".", 1)[0])
+
+# Recommendation policy for `replay` and `monitor`: surfaces what a host *could*
+# do without ever taking it. `inspect` deliberately does not use this; see below.
+_RECOMMENDATION_POLICY = Policy(
+    warning=InterventionAction.Observe,
+    stalled=InterventionAction.Replan,
+    regressing=InterventionAction.Replan,
+    cooldown_steps=1,
+    max_interventions=10_000,
+)
+
+_COLORS = {
+    "healthy": "\033[32m",
+    "warning": "\033[33m",
+    "stalled": "\033[31m",
+    "regressing": "\033[35m",
+}
+_RESET = "\033[0m"
+
+
+def _paint(text: str, status: str, enabled: bool) -> str:
+    if not enabled:
+        return text
+    return f"{_COLORS.get(status, '')}{text}{_RESET}"
+
+
+def _check_schema(record: dict[str, Any], path: str, lineno: int) -> None:
+    """Reject a trajectory this runtime cannot read."""
+    raw = record.get("schema_version")
+    if raw is None:
+        return
+    version = str(raw)
+    major = version.partition(".")[0]
+    if not major.isdigit():
+        raise SystemExit(
+            f"{path}:{lineno}: unreadable schema_version {version!r}; "
+            f"expected '<major>.<minor>' (this runtime reads {SCHEMA_VERSION})"
+        )
+    if int(major) != _SCHEMA_MAJOR:
+        raise SystemExit(
+            f"{path}:{lineno}: incompatible trajectory schema {version}; "
+            f"this runtime reads schema {SCHEMA_VERSION}. Trajectory major versions "
+            "must match — upgrade Microloop, or re-record the trajectory with "
+            "this schema version."
+        )
+
+
+def _load_record(path: str, lineno: int, line: str) -> dict[str, Any]:
+    try:
+        record = json.loads(line)
+    except json.JSONDecodeError as error:
+        raise SystemExit(f"{path}:{lineno}: invalid JSON: {error}") from error
+    if not isinstance(record, dict):
+        raise SystemExit(f"{path}:{lineno}: expected a JSON object")
+    _check_schema(record, path, lineno)
+    return record
+
+
+def _iter_records(path: str, follow: bool = False, interval: float = 0.25):
+    """Yield trajectory records, optionally following a file as it grows."""
+    with open(path, encoding="utf-8") as handle:
+        lineno = 0
+        while True:
+            where = handle.tell()
+            raw = handle.readline()
+            if raw == "":
+                if not follow:
+                    return
+                handle.seek(where)
+                time.sleep(interval)
+                continue
+            line = raw.strip()
+            if not line:
+                continue
+            lineno += 1
+            yield _load_record(path, lineno, line)
+
+
+def _read_trajectory(path: str) -> tuple[str, list[dict[str, Any]]]:
+    schema = SCHEMA_VERSION
+    records: list[dict[str, Any]] = []
+    for record in _iter_records(path):
+        if "schema_version" in record:
+            schema = str(record["schema_version"])
+        records.append(record)
+    if not records:
+        raise SystemExit(f"{path}: no trajectory events found")
+    return schema, records
+
+
+def _event_from_record(record: dict[str, Any], fallback_step: int) -> Event:
+    return Event(
+        step=int(record.get("step", fallback_step)),
+        action=str(record.get("action", "")),
+        observation=str(record.get("observation", "")),
+        state=record.get("state"),
+        metrics=record.get("metrics"),
+        metadata=record.get("metadata"),
+    )
+
+
+def _recommending() -> Monitor:
+    return Monitor(policy=_RECOMMENDATION_POLICY)
+
+
+def _observing() -> Monitor:
+    """Default runtime posture: detection without any intervention."""
+    return Monitor()
+
+
+def commands() -> dict[str, Any]:
+    return {
+        "inspect": _inspect,
+        "replay": _replay,
+        "monitor": _monitor_live,
+        "doctor": _doctor,
+    }
+
+
+def _inspect(args: argparse.Namespace) -> int:
+    schema, records = _read_trajectory(args.trajectory)
+    # Detection only: `inspect` reports what the detectors found, so it runs the
+    # default observation-only policy and never shows a host's replan/stop choice.
+    monitor = _observing()
+    first_detected: int | None = None
+    last = None
+    for index, record in enumerate(records, start=1):
+        decision = monitor.observe_event(_event_from_record(record, index))
+        if decision.status != ProgressState.Healthy and first_detected is None:
+            first_detected = decision.step
+        last = decision
+    assert last is not None
+
+    reasons = ", ".join(last.reasons) if last.reasons else "none"
+    evidence = last.evidence[0]["detail"] if last.evidence else "none"
+    print(f"Microloop trajectory analysis (schema {schema})")
+    print(f"{'Steps':<15}{len(records)}")
+    print(f"{'Status':<15}{last.status}")
+    print(f"{'Detected at':<15}{'step ' + str(first_detected) if first_detected else 'none'}")
+    print(f"{'Reasons':<15}{reasons}")
+    print(f"{'Evidence':<15}{evidence}")
+    print(f"{'Action':<15}{last.intervention} (default policy: observe only)")
+    return 0
+
+
+def _replay(args: argparse.Namespace) -> int:
+    schema, records = _read_trajectory(args.trajectory)
+    monitor = _recommending()
+    for index, record in enumerate(records, start=1):
+        decision = monitor.observe_event(_event_from_record(record, index))
+        payload = {
+            "schema_version": schema,
+            "step": decision.step,
+            "status": decision.status,
+            "reasons": decision.reasons,
+            "intervention": decision.intervention,
+            "severity": decision.severity,
+            "verified_progress": decision.verified_progress,
+        }
+        if args.json:
+            print(json.dumps(payload))
+        else:
+            reasons = ",".join(decision.reasons) or "-"
+            print(
+                f"{decision.step:>4}  {decision.status:<10} "
+                f"{decision.intervention:<8} {reasons}"
+            )
+    return 0
+
+
+def _monitor_live(args: argparse.Namespace) -> int:
+    color = sys.stdout.isatty() and not args.no_color
+    monitor = _recommending()
+    steps = 0
+    stalls = 0
+    warnings = 0
+    regressions = 0
+    interventions = 0
+    recovered = False
+    seen_issue = False
+
+    print("Microloop")
+    print(f"trajectory {args.trajectory}" + (" (following)" if args.follow else ""))
+    print()
+    try:
+        for record in _iter_records(args.trajectory, follow=args.follow, interval=args.interval):
+            steps += 1
+            decision = monitor.observe_event(_event_from_record(record, steps))
+            if decision.status == "stalled":
+                stalls += 1
+            elif decision.status == "warning":
+                warnings += 1
+            elif decision.status == "regressing":
+                regressions += 1
+            if decision.status != "healthy":
+                seen_issue = True
+            elif seen_issue:
+                recovered = True
+
+            header = _paint(f"{decision.status.upper():<10}", decision.status, color)
+            reasons = " ".join(decision.reasons)
+            print(f"{decision.step:>4}  {header} {reasons}".rstrip())
+            for item in decision.evidence:
+                print(f"      {item['detail']}")
+            if decision.intervention != InterventionAction.Observe:
+                interventions += 1
+                print(f"      -> {decision.intervention.upper()} (recommended)")
+            print()
+    except KeyboardInterrupt:
+        print()
+
+    print("completed" if not seen_issue or recovered else "stopped")
+    print(f"{'Steps':<18}{steps}")
+    print(f"{'Stalls':<18}{stalls}")
+    print(f"{'Warnings':<18}{warnings}")
+    print(f"{'Regressions':<18}{regressions}")
+    print(f"{'Recommended':<18}{interventions}")
+    print(f"{'Recovered':<18}{'yes' if recovered else 'no'}")
+    return 0
+
+
+def _doctor(_args: argparse.Namespace) -> int:
+    checks = [
+        ("microloop", __version__),
+        ("schema", SCHEMA_VERSION),
+        ("runtime", "native (PyO3)"),
+        ("python", platform.python_version()),
+        ("platform", f"{platform.system()} {platform.machine()}"),
+    ]
+    ok = True
+    for name, value in checks:
+        print(f"[ok] {name:<10} {value}")
+    try:
+        from .microloop_core import Monitor as _Native  # noqa: F401
+
+        print("[ok] native extension importable")
+    except Exception as error:  # pragma: no cover - environment dependent
+        ok = False
+        print(f"[fail] native extension: {error}")
+    return 0 if ok else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="microloop", description="Microloop runtime tools")
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"microloop {__version__} (schema {SCHEMA_VERSION}, runtime: native)",
+    )
+    sub = parser.add_subparsers(dest="command")
+    inspect_parser = sub.add_parser(
+        "inspect",
+        help="summarize a trajectory JSONL (detection only, no intervention policy)",
+    )
+    inspect_parser.add_argument("trajectory")
+    replay_parser = sub.add_parser(
+        "replay",
+        help="re-run recorded events through the current engine",
+    )
+    replay_parser.add_argument("trajectory")
+    replay_parser.add_argument("--json", action="store_true", help="emit decisions as JSONL")
+    monitor_parser = sub.add_parser("monitor", help="print a live progress view")
+    monitor_parser.add_argument("trajectory")
+    monitor_parser.add_argument(
+        "-f", "--follow", action="store_true", help="keep reading as the file grows"
+    )
+    monitor_parser.add_argument(
+        "--interval", type=float, default=0.25, help="poll interval in seconds when following"
+    )
+    monitor_parser.add_argument("--no-color", action="store_true", help="disable ANSI color")
+    sub.add_parser("doctor", help="check the native runtime")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        return 0
+    return commands()[args.command](args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

microloop-0.3.0.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: microloop
+Version: 0.3.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: License :: OSI Approved :: MIT License
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Development Status :: 4 - Beta
+License-File: LICENSE-MIT
+License-File: LICENSE-APACHE
+Summary: Local reliability runtime for autonomous agents
+Keywords: agent,llm,trajectory,progress,loop-detection
+Author: Microloop Team
+License-Expression: MIT OR Apache-2.0
+Requires-Python: >=3.10, <3.14
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/Devaretanmay/microloop
+Project-URL: Repository, https://github.com/Devaretanmay/microloop
+
+# Microloop Python SDK
+
+Python bindings for the Microloop local reliability runtime.
+
+```python
+from microloop import InterventionAction, Monitor, Policy
+
+policy = Policy(
+    stalled=InterventionAction.Replan,
+    regressing=InterventionAction.Stop,
+    cooldown_steps=5,
+)
+monitor = Monitor(policy=policy)
+
+for step in agent.steps():
+    decision = monitor.observe(
+        action=step.action,
+        observation=step.result,
+        state=step.state,
+        metrics={"exit_code": step.exit_code},
+    )
+    if decision.should_intervene:
+        agent.inject(decision.recovery_context)
+```
+
+`Monitor.observe(...)` returns a `Decision` with `status`, `reasons`,
+`intervention`, `severity`, `verified_progress` and `feedback`. The default
+policy only observes; automatic recovery requires explicit opt-in.
+
+You own the agent loop. `Monitor` classifies and advises; it never runs tools,
+calls a model, or stops a process.
+
+## CLI
+
+```bash
+microloop inspect trajectory.jsonl   # detection only, default observe-only policy
+microloop replay trajectory.jsonl --json  # re-run recorded events through the engine
+microloop monitor trajectory.jsonl --follow
+microloop doctor
+```
+
+`replay` re-runs *recorded events* through the current engine. It does not
+reproduce the original agent execution. A trajectory with an incompatible
+`schema_version` major version is rejected rather than analyzed.
+
+## Building
+
+```bash
+pip install maturin
+maturin develop --manifest-path python/microloop/Cargo.toml
+```
+
+No external credentials or network connections are required. All trajectory
+evaluation runs locally in Rust via PyO3.
+

microloop-0.3.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+microloop/__init__.py,sha256=TyEdfEbnggSZH7fIP9AFWLkSjHZbEWv866OJb0fdwe0,7563
+microloop/cli.py,sha256=AkjqrI7_msaYJLLoq-__XXXWKQp7x1MTQ9o6A1N5i7o,11285
+microloop/microloop_core.pyd,sha256=6ELkzbzuXtfetELCBfR1qR8y0WfSz4m-fyQArJugkec,1214976
+microloop/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+microloop-0.3.0.dist-info/METADATA,sha256=xyGPUmORrizxF1b0VLTJWfm2AZc9m3tCFGP3VmR1f5I,2775
+microloop-0.3.0.dist-info/WHEEL,sha256=7HL-TGvq44Ofp0yhZL-uRIIFHcJTIqqkRZVQ2wZidzM,96
+microloop-0.3.0.dist-info/entry_points.txt,sha256=IH9dbn7NkvU8eRSKXpvNhYBsPVuIqll-DqFEelqfLTs,47
+microloop-0.3.0.dist-info/licenses/LICENSE-APACHE,sha256=rbE9VbG9z2yR4NDeFiwhzbli2eDjiXYeUIhQIvcUdM8,11548
+microloop-0.3.0.dist-info/licenses/LICENSE-MIT,sha256=NRAxjDGOWZmFNvH50bZgkWzQLXQKLyJrPmrR_K5KJsA,1087
+microloop-0.3.0.dist-info/sboms/microloop-python.cyclonedx.json,sha256=cAVkmwmBV3p1i8JkwBpFVHtK33fWMs1sKZ7YNkMQl_4,48880
+microloop-0.3.0.dist-info/RECORD,,

microloop-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.15.0)
+Root-Is-Purelib: false
+Tag: cp310-abi3-win_amd64

microloop-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+microloop=microloop.cli:main