inline-core 1.1.1__py3-none-any.whl

inline_core/graph/descriptor.py

@@ -0,0 +1,81 @@
+"""Node descriptors: the data half of a node, served at GET /v1/models. See docs/contract.md.
+
+The behavior half (build request, run components) lives in a NodeRunner, kept out of this data.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from ..media import MediaKind
+from .schema import PortKind
+
+
+class Widget(str, Enum):
+    TEXT = "text"
+    TEXTAREA = "textarea"
+    NUMBER = "number"
+    BOOLEAN = "boolean"
+    SELECT = "select"
+    SEED = "seed"
+
+
+@dataclass(frozen=True)
+class Option:
+    value: str
+    label: str
+
+
+@dataclass(frozen=True)
+class ParamField:
+    key: str
+    label: str
+    widget: Widget
+    default: Any
+    min: float | None = None
+    max: float | None = None
+    step: float | None = None
+    options: tuple[Option, ...] = ()
+    # A dynamic catalog Core fills from what is installed (checkpoints, loras, vae, ...).
+    options_from: str | None = None
+    advanced: bool = False
+
+
+@dataclass(frozen=True)
+class Port:
+    id: str
+    label: str
+    kind: PortKind
+    required: bool = False
+
+
+@dataclass(frozen=True)
+class NodeDescriptor:
+    type: str
+    title: str
+    category: str
+    inputs: tuple[Port, ...] = ()
+    outputs: tuple[Port, ...] = ()
+    params: tuple[ParamField, ...] = ()
+    # Only generation nodes back a Frame; source/utility nodes leave this None.
+    output_kind: MediaKind | None = None
+    icon: str = ""
+    source: str = "builtin"
+    # Internal building blocks (loaders, samplers, VAE) — served for validation/execution but never
+    # offered in the UI's add-node menu. Keeps generation one-click: the user sees only high-level
+    # model nodes (e.g. Z-Image Turbo); loading a diffusion model / VAE / encoder happens behind it.
+    hidden: bool = False
+
+    def output(self, port_id: str) -> Port | None:
+        return next((p for p in self.outputs if p.id == port_id), None)
+
+    def input(self, port_id: str) -> Port | None:
+        return next((p for p in self.inputs if p.id == port_id), None)
+
+    def seed_keys(self) -> tuple[str, ...]:
+        return tuple(p.key for p in self.params if p.widget is Widget.SEED)
+
+    def defaults(self) -> dict[str, Any]:
+        return {p.key: p.default for p in self.params}

inline_core/graph/executor.py

@@ -0,0 +1,102 @@
+"""The graph executor: lazily run a target's closure, reuse cached nodes, stream run events.
+
+It orchestrates cheap work inline. A model node's runner submits the denoise to the batched sampler
+(see sampling/batch.py); the executor never runs the loop itself.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Any
+
+from ..errors import CancelledError, GraphValidationError, InlineCoreError
+from ..runtime.context import ExecutionContext
+from ..runtime.progress import CancelledEvent, ErrorEvent, NodeDoneEvent, RunDoneEvent
+from ..runtime.run import NodeRuntimeState, RunState, RunStatus, StateTrackingEmitter
+from .cache import NodeCache, is_cache_eligible, node_cache_key
+from .registry import Registry
+from .schema import Graph, Node
+from .topo import topo_sort, upstream_closure
+from .validate import validate
+
+
+class Executor:
+    def __init__(self, registry: Registry, cache: NodeCache) -> None:
+        self._registry = registry
+        self._cache = cache
+
+    def run(self, graph: Graph, target: str, ctx: ExecutionContext, state: RunState) -> None:
+        """Run the target's closure, updating `state` and forwarding events to ctx.emitter."""
+        emitter = StateTrackingEmitter(ctx.emitter, state)
+        run_ctx = replace(ctx, emitter=emitter)
+        try:
+            order = self._plan(graph, target, state)
+            state.status = RunStatus.RUNNING
+            outputs: dict[str, dict[str, Any]] = {}
+            for node_id in order:
+                if ctx.cancel.cancelled:
+                    raise CancelledError("Run cancelled.")
+                self._run_node(graph, node_id, outputs, run_ctx)
+            emitter.emit(RunDoneEvent(run_id=ctx.run_id))
+        except CancelledError:
+            emitter.emit(CancelledEvent(run_id=ctx.run_id))
+        except GraphValidationError as error:
+            emitter.emit(ErrorEvent(run_id=ctx.run_id, message=str(error), node_id=error.node_id))
+        except InlineCoreError as error:
+            emitter.emit(ErrorEvent(run_id=ctx.run_id, message=str(error)))
+
+    def _plan(self, graph: Graph, target: str, state: RunState) -> list[str]:
+        validate(graph, target, self._registry)
+        closure = list(upstream_closure(target, graph.input_sources))
+        order = topo_sort(closure, graph.input_sources)
+        for node_id in order:
+            state.nodes.setdefault(node_id, NodeRuntimeState())
+        return order
+
+    def _run_node(
+        self,
+        graph: Graph,
+        node_id: str,
+        outputs: dict[str, dict[str, Any]],
+        ctx: ExecutionContext,
+    ) -> None:
+        node = graph.node(node_id)
+        runner = self._registry.runner(node.type)
+        inputs = self._resolve_inputs(node, outputs)
+
+        key: str | None = None
+        if runner.produces_takes and is_cache_eligible(node, self._registry):
+            # TODO(phase1): pass real asset content hashes so identity is content-addressed.
+            key = node_cache_key(graph, node_id, self._registry, asset_hashes={})
+            cached = self._cache.get(key)
+            if cached is not None:
+                ctx.emitter.emit(
+                    NodeDoneEvent(run_id=ctx.run_id, node_id=node_id, cached=True, takes=cached)
+                )
+                outputs[node_id] = self._take_outputs(node, cached[0] if cached else None)
+                return
+
+        result = runner.run(node, inputs, ctx)
+        outputs[node_id] = result.outputs
+        if result.takes:
+            if key is not None:
+                self._cache.put(key, result.takes)
+            ctx.emitter.emit(
+                NodeDoneEvent(run_id=ctx.run_id, node_id=node_id, cached=False, takes=result.takes)
+            )
+
+    def _resolve_inputs(
+        self, node: Node, outputs: dict[str, dict[str, Any]]
+    ) -> dict[str, list[Any]]:
+        resolved: dict[str, list[Any]] = {}
+        for port_id, edges in node.inputs.items():
+            values: list[Any] = []
+            for edge in edges:
+                upstream = outputs.get(edge.from_node, {})
+                if edge.output in upstream:
+                    values.append(upstream[edge.output])
+            resolved[port_id] = values
+        return resolved
+
+    def _take_outputs(self, node: Node, take: Any) -> dict[str, Any]:
+        return {port.id: take for port in self._registry.get(node.type).outputs}

