diffusers-workflow 0.4.0__py3-none-any.whl

dw/realize.py

@@ -0,0 +1,250 @@
+"""Realizing a workflow: a copy of a definition with every mutable input
+pinned, so the file left beside a run's manifest reproduces that run however
+the library, the catalog or the output tree change afterwards.
+
+What "mutable" means here is precisely the set of things that can differ
+between two runs of the same file: the arguments a caller passed, the seed a
+seedless workflow drew, the text a stored prompt held at the time, and which
+run 'output:.../latest/...' picked. Everything else - 'asset:', 'constant:',
+'previous_result:', 'builtin:' and a sub-workflow's path - is a name whose
+meaning is pinned by something already recorded (the asset library, the
+manifest's dw_version, the file itself), so it is kept as written and, for a
+local sub-workflow, digested into the manifest instead.
+
+Two rules hold this module together. It never mutates its input: the caller
+hands it the definition the run is about to work from. And it never fails a
+run: a reference that will not resolve is left exactly as written, so the
+engine raises its own error at the point it would have raised anyway.
+"""
+
+import copy
+import hashlib
+import logging
+import os
+
+from .prompts import PROMPT_PREFIX, fetch_prompt
+from .runs import (
+    LATEST,
+    OUTPUT_PREFIX,
+    is_output_reference,
+    output_root as default_output_root,
+    resolve_output_reference,
+    version_selector,
+)
+from .security import SecurityError, validate_workflow_path
+from .workflow_sources import resolve_sub_workflow, SubWorkflowNotFound
+from .variables import set_variables
+
+logger = logging.getLogger("dw")
+
+BUILTIN_PREFIX = "builtin:"
+VARIABLE_PREFIX = "variable:"
+
+
+def realize_workflow(
+    definition,
+    arguments,
+    seed,
+    base_dir=None,
+    prompt_dir=None,
+    output_root=None,
+    workflow_dir=None,
+    pin_outputs=True,
+):
+    """A copy of `definition` with every mutable input pinned.
+
+    Args:
+        definition: The workflow as loaded, before Workflow.run's deep copy.
+            Never mutated.
+        arguments: The run's argument dict, folded into the variable defaults
+            exactly as `set_variables` folds them for the run itself.
+        seed: The seed the run resolved - an integer, never None, because
+            `Workflow.run` draws one when the workflow names none.
+        base_dir: The workflow file's directory, anchoring prompt discovery
+            and a sub-workflow's relative path.
+        prompt_dir: The prompt library, for `prompt:` inlining.
+        output_root: The output directory `output:` names resolve against.
+        workflow_dir: The root a sub-workflow path is confined to, as
+            `Workflow` confines it; None for an unconfined CLI run.
+        pin_outputs: Whether an 'output:.../latest/...' reference is rewritten
+            to the run it resolves to. The run leaves this True; the planner
+            (dw/plan.py) passes False so a run finishing between a validate
+            call and the queue call does not change the fingerprint of
+            identical work.
+
+    Returns:
+        (realized, annotations) - the pinned copy, and
+        {"prompts": [name, ...], "sub_workflows": {path: sha256 or None}}
+        for the manifest to carry, since the schema has nowhere to put them.
+    """
+    annotations = {"prompts": [], "sub_workflows": {}}
+    realized = copy.deepcopy(definition)
+
+    variables = realized.get("variables")
+    if isinstance(variables, dict):
+        # Exactly what the run computed: set_variables coerces each value to
+        # the type of the declared default and rejects an undeclared name
+        set_variables(arguments or {}, variables)
+
+    realized["seed"] = seed
+    # A definition can point its top-level seed at a declared variable
+    # ('"seed": "variable:seed_arg"') rather than an integer, so the run's
+    # resolved seed can also be read wherever else the workflow names that
+    # variable. Pinning the top-level field alone would leave the variable's
+    # own default whatever it was written as (typically none) - and a rerun
+    # of this realized copy with no seed argument would put that null
+    # default back over the pinned integer everywhere but the top level.
+    definition_seed = definition.get("seed")
+    if isinstance(definition_seed, str) and definition_seed.startswith(VARIABLE_PREFIX):
+        seed_variable = definition_seed.removeprefix(VARIABLE_PREFIX)
+        if isinstance(variables, dict) and seed_variable in variables:
+            variables[seed_variable] = seed
+    realized = _pin(
+        realized, annotations, base_dir, prompt_dir, output_root, pin_outputs
+    )
+    _record_sub_workflows(realized.get("steps"), annotations, base_dir, workflow_dir)
+    return realized, annotations
+
+
+def strings_with_prefix(tree, prefix):
+    """Every string in a nested dict/list tree that starts with `prefix`, in
+    first-seen order, deduplicated."""
+    found = []
+
+    def collect(value):
+        if value.startswith(prefix) and value not in found:
+            found.append(value)
+        return value
+
+    _map_strings(tree, collect)
+    return found
+
+
+def _map_strings(value, transform):
+    """Rebuild `value`, replacing every string it contains with
+    `transform(string)`. One recursive walk over dicts, lists and strings -
+    the shape `referenced_result_names` in dw/step_cache.py walks - shared by
+    `_pin` (which rewrites matching references) and `strings_with_prefix`
+    (which only collects them), so a reference is found wherever it sits: a
+    pipeline argument, a task argument, a sub-workflow's argument map, an
+    element of a list.
+    """
+    if isinstance(value, str):
+        return transform(value)
+    if isinstance(value, dict):
+        return {key: _map_strings(item, transform) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_map_strings(item, transform) for item in value]
+    return value
+
+
+def _pin(value, annotations, base_dir, prompt_dir, output_root, pin_outputs=True):
+    """Rebuild a value with prompt references inlined and, when
+    `pin_outputs`, output references pinned."""
+
+    def transform(string):
+        if string.startswith(PROMPT_PREFIX):
+            return _inline_prompt(string, annotations, prompt_dir, base_dir)
+        if pin_outputs and is_output_reference(string):
+            return _pin_output(string, output_root)
+        return string
+
+    return _map_strings(value, transform)
+
+
+def _inline_prompt(reference, annotations, prompt_dir, base_dir):
+    """The stored text, and the name recorded for the manifest.
+
+    A stored prompt's text may not itself begin with a reference prefix (an
+    engine rule `fetch_prompt` enforces), so inlining cannot introduce a
+    second resolution.
+    """
+    try:
+        text = fetch_prompt(reference, prompt_dir, base_dir)
+    except (SecurityError, OSError, ValueError) as e:
+        logger.warning(f"Realization kept {reference} as written: {e}")
+        return reference
+    name = reference.removeprefix(PROMPT_PREFIX).strip()
+    if name not in annotations["prompts"]:
+        annotations["prompts"].append(name)
+    return text
+
+
+def _pin_output(reference, output_root):
+    """'output:<identity>/latest/<file>' - or '/v4/' - rewritten to the run it
+    resolved to.
+
+    A version is stable, but deleting the newest run frees its number for
+    reuse, so the realized copy names the run id either way. An explicit run
+    id is already pinned, so it is returned untouched without touching the
+    disk - realizing must not fail on a reference the run has not reached
+    yet.
+    """
+    name = reference.removeprefix(OUTPUT_PREFIX).strip()
+    if not any(
+        part == LATEST or version_selector(part) is not None for part in name.split("/")
+    ):
+        return reference
+    root = output_root or default_output_root()
+    try:
+        resolved = resolve_output_reference(reference, root)
+        relative = os.path.relpath(resolved, root).replace(os.sep, "/")
+    except (SecurityError, OSError, ValueError) as e:
+        logger.warning(f"Realization kept {reference} as written: {e}")
+        return reference
+    return f"{OUTPUT_PREFIX}{relative}"
+
+
+def _record_sub_workflows(steps, annotations, base_dir, workflow_dir):
+    """Digest every sub-workflow a step names by local path.
+
+    The schema's 'workflow' step takes a path, not a definition, so the
+    realized file keeps the path and the manifest records what the file held.
+    A builtin is packaged with the engine and pinned by the manifest's
+    dw_version, so it is not digested.
+    """
+
+    def scan(value):
+        if isinstance(value, dict):
+            reference = value.get("workflow")
+            if isinstance(reference, dict):
+                path = reference.get("path")
+                if isinstance(path, str) and not path.startswith(BUILTIN_PREFIX):
+                    annotations["sub_workflows"][path] = _digest(
+                        path, base_dir, workflow_dir
+                    )
+            for item in value.values():
+                scan(item)
+        elif isinstance(value, list):
+            for item in value:
+                scan(item)
+
+    for step in steps or []:
+        scan(step)
+
+
+def read_sub_workflow(path, base_dir, workflow_dir):
+    """The bytes of the sub-workflow file a step's `path` names, or None
+    when it cannot be read.
+
+    Resolved the way `Workflow.create_step_action` resolves it - beside the
+    referencing file, then across the workflow search path, then through
+    `validate_workflow_path` confined to the root it came from - so a path
+    this run could not have loaded is not one realization (or the planner)
+    reads either, and a catalog name the run composed is read rather than
+    recorded as unreadable (#90).
+    """
+    try:
+        candidate, root = resolve_sub_workflow(path, base_dir or ".", workflow_dir)
+        validated = validate_workflow_path(candidate, root)
+        with open(validated, "rb") as file:
+            return file.read()
+    except (SecurityError, OSError, ValueError, SubWorkflowNotFound) as e:
+        logger.debug(f"Sub-workflow {path} could not be read: {e}")
+        return None
+
+
+def _digest(path, base_dir, workflow_dir):
+    """The SHA-256 of a sub-workflow file, or None when it cannot be read."""
+    raw = read_sub_workflow(path, base_dir, workflow_dir)
+    return hashlib.sha256(raw).hexdigest() if raw is not None else None

