Skip to content
This repository was archived by the owner on Sep 23, 2026. It is now read-only.

Configuration Errors and Logging

Jump to bottom
kunail0804 edited this page Jul 19, 2026 · 5 revisions

Configuration, Errors & Logging

Spec reference: MASTER_SPEC §21–23.

Error & warning handling

Errors are first-class compiler objects — the compiler never silently ignores a failure. Every stage returns the Compiler Result wrapper (data, warnings, errors, metadata), identical across all modules.

Severity levels

Severity Meaning Examples
Information Describes activity; never requires action successful compilation, debug events, statistics
Warning Recoverable; compilation continues unknown concept, deprecated concept/alias, duplicate tag removed, unused field
Error Invalid intermediate data; the affected compilation stops malformed Scene JSON, missing required field, invalid category, schema mismatch, circular expansion
Fatal The compiler cannot start or continue at all Knowledge Base missing, Resolver/Analyzer unavailable, invalid configuration

The distinction: an Error halts one compilation path while the compiler remains operational; a Fatal condition means the compiler cannot run.

Message structure

Every message carries a unique code (e.g. SC0001), plus severity, title, description, and optional context. Error messages should explain what failed, why, and a possible solution. See the full list in Glossary & Reference.

Messages must be machine-readable; human-readable formatting belongs to the UI. Logs must not require string parsing.

Logging & debugging

Debugging is a core feature — intermediate representations must always be inspectable.

  • Debug levels: None, Basic, Verbose, Developer.
  • Stage inspection: users can inspect each representation: Natural Language → Scene JSON → Resolved Tags → Prompt.
  • Traceability: every tag can expose its origin sentence, Scene JSON location, Resolver rule, Knowledge Base Entry, and final category.
  • Development mode: exposes compilation time, Resolver statistics, Knowledge Base version, Analyzer version, and node versions.

Configuration

The compiler must be configurable without code modification. Configuration is external, human-readable, and version-controlled; the compiler uses JSON.

Configuration changes behaviour, never architecture. Every option must remain deterministic; random seeds must not exist.

Example

{
  "schema": "1.0",
  "analyzer": {
    "backend": "ollama",
    "model": "llama3",
    "temperature": 0.0,
    "max_retries": 3,
    "timeout": 60
  },
  "resolver": {
    "knowledge_base": "knowledge_base/",
    "strict_mode": true,
    "allow_aliases": true,
    "expansion_enabled": true,
    "max_expansion_depth": 8,
    "include_nsfw": false,
    "knowledge_base_version": null
  },
  "validator": {
    "allow_unknown_fields": false
  },
  "prompt_builder": {
    "target": "easy_illustrious",
    "separator": ",",
    "remove_duplicate_tags": true
  },
  "semantic": {
    "enabled": false,
    "min_similarity": 0.5,
    "backend": "char_ngram"
  },
  "debug": {
    "enabled": false,
    "level": "basic"
  }
}

Options by section

  • Analyzer: backend, model, temperature, max retries, timeout, context length, custom system prompt, streaming. temperature = 0 is recommended.
  • Resolver: Knowledge Base path, strict mode, alias resolution, expansion enabled, max expansion depth, include_nsfw (default false; gates explicit-rated entries), and knowledge_base_version (default null; pin a specific Knowledge Base dataset version — see Knowledge Base).
  • Scene Validator: unknown-field policy, strictness.
  • Prompt output: the prompt_builder section carries the prompt separator (used by the Resolver's translation), target, and remove_duplicate_tags. As of V2, remove_duplicate_tags is wired: it gates the Resolver's post-expansion deduplication (SC0007) and defaults to true, so output is unchanged unless explicitly disabled. The former trim_empty_outputs option was removed (inert since V1.1 dropped categories).
  • Semantic (V2, opt-in): enabled (default false), min_similarity (acceptance threshold, default 0.5), and backend (default char_ngram, a deterministic offline model). Controls the opt-in nearest-neighbour fallback — see Resolver.
  • Debug: debug mode, log level, save intermediate files, performance metrics, trace mode.

What the Configuration node exposes

The table above describes the configuration document. The Configuration node deliberately surfaces only the subset a user should have to touch, in line with design principle 3.15 (Ask Only What Matters). These fields keep their defaults and are not node inputs:

Field Why it is hidden
resolver.knowledge_base (path) The Knowledge Base ships inside the package, so the path is fixed.
prompt_builder.target Reserved; to be replaced in V3.
prompt_builder.separator Fixed to , for this version.
analyzer.system_prompt A hand-written system prompt is not a user-friendly surface; the built-in analyzer prompt is always used.

They remain part of the config document, so a programmatic caller building a Config directly can still set them. See ComfyUI Nodes for the exact node inputs.

Related pages

A note on AI assistance

This project — its code, tests, and documentation — is built with heavy help from AI coding assistants and maintained by a solo author. AI makes mistakes: despite testing and review, parts of this may be inaccurate, out of date, or wrong. Treat it as a good-faith best effort, not authoritative truth — if the docs and the code disagree, the code wins. Please open an issue when something looks off.

Clone this wiki locally