generflow-core 0.2.0__py3-none-any.whl

generflow_core/__init__.py

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

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/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/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",
+]

generflow_core/adapters/llm.py

@@ -0,0 +1,186 @@
+"""LLM adapter base + OpenAI + Anthropic implementations."""
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from typing import AsyncIterator
+
+
+class LLMError(Exception):
+    pass
+
+
+class LLMAdapter(ABC):
+    """Base class. Adapters convert a prompt into a stream of text chunks."""
+
+    name: str = "base"
+
+    @abstractmethod
+    async def stream(
+        self,
+        system: str,
+        user: str,
+        *,
+        max_tokens: int = 2000,
+        temperature: float = 0.3,
+    ) -> AsyncIterator[str]:
+        """Yield text chunks as they arrive from the model."""
+        if False:  # pragma: no cover — abstract
+            yield ""
+
+
+class OpenAIAdapter(LLMAdapter):
+    name = "openai"
+
+    def __init__(self, model: str = "gpt-4o-mini", api_key: str | None = None) -> None:
+        self.model = model
+        self.api_key = api_key or os.environ.get("OPENAI_API_KEY", "")
+        if not self.api_key:
+            raise LLMError("OPENAI_API_KEY not set")
+
+    async def stream(
+        self,
+        system: str,
+        user: str,
+        *,
+        max_tokens: int = 2000,
+        temperature: float = 0.3,
+    ) -> AsyncIterator[str]:
+        try:
+            from openai import AsyncOpenAI
+        except ImportError as e:
+            raise LLMError("openai package not installed. pip install openai") from e
+        client = AsyncOpenAI(api_key=self.api_key)
+        resp = await client.chat.completions.create(
+            model=self.model,
+            messages=[
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+            max_tokens=max_tokens,
+            temperature=temperature,
+            stream=True,
+        )
+        async for chunk in resp:
+            if chunk.choices and chunk.choices[0].delta.content:
+                yield chunk.choices[0].delta.content
+
+
+class AnthropicAdapter(LLMAdapter):
+    name = "anthropic"
+
+    def __init__(self, model: str = "claude-3-5-sonnet-latest", api_key: str | None = None) -> None:
+        self.model = model
+        self.api_key = api_key or os.environ.get("ANTHROPIC_API_KEY", "")
+        if not self.api_key:
+            raise LLMError("ANTHROPIC_API_KEY not set")
+
+    async def stream(
+        self,
+        system: str,
+        user: str,
+        *,
+        max_tokens: int = 2000,
+        temperature: float = 0.3,
+    ) -> AsyncIterator[str]:
+        try:
+            from anthropic import AsyncAnthropic
+        except ImportError as e:
+            raise LLMError("anthropic package not installed. pip install anthropic") from e
+        client = AsyncAnthropic(api_key=self.api_key)
+        async with client.messages.stream(
+            model=self.model,
+            system=system,
+            messages=[{"role": "user", "content": user}],
+            max_tokens=max_tokens,
+            temperature=temperature,
+        ) as stream:
+            async for text in stream.text_stream:
+                yield text
+
+
+class EchoAdapter(LLMAdapter):
+    """Returns a hardcoded spec — useful for local dev / tests / offline demo.
+
+    Picks a spec based on keywords in the user message so the eval harness
+    can exercise multiple flows without an API key.
+    """
+
+    name = "echo"
+
+    DASHBOARD = """root = Card(title="Sales Dashboard", [
+  Header(level=1, text="Q3 Performance"),
+  Row(gap=md, [
+    Metric(label=Revenue, value="$2.4M", delta="+12.4%"),
+    Metric(label=Deals, value=142, delta="+8"),
+    Metric(label="Win Rate", value="34%", delta="-1.2%"),
+  ]),
+  Chart(type=bar, title="Monthly Revenue", src="monthly_revenue"),
+  Header(level=2, text="Top Customers"),
+  List(src="top_customers"),
+])
+"""
+
+    SIGNUP_FORM = """root = Form(title="Sign up", [
+  Field(name=email, label=Email, type=email),
+  Field(name=password, label=Password, type=password),
+  Button(label="Create account", intent="user.signup"),
+])
+"""
+
+    TOP_CUSTOMERS = """root = Card(title="Top Customers", [
+  Header(level=1, text="By LTV"),
+  List(src="top_customers"),
+])
+"""
+
+    MULTI_SECTION = """root = Card(title="Summary", [
+  Header(level=2, text="Overview"),
+  Row(gap=md, [
+    Metric(label=Revenue, value="$2.4M"),
+    Metric(label=Deals, value=142),
+  ]),
+])
+"""
+
+    GENERIC = """root = Card(title="Generated", [
+  Text([ "Hello" ]),
+])
+"""
+
+    def _pick(self, user: str) -> str:
+        s = user.lower()
+        if "sign up" in s or "signup" in s or "form" in s:
+            return self.SIGNUP_FORM
+        if "top customer" in s or "ltv" in s:
+            return self.TOP_CUSTOMERS
+        if "card" in s and "metric" in s:
+            return self.MULTI_SECTION
+        if "dashboard" in s or "sales" in s:
+            return self.DASHBOARD
+        return self.GENERIC
+
+    async def stream(
+        self,
+        system: str,
+        user: str,
+        *,
+        max_tokens: int = 2000,
+        temperature: float = 0.3,
+    ) -> AsyncIterator[str]:
+        text = self._pick(user)
+        # Simulate streaming by yielding character-by-character with small chunks
+        chunk_size = 12
+        for i in range(0, len(text), chunk_size):
+            yield text[i : i + chunk_size]
+
+
+def get_adapter(name: str | None = None) -> LLMAdapter:
+    """Pick an adapter based on env vars. Defaults to Echo if no keys are set."""
+    if name == "openai" or (name is None and os.environ.get("OPENAI_API_KEY")):
+        if os.environ.get("OPENAI_API_KEY"):
+            return OpenAIAdapter()
+    if name == "anthropic" or (name is None and os.environ.get("ANTHROPIC_API_KEY")):
+        if os.environ.get("ANTHROPIC_API_KEY"):
+            return AnthropicAdapter()
+    return EchoAdapter()

generflow_core/api/__init__.py

@@ -0,0 +1,5 @@
+"""API module: FastAPI app + SSE streaming + local-only render."""
+from .app import app
+from .prompt import build_system_prompt
+
+__all__ = ["app", "build_system_prompt"]