Publish Canter 0.5.0 contrastive PDG support

API.md

@@ -26,7 +26,7 @@ image = output.image
 | Parameter | Default | Description |
 | --- | --- | --- |
 | `prompts` | required | One prompt string or a sequence containing one prompt per image. |
-| `negative_prompts` | `None` | Optional CFG negative prompt string or sequence. The count must match `prompts`. `None` uses the learned unconditional token. |
+| `negative_prompts` | `None` | Optional negative prompt string or sequence for CFG and contrastive PDG. The count must match `prompts`. `None` uses the learned unconditional token. |
 | `config` | `CanterPipelineConfig()` | Inference and output settings. |
 | `initial_noise` | `None` | Optional float32 latent noise tensor with the configured batch and spatial shape. |
 | `progress` | `None` | Optional callback receiving completed and total solver updates. |
@@ -212,8 +212,9 @@ operations. The VAE decoder retains its published seed behavior.
 ### PNG metadata
 
 Images downloaded from the Gradio interface contain a `canter` PNG text field
-with compact JSON. The object begins with the prompt, effective per-image seed,
-width, height, steps, solver, and schedule. It then records PDG, CFG,
+with compact JSON. The object begins with the prompt, optional negative prompt,
+effective per-image seed, width, height, steps, solver, and schedule. It then
+records PDG, CFG,
 self-attention gain, logSNR shift, the Euler-Maruyama and ER-SDE noise
 multipliers, installed code version, numbered checkpoint release, and weight
 dtype.
