ellements 0.2.0__py3-none-any.whl

ellements/fslm/observers.py

@@ -0,0 +1,107 @@
+"""Observer protocol and built-in observers for FSLM runtime events."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class FSLMEventRecord(BaseModel):
+    """One machine-level observer event."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: str
+    ts: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    machine_id: str
+    step_id: str | None = None
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+@runtime_checkable
+class FSLMObserver(Protocol):
+    """Receives machine-level FSLM events."""
+
+    async def on_event(self, event: FSLMEventRecord) -> None:
+        """Handle one FSLM event."""
+
+
+class RecordingFSLMObserver:
+    """In-memory observer useful for tests."""
+
+    def __init__(self) -> None:
+        self.events: list[FSLMEventRecord] = []
+
+    async def on_event(self, event: FSLMEventRecord) -> None:
+        self.events.append(event)
+
+
+class JsonlFSLMObserver:
+    """Append FSLM observer events as JSON lines."""
+
+    def __init__(self, path: str | Path) -> None:
+        self._path = Path(path)
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = asyncio.Lock()
+
+    async def on_event(self, event: FSLMEventRecord) -> None:
+        line = json.dumps(event.model_dump(mode="json"), separators=(",", ":")) + "\n"
+        async with self._lock:
+            await asyncio.to_thread(self._append, line)
+
+    def _append(self, line: str) -> None:
+        with self._path.open("a", encoding="utf-8") as handle:
+            handle.write(line)
+
+
+class RichConsoleFSLMObserver:
+    """Pretty console observer for watching machines run."""
+
+    def __init__(self) -> None:
+        from rich.console import Console
+
+        self._console = Console()
+
+    async def on_event(self, event: FSLMEventRecord) -> None:
+        if event.type == "EventReceived":
+            self._console.print(
+                f"[bold cyan]event[/] {event.payload.get('event_type')} "
+                f"[dim]in {event.payload.get('state')}[/]"
+            )
+        elif event.type == "TransitionSelected":
+            self._console.print(
+                f"[bold green]transition[/] {event.payload.get('transition')} "
+                f"[dim]{event.payload.get('source')} -> "
+                f"{event.payload.get('target')}[/]"
+            )
+        elif event.type == "GuardEvaluated":
+            status = "ok" if event.payload.get("allowed") else "blocked"
+            self._console.print(
+                f"  [magenta]guard[/] {event.payload.get('id')}: {status} "
+                f"[dim]confidence={event.payload.get('confidence')}[/]"
+            )
+        elif event.type == "InvariantChecked":
+            status = "ok" if event.payload.get("allowed") else "violation"
+            self._console.print(
+                f"  [yellow]invariant[/] {event.payload.get('id')}: {status}"
+            )
+        elif event.type == "StepCompleted":
+            self._console.print(
+                f"[bold blue]step[/] {event.payload.get('status')} "
+                f"[dim]state={event.payload.get('state')}[/]"
+            )
+
+
+__all__ = [
+    "FSLMEventRecord",
+    "FSLMObserver",
+    "JsonlFSLMObserver",
+    "RecordingFSLMObserver",
+    "RichConsoleFSLMObserver",
+]
+

ellements/fslm/persistence.py

@@ -0,0 +1,72 @@
+"""In-memory and local-file persistence for FSLM runtime records."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .models import FSLMEvent, MachineSnapshot, StepResult
+
+
+class InMemoryFSLMStore:
+    """Lightweight in-memory store for snapshots/events/results/traces."""
+
+    def __init__(self) -> None:
+        self.snapshot: MachineSnapshot | None = None
+        self.events: list[FSLMEvent] = []
+        self.results: list[StepResult] = []
+        self.traces: list[dict[str, Any]] = []
+
+    async def save_snapshot(self, snapshot: MachineSnapshot) -> None:
+        self.snapshot = snapshot
+
+    async def load_snapshot(self) -> MachineSnapshot | None:
+        return self.snapshot
+
+    async def append_event(self, event: FSLMEvent) -> None:
+        self.events.append(event)
+
+    async def append_result(self, result: StepResult) -> None:
+        self.results.append(result)
+
+    async def append_trace(self, trace: dict[str, Any]) -> None:
+        self.traces.append(trace)
+
+
+class LocalFSLMStore:
+    """Local JSON/JSONL store using the `.fslm/` layout."""
+
+    def __init__(self, root: str | Path) -> None:
+        self.root = Path(root)
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    async def save_snapshot(self, snapshot: MachineSnapshot) -> None:
+        self._write_json(self.root / "snapshot.json", snapshot.model_dump(mode="json"))
+
+    async def load_snapshot(self) -> MachineSnapshot | None:
+        path = self.root / "snapshot.json"
+        if not path.is_file():
+            return None
+        return MachineSnapshot.model_validate(json.loads(path.read_text("utf-8")))
+
+    async def append_event(self, event: FSLMEvent) -> None:
+        self._append_jsonl(self.root / "events.jsonl", event.model_dump(mode="json"))
+
+    async def append_result(self, result: StepResult) -> None:
+        self._append_jsonl(self.root / "results.jsonl", result.model_dump(mode="json"))
+
+    async def append_trace(self, trace: dict[str, Any]) -> None:
+        self._append_jsonl(self.root / "traces.jsonl", trace)
+
+    @staticmethod
+    def _write_json(path: Path, data: dict[str, Any]) -> None:
+        path.write_text(json.dumps(data, indent=2, sort_keys=True), encoding="utf-8")
+
+    @staticmethod
+    def _append_jsonl(path: Path, data: dict[str, Any]) -> None:
+        with path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(data, sort_keys=True) + "\n")
+
+
+__all__ = ["InMemoryFSLMStore", "LocalFSLMStore"]