fix: forward parsed phrase, not raw text, in SAM3 tokenizer fast path

[a-yeyang]

Problem

In the SAM3 detection prompt grammar, :N sets max_detections for a category, and omitting it defaults to 1 (_parse_prompts(): result.append((part, 1))). So person:1 is documented to be equivalent to person.

It isn't. SAM3TokenizerWrapper.tokenize_with_weights() takes a fast path when there's a single prompt with max_detections == 1 — i.e. exactly the foo and foo:1 cases — but forwards the raw, unparsed text to the inner tokenizer instead of the phrase _parse_prompts() already extracted:

def tokenize_with_weights(self, text: str, return_word_ids=False, **kwargs):
    parsed = _parse_prompts(text)
    if len(parsed) <= 1 and (not parsed or parsed[0][1] == 1):
        return super().tokenize_with_weights(text, return_word_ids, **kwargs)
    #                                        ^^^^ still contains ":1"

So person:1 is literally encoded as the string "person:1", not "person". Per the issue's own measurements, this can be catastrophic depending on wording: on a test image, person masked 31.6% of the frame (correct), while person:1 — which should produce the same embedding — masked only 0.6% (a wrong, unrelated region). person:2 and person:1,person:1 already took the (correct) multi-prompt path and were unaffected.

Fix

Forward the already-parsed phrase to the fast path instead of the raw text, falling back to the original text only when parsing produced nothing (an empty string) to avoid indexing into an empty list:

    if len(parsed) <= 1 and (not parsed or parsed[0][1] == 1):
        return super().tokenize_with_weights(parsed[0][0] if parsed else text, return_word_ids, **kwargs)

This is the exact fix suggested in the issue report.

Testing

Added tests-unit/comfy_test/sam3_tokenizer_test.py, following the pattern already used in tests-unit/comfy_test/gemma4_template_test.py: a small capture stand-in subs for the inner SDTokenizer so the fix is verified against the real SAM3TokenizerWrapper.tokenize_with_weights() code path without needing real vocab/model files. Covers: the exact person:1 regression, a whitespace-padded variant, the unaffected bare-prompt and multi-prompt paths (person:2, person:1,person:1), and an empty-prompt edge case.

I verified the fix's correctness against the actual, unmodified sam3_clip.py source (loading it directly with lightweight stand-ins for its torch/transformers dependency chain, since I could not get those installed in my sandbox) — confirmed the same assertions fail against the pre-fix code and pass against the post-fix code. ruff check comfy/text_encoders/sam3_clip.py tests-unit/comfy_test/sam3_tokenizer_test.py → All checks passed. python -m py_compile on both files succeeds. I was not able to run the test file itself end-to-end with the real torch/transformers dependency chain locally (network constraints); it will run under CI's test-unit.yml, which installs the full dependency set.

Fixes #15811

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 09a93dd3-ee05-4249-bee6-b59cdeac29e6

📥 Commits

Reviewing files that changed from the base of the PR and between b78cec8 and 6734b18.

📒 Files selected for processing (2)

• comfy/text_encoders/sam3_clip.py
• tests-unit/comfy_test/sam3_tokenizer_test.py

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (6)

**/*

📄 CodeRabbit inference engine (AGENTS.md)

**/*: Keep changes small, direct, and limited to the narrowest necessary code path and smallest number of files.
Prefer practical fixes, minimal dependencies, and existing repository patterns; remove obsolete, dead, unreachable, or unused code.
Preserve existing APIs, node names, model-loading behavior, file layout, and workflow compatibility unless replacement is explicitly intended.
Core ComfyUI must not add outbound internet requests, telemetry, tracking, reporting, remote configuration, or background network activity. User-authorized model downloads are limited to the requested artifact and must exclude telemetry and unrelated metadata.

Files:

• comfy/text_encoders/sam3_clip.py
• tests-unit/comfy_test/sam3_tokenizer_test.py

**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