@@ -287,8 +288,9 @@ output = pipe(
 Step indices run from `0` through `steps - 1`.
 
 An explicit negative prompt replaces the learned unconditional token on CFG
-branches. Negative prompts require enabled CFG or a CFG-dependent PDG mode.
-For prompt batches, supply one negative prompt per positive prompt.
+and contrastive PDG branches. Negative prompts require enabled CFG or a PDG
+mode that consumes contrastive text. For prompt batches, supply one negative
+prompt per positive prompt.
 
 ## PDG
 
@@ -342,6 +344,7 @@ contrast, and oversaturation.
 | --- | --- | --- |
 | `PdgMode.NONE` | `"none"` | No PDG branch. Required when PDG is disabled. |
 | `PdgMode.FULL` | `"full"` | Guides from the middle-skipped path toward the full main path. |
+| `PdgMode.FULL_CONTRASTIVE` | `"full_contrastive"` | Uses negative text on the middle-skipped path, or learned unconditional text when no negative prompt is supplied. |
 | `PdgMode.THREE_QUARTER` | `"three_quarter"` | Guides from the 75 percent SPRINT path toward the full main path. |
 | `PdgMode.ALTERNATE_PDG_FIRST` | `"alternate_pdg_first"` | Alternates PDG on even updates and CFG on odd updates within the PDG window. |
 | `PdgMode.ALTERNATE_CFG_FIRST` | `"alternate_cfg_first"` | Alternates CFG on even updates and PDG on odd updates within the PDG window. |
@@ -349,8 +352,12 @@ contrast, and oversaturation.
 | `PdgMode.PDG_WITH_ALTERNATING_CFG` | `"pdg_with_alternating_cfg"` | Applies PDG on every active update and adds CFG on odd updates. |
 | `PdgMode.CFG_TO_PDG` | `"cfg_to_pdg"` | Uses CFG before the PDG window, then uses full-path PDG inside the window. |
 
-The five compound modes require `cfg.scale`. `start_step=0` with
-`PdgMode.CFG_TO_PDG` begins directly with PDG.
+The five compound modes require `cfg.scale`. `PdgMode.FULL_CONTRASTIVE` uses
+the PDG scale only. `start_step=0` with `PdgMode.CFG_TO_PDG` begins directly
+with PDG.
+
+`pdg_branch_conditioning(mode)` returns `PdgBranchConditioning.POSITIVE` or
+`PdgBranchConditioning.CONTRASTIVE` for the selected PDG alternative path.
 
 ## Self-attention gain
 
@@ -457,7 +464,7 @@ schedule = output.schedule
 | Parameter | Default | Description |
 | --- | --- | --- |
 | `prompts` | required | One string or a sequence of strings. |
-| `negative_prompts` | `None` | Optional negative prompt string or sequence for CFG branches. The count must match `prompts`. |
+| `negative_prompts` | `None` | Optional negative prompt string or sequence for CFG and contrastive PDG branches. The count must match `prompts`; blank text uses learned unconditional conditioning. |
 | `config` | `CanterInferenceConfig()` | Latent inference settings. |
 | `initial_noise` | `None` | Optional float32 noise with shape `[batch, 128, height / 16, width / 16]`. |
 | `progress` | `None` | Optional callback receiving `(completed_updates, total_updates)`. |

README.md

@@ -111,8 +111,11 @@ bundled one-eighth-scale latent-RGB projection. Busy preview work is skipped,
 so the sampler never waits for browser publication. The native one-eighth-size
 preview is sent directly and scaled for display by the browser. The UI checkbox
 below the size preset disables previews.
-Downloaded PNG files contain the prompt, effective per-image settings, Canter
-code version, and numbered checkpoint release as JSON metadata.
+The negative prompt field appears when CFG or a contrastive-text PDG mode is
+active. Blank negative text uses Canter's learned unconditional conditioning.
+Downloaded PNG files contain the prompt, optional negative prompt, effective
+per-image settings, Canter code version, and numbered checkpoint release as
+JSON metadata.
 
 The server listens on port 7860. To select the bind address explicitly:
 

RELEASES.md

@@ -10,6 +10,11 @@ The current package also supplies the small latent-RGB preview projection;
 preview behavior therefore follows the installed code rather than changing an
 older denoiser checkpoint tag.
 
+Canter `0.5.0` adds contrastive PDG. Its middle-skipped guidance path uses an
+explicit negative prompt when supplied and learned unconditional text when the
+negative prompt is blank or absent. The Python API, Gradio interface, and
+ComfyUI nodes use the same branch-selection rule.
+
 Canter `0.4.1` makes the dense backend apply to the bundled text encoder as
 well as denoiser text attention. Dense text encoding now uses padded PyTorch
 scaled dot-product attention and does not require the explicit CUDA

TECHNICAL_REPORT.md

@@ -424,9 +424,11 @@ At resolutions around the \\(1024^2\\) aspect-ratio buckets, a PDG scale near 2.
 and a self-attention gain near -0.03 gives substantially better results than
 reducing PDG while leaving the gain at zero.
 
-PDG can be combined with CFG, including CFG with negative prompts. The release
-also provides several CFG/PDG interaction modes, constant, linear, and power
-PDG curves, and independent start and stop steps for both guidance methods.
+Contrastive PDG conditions the middle-skipped path with either a negative
+prompt or Canter's learned unconditional text. PDG can also be combined with
+CFG. The release provides several CFG/PDG interaction modes, constant, linear,
+and power PDG curves, and independent start and stop steps for both guidance
+methods.
 See [API and inference parameters](API.md) for the complete interface.
 
 ## Dataset

canter/__init__.py

@@ -16,9 +16,11 @@ from .inference import (
     CanterLatentOutput,
     CanterVelocityModel,
     CfgGuidance,
+    PdgBranchConditioning,
     PdgCurve,
     PdgGuidance,
     PdgMode,
+    pdg_branch_conditioning,
 )
 from .loading import (
     CanterComponents,
@@ -79,6 +81,7 @@ __all__ = [
     "CfgGuidance",
     "LatentRgbPreviewer",
     "LatentRgbProjection",
+    "PdgBranchConditioning",
     "PdgCurve",
     "PdgGuidance",
     "PdgMode",
@@ -92,5 +95,6 @@ __all__ = [
     "WeightDType",
     "__version__",
     "build_schedule",
+    "pdg_branch_conditioning",
     "solve",
 ]

canter/inference.py

@@ -42,6 +42,7 @@ class PdgMode(Enum):
 
     NONE = "none"
     FULL = "full"
+    FULL_CONTRASTIVE = "full_contrastive"
     THREE_QUARTER = "three_quarter"
     ALTERNATE_PDG_FIRST = "alternate_pdg_first"
     ALTERNATE_CFG_FIRST = "alternate_cfg_first"
@@ -308,25 +309,38 @@ def _pdg_uses_cfg(mode: PdgMode) -> bool:
             | PdgMode.CFG_TO_PDG
         ):
             return True
-        case PdgMode.NONE | PdgMode.FULL | PdgMode.THREE_QUARTER:
+        case (
+            PdgMode.NONE
+            | PdgMode.FULL
+            | PdgMode.FULL_CONTRASTIVE
+            | PdgMode.THREE_QUARTER
+        ):
             return False
         case _ as unreachable:
             raise RuntimeError(f"Unsupported PDG mode: {unreachable}")
 
 
-def _pdg_tweak_uses_unconditional(mode: PdgMode) -> bool:
-    """Return whether a single active PDG branch uses unconditional text."""
+class PdgBranchConditioning(Enum):
+    """Text conditioning supplied to an active PDG alternative path."""
+
+    POSITIVE = "positive"
+    CONTRASTIVE = "contrastive"
+
+
+def pdg_branch_conditioning(mode: PdgMode) -> PdgBranchConditioning:
+    """Return the text branch used by an active PDG alternative path."""
 
     match mode:
         case (
-            PdgMode.ALTERNATE_PDG_FIRST
+            PdgMode.FULL_CONTRASTIVE
+            | PdgMode.ALTERNATE_PDG_FIRST
             | PdgMode.ALTERNATE_CFG_FIRST
             | PdgMode.COMBINED_CFG_PDG
             | PdgMode.PDG_WITH_ALTERNATING_CFG
         ):
-            return True
+            return PdgBranchConditioning.CONTRASTIVE
         case PdgMode.NONE | PdgMode.FULL | PdgMode.THREE_QUARTER | PdgMode.CFG_TO_PDG:
-            return False
+            return PdgBranchConditioning.POSITIVE
         case _ as unreachable:
             raise RuntimeError(f"Unsupported PDG mode: {unreachable}")
 
@@ -406,7 +420,8 @@ class CanterGuidedVelocity:
         if active.pdg:
             tweak_text = (
                 self._unconditional()
-                if _pdg_tweak_uses_unconditional(self.config.pdg.mode)
+                if pdg_branch_conditioning(self.config.pdg.mode)
+                is PdgBranchConditioning.CONTRASTIVE
                 else self.conditional
             )
             tweak = self._predict(
@@ -433,7 +448,12 @@ class CanterGuidedVelocity:
         pdg_active = self.config.pdg.enabled and _inside(step, self.pdg_window)
         mode = self.config.pdg.mode
         match mode:
-            case PdgMode.NONE | PdgMode.FULL | PdgMode.THREE_QUARTER:
+            case (
+                PdgMode.NONE
+                | PdgMode.FULL
+                | PdgMode.FULL_CONTRASTIVE
+                | PdgMode.THREE_QUARTER
+            ):
                 return _GuidanceStep(cfg_active, pdg_active, mode)
             case PdgMode.ALTERNATE_PDG_FIRST:
                 if pdg_active:
@@ -520,7 +540,7 @@ class CanterGuidedVelocity:
 
         if self.unconditional is None:
             raise RuntimeError(
-                "An active CFG-dependent branch is missing unconditional text."
+                "An active contrastive branch is missing negative or unconditional text."
             )
         return self.unconditional
 
@@ -529,7 +549,7 @@ class CanterGuidedVelocity:
         """Map a concrete public PDG mode to one frozen model path."""
 
         match mode:
-            case PdgMode.FULL:
+            case PdgMode.FULL | PdgMode.FULL_CONTRASTIVE:
                 return CanterPath.SKIP_MIDDLE
             case PdgMode.THREE_QUARTER:
                 return CanterPath.THREE_QUARTER
@@ -549,7 +569,12 @@ def _needs_unconditional_text(config: CanterGuidanceConfig) -> bool:
     """Return whether any configured inference step can use unconditional text."""
 
     return bool(config.cfg.enabled) or (
-        bool(config.pdg.enabled) and _pdg_uses_cfg(config.pdg.mode)
+        bool(config.pdg.enabled)
+        and (
+            _pdg_uses_cfg(config.pdg.mode)
+            or pdg_branch_conditioning(config.pdg.mode)
+            is PdgBranchConditioning.CONTRASTIVE
+        )
     )
 
 
@@ -793,5 +818,7 @@ def _negative_prompt_batch(
     if _prompt_batch_is_blank(values):
         return None
     if not required:
-        raise ValueError("Negative prompts require an active CFG branch.")
+        raise ValueError(
+            "Negative prompts require active CFG or contrastive PDG guidance."
+        )
     return values

canter/version.py

@@ -1,4 +1,4 @@
 """Single source of truth for the installable Canter code version."""
 
-__version__ = "0.4.1"
+__version__ = "0.5.0"
 CANTER_VERSION = __version__

canter/webui_app.py

@@ -28,6 +28,7 @@ from .webui_runtime import (
     _unloaded_model_status,
     random_seed,
     snap_image_dimension,
+    update_negative_prompt_visibility,
     update_pdg_clean_scale,
 )
 
@@ -49,6 +50,7 @@ _SCHEDULE_CHOICES = (
 )
 _PDG_MODE_CHOICES = (
     ("Full path drop", PdgMode.FULL.value),
+    ("Contrastive PDG", PdgMode.FULL_CONTRASTIVE.value),
     ("Three-quarter path", PdgMode.THREE_QUARTER.value),
     ("Alternate: PDG first", PdgMode.ALTERNATE_PDG_FIRST.value),
     ("Alternate: CFG first", PdgMode.ALTERNATE_CFG_FIRST.value),
@@ -333,6 +335,7 @@ class _BasicInputs:
     """Prompt and basic generation controls rendered above advanced settings."""
 
     prompt: gr.Textbox
+    negative_prompt: gr.Textbox
     image_count: gr.Number
     size_preset: gr.Dropdown
     preview_enabled: gr.Checkbox
@@ -370,6 +373,7 @@ class _WebInputs:
     pdg_power: gr.Slider
     pdg_start_step: gr.Number
     pdg_stop_step: gr.Textbox
+    negative_prompt: gr.Textbox
 
     def ordered(self) -> tuple[gr.Component, ...]:
         """Return components in the order accepted by ``generate``."""
@@ -399,6 +403,7 @@ class _WebInputs:
             self.pdg_start_step,
             self.pdg_stop_step,
             self.preview_enabled,
+            self.negative_prompt,
         )
 
 
@@ -441,10 +446,14 @@ def _prompt_input() -> gr.Textbox:
     )
 
 
-def _basic_inputs(prompt: gr.Textbox) -> _BasicInputs:
+def _basic_inputs(
+    prompt: gr.Textbox,
+    negative_prompt: gr.Textbox,
+) -> _BasicInputs:
     """Render prompt, image-count, preset, shape, and seed controls."""
 
     prompt.render()
+    negative_prompt.render()
     image_count = gr.Number(
         minimum=1,
         maximum=_MAX_IMAGE_COUNT,
@@ -488,6 +497,7 @@ def _basic_inputs(prompt: gr.Textbox) -> _BasicInputs:
     )
     return _BasicInputs(
         prompt=prompt,
+        negative_prompt=negative_prompt,
         image_count=image_count,
         size_preset=size_preset,
         preview_enabled=preview_enabled,
@@ -729,6 +739,19 @@ def _pdg_inputs() -> tuple[
     return enabled, mode, curve, noisy_scale, clean_scale, power, start, stop
 
 
+def _negative_prompt_input() -> gr.Textbox:
+    """Create an initially hidden negative prompt below the positive prompt."""
+
+    return gr.Textbox(
+        value="",
+        label="Negative prompt",
+        lines=3,
+        visible=False,
+        interactive=False,
+        render=False,
+    )
+
+
 def _create_inputs(
     basic: _BasicInputs,
 ) -> _WebInputs:
@@ -782,6 +805,7 @@ def _create_inputs(
         pdg_power=pdg_power,
         pdg_start_step=pdg_start,
         pdg_stop_step=pdg_stop,
+        negative_prompt=basic.negative_prompt,
     )
 
 
@@ -1053,7 +1077,8 @@ def _create_workspace(
     with gr.Row(elem_id="canter-workspace"):
         with gr.Column(scale=3, min_width=360, elem_id="canter-controls"):
             prompt = _prompt_input()
-            basic = _basic_inputs(prompt)
+            negative_prompt = _negative_prompt_input()
+            basic = _basic_inputs(prompt, negative_prompt)
             with gr.Row():
                 generate = gr.Button(
                     "Generate",
@@ -1157,6 +1182,15 @@ def _connect_control_callbacks(
         api_name=None,
         api_visibility="private",
     )
+    for component in (inputs.cfg_enabled, inputs.pdg_enabled, inputs.pdg_mode):
+        component.change(
+            fn=update_negative_prompt_visibility,
+            inputs=(inputs.cfg_enabled, inputs.pdg_enabled, inputs.pdg_mode),
+            outputs=inputs.negative_prompt,
+            queue=False,
+            api_name=None,
+            api_visibility="private",
+        )
     controls.api.click(
         fn=None,
         inputs=None,

canter/webui_runtime.py

@@ -22,9 +22,11 @@ from PIL import Image
 from .inference import (
     CanterInferenceConfig,
     CfgGuidance,
+    PdgBranchConditioning,
     PdgCurve,
     PdgGuidance,
     PdgMode,
+    pdg_branch_conditioning,
 )
 from .pipeline import (
     CanterOutputType,
@@ -64,6 +66,7 @@ class _ImagePipeline(Protocol):
         self,
         prompts: str | Sequence[str],
         *,
+        negative_prompts: str | Sequence[str] | None,
         config: CanterPipelineConfig,
         initial_noise: None,
         progress: SolverProgress | None,
@@ -84,6 +87,7 @@ class CanterWebRequest:
     """Validated sequential image request and frozen base configuration."""
 
     prompt: str
+    negative_prompt: str | None
     image_count: int
     config: CanterPipelineConfig
 
@@ -287,6 +291,7 @@ class CanterWebController:
         pdg_start_step: int | float,
         pdg_stop_step: int | float | str | None,
         preview_enabled: bool,
+        negative_prompt: str = "",
         browser_request: gr.Request | None = None,
     ) -> Generator[_GenerationUpdate, None, None]:
         """Yield each batch-one image as soon as its decoding completes."""
@@ -316,6 +321,7 @@ class CanterWebController:
             pdg_power=pdg_power,
             pdg_start_step=pdg_start_step,
             pdg_stop_step=pdg_stop_step,
+            negative_prompt=negative_prompt,
         )
         _log_generation_request(request)
         pipeline = self._ensure_loaded()
@@ -353,6 +359,7 @@ class CanterWebController:
                 image_config = _image_config(request, image_index)
                 output = pipeline(
                     request.prompt,
+                    negative_prompts=request.negative_prompt,
                     config=image_config,
                     initial_noise=None,
                     progress=_step_progress(
@@ -395,6 +402,7 @@ class CanterWebController:
                 image = _attach_png_metadata(
                     output.images[0],
                     prompt=request.prompt,
+                    negative_prompt=request.negative_prompt,
                     config=image_config,
                     metadata=pipeline.metadata,
                 )
@@ -812,6 +820,21 @@ def _validated_prompt(prompt: str) -> str:
     return prompt
 
 
+def _validated_negative_prompt(prompt: str, *, enabled: bool) -> str | None:
+    """Resolve blank negative text to learned unconditional conditioning."""
+
+    if not isinstance(prompt, str):
+        raise TypeError("negative_prompt must be a string.")
+    if not prompt.strip():
+        return None
+    if not enabled:
+        raise ValueError(
+            "A negative prompt requires active CFG or a PDG mode that consumes "
+            "contrastive text."
+        )
+    return prompt
+
+
 def _pdg_mode_uses_cfg(mode: PdgMode) -> bool:
     """Return whether one public PDG mode consumes the CFG scale."""
 
@@ -824,7 +847,7 @@ def _pdg_mode_uses_cfg(mode: PdgMode) -> bool:
             | PdgMode.CFG_TO_PDG
         ):
             return True
-        case PdgMode.FULL | PdgMode.THREE_QUARTER:
+        case PdgMode.FULL | PdgMode.FULL_CONTRASTIVE | PdgMode.THREE_QUARTER:
             return False
         case PdgMode.NONE:
             raise ValueError("The enabled web PDG selection cannot use mode none.")
@@ -832,6 +855,29 @@ def _pdg_mode_uses_cfg(mode: PdgMode) -> bool:
             raise RuntimeError(f"Unsupported PDG mode: {unreachable}")
 
 
+def update_negative_prompt_visibility(
+    cfg_enabled: bool,
+    pdg_enabled: bool,
+    pdg_mode: str,
+) -> dict[str, object]:
+    """Show negative text only when the selected guidance can consume it."""
+
+    resolved_mode = _choice(pdg_mode, _PDG_MODES, "PDG mode")
+    visible = bool(cfg_enabled) or (
+        bool(pdg_enabled)
+        and (
+            _pdg_mode_uses_cfg(resolved_mode)
+            or pdg_branch_conditioning(resolved_mode)
+            is PdgBranchConditioning.CONTRASTIVE
+        )
+    )
+    match visible:
+        case True:
+            return gr.update(visible=True, interactive=True)
+        case False:
+            return gr.update(value="", visible=False, interactive=False)
+
+
 def update_pdg_clean_scale(
     curve: str,
     noisy_scale: int | float,
@@ -876,12 +922,25 @@ def build_web_request(
     pdg_power: int | float,
     pdg_start_step: int | float,
     pdg_stop_step: int | float | str | None,
+    negative_prompt: str = "",
 ) -> CanterWebRequest:
     """Validate raw Gradio values and construct the frozen Canter dataclasses."""
 
     resolved_pdg_mode = _choice(pdg_mode, _PDG_MODES, "PDG mode")
     active_pdg_mode = resolved_pdg_mode if pdg_enabled else PdgMode.NONE
     uses_cfg_scale = pdg_enabled and _pdg_mode_uses_cfg(resolved_pdg_mode)
+    uses_negative_prompt = cfg_enabled or (
+        pdg_enabled
+        and (
+            uses_cfg_scale
+            or pdg_branch_conditioning(resolved_pdg_mode)
+            is PdgBranchConditioning.CONTRASTIVE
+        )
+    )
+    resolved_negative_prompt = _validated_negative_prompt(
+        negative_prompt,
+        enabled=uses_negative_prompt,
+    )
     resolved_cfg_scale = (
         _number(cfg_scale, "CFG scale") if cfg_enabled or uses_cfg_scale else None
     )
@@ -952,6 +1011,7 @@ def build_web_request(
     )
     return CanterWebRequest(
         prompt=_validated_prompt(prompt),
+        negative_prompt=resolved_negative_prompt,
         image_count=resolved_image_count,
         config=CanterPipelineConfig(
             inference=inference,
@@ -1006,6 +1066,7 @@ def _cfg_metadata(cfg: CfgGuidance) -> dict[str, object]:
 def _png_metadata_json(
     *,
     prompt: str,
+    negative_prompt: str | None,
     config: CanterPipelineConfig,
     metadata: CanterPipelineMetadata,
 ) -> str:
@@ -1016,6 +1077,7 @@ def _png_metadata_json(
         raise RuntimeError("PNG metadata requires the resolved per-image seed.")
     payload: dict[str, object] = {
         "prompt": prompt,
+        "negative_prompt": negative_prompt,
         "seed": inference.seed,
         "width": inference.width,
         "height": inference.height,
@@ -1038,6 +1100,7 @@ def _attach_png_metadata(
     image: Image.Image,
     *,
     prompt: str,
+    negative_prompt: str | None,
     config: CanterPipelineConfig,
     metadata: CanterPipelineMetadata,
 ) -> Image.Image:
@@ -1045,6 +1108,7 @@ def _attach_png_metadata(
 
     image.info[_PNG_METADATA_KEY] = _png_metadata_json(
         prompt=prompt,
+        negative_prompt=negative_prompt,
         config=config,
         metadata=metadata,
     )