Metadata-Version: 2.4
Name: generflow-core
Version: 0.2.0
Summary: Generflow Python runtime — streams low-token UI specs over SSE, with HITL checkpoints, live data binding, action gating, and rewind/replay.
Author-email: Generflow <team@generflow.dev>
License: Apache-2.0
Project-URL: Homepage, https://generflow.dev
Project-URL: Repository, https://github.com/generflow/generflow
Project-URL: Documentation, https://docs.generflow.dev
Project-URL: Issues, https://github.com/generflow/generflow/issues
Project-URL: Changelog, https://github.com/generflow/generflow/blob/main/CHANGELOG.md
Keywords: ai,generative-ui,llm,sse,agent,hitl,human-in-the-loop,design-system,streaming,tooling
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: pydantic>=2.5
Requires-Dist: openai>=1.12
Requires-Dist: anthropic>=0.18
Requires-Dist: pyyaml>=6.0
Requires-Dist: tiktoken>=0.5
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: httpx>=0.26; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Provides-Extra: all
Requires-Dist: generflow-core[dev]; extra == "all"

# generflow-core

> The Python runtime for [Generflow](https://generflow.dev) — 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 `$ref`s 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

```bash
pip install generflow-core
```

Or with all dev extras:

```bash
pip install generflow-core[dev]
```

## Quickstart (no API key)

```python
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)

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

Then send a chat message:

```bash
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):

```bash
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](https://github.com/generflow/generflow/blob/main/docs/gf-lang.ebnf) and the [event reference](https://docs.generflow.dev/protocol).

```http
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":[...]}