inline_core/graph/primitives.py

@@ -0,0 +1,137 @@
+"""The low-level primitive node vocabulary (our own clean design, not Comfy's names).
+
+Descriptors only here; the diffusers-backed runners land in C2. Registering them descriptor-first
+lets /v1/models serve the palette and the validator type-check engine-typed edges (model, vae,
+conditioning, latent) now. Only media-output nodes (vae/decode) become Frames with take history.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import TYPE_CHECKING
+
+from ..media import MediaKind
+from .descriptor import NodeDescriptor, Option, ParamField, Port, Widget
+from .schema import PortKind
+
+if TYPE_CHECKING:
+    from .registry import Registry
+
+_SAMPLERS = (Option("euler", "Euler"), Option("dpmpp_2m", "DPM++ 2M"), Option("heun", "Heun"))
+_SCHEDULERS = (Option("simple", "Simple"), Option("karras", "Karras"))
+
+LOAD_DIFFUSION_MODEL = NodeDescriptor(
+    type="load/diffusion-model",
+    title="Load Diffusion Model",
+    category="Loaders",
+    icon="box",
+    params=(ParamField("file", "Model", Widget.SELECT, "", options_from="diffusion_models"),),
+    outputs=(Port("model", "Model", PortKind.MODEL),),
+)
+
+LOAD_VAE = NodeDescriptor(
+    type="load/vae",
+    title="Load VAE",
+    category="Loaders",
+    icon="box",
+    params=(ParamField("file", "VAE", Widget.SELECT, "", options_from="vae"),),
+    outputs=(Port("vae", "VAE", PortKind.VAE),),
+)
+
+LOAD_TEXT_ENCODER = NodeDescriptor(
+    type="load/text-encoder",
+    title="Load Text Encoder",
+    category="Loaders",
+    icon="box",
+    params=(ParamField("file", "Text encoder", Widget.SELECT, "", options_from="text_encoders"),),
+    outputs=(Port("text_encoder", "Text encoder", PortKind.TEXT_ENCODER),),
+)
+
+ENCODE_TEXT = NodeDescriptor(
+    type="encode/text",
+    title="Encode Text",
+    category="Conditioning",
+    icon="type",
+    inputs=(
+        Port("text_encoder", "Text encoder", PortKind.TEXT_ENCODER, required=True),
+        Port("prompt", "Prompt", PortKind.TEXT, required=True),
+    ),
+    outputs=(Port("conditioning", "Conditioning", PortKind.CONDITIONING),),
+)
+
+EMPTY_LATENT = NodeDescriptor(
+    type="latent/empty",
+    title="Empty Latent",
+    category="Latent",
+    icon="square",
+    params=(
+        ParamField("width", "Width", Widget.NUMBER, 1024, min=64, max=4096, step=8),
+        ParamField("height", "Height", Widget.NUMBER, 1024, min=64, max=4096, step=8),
+        ParamField("batch", "Batch", Widget.NUMBER, 1, min=1, max=16, step=1),
+    ),
+    outputs=(Port("latent", "Latent", PortKind.LATENT),),
+)
+
+SAMPLE = NodeDescriptor(
+    type="sample",
+    title="Sample",
+    category="Sampling",
+    icon="wand",
+    inputs=(
+        Port("model", "Model", PortKind.MODEL, required=True),
+        Port("positive", "Positive", PortKind.CONDITIONING, required=True),
+        Port("negative", "Negative", PortKind.CONDITIONING, required=False),
+        Port("latent", "Latent", PortKind.LATENT, required=True),
+    ),
+    params=(
+        ParamField("steps", "Steps", Widget.NUMBER, 20, min=1, max=200, step=1),
+        ParamField("cfg", "CFG", Widget.NUMBER, 5.0, min=0.0, max=30.0, step=0.1),
+        ParamField("sampler", "Sampler", Widget.SELECT, "euler", options=_SAMPLERS),
+        ParamField("scheduler", "Scheduler", Widget.SELECT, "simple", options=_SCHEDULERS),
+        ParamField("seed", "Seed (-1 = random)", Widget.SEED, -1),
+    ),
+    outputs=(Port("latent", "Latent", PortKind.LATENT),),
+)
+
+VAE_DECODE = NodeDescriptor(
+    type="vae/decode",
+    title="VAE Decode",
+    category="VAE",
+    icon="image",
+    output_kind=MediaKind.IMAGE,
+    inputs=(
+        Port("vae", "VAE", PortKind.VAE, required=True),
+        Port("latent", "Latent", PortKind.LATENT, required=True),
+    ),
+    outputs=(Port("image", "Image", PortKind.IMAGE),),
+)
+
+VAE_ENCODE = NodeDescriptor(
+    type="vae/encode",
+    title="VAE Encode",
+    category="VAE",
+    icon="square",
+    inputs=(
+        Port("vae", "VAE", PortKind.VAE, required=True),
+        Port("image", "Image", PortKind.IMAGE, required=True),
+    ),
+    outputs=(Port("latent", "Latent", PortKind.LATENT),),
+)
+
+PRIMITIVES: tuple[NodeDescriptor, ...] = (
+    LOAD_DIFFUSION_MODEL,
+    LOAD_VAE,
+    LOAD_TEXT_ENCODER,
+    ENCODE_TEXT,
+    EMPTY_LATENT,
+    SAMPLE,
+    VAE_DECODE,
+    VAE_ENCODE,
+)
+
+
+def register_primitives(registry: Registry) -> None:
+    """Register the primitive descriptors, marked hidden so they never surface in the add-node menu
+    (they stay available for validation/execution). Their runners land in C2."""
+    for descriptor in PRIMITIVES:
+        registry.register(replace(descriptor, hidden=True))

inline_core/graph/registry.py

@@ -0,0 +1,61 @@
+"""The node registry: descriptors served at /v1/models plus the runner behind each type."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import replace
+
+from ..errors import UnknownNodeType
+from .descriptor import NodeDescriptor
+from .primitives import register_primitives
+from .runners import IMAGE_INPUT, TEXT_INPUT, ImageInputRunner, NodeRunner, TextInputRunner
+
+
+class Registry:
+    def __init__(self) -> None:
+        self._descriptors: dict[str, NodeDescriptor] = {}
+        self._runners: dict[str, NodeRunner] = {}
+
+    def register(self, descriptor: NodeDescriptor, runner: NodeRunner | None = None) -> None:
+        """Register a node. A descriptor with no runner is served + validated but cannot run yet."""
+        self._descriptors[descriptor.type] = descriptor
+        if runner is not None:
+            self._runners[descriptor.type] = runner
+
+    def get(self, node_type: str) -> NodeDescriptor:
+        descriptor = self._descriptors.get(node_type)
+        if descriptor is None:
+            raise UnknownNodeType(f"Unknown node type {node_type!r}.")
+        return descriptor
+
+    def has(self, node_type: str) -> bool:
+        return node_type in self._descriptors
+
+    def runner(self, node_type: str) -> NodeRunner:
+        runner = self._runners.get(node_type)
+        if runner is None:
+            raise UnknownNodeType(f"No runner registered for {node_type!r}.")
+        return runner
+
+    def descriptors(self) -> list[NodeDescriptor]:
+        return list(self._descriptors.values())
+
+    def version(self) -> str:
+        # TODO(phase1): fold resolved dynamic options into this so installing a model bumps it.
+        payload = json.dumps(sorted(self._descriptors), separators=(",", ":"))
+        return f"r_{hashlib.sha256(payload.encode()).hexdigest()[:8]}"
+
+
+def build_default_registry() -> Registry:
+    """A registry with the built-in source nodes and the low-level primitive descriptors.
+
+    Source nodes have runners; the primitives are descriptor-only until their runners land (C2).
+    Both are marked hidden: the Studio drives text/image inputs through its own Prompt/library
+    nodes, so these plumbing types stay runnable but never appear in the add-node menu.
+    """
+    registry = Registry()
+    registry.register(replace(TEXT_INPUT, hidden=True), TextInputRunner())
+    registry.register(replace(IMAGE_INPUT, hidden=True), ImageInputRunner())
+    register_primitives(registry)
+    return registry

