generflow-core 0.2.0__py3-none-any.whl

generflow_core/api/app.py

@@ -0,0 +1,494 @@
+"""FastAPI app: SSE streaming + data binding + actions + HITL.
+
+Phase 2 wire-up. New endpoints:
+  GET  /v1/app/manifest      — app config (sources + actions, no secrets)
+  POST /v1/stream            — streaming (now resolves `src=` refs and emits data.fill)
+  POST /v1/action/dispatch   — build a dispatch plan (returns payload for confirm)
+  POST /v1/action/execute    — execute a confirmed dispatch plan
+  POST /v1/action/audit      — recent audit log
+  POST /v1/render            — local-only mode (no LLM, no data)
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+import time
+import uuid
+from pathlib import Path
+from typing import Any, AsyncIterator
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+from ..adapters import get_adapter
+from .prompt import build_system_prompt
+from ..actions import (
+    ActionError,
+    ActionResult,
+    DispatchPlan,
+    audit_recent,
+    build_dispatch,
+    execute_dispatch,
+)
+from ..databind import AppConfig, ResolverError, resolve_source
+from ..hitl import Decision, pii_gate, scan_pii
+from ..registry import Registry
+from ..spec import Assignment, Component, GFLangParser, Update, parse_update
+from ..replay import EventBuffer
+from ..observability import get_metrics, M
+
+
+app = FastAPI(title="Generflow", version="0.2.0")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Default registry — components
+_registry = Registry()
+
+# Session-scoped event buffers (for replay). Keyed by session_id.
+_session_buffers: dict[str, EventBuffer] = {}
+
+# Default app config — empty. Loaded from GENERFLOW_APP_CONFIG env var
+# or default config file if it exists.
+_app_config = AppConfig.empty()
+_default_cfg = Path(__file__).parent.parent.parent.parent / "examples" / "sample-app.yaml"
+if _default_cfg.exists():
+    try:
+        _app_config = AppConfig.from_file(_default_cfg)
+    except Exception as e:
+        print(f"warning: could not load {_default_cfg}: {e}")
+
+
+class StreamRequest(BaseModel):
+    message: str
+    session_id: str | None = None
+    adapter: str | None = None
+    resolve_data: bool = True   # auto-resolve src= refs (toggle off for fast-path testing)
+    auto_execute: bool = False  # auto-execute confirmed actions (testing only — HITL off)
+
+
+class DispatchRequest(BaseModel):
+    intent: str
+    bindings: dict[str, Any] = {}
+    user: str = "anon"
+
+
+class ExecuteRequest(BaseModel):
+    plan: dict[str, Any]
+    user: str = "anon"
+
+
+def _sse(event: str, data: dict[str, Any]) -> str:
+    return f"event: {event}\ndata: {json.dumps(data, default=str)}\n\n"
+
+
+async def _resolve_ref(path: str, ref_name: str, params: dict | None = None) -> dict[str, Any]:
+    """Resolve a `src=$ref_name` reference. Returns a data.fill event payload."""
+    try:
+        data, fetched_at = await resolve_source(_app_config, ref_name, params or {})
+        return {
+            "path": path,
+            "ref": ref_name,
+            "value": data,
+            "fetched_at": fetched_at,
+            "ok": True,
+        }
+    except ResolverError as e:
+        return {"path": path, "ref": ref_name, "ok": False, "error": str(e)}
+
+
+def _walk_for_refs(node: Any, path: str = "root") -> list[tuple[str, str, dict]]:
+    """Walk a parsed tree, return list of (node_path, ref_name, params)."""
+    out: list[tuple[str, str, dict]] = []
+    if isinstance(node, Assignment):
+        node = node.value
+        path = node.identifier or path
+    if not isinstance(node, Component):
+        return out
+    # look at this node's kwargs for src= refs
+    for k, v in node.kwargs.items():
+        if k == "src" and isinstance(v, Ref):
+            out.append((f"{path}.kwargs.src", v.name, {}))
+    # recurse into children
+    for i, child in enumerate(node.args):
+        if isinstance(child, Literal) and isinstance(child.value, list):
+            for j, sub in enumerate(child.value):
+                out.extend(_walk_for_refs(sub, f"{path}.children[{j}]"))
+    return out
+
+
+async def stream_spec(
+    message: str,
+    session_id: str,
+    adapter_name: str | None,
+    resolve_data: bool = True,
+) -> AsyncIterator[str]:
+    start = time.time()
+    metrics = get_metrics()
+    metrics.incr(M["REQUESTS"], adapter=adapter_name or "default")
+    buf = EventBuffer()
+    _session_buffers[session_id] = buf
+
+    span = metrics.start_span("stream", session_id=session_id, adapter=adapter_name or "default")
+    try:
+        adapter = get_adapter(adapter_name)
+    except Exception as e:
+        span.status = "error"
+        span.error = str(e)
+        metrics.end_span(span, status="error", error=str(e))
+        yield _sse("error", {"message": str(e)})
+        return
+
+    yield _sse("session.start", {"session_id": session_id, "adapter": adapter.name})
+    buf.append("session.start", {"session_id": session_id, "adapter": adapter.name})
+
+    parser = GFLangParser()
+    system_prompt = build_system_prompt(_registry, _app_config)
+    full_text = ""
+    spec_line_count = 0
+    registered_count = 0
+    invalid_count = 0
+    update_count = 0
+    last_root: Component | None = None
+
+    try:
+        llm_span = metrics.start_span("llm_call", adapter=adapter.name)
+        async for chunk in adapter.stream(system=system_prompt, user=message):
+            full_text += chunk
+            nodes = parser.feed_chunk(chunk)
+            for node in nodes:
+                # Try to interpret as Update first
+                if isinstance(node, Assignment) and isinstance(node.value, Component):
+                    upd = parse_update(f"{node.identifier} = ...", lambda _v: None)
+                    # parse_update on Assignment path won't work; do manual
+                    if node.identifier and node.identifier.startswith("Update"):
+                        # This is an Update — synthesize
+                        upd = Update(
+                            path=node.identifier[len("Update("):-1] if "(" in node.identifier else "",
+                            value=node.value,
+                            raw_line=full_text.split("\n")[-2] if "\n" in full_text else "",
+                        )
+                        if upd.path:
+                            update_count += 1
+                            metrics.incr("generflow_updates_total")
+                            ev_data = {
+                                "path": upd.path,
+                                "value": upd.value.to_dict() if hasattr(upd.value, "to_dict") else upd.value,
+                            }
+                            yield _sse("update", ev_data)
+                            buf.append("update", ev_data)
+                            continue
+                if isinstance(node, Assignment):
+                    comp = node.value
+                elif isinstance(node, Component):
+                    comp = node
+                else:
+                    continue
+                if not isinstance(comp, Component):
+                    continue
+                last_root = comp
+                spec_line_count += 1
+                valid = _registry.has(comp.name)
+                if valid:
+                    registered_count += 1
+                    metrics.incr(M["COMPONENTS_MOUNTED"])
+                else:
+                    invalid_count += 1
+                line_data = {
+                    "path": f"line:{spec_line_count}",
+                    "component": comp.name,
+                    "node": comp.to_dict(),
+                    "valid": valid,
+                }
+                yield _sse("spec.line", line_data)
+                buf.append("spec.line", line_data)
+                if valid:
+                    mount_data = {
+                        "path": f"line:{spec_line_count}",
+                        "component": comp.name,
+                        "props_hash": hash(json.dumps(comp.kwargs, sort_keys=True, default=str)),
+                    }
+                    yield _sse("component.mount", mount_data)
+                    buf.append("component.mount", mount_data)
+                    # if has src= ref, resolve and emit data.fill
+                    if resolve_data:
+                        for path, ref_name, params in _walk_for_refs(comp):
+                            if ref_name not in _app_config.source_names():
+                                hitl_data = {
+                                    "kind": "missing_source",
+                                    "path": path,
+                                    "ref": ref_name,
+                                    "question": f"Source '{ref_name}' is not bound. Skip?",
+                                    "options": ["skip", "abort"],
+                                }
+                                yield _sse("hitl.request", hitl_data)
+                                buf.append("hitl.request", hitl_data)
+                                metrics.incr(M["HITL_TRIGGERED"], kind="missing_source")
+                            else:
+                                data_span = metrics.start_span("data_resolve", ref=ref_name)
+                                fill = await _resolve_ref(path, ref_name, params)
+                                metrics.end_span(data_span, status="ok" if fill.get("ok") else "error")
+                                if fill.get("ok"):
+                                    metrics.incr(M["DATA_RESOLVED"], ref=ref_name)
+                                    val = fill["value"]
+                                    # PII check
+                                    kinds = scan_pii(val)
+                                    if kinds:
+                                        hitl_data = {
+                                            "kind": "pii",
+                                            "path": path,
+                                            "ref": ref_name,
+                                            "reason": f"PII detected: {', '.join(kinds)}",
+                                            "options": ["show redacted", "show full", "skip"],
+                                            "confidence": 0.3,
+                                        }
+                                        yield _sse("hitl.request", hitl_data)
+                                        buf.append("hitl.request", hitl_data)
+                                        metrics.incr(M["HITL_TRIGGERED"], kind="pii")
+                                else:
+                                    metrics.incr(M["DATA_FAILED"], ref=ref_name)
+                                yield _sse("data.fill", fill)
+                                buf.append("data.fill", fill)
+        metrics.end_span(llm_span, status="ok")
+        # flush
+        for node in parser.flush():
+            spec_line_count += 1
+    except Exception as e:
+        span.status = "error"
+        span.error = str(e)
+        yield _sse("error", {"message": f"stream error: {e}"})
+        buf.append("error", {"message": str(e)})
+
+    latency_ms = int((time.time() - start) * 1000)
+    tokens = len(full_text) // 4
+    metrics.observe(M["LATENCY_STREAM"], latency_ms, adapter=adapter.name)
+    metrics.incr(M["TOKENS"], value=tokens, adapter=adapter.name)
+    end_data = {
+        "session_id": session_id,
+        "tokens": tokens,
+        "latency_ms": latency_ms,
+        "spec_lines": spec_line_count,
+        "registered": registered_count,
+        "invalid": invalid_count,
+        "updates": update_count,
+        "adapter": adapter.name,
+        "events": len(buf),
+        "text": full_text,
+    }
+    yield _sse("stream.end", end_data)
+    buf.append("stream.end", end_data)
+    span.attributes["tokens"] = tokens
+    span.attributes["spec_lines"] = spec_line_count
+    span.attributes["registered"] = registered_count
+    span.attributes["invalid"] = invalid_count
+    metrics.end_span(span)
+
+
+# ── Routes ───────────────────────────────────────────────────────────────
+
+@app.get("/")
+async def root() -> dict:
+    return {
+        "name": "generflow-core",
+        "version": "0.2.0",
+        "registry_components": _registry.names(),
+        "app_sources": _app_config.source_names(),
+        "app_actions": _app_config.action_names(),
+    }
+
+
+@app.get("/health")
+async def health() -> dict:
+    return {"status": "ok", "version": "0.2.0"}
+
+
+@app.get("/v1/registry/manifest")
+async def manifest() -> dict:
+    return _registry.manifest()
+
+
+@app.get("/v1/app/manifest")
+async def app_manifest() -> dict:
+    """App config manifest: sources + actions, no secrets."""
+    return {
+        "version": _app_config.version,
+        "sources": [
+            {"name": s.name, "type": s.type, "description": s.description, "cache_seconds": s.cache_seconds}
+            for s in _app_config.sources.values()
+        ],
+        "actions": [
+            {
+                "name": a.name,
+                "method": a.method,
+                "bind": a.bind,
+                "confirm": a.confirm,
+                "requires_role": a.requires_role,
+                "description": a.description,
+            }
+            for a in _app_config.actions.values()
+        ],
+    }
+
+
+@app.post("/v1/stream")
+async def stream(req: StreamRequest):
+    if not req.message.strip():
+        raise HTTPException(400, "message is required")
+    session_id = req.session_id or str(uuid.uuid4())
+    return StreamingResponse(
+        stream_spec(req.message, session_id, req.adapter, req.resolve_data),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",
+            "Connection": "keep-alive",
+        },
+    )
+
+
+@app.post("/v1/action/dispatch")
+async def action_dispatch(req: DispatchRequest) -> dict:
+    """Build a dispatch plan from an intent + bindings. Does NOT execute."""
+    try:
+        plan = build_dispatch(_app_config, req.intent, req.bindings)
+    except ActionError as e:
+        raise HTTPException(400, str(e))
+    return {"plan": plan.to_dict()}
+
+
+@app.post("/v1/action/execute")
+async def action_execute(req: ExecuteRequest) -> dict:
+    """Execute a previously-built dispatch plan. Caller must have shown the
+    user the plan and received approval. This endpoint is idempotent on
+    payload_hash within a short window (dedup is the caller's job)."""
+    p = req.plan
+    # rebuild a thin DispatchPlan from the wire shape
+    action = _app_config.action(p["intent"])
+    if action is None:
+        raise HTTPException(400, f"Unknown action: {p['intent']}")
+    plan = DispatchPlan(
+        intent=p["intent"],
+        action=action,
+        method=p["method"],
+        url=p["url"],
+        headers=p.get("headers", {}),
+        body=p.get("body", {}),
+        payload_hash=p.get("payload_hash", ""),
+        confirm_required=p.get("confirm_required", True),
+        requires_role=p.get("requires_role"),
+        audit=p.get("audit", True),
+    )
+    # role check (caller passes user, this is a stub — real impl would
+    # check against a session/role store)
+    if plan.requires_role and req.user == "anon":
+        raise HTTPException(403, f"Action requires role: {plan.requires_role}")
+    t0 = time.time()
+    result = await execute_dispatch(plan)
+    latency_ms = int((time.time() - t0) * 1000)
+    if plan.audit:
+        from ..actions import audit_record
+        audit_record(
+            intent=plan.intent,
+            user=req.user,
+            payload_hash=plan.payload_hash,
+            status=result.status,
+            latency_ms=latency_ms,
+        )
+    return {"result": result.to_dict(), "latency_ms": latency_ms}
+
+
+@app.get("/v1/action/audit")
+async def action_audit(limit: int = 50) -> dict:
+    return {"entries": audit_recent(limit)}
+
+
+# ── Phase 3 endpoints ────────────────────────────────────────────────────
+
+@app.get("/v1/metrics")
+async def metrics() -> "Response":
+    """Prometheus-format metrics."""
+    from fastapi import Response
+    return Response(content=get_metrics().to_prometheus(), media_type="text/plain")
+
+
+@app.get("/v1/trace")
+async def trace(limit: int = 50) -> dict:
+    """Recent spans + counters."""
+    return get_metrics().to_json()
+
+
+@app.get("/v1/replay/{session_id}")
+async def replay_session(session_id: str) -> dict:
+    """Replay events from a session buffer (for debugging).
+
+    Returns events with their original timestamps. For live replay
+    with rate, use the WebSocket endpoint (Phase 3.5).
+    """
+    buf = _session_buffers.get(session_id)
+    if buf is None:
+        raise HTTPException(404, f"session {session_id} not found")
+    return {
+        "session_id": session_id,
+        "event_count": len(buf),
+        "events": [
+            {"seq": e.seq, "ts": e.ts, "type": e.type, "data": e.data}
+            for e in buf
+        ],
+    }
+
+
+@app.get("/v1/replay/{session_id}/scrub/{seq}")
+async def scrub_session(session_id: str, seq: int) -> dict:
+    """Reconstruct spec state at a given event sequence point."""
+    buf = _session_buffers.get(session_id)
+    if buf is None:
+        raise HTTPException(404, f"session {session_id} not found")
+    return buf.scrub_state(seq)
+
+
+@app.post("/v1/diff")
+async def diff_specs_endpoint(req: StreamRequest) -> dict:
+    """Diff two specs (uses the first line of `message` as `before`, rest as `after`)."""
+    from ..spec import diff_specs, summarize_diff
+    parts = req.message.split("---SEPARATOR---", 1)
+    if len(parts) != 2:
+        # fallback: diff against an empty spec
+        before, after = "", req.message
+    else:
+        before, after = parts
+    entries = diff_specs(before, after)
+    return {"summary": summarize_diff(entries), "entries": entries}
+
+
+@app.post("/v1/render")
+async def render_static(req: StreamRequest):
+    """Local-only mode: parse a static GF-Lang spec, no LLM call, no data."""
+    parser = GFLangParser()
+    nodes = parser.feed_chunk(req.message)
+    out = []
+    for node in nodes:
+        out.append(node.to_dict())
+    return {"nodes": out, "registry": _registry.names()}
+
+
+@app.post("/v1/render-html")
+async def render_html_endpoint(req: StreamRequest):
+    """Local-only mode: render a GF-Lang spec to self-contained HTML."""
+    from ..cli import render_html
+    html = render_html(req.message, _registry)
+    return {"html": html, "bytes": len(html)}
+
+
+def main() -> None:
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=7878)
+
+
+if __name__ == "__main__":
+    main()

