PyPI - generflow-core - Versions diffs - 0.2.0__py3-none-any.whl - Mend

generflow-core 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (30) hide show

generflow_core/__init__.py +3 -0
generflow_core/actions/__init__.py +22 -0
generflow_core/actions/dispatcher.py +223 -0
generflow_core/adapters/__init__.py +11 -0
generflow_core/adapters/llm.py +186 -0
generflow_core/api/__init__.py +5 -0
generflow_core/api/app.py +494 -0
generflow_core/api/prompt.py +64 -0
generflow_core/cli.py +241 -0
generflow_core/databind/__init__.py +30 -0
generflow_core/databind/config.py +183 -0
generflow_core/databind/resolver.py +306 -0
generflow_core/hitl/__init__.py +22 -0
generflow_core/hitl/gates.py +165 -0
generflow_core/interop/__init__.py +257 -0
generflow_core/observability/__init__.py +208 -0
generflow_core/py.typed +0 -0
generflow_core/registry/__init__.py +4 -0
generflow_core/registry/registry.py +194 -0
generflow_core/replay/__init__.py +189 -0
generflow_core/spec/__init__.py +21 -0
generflow_core/spec/ast.py +61 -0
generflow_core/spec/diff.py +177 -0
generflow_core/spec/parser.py +332 -0
generflow_core/spec/update.py +136 -0
generflow_core-0.2.0.dist-info/METADATA +161 -0
generflow_core-0.2.0.dist-info/RECORD +30 -0
generflow_core-0.2.0.dist-info/WHEEL +5 -0
generflow_core-0.2.0.dist-info/entry_points.txt +3 -0
generflow_core-0.2.0.dist-info/top_level.txt +1 -0

generflow_core/cli.py ADDED Viewed

