inline-core 1.1.1__tar.gz

inline_core-1.1.1/.gitignore

@@ -0,0 +1,20 @@
+# Model weights (gigabytes). The engine's models root — `models_dir()` defaults to ./models, and
+# runners scan ./models/<category>/ (e.g. diffusion_models/). Leading slash anchors this to the repo
+# root ONLY, so the source package src/inline_core/models/ (code) stays tracked.
+/models/
+
+# Engine working data: the run DB and generated takes (also grows to gigabytes).
+/.inline/
+
+# Studio app data + project workspace (when created under the repo) and local server logs.
+/.inline-studio-server/
+/InlineStudioProjects/
+*.log
+
+# Python venv + bytecode
+.venv/
+__pycache__/
+*.py[cod]
+
+# Local env overrides
+.env

inline_core-1.1.1/.python-version

@@ -0,0 +1 @@
+3.11

inline_core-1.1.1/CLAUDE.md

@@ -0,0 +1,212 @@
+# Inline Core — Engineering Guide
+
+Inline Core is the **generation engine behind Inline** (the Storyline / Inline Studio UI client). It
+takes a **typed node graph (JSON)** and returns immutable renders ("takes"), running image and video
+models across macOS, Windows, and Linux — from CPU-only boxes and low-VRAM laptops up to multi-GPU
+machines that split a single image's sampling across GPUs (via xDiT). **It is the render backend that
+replaces ComfyUI for Inline.**
+
+> The UI client lives in the separate **Inline Studio / Storyline** repo (`inline-studio`, an Electron
+> app). It drives this engine over the `/v1` HTTP + websocket API. Inline Core is headless and knows
+> nothing about the UI.
+
+> Read this file before changing code. It defines the architecture and the non-negotiable rules.
+> `README.md` is the user/product-facing version of the same story; this is the engineering contract.
+
+## Mental model (everything is organised around this)
+
+```
+Graph (typed nodes + edges)  →  Run  →  Take[]  (immutable renders)
+```
+
+- **Graph** — a JSON DAG of typed nodes. Edges are type-checked (`model`, `vae`, `conditioning`,
+  `latent`, media) **before** the run, so a bad graph is rejected at submit (422), never mid-denoise.
+- **Run** — one execution of a target node's upstream closure. Durable (survives a restart) and
+  pollable; progress streams over a websocket.
+- **Take** — one immutable output. Regenerating adds a take; **nothing is overwritten** (this mirrors
+  Inline Studio's frame/take model — the take history is the core value Comfy lacks).
+- **Node** — has a **descriptor** (the data half: ports, params, file pickers — served at
+  `/v1/models`) and a **runner** (the behavior half). A descriptor with no runner is served and
+  type-checked but cannot execute yet.
+
+### The two boundaries that matter most (why this isn't ComfyUI)
+
+1. **Graph orchestration is decoupled from GPU work.** The executor runs cheap orchestration inline
+   and never runs the denoise loop itself — a model runner submits a `SampleJob` through the
+   **batched-sampler seam** (`sampling/batch.py`). The graph is the unit of caching; the sampler is
+   the unit of batching; the multi-GPU split routes through that same seam.
+2. **The device policy is the single owner of placement.** No node or component ever picks a device,
+   dtype, or offload. They ask `DevicePolicy.placement(role)`. So the same graph runs on a 4090, a
+   6 GB laptop, pure CPU, or split across several GPUs, without touching the graph.
+
+If you find yourself hardcoding a device in a component, or running a denoise loop inside the
+executor, stop — you're breaking one of the two boundaries the whole design exists to keep.
+
+## Architecture
+
+Headless Python. A FastAPI `/v1` server over a run manager, a node registry, and a device policy.
+
+```
+HTTP/WS  →  server/app.py  →  RunManager  →  Executor  →  Registry (descriptor + runner)
+                                                              │
+                                    runner "lowers" to  →  components (TextEncoder/Denoiser/VAE/…)
+                                                              │
+                                            SampleJob  →  BatchedSampler (inline | xDiT worker group)
+```
+
+- **`server/`** — the `/v1` API. `app.py` (routes), `manager.py` (validate → queue → run on a worker
+  thread → fan out events), `run_store.py` (SQLite durability), `bootstrap.py` (best-effort model
+  registration), `serialize.py` (contract JSON), `assets.py` (content-addressed upload).
+- **`graph/`** — the engine core. `schema.py` (typed `Graph`/`Node`/`Edge` + JSON parser),
+  `descriptor.py` (node data half), `runners.py` (node behavior half + source nodes), `registry.py`
+  (descriptors + runners), `validate.py` + `topo.py` (type-check + order), `executor.py` (lazy
+  closure execution, node cache), `primitives.py` (the low-level node vocabulary), `cache.py`.
+- **`components/`** — the five device-agnostic component interfaces (`TextEncoder`, `Scheduler`,
+  `Denoiser`, `Sampler`, `VAE`) plus opaque `Conditioning`/`Latents`. Placement comes from the ctx.
+- **`sampling/`** — `batch.py`: the graph/GPU boundary. `SampleJob` → `BatchedSampler`
+  (`InlineBatchedSampler` today; `XFuserBatchedSampler` routes a parallel placement to the worker
+  group). Keep this module torch-free and mockable.
+- **`device/`** — the policy. `policy.py` (interface: `Placement`, `Profile`, quant, attention),
+  `memory.py` (`MemoryPolicy`), `detect.py` / `auto.py` (enumerate GPUs, NVLink vs PCIe), `types.py`.
+- **`parallel/`** — the xDiT (xfuser) worker group: one process per GPU via `torchrun`, talking over
+  local IPC behind the sampler seam. `launch.py`, `worker.py`, `group.py`, `registry.py`, `config.py`,
+  `protocol.py`. The HTTP server, DB, and graph stay single-process; only the denoise distributes.
+- **`models/`** — `catalog.py` (scans the models root, feeds `options_from` selects + the registry
+  version) and the **model-runner subpackages** (e.g. `zimage/`), imported best-effort by
+  `server/bootstrap.py` so a torch-less install still boots.
+- **`runtime/`** — `context.py` (`ExecutionContext`, `CancelToken`), `run.py` (`RunState`),
+  `progress.py` (events + emitters), `store.py` / `file_store.py` (`TakeStore`: owns take bytes/hash/
+  uri).
+- **`importer/`** — `comfy.py`: best-effort ComfyUI-workflow → Inline-Core-graph mapping. All ComfyUI
+  format knowledge lives here.
+- **`config.py`** — all env config, small and explicit. **`takes.py`**, **`media.py`**, **`errors.py`**
+  — domain primitives (`Take`/`AssetRef`, `MediaKind`, the error hierarchy).
+
+### Node vocabularies (three, and their status)
+
+- **Source nodes** (`graph/runners.py`) — `input/text`, `input/image`. Runners exist; pure, no takes.
+  These are the closure boundary: the UI feeds curated inputs in as source nodes so nothing upstream
+  is recomputed.
+- **Low-level primitives** (`graph/primitives.py`) — `load/diffusion-model`, `load/vae`,
+  `load/text-encoder`, `encode/text`, `latent/empty`, `sample`, `vae/decode`, `vae/encode`. These are
+  the ComfyUI-equivalent decomposed graph and the intended long-term surface. **Descriptor-only
+  today — their runners land in C2.** A graph built from them validates and type-checks but raises
+  `No runner registered` at execution.
+- **Model runners** (`models/<name>/`) — high-level single generation nodes. **`alibaba/z-image-turbo`
+  (`models/zimage/`) is the one runnable generation path today** (prompt + optional image → one take,
+  backed by diffusers' `ZImagePipeline`/`ZImageImg2ImgPipeline`). This is the "Z-Image pipeline that
+  already works" — the primitives will reach parity in C2. It loads from a **single diffusion
+  `.safetensors`** (drop one file in `diffusion_models/`, ComfyUI-style — no repo folder to set up):
+  the runner loads the transformer via `from_single_file` and pulls the VAE / text-encoder / tokenizer
+  from the reference repo behind the scenes, so the user only ever handles one model file.
+- **Low-level primitives and source nodes are `hidden`** (`NodeDescriptor.hidden`): they are served for
+  validation/execution but never offered in the UI's add-node menu. Generation stays one-click — the
+  user sees only high-level model nodes; loaders/VAE/encoders are wired up behind them.
+
+Only media-output nodes (`vae/decode`, a model runner) become Frames with take history; the engine
+handles (`model`, `vae`, `text-encoder`, `conditioning`, `latent`) are opaque typed sockets passed
+between nodes and are never takes.
+
+### Storage & configuration (all env, see `config.py`)
+
+- **Models root** — `INLINE_MODELS_DIR`, else `./models`. **Bring your own weights; nothing is
+  downloaded.** ComfyUI-style category subfolders (`diffusion_models/`, `vae/`, `text_encoders/`,
+  `loras/`, `controlnet/`, `checkpoints/`, `clip_vision/`, `upscale_models/`, `embeddings/`). The
+  catalog scans this on start; a file dropped in bumps the registry version so clients refetch
+  `/v1/models`. A model may be a single weight file or a folder (e.g. a diffusers snapshot or a
+  sharded text encoder).
+- **Data dir** — `INLINE_DATA_DIR`, else `./.inline`. Engine-owned working data: `runs.db` (durable
+  runs) and `takes/` (output bytes).
+- **Server bind** — `INLINE_HOST` (default `127.0.0.1`), `INLINE_PORT` (default `8848`).
+- **Model overrides** — e.g. `INLINE_ZIMAGE_MODEL` (a single `.safetensors` file path, a local
+  diffusers dir, or a HF repo id for Z-Image). Auto-resolved from `diffusion_models/` when unset.
+- **Memory** — always prefer the GPU: even under the `lowvram` profile, weights stay resident on the
+  GPU (VAE tiling/slicing + attention slicing + int8 do the saving); we do **not** auto-offload to CPU.
+  `INLINE_ALLOW_CPU_OFFLOAD=1` opts back into `enable_model_cpu_offload()` for extreme cases.
+- **Multi-GPU** — `INLINE_PARALLEL` (e.g. `pipefusion=2`, `pipefusion=2,ulysses=2`); degrees multiply
+  to the world size, which must equal the GPU count.
+
+### The `/v1` API (the contract with Inline Studio)
+
+- `POST /v1/runs {graph, target}` → `{runId}` (validated up front; 422 on a bad graph, 409 on a
+  reused `clientRunId` with a different graph).
+- `GET /v1/runs/{id}` → durable run state. `DELETE /v1/runs/{id}` cancels.
+- `GET /v1/runs/{id}/events` (websocket) → a `snapshot`, then `progress` / `node_done` / `run_done`.
+- `GET /v1/models` → node descriptors + `registryVersion` (ETag-aware; folds in the model-file scan).
+- `GET /v1/models/{type}`, `GET /v1/takes/{id}`, `GET /v1/takes/{id}/bytes`, `POST /v1/assets`,
+  `GET /v1/health`.
+
+Errors are `{error: {code, message, nodeId?}}` with the right HTTP status — they never leak a raw
+traceback. The JSON shapes live in `server/serialize.py`.
+
+## Multi-GPU (xDiT): split one image across GPUs
+
+One image's **denoise loop** (the expensive part) runs collectively across GPUs — not "one image per
+GPU". It's done with xfuser in an isolated worker group (one process per GPU via `torchrun`, over
+local IPC) behind the `XFuserBatchedSampler` seam. Single-GPU/CPU runs take the in-process path and
+pay no overhead. Split method is chosen from the detected interconnect: **PipeFusion** (default, PCIe)
+or **Ulysses** (NVLink). The policy and IPC round-trip are in place and tested with a stub worker; the
+real xfuser denoise lands with the GPU-side runner (C2). Keep `sampling/batch.py` torch-free — the
+real codec that moves tensors lives with the model runner.
+
+## Code standards (non-negotiable)
+
+- **Typed, strict.** `pyright` in strict mode (`[tool.pyright]`, `typeCheckingMode = "strict"`), all of
+  `src` + `tests`. No silent `Any` leaks across component/graph boundaries.
+- **Lint.** `ruff` with `select = ["E", "F", "I", "UP", "B"]`, line length 100, target `py311`.
+- **Typed graph, validated before run.** Never execute an unvalidated graph. Edge type-checking
+  (`graph/validate.py` + `port_satisfies`) rejects bad wiring at submit. New port kinds go in
+  `schema.py`.
+- **Device policy owns placement.** Components and runners **never** self-assign a device/dtype/
+  offload — they call `ctx.policy.placement(role)` (`text_encoder`, `denoiser`, `vae`, …). This is the
+  rule that keeps one graph portable across GPU / low-VRAM / CPU / multi-GPU. The policy **prefers the
+  GPU**: a low-VRAM GPU keeps weights resident (tiling/slicing/int8 do the saving) and does not
+  auto-offload to CPU (`placement.offload` defaults False; opt in with `INLINE_ALLOW_CPU_OFFLOAD`).
+- **Graph never runs the denoise inline.** A model runner lowers to components and submits a
+  `SampleJob` through the batched-sampler seam. The executor orchestrates; it does not sample.
+- **Immutable takes.** The `TakeStore` owns bytes/hash/uri; regenerating adds a take. Never overwrite.
+- **Engine deps are optional and import-guarded.** Heavy deps (torch, diffusers, xfuser) live in
+  `[project.optional-dependencies]` extras (`zimage`, `server`, `parallel`, `dev`). Model-runner
+  subpackages import torch/diffusers at module top **on purpose**: an absent extra makes the import
+  raise, and `server/bootstrap.py` skips that model best-effort so a core install still boots and
+  serves source nodes. Never import a heavy dep at package top level outside a runner subpackage.
+- **Engine isolation.** All ComfyUI-format knowledge lives in `importer/comfy.py`; all xDiT/worker
+  knowledge behind `parallel/` and the sampler seam. Don't scatter it.
+- **Bring-your-own models.** Nothing is downloaded by the engine. The catalog scans; the user places
+  files. A model picker is a `SELECT` param with `options_from="<category>"`.
+- **Tests (pytest).** Cover the logic that matters: graph validate/topo/executor/cache, the catalog
+  scan, the run store + server contract, the device/memory policy, the parallel group + xfuser seam,
+  the comfy importer, and each model runner (import-guarded, no GPU needed). See `tests/`.
+- **Commits.** Conventional Commits (`feat:`, `fix:`, `chore:`), small and scoped.
+
+## Commands
+
+```
+uv venv                                   # create ./.venv
+uv pip install -e ".[dev]"                # engine + server + test tooling
+uv pip install -e ".[zimage]"             # + torch, diffusers, transformers (real generation)
+uv pip install -e ".[parallel]"           # + xfuser, for multi-GPU denoise (2+ GPUs)
+
+./webui.sh                                # run (loopback:8848); friendly flags → INLINE_* env
+./webui.sh --listen --port 9000           # bind all interfaces
+./webui.sh --lowvram                      # tight-VRAM profile
+./webui.sh --install --extra zimage       # set up ./.venv with the Z-Image runtime, then exit
+python -m inline_core.server              # run the server directly (INLINE_HOST / INLINE_PORT)
+
+ruff check .                              # lint (zero warnings)
+uv run pytest -q                          # tests (no GPU; model code is import-guarded)
+```
+
+## Where to add things
+
+- **New model runner** → a subpackage `models/<name>/` with `runner.py` (a `NodeDescriptor` + a
+  `NodeRunner` + `register_<name>(registry, store, policy)`) and an `__init__.py` re-exporting it;
+  add a `try/except ImportError` block in `server/bootstrap.py`; add an optional-deps extra in
+  `pyproject.toml`. Copy `models/zimage/` — it's the reference.
+- **New low-level primitive** → descriptor in `graph/primitives.py`; its runner lands with the C2 work
+  (build a component in `components/`, wire it through `encode`/`sample`/`vae` and the sampler seam).
+- **New `/v1` route** → add it in `server/app.py`, shape the JSON in `server/serialize.py`, keep errors
+  as `{error:{code,message}}` with the right status. Update the API list in `README.md`.
+- **New port/handle type** → `PortKind` in `graph/schema.py` (+ `port_satisfies` if it has coercions).
+- **New device/memory behaviour** → behind `DevicePolicy` in `device/`; never in a component.
+- **New ComfyUI import behaviour** → `importer/comfy.py` only.

inline_core-1.1.1/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: inline-core
+Version: 1.1.1
+Summary: The generation engine behind Inline.
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: psutil>=5.9
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: imageio-ffmpeg>=0.4; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'dev'
+Provides-Extra: parallel
+Requires-Dist: accelerate>=0.30; extra == 'parallel'
+Requires-Dist: diffusers>=0.36; extra == 'parallel'
+Requires-Dist: huggingface-hub>=0.23; extra == 'parallel'
+Requires-Dist: nvidia-ml-py>=12; extra == 'parallel'
+Requires-Dist: safetensors>=0.4; extra == 'parallel'
+Requires-Dist: torch>=2.2; extra == 'parallel'
+Requires-Dist: transformers>=4.44; extra == 'parallel'
+Requires-Dist: xfuser>=0.4; extra == 'parallel'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == 'server'
+Requires-Dist: imageio-ffmpeg>=0.4; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'server'
+Provides-Extra: zimage
+Requires-Dist: accelerate>=0.30; extra == 'zimage'
+Requires-Dist: diffusers>=0.36; extra == 'zimage'
+Requires-Dist: huggingface-hub>=0.23; extra == 'zimage'
+Requires-Dist: safetensors>=0.4; extra == 'zimage'
+Requires-Dist: torch>=2.2; extra == 'zimage'
+Requires-Dist: transformers>=4.44; extra == 'zimage'

inline_core-1.1.1/README.md

@@ -0,0 +1,177 @@
+# Inline Core
+
+The generation engine behind Inline. It takes a typed node graph (JSON) and returns immutable renders
+("takes"), running image and video models on macOS, Windows, and Linux, from CPU-only boxes and
+low-VRAM laptops up to multi-GPU machines that split a single image's sampling across GPUs (via
+xDiT). It is the render backend that replaces ComfyUI for Inline.
+
+First model: Z-Image (Alibaba Tongyi), a 6B rectified-flow diffusion transformer (and a model xDiT
+already supports, so the multi-GPU split works on it from the start).
+
+> Status: early, and running end to end against a stub engine. In place and tested: the graph engine,
+> the typed `/v1` HTTP + websocket API (durable runs, streamed progress, coalescing), the model-dir
+> scan, the device + memory policy (profiles, dtype, offload, int8), the low-level primitive node
+> vocabulary, and a ComfyUI workflow importer. The Z-Image loader is written and validates on a GPU.
+> Cross-request batching, single-image multi-GPU (an xDiT worker group behind the sampler seam, with
+> the policy and IPC round-trip tested), and out-of-process custom nodes are built as seams but not
+> yet running on real hardware.
+
+## How it differs from ComfyUI's architecture
+
+ComfyUI is a great canvas but a fragile engine. Inline Core keeps the open node-graph model and
+rebuilds the engine underneath it.
+
+|              | ComfyUI                                                                     | Inline Core                                                                                                                                      |
+| ------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Graph vs GPU | runs the denoise loop inline, one request at a time                         | graph orchestration (cheap, per request) is separate from a batched sampler that groups compatible jobs across requests                          |
+| Schema       | positional `widgets_values`, validated at runtime (dies mid-graph)          | typed graph, named params, edges type-checked before the run (rejected at submit)                                                                |
+| Devices      | some nodes pin to CPU on a GPU box; Z-Image will not run on CPU             | one device/memory policy owns dtype, placement, offload, and attention; no node hardcodes a device, so one graph runs GPU, low-VRAM, or pure CPU |
+| Multi-GPU    | one image runs on one GPU; splitting a single image needs third-party nodes | one image's denoise can split across GPUs via xDiT (PipeFusion on PCIe, Ulysses on NVLink), in an isolated worker group behind the sampler seam  |
+| Custom nodes | all load into one interpreter and env, so any node can break the core       | run out of process, each pack in its own venv, behind a semver SDK                                                                               |
+| Interface    | a web UI driven by graph JSON over a socket; run state is ephemeral         | a headless `/v1` HTTP + websocket API; runs are durable and survive a restart                                                                    |
+| Outputs      | files you overwrite                                                         | immutable takes; regenerating adds a take, never overwrites                                                                                      |
+| Models       | `models/` dir, dropdowns from a scan                                        | same layout (bring your own, no downloads); a typed catalog feeds versioned node descriptors the UI renders generically                          |
+
+The two boundaries that matter most: graph orchestration is decoupled from GPU batching (graphs are
+the unit of caching, the sampler is the unit of batching, and the multi-GPU split routes through that
+same seam), and the device policy is the single owner of placement, so the same graph runs on a 4090,
+a 6 GB laptop, pure CPU, or split across several GPUs, without touching the graph.
+
+## Install
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```
+uv venv
+uv pip install -e ".[server]"     # engine + HTTP/websocket API
+uv pip install -e ".[zimage]"     # + torch, diffusers, transformers (for real generation)
+uv pip install -e ".[parallel]"   # + xfuser, for splitting one image across GPUs (needs 2+ GPUs)
+```
+
+## Models
+
+Drop files into the models dir (default `./models`, override with `INLINE_MODELS_DIR`), ComfyUI-style,
+by category:
+
+```
+models/
+  diffusion_models/   z_image_turbo_bf16.safetensors   <- the one file you need for Z-Image
+  vae/                ae.safetensors                   <- optional (see below)
+  text_encoders/      qwen/   (an HF-format folder: config + tokenizer + weights)  <- optional
+  loras/  controlnet/  checkpoints/  ...
+```
+
+**Z-Image loads from a single diffusion `.safetensors`.** Drop that one ComfyUI-style file in
+`diffusion_models/`; the runner loads the transformer via diffusers `from_single_file`. It also needs
+a VAE + text-encoder + tokenizer, resolved from **local files** — `vae/*.safetensors` or a dir, and an
+HF-format `text_encoders/` dir.
+
+**Nothing is ever downloaded as a side effect of a render.** Every load runs `local_files_only=True`,
+so a missing model is a clear, fast error, not a silent multi-GB fetch. Models arrive by exactly two
+paths:
+
+1. **You place files** under `models/` (bring-your-own / fully offline); or
+2. **You download them explicitly** from the Z-Image node's model popup in the UI — it lists the
+   diffusion model, VAE, and text-encoder, shows which are missing, and downloads them **into
+   `models/`** (never the hidden HF cache) with visible progress.
+
+Override the diffusion source with `INLINE_ZIMAGE_MODEL` (a file or a diffusers dir), and the supporting
+components with `INLINE_ZIMAGE_VAE` / `INLINE_ZIMAGE_TEXT_ENCODER`. The engine scans the models dir on
+start; a node's model pickers list what is present.
+
+## Nodes
+
+`/v1/models` serves each node's descriptor (ports, params, file pickers), so the Inline Studio canvas
+renders any node generically — adding a node type needs no UI release.
+
+**High-level model nodes are what the user sees.** Generation is one-click: you drop a single
+**Z-Image Turbo** node, wire a Prompt into it, and hit Run. The node hooks up the diffusion model, VAE,
+and text-encoder behind the scenes — no loader/sampler wiring.
+
+Underneath, a **low-level primitive vocabulary** exists (`load/diffusion-model`, `load/vae`,
+`load/text-encoder`, `encode/text`, `latent/empty`, `sample`, `vae/decode`, `vae/encode`) — the
+ComfyUI-equivalent decomposed graph, kept for validation/execution — but these are marked **`hidden`**
+and never appear in the add-node menu. Engine handles (`model`, `vae`, `text-encoder`, `conditioning`,
+`latent`) are typed sockets between nodes; only media outputs become Frames with take history. A
+best-effort ComfyUI importer maps existing workflows onto the primitives.
+
+## Multi-GPU: split one image across GPUs
+
+Cut a single image's latency by running its denoise across several GPUs. The denoise loop (the
+iterative sampling step) is the expensive part of a render; with two or more GPUs, Inline Core runs
+each step's transformer forward collectively across them so one image finishes faster. This is not
+"one image per GPU" (independent renders); it is one image whose sampling is shared by all the GPUs.
+
+It is done with xDiT (`xfuser`), which parallelizes diffusion-transformer inference. xfuser runs in
+an isolated worker group the engine spawns (one process per GPU via `torchrun`) and talks to over
+local IPC, so the HTTP server, database, and graph stay single-process and only the denoise is
+distributed. It sits behind the sampler seam (`XFuserBatchedSampler`), so a single-GPU or CPU run
+takes the in-process path and pays no overhead.
+
+Two split methods, chosen from the interconnect the engine detects:
+
+- **PipeFusion (default, PCIe):** shards the transformer into a displaced patch pipeline with low,
+  depth-independent communication. It needs no NVLink and works over plain PCIe (or Ethernet across
+  nodes), so it is the default on a typical multi-GPU box.
+- **Ulysses (NVLink):** sequence-parallel attention, used when NVLink is present because it wants
+  the higher interconnect bandwidth.
+
+Enabling it:
+
+1. **Install the extra** and have 2+ CUDA GPUs on one machine:
+   ```
+   uv pip install -e ".[parallel]"   # pulls in xfuser and nvidia-ml-py; torchrun ships with torch
+   ```
+2. **Run normally.** On the first denoise, the device policy enumerates the GPUs, detects NVLink vs
+   PCIe (via `nvidia-ml-py`), and returns a parallel placement when there is more than one GPU. The
+   engine then spawns the xfuser worker group (lazily, once, then reuses it) and splits the sampling
+   across the GPUs. No graph, API, or per-request change is needed.
+3. **Override the split** if you want to pick it by hand, with `INLINE_PARALLEL`:
+   ```
+   INLINE_PARALLEL=pipefusion=2              # 2 GPUs, PipeFusion
+   INLINE_PARALLEL=pipefusion=2,ulysses=2    # 4 GPUs, PipeFusion x Ulysses
+   ```
+   The degrees multiply to the world size, which must equal the number of GPUs.
+
+The device policy and the worker-group IPC are in place and tested with a stub worker; the real
+xfuser denoise lands with the GPU-side Z-Image runner.
+
+## Run
+
+The easy path is `webui.sh`, which maps friendly flags onto the engine's `INLINE_*` env knobs:
+
+```
+./webui.sh                            # loopback, port 8848
+./webui.sh --listen --port 9000       # bind all interfaces on 9000
+./webui.sh --multi-gpu                # split one image across GPUs (auto with 2+ GPUs)
+./webui.sh --lowvram                  # tight-VRAM profile
+./webui.sh --install --extra zimage   # set up ./.venv with the Z-Image runtime, then exit
+```
+
+`./webui.sh --help` lists every flag (networking, multi-GPU, device/memory profile, paths). The same
+flags are available on the Python entrypoint — `python main.py --help` — which is the dev path (it also
+takes `--front-end-root DIR` to serve a local SPA build). Or run the server module directly:
+
+```
+python main.py --listen --port 9000   # same flags as webui.sh; --front-end-root for a local UI build
+python -m inline_core.server          # bare server (INLINE_HOST / INLINE_PORT from the env)
+```
+
+Working data (the run database and takes) lives in `INLINE_DATA_DIR` (default `./.inline`).
+
+## API (v1)
+
+- `POST /v1/runs {graph, target}` returns `{runId}` (validated up front; 422 on a bad graph)
+- `GET /v1/runs/{id}` returns run state (durable; survives a restart)
+- `GET /v1/runs/{id}/events` (websocket): a snapshot, then `progress` / `node_done` / `run_done`
+- `DELETE /v1/runs/{id}` cancels
+- `GET /v1/models` returns node descriptors + `registryVersion` (ETag-aware)
+- `GET /v1/takes/{id}` and `/v1/takes/{id}/bytes`
+- `POST /v1/assets` (content-addressed upload) and `GET /v1/health`
+
+## Development
+
+```
+ruff check .        # lint
+uv run pytest -q    # tests (no GPU needed; model code is import-guarded)
+```