generflow_core/api/prompt.py

@@ -0,0 +1,64 @@
+"""System prompt for the LLM.
+
+Phase 2: includes data sources + actions sections, plus rules for
+surgical updates on multi-turn conversations.
+"""
+from __future__ import annotations
+
+from ..databind import AppConfig
+from ..registry import Registry
+
+
+SYSTEM_PROMPT_TEMPLATE = """You are Generflow, an AI that composes user interfaces by emitting GF-Lang specifications.
+
+{registry}
+
+{app}
+
+# GF-Lang syntax (line-oriented)
+
+You emit one logical line per UI node. Each line is independently renderable.
+
+Structure:
+  Component(prop1=value, prop2=value, [ child1, child2 ])
+
+Examples:
+  Header(level=1, text="Q3 Sales")
+  Metric(label=Revenue, value="$2.4M", delta="+12.4%")
+  Card(p=md, title=Dashboard, [ Header(text=Sales), Row([ Metric(label=A, value=100) ]) ])
+
+Rules:
+1. ONLY use the component names listed above. Unknown components will be silently dropped.
+2. ONLY use the props listed for each component. Unknown props are ignored.
+3. Children are always a list `[ ... ]` as the LAST positional argument. Components with `has_children: true` accept a child list.
+4. Strings: use bare identifier for short values (level=1, color=muted) and double-quoted for anything with spaces or special chars (title="My Dashboard").
+5. Numbers are bare (`value=42`), booleans are `true`/`false`, lists use `[ ... ]`.
+6. To bind a component to live data, use `src=source_name` (defined in the data sources above). NEVER invent data values — bind via src.
+7. To make a Button perform an action, use `intent=intent_name` (defined in the actions above). Pass form state via `bind=[field1, field2]` in a Submit wrapper.
+8. Emit one root component named `root = ...` (or just the bare top-level component, treated as root).
+9. NEVER write prose, explanations, or markdown. Output ONLY GF-Lang.
+10. NEVER wrap in code fences.
+11. If the user's request is unclear, ask a clarifying question as plain text (this is the only exception to rule 9).
+
+# Multi-turn updates
+
+When the user asks to change a small detail on an EXISTING UI (e.g., "change the title to 'Q4 Sales'"), DO NOT regenerate the whole spec. Instead emit an Update:
+
+  Update(path="root.children[0].kwargs.text", value="Q4 Sales")
+
+Path syntax: dot-separated, with `[index]` for children. Common paths:
+  - `root.children[0].kwargs.title` — the title prop of the first child
+  - `root.children[2].children[1].kwargs.value` — nested
+  - `root.kwargs.title` — the root's own prop
+
+Surgical updates are ~10x cheaper than full re-renders. Use them whenever possible.
+
+# Streaming
+
+Emit the root first, then fill in children. The renderer progressively displays what it has, so the user sees structure before data.
+"""
+
+
+def build_system_prompt(registry: Registry, app: AppConfig | None = None) -> str:
+    app_section = app.to_prompt_section() if app else ""
+    return SYSTEM_PROMPT_TEMPLATE.format(registry=registry.to_prompt(), app=app_section)