@@ -0,0 +1,241 @@
+"""Local-only CLI: render a GF-Lang spec file to HTML/JSON without an LLM.
+Useful for:
+  - Static dashboard embedding
+  - Storybook integration
+  - Design-system handoff (designer writes a spec, dev renders it)
+  - Email-renderable reports (spec → HTML → email)
+Usage:
+  python -m generflow_core.cli render spec.gf -o output.html
+  python -m generflow_core.cli validate spec.gf
+  python -m generflow_core.cli diff before.gf after.gf
+  python -m generflow_core.cli to-a2ui spec.gf -o output.a2ui.json
+  python -m generflow_core.cli from-a2ui incoming.a2ui.json -o spec.gf
+"""
+from __future__ import annotations
+import argparse
+import json
+import sys
+from pathlib import Path
+from .spec import GFLangParser, diff_specs, summarize_diff
+from .registry import Registry
+from .interop import a2ui_to_gflang, gflang_to_a2ui
+# ── Render: spec → HTML ───────────────────────────────────────────────────
+def render_html(spec_text: str, registry: Registry | None = None) -> str:
+    """Render a GF-Lang spec to a self-contained HTML document.
+    The HTML has inline CSS and minimal JS. No React, no Tailwind CDN —
+    everything's a single file you can drop in an email or iframe.
+    """
+    registry = registry or Registry()
+    parser = GFLangParser()
+    nodes = parser.feed_chunk(spec_text)
+    if not nodes:
+        return _empty_html("(empty spec)")
+    root = nodes[0]
+    if hasattr(root, "value"):
+        root = root.value
+    body = _render_node_html(root, registry)
+    return f"""<!doctype html>
+<html><head>
+<meta charset="utf-8">
+<title>Generflow render</title>
+<style>
+body {{ font: 14px/1.5 system-ui, -apple-system, sans-serif; margin: 0; padding: 24px; background: #fafafa; color: #1a1a1a; }}
+.gf-card {{ background: white; border: 1px solid #e5e5e5; border-radius: 8px; padding: 16px; margin: 12px 0; box-shadow: 0 1px 2px rgba(0,0,0,0.04); }}
+.gf-card > .gf-title {{ font-size: 18px; font-weight: 600; margin-bottom: 12px; color: #111; }}
+.gf-stack, .gf-row, .gf-col {{ display: flex; gap: 12px; }}
+.gf-col {{ flex-direction: column; }}
+.gf-header {{ font-weight: 600; margin: 8px 0; }}
+.gf-header.h1 {{ font-size: 24px; }} .gf-header.h2 {{ font-size: 18px; }} .gf-header.h3 {{ font-size: 14px; }}
+.gf-text {{ margin: 4px 0; }}
+.gf-metric {{ display: flex; flex-direction: column; padding: 12px; background: #f8f8f8; border-radius: 6px; flex: 1; }}
+.gf-metric .label {{ font-size: 12px; color: #666; text-transform: uppercase; letter-spacing: 0.5px; }}
+.gf-metric .value {{ font-size: 28px; font-weight: 700; color: #111; margin-top: 4px; }}
+.gf-metric .delta-positive {{ color: #10b981; font-size: 12px; }}
+.gf-metric .delta-negative {{ color: #ef4444; font-size: 12px; }}
+.gf-button {{ background: #2563eb; color: white; border: none; padding: 10px 16px; border-radius: 6px; cursor: pointer; font-weight: 500; }}
+.gf-button:hover {{ background: #1d4ed8; }}
+.gf-form {{ background: white; border: 1px solid #e5e5e5; border-radius: 8px; padding: 16px; }}
+.gf-field {{ display: flex; flex-direction: column; margin: 8px 0; }}
+.gf-field label {{ font-size: 12px; color: #666; margin-bottom: 4px; }}
+.gf-field input {{ padding: 8px; border: 1px solid #ddd; border-radius: 4px; }}
+.gf-list {{ list-style: none; padding: 0; }}
+.gf-list li {{ padding: 8px 12px; border-bottom: 1px solid #f0f0f0; }}
+.gf-chart {{ background: #f8f8f8; border-radius: 6px; padding: 12px; min-height: 120px; display: flex; align-items: center; justify-content: center; color: #666; }}
+.gf-meta {{ font-size: 11px; color: #999; margin-top: 24px; padding-top: 12px; border-top: 1px solid #eee; }}
+</style>
+</head><body>
+{body}
+<div class="gf-meta">Rendered by Generflow · {len(nodes)} top-level node(s)</div>
+</body></html>"""
+def _render_node_html(node, registry: Registry) -> str:
+    from .spec.ast import Component, Literal
+    if not isinstance(node, Component):
+        return ""
+    name = node.name
+    kwargs = {k: (v.value if isinstance(v, Literal) else str(v)) for k, v in node.kwargs.items()}
+    children_html = ""
+    # read children from new Component.children field first; fall back to args[-1]
+    children = getattr(node, "children", None)
+    if children:
+        children_html = "".join(_render_node_html(c, registry) for c in children if isinstance(c, Component))
+    elif node.args:
+        last = node.args[-1]
+        if isinstance(last, Literal) and isinstance(last.value, list):
+            children_html = "".join(_render_node_html(c, registry) for c in last.value if isinstance(c, Component))
+    if name == "Card":
+        title = kwargs.get("title", "")
+        title_html = f'<div class="gf-title">{title}</div>' if title else ""
+        return f'<div class="gf-card">{title_html}{children_html}</div>'
+    if name in ("Stack", "Col"):
+        return f'<div class="gf-col">{children_html}</div>'
+    if name == "Row":
+        return f'<div class="gf-row">{children_html}</div>'
+    if name == "Header":
+        lvl = kwargs.get("level", "1")
+        text = kwargs.get("text", "")
+        return f'<div class="gf-header h{lvl}">{text}</div>'
+    if name == "Text":
+        text = kwargs.get("text", "")
+        return f'<div class="gf-text">{text}</div>'
+    if name == "Metric":
+        label = kwargs.get("label", "")
+        value = kwargs.get("value", "—")
+        delta = kwargs.get("delta", "")
+        delta_cls = "delta-positive" if delta.startswith("+") else ("delta-negative" if delta.startswith("-") else "")
+        delta_html = f'<span class="{delta_cls}">{delta}</span>' if delta else ""
+        return f'<div class="gf-metric"><span class="label">{label}</span><span class="value">{value}</span>{delta_html}</div>'
+    if name == "Chart":
+        title = kwargs.get("title", "")
+        ctype = kwargs.get("type", "bar")
+        return f'<div class="gf-chart">[Chart: {title or ctype}]</div>'
+    if name == "Button":
+        label = kwargs.get("label", "")
+        intent = kwargs.get("intent", "")
+        intent_attr = f' data-intent="{intent}"' if intent else ""
+        return f'<button class="gf-button"{intent_attr}>{label}</button>'
+    if name == "Form":
+        title = kwargs.get("title", "")
+        title_html = f'<h3>{title}</h3>' if title else ""
+        return f'<div class="gf-form">{title_html}{children_html}</div>'
+    if name == "Field":
+        label = kwargs.get("label", "")
+        name_attr = kwargs.get("name", "")
+        ftype = kwargs.get("type", "text")
+        return f'<div class="gf-field"><label>{label}</label><input type="{ftype}" name="{name_attr}"></div>'
+    if name == "List":
+        return f'<ul class="gf-list">{children_html or "<li>(list — data source not resolved in static mode)</li>"}</ul>'
+    if name == "Navbar":
+        title = kwargs.get("title", "")
+        return f'<nav class="gf-card"><div class="gf-title">{title}</div></nav>'
+    if name == "Modal":
+        return f'<div class="gf-card"><em>(Modal — not interactive in static mode)</em>{children_html}</div>'
+    # unknown component — render as warning
+    return f'<div class="gf-text" style="color:#999">[Unknown component: {name}]</div>'
+def _empty_html(msg: str) -> str:
+    return f'<!doctype html><html><body><p>{msg}</p></body></html>'
+# ── CLI ───────────────────────────────────────────────────────────────────
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="generflow", description="Generflow local-only CLI")
+    sub = parser.add_subparsers(dest="command", required=True)
+    p_render = sub.add_parser("render", help="Render a GF-Lang spec to HTML")
+    p_render.add_argument("spec", type=Path, help="Path to .gf file")
+    p_render.add_argument("-o", "--output", type=Path, default=None)
+    p_validate = sub.add_parser("validate", help="Validate a spec against the registry")
+    p_validate.add_argument("spec", type=Path)
+    p_diff = sub.add_parser("diff", help="Compare two specs")
+    p_diff.add_argument("before", type=Path)
+    p_diff.add_argument("after", type=Path)
+    p_to_a2ui = sub.add_parser("to-a2ui", help="Convert GF-Lang to A2UI JSONL")
+    p_to_a2ui.add_argument("spec", type=Path)
+    p_to_a2ui.add_argument("-o", "--output", type=Path, default=None)
+    p_from_a2ui = sub.add_parser("from-a2ui", help="Convert A2UI JSONL to GF-Lang")
+    p_from_a2ui.add_argument("a2ui", type=Path)
+    p_from_a2ui.add_argument("-o", "--output", type=Path, default=None)
+    args = parser.parse_args()
+    if args.command == "render":
+        text = args.spec.read_text()
+        html = render_html(text)
+        if args.output:
+            args.output.write_text(html)
+            print(f"wrote {args.output}")
+        else:
+            print(html)
+        return 0
+    if args.command == "validate":
+        text = args.spec.read_text()
+        p = GFLangParser()
+        nodes = p.feed_chunk(text)
+        r = Registry()
+        valid = 0
+        invalid = 0
+        from .spec.ast import Assignment, Component
+        for n in nodes:
+            target = n.value if isinstance(n, Assignment) else n
+            if isinstance(target, Component):
+                if r.has(target.name):
+                    valid += 1
+                    print(f"  ✓ {target.name}")
+                else:
+                    invalid += 1
+                    print(f"  ✗ {target.name} — not in registry")
+        print(f"\n{valid} valid, {invalid} invalid")
+        return 0 if invalid == 0 else 1
+    if args.command == "diff":
+        before = args.before.read_text()
+        after = args.after.read_text()
+        entries = diff_specs(before, after)
+        summary = summarize_diff(entries)
+        print(json.dumps({"summary": summary, "entries": entries}, indent=2))
+        return 0
+    if args.command == "to-a2ui":
+        text = args.spec.read_text()
+        out = gflang_to_a2ui(text)
+        if args.output:
+            args.output.write_text(out + "\n")
+            print(f"wrote {args.output}")
+        else:
+            print(out)
+        return 0
+    if args.command == "from-a2ui":
+        text = args.a2ui.read_text()
+        out = a2ui_to_gflang(text)
+        if args.output:
+            args.output.write_text(out + "\n")
+            print(f"wrote {args.output}")
+        else:
+            print(out)
+        return 0
+    return 1
+if __name__ == "__main__":
+    sys.exit(main())

