generflow-core 0.2.0__tar.gz

generflow_core-0.2.0/PKG-INFO

@@ -0,0 +1,161 @@
+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":[...]}

generflow_core-0.2.0/README.md

@@ -0,0 +1,119 @@
+# 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":[...]}

generflow_core-0.2.0/pyproject.toml

@@ -0,0 +1,91 @@
+[build-system]
+requires = ["setuptools>=68", "wheel", "setuptools_scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "generflow-core"
+version = "0.2.0"
+description = "Generflow Python runtime — streams low-token UI specs over SSE, with HITL checkpoints, live data binding, action gating, and rewind/replay."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Generflow", email = "team@generflow.dev" }]  # placeholder
+keywords = [
+    "ai",
+    "generative-ui",
+    "llm",
+    "sse",
+    "agent",
+    "hitl",
+    "human-in-the-loop",
+    "design-system",
+    "streaming",
+    "tooling",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "Typing :: Typed",
+]
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.27",
+    "pydantic>=2.5",
+    "openai>=1.12",
+    "anthropic>=0.18",
+    "pyyaml>=6.0",
+    "tiktoken>=0.5",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "pytest-asyncio>=0.23",
+    "httpx>=0.26",
+    "build>=1.0",
+    "twine>=4.0",
+]
+all = ["generflow-core[dev]"]
+
+[project.urls]
+Homepage = "https://generflow.dev"
+Repository = "https://github.com/generflow/generflow"
+Documentation = "https://docs.generflow.dev"
+Issues = "https://github.com/generflow/generflow/issues"
+Changelog = "https://github.com/generflow/generflow/blob/main/CHANGELOG.md"
+
+[project.scripts]
+generflow = "generflow_core.api.app:main"
+generflow-render = "generflow_core.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["generflow_core*"]
+
+[tool.setuptools.package-data]
+generflow_core = ["py.typed"]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+filterwarnings = [
+    "ignore::DeprecationWarning:datetime.*",
+]
+
+[tool.build_sphinx]
+source-dir = "docs"
+build-dir = "docs/_build"

generflow_core-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

generflow_core-0.2.0/src/generflow_core/__init__.py

@@ -0,0 +1,3 @@
+"""generflow-core: Generflow Python backend runtime."""
+
+__version__ = "0.1.0"

generflow_core-0.2.0/src/generflow_core/actions/__init__.py

@@ -0,0 +1,22 @@
+"""Action module: intent dispatch + audit."""
+from .dispatcher import (
+    ActionError,
+    ActionResult,
+    DispatchPlan,
+    audit_clear,
+    audit_recent,
+    audit_record,
+    build_dispatch,
+    execute_dispatch,
+)
+
+__all__ = [
+    "ActionError",
+    "ActionResult",
+    "DispatchPlan",
+    "audit_clear",
+    "audit_recent",
+    "audit_record",
+    "build_dispatch",
+    "execute_dispatch",
+]

generflow_core-0.2.0/src/generflow_core/actions/dispatcher.py