dw/reference_limits.py

@@ -0,0 +1,215 @@
+"""How many references of each kind a pipeline's request may carry.
+
+A pipeline that conditions on reference media - MiniMax-H3's `ref2va` is the
+one in the catalog - bounds what it accepts: so many images, so many videos,
+so many audio clips, so many in total, and for H3 an audio reference may never
+be the only one. Those bounds are enforced by the pipeline itself, which means
+they are enforced *after* the checkpoint is loaded: a caller who ran the free
+`validate_workflow`, was quoted eight minutes and acknowledged the cost found
+out minutes in, from a failed job, what a millisecond of arithmetic could have
+told them (#136).
+
+The numbers are not written here. They live on the diffusers block that
+enforces them, as its constructor's defaults, and this module reads them off
+that block - so a diffusers release that raises a limit raises it here too,
+and the engine holds no model knowledge but the name of the class that
+declares the limits (see REFERENCE_LIMIT_BLOCKS). A family diffusers has no
+such block for is simply not checked: this pass only ever refuses a request
+the pipeline itself would refuse.
+"""
+
+import importlib
+import inspect
+import logging
+
+from .for_each import MEMBER_SEPARATOR, render_path
+
+logger = logging.getLogger("dw")
+
+# The module a family's reference classes live in -> the block whose
+# __init__ defaults declare that family's limits. A pointer, not a number:
+# what a limit *is* stays diffusers', which is the only place it can stay
+# correct across a release
+REFERENCE_LIMIT_BLOCKS = {
+    "diffusers.modular_pipelines.minimax_h3": (
+        "diffusers.modular_pipelines.minimax_h3.before_encoder",
+        "MiniMaxH3Ref2VASetupStep",
+    ),
+}
+
+# Families where an audio reference may not stand alone - H3 conditions a
+# soundtrack on a picture, so audio by itself has nothing to speak over
+AUDIO_NEEDS_A_PICTURE = frozenset(REFERENCE_LIMIT_BLOCKS)
+
+REFERENCE_TYPE_KEY = "reference_type"
+
+# Values substitution resolves before this pass runs; one still spelled out
+# is another pass's complaint, not this one's
+_UNRESOLVED_PREFIXES = ("variable:", "item:", "previous_result:", "gather:")
+
+
+def _family(module_name):
+    """The REFERENCE_LIMIT_BLOCKS key a class's module belongs to, or None."""
+    for family in REFERENCE_LIMIT_BLOCKS:
+        if module_name == family or module_name.startswith(family + "."):
+            return family
+    return None
+
+
+def _limits(family):
+    """The (model name, per-kind limits, total) a family declares.
+
+    Read from the block's constructor signature rather than from an instance:
+    constructing one is cheap but not free, and a default is exactly what the
+    signature holds. The model name is the block's own, so even the family's
+    name in the message is diffusers'.
+    """
+    module_path, class_name = REFERENCE_LIMIT_BLOCKS[family]
+    try:
+        block = getattr(importlib.import_module(module_path), class_name)
+        parameters = inspect.signature(block.__init__).parameters
+    except Exception:
+        # A diffusers that renamed or dropped the block - checking nothing is
+        # the right failure here, since the pipeline still enforces its own
+        logger.debug(f"No reference limits available from {family}", exc_info=True)
+        return None, None, None
+
+    per_kind = {}
+    total = None
+    for name, parameter in parameters.items():
+        if parameter.default is inspect.Parameter.empty:
+            continue
+        if name == "max_references":
+            total = parameter.default
+        elif name.startswith("max_") and name.endswith("s"):
+            per_kind[name[len("max_") : -1]] = parameter.default
+    model_name = getattr(block, "model_name", family.rsplit(".", 1)[-1])
+    return model_name, (per_kind or None), total
+
+
+def _reference_class(value):
+    """The class a reference entry's '*_type' names, or None.
+
+    Anything that does not resolve, or that the untrusted gate refuses, is
+    left alone: realize_args reports a type it cannot load, and the type
+    reference check a refused one, with a better message than this pass
+    could give.
+    """
+    if not isinstance(value, dict):
+        return None
+    name = value.get(REFERENCE_TYPE_KEY)
+    if not isinstance(name, str) or name.startswith(_UNRESOLVED_PREFIXES):
+        return None
+    if "." not in name:
+        return None
+    # Through the run's own resolver, so an untrusted workflow's name meets
+    # the same trust gate here, at validate time, before anything imports
+    from .type_helpers import load_type_from_full_name
+
+    try:
+        return load_type_from_full_name(name, REFERENCE_TYPE_KEY)
+    except Exception:
+        return None
+
+
+def _kinds(entries):
+    """(family, [kind, ...]) for a list of reference entries, or None.
+
+    A family is the one whose limits this pass knows how to read; an entry
+    whose class carries no 'kind', or a list mixing two families, is not a
+    reference set this pass understands.
+    """
+    if not isinstance(entries, list) or not entries:
+        return None
+    found = None
+    kinds = []
+    for entry in entries:
+        reference = _reference_class(entry)
+        kind = getattr(reference, "kind", None)
+        if not isinstance(kind, str):
+            return None
+        family = _family(getattr(reference, "__module__", ""))
+        if family is None:
+            return None
+        if found is None:
+            found = family
+        elif found != family:
+            return None
+        kinds.append(kind)
+    return (found, kinds) if found else None
+
+
+def _errors_for(kinds, family):
+    """Every limit a set of reference kinds breaks, as messages."""
+    model_name, per_kind, total = _limits(family)
+    if per_kind is None and total is None:
+        return []
+
+    messages = []
+    for kind, limit in sorted((per_kind or {}).items()):
+        count = kinds.count(kind)
+        if count > limit:
+            messages.append(
+                f"{model_name} accepts at most {limit} "
+                f"{kind} reference{'s' if limit != 1 else ''}, got {count}."
+            )
+    if total is not None and len(kinds) > total:
+        messages.append(
+            f"{model_name} accepts at most {total} references in total, "
+            f"got {len(kinds)}."
+        )
+    if family in AUDIO_NEEDS_A_PICTURE and set(kinds) == {"audio"}:
+        messages.append(
+            "An audio reference has to be paired with at least one image or "
+            "video reference and cannot be used on its own."
+        )
+    return messages
+
+
+def reference_limit_errors(workflow_definition, source_indices=None):
+    """Every reference list a pipeline would refuse, as [{path, message}].
+
+    The definition handed here has already been substituted and expanded, so a
+    `for_each` member's own references are checked as they will run;
+    `source_indices` maps each expanded step back to the step the author
+    wrote, and the member is named in the message - the same convention
+    subfolder_errors uses.
+    """
+    steps = workflow_definition.get("steps")
+    if not isinstance(steps, list):
+        return []
+
+    errors = []
+    for index, step in enumerate(steps):
+        if not isinstance(step, dict):
+            continue
+        pipeline = step.get("pipeline")
+        arguments = pipeline.get("arguments") if isinstance(pipeline, dict) else None
+        if not isinstance(arguments, dict):
+            continue
+        source = (
+            source_indices[index]
+            if source_indices is not None and index < len(source_indices)
+            else index
+        )
+        name = step.get("name")
+        where = (
+            f" in member '{name}'"
+            if isinstance(name, str) and MEMBER_SEPARATOR in name
+            else ""
+        )
+        for key, value in arguments.items():
+            found = _kinds(value)
+            if found is None:
+                continue
+            family, kinds = found
+            for message in _errors_for(kinds, family):
+                errors.append(
+                    {
+                        "path": render_path(
+                            ("steps", source, "pipeline", "arguments", key)
+                        ),
+                        "message": f"{message.rstrip('.')}{where}.",
+                    }
+                )
+    return errors