inline_core/graph/runners.py

@@ -0,0 +1,72 @@
+"""Node runners: the behavior half of a node. Source runners are pure; model runners lower to
+components (see models/runner.py). Every runner returns its output values and any takes it produced.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+
+from ..errors import ComponentError
+from ..runtime.context import ExecutionContext
+from ..takes import AssetRef, Take
+from .descriptor import NodeDescriptor, ParamField, Port, Widget
+from .schema import Node, PortKind
+
+
+@dataclass
+class NodeResult:
+    outputs: dict[str, Any]
+    takes: list[Take] = field(default_factory=list)
+
+
+class NodeRunner(ABC):
+    produces_takes: ClassVar[bool] = False
+
+    @abstractmethod
+    def run(
+        self, node: Node, inputs: dict[str, list[Any]], ctx: ExecutionContext
+    ) -> NodeResult: ...
+
+
+class TextInputRunner(NodeRunner):
+    produces_takes = False
+
+    def run(self, node: Node, inputs: dict[str, list[Any]], ctx: ExecutionContext) -> NodeResult:
+        return NodeResult(outputs={"text": str(node.params.get("text", ""))})
+
+
+class ImageInputRunner(NodeRunner):
+    produces_takes = False
+
+    def run(self, node: Node, inputs: dict[str, list[Any]], ctx: ExecutionContext) -> NodeResult:
+        return NodeResult(outputs={"image": _asset_ref(node.params.get("asset"))})
+
+
+def _asset_ref(raw: Any) -> AssetRef:
+    if isinstance(raw, dict):
+        ref = raw.get("ref")
+        if ref == "asset":
+            return AssetRef(ref="asset", id=str(raw.get("id", "")))
+        if ref == "path":
+            return AssetRef(ref="path", path=str(raw.get("path", "")))
+    raise ComponentError("An image input node needs a valid asset reference.")
+
+
+TEXT_INPUT = NodeDescriptor(
+    type="input/text",
+    title="Prompt",
+    category="Input",
+    outputs=(Port("text", "Text", PortKind.TEXT),),
+    params=(ParamField("text", "Text", Widget.TEXTAREA, ""),),
+    icon="type",
+)
+
+IMAGE_INPUT = NodeDescriptor(
+    type="input/image",
+    title="Image",
+    category="Input",
+    outputs=(Port("image", "Image", PortKind.IMAGE),),
+    icon="image",
+)

inline_core/graph/schema.py

@@ -0,0 +1,136 @@
+"""The typed graph: PortKind, Node, Edge, Graph, and the JSON parser. Graph schemaVersion 1."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from ..errors import GraphValidationError
+
+SCHEMA_VERSION = 1
+
+
+class PortKind(str, Enum):
+    # media (cross the wire as takes / assets)
+    IMAGE = "image"
+    IMAGE_LIST = "image[]"
+    VIDEO = "video"
+    AUDIO = "audio"
+    TEXT = "text"
+    MASK = "mask"
+    # engine handles (opaque, passed between low-level nodes; never a take)
+    MODEL = "model"
+    VAE = "vae"
+    TEXT_ENCODER = "text-encoder"
+    CONDITIONING = "conditioning"
+    LATENT = "latent"
+
+
+def port_satisfies(source: PortKind, target: PortKind) -> bool:
+    """Whether an output of `source` kind may feed an input of `target` kind."""
+    if source == target:
+        return True
+    # a single image satisfies a list input (a one-element list)
+    return source is PortKind.IMAGE and target is PortKind.IMAGE_LIST
+
+
+@dataclass(frozen=True)
+class Edge:
+    from_node: str
+    output: str
+
+
+@dataclass
+class Node:
+    id: str
+    type: str
+    params: dict[str, Any] = field(default_factory=dict)
+    inputs: dict[str, list[Edge]] = field(default_factory=dict)
+
+
+@dataclass
+class Graph:
+    schema_version: int
+    nodes: list[Node]
+    _by_id: dict[str, Node] = field(default_factory=dict, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self._by_id = {n.id: n for n in self.nodes}
+
+    def node(self, node_id: str) -> Node:
+        node = self._by_id.get(node_id)
+        if node is None:
+            raise GraphValidationError(f"No node with id {node_id!r}.", node_id=node_id)
+        return node
+
+    def ids(self) -> list[str]:
+        return [n.id for n in self.nodes]
+
+    def input_sources(self, node_id: str) -> list[str]:
+        """Distinct upstream node ids feeding this node (the edges for topo sort)."""
+        seen: list[str] = []
+        for edges in self.node(node_id).inputs.values():
+            for e in edges:
+                if e.from_node not in seen:
+                    seen.append(e.from_node)
+        return seen
+
+
+def _parse_edge(raw: Any) -> Edge:
+    if not isinstance(raw, dict):
+        raise GraphValidationError("An input edge must be an object with 'from' and 'output'.")
+    frm = raw.get("from")
+    out = raw.get("output")
+    if not isinstance(frm, str) or not isinstance(out, str):
+        raise GraphValidationError("An input edge needs string 'from' and 'output'.")
+    return Edge(from_node=frm, output=out)
+
+
+def _parse_inputs(raw: Any, node_id: str) -> dict[str, list[Edge]]:
+    if raw is None:
+        return {}
+    if not isinstance(raw, dict):
+        raise GraphValidationError("Node 'inputs' must be an object.", node_id=node_id)
+    inputs: dict[str, list[Edge]] = {}
+    for port, val in raw.items():
+        inputs[str(port)] = [_parse_edge(e) for e in val] if isinstance(val, list) else [
+            _parse_edge(val)
+        ]
+    return inputs
+
+
+def _parse_node(raw: Any) -> Node:
+    if not isinstance(raw, dict):
+        raise GraphValidationError("Each node must be an object.")
+    node_id = raw.get("id")
+    node_type = raw.get("type")
+    if not isinstance(node_id, str) or not isinstance(node_type, str):
+        raise GraphValidationError("Each node needs a string 'id' and 'type'.")
+    params = raw.get("params") or {}
+    if not isinstance(params, dict):
+        raise GraphValidationError("Node 'params' must be an object.", node_id=node_id)
+    return Node(
+        id=node_id,
+        type=node_type,
+        params={str(k): v for k, v in params.items()},
+        inputs=_parse_inputs(raw.get("inputs"), node_id),
+    )
+
+
+def parse_graph(data: Any) -> Graph:
+    """Parse the contract's graph JSON into a typed Graph. Raises GraphValidationError on shape."""
+    if not isinstance(data, dict):
+        raise GraphValidationError("Graph must be an object.")
+    version = data.get("schemaVersion")
+    if version != SCHEMA_VERSION:
+        raise GraphValidationError(f"Unsupported graph schemaVersion: {version!r}.")
+    raw_nodes = data.get("nodes")
+    if not isinstance(raw_nodes, list):
+        raise GraphValidationError("Graph 'nodes' must be a list.")
+    nodes = [_parse_node(n) for n in raw_nodes]
+    ids = [n.id for n in nodes]
+    dupes = sorted({i for i in ids if ids.count(i) > 1})
+    if dupes:
+        raise GraphValidationError(f"Duplicate node ids: {dupes}.")
+    return Graph(schema_version=version, nodes=nodes)

inline_core/graph/topo.py

@@ -0,0 +1,49 @@
+"""Pure graph traversal: the upstream closure and a stable topological sort."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from ..errors import CycleError
+
+Edges = Callable[[str], list[str]]
+
+
+def upstream_closure(target: str, edges: Edges) -> set[str]:
+    """Every node reachable upstream of `target`, inclusive."""
+    seen: set[str] = set()
+    stack = [target]
+    while stack:
+        node_id = stack.pop()
+        if node_id in seen:
+            continue
+        seen.add(node_id)
+        for up in edges(node_id):
+            if up not in seen:
+                stack.append(up)
+    return seen
+
+
+def topo_sort(ids: list[str], edges: Edges) -> list[str]:
+    """Kahn sort over `ids` (dependencies first). Raises CycleError on a residual cycle."""
+    id_set = set(ids)
+    indegree = dict.fromkeys(ids, 0)
+    dependents: dict[str, list[str]] = {i: [] for i in ids}
+    for i in ids:
+        for up in edges(i):
+            if up not in id_set:
+                continue
+            indegree[i] += 1
+            dependents[up].append(i)
+    queue = [i for i in ids if indegree[i] == 0]
+    order: list[str] = []
+    while queue:
+        node_id = queue.pop(0)
+        order.append(node_id)
+        for dep in dependents[node_id]:
+            indegree[dep] -= 1
+            if indegree[dep] == 0:
+                queue.append(dep)
+    if len(order) != len(ids):
+        raise CycleError("This graph has a cycle.")
+    return order