NidAll-ComfyUI_PromptStyler/TECHNICAL_DOCUMENTATION.md

PromptStyler Maintainer Notes

This document is for maintainers. It tracks architecture, pack behavior, and the rules that matter when changing runtime style resolution.

Architecture

Runtime surface:

• nodes.py: ComfyUI node definition and input/output wiring
• style_library.py: shared style loading, indexing, search, filtering, prompt composition, and legacy snapshot generation

Maintainer tooling:

• tools/validate_styles.py: strict schema and uniqueness validation
• tools/audit_styles.py: consistency audit and quality checks
• tools/add_styles.py: user/custom pack helper
• tools/generate_style_packs.py: curated pack generation plus legacy snapshot refresh
• tools/sync_legacy_styles.py: regenerate styles/styles_v1.json from merged packs
• tools/version_sync.py: check or write release metadata derived from VERSION
• STYLE_TAXONOMY.md: pack purpose, target size, and routing rules for future style additions

Data sources:

• styles/packs/*.json: primary runtime source
• styles/styles_v1.json: generated compatibility snapshot

Load Policies

style_library.py exposes two load modes:

• strict: fail on malformed files or required-field issues
• lenient: warn and skip unusable files so the runtime node can stay available

Use strict in maintainer tooling and CI. Use lenient in the ComfyUI runtime node.

Runtime Resolution Model

The node resolves one base style and optionally one overlay style.

Base style resolution modes:

• dropdown
• id
• search

Search ranking order:

1. exact id match
2. exact name match
3. token matches across id, name, category, and tags

Search filters are applied before scoring:

• category_hint
• tag_hint

If multiple candidates tie for the best score, resolution fails with the top candidates listed.

Prompt Composition Rules

Recommended composition model:

• base style
• optional color-grade overlay
• optional search-driven style lookup

Default phrase-based variant:

• style_strength=subtle: first 3 prefix phrases and first 3 suffix phrases
• style_strength=normal: first 6 prefix phrases and first 6 suffix phrases
• style_strength=strong: all phrases
• dedupe_mode=smart: remove only style-added duplicates, never collapse the raw user prompt
• dedupe_mode=off: preserve all style phrases in original order

Overlay rule:

• overlay_style_id must resolve to a category starting with Color Grade
• the overlay contributes suffix-only styling

Variant rule:

• template_variant=default uses phrase-based composition
• model-specific variants use the style's model entry when available and fall back to default otherwise

Pack Authoring Rules

Required fields per style:

• id
• name
• default.prefix
• default.suffix

Conventions:

• id must be unique and snake_case
• phrase-based text should use comma+space separators
• keep style text subject-agnostic unless the style itself is explicitly subject-specific
• avoid photo/cinema gear terms in curated styles

Release Metadata

Version metadata flow:

• edit VERSION
• run python tools/version_sync.py write
• CI enforces that VERSION, __init__.py, and .release-please-manifest.json are aligned

Maintenance Checklist

When changing curated style packs:

1. regenerate or update the packs
2. run python tools/validate_styles.py
3. run python tools/audit_styles.py
4. run python tools/sync_legacy_styles.py if needed
5. update README.md when user-visible behavior changed
6. update CHANGELOG.md