dw/reference_names.py

@@ -0,0 +1,125 @@
+"""The shape of an `asset:` / `prompt:` / `output:` name, checked for free.
+
+An `output:` reference naming a file a `for_each` step wrote - the `@` in
+`shot@opening_statement` - validated clean and then failed the job at run
+time, after the queue, with a message that described a *valid* name and said
+nothing about what it had objected to (#162). Two things were wrong with
+that, and only one of them was the `@`: a name that can never resolve, in
+any workspace, is not a run-time discovery. Its shape is a property of the
+string alone.
+
+So the shape is checked here, in `validation_errors`, which is what
+`POST /api/validate`, `validate_workflow` and the pre-queue check all run -
+while *existence* stays where it was. Whether a run id is still on disk
+depends on the workspace and on what pruning has taken, and the definition's
+own references (a template's `prompt:ltx2/hummingbird_garden`) are not the
+caller's to answer for; the caller's `arguments` are separately resolved
+against the workspace by the validate route.
+"""
+
+from .assets import ASSET_PREFIX
+from .for_each import MEMBER_SEPARATOR, render_path
+from .prompts import PROMPT_PREFIX
+from .runs import OUTPUT_PREFIX
+from .security import (
+    InvalidInputError,
+    validate_asset_reference,
+    validate_output_reference,
+    validate_prompt_reference,
+)
+
+# Substitution and expansion run before this pass, so every string reaching
+# it is literal. One still spelled with a deferred prefix is nothing this
+# pass resolved, and the undeclared-variable pass owns that complaint
+_UNRESOLVED_PREFIXES = ("variable:", "item:", "previous_result:", "gather:")
+
+
+def _output_name(reference):
+    """The part of an `output:` reference the name rule applies to.
+
+    `latest` in the run-id position is expanded before the path is joined,
+    so it is checked as the ordinary segment it looks like.
+    """
+    return reference.removeprefix(OUTPUT_PREFIX).strip()
+
+
+_KINDS = (
+    (OUTPUT_PREFIX, validate_output_reference, _output_name),
+    (ASSET_PREFIX, validate_asset_reference, None),
+    (PROMPT_PREFIX, validate_prompt_reference, None),
+)
+
+
+def reference_name_errors(workflow_definition, source_indices=None):
+    """Every reference in the definition whose *name* is malformed, as
+    [{path, message}].
+
+    Walks the substituted, expanded definition. `source_indices`, when
+    given, maps each expanded step back to the step the author wrote, so an
+    error inside a `for_each` member carries a path in their file and names
+    the member.
+    """
+    steps = workflow_definition.get("steps")
+    if not isinstance(steps, list):
+        return []
+
+    errors = []
+    for index, step in enumerate(steps):
+        if not isinstance(step, dict):
+            continue
+        source = (
+            source_indices[index]
+            if source_indices is not None and index < len(source_indices)
+            else index
+        )
+        name = step.get("name")
+        where = (
+            f" in member '{name}'"
+            if isinstance(name, str) and MEMBER_SEPARATOR in name
+            else ""
+        )
+        for path, value in _strings(step, ("steps", source)):
+            problem = reference_fault(value)
+            if problem is not None:
+                errors.append(
+                    {"path": render_path(path), "message": f"{problem}{where}"}
+                )
+    return errors
+
+
+def reference_fault(value):
+    """Why this string's reference name is malformed, or None.
+
+    None for anything that is not a reference, and for one still spelled
+    with a deferred prefix behind the reference prefix - `output:` on a
+    value substitution has not reached yet is not this pass's complaint.
+    """
+    if not isinstance(value, str):
+        return None
+    for prefix, check, extract in _KINDS:
+        if not value.startswith(prefix):
+            continue
+        rest = value[len(prefix) :].strip()
+        if not rest or rest.startswith(_UNRESOLVED_PREFIXES):
+            return None
+        try:
+            check(extract(value) if extract else rest)
+        except InvalidInputError as e:
+            return str(e)
+        return None
+    return None
+
+
+def _strings(value, path):
+    """Every string inside a step, paired with the path it sits at."""
+    if isinstance(value, str):
+        yield path, value
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            yield from _strings(item, path + (index,))
+    elif isinstance(value, dict):
+        for key, item in value.items():
+            yield from _strings(item, path + (key,))
+
+
+__all__ = ["reference_fault", "reference_name_errors"]