The docs had drifted badly: docs/nodes.md still documented the Category Splitter
and Prompt Builder (removed in V1.1) and the Knowledge Base Loader (removed in
V2.1), gave the Resolver the wrong outputs, and the consistency test actively
pinned the retired RESOLVED_TAGS/CATEGORY_MAP types.
- README: rewritten around the V2 philosophy shift — 'know more, ask less'.
Documents the automatic Knowledge Base growth, the opt-in KB-bounded semantic
fallback and the fidelity work (know more), and the configuration
centralization, node consolidation (eight nodes -> five) and hidden
non-user-facing options (ask less), plus what did not change: determinism.
Corrects the tagline (flat prompt, not category-separated) and the node tables.
- docs/nodes.md: rewritten for the five shipped nodes with their real inputs and
outputs, plus a full Configuration input reference and the settings that are
deliberately not exposed.
- docs/definition_of_done.md: V1 record marked complete; evidence re-pointed at
the code as it stands (no compiler/splitter, compiler/builder).
- docs/README.md: MASTER_SPEC reframed as the original design spec (code wins);
index the in-repo docs.
- examples/README.md: pipeline diagram redrawn for the current graph.
- tests/test_docs_consistency.py: stop requiring the retired inter-stage types and
add a guard so removed nodes cannot reappear in the reference.
Co-authored-by: kunail0804 <kunail0804@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
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>
* feat(nodes): centralize duplicated settings on Configuration + add tooltips
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: Claude Opus 4.8 <noreply@anthropic.com>
* fix(examples): refresh workflow widget values; guard against widget drift
The shipped example workflow carried stale positional widget values from before
V2 removed prompt_builder.trim_empty_outputs from the Configuration node. ComfyUI
stores widgets positionally, so every later value shifted: debug_level received a
leftover boolean ("false") and, in older saved workflows, the prompt separator
received a boolean ("true") instead of ",".
- Rebuild the Configuration node's 21 widget values in the current order.
- Update the Analyzer node to the current shape (natural_language + system_prompt;
config now arrives via a wired COMPILER_CONFIG input) and wire the Configuration
node into it.
- Add the KB Loader's version widget value.
- New regression test: every example-workflow node's widgets_values length must
match the node's current widget count, so this drift cannot recur silently.
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>
* feat!: collapse pipeline — Resolver emits a flat prompt, drop categories (v1.1)
BREAKING CHANGE: the Category Splitter and Prompt Builder stages and nodes are
removed. The Resolver is now the translator from Scene JSON to prompt: it resolves
concepts to Knowledge Base tags and joins them into one flat comma-separated
prompt string, in resolution order (which naturally leads with character concepts).
Resolver node outputs are now (prompt, warnings, errors, json) — the json being
the traceable resolved tags so a translation problem is inspectable. Node count
drops from 8 to 6. The CategoryMap/PromptOutput models and their schemas are
removed; the `category` field remains on entries and resolved tags for
traceability only. Debug Viewer simplified to scene/warnings/errors.
Goldens, example scenes/workflow, integration/performance/repo-layout/release
tests, benchmark script, and the docs (README + wiki) are updated to the flat
prompt. Version bumped to 1.1.0.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* build: drop removed splitter/builder packages from pyproject
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>
Ship ready-to-use examples (MASTER_SPEC §24, Phase 7).
- examples/workflows/scene_compiler_pipeline.json: a ComfyUI workflow wiring
Configuration + Knowledge Base Loader + Analyzer -> Validator -> Resolver ->
Category Splitter -> Prompt Builder.
- examples/scenes/*.scene.json: standalone example Scene JSON documents
(single character; two characters with an interaction and an expansion).
- examples/scenes/*.prompts.json: the exact prompt outputs each scene compiles to
with the shipped Knowledge Base and default config.
- examples/README.md: how to load the workflow and use the scene examples.
tests/test_examples.py asserts each example Scene JSON compiles to its documented
outputs, and that the workflow references only registered Scene Compiler nodes
and includes the full pipeline. The workflow JSON still wants a ComfyUI visual
check.
Co-authored-by: kunail0804 <kunail0804@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Formalize the Knowledge Base on-disk format and tighten the entry schema per
MASTER_SPEC §15.3-§15.10, §18.2.
- compiler/common/categories.py: single source of truth for the 19 canonical
categories (lowercase identifiers of the §18.2 list) plus is_valid_category.
- knowledge_base_entry.schema.json (v1.1): category restricted to the 19; tags
require at least one item; expand entries must be snake_case canonical ids;
aliases uniqueItems.
- knowledge_base/README.md: by-domain file layout, the "each file is a JSON array
of entries" format, and contributor field rules (id/alias global uniqueness,
tag order, expansion targets, one-tag minimum).
- examples/knowledge_base.example.json: worked file demonstrating an alias and an
expansion.
Cross-entry rules (global uniqueness, expand targets exist) are deferred to the
KB validation tooling (#9); this issue defines per-entry structure only.
Tests: 19-category constant and schema-enum consistency, entry validation
(category/tags/id/expand/unknown-field), and the worked example (array shape,
per-entry validity, alias+expansion present, expand targets resolve).
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>
