diffusers-workflow 0.4.0__py3-none-any.whl

dw_mcp/diagnose.py

@@ -0,0 +1,371 @@
+"""Queue a run and work out what happened.
+
+Two rules shape this module. A run costs real GPU time on an engine that
+runs one job at a time, so `run_workflow` - and `rerun_job`, which queues
+the same work - refuses until the caller has acknowledged that. And a generation takes minutes, longer than any MCP
+client will hold a tool call open, so submitting returns immediately and
+progress is polled from the event log.
+"""
+
+import os
+import time
+
+from dw_mcp.client import DwApiError, api_path, coerce_json_object
+
+TERMINAL_STATUSES = {"succeeded", "failed", "cancelled"}
+
+# How often wait_for_job re-polls /api/jobs/{id} - matches SSE_POLL_SECONDS,
+# the interval the SSE stream itself re-checks a job at (dw/server/app.py).
+WAIT_POLL_SECONDS = 1.0
+
+# A generation can run for minutes, far longer than an MCP client holds a
+# tool call open, so wait_for_job's own budget stays well under that no
+# matter what a caller asks for. Some clients hold a tool call open far
+# longer than the 55s this was tuned against (#248), so a deployment that
+# knows its own harness's tool-call budget can raise the cap with
+# DW_MCP_MAX_WAIT_SECONDS - unset, it stays 55.
+MAX_WAIT_SECONDS = float(os.environ.get("DW_MCP_MAX_WAIT_SECONDS", 55))
+
+COST_REFUSAL = (
+    "Running a workflow occupies the GPU for minutes and the engine runs one "
+    "job at a time. Call `validate_workflow` with the arguments you will run "
+    "with (free): its `plan` says what will execute - `estimate.minutes` with "
+    "its `basis`, and any weights in `downloads_required` this box has to "
+    "fetch first. Tell the user that number, get their go-ahead, then call "
+    'again with acknowledged_cost bound to the plan: {"fingerprint": '
+    'plan.fingerprint, "minutes": plan.estimate.minutes, "downloads": '
+    "[each non-null downloads_required repo]} - the server then refuses (409) if the "
+    "run's shape changed since. acknowledged_cost=true is for a `plan` that "
+    "was null."
+)
+
+
+def _acknowledgement_body(acknowledged_cost):
+    """What an acknowledgement adds to a request body: a bound one is the
+    dict itself, verbatim, so the server compares what the agent quoted; a
+    bare true is sent as true, so the job records `acknowledged: boolean`
+    rather than reading as one that never passed a gate at all (#85). A
+    dict without a fingerprint is a mistake caught here, before anything is
+    queued."""
+    if isinstance(acknowledged_cost, dict):
+        if not acknowledged_cost.get("fingerprint"):
+            raise DwApiError(
+                "A bound acknowledged_cost needs `fingerprint` - the "
+                "plan.fingerprint the validate answer carried. Validate again "
+                "and pass {fingerprint, minutes, downloads} from its plan."
+            )
+        # A from_single_file URL sits in downloads_required with repo: null;
+        # an agent copying the list verbatim should not earn a 422 for it
+        downloads = acknowledged_cost.get("downloads")
+        if isinstance(downloads, list):
+            acknowledged_cost = {
+                **acknowledged_cost,
+                "downloads": [repo for repo in downloads if repo],
+            }
+        return {"acknowledged_cost": acknowledged_cost}
+    return {"acknowledged_cost": bool(acknowledged_cost)}
+
+
+def run_workflow(
+    client,
+    workflow_path=None,
+    inline_workflow=None,
+    workflow=None,
+    name=None,
+    arguments=None,
+    acknowledged_cost=False,
+    workspace=None,
+    wait_seconds=0,
+):
+    """Queue a workflow. `workflow_path` (or `name` - the same thing
+    `validate_workflow` calls it) is either a catalog name from
+    `list_workflows` or a path to a workflow file on the server;
+    `inline_workflow` (or `workflow` - the same thing `validate_workflow`
+    calls it) is a full definition. A document just checked with
+    `validate_workflow` can be handed straight to this call under either
+    spelling. Returns as soon as it is queued - it does not wait for the job
+    to finish. Poll `get_job_events` for progress.
+
+    `wait_seconds` folds the first `wait_for_job` into this call: when it
+    is above 0 the queued job is waited on exactly as
+    `wait_for_job(job_id, timeout_seconds=wait_seconds)` would - same clamp
+    to MAX_WAIT_SECONDS, same `waited_seconds` / `timeout_*` /
+    `still_running` fields - and the answer carries the queued-job fields
+    plus that wait's slim job. Almost every run is followed by a wait, and
+    an unattended agent pays a whole tool turn for it; where the cap covers
+    the job's runtime this one call is the run and the wait. The gate is
+    untouched: queuing is refused before anything is waited on, and a
+    refused queue (409 on a stale plan) returns nothing extra.
+
+    `acknowledged_cost` is true or, better, the plan it was quoted from:
+    {fingerprint, minutes, downloads} from `validate_workflow` - see
+    COST_REFUSAL. A bound one the server checks; a 409 means the run's
+    shape changed since the quote and the message carries the new plan."""
+    if workflow_path is not None and name is not None:
+        raise DwApiError(
+            "`workflow_path` and `name` are the same thing - provide only one."
+        )
+    inline_workflow = coerce_json_object(inline_workflow, "inline_workflow")
+    workflow = coerce_json_object(workflow, "workflow")
+    if inline_workflow is not None and workflow is not None:
+        raise DwApiError(
+            "`inline_workflow` and `workflow` are the same thing - provide only one."
+        )
+    path = workflow_path if workflow_path is not None else name
+    inline = inline_workflow if inline_workflow is not None else workflow
+    if not acknowledged_cost:
+        raise DwApiError(COST_REFUSAL)
+    if (path is None) == (inline is None):
+        raise DwApiError(
+            "Provide exactly one of `workflow_path`/`name` (a catalog name "
+            "or a path to a workflow on the server) or "
+            "`inline_workflow`/`workflow` (a definition to run as-is)."
+        )
+    payload = {"arguments": arguments or {}}
+    payload.update(_acknowledgement_body(acknowledged_cost))
+    if path is not None:
+        payload["workflow_path"] = path
+    else:
+        payload["workflow"] = inline
+    # base_dir is deliberately absent: it decides where an inline workflow's
+    # relative paths resolve, and the MCP surface does not hand that out
+    # A named workspace pins this one job rather than the session: a
+    # restarted session forgets use_workspace, and a job that resolves
+    # output: references in the wrong root fails after it was queued
+    params = {"workspace": workspace} if workspace else None
+    job = client.post_json("/api/jobs", payload, params=params)
+    queued = {
+        "job_id": job.get("id"),
+        "status": job.get("status"),
+        "queue_position": job.get("queue_position"),
+        "workspace": job.get("workspace"),
+        "next": "Poll get_job_events(job_id) for progress, then get_job(job_id) "
+        "for the manifest or the error.",
+    }
+    if not wait_seconds or float(wait_seconds) <= 0 or queued["job_id"] is None:
+        return queued
+    # The same loop wait_for_job runs, not a second one: its clamp, its
+    # budget fields and its `next` are what a caller already paces against.
+    # The wait's status and next overwrite the queued ones, since the job
+    # has moved on from "queued" by the time either is read
+    waited = wait_for_job(client, queued["job_id"], timeout_seconds=wait_seconds)
+    return {**queued, **waited}
+
+
+def get_job(client, job_id):
+    """A job's status, arguments, warnings, manifest, error and traceback.
+    A running job also carries `progress` - the step, the phase and how long
+    it has been in it, with a denoise counter that is null until that loop
+    starts. Null under `generating` is the pipeline's silent lead-in, not a
+    hang; see wait_for_job. A FAILED job keeps `progress` too, frozen at the
+    moment it died - the phase it was in is the fastest way to tell what
+    killed it, faster than reading `traceback`."""
+    return client.get_json(api_path("api", "jobs", job_id))
+
+
+def get_job_workflow(client, job_id):
+    """The workflow a job ran. `realized: true` means every mutable input
+    is pinned (arguments, seed, prompts, output:latest); false means the
+    job predates run tracking and this is the definition as submitted.
+    Pass it to save_workflow to rerun it by name, or edit it and pass it
+    to run_workflow as inline_workflow."""
+    body = client.get_json(api_path("api", "jobs", job_id, "workflow"))
+    return {
+        "job_id": job_id,
+        "realized": bool(body.get("realized")),
+        "workflow": body.get("definition"),
+        # Which variable rerun_job(new_seed=True) would draw into, null when
+        # the workflow has none - see rerun_job on why that matters
+        "seed_variable": body.get("seed_variable"),
+        "next": "Pass `workflow` to save_workflow to keep it in the catalog "
+        "under a name, or edit it and pass it to run_workflow as "
+        "inline_workflow.",
+    }
+
+
+def get_job_events(client, job_id, after=-1, limit=200, kinds=None):
+    """One page of a job's progress events. `after` is exclusive - pass back
+    the previous call's `last_seq` to continue. `kinds` (e.g.
+    `["log", "warning"]`) restricts the page to events whose `event` or
+    `kind` is one of those values -
+    without it, bookkeeping events (`memory`, `step_start`, `phase`, ...)
+    dominate the payload; `kinds=["log", "warning"]` is what confirms a
+    chain's applied values (resample/mix/normalize gains) cheaply."""
+    params = {"after": after, "limit": limit}
+    if kinds:
+        params["kinds"] = list(kinds)
+    return client.get_json(
+        api_path("api", "jobs", job_id, "event-log"),
+        params=params,
+    )
+
+
+_SLIM_KEYS = (
+    "id",
+    "workflow_name",
+    "status",
+    "created_at",
+    "started_at",
+    "finished_at",
+    "workspace",
+    "run_id",
+    # The run's ordinal - the 'v5' the gallery labels its files with - so
+    # the caller can name the run it just waited on without another call
+    "run_version",
+    "queue_position",
+    "warnings",
+    "error",
+    "event_count",
+    # Where a running job has got to: the step, the phase and how long it
+    # has been in it, plus the denoise counter when one is running. A
+    # single-step generation emits nothing for minutes at a time, so this
+    # is what separates a slow job from a hung one on a poll that would
+    # otherwise come back byte-identical
+    "progress",
+)
+
+
+def slim_job(job):
+    """A job row without its arguments and traceback - what a poll needs.
+
+    The arguments of an H3 workflow are thousands of tokens of prompt text,
+    repeated on every poll of a long render; get_job serves them once. The
+    manifest is kept only once the job is terminal, when it names files.
+    """
+    slim = {key: job.get(key) for key in _SLIM_KEYS if key in job}
+    if job.get("status") in TERMINAL_STATUSES:
+        slim["manifest"] = job.get("manifest")
+    return slim
+
+
+def wait_for_job(client, job_id, timeout_seconds=20):
+    """Block until a job reaches a terminal status, or `timeout_seconds`
+    elapses - a bounded alternative to polling `get_job`/`get_job_events` by
+    hand. Does not queue anything, so it does not require
+    `acknowledged_cost`; it only reads a job someone already queued.
+
+    `timeout_seconds` is clamped to [0, MAX_WAIT_SECONDS]: a generation can
+    run for minutes, far longer than an MCP client holds a tool call open,
+    so this never blocks past a budget kept well under that - 55s by
+    default, raised for a deployment whose harness tolerates a longer tool
+    call via the `DW_MCP_MAX_WAIT_SECONDS` env var, in which case one call
+    can cover a whole short job rather than needing several polls. Every
+    reply says what was applied - `timeout_applied_seconds` is the budget
+    the call actually ran under, `timeout_requested_seconds` what was asked
+    for, and `waited_seconds` how long this call blocked - so a caller
+    asking for 600 can tell a capped return from an elapsed one rather
+    than inferring it from wall clock. Returns as soon as the job's status
+    is succeeded, failed or cancelled. If the timeout elapses first,
+    returns the job's last-seen status with `still_running: true` instead
+    of hanging - call again to keep waiting. Returns a slim job - status,
+    warnings, error, and the manifest once finished - without the
+    arguments; get_job has those.
+
+    A running job carries `progress`: the step it is on, the phase
+    (`loading`, `generating`, `decoding`, `saving`) with the model or step
+    named in `phase_detail`, `seconds_in_phase`, `seconds_since_event`, and
+    `denoise_step`/`denoise_total_steps`, which are null until the denoise
+    loop starts. `denoise_total_steps` is the schedule that actually runs,
+    which is not always the `num_inference_steps` asked for (#110). Two
+    calls with the same phase and a growing
+    `seconds_in_phase` but a moving `denoise_step` is a slow run; one where
+    `denoise_step` is a number that does not move while
+    `seconds_since_event` climbs is a stuck one.
+
+    `denoise_step: null` under `generating` is neither: it is the lead-in
+    the pipeline runs before the loop - encoding the prompt and every
+    reference - which emits nothing and is well over a minute on a large
+    video model. Its length follows what it has to encode, and a *video*
+    reference makes it much longer; the measured figures are the model
+    skill's (`minimax-h3` for H3). Silence there is expected, and `get_job_events`
+    says which block it is inside while it lasts - one `log` line per
+    top-level block of a modular pipeline. `seconds_since_event` only says
+    something once `denoise_step` is a number, or in any other phase.
+
+    Even then it is coarse: where a transformer block cache is configured
+    the denoise steps are uneven - several cheap ones, then a full one -
+    so a long gap between steps can be a healthy run. Read liveness as
+    `denoise_step` having moved between polls minutes apart rather than as
+    silence under a fixed threshold."""
+    requested = max(0.0, float(timeout_seconds))
+    applied = min(requested, float(MAX_WAIT_SECONDS))
+    capped = applied < requested
+    started = time.monotonic()
+    deadline = started + applied
+    while True:
+        job = client.get_json(api_path("api", "jobs", job_id))
+        status = job.get("status")
+        budget = {
+            "waited_seconds": round(time.monotonic() - started, 1),
+            "timeout_requested_seconds": round(requested, 1),
+            "timeout_applied_seconds": round(applied, 1),
+            "timeout_capped": capped,
+        }
+        if status in TERMINAL_STATUSES:
+            return {
+                "job_id": job_id,
+                "status": status,
+                "still_running": False,
+                **budget,
+                "job": slim_job(job),
+                "next": "get_job(job_id) for the arguments and traceback, "
+                "get_job_workflow(job_id) for the realized workflow.",
+            }
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            next_step = (
+                "Call wait_for_job again, or get_job_events for incremental progress."
+            )
+            if capped:
+                next_step = (
+                    f"You asked to wait {round(requested, 1)}s but one call "
+                    f"blocks for at most {MAX_WAIT_SECONDS}s, so this "
+                    "returned early rather than timing out. The job is still "
+                    "running: call wait_for_job again (each call covers "
+                    f"~{MAX_WAIT_SECONDS}s of it), or get_job_events for "
+                    "incremental progress."
+                )
+            return {
+                "job_id": job_id,
+                "status": status,
+                "still_running": True,
+                **budget,
+                "job": slim_job(job),
+                "next": next_step,
+            }
+        time.sleep(min(WAIT_POLL_SECONDS, remaining))
+
+
+def cancel_job(client, job_id):
+    """Ask a queued or running job to stop."""
+    return client.post_json(api_path("api", "jobs", job_id, "cancel"))
+
+
+def rerun_job(client, job_id, acknowledged_cost=False, new_seed=False):
+    """Queue a fresh job from a previous job's stored spec. This costs the
+    same GPU time as `run_workflow` and passes through the same gate - a
+    rerun is a run, and the gate would be worth nothing if a job id bought
+    a way around it.
+
+    `new_seed` draws a fresh seed into the workflow's seed variable. Without
+    it the arguments repeat exactly, and a seeded workflow's rerun is served
+    whole from the step cache - the earlier run's files, republished in a
+    fraction of a second, with `reused: true`. Ask for a new seed when the
+    point is a different image rather than the same one again.
+
+    `acknowledged_cost` takes the same bound form as `run_workflow`; a
+    fresh seed never changes a fingerprint, so the original plan still
+    binds a new-seed rerun."""
+    if not acknowledged_cost:
+        raise DwApiError(COST_REFUSAL)
+    return client.post_json(
+        api_path("api", "jobs", job_id, "rerun"),
+        {"new_seed": new_seed, **_acknowledgement_body(acknowledged_cost)},
+    )
+
+
+def move_job(client, job_id, direction):
+    """Reorder a queued job: up, down, front, or back."""
+    return client.post_json(
+        api_path("api", "jobs", job_id, "move"), {"direction": direction}
+    )