generflow_core/databind/__init__.py ADDED Viewed

@@ -0,0 +1,30 @@
+"""Databind module: data sources + resolvers."""
+from .config import Action, AppConfig, DataSource
+from .resolver import (
+    McpResolver,
+    GraphqlResolver,
+    Resolver,
+    ResolverError,
+    RestResolver,
+    SqlResolver,
+    cache_clear,
+    get_resolver,
+    register_resolver,
+    resolve_source,
+)
+__all__ = [
+    "Action",
+    "AppConfig",
+    "DataSource",
+    "GraphqlResolver",
+    "McpResolver",
+    "Resolver",
+    "ResolverError",
+    "RestResolver",
+    "SqlResolver",
+    "cache_clear",
+    "get_resolver",
+    "register_resolver",
+    "resolve_source",
+]

generflow_core/databind/config.py ADDED Viewed

@@ -0,0 +1,183 @@
+"""App-level registry config: data sources + actions, loaded from a YAML file.
+This is the *application developer's* config — separate from the
+component registry (which is the LLM-facing allow-list of UI primitives).
+The config binds:
+- `sources`: named data sources (REST, SQL, GraphQL, MCP) — the LLM
+  emits `src="q3_revenue"` and the backend resolves it here.
+- `actions`: named intent → endpoint mappings — the LLM emits
+  `intent="refund.approve"` and the backend dispatches here.
+Secrets are referenced via `${SECRET_NAME}` syntax and resolved at
+load time from environment variables. Secrets never appear in prompts
+or logs.
+"""
+from __future__ import annotations
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+import yaml
+_SECRET_RE = re.compile(r"\$\{([A-Z][A-Z0-9_]*)\}")
+def _interpolate(value: Any, vars: dict[str, str]) -> Any:
+    """Replace `{key}` placeholders in any string within a nested structure.
+    Used to inject paths like `{config_dir}` into YAML values so config files
+    stay self-contained (no absolute paths leaking into the repo).
+    """
+    if isinstance(value, str):
+        out = value
+        for k, v in vars.items():
+            out = out.replace("{" + k + "}", v)
+        return out
+    if isinstance(value, dict):
+        return {k: _interpolate(v, vars) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_interpolate(v, vars) for v in value]
+    return value
+def _resolve_secrets(value: Any) -> Any:
+    """Recursively resolve ${SECRET_NAME} references from environment."""
+    if isinstance(value, str):
+        def repl(m: re.Match) -> str:
+            name = m.group(1)
+            v = os.environ.get(name)
+            if v is None:
+                raise ValueError(f"Secret {name!r} referenced in config but not set in environment")
+            return v
+        return _SECRET_RE.sub(repl, value)
+    if isinstance(value, dict):
+        return {k: _resolve_secrets(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_resolve_secrets(v) for v in value]
+    return value
+@dataclass
+class DataSource:
+    name: str
+    type: Literal["rest", "sql", "graphql", "mcp", "file"]
+    config: dict = field(default_factory=dict)
+    cache_seconds: int = 0
+    description: str = ""
+    @classmethod
+    def from_dict(cls, name: str, d: dict) -> "DataSource":
+        t = d.get("type")
+        if t not in ("rest", "sql", "graphql", "mcp", "file"):
+            raise ValueError(f"Source {name!r}: unknown type {t!r}")
+        return cls(
+            name=name,
+            type=t,
+            config={k: v for k, v in d.items() if k not in ("type", "cache", "description")},
+            cache_seconds=int(d.get("cache", 0)),
+            description=d.get("description", ""),
+        )
+@dataclass
+class Action:
+    name: str
+    type: Literal["rest"] = "rest"  # only REST actions for v2; SQL/MCP later
+    method: str = "POST"
+    url: str = ""
+    headers: dict = field(default_factory=dict)
+    body_template: dict = field(default_factory=dict)
+    bind: list[str] = field(default_factory=list)  # keys the LLM may supply
+    confirm: bool = True
+    audit: bool = True
+    requires_role: str | None = None
+    description: str = ""
+    @classmethod
+    def from_dict(cls, name: str, d: dict) -> "Action":
+        bind = d.get("bind", [])
+        if not isinstance(bind, list):
+            raise ValueError(f"Action {name!r}: 'bind' must be a list")
+        return cls(
+            name=name,
+            type="rest",
+            method=d.get("method", "POST").upper(),
+            url=d.get("url", ""),
+            headers=d.get("headers", {}),
+            body_template=d.get("body", {}),
+            bind=bind,
+            confirm=bool(d.get("confirm", True)),
+            audit=bool(d.get("audit", True)),
+            requires_role=d.get("requires_role"),
+            description=d.get("description", ""),
+        )
+@dataclass
+class AppConfig:
+    sources: dict[str, DataSource] = field(default_factory=dict)
+    actions: dict[str, Action] = field(default_factory=dict)
+    version: int = 1
+    def source(self, name: str) -> DataSource | None:
+        return self.sources.get(name)
+    def action(self, name: str) -> Action | None:
+        return self.actions.get(name)
+    def source_names(self) -> list[str]:
+        return sorted(self.sources.keys())
+    def action_names(self) -> list[str]:
+        return sorted(self.actions.keys())
+    @classmethod
+    def from_dict(cls, d: dict) -> "AppConfig":
+        d = _resolve_secrets(d)
+        sources = {n: DataSource.from_dict(n, s) for n, s in d.get("sources", {}).items()}
+        actions = {n: Action.from_dict(n, a) for n, a in d.get("actions", {}).items()}
+        return cls(sources=sources, actions=actions, version=d.get("version", 1))
+    @classmethod
+    def from_file(cls, path: str | Path) -> "AppConfig":
+        p = Path(path).resolve()
+        data = yaml.safe_load(p.read_text())
+        # interpolate {config_dir} in string values so paths stay relative to the YAML file
+        config_dir = str(p.parent)
+        data = _interpolate(data, {"config_dir": config_dir})
+        return cls.from_dict(data)
+    @classmethod
+    def empty(cls) -> "AppConfig":
+        return cls()
+    def to_prompt_section(self) -> str:
+        """Render the data sources + actions as sections of the LLM prompt.
+        The LLM only sees intent/source names — never URLs, never secrets.
+        This is the security boundary for writes and the grounding layer
+        for data.
+        """
+        lines: list[str] = []
+        if self.sources:
+            lines.append("Data sources (use `src=\"name\"` to bind a component to live data):")
+            lines.append("")
+            for s in self.sources.values():
+                desc = f" — {s.description}" if s.description else ""
+                lines.append(f"- {s.name} ({s.type}){desc}")
+            lines.append("")
+        if self.actions:
+            lines.append("Available actions (use `intent=\"name\"` on a Button):")
+            lines.append("")
+            for a in self.actions.values():
+                bind = ", ".join(a.bind) if a.bind else "(no args)"
+                conf = " [requires confirmation]" if a.confirm else ""
+                desc = f" — {a.description}" if a.description else ""
+                lines.append(f"- {a.name}({bind}){conf}{desc}")
+            lines.append("")
+        return "\n".join(lines)