inline_core-1.1.1/main.py

@@ -0,0 +1,93 @@
+"""Inline Studio — single entrypoint.
+
+Run one Python process that serves both the API and the UI on one port:
+
+    python main.py                                  # end users: frontend from the installed package
+    python main.py --front-end-root ../Inline-Studio/dist-web   # dev: serve a local SPA build
+    python main.py --listen --port 8000             # bind 0.0.0.0 on a custom port
+
+Flags map onto the engine's INLINE_* env knobs, then hand off to the server entrypoint. Build the
+dev frontend with `npm run build:spa` in the Inline Studio repo, or use `npm run dev:web` for HMR.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="inline-studio",
+        description="Run Inline Core + the Inline Studio UI on one port.",
+    )
+    # Networking
+    parser.add_argument("--host", help="Bind address (default 127.0.0.1).")
+    parser.add_argument(
+        "--listen",
+        action="store_true",
+        help="Bind 0.0.0.0 so other machines on your network can reach it.",
+    )
+    parser.add_argument("--port", type=int, help="Port to serve on (default 8848).")
+    # Paths
+    parser.add_argument(
+        "--front-end-root",
+        help="Serve a local frontend build (a dir with index.html) instead of the installed "
+        "inline_studio_frontend package. The dev loop — rebuild locally, no republish.",
+    )
+    parser.add_argument("--models-dir", help="Models root to scan (default ./models).")
+    parser.add_argument("--data-dir", help="Working data dir: runs + takes (default ./.inline).")
+    # Device / memory
+    parser.add_argument(
+        "--profile", help="Device/memory profile: gpu-max | lowvram | cpu (default: auto-detected)."
+    )
+    parser.add_argument(
+        "--lowvram", action="store_true", help="Shortcut for --profile lowvram (tight-VRAM saving)."
+    )
+    parser.add_argument(
+        "--cpu", action="store_true", help="Shortcut for --profile cpu (force CPU generation)."
+    )
+    parser.add_argument(
+        "--vram-budget", type=float, help="Treat the GPU as having this many GB of usable VRAM."
+    )
+    # Multi-GPU (xDiT): split one image's denoise across GPUs. Auto-detected with 2+ GPUs.
+    parser.add_argument(
+        "--multi-gpu",
+        "--parallel",
+        dest="parallel",
+        help="Multi-GPU split spec, e.g. pipefusion=2 or pipefusion=2,ulysses=2 (degrees multiply "
+        "to the GPU count). Auto-detected with 2+ GPUs.",
+    )
+    args = parser.parse_args()
+
+    if args.listen:
+        os.environ["INLINE_HOST"] = "0.0.0.0"
+    if args.host:
+        os.environ["INLINE_HOST"] = args.host
+    if args.port:
+        os.environ["INLINE_PORT"] = str(args.port)
+    if args.front_end_root:
+        os.environ["INLINE_FRONTEND_ROOT"] = args.front_end_root
+    if args.models_dir:
+        os.environ["INLINE_MODELS_DIR"] = args.models_dir
+    if args.data_dir:
+        os.environ["INLINE_DATA_DIR"] = args.data_dir
+    if args.lowvram:
+        os.environ["INLINE_PROFILE"] = "lowvram"
+    if args.cpu:
+        os.environ["INLINE_PROFILE"] = "cpu"
+    if args.profile:
+        os.environ["INLINE_PROFILE"] = args.profile
+    if args.vram_budget:
+        os.environ["INLINE_VRAM_BUDGET_GB"] = str(args.vram_budget)
+    if args.parallel:
+        os.environ["INLINE_PARALLEL"] = args.parallel
+
+    # Import after env is set so config picks it up.
+    from inline_core.server.__main__ import main as run_server
+
+    run_server()
+
+
+if __name__ == "__main__":
+    main()

inline_core-1.1.1/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+# PyPI distribution name. The import package is `inline_core` (src/inline_core); PyPI treats the
+# hyphen and underscore as equivalent, so `pip install inline-core` installs the `inline_core` package.
+name = "inline-core"
+version = "1.1.1"
+description = "The generation engine behind Inline."
+requires-python = ">=3.11"
+dependencies = [
+  "numpy>=1.26",
+  "psutil>=5.9",
+]
+
+[project.optional-dependencies]
+# Model-runtime deps land with the component implementations. The installer selects the right
+# torch wheel per OS and accelerator (see PLAN.md, cross-platform). Kept out of the core env so
+# the engine skeleton stays light and portable to review.
+zimage = [
+  "torch>=2.2",
+  # Z-Image landed in diffusers 0.36 (ZImagePipeline); diffusers from git main may be required.
+  "diffusers>=0.36",
+  "transformers>=4.44",
+  "accelerate>=0.30",
+  "safetensors>=0.4",
+  # Explicit model downloads (the node's model popup) go through huggingface_hub. It ships
+  # transitively with diffusers/transformers, but pin it here since we call snapshot_download
+  # directly and rely on local_dir= to land files in models/ (never the hidden HF cache).
+  "huggingface_hub>=0.23",
+]
+server = [
+  "fastapi>=0.110",
+  "uvicorn[standard]>=0.29",
+  # Bundled ffmpeg binary for the Studio timeline render (director preview/export). ffprobe is not
+  # bundled — install a system ffmpeg for duration probing, else clips fall back to a still length.
+  "imageio-ffmpeg>=0.4",
+]
+# The prebuilt web UI (inline-studio-frontend) is NOT a hard dependency here on purpose: it's
+# published separately by CI and a source/dev checkout serves the UI via `--front-end-root ../dist-web`
+# with no wheel at all. End users get it through the pip path — `requirements.txt` (repo root) pins
+# `inline-studio-frontend` alongside the engine (mirrors ComfyUI's requirements.txt), and `webui.sh`
+# installs it on demand. Core's resolve_frontend_root() then finds the installed package's static/.
+# Multi-GPU denoise: split one image across GPUs via xDiT (xfuser). Isolated in the worker group so
+# the core env is unaffected. torchrun ships with torch (from zimage); nvidia-ml-py detects NVLink so
+# the policy picks Ulysses vs PipeFusion. flash-attn (Ulysses/Ring on NVLink) is an opt-in extra.
+parallel = [
+  "inline-core[zimage]",
+  "xfuser>=0.4",
+  "nvidia-ml-py>=12",
+]
+dev = [
+  "inline-core[server]",
+  "pytest>=8",
+  "ruff>=0.6",
+  "pyright>=1.1",
+  "httpx>=0.27",
+]
+
+[project.scripts]
+# One command to run the engine + the Inline Studio UI on one port (see main.py for flags).
+inline-studio = "inline_core.server.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/inline_core"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]