fabricatio-webui

MIT

Web UI service for the Fabricatio LLM application framework. Serves a Vue-based single-page application built with Vite over an axum HTTP server (Rust, bound via PyO3).

Installation

pip install fabricatio[webui]
# or
pip install fabricatio-webui

The CLI entry point requires the cli extra:

pip install fabricatio-webui[cli]

Quick Start

Start the service with the bundled frontend:

fc-webui

This serves the SPA at http://127.0.0.1:9846. Use --frontend-dir / -d to point at a custom build, and --addr / -a to change the bind address:

fc-webui --addr 0.0.0.0:3000 --frontend-dir ./dist

Run something in under a minute (no LLM required)

The Hello Fabricatio blueprint is a pure-Python two-step pipeline that needs no LLM, no API keys, and no configuration:

1. On the board canvas, drag webui → Hello Fabricatio from the blueprint rail onto a role (create one first via right-click → Add role).
2. Double-click the role card to open the workflow: a TextStats node wired into a SummarizeStats node.
3. Click ▶ Run on the workflow chip (or press Ctrl+Enter inside the workflow) — the dialog opens pre-filled with the namespace (hello-fabricatio); put your text in Extra init context: {"text": "hello fabricatio"}.
4. Run — the console streams node_start/done events and the task result is the summary line, e.g. [demo] chars: 16, words: 2, lines: 1.

Every other shipped blueprint (novel/typst pipelines) drives real LLM calls and requires configured credentials before it can run.

API

All functionality is exposed through the Rust-backed Python module fabricatio_webui.rust.

start_service(...)

Starts an async HTTP server (axum + tokio) that serves static files from frontend_dir with SPA fallback (all unmatched routes serve index.html). CORS is permissive when allowed_origins is empty, otherwise restricted to the given origins.

The exact Python-visible signature lives in the generated stub (python/fabricatio_webui/rust/__init__.pyi, regenerated by cargo run -p fabricatio-stubgen --features webui).

Execution pipeline

Submissions (POST /api/execute or a WS submit message) are forwarded to an in-process asyncio worker (fabricatio_webui.worker.WorkflowWorker). The worker instantiates Action nodes from the workflow graph, executes them in topological order, and streams lifecycle events back over WebSocket. POST /api/interrupt cancels the running execution (execution_done with cancelled: true). Queue and history are owned by the worker and exposed via GET /api/queue and GET /api/history.

The CLI wires everything together:

# fc-webui — worker + server run on one event loop
import asyncio, json
from fabricatio_webui.blueprints import build_blueprints
from fabricatio_webui.config import webui_config
from fabricatio_webui.registry import build_node_registry
from fabricatio_webui.rust import rust_broadcast, start_service
from fabricatio_webui.worker import WorkflowWorker

async def main() -> None:
    worker = WorkflowWorker(
        rust_broadcast, "./workflows",
        queue_max=webui_config.queue_max, history_max=webui_config.history_max,
    )
    await asyncio.gather(
        start_service("./www", "./workflows", "127.0.0.1:9846",
                      json.dumps(build_node_registry()["node_types"]),
                      json.dumps(build_blueprints()["blueprints"]),
                      list(webui_config.allowed_origins),
                      worker.submit, worker.cancel_current,
                      worker.queue_snapshot, worker.history_snapshot,
                      worker.rebuild_roles,
                      bool(webui_config.persist_workflows)),
        worker.run(),
    )

asyncio.run(main())

Board editor

The frontend is a node-based board editor for authoring role-driven workflows. A board is the top-level saved document (format_version: 2) holding:

• roles — each with a name, description, and a list of workflows; every workflow is a node graph plus the namespace pattern it subscribes to (e.g. "write::book" → "write::book::*::Pending").
• actions — optional board-level custom Action definitions (emitted as Python subclasses by the code generator).

Blueprints are collected at startup from the workflows subpackage of every installed fabricatio-* package (the node catalog's actions likewise, from each package's actions tree), so installing another ecosystem package is enough for its content to appear — no configuration. They are served via GET /api/blueprints and offered in the sidebar for one-click board seeding. The introspected node catalog — every registered Action subclass with its typed ports, config fields, widget hints, MRO groups, source code, and an 8-hex schema fingerprint — comes from GET /api/nodes. Boards are CRUD-managed through GET|POST /api/workflows and GET|DELETE /api/workflows/{id}; every save/delete re-dispatches roles onto the worker's event bus.

Using the editor

• Add nodes: right-click or double-click the canvas → fuzzy-searchable node menu grouped by category. Ctrl+F opens the command palette for node/command search from anywhere.
• Wire dataflow: drag between port dots; connections are type-checked (isValidConnection), optional inputs render hollow handles.
• Configure inline: every config field renders an in-node widget derived from the Action's pydantic annotations — toggles, number steppers with min/max/step, combos fed by Literal options, text/textarea, JSON fields; fields are grouped by their owning class in the Action's MRO.
• Run: click ▶ on a workflow chip (role card) to debug-run exactly that workflow — the dialog opens pre-filled with its name, namespace, and stored init context. Inside the workflow editor Ctrl+Enter opens the same dialog; the toolbar Publish publishes a free-form task to any namespace. Per-node status badges + the live console stream (node_start/done/error events); POST /api/interrupt cancels mid-run. The node currently executing gets a purple breathing halo on the canvas.
• Save: Ctrl+S persists the board server-side; autosave drafts go to browser localStorage.