@@ -0,0 +1,223 @@
+"""Action dispatcher: intent → configured endpoint, with HITL confirm.
+
+The LLM emits `intent="refund.approve"` on a Button. This module:
+  1. Looks up the intent in the app config
+  2. Merges the bound values (form state) into the body template
+  3. Returns a dispatch plan with confirm-required flag
+
+The actual HTTP call is made by the SSE handler after the user
+confirms via the HITL gate. This separation lets us:
+- Audit the intent *before* the call
+- Show the user exactly what will be sent
+- Cancel cleanly if they back out
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..databind import AppConfig, Action
+
+
+class ActionError(Exception):
+    pass
+
+
+@dataclass
+class DispatchPlan:
+    """A fully-resolved plan for an action call, ready for user confirmation.
+
+    Not yet executed — `executed` is False until the HITL gate (or auto-approve)
+    fires the actual request.
+    """
+    intent: str
+    action: Action
+    method: str
+    url: str
+    headers: dict
+    body: dict
+    payload_hash: str
+    confirm_required: bool
+    requires_role: str | None
+    audit: bool
+
+    def to_dict(self) -> dict:
+        return {
+            "intent": self.intent,
+            "method": self.method,
+            "url": self.url,
+            "headers": {k: v for k, v in self.headers.items() if k.lower() != "authorization"},
+            "body": self.body,
+            "payload_hash": self.payload_hash,
+            "confirm_required": self.confirm_required,
+            "requires_role": self.requires_role,
+            "audit": self.audit,
+        }
+
+
+def build_dispatch(
+    config: AppConfig,
+    intent: str,
+    bindings: dict[str, Any] | None = None,
+) -> DispatchPlan:
+    """Build a dispatch plan from an intent + bound values.
+
+    `bindings` is the form state or other values the LLM specified via
+    `bind=[...]` on the Button. Only keys in the action's allow-listed
+    `bind` are accepted — everything else is dropped (field smuggling
+    prevention).
+    """
+    action = config.action(intent)
+    if action is None:
+        raise ActionError(f"Unknown action intent: {intent!r}")
+    bindings = bindings or {}
+    # enforce bind allow-list
+    allowed = set(action.bind)
+    sanitized: dict[str, Any] = {}
+    for k, v in bindings.items():
+        if k in allowed:
+            sanitized[k] = v
+    # merge into body template — keep original types (int, str, etc.)
+    body = _render_template(action.body_template, sanitized)
+    # no-op for now: keep body as-is. The binding type flows through
+    # the renderer; downstream JSON serialization handles the rest.
+    # interpolate URL params
+    url = action.url
+    for k, v in sanitized.items():
+        url = url.replace(f"${k}", str(v))
+    # payload hash (used for audit dedup + render preview)
+    payload = json.dumps(body, sort_keys=True, default=str)
+    payload_hash = hashlib.sha256(payload.encode()).hexdigest()[:16]
+    # auth: bearer is interpolated from env at config-load time,
+    # so we just need to copy the configured headers
+    return DispatchPlan(
+        intent=intent,
+        action=action,
+        method=action.method,
+        url=url,
+        headers=dict(action.headers),
+        body=body,
+        payload_hash=payload_hash,
+        confirm_required=action.confirm,
+        requires_role=action.requires_role,
+        audit=action.audit,
+    )
+
+
+def _render_template(template: Any, values: dict[str, Any]) -> Any:
+    """Recursively replace `$key` in strings with `values[key]`."""
+    if isinstance(template, str):
+        out = template
+        for k, v in values.items():
+            out = out.replace(f"${k}", str(v))
+        return out
+    if isinstance(template, dict):
+        return {k: _render_template(v, values) for k, v in template.items()}
+    if isinstance(template, list):
+        return [_render_template(v, values) for v in template]
+    return template
+
+
+def _coerce_types(body: Any) -> Any:
+    """If a value came back as a numeric string ("89") but the binding was
+    numeric (89), restore the original type. Keeps dispatch payloads
+    type-correct for downstream APIs."""
+    if isinstance(body, dict):
+        return {k: _coerce_types(v) for k, v in body.items()}
+    if isinstance(body, list):
+        return [_coerce_types(v) for v in body]
+    if isinstance(body, str):
+        s = body.strip()
+        if s and (s[0].isdigit() or (s[0] == "-" and len(s) > 1 and s[1].isdigit())):
+            try:
+                if "." in s:
+                    return float(s)
+                return int(s)
+            except ValueError:
+                pass
+    return body
+
+
+# ── Execution ──────────────────────────────────────────────────────────────
+
+import asyncio
+
+
+class ActionResult:
+    def __init__(self, status: int, body: Any, ok: bool, error: str | None = None) -> None:
+        self.status = status
+        self.body = body
+        self.ok = ok
+        self.error = error
+
+    def to_dict(self) -> dict:
+        return {"status": self.status, "ok": self.ok, "error": self.error, "body": self.body}
+
+
+async def execute_dispatch(plan: DispatchPlan) -> ActionResult:
+    """Execute a confirmed dispatch plan. Sends the actual HTTP request."""
+    import httpx
+    try:
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            r = await client.request(
+                plan.method,
+                plan.url,
+                json=plan.body,
+                headers=plan.headers,
+            )
+            try:
+                body = r.json()
+            except Exception:
+                body = r.text
+            return ActionResult(status=r.status_code, body=body, ok=r.is_success)
+    except Exception as e:
+        return ActionResult(status=0, body=None, ok=False, error=str(e))
+
+
+# ── Audit log ─────────────────────────────────────────────────────────────
+
+import datetime
+import threading
+
+
+_AUDIT_LOG: list[dict] = []
+_AUDIT_LOCK = threading.Lock()
+
+
+def audit_record(
+    intent: str,
+    user: str,
+    payload_hash: str,
+    status: int,
+    latency_ms: int,
+    extra: dict | None = None,
+) -> None:
+    """Append a record to the in-memory audit log.
+
+    Production would back this with Postgres / OpenTelemetry / etc.
+    For v1, an in-memory list is enough to demonstrate the shape.
+    """
+    rec = {
+        "ts": datetime.datetime.utcnow().isoformat() + "Z",
+        "intent": intent,
+        "user": user,
+        "payload_hash": payload_hash,
+        "status": status,
+        "latency_ms": latency_ms,
+    }
+    if extra:
+        rec.update(extra)
+    with _AUDIT_LOCK:
+        _AUDIT_LOG.append(rec)
+
+
+def audit_recent(limit: int = 50) -> list[dict]:
+    with _AUDIT_LOCK:
+        return list(_AUDIT_LOG[-limit:])
+
+
+def audit_clear() -> None:
+    with _AUDIT_LOCK:
+        _AUDIT_LOG.clear()

generflow_core-0.2.0/src/generflow_core/adapters/__init__.py

@@ -0,0 +1,11 @@
+"""LLM adapters — pluggable backends (OpenAI, Anthropic, Echo for local dev)."""
+from .llm import AnthropicAdapter, EchoAdapter, LLMAdapter, LLMError, OpenAIAdapter, get_adapter
+
+__all__ = [
+    "AnthropicAdapter",
+    "EchoAdapter",
+    "LLMAdapter",
+    "LLMError",
+    "OpenAIAdapter",
+    "get_adapter",
+]