dw_mcp/exports.py

@@ -0,0 +1,84 @@
+"""Bundling a finished job so it can leave the server.
+
+The one thing this module has to keep saying: the directory it makes is on
+the machine running dw.serve, which over a `dw.serve --mcp` endpoint is the
+GPU box and not where the agent is. The zip URL is the way to it from
+anywhere else - but when the server requires a bearer token (#353), that URL
+is for the person to open, not for this agent to fetch on their behalf; see
+`export_job`'s `auth_required` / `open_url`.
+"""
+
+from dw_mcp.client import api_path
+
+
+def export_job(client, job_id, overwrite=False):
+    """Gather one finished job into a directory on the machine running
+    dw.serve: workflow.json (realized), manifest.json, job.json, README,
+    assets/, inputs/, outputs/. The export copies every output and input
+    file rather than linking them, so a video job's export costs its size
+    again on the server's disk; `total_bytes` in the result reports what
+    was copied. Returns the directory, the zip URL(s), the file list with
+    sizes and the total. The three JSON files are in the zip, not repeated
+    here. The directory is on the server machine, not this one.
+
+    `auth_required` says whether the zip needs this server's bearer token
+    to open - a token this agent has no way to attach to a browser or hand
+    to someone else's tooling. When it is true, `open_url` is for the
+    *person* to open, not for this agent to fetch: hand it to them (see
+    `next`). When it is false, `open_url` may be fetched directly. It is
+    `absolute_zip_url` when the server has one configured (`DW_PUBLIC_URL`
+    / the `public_url` setting), else the relative `zip_url`."""
+    body = client.post_json(
+        api_path("api", "jobs", job_id, "export"),
+        params={"overwrite": "true" if overwrite else "false"},
+    )
+    directory = body.get("directory")
+    zip_url = body.get("zip_url")
+    absolute_zip_url = body.get("absolute_zip_url")
+    auth_required = bool(body.get("auth_required"))
+    if auth_required:
+        open_url = absolute_zip_url or zip_url
+        next_text = (
+            "The directory is on the server, and the zip is behind this "
+            "server's bearer token - hand open_url to the person and let "
+            "them open it themselves; do not fetch it. "
+            + (
+                "It is already absolute."
+                if absolute_zip_url
+                else "It is relative - tell the person the server's own "
+                "address, since none is configured (DW_PUBLIC_URL/public_url)."
+            )
+            + " Individual results stay reachable inline via "
+            "get_output_image/get_output_audio/get_output_frames without "
+            "opening the zip at all. workflow.json, manifest.json and "
+            "job.json are inside it - they are not repeated here; "
+            "get_job_workflow and get_job serve them individually."
+        )
+    else:
+        open_url = absolute_zip_url or zip_url
+        next_text = (
+            "The directory is on the server. To give the user the files, "
+            "fetch open_url and unpack it into exports/ under the session's "
+            "working directory - it is the user's deliverable, not a "
+            "temporary file, so not a scratch or temp directory. The archive "
+            "already unpacks into one folder named after the job id; do not "
+            "create that folder first or the id is doubled in the path. "
+            "workflow.json, manifest.json and job.json are inside it - they "
+            "are not repeated here; get_job_workflow and get_job serve them "
+            "individually."
+        )
+    result = {
+        "job_id": job_id,
+        "where": f"{directory} on the machine running the MCP server",
+        "directory": directory,
+        "zip_url": zip_url,
+        "auth_required": auth_required,
+        "open_url": open_url,
+        "files": body.get("files") or [],
+        "total_bytes": body.get("total_bytes"),
+        "missing": body.get("missing") or [],
+        "next": next_text,
+    }
+    if absolute_zip_url is not None:
+        result["absolute_zip_url"] = absolute_zip_url
+    return result

