Remove settings the user should not have to touch, and make every tooltip
plain-language:
- knowledge_base path: removed; the Knowledge Base ships in the package, so the
path is fixed rather than a prompted input.
- prompt_target: removed (reserved; to be replaced in V3).
- prompt_separator: removed; always ',' this version. Both keep their compiler
defaults, just no longer exposed as node inputs.
- analyzer_system_prompt (Configuration) and system_prompt (Scene Analyzer):
removed. A user-authored system prompt is not UX-friendly; the built-in analyzer
prompt is always used.
- Rewrite all node tooltips in plain language reflecting the current nodes.
Example workflow and node tests updated; docs/nodes.md refreshed.
BREAKING CHANGE: the Configuration node's knowledge_base, prompt_target,
prompt_separator, and analyzer_system_prompt inputs and the Scene Analyzer's
system_prompt input are removed.
Co-authored-by: kunail0804 <kunail0804@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
The Knowledge Base directory was entered in two places — the Configuration node's
knowledge_base path and the Knowledge Base Loader node's path — a duplication with
no benefit. Remove the Knowledge Base Loader node and have the Configuration node
load the Knowledge Base itself, emitting it on a new knowledge_base output wired
into the Resolver.
- New nodes/kb_loading.py holds the shared, process-wide load-once cache and
package-relative path resolution (extracted from the deleted loader node).
- Configuration node: gains a knowledge_base_reload input and a KNOWLEDGE_BASE
output; RETURN is now (config, knowledge_base, warnings, errors). A KB load
failure surfaces on errors while the config is still emitted (the Analyzer and
Validator do not need the KB).
- Remove SceneCompilerKnowledgeBaseLoader from the node registrations.
- Rebuild the example workflow to wire Configuration.knowledge_base -> Resolver.
- Docs (README, docs/nodes.md) updated; tests moved to test_kb_loading.py.
BREAKING CHANGE: the Knowledge Base Loader node is removed. Workflows that used it
must load the Knowledge Base via the Configuration node's knowledge_base output.
Co-authored-by: kunail0804 <kunail0804@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
The Scene Analyzer built its own Config from local model_name/temperature/
timeout/system_prompt widgets and ignored the Configuration node entirely, so
the analyzer model was set in two disconnected places (bug report #4).
- Scene Analyzer: add an optional `config` (COMPILER_CONFIG) input and drop the
duplicated model/temperature/timeout widgets. Settings now come from the
Configuration node; without one, defaults apply with a 300 s cold-load-friendly
timeout. A non-empty `system_prompt` widget still overrides the config.
- Knowledge Base Loader: accept an optional `config`; when wired, its KB path and
version take precedence over the node's own widgets.
- Add tooltips to every input on all six nodes.
Docs (docs/nodes.md) updated for the Analyzer/KB Loader input changes.
Co-authored-by: kunail0804 <kunail0804@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* perf: KB load-once cache, compiled index, lazy loading, parallel resolution (#38)
Closes#130, #131, #132, #133, #134.
- Loader node routes through a process-wide KnowledgeBaseLoader cache so the KB
loads once per (path, version) and is reused across run() calls.
- Normalized lookup table compiled once per KB (per NSFW gating) and reused across
resolves instead of rebuilt per resolve_scene. normalize_concept moved to
knowledge_base (re-exported from the resolver).
- Incremental per-category lazy file loading behind KnowledgeBaseLoader.
- Optional parallel per-concept resolution (thread pool), merged in exact
discovery order; deterministic and threshold-gated (default sequential).
- Performance regression guard (generous ceilings + relative ratio). Refreshed
docs/benchmarks.md (resolution 57.6us -> 17.8us).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs(changelog): note V2 performance improvements (#38)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: kunail0804 <kunail0804@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Closes#114, #115, #116, #117.
- Deterministic, offline, dependency-free char-ngram embedding backend + config
section (semantic.enabled default false, min_similarity, backend).
- Committed embedding index (data/kb_embedding_index.json) mapping vectors to real
KB entry ids only; built by scripts/build_embedding_index.py, loaded once/cached.
- Resolver falls back to the nearest entry on a deterministic miss when enabled,
accepting >= min_similarity and emitting SC0020; NSFW-gated neighbours are
skipped. Disabled => byte-identical to before.
- Guarantee tests: deterministic lookup always wins (exact hit never queries the
index), fallback emits only KB tags (no invention), identical input => identical
output. SC0020 registered.
Co-authored-by: kunail0804 <kunail0804@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Two ComfyUI issues found while testing.
1. Empty output with no error: the Knowledge Base Loader resolved a relative
`path` against ComfyUI's working directory, not this package, so the default
`knowledge_base/` loaded 0 entries (an empty KB is valid) and every concept
became unknown -> empty prompts. Relative paths now resolve against the
package root, and the loader warns when the Knowledge Base is empty.
2. Add a `raw` string output (a JSON dump of the node's data) to the Scene
Analyzer, Scene Validator, Resolver, Category Splitter, and Prompt Builder
nodes, plus a summary `raw` on the Knowledge Base Loader, for inspecting the
pipeline in the graph. Adds a shared to_raw_json helper.
Tests: package-relative path resolution (independent of cwd), empty-KB warning,
raw output content, and updated node metadata/return-arity expectations.
Co-authored-by: kunail0804 <kunail0804@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Finalize packaging and release readiness (MASTER_SPEC Phase 8, §7.8, §28).
- pyproject.toml: bump version to 1.0.0; ship the JSON Schemas as package data
and enable include-package-data.
- MANIFEST.in: include the data directories (schemas, knowledge_base, prompts,
config, examples, docs) in the source distribution.
- CHANGELOG.md: 1.0.0 release notes.
- docs/definition_of_done.md: the §7.8 Definition-of-Done checklist mapped to
evidence, with the ComfyUI visual check and the tag/release step flagged as the
remaining manual steps.
- tests/test_release_readiness.py: assert the version, changelog, DoD doc, and
that every schema / Knowledge Base / config / prompt data file is present and
declared for packaging.
Verified: `python -m build --sdist` produces comfyui_scene_compiler-1.0.0 with
all 13 Knowledge Base files, 10 schemas, the system prompt, and the default
config bundled. Tagging v1.0.0 and publishing the release are intentionally left
to a human after the ComfyUI visual check.
Co-authored-by: kunail0804 <kunail0804@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* docs: verify and complete project documentation (#31)
Align the docs with the shipped V1 implementation (MASTER_SPEC §7.6, Phase 7).
- README: fix the Category Splitter output (it emits a Category Map; the
per-category strings are produced by the Prompt Builder).
- docs/nodes.md: developer node reference with the exact inputs, outputs, and
inter-stage data types for all eight nodes.
- CONTRIBUTING.md: link the Knowledge Base contribution guide and validation
command, the golden-regeneration note, and the node/benchmark references.
- tests/test_docs_consistency.py: guards that README and docs/nodes.md mention
every registered node and cover the inter-stage types, and that CONTRIBUTING
links the Knowledge Base guide -- so docs cannot drift from the code.
The wiki ComfyUI-Nodes page is updated to match (Category Splitter emits a
Category Map) in the wiki repository.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* chore: retrigger CI (runner backlog)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: kunail0804 <kunail0804@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Add performance benchmarks for the non-Analyzer pipeline (MASTER_SPEC §26.6,
NFR-004) plus tests.
- scripts/benchmark.py: measures Knowledge Base load time, single-scene
resolution time, and full pipeline time (median over iterations) and records a
baseline to docs/benchmarks.md.
- docs/benchmarks.md: recorded baseline numbers (indicative, machine-dependent).
- tests/test_performance.py: a benchmark smoke test (functions run, all metrics
positive, a generous non-flaky bound), a check that the recorded baseline
exists, and two tests confirming the Knowledge Base is loaded once and reused
(the loader caches; the pipeline never reloads per compilation).
Co-authored-by: kunail0804 <kunail0804@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Scaffold the Phase 0 foundation per MASTER_SPEC §24:
- Directory layout: nodes/, compiler/{analyzer,validator,resolver,splitter,
builder,common}/, knowledge_base/, schemas/, prompts/, config/,
tests/{analyzer,resolver,validator,integration,regression}/, examples/,
scripts/, docs/.
- pyproject.toml targeting Python 3.11+, jsonschema as the single runtime dep,
ruff + pytest as dev deps, explicit package list, and ruff/pytest config.
- ruff for linting and formatting; pytest with repo root on pythonpath.
- GitHub Actions CI running install, ruff lint, ruff format check, and pytest
on Python 3.11 and 3.12 for pushes and pull requests.
- docs/ skeleton and CONTRIBUTING.md referencing the wiki.
- Layout test asserting the §24 structure and package importability.
Co-authored-by: kunail0804 <kunail0804@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