**/*.py: Keep state and capability flags on the object that owns the behavior. Prefer explicit parent-owned attributes over probing child objects with getattr; use child checks only when the child owns the delegated behavior.
Preserve shared method signatures, argument order, return shapes, side effects, and error behavior unless every affected caller and interface is intentionally updated.
Do not add unused compatibility parameters, flags, attributes, constructor options, or model-specific options to shared helpers; keep one-off behavior at the integration boundary.
Normalize third-party return conventions at integration boundaries so core code receives the expected type and shape; avoid undocumented caller-side unwrapping.
Do not add torch.no_grad, torch.inference_mode, or inference-mode wrappers. Do not add model freeze/unfreeze toggles; only disable globally enabled inference mode when a training path requires gradients.
Remove inference-only training behavior such as dropout while preserving checkpoint and state-dict compatibility; use nn.Identity when deleting a module would alter keys or ordering.
Keep imports at module scope except established optional-backend probes or imports required to avoid cycles; avoid unnecessary try/except blocks and use specific exceptions with useful fallbacks.
Do not add workarounds for unsupported library versions, especially PyTorch exception-and-float-cast retries, unless a comment names the exact versions still requiring them.
Let unsupported model formats, invalid quantization metadata, and bad states fail with clear errors instead of silently degrading output.
Match local style, keep comments sparse and useful, and remove comments that merely restate obvious code.
Treat dtype, device placement, VRAM use, and offloading as correctness concerns across CPU, CUDA, ROCm, MPS, DirectML, XPU, NPU, and low-VRAM environments.
Prefer existing ComfyUI and Comfy Kitchen operations, quantization helpers, cast/offload helpe...

Files:

• comfy/text_encoders/sam3_clip.py
• tests-unit/comfy_test/sam3_tokenizer_test.py

**/*.{py,json}

📄 CodeRabbit inference engine (AGENTS.md)

Treat legacy combo, io.Combo, and io.DynamicCombo values affecting filesystem access as untrusted; revalidate them at load/save boundaries with folder_paths, containment checks, or fixed allowlists.

Files:

• comfy/text_encoders/sam3_clip.py
• tests-unit/comfy_test/sam3_tokenizer_test.py

**/*.{py,md,txt,json}

📄 CodeRabbit inference engine (AGENTS.md)

Keep warning and info messages short and actionable, remove noisy or misleading logging, and make documentation edits concise, factual, and tied to changed behavior.

Files:

• comfy/text_encoders/sam3_clip.py
• tests-unit/comfy_test/sam3_tokenizer_test.py

**

⚙️ CodeRabbit configuration file

**: IMPORTANT: Only comment on issues directly introduced by this PR's code changes.
Treat AGENTS.md as mandatory repository policy, not optional style guidance.
Flag PR changes that violate AGENTS.md even when the code is otherwise functional.
In particular, enforce architecture boundaries, dtype/device/memory rules,
interface contracts, import style, no unnecessary try/except blocks, no inline
imports, no outbound internet paths in core ComfyUI, and narrow scoped fixes.
Prefer direct findings over suggestions when a rule is violated. Only ignore
AGENTS.md when it clearly conflicts with a newer explicit maintainer instruction
in the PR.
Do NOT flag pre-existing issues in code that was merely moved, re-indented,
de-indented, or reformatted without logic changes. If code appears in the diff
only due to whitespace or structural reformatting (e.g., removing a with: block),
treat it as unchanged. Contributors should not feel obligated to address
pre-existing issues outside the scope of their contribution.

Files:

• comfy/text_encoders/sam3_clip.py
• tests-unit/comfy_test/sam3_tokenizer_test.py

comfy/**

⚙️ CodeRabbit configuration file

comfy/**: Core ML/diffusion engine. Focus on:

• Backward compatibility (breaking changes affect all custom nodes)
• Memory management and GPU resource handling
• Performance implications in hot paths
• Thread safety for concurrent execution

Files:

• comfy/text_encoders/sam3_clip.py

🔇 Additional comments (3)

comfy/text_encoders/sam3_clip.py (1)

54-58: LGTM!

tests-unit/comfy_test/sam3_tokenizer_test.py (2)

1-18: LGTM!

Also applies to: 28-119

---

20-26: 🩺 Stability & Availability

Keep the CPU setup before the SAM3 import.

The import loads comfy.model_management, which reads args.cpu during initialization. On CPU-only systems, this setup is required to select CPU mode.

			> Likely an incorrect or invalid review comment.

---

📝 Walkthrough

Walkthrough

SAM3 single-prompt tokenization now encodes parsed prompt text, so :N detection-count suffixes are excluded from token content. Regression tests cover suffix stripping, bare prompts, whitespace variants, multi-prompt inputs, empty prompts, repeated prompts, and preserved detection counts.

Merge Risk: ⚪ Minimal · up to 6734b

The change forwards the parsed SAM3 phrase for the single-prompt fast path and adds focused regression coverage; no actionable merge-blocking risk remains beyond normal checks.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main fix: forwarding parsed SAM3 prompt text in the tokenizer fast path.
Description check	✅ Passed	The description directly explains the SAM3 tokenizer bug, the fix, the tests, and validation results.
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

Warning

⚠️ This pull request shows signs of AI-generated slop (redundant_comments). It has been flagged by CodeRabbit slop detection and should be reviewed carefully.