dw_mcp/guides.py

@@ -0,0 +1,35 @@
+"""The prose guides, read from the engine an agent is about to drive.
+
+These proxy `GET /api/guides` like every other handler proxies its route.
+They used to read the markdown shipped in this package, on the theory that
+documentation works the same against a remote engine as a local one. It
+does not: an MCP at one version against a `dw.serve` at another confidently
+indexed sections - `Speech Generation`, `templates/` - the server did not
+have, and the guides an agent reads have to describe the engine that will
+run what it authors. The one thing given up is answering `list_guides`
+while the server is down, which is not a real use.
+
+The `GUIDES` table, section extraction and the checkout-else-packaged file
+resolution now live in `dw/server/guides.py`.
+"""
+
+from dw_mcp.client import api_path
+
+
+def list_guides(client):
+    """Every guide the engine serves, with what it covers and the sections
+    it holds. The section headings are the routing table."""
+    return client.get_json("/api/guides")
+
+
+def get_guide(client, name, section=None):
+    """One guide, or one section of it. A section name is matched loosely
+    on the server, so a heading copied approximately resolves.
+
+    Without a section the answer is the guide's index - its opening, its
+    first section, and `sections`/`withheld` naming the rest - not the
+    whole file: WORKFLOW_GUIDE.md whole is ~19.6k tokens, more in one call
+    than the entire tool surface costs to connect (#101). Name the section
+    you want."""
+    params = {"section": section} if section is not None else None
+    return client.get_json(api_path("api", "guides", name), params=params)