comfy-draftsman 0.15.0__tar.gz

comfy_draftsman-0.15.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    # 15-min ceiling: the full suite runs in <60s on every matrix cell
+    # we've measured. Capping the job also surfaces GitHub-hosted
+    # runner-acquisition failures ("not acquired even after multiple
+    # attempts") as a fast, clear failure rather than a 15-minute hang
+    # that burns CI minutes before the runner ever starts.
+    timeout-minutes: 15
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      # --frozen: fail if the committed uv.lock is stale rather than silently
+      # resolving something else than what a user installing from it would get
+      - name: Install
+        run: uv sync --frozen --group dev
+      - name: Lint
+        run: uv run ruff check .
+      - name: Typecheck
+        run: uv run mypy src
+      - name: Test
+        run: uv run pytest
+
+  # The package ships non-Python data (knowledge/families/*.yaml). Nothing in the
+  # test suite proves those land in the wheel - a build that quietly dropped them
+  # would still pass every test, then fail on a user's first get_model_guidance.
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+      - name: Build wheel
+        run: uv build
+      - name: Knowledge data is importable from the built wheel
+        shell: bash
+        run: |
+          wheel=$(ls dist/*.whl)
+          uv run --isolated --no-project --with "$wheel" python -c "
+          import comfy_draftsman, comfy_draftsman.knowledge as k
+          families = k.list_families()
+          print(comfy_draftsman.__version__, families)
+          assert 'flux' in families and 'sdxl' in families, families
+          assert k.get_guidance('flux')['sampling'], 'guidance YAML did not ship'
+          "

comfy_draftsman-0.15.0/.github/workflows/release.yml

@@ -0,0 +1,140 @@
+name: Release
+
+# Publishes to PyPI via Trusted Publishing (OIDC) - no API token is ever stored
+# in this repo. The `pypi` / `testpypi` GitHub environments and the matching
+# pending publishers on (test.)pypi.org are configured once, by hand; see
+# README.md -> "Publishing a release".
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish"
+        required: true
+        default: testpypi
+        type: choice
+        options: [testpypi, pypi]
+
+# Least privilege by default: only the two jobs that genuinely need a token
+# widen this, and each widens it to exactly one scope. Without a top-level
+# block, jobs inherit whatever the repository's default is - which on an older
+# repo is still read/write on every scope, handed to third-party actions.
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+
+      # A tag that disagrees with comfy_draftsman.__version__ publishes a
+      # surprise version - and PyPI never lets a version number be reused, so
+      # the mistake is permanent. Fail before the build instead.
+      - name: Tag matches __version__
+        if: startsWith(github.ref, 'refs/tags/v')
+        shell: bash
+        run: |
+          version=$(grep -oP '(?<=^__version__ = ")[^"]+' src/comfy_draftsman/__init__.py)
+          tag="${GITHUB_REF_NAME#v}"
+          echo "tag=$tag package=$version"
+          test "$tag" = "$version" || {
+            echo "::error::tag v$tag does not match __version__ $version"
+            exit 1
+          }
+
+      - name: Build
+        run: uv build
+
+      # Same assertion as CI's `package` job: the wheel ships non-Python data
+      # (knowledge/families/*.yaml) that no unit test can prove landed in it.
+      - name: Knowledge data is importable from the built wheel
+        shell: bash
+        run: |
+          wheel=$(ls dist/*.whl)
+          uv run --isolated --no-project --with "$wheel" python -c "
+          import comfy_draftsman, comfy_draftsman.knowledge as k
+          families = k.list_families()
+          print(comfy_draftsman.__version__, families)
+          assert 'flux' in families and 'sdxl' in families, families
+          assert k.get_guidance('flux')['sampling'], 'guidance YAML did not ship'
+          "
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    # A tag push always goes to the real index; workflow_dispatch picks.
+    environment: ${{ github.event_name == 'workflow_dispatch' && inputs.target || 'pypi' }}
+    permissions:
+      id-token: write # Trusted Publishing supplies the credential via OIDC
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      # Two steps rather than a computed `repository-url`: the action defaults
+      # to the real index, and an empty string is not the same as "unset".
+      - name: Publish to TestPyPI
+        if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # no API token is passed at all - the credential comes from OIDC
+          repository-url: https://test.pypi.org/legacy/
+      - name: Publish to PyPI
+        if: github.event_name != 'workflow_dispatch' || inputs.target == 'pypi'
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  # A tag is not a Release: GitHub creates one only when asked. Without this job
+  # "Watch -> Releases" notifies nobody, which is the whole mechanism users have
+  # for learning that a new version exists.
+  github-release:
+    needs: publish
+    # BOTH conditions: "Use workflow from" lets a workflow_dispatch run start
+    # from a tag ref, so a TestPyPI dry run would otherwise cut a real GitHub
+    # Release - notifying every watcher about a version that only reached
+    # TestPyPI, and leaving the later real tag push to fail on "release already
+    # exists" after PyPI publishing had irreversibly succeeded.
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Release notes from CHANGELOG
+        shell: bash
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          # the '## <version> - title' block, up to the next '## ' heading
+          awk -v v="$version" '
+            $0 ~ "^## " v "([^0-9.]|$)" { inside = 1; next }
+            inside && /^## / { exit }
+            inside { print }
+          ' CHANGELOG.md > notes.md
+          if [ ! -s notes.md ]; then
+            echo "No CHANGELOG entry for $version." > notes.md
+          fi
+          cat notes.md
+      - name: Create the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/* \
+            --title "$GITHUB_REF_NAME" \
+            --notes-file notes.md \
+            --verify-tag

comfy_draftsman-0.15.0/.gitignore

@@ -0,0 +1,38 @@
+# Test ComfyUI environment (cloned/installed locally, never committed)
+.comfyui-test/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# Session workspaces created at runtime
+.draftsman-sessions/
+
+# Local agent worklogs / evidence (never committed or published)
+.omo/
+.claude/
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# Internal work plans / agent worklogs (keep local; public TODOs live in docs/ARCHITECTURE.md)
+docs/superpowers/
+docs/plans/
+
+# Secrets (API keys, credentials)
+.env*

comfy_draftsman-0.15.0/AGENTS.md

@@ -0,0 +1,99 @@
+# AGENTS.md — comfy-draftsman
+
+A local-first MCP server that drafts, organizes, validates, and runs ComfyUI workflows. Delivers clean, labeled, annotated UI-format graphs that humans can read — computed layout, colored stage groups, titled nodes, green-highlighted knobs, and generated guidance notes. Python ≥3.11, hatchling build, httpx + websockets + mcp stack.
+
+**Deep reference: `docs/ARCHITECTURE.md` (read it before engine/graph/validation changes)**
+
+## Current state
+
+_Last verified: 2026-08-22_
+
+- **Status:** in development, at v0.15.0 (`src/comfy_draftsman/__init__.py` is the single source of truth for the version). CI green. **PyPI release pipeline is wired** (`.github/workflows/release.yml`, Trusted Publishing) but the first tag has not been pushed — see README → "Publishing a release" for the one-time manual setup.
+- **Works:** the full draft → organize → validate → run → save loop against a live ComfyUI instance; schema 0.4 and 1.0 graphs including subgraph flatten/rebuild; V3 dynamic combos, autogrow inputs and match types round-tripping through the API's dotted-key form; `organize_workflow`'s labeled stage groups, knob cards and guidance notes; workflow import straight from ComfyUI's browser (`list_workflows` + `import_workflow(name=…)`); the per-family knowledge floor plus a persistent learned overlay written by `record_learning`.
+- **In progress:** nothing half-built — each round lands complete. The most recent round (0.15.0) added a VRAM fit verdict, a partner-node spend gate, and the PyPI pipeline; `CHANGELOG.md` records what each round changed and, importantly, what was deliberately *not* changed.
+- **Known gaps / next steps:** the first PyPI tag is unpushed (one-time PyPI/TestPyPI account setup pending — README → “Publishing a release”); `api_node` detection and a real elicitation round-trip are unverified against a live instance; six families carry no VRAM data and correctly stay silent; `COMFY_DYNAMICSLOT_V3` is classified but never exercised (no live instance declares one — do not implement it speculatively); widget-backed custom-JS inputs stay a deliberate loud stop rather than a silently-wrong emit. All written up in full under `docs/ARCHITECTURE.md` → "Remaining TODOs".
+- **Deep docs:** `docs/ARCHITECTURE.md` (module map, data flow, subgraph mechanics, hard-won gotchas, open TODOs), `docs/PERMISSIONS.md` (which tools are read-only), `CHANGELOG.md`.
+
+## Architecture in 60 seconds
+
+- **Thin MCP wiring layer.** `server.py` exposes tools/prompts; all logic lives in tested modules underneath. Ground truth is the live ComfyUI instance's `/object_info`.
+- **Graph model with schema 0.4/1.0 support.** `graph/` handles workflow ↔ internal model conversion, widget mapping, subgraph flattening, live-instance validation, and layout.
+- **ComfyUI client layer.** `comfy/` provides the httpx REST client, object_info catalog, websocket progress tracker, and Comfy Registry lookups for missing node packs.
+- **Two-layer knowledge system.** Per-family tuning floor (YAML) + persistent learned overlay. `record_learning` saves researched settings so future sessions start smarter. The floor also carries optional, sourced VRAM requirements behind `knowledge.fit_verdict`.
+- **Gates that teach reactively.** The VRAM fit verdict and the partner-node spend gate both fire before anything irreversible, so each explains itself in its own response instead of in a docstring everyone pays for.
+- **V3 dynamic combos first-class.** `COMFY_DYNAMICCOMBO_V3`, `COMFY_AUTOGROW_V3`, match types, and socketless widgets are handled natively — values round-trip through the API's dotted-key form.
+- **Token discipline.** Every tool returns bounded lists; findings are severity-capped; summaries clip long strings. Full object_info is never returned to the model. The tool surface — the one budget paid on *every* request — is stripped of pydantic's auto-generated schema titles *and* of docstring indentation at import (`_trim_published_surface`), and held under a ceiling by `tests/test_round18_tokens.py`. Keep that ceiling interpreter-independent: only Python 3.13+ strips docstring indentation at compile time.
+
+## Layout
+
+| Directory | Purpose |
+|-----------|---------|
+| `src/comfy_draftsman/server.py` | MCP tools/prompts — thin wiring only, no logic |
+| `src/comfy_draftsman/graph/` | Workflow model, widgets, subgraph flattening, validate, lint, annotate, layout, knobs, port, spend |
+| `src/comfy_draftsman/comfy/` | httpx client, object_info catalog, websocket progress, Comfy Registry |
+| `src/comfy_draftsman/knowledge/` | Per-family tuning floor (YAML) + learned overlay |
+| `src/comfy_draftsman/config.py` | Env-driven config (COMFYUI_URL, DRAFTSMAN_SESSION_DIR, ...) |
+| `src/comfy_draftsman/session.py` | workflow_id → Workflow store, persisted under session dir |
+| `tests/` | pytest + pytest-asyncio; integration tests require running ComfyUI |
+| `docs/` | Architecture (deep reference), images, showcase |
+
+## Build / test / run
+
+```bash
+# Install (editable)
+uv sync
+
+# Run the MCP server
+comfy-draftsman
+# or: uv run comfy-draftsman
+
+# Test (excludes integration tests by default)
+uv run pytest
+
+# Test with integration tests (requires COMFYUI_TEST_URL)
+uv run pytest -m integration
+
+# Lint
+uv run ruff check src tests
+
+# Typecheck
+uv run mypy
+
+# Wheel data check (CI's `package` job) - --refresh, or uv serves a cached
+# extract of the previous build with the same version number
+uv build && uv run --isolated --no-project --refresh --with "$(ls dist/*.whl)" python -c "
+import comfy_draftsman.knowledge as k; assert k.get_guidance('flux')['sampling']"
+```
+
+## Conventions & gotchas
+
+- Dynamic nodes serialize only in-use widgets — never pad widgets_values with `None`.
+- Frontend runs `.replace()` over every string widget at queue time — `null` crashes the editor.
+- Seed control widgets are a name heuristic (INT literally named `seed`/`noise_seed`).
+- Never default paths off `Path.cwd()` — MCP hosts launch from arbitrary directories. Session state lives under `~/.comfy-draftsman`.
+- `object_info` is multi-megabyte — never return it or full combo lists to the model. Everything recurring must be capped or digested.
+- Validation gates: `run_workflow` and `save_workflow` refuse on `validate()` errors unless `allow_invalid=True`.
+- `lint()` is advisory only — it never blocks.
+- `edit_workflow` ops deliberately do NOT reach inside subgraph definitions — rebuild flat to modify internals.
+- `organize_workflow` never synthesizes a download URL or an alignment (`multiple_of`) requirement — both only ever come from a curated family YAML or a `record_learning` call; a guessed one is worse than none.
+- **Never invent VRAM numbers.** `hardware.vram_gb` requires a `hardware.source` that states the figure; `tests/test_hardware_fit.py` fails the build otherwise.
+- **Unknown is not paid.** No VRAM data, or an instance too old to flag `api_node`, means *say nothing* / *don't bill* — never a default, never a nag. A warning repeated on every call is one an agent learns to skip.
+- **New behavior is taught by responses, not by docstrings.** The tool surface is re-sent on every request (`test_round18_tokens.py` caps it); a gate that fires before the irreversible act can explain itself in its own return value, paid for only by the caller who hit it.
+
+## Security
+
+This file is **public-safe by default**. Never add local paths, credentials, API keys, personal data, infrastructure details, or subscription info.
+
+Before pushing, re-read this file and `CLAUDE.md` against that rule. Maintainers run a denylist checker over both; it lives outside the repo (it is a machine-local tool, and a `pwsh` script would not run on the Linux CI runner anyway), so there is deliberately no in-repo command to invoke here.
+
+Deep architecture, data flow, subgraph mechanics, and gotchas: `docs/ARCHITECTURE.md`.
+
+## Maintenance
+
+**Update rule:** When you change the architecture, build/test commands, or conventions, update this AGENTS.md in the same commit. Keep under 200 lines. Link to `docs/ARCHITECTURE.md` for detail.
+
+**CLAUDE.md:** One-line shim: `@AGENTS.md`.
+
+**New-repo rule:** Create AGENTS.md in the first session a new repo is worked on.
+
+**No-overlap rule:** Explanatory prose lives in one file. AGENTS.md = agent-facing summary; `docs/ARCHITECTURE.md` = deep reference. Identical build/test/run commands may be restated verbatim. Explanatory prose must not be duplicated — link instead.