Export as CLI / Python package

Every role card carries a code action that opens the generated-module dialog — a full export panel. Pick a scope and a format, preview every generated file in tabs, then copy, download a single file, or export the whole artifact as .zip:

• Scope — whole role (all of its workflows) or a single workflow.
• Format:
  • Script — the runnable package: main.py with PEP 723 metadata (uv-run-anywhere), pyproject.toml, workflow.json, README.md.
  • CLI tool — everything above plus an installable src-layout package wired to a [project.scripts] console command.
  • Python package — a typed library: pip install . then from <pkg> import build_role, run (py.typed included).
  • PyPI-ready — the package plus a console command, LICENSE, test skeleton, ruff config, and a trusted-publishing release workflow.

The CLI flavor, zero setup:

unzip hello-fabricatio-cli.zip -d hello-fabricatio && cd hello-fabricatio
uv run main.py --text "hello fabricatio"   # script mode, no install
uv tool install .                          # installs the hello-fabricatio command
hello-fabricatio --text "hello fabricatio"

The package flavors, as a library:

unzip hello-fabricatio-package.zip -d hello-fabricatio && cd hello-fabricatio
pip install .
python -c "import asyncio, hello_fabricatio; print(asyncio.run(hello_fabricatio.run({'text': 'hello'})))"

uv reads the PEP 723 block and installs the dependencies automatically. Task input: --text "…" (shorthand), --input '{"text": "…"}' (JSON literal), or --input-file ctx.json. LLM-backed workflows additionally need configured credentials (a fabricatio.toml or FABRICATIO_* env vars); pure-Python pipelines run without any.

Themes

The UI ships dark (default) and light themes. Switch via Settings sidebar → Appearance → Theme. The choice persists per-browser (localStorage) and is applied before first paint (no flash on reload).

Language

The UI ships English and 中文 catalogs (vue-i18n). Switch via Settings sidebar → Appearance → Language; the choice persists per-browser (localStorage) alongside the theme and is applied at startup.

Import / export boards

In the Boards sidebar:

• Export all (header ⤓): downloads fabricatio-boards.json, a JSON array of every saved board.
• Per-board export (row ⤓): downloads <name>.json for that one board.
• Import (header ⤓↑): pick one or more JSON files — each may hold a single board object or an array. Every entry must be format_version: 2; entries are upserted by name (the server derives the storage id from it), so re-importing an edited file updates the existing board. Invalid payloads raise an error toast and leave the stored boards untouched.

Boards exported this way are plain JSON — diff them, commit them, share them, or hand-edit roles/workflows offline and import back.

WebSocket protocol

One endpoint: /ws. Messages are JSON objects tagged by a type field.

Client → server:

Server → client:

Configuration

All options below are read through the fabricatio configuration chain (see the Configuration Guide). Set them under the [ext.webui] table in fabricatio.toml, equivalently under [tool.fabricatio.ext.webui] in pyproject.toml, or via FABRICATIO_EXT__WEBUI__<FIELD_UPPER> environment variables.

[ext.webui]
addr = "127.0.0.1:9846"
queue_max = 64

Access at runtime: from fabricatio_webui.config import webui_config.

Dependencies

• fabricatio-core — core interfaces and configuration
• axum + tokio + tower-http (Rust) — HTTP server and middleware
• typer (optional, for CLI) — fc-webui command

Todos / Known Gaps

Re-verified 2026-08-21 against source. Grouped by category; checkboxes track completion.

Functional gaps

• ComfyNode.vue open-source emit is not wired — the title-bar dblclick emits open-source, but VueFlow does not propagate custom events from custom node types, so NodeCanvas.vue uses the onNodeClick dblclick path instead. Remove the dead emit or document why it is kept.
• llm_token is never emitted — the full receive path exists (Rust variant, TS interface, execution-store token buffer) but no Python code emits token events from LLM calls. Future work: wire streaming tokens into the instrumented actions.

Test gaps

• migrate_board has no test coverage — test_registry.py covers migrate_workflow only; the format 0/1 → 2 board migration is untested.
• Frontend unit coverage is thin — argGroups, autoLayout, board store, NodeWidget, NodeInspector, codegen, and exportPkg have specs. Missing: workflow/ui/execution/loading/notifications stores, most canvas/chrome/board components, and all composables (useWebSocket, useHotkeys, useAppActions, useOutputPreview).
• No Rust tests beyond types.rs — api.rs, state.rs, ws.rs, webui.rs have no unit/integration tests for the HTTP and WS endpoints.

Code hygiene

• Pre-existing ruff violations in registry/_schema.py — C901 (_type_to_port_type 13 > 10) and PLR0912 (_widget_hint 15 > 12); carried over verbatim from the old registry.py. Refactor or extend the # noqa comments.
• Vite INEFFECTIVE_DYNAMIC_IMPORT warning — src/api/client.ts is dynamically imported by stores/board.ts but statically by other stores; the dynamic import never splits a chunk.

Infra / DX

• No E2E browser tests — the workspace lacks a browser-test harness for the webui package (Puppeteer unavailable in the Bun JS VM); only live API checks are possible.
• Python tests lack a package-local runner config — python/ has no pyproject.toml; tests must be invoked with an explicit path (python -m pytest packages/fabricatio-webui/python/tests/) and uv run attempts rebuilds and times out.

License

This project is licensed under the MIT License.