Full README/docs/index.md rewrite from a product/UX-first structure
(what-is-this, why, then a deep-dive per node group with screenshots)
instead of an incremental changelog-style read.
All screenshots regenerated from a real, running ComfyUI instance —
not reused. This surfaced and fixed two more bugs in
scripts/take_screenshots.py, the project's own screenshot-automation
tool, which nobody had run since before the ADR-007 rename (the old
committed screenshots still showed pre-rename node names, e.g.
"Ollama Chat Completion" instead of "Chat Completion"):
- Every LiteGraph.createNode() call used the pre-rename node type
strings (OllamaChatCompletion/OllamaLoadModel/OllamaUnloadModel);
fixed to the current names.
- The canvas locator ("canvas#graph-canvas, canvas") silently
grabbed a 250x200 minimap canvas ComfyUI's frontend added since
this script was last verified, instead of the real graph — every
screenshot failed with a clipping error. Fixed to target
#graph-canvas explicitly.
Two new scenes added, addressing the actual gap: existing
screenshots showed connectivity and options, never the two things
this whole epic sequence was about — structured output (the live
dynamic output sockets appearing as output_schema is edited, via the
real js/ollama.js widget callbacks the previous commit fixed) and
llama.cpp (LlamaCppClient wired into the same generic ChatCompletion
node Ollama uses — the actual point of the adapter pattern).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0132ojafeazQ3ephcBejEWFj
Second LLMProvider (ADR-007), backed by llama-server's router mode. Only
one new ComfyUI node — LlamaCppClient, emitting the same LLM_CLIENT socket
Ollama Client does. ChatCompletion, LLMModelSelector, LLMLoadModel,
LLMUnloadModel work unmodified once wired to it — the actual proof the
provider abstraction generalizes, not just Ollama-shaped in practice.
API shape verified live against ggml-org/llama.cpp's tools/server/README.md
(research.md) rather than assumed: model identifier field is "id" (not
"name"), status is a nested {"value": "..."} object. list_models() needs
no normalization — llama.cpp's status vocabulary is exactly ModelStatus's
full set, unlike Ollama's narrower one.
38 new tests (test_llamacpp_provider.py, test_llamacpp.py), including a
dedicated US4 test proving no generic node branches on provider type —
the same call sequence succeeds against an Ollama-shaped or llama.cpp-
shaped fake provider.
README/docs updated for the new node this time, not left stale.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0132ojafeazQ3ephcBejEWFj
README.md and docs/index.md still named OllamaChatCompletion/OllamaModelSelector/
OllamaLoadModel/OllamaUnloadModel and the OLLAMA_CLIENT socket — stale after
the atomic cutover. Updated both (they're content-duplicates) and added the
old->new migration table FR-009 requires, which previously only existed as
a code comment (comfydv.ollama.MIGRATION_MAP), not surfaced to users.
Found via a dedicated docs-freshness pass, not caught by the beacon-reviewer
correctness review (which is scoped to code, not prose).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0132ojafeazQ3ephcBejEWFj
- README.md + docs/index.md: fix stale wiring instructions that referenced
model_name optional input (removed); now correctly shows wiring
OllamaLoadModel.model_name → OllamaChatCompletion.model (STRING)
- ChatCompletion description updated to mention inline response display
- Minimal chat workflow prose updated to reflect STRING model input + inline
display (no separate Text Display node needed)
- .github/workflows/docs.yml: auto-deploy docs via mike on push to main;
reads version from pyproject.toml, deploys as <version> + stable alias
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RWysE6jYn4YjNorLBQ1cXb
OllamaUnloadModel now works as a pass-through node: wire
OllamaChatCompletion.response into the optional `passthrough` input and
OllamaChatCompletion.model_name into `model` — ComfyUI's data-flow graph
then guarantees Load → Chat → Unload execution order.
OllamaChatCompletion gains an optional `model_name` forceInput so
OllamaLoadModel.model_name can wire in (creating Load → Chat ordering) and
overrides the COMBO dropdown. It also returns `model_name` as a 3rd output
so the model can flow downstream to UnloadModel without duplication.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RWysE6jYn4YjNorLBQ1cXb
Replace hand-crafted PowerPoint exports with Playwright-generated screenshots
taken from the actual running Docker test harness:
- scripts/take_screenshots.py: headless Chromium via Playwright; creates nodes
programmatically via LiteGraph/window.app, triggers updateNodeConfig() for
FormatString's dynamic socket update, then crops tightly around each node
- docs/assets/: four screenshots (fstring, jinja2, random, circuit_breaker)
replacing the old 1920×1080 PowerPoint exports (90%+ smaller, more accurate)
- Justfile: add `screenshots` recipe (starts harness if needed, waits healthy,
runs the script)
- README.md: rewrite to cover all three nodes including Circuit Breaker;
fix stale dependency list (was listing rich/colorama/termcolor which we
removed in spec 001); add ComfyUI Manager install path
- pyproject.toml + uv.lock: add playwright to [dev] dependencies
Run: just screenshots
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RWysE6jYn4YjNorLBQ1cXb
* chore: initialise BEACON framework with all bootstrap artefacts
- Problem statement, constitution, architecture doc, roadmap populated
- CHANGELOG.md created (Keep a Changelog); README expanded with
What-is-this, Install, and Quickstart sections
- pyproject.toml gains [project.urls] (repository + documentation)
- beacon doctor: 32 pass, 2 pre-commit warns, 0 failures
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: Phase 1 — add NullHandler to package root, remove hardcoded setLevel
T001: logging.getLogger("comfydv").addHandler(NullHandler()) in __init__.py
T002: remove logger.setLevel(logging.DEBUG) from format_string.py
Also fix pyproject.toml TOML structure (project.urls was inside [project] block)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* test: failing tests for logging modernisation (T010-T through T030-T)
RED phase — 5 tests fail for the correct reasons before implementation:
T010-T: format_string produces stdout (print block)
T011-T: update_widget emits INFO records on hot path
T012-T: random_choice produces stdout (colorama/rich prints)
T020-T: load_node_state uses print() on error instead of logger.error
T021-T: circuit_breaker uses print() instead of logger
T001/T002/T030-T already green: NullHandler registered, setLevel removed.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat: standardise logging across all nodes (T010-I through T044)
GREEN phase — all 11 logging tests pass:
T010-I: Remove 8-line diagnostic print block from format_string()
T011-I: Downgrade all hot-path logger.info() calls to logger.debug();
switch all logger calls to %-style formatting; remove rich import
T012-I: Replace colorama/termcolor/rich print calls in random_choice with
logger.debug(); add logger = logging.getLogger(__name__)
T020-I: Convert print() on load_node_state error to logger.error()
T021-I: Add logger to circuit_breaker; replace print() with logger.debug();
fix logic so status=False triggers the interrupt (per BDD spec)
T040: Remove colorama, rich, termcolor from pyproject.toml dependencies
T042: ruff check + format clean
T044: beacon doctor --strict passes (34/34)
Also adds ADR-001 and ADR-002 capturing the stdlib logging and NullHandler
decisions, linked from the logging-modernisation epic.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: mark all 001-standardise-logging tasks complete in tasks.md
All [x] checkboxes flipped after 11/11 tests pass and beacon doctor --strict
reports 0 failures.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: mark logging-modernisation epic success criteria complete
All success criteria verified: NullHandler added, setLevel removed, print()
calls converted, colorama/rich/termcolor removed from deps, zero stdout in
normal operation, errors surface at ERROR level, all tests pass.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: commit spec artefacts and dependency lock for 001-standardise-logging
Includes spec.md, plan.md, research.md, BDD feature files, contracts, .beacon.toml
backlink, and uv.lock after removing colorama/rich/termcolor.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: James Veitch <darthveitcher@office-mac-mini.local>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
BREAKING CHANGE: Output order changed to put primary outputs first
- formatted_string now always in output position 0 (was dynamic)
- saved_file_path now always in output position 1 (was dynamic)
- Variable pass-through outputs now in positions 2+ (were 0+)
This change ensures primary outputs are in fixed, predictable positions,
resolving ComfyUI output mapping issues when dynamic outputs are present.
Changes:
- Updated format_string() return statement to reverse output order
- Updated update_widget() to set RETURN_TYPES/RETURN_NAMES in new order
- Updated all 47 tests to expect new output positions
- Updated all docstrings and examples in format_string.py
- Added comprehensive "Output Structure" documentation to README.md
- Added same documentation to docs/index.md for consistency
- All tests passing ✅
