generflow-core 0.2.0__py3-none-any.whl

generflow_core/replay/__init__.py

@@ -0,0 +1,189 @@
+"""Rewind/replay: buffer SSE events as they arrive, allow scrubbing
+through them at any speed, and export for debugging.
+
+Storage is a flat list of events with monotonic timestamps. The
+scrubber reconstructs the spec tree at any point in time.
+
+Key uses:
+  - User hits "rewind" → events replay at 4× speed
+  - Developer debugs "what went wrong here?" → scrub to the moment
+  - Eval harness reproduces deterministic spec states
+  - The playground lets users see the LLM "thinking"
+"""
+from __future__ import annotations
+
+import json
+import time
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Any, Iterator
+
+from ..spec import GFLangParser, Assignment, Component
+
+
+@dataclass
+class BufferedEvent:
+    seq: int                              # monotonic sequence number
+    ts: float                             # wall-clock time
+    type: str                             # session.start, spec.line, data.fill, update, etc.
+    data: dict = field(default_factory=dict)
+
+
+class EventBuffer:
+    """In-memory buffer of SSE events for one session.
+
+    Supports:
+      - append(events) as they stream in
+      - iter() to walk all events
+      - replay(rate=4.0) to walk events at speed
+      - scrub(seq) to get the cumulative state at that point
+    """
+
+    def __init__(self, max_size: int = 100_000) -> None:
+        self._events: list[BufferedEvent] = []
+        self._seq = 0
+        self._max_size = max_size
+
+    def append(self, event_type: str, data: dict | None = None) -> BufferedEvent:
+        self._seq += 1
+        ev = BufferedEvent(seq=self._seq, ts=time.time(), type=event_type, data=data or {})
+        self._events.append(ev)
+        if len(self._events) > self._max_size:
+            self._events.pop(0)
+        return ev
+
+    def __len__(self) -> int:
+        return len(self._events)
+
+    def __iter__(self) -> Iterator[BufferedEvent]:
+        return iter(self._events)
+
+    def slice(self, start: int = 0, end: int | None = None) -> list[BufferedEvent]:
+        return self._events[start:end]
+
+    def at(self, seq: int) -> list[BufferedEvent]:
+        """All events up to and including seq."""
+        return [e for e in self._events if e.seq <= seq]
+
+    async def replay(self, rate: float = 1.0) -> Iterator[BufferedEvent]:
+        """Yield events at `rate`× real-time speed.
+
+        rate=4.0 → 4× faster than original; rate=0.5 → half-speed.
+        """
+        if not self._events:
+            return
+        start = self._events[0].ts
+        for i, ev in enumerate(self._events):
+            if i > 0:
+                original_delta = ev.ts - self._events[i - 1].ts
+                replay_delta = original_delta / rate
+                # cap at 100ms to avoid freezing on big gaps
+                if replay_delta > 0.1:
+                    replay_delta = 0.1
+                # busy-wait sleep — caller should be async
+                time.sleep(replay_delta)
+            yield ev
+
+    def scrub_state(self, seq: int) -> dict:
+        """Reconstruct the spec state at a given sequence point.
+
+        Returns:
+          {
+            "spec_lines": N,
+            "data_fills": M,
+            "updates": K,
+            "spec_text": "<reconstructed GF-Lang>",
+            "tree": { ... Component dict ... }
+          }
+        """
+        events = self.at(seq)
+        spec_text = ""
+        data_fills: dict[str, Any] = {}
+        updates: list[dict] = []
+        for ev in events:
+            if ev.type == "spec.line":
+                node = ev.data.get("node", {})
+                spec_text += _node_to_gflang(node) + "\n"
+            elif ev.type == "update":
+                updates.append(ev.data)
+                # apply the update (best-effort, no validation)
+                path = ev.data.get("path", "")
+                value = ev.data.get("value")
+                if path and value is not None:
+                    _apply_inline_update(spec_text, path, value)
+            elif ev.type == "data.fill":
+                ref = ev.data.get("ref")
+                if ref:
+                    data_fills[ref] = ev.data.get("value")
+        # parse reconstructed text
+        parser = GFLangParser()
+        nodes = parser.feed_chunk(spec_text)
+        return {
+            "seq": seq,
+            "spec_lines": sum(1 for e in events if e.type == "spec.line"),
+            "data_fills": len(data_fills),
+            "updates": len(updates),
+            "data_by_ref": data_fills,
+            "spec_text": spec_text,
+            "parsed_nodes": [n.to_dict() for n in nodes],
+        }
+
+    def export(self) -> dict:
+        """Export the full buffer as JSON (for debugging / sharing)."""
+        return {
+            "version": 1,
+            "event_count": len(self._events),
+            "first_ts": self._events[0].ts if self._events else None,
+            "last_ts": self._events[-1].ts if self._events else None,
+            "events": [{"seq": e.seq, "ts": e.ts, "type": e.type, "data": e.data} for e in self._events],
+        }
+
+
+def _node_to_gflang(node: dict) -> str:
+    """Reconstruct GF-Lang text from a serialized Component dict."""
+    name = node.get("name", "Text")
+    kwargs = node.get("kwargs", {})
+    args = node.get("args", [])
+    children = node.get("children", [])
+    parts = []
+    for k, v in kwargs.items():
+        parts.append(f"{k}={_render_gflang_value(v)}")
+    children_str = ""
+    if children:
+        kids = [_node_to_gflang(c) for c in children]
+        children_str = "[\n  " + ",\n  ".join(kids) + ",\n]"
+    if children_str:
+        if parts:
+            return f"{name}({', '.join(parts)},\n{children_str})"
+        return f"{name}({children_str})"
+    if parts:
+        return f"{name}({', '.join(parts)})"
+    return f"{name}()"
+
+
+def _render_gflang_value(v: Any) -> str:
+    if v is None:
+        return "null"
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, (int, float)):
+        return str(v)
+    if isinstance(v, str):
+        if any(c in v for c in " \t\"\\'"):
+            return '"' + v.replace("\\", "\\\\").replace('"', '\\"') + '"'
+        return v
+    if isinstance(v, dict):
+        # looks like a serialized Component
+        if "name" in v and ("kwargs" in v or "args" in v):
+            return _node_to_gflang(v)
+        return json.dumps(v)
+    if isinstance(v, list):
+        return "[" + ", ".join(_render_gflang_value(x) for x in v) + "]"
+    return str(v)
+
+
+def _apply_inline_update(text: str, path: str, value: Any) -> None:
+    """Best-effort: mutate `text` by replacing the value at `path`."""
+    # not implemented in v1 (use spec.update.apply_update on the parsed tree)
+    # this is a placeholder for future expansion
+    pass

generflow_core/spec/__init__.py

@@ -0,0 +1,21 @@
+"""GF-Lang spec module — public API."""
+from .ast import Assignment, Component, Literal, Ref
+from .diff import DiffEntry, diff_specs, summarize_diff
+from .parser import GFLangParser, ParseError, count_tokens
+from .update import Update, apply_update, parse_update
+
+__all__ = [
+    "Assignment",
+    "Component",
+    "DiffEntry",
+    "Literal",
+    "Ref",
+    "Update",
+    "GFLangParser",
+    "ParseError",
+    "apply_update",
+    "count_tokens",
+    "diff_specs",
+    "parse_update",
+    "summarize_diff",
+]

generflow_core/spec/ast.py

@@ -0,0 +1,61 @@
+"""GF-Lang AST node types."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Union
+
+
+@dataclass
+class Literal:
+    value: Union[str, int, float, bool, list, None]
+
+    def to_dict(self) -> Any:
+        return self.value
+
+
+@dataclass
+class Component:
+    name: str
+    args: list = field(default_factory=list)
+    kwargs: dict = field(default_factory=dict)
+    children: list = field(default_factory=list)  # child Components (not positional args)
+
+    def to_dict(self) -> dict:
+        return {
+            "type": "component",
+            "name": self.name,
+            "args": [_to_dict(a) for a in self.args],
+            "kwargs": {k: _to_dict(v) for k, v in self.kwargs.items()},
+            "children": [_to_dict(c) for c in self.children],
+        }
+
+
+@dataclass
+class Ref:
+    name: str  # the part after $
+
+    def to_dict(self) -> dict:
+        return {"type": "ref", "name": self.name}
+
+
+@dataclass
+class Assignment:
+    identifier: str
+    value: Any  # Component | Literal | Ref
+
+    def to_dict(self) -> dict:
+        return {
+            "type": "assignment",
+            "id": self.identifier,
+            "value": _to_dict(self.value),
+        }
+
+
+def _to_dict(node: Any) -> Any:
+    if hasattr(node, "to_dict"):
+        return node.to_dict()
+    if isinstance(node, dict):
+        return {k: _to_dict(v) for k, v in node.items()}
+    if isinstance(node, list):
+        return [_to_dict(x) for x in node]
+    return node

generflow_core/spec/diff.py

@@ -0,0 +1,177 @@
+"""Spec diffing: compare two GF-Lang specs and produce a structural diff.
+
+Useful for:
+  - Regression testing ("did the prompt change break this UI?")
+  - Prompt evaluation ("what changed between version A and B?")
+  - Showing users "the AI just changed this field"
+
+Diff output format: list of {op, path, before, after} entries.
+Ops: "added", "removed", "changed", "moved".
+
+Inspired by RFC 6902 (JSON Patch) but adapted for the spec tree.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+from typing import Any
+
+from .ast import Assignment, Component, Literal, Ref
+
+
+@dataclass
+class DiffEntry:
+    op: str          # "added" | "removed" | "changed" | "moved"
+    path: str        # e.g. "root.children[2].kwargs.value"
+    before: Any = None
+    after: Any = None
+    note: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "op": self.op,
+            "path": self.path,
+            "before": _serialize(self.before),
+            "after": _serialize(self.after),
+            "note": self.note,
+        }
+
+
+def _serialize(v: Any) -> Any:
+    """Make AST nodes JSON-friendly."""
+    if v is None or isinstance(v, (str, int, float, bool)):
+        return v
+    if isinstance(v, (Component, Assignment, Literal, Ref)):
+        return v.to_dict()
+    if isinstance(v, dict):
+        return {k: _serialize(val) for k, val in v.items()}
+    if isinstance(v, list):
+        return [_serialize(x) for x in v]
+    return str(v)
+
+
+def diff_specs(before_text: str, after_text: str) -> list[dict]:
+    """Compare two GF-Lang spec strings and return a diff.
+
+    Parses both specs, then walks in lockstep producing entries for each
+    structural difference. If a spec fails to parse, the whole thing
+    is reported as one entry.
+    """
+    from .parser import GFLangParser
+
+    p = GFLangParser()
+    a = p.feed_chunk(before_text)
+    b = p.feed_chunk(after_text)
+
+    # unwrap Assignment(root = ...) → root Component
+    a_root = _root(a)
+    b_root = _root(b)
+    if a_root is None or b_root is None:
+        return [DiffEntry(
+            op="error",
+            path="$",
+            before=before_text[:80] + "..." if len(before_text) > 80 else before_text,
+            after=after_text[:80] + "..." if len(after_text) > 80 else after_text,
+            note="could not parse one or both specs",
+        ).to_dict()]
+    out: list[DiffEntry] = []
+    _walk(a_root, b_root, "root", out)
+    return [e.to_dict() for e in out]
+
+
+def _root(nodes: list) -> Component | None:
+    if not nodes:
+        return None
+    n = nodes[0]
+    if isinstance(n, Assignment):
+        n = n.value
+    return n if isinstance(n, Component) else None
+
+
+def _walk(a: Any, b: Any, path: str, out: list[DiffEntry]) -> None:
+    """Recursively compare two AST subtrees."""
+    if type(a) != type(b):
+        out.append(DiffEntry(op="changed", path=path, before=a, after=b, note=f"type changed {type(a).__name__}→{type(b).__name__}"))
+        return
+    if isinstance(a, Component):
+        if a.name != b.name:
+            out.append(DiffEntry(op="changed", path=f"{path}.name", before=a.name, after=b.name, note="component renamed"))
+        # compare kwargs
+        a_keys = set(a.kwargs.keys())
+        b_keys = set(b.kwargs.keys())
+        for k in sorted(a_keys - b_keys):
+            out.append(DiffEntry(op="removed", path=f"{path}.kwargs.{k}", before=_serialize(a.kwargs[k])))
+        for k in sorted(b_keys - a_keys):
+            out.append(DiffEntry(op="added", path=f"{path}.kwargs.{k}", after=_serialize(b.kwargs[k])))
+        for k in sorted(a_keys & b_keys):
+            _walk(a.kwargs[k], b.kwargs[k], f"{path}.kwargs.{k}", out)
+        # compare children
+        _walk_children(a, b, path, out)
+    elif isinstance(a, Literal):
+        if a.value != b.value:
+            out.append(DiffEntry(op="changed", path=path, before=_serialize(a.value), after=_serialize(b.value)))
+    elif isinstance(a, Ref):
+        if a.name != b.name:
+            out.append(DiffEntry(op="changed", path=path, before=a.name, after=b.name, note="ref renamed"))
+    elif isinstance(a, dict):
+        a_keys = set(a.keys())
+        b_keys = set(b.keys())
+        for k in sorted(a_keys - b_keys):
+            out.append(DiffEntry(op="removed", path=f"{path}.{k}", before=_serialize(a[k])))
+        for k in sorted(b_keys - a_keys):
+            out.append(DiffEntry(op="added", path=f"{path}.{k}", after=_serialize(b[k])))
+        for k in sorted(a_keys & b_keys):
+            _walk(a[k], b[k], f"{path}.{k}", out)
+
+
+def _walk_children(a: Component, b: Component, path: str, out: list[DiffEntry]) -> None:
+    """Compare children arrays (positional + list-of-children)."""
+    # gather child lists: each Component has children as the last positional arg
+    a_children = _children(a)
+    b_children = _children(b)
+    if len(a_children) != len(b_children):
+        out.append(DiffEntry(
+            op="changed", path=f"{path}.children",
+            before=f"{len(a_children)} children",
+            after=f"{len(b_children)} children",
+            note="child count changed",
+        ))
+    n = min(len(a_children), len(b_children))
+    for i in range(n):
+        _walk(a_children[i], b_children[i], f"{path}.children[{i}]", out)
+    if len(a_children) > n:
+        for i in range(n, len(a_children)):
+            out.append(DiffEntry(op="removed", path=f"{path}.children[{i}]", before=_serialize(a_children[i])))
+    if len(b_children) > n:
+        for i in range(n, len(b_children)):
+            out.append(DiffEntry(op="added", path=f"{path}.children[{i}]", after=_serialize(b_children[i])))
+
+
+def _children(comp: Component) -> list:
+    """Extract the list of child Components.
+
+    Prefers the new `.children` field on Component. Falls back to the
+    legacy `args[-1]` Literal-wrapped list for backward compatibility
+    with code that hasn't been updated yet.
+    """
+    if hasattr(comp, "children") and comp.children:
+        return comp.children
+    if not comp.args:
+        return []
+    last = comp.args[-1]
+    if isinstance(last, Literal) and isinstance(last.value, list):
+        return last.value
+    return []
+
+
+def summarize_diff(entries: list[dict]) -> dict:
+    """Produce a one-line summary of a diff: counts + the most-impacted path."""
+    if not entries:
+        return {"count": 0, "added": 0, "removed": 0, "changed": 0, "top_path": None}
+    counts = {"added": 0, "removed": 0, "changed": 0, "moved": 0, "error": 0}
+    for e in entries:
+        op = e["op"]
+        counts[op] = counts.get(op, 0) + 1
+    # pick the shallowest changed/added path with a non-trivial value
+    interesting = [e for e in entries if e["op"] in ("changed", "added", "removed")]
+    top = interesting[0]["path"] if interesting else None
+    return {"count": len(entries), **counts, "top_path": top}