generflow-core 0.2.0

Generflow Python runtime — streams low-token UI specs over SSE, with HITL checkpoints, live data binding, action gating, and rewind/replay.

generflow-core

The Python runtime for Generflow — open-source generative UI.

Generflow solves four problems nobody else has solved together:

1. Token-efficient UI description — GF-Lang is a streaming-friendly DSL that uses 57.6% fewer tokens than equivalent JSON (benchmarked, beats JSON on 10/10 widgets).
2. Data-grounded rendering — components can declare $refs to live data sources (REST, SQL, GraphQL, MCP). No fabricated numbers.
3. HITL hallucination mitigation — every render passes through a security boundary (component allow-list), and every action is gated by HITL checks (PII scan, missing source, ambiguity, low confidence).
4. Cross-platform — Web Components + React + vanilla TS renderers. Same protocol, any framework.

Install

pip install generflow-core

Or with all dev extras:

pip install generflow-core[dev]

Quickstart (no API key)

from generflow_core.adapters import EchoAdapter
from generflow_core.spec import GFLangParser
from generflow_core.registry import Registry
import asyncio

async def main():
    adapter = EchoAdapter()
    registry = Registry()
    parser = GFLangParser()

    full = ""
    async for chunk in adapter.stream("", "build a dashboard"):
        full += chunk

    for node in parser.feed_chunk(full):
        if registry.has(node.name):
            print(f"  ✓ {node.name}")

asyncio.run(main())

Quickstart (real LLM)

export OPENAI_API_KEY=sk-...
python -m generflow_core.api.app    # → http://localhost:7878

Then send a chat message:

curl -X POST http://localhost:7878/v1/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "build a sales dashboard", "session_id": "demo"}'

CLI

The package ships a CLI for local-only rendering (no LLM, no API key):

generflow-render render dashboard.gf -o dashboard.html
generflow-render validate dashboard.gf
generflow-render diff before.gf after.gf
generflow-render to-a2ui dashboard.gf -o dashboard.a2ui.json
generflow-render from-a2ui incoming.a2ui.json -o spec.gf

Architecture

┌──────────────────┐    SSE     ┌──────────────────┐
│   LLM Adapter    │ ─────────▶ │  SSE /v1/stream  │
│ (OpenAI/Anthro/  │            │                  │
│  Echo)           │            │  parser (Python) │
└──────────────────┘            │      │           │
                                │      ▼           │
                                │  Registry        │
                                │  (allow-list)    │
                                │      │           │
                                │      ▼           │
                                │  DataResolver    │
                                │  (REST/SQL/GQL)  │
                                │      │           │
                                │      ▼           │
                                │  HITL gates      │
                                │  (PII/conf/etc)  │
                                │      │           │
                                │      ▼           │
                                │  Action dispatch │
                                │  (intent → HTTP) │
                                └──────────────────┘
                                         │
                                         ▼
                              SSE events: spec.line,
                              component.mount, data.fill,
                              hitl.request, action.request,
                              update, stream.end

Protocol

Generflow's protocol is a stream of typed SSE events. See the GF-Lang grammar and the event reference.

event: session.start
data: {"session_id":"demo","adapter":"openai"}

event: spec.line
data: {"path":"line:1","component":"Card","node":{...},"valid":true}

event: data.fill
data: {"ref":"monthly_revenue","ok":true,"value":[...]}