ComfyUI-Sigmax is a planned model-aware sigma schedule and sampler toolkit for ComfyUI. Its first validation targets are Krea 2 Turbo and Krea 2 RAW; the longer-term design supports versioned profiles for other flow-matching and diffusion model families.

Status: pre-alpha foundation. No user-facing ComfyUI nodes are implemented yet. The current repository provides a side-effect-free package shell, packaging metadata, quality gates, framework-independent schedule primitives, canonical schedule-artifact serialization, and the first evidence-pinned Krea 2 Turbo structural profile. It also provides typed model/profile/sampler capability preflight and complete independent 4/8/12/16-step Turbo golden vectors, but does not yet claim framework or native-ComfyUI parity and exposes no ComfyUI nodes. The complete core and profile layer are dependency-free and have enforced isolation/property/golden test lanes.

Why Sigmax

Sampling systems often mix four different concerns:

how a model interprets time or sigma;
how the sigma sequence is constructed;
which numerical sampler integrates model predictions;
which settings are authoritative for a specific model variant.

Sigmax will keep those concerns separate. A schedule must come from an explicit, traceable profile; experimental transforms must remain distinguishable from reference behavior; and features that require stateful sampler steps must not be represented as inert sigma controls.

Planned Product Shape

The intended toolkit includes:

official-parity Krea 2 Turbo and resolution-aware Krea 2 RAW schedules;
a pure, independently testable schedule engine;
versioned model profiles with evidence and provenance;
simple model-aware and advanced schedule nodes;
schedule inspection, comparison, metadata, and fingerprints;
native ComfyUI Euler reuse where it is mathematically equivalent;
separate full-sampler implementations only where sigma tensors are insufficient;
numerical golden, parity, property, and integration test lanes.

These are roadmap targets, not claims about the current package.

Current Repository Surface

The import contract is intentionally minimal:

import comfyui_sigmax

assert comfyui_sigmax.NODE_CLASS_MAPPINGS == {}
assert comfyui_sigmax.NODE_DISPLAY_NAME_MAPPINGS == {}

Empty mappings prevent unfinished nodes from being registered. Runtime dependencies are also empty; Diffusers is an optional reference dependency used for later parity research.

The pure core currently exposes explicit schedule ownership, sigma domains, transform stages, pre-execution compatibility validation, and immutable request/result structures:

from comfyui_sigmax.core import (
    ScheduleInputs,
    ScheduleOwnership,
    SigmaDomain,
    TerminalPolicy,
    apply_terminal_policy,
    exponential_mu_shift,
    krea_reciprocal_step_grid,
)

ownership = ScheduleOwnership.EXTERNAL_SIGMAS
domain = SigmaDomain.UNIT_FLOW
requested_inputs = ScheduleInputs(steps=8, width=1024, height=1024)
base_grid = krea_reciprocal_step_grid(8)
shifted = exponential_mu_shift(base_grid, mu=1.15)
sigmas = apply_terminal_policy(
    shifted,
    policy=TerminalPolicy.APPEND_ZERO,
    domain=domain,
)

Model-native, externally constructed, and model-patched schedules are mutually exclusive. External transforms cannot be silently applied to native or patched ownership. Requested and effective inputs are stored separately, and effective step or dimension changes require an explicit override record.

The Krea builder returns only the unshifted, non-terminal base grid. Exponential mu, direct-ratio, and explicit no-shift transforms are separate, unit-flow-only operations. The terminal stage remains separate so terminal zero cannot be appended or transformed twice. Terminal-inclusive start/end ranges and ComfyUI-compatible partial-denoise tail slicing are also explicit; invalid or empty manual ranges fail instead of silently changing execution.

Complete external schedules can be validated for finite values, domain bounds, exact transition count, strict decrease, and terminal-zero policy. The core also provides typed IEEE-754 float tokens, bounded NFC canonical projections, and separate numerical and construction SHA-256 fingerprints that reproduce the published artifact fixtures.

Validated external ScheduleResult values can now be built into immutable ScheduleArtifact objects and transported as strict canonical UTF-8 JSON:

