generflow-core 0.2.0__py3-none-any.whl

generflow_core/interop/__init__.py

@@ -0,0 +1,257 @@
+"""A2UI interop: convert A2UI JSONL messages to GF-Lang specs.
+
+A2UI is Google's Agent-to-UI protocol (v0.8/0.9). Messages are JSONL:
+
+  {"version":"v0.8","type":"beginRendering","surfaceId":"main","root":"root","components":[
+    {"id":"root","component":"Card","child":"body","title":"Dashboard"},
+    {"id":"body","component":"Column","children":["hdr","chart"]},
+    {"id":"hdr","component":"Text","text":"Hello"},
+    {"id":"chart","component":"Chart","type":"bar","data":[{"x":"Q1","y":1.2}]}
+  ]}
+
+We translate to a single GF-Lang spec. The mapping is lossy in places
+(component names, prop names) but reversible — we ship a reverse
+converter too for A2UI consumers who want to embed Generflow output.
+
+References:
+  https://github.com/google/a2ui
+  https://a2ui.org/spec/v0.8
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from ..spec.ast import Assignment, Component, Literal
+
+
+# A2UI → Generflow name map (extend as needed)
+_A2UI_NAME_MAP = {
+    "Column": "Col",
+    "Row": "Row",
+    "Card": "Card",
+    "Text": "Text",
+    "Heading": "Header",
+    "Chart": "Chart",
+    "List": "List",
+    "Button": "Button",
+    "Form": "Form",
+    "TextField": "Field",
+    "Modal": "Modal",
+    "NavigationBar": "Navbar",
+}
+
+# A2UI → Generflow prop map (per component)
+_A2UI_PROP_MAP = {
+    "Card": {"title": "title"},
+    "Header": {"text": "text"},
+    "Text": {"text": "text"},
+    "Button": {"text": "label"},
+    "Field": {"label": "label", "type": "type"},
+}
+
+
+@dataclass
+class A2UIParseError(Exception):
+    line: int
+    reason: str
+
+    def __str__(self) -> str:
+        return f"A2UI parse error on line {self.line}: {self.reason}"
+
+
+def a2ui_to_gflang(a2ui_text: str) -> str:
+    """Convert A2UI JSONL to a GF-Lang spec string.
+
+    Only the `beginRendering` message is required. We rebuild the tree
+    from the components list and emit it as a single root expression.
+    """
+    components: dict[str, dict] = {}
+    root_id: str | None = None
+    surface_id: str = "main"
+    version: str = "v0.8"
+
+    for i, raw in enumerate(a2ui_text.splitlines()):
+        raw = raw.strip()
+        if not raw:
+            continue
+        # Try to parse as a single message first (compact JSONL or pretty-printed
+        # single message). Then fall back to JSONL splitting by top-level '{' starts.
+        try:
+            msg = json.loads(raw)
+        except json.JSONDecodeError:
+            # likely a pretty-printed multi-line message; we need to find the
+            # top-level message boundaries. For v1, we support either:
+            #   - one message per line (JSONL)
+            #   - one message total (possibly multi-line)
+            # So we concatenate remaining lines and try again.
+            remaining = "\n".join(a2ui_text.splitlines()[i:]).strip()
+            try:
+                msg = json.loads(remaining)
+            except json.JSONDecodeError as e:
+                raise A2UIParseError(i + 1, f"invalid JSON: {e}")
+            # process the single message and stop
+            mtype = msg.get("type")
+            if mtype == "beginRendering":
+                version = msg.get("version", version)
+                surface_id = msg.get("surfaceId", surface_id)
+                root_id = msg.get("root", "root")
+                for comp in msg.get("components", []):
+                    cid = comp.get("id")
+                    if cid:
+                        components[cid] = comp
+            break
+        mtype = msg.get("type")
+        if mtype == "beginRendering":
+            version = msg.get("version", version)
+            surface_id = msg.get("surfaceId", surface_id)
+            root_id = msg.get("root", "root")
+            for comp in msg.get("components", []):
+                cid = comp.get("id")
+                if cid:
+                    components[cid] = comp
+        elif mtype == "dataModelUpdate":
+            # store as a side-channel for later use
+            pass
+        # other types (surfaceUpdate, etc.) ignored in v1
+
+    if root_id is None or root_id not in components:
+        raise A2UIParseError(0, "no beginRendering message or missing root component")
+
+    rendered = _render_node(root_id, components)
+    return rendered
+
+
+def _render_node(node_id: str, comps: dict[str, dict]) -> str:
+    """Render a single node (and recursively its children) as GF-Lang."""
+    comp = comps.get(node_id)
+    if comp is None:
+        return f"Text([ \"[missing:{node_id}]\" ])"
+    raw_name = comp.get("component", "Text")
+    name = _A2UI_NAME_MAP.get(raw_name, raw_name)
+    prop_map = _A2UI_PROP_MAP.get(name, {})
+
+    # collect kwargs
+    kwargs: list[str] = []
+    for a2ui_prop, gf_prop in prop_map.items():
+        if a2ui_prop in comp:
+            kwargs.append(f"{gf_prop}={_render_value(comp[a2ui_prop])}")
+
+    # special: Chart has `type` and `data`
+    if name == "Chart":
+        if "type" in comp:
+            kwargs.append(f"type={_render_value(comp['type'])}")
+        if "data" in comp:
+            # A2UI inline data → wrap as a List child with Text children
+            data_items = comp["data"]
+            inner = ", ".join(_render_value(d) for d in data_items)
+            kwargs.append(f"src=__inline__:{len(data_items)}")
+
+    # render children if present
+    children_str = ""
+    if "children" in comp:
+        # A2UI: child is a string id or a list of ids
+        kids = comp["children"]
+        if isinstance(kids, str):
+            kids = [kids]
+        kids_rendered = [_render_node(k, comps) for k in kids if k in comps]
+        if kids_rendered:
+            children_str = "[\n  " + ",\n  ".join(kids_rendered) + ",\n]"
+    elif "child" in comp:
+        cid = comp["child"]
+        if cid in comps:
+            children_str = "[\n  " + _render_node(cid, comps) + ",\n]"
+
+    if children_str:
+        return f"{name}({', '.join(kwargs) + ', ' if kwargs else ''}{children_str})"
+    if kwargs:
+        return f"{name}({', '.join(kwargs)})"
+    return f"{name}()"
+
+
+def _render_value(v: Any) -> str:
+    """Render a Python value as a GF-Lang literal."""
+    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, list):
+        return "[" + ", ".join(_render_value(x) for x in v) + "]"
+    if isinstance(v, dict):
+        return json.dumps(v)
+    return str(v)
+
+
+def gflang_to_a2ui(gf_text: str, surface_id: str = "main") -> str:
+    """Reverse: convert a GF-Lang spec to A2UI JSONL.
+
+    Emits a single `beginRendering` message. Children get synthetic ids
+    (`n0`, `n1`, ...). Useful for sharing Generflow output with
+    A2UI consumers (or for debugging).
+    """
+    from ..spec.parser import GFLangParser
+
+    p = GFLangParser()
+    nodes = p.feed_chunk(gf_text)
+    if not nodes:
+        return ""
+    root_node = nodes[0]
+    if isinstance(root_node, Assignment):
+        root_node = root_node.value
+    if not isinstance(root_node, Component):
+        return ""
+
+    components: list[dict] = []
+    node_counter = [0]
+
+    def alloc() -> str:
+        node_counter[0] += 1
+        return f"n{node_counter[0]}"
+
+    def walk(comp: Component) -> str:
+        cid = alloc()
+        a2ui_name = {v: k for k, v in _A2UI_NAME_MAP.items()}.get(comp.name, comp.name)
+        entry: dict[str, Any] = {"id": cid, "component": a2ui_name}
+        # reverse prop map
+        rev = {v: k for k, v in _A2UI_PROP_MAP.get(comp.name, {}).items()}
+        for k, v in comp.kwargs.items():
+            a2ui_prop = rev.get(k, k)
+            entry[a2ui_prop] = _value_to_json(v)
+        # children: prefer the new .children field; fall back to args[-1] for back-compat
+        kids = getattr(comp, "children", None)
+        if not kids and comp.args:
+            last = comp.args[-1]
+            if isinstance(last, Literal) and isinstance(last.value, list):
+                kids = [c for c in last.value if isinstance(c, Component)]
+        if kids:
+            child_ids = [walk(c) for c in kids]
+            if len(child_ids) == 1:
+                entry["child"] = child_ids[0]
+            else:
+                entry["children"] = child_ids
+        components.append(entry)
+        return cid
+
+    root_id = walk(root_node)
+
+    msg = {
+        "version": "v0.8",
+        "type": "beginRendering",
+        "surfaceId": surface_id,
+        "root": root_id,
+        "components": components,
+    }
+    return json.dumps(msg, indent=2)
+
+
+def _value_to_json(v: Any) -> Any:
+    if isinstance(v, Literal):
+        return v.value
+    return str(v)

generflow_core/observability/__init__.py

@@ -0,0 +1,208 @@
+"""Observability: lightweight metrics + tracing.
+
+Production usage would back this with OpenTelemetry. For v1 we ship an
+in-process collector that:
+  - Counts requests, tokens, components mounted, actions executed
+  - Records latency histograms (P50/P95/P99)
+  - Tracks errors per adapter
+  - Exports Prometheus text format and JSON
+
+Exposed via /v1/metrics (Prometheus) and /v1/trace (recent spans).
+"""
+from __future__ import annotations
+
+import json
+import threading
+import time
+from collections import defaultdict
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass
+class Span:
+    """A single timed operation."""
+    name: str
+    start: float
+    end: float = 0.0
+    attributes: dict = field(default_factory=dict)
+    status: str = "ok"  # "ok" | "error"
+    error: str | None = None
+
+    @property
+    def duration_ms(self) -> float:
+        return (self.end - self.start) * 1000 if self.end > 0 else 0.0
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "start": self.start,
+            "end": self.end,
+            "duration_ms": self.duration_ms,
+            "attributes": self.attributes,
+            "status": self.status,
+            "error": self.error,
+        }
+
+
+class MetricsCollector:
+    """Thread-safe metrics + span collector."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._counters: dict[str, int] = defaultdict(int)
+        self._histograms: dict[str, list[float]] = defaultdict(list)
+        self._spans: list[Span] = []
+        self._max_spans = 1000
+        self._max_histogram = 1000
+
+    # ── Counters ──────────────────────────────────────────────────────────
+
+    def incr(self, name: str, value: int = 1, **labels: str) -> None:
+        key = self._key(name, labels)
+        with self._lock:
+            self._counters[key] += value
+
+    def observe(self, name: str, value: float, **labels: str) -> None:
+        key = self._key(name, labels)
+        with self._lock:
+            self._histograms[key].append(value)
+            if len(self._histograms[key]) > self._max_histogram:
+                self._histograms[key] = self._histograms[key][-self._max_histogram:]
+
+    def counter_value(self, name: str, **labels: str) -> int:
+        return self._counters.get(self._key(name, labels), 0)
+
+    # ── Spans ─────────────────────────────────────────────────────────────
+
+    def start_span(self, name: str, **attributes: Any) -> Span:
+        return Span(name=name, start=time.time(), attributes=dict(attributes))
+
+    def end_span(self, span: Span, status: str = "ok", error: str | None = None) -> None:
+        span.end = time.time()
+        span.status = status
+        span.error = error
+        with self._lock:
+            self._spans.append(span)
+            if len(self._spans) > self._max_spans:
+                self._spans = self._spans[-self._max_spans:]
+        # auto-record latency in a histogram
+        self.observe(f"{span.name}.duration_ms", span.duration_ms, **span.attributes)
+
+    def recent_spans(self, limit: int = 50) -> list[dict]:
+        with self._lock:
+            return [s.to_dict() for s in self._spans[-limit:]]
+
+    # ── Percentiles ──────────────────────────────────────────────────────
+
+    def percentiles(self, name: str, pcts: list[float] | None = None, **labels: str) -> dict[float, float]:
+        if pcts is None:
+            pcts = [50, 95, 99]
+        key = self._key(name, labels)
+        with self._lock:
+            data = sorted(self._histograms.get(key, []))
+        if not data:
+            return {p: 0.0 for p in pcts}
+        out = {}
+        for p in pcts:
+            idx = min(int(len(data) * p / 100), len(data) - 1)
+            out[p] = data[idx]
+        return out
+
+    # ── Export ───────────────────────────────────────────────────────────
+
+    def to_prometheus(self) -> str:
+        """Render in Prometheus text format."""
+        lines = []
+        with self._lock:
+            for key, value in self._counters.items():
+                name, labels = self._split_key(key)
+                label_str = self._labels_str(labels)
+                lines.append(f"{name}{label_str} {value}")
+            for key, values in self._histograms.items():
+                name, labels = self._split_key(key)
+                label_str = self._labels_str(labels)
+                # emit summary
+                if values:
+                    sorted_v = sorted(values)
+                    p50 = sorted_v[len(sorted_v) // 2]
+                    p95 = sorted_v[min(int(len(sorted_v) * 0.95), len(sorted_v) - 1)]
+                    p99 = sorted_v[min(int(len(sorted_v) * 0.99), len(sorted_v) - 1)]
+                    lines.append(f"{name}_p50{label_str} {p50:.2f}")
+                    lines.append(f"{name}_p95{label_str} {p95:.2f}")
+                    lines.append(f"{name}_p99{label_str} {p99:.2f}")
+                    lines.append(f"{name}_count{label_str} {len(values)}")
+        return "\n".join(lines) + "\n"
+
+    def to_json(self) -> dict:
+        with self._lock:
+            return {
+                "version": 1,
+                "counters": dict(self._counters),
+                "histograms": {k: {"count": len(v), "p50": self._percentile(v, 50), "p95": self._percentile(v, 95), "p99": self._percentile(v, 99)} for k, v in self._histograms.items()},
+                "spans_recent": [s.to_dict() for s in self._spans[-50:]],
+            }
+
+    # ── Internal helpers ─────────────────────────────────────────────────
+
+    def _key(self, name: str, labels: dict) -> str:
+        if not labels:
+            return name
+        sorted_labels = sorted(labels.items())
+        return f"{name}?{','.join(f'{k}={v}' for k, v in sorted_labels)}"
+
+    def _split_key(self, key: str) -> tuple[str, dict]:
+        if "?" not in key:
+            return key, {}
+        name, label_str = key.split("?", 1)
+        labels = {}
+        for pair in label_str.split(","):
+            if "=" in pair:
+                k, v = pair.split("=", 1)
+                labels[k] = v
+        return name, labels
+
+    def _labels_str(self, labels: dict) -> str:
+        if not labels:
+            return ""
+        return "{" + ",".join(f'{k}="{v}"' for k, v in sorted(labels.items())) + "}"
+
+    def _percentile(self, values: list[float], p: float) -> float:
+        if not values:
+            return 0.0
+        s = sorted(values)
+        return s[min(int(len(s) * p / 100), len(s) - 1)]
+
+
+# ── Singleton + standard Generflow metrics ────────────────────────────────
+
+_metrics: MetricsCollector | None = None
+
+
+def get_metrics() -> MetricsCollector:
+    global _metrics
+    if _metrics is None:
+        _metrics = MetricsCollector()
+    return _metrics
+
+
+def reset_metrics() -> None:
+    """Reset for tests."""
+    global _metrics
+    _metrics = MetricsCollector()
+
+
+# Standard metric names (so dashboards have something stable)
+M = {
+    "REQUESTS": "generflow_requests_total",
+    "TOKENS": "generflow_tokens_total",
+    "COMPONENTS_MOUNTED": "generflow_components_mounted_total",
+    "DATA_RESOLVED": "generflow_data_resolved_total",
+    "DATA_FAILED": "generflow_data_failed_total",
+    "ACTIONS_DISPATCHED": "generflow_actions_dispatched_total",
+    "ACTIONS_EXECUTED": "generflow_actions_executed_total",
+    "HITL_TRIGGERED": "generflow_hitl_triggered_total",
+    "LATENCY_STREAM": "generflow_stream_duration_ms",
+    "LATENCY_LLM": "generflow_llm_duration_ms",
+    "LATENCY_DATA": "generflow_data_duration_ms",
+}

generflow_core/registry/__init__.py

@@ -0,0 +1,4 @@
+"""Registry module — component allow-list (security boundary)."""
+from .registry import ComponentSpec, Registry, DEFAULT_CATALOG, default_registry, parse_ref
+
+__all__ = ["ComponentSpec", "Registry", "DEFAULT_CATALOG", "default_registry", "parse_ref"]

generflow_core/registry/registry.py

@@ -0,0 +1,194 @@
+"""Component registry: the allow-list that prevents prompt injection UI
+and enforces the design system.
+
+Both backend and frontend load this same manifest. The renderer refuses
+to mount any component not in the registry. The backend refuses to emit
+any spec.line event for an unknown component.
+
+Phase 3 adds versioning: components can be referenced as `Card` (latest),
+`Card@v1` (legacy), or `Card@v2` (latest). The renderer enforces the
+requested version or falls back gracefully.
+"""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+_VERSION_RE = re.compile(r"^([A-Za-z_][\w]*)@v(\d+)$")
+
+
+def parse_ref(ref: str) -> tuple[str, int]:
+    """Parse 'Card' → ('Card', 1), 'Card@v2' → ('Card', 2)."""
+    m = _VERSION_RE.match(ref)
+    if m:
+        return m.group(1), int(m.group(2))
+    return ref, 1
+
+
+@dataclass
+class ComponentSpec:
+    name: str
+    description: str
+    props: dict[str, str] = field(default_factory=dict)
+    has_children: bool = False
+    category: str = "base"
+    version: int = 1  # Phase 3 addition
+
+    @property
+    def key(self) -> str:
+        """'Card@v2' or 'Card' for v1."""
+        return f"{self.name}@v{self.version}" if self.version > 1 else self.name
+
+    def to_dict(self) -> dict:
+        d = {
+            "name": self.name,
+            "description": self.description,
+            "props": self.props,
+            "has_children": self.has_children,
+            "category": self.category,
+            "version": self.version,
+            "key": self.key,
+        }
+        return d
+
+
+# Built-in default catalog — 14 base components for v1
+DEFAULT_CATALOG: list[ComponentSpec] = [
+    ComponentSpec(name="Card", description="A container with padding and a border. Most layouts start here.", props={"p": "string", "title": "string"}, has_children=True, category="layout"),
+    ComponentSpec(name="Stack", description="Vertical or horizontal stack of children.", props={"dir": "string", "gap": "string", "align": "string"}, has_children=True, category="layout"),
+    ComponentSpec(name="Header", description="A heading. Levels 1-3 via 'level' prop.", props={"level": "string", "text": "string"}, category="text"),
+    ComponentSpec(name="Text", description="Inline or block text. 'size' controls emphasis.", props={"size": "string", "color": "string"}, category="text"),
+    ComponentSpec(name="Metric", description="Big number with label, optionally bound to a data source.", props={"label": "string", "value": "string", "src": "string", "fmt": "string", "delta": "string"}, category="data"),
+    ComponentSpec(name="Chart", description="Data visualization. 'type' is bar/line/pie. 'src' binds the data.", props={"type": "string", "src": "string", "title": "string", "span": "string"}, category="data"),
+    ComponentSpec(name="Button", description="Clickable action. 'intent' triggers an action from the app config.", props={"label": "string", "intent": "string"}, category="interactive"),
+    ComponentSpec(name="Form", description="Form container. Children are Field and Button.", has_children=True, props={"title": "string"}, category="interactive"),
+    ComponentSpec(name="Field", description="Input field. 'name' binds to form state.", props={"name": "string", "label": "string", "value": "string", "type": "string"}, category="interactive"),
+    ComponentSpec(name="List", description="List of items, each rendered as a Text child.", has_children=True, props={"src": "string"}, category="data"),
+    ComponentSpec(name="Modal", description="Overlaid dialog. Children render inside.", has_children=True, props={"title": "string", "open": "string"}, category="layout"),
+    ComponentSpec(name="Navbar", description="Top navigation bar.", has_children=True, props={"title": "string"}, category="layout"),
+    ComponentSpec(name="Row", description="Horizontal flex row.", has_children=True, props={"gap": "string", "align": "string"}, category="layout"),
+    ComponentSpec(name="Col", description="Vertical flex column. Default for top-level containers.", has_children=True, props={"gap": "string"}, category="layout"),
+]
+
+
+class Registry:
+    """Component registry with version-aware lookups.
+
+    Internal storage is keyed by full key ('Card' or 'Card@v2'). Bare
+    name lookups return the latest version. Both shapes preserved for
+    backwards compatibility — has('Card') and has('Card@v2') both work.
+    """
+
+    def __init__(self, catalog: list[ComponentSpec] | None = None) -> None:
+        # keyed by full key
+        self._by_key: dict[str, ComponentSpec] = {}
+        # name → sorted list of versions
+        self._versions: dict[str, list[int]] = {}
+        for c in catalog or DEFAULT_CATALOG:
+            self._register(c)
+
+    def _register(self, spec: ComponentSpec) -> None:
+        self._by_key[spec.key] = spec
+        self._versions.setdefault(spec.name, []).append(spec.version)
+        self._versions[spec.name].sort()
+
+    def register(self, spec: ComponentSpec) -> None:
+        """Public registration (Phase 3 addition). Lets users add versions."""
+        self._register(spec)
+
+    def has(self, name: str) -> bool:
+        """True if the component exists (any version). Works with bare name or 'Name@vN'."""
+        name, _ = parse_ref(name)
+        return name in self._versions
+
+    def has_exact(self, key: str) -> bool:
+        """True if the exact key (with @vN) exists."""
+        return key in self._by_key
+
+    def get(self, name: str) -> ComponentSpec | None:
+        """Look up by name or key. Bare name → latest version."""
+        if "@" in name:
+            name_only, ver = parse_ref(name)
+            # v1 uses bare name as key, v2+ uses @vN suffix
+            key = name if ver > 1 else name_only
+            return self._by_key.get(key)
+        name_only, _ = parse_ref(name)
+        versions = self._versions.get(name_only, [])
+        if not versions:
+            return None
+        latest = versions[-1]
+        key = f"{name_only}@v{latest}" if latest > 1 else name_only
+        return self._by_key.get(key)
+
+    def versions(self, name: str) -> list[int]:
+        """List of registered versions for a component."""
+        return list(self._versions.get(name, []))
+
+    def names(self) -> list[str]:
+        """Bare component names (latest version per name)."""
+        return sorted(self._versions.keys())
+
+    def all_keys(self) -> list[str]:
+        """All keys, including versioned ones."""
+        return sorted(self._by_key.keys())
+
+    def to_prompt(self) -> str:
+        """Render the catalog as a section of the system prompt."""
+        lines = ["Available components (use EXACTLY these names):", ""]
+        # group by category, show latest version of each name
+        by_cat: dict[str, list[ComponentSpec]] = {}
+        for name in self.names():
+            spec = self.get(name)
+            if spec:
+                by_cat.setdefault(spec.category, []).append(spec)
+        for cat in sorted(by_cat):
+            lines.append(f"## {cat}")
+            for c in by_cat[cat]:
+                v = f"@v{c.version}" if c.version > 1 else ""
+                props_str = ", ".join(f"{k}:{v}" for k, v in c.props.items()) or "—"
+                child_marker = " (has children)" if c.has_children else ""
+                lines.append(f"- {c.name}{v}{child_marker} — {c.description}")
+                lines.append(f"    props: {props_str}")
+            lines.append("")
+        # versioned aliases note
+        all_keys = self.all_keys()
+        versioned = [k for k in all_keys if "@v" in k and self.versions(k.split("@v")[0])[0] != int(k.split("@v")[1])]
+        if versioned:
+            lines.append("## Available versions")
+            for k in versioned:
+                lines.append(f"- {k}")
+        return "\n".join(lines)
+
+    def manifest(self) -> dict:
+        """Return the registry as a manifest dict (versioned)."""
+        return {
+            "version": 2,  # Phase 3 bump — manifest now includes per-component versions
+            "components": [c.to_dict() for c in self._by_key.values()],
+        }
+
+    def manifest_json(self) -> str:
+        return json.dumps(self.manifest(), indent=2)
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> "Registry":
+        data = json.loads(Path(path).read_text())
+        cat = [
+            ComponentSpec(
+                name=c["name"],
+                description=c.get("description", ""),
+                props=c.get("props", {}),
+                has_children=c.get("has_children", False),
+                category=c.get("category", "base"),
+                version=c.get("version", 1),
+            )
+            for c in data.get("components", [])
+        ]
+        return cls(cat)
+
+
+def default_registry() -> Registry:
+    """Convenience: build a fresh Registry from DEFAULT_CATALOG."""
+    return Registry(DEFAULT_CATALOG)