from comfyui_sigmax.core import (
    build_schedule_artifact,
    deserialize_schedule_artifact,
    serialize_schedule_artifact,
)

# `result` and `metadata` are validated immutable core contracts.
artifact = build_schedule_artifact(result, metadata=metadata, precision="float64")
payload = serialize_schedule_artifact(artifact)
restored = deserialize_schedule_artifact(payload)

assert restored == artifact

The parser bounds input size, rejects duplicate keys, BOMs, invalid UTF-8, JSON floating literals, non-standard constants, unknown schema fields, and non-canonical encodings. It recomputes both numerical and construction fingerprints before returning an artifact.

Model, profile, sampler, and requested execution features also have immutable capability contracts:

from comfyui_sigmax.core import (
    CompatibilityLevel,
    ExecutionFeatureRequest,
    ModelCapabilities,
    ProfileCapabilities,
    SamplerCapabilities,
    evaluate_compatibility,
    require_compatible,
)

# `model`, `profile`, and `sampler` are validated capability declarations.
decision = evaluate_compatibility(
    model=model,
    profile=profile,
    sampler=sampler,
    request=ExecutionFeatureRequest(),
)
assert decision.level in {
    CompatibilityLevel.ALLOW,
    CompatibilityLevel.WARN,
}
require_compatible(decision)

The preflight checks model family and variant, prediction and sigma domains, schedule ownership, terminal requirements, deterministic or stochastic behavior, noise ownership, sampler state, partial denoise, and per-token timesteps. Its stable reason codes distinguish ALLOW, WARN, and REJECT; rejected combinations fail before host or sampler execution.

The first concrete profile is an immutable, evidence-pinned declaration of the official Krea 2 Turbo recipe:

from comfyui_sigmax.profiles import (
    KREA2_TURBO_PROFILE,
    build_krea2_turbo_schedule,
)

assert KREA2_TURBO_PROFILE.profile_id == "krea2.turbo.official"
result = build_krea2_turbo_schedule(width=1025, height=1024)
assert result.effective_inputs.width == 1040
assert len(result.sigmas) == 9

The profile declares unit-flow external schedule ownership, the Krea reciprocal-step grid, fixed exponential mu = 1.15, terminal zero, deterministic ComfyUI Euler capabilities, Krea-guidance 0.0 / ComfyUI-CFG 1.0, and ceil-to-16 dimensions. Its references are pinned to immutable Krea, Diffusers, and ComfyUI revisions. Non-eight-step construction is allowed only as an explicitly modified result.

The committed tests/golden/krea2_turbo_v1.json fixture freezes complete terminal-inclusive 4-, 8-, 12-, and 16-step float64 and IEEE-754 float32 vectors. A standard-library-only high-precision Decimal generator imports no Sigmax, ComfyUI, Diffusers, NumPy, or PyTorch code; regeneration must match the canonical fixture byte for byte. The eight-step vector also passes a separate implementation of Krea's official direct expression. This is independent golden/formula evidence, while Krea/Diffusers execution and native ComfyUI parity remain later validation stages.

The canonical gate runs scripts/check_core_independence.py before pytest. It requires a clean dev environment, launches Python isolated mode, blocks comfy and diffusers, and imports every core and profile module. Static import-boundary and deterministic property/metamorphic/golden tests provide complementary evidence. These checks prove framework independence and detect Turbo formula drift; they do not claim Krea/Diffusers or native ComfyUI execution parity.

Development Setup

Python 3.10 or newer is required.

Windows:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
powershell -File scripts/run_full_tests_windows.ps1

Linux or WSL:

python3 -m venv .venv-wsl
.venv-wsl/bin/python -m pip install -e '.[dev]'
bash scripts/run_full_tests_linux.sh

See Contributing for the development workflow and Compatibility for the distinction between validated environments and planned host/model support.

Documentation

License and Attribution

ComfyUI-Sigmax is distributed under the MIT License. The project retains attribution for its audited source lineage in NOTICE.