multimodal-preprocess-kit 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. multimodal_preprocess_kit-0.2.0/LICENSE +21 -0
  2. multimodal_preprocess_kit-0.2.0/PKG-INFO +144 -0
  3. multimodal_preprocess_kit-0.2.0/README.md +116 -0
  4. multimodal_preprocess_kit-0.2.0/mm_preprocess_kit/__init__.py +32 -0
  5. multimodal_preprocess_kit-0.2.0/mm_preprocess_kit/caption_quality.py +139 -0
  6. multimodal_preprocess_kit-0.2.0/mm_preprocess_kit/fallback.py +22 -0
  7. multimodal_preprocess_kit-0.2.0/mm_preprocess_kit/models.py +49 -0
  8. multimodal_preprocess_kit-0.2.0/mm_preprocess_kit/policy.py +81 -0
  9. multimodal_preprocess_kit-0.2.0/mm_preprocess_kit/py.typed +0 -0
  10. multimodal_preprocess_kit-0.2.0/multimodal_preprocess_kit.egg-info/PKG-INFO +144 -0
  11. multimodal_preprocess_kit-0.2.0/multimodal_preprocess_kit.egg-info/SOURCES.txt +21 -0
  12. multimodal_preprocess_kit-0.2.0/multimodal_preprocess_kit.egg-info/dependency_links.txt +1 -0
  13. multimodal_preprocess_kit-0.2.0/multimodal_preprocess_kit.egg-info/requires.txt +3 -0
  14. multimodal_preprocess_kit-0.2.0/multimodal_preprocess_kit.egg-info/top_level.txt +1 -0
  15. multimodal_preprocess_kit-0.2.0/pyproject.toml +44 -0
  16. multimodal_preprocess_kit-0.2.0/setup.cfg +4 -0
  17. multimodal_preprocess_kit-0.2.0/tests/test_caption_mode.py +24 -0
  18. multimodal_preprocess_kit-0.2.0/tests/test_caption_quality.py +102 -0
  19. multimodal_preprocess_kit-0.2.0/tests/test_decide_actions.py +49 -0
  20. multimodal_preprocess_kit-0.2.0/tests/test_defer.py +37 -0
  21. multimodal_preprocess_kit-0.2.0/tests/test_fallback.py +19 -0
  22. multimodal_preprocess_kit-0.2.0/tests/test_no_borrow.py +9 -0
  23. multimodal_preprocess_kit-0.2.0/tests/test_retry.py +12 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 multimodal-preprocess-kit contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,144 @@
1
+ Metadata-Version: 2.4
2
+ Name: multimodal-preprocess-kit
3
+ Version: 0.2.0
4
+ Summary: A framework-agnostic policy kit for chatbot multimodal preprocessing: caption retry, pending-message deferral, caption-mode selection, caption quality checks, and safe fallback.
5
+ Author: multimodal-preprocess-kit contributors
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/AirXsLink/multimodal-preprocess-kit
8
+ Project-URL: Repository, https://github.com/AirXsLink/multimodal-preprocess-kit
9
+ Project-URL: Issues, https://github.com/AirXsLink/multimodal-preprocess-kit/issues
10
+ Project-URL: Changelog, https://github.com/AirXsLink/multimodal-preprocess-kit/blob/main/CHANGELOG.md
11
+ Keywords: chatbot,multimodal,preprocessing,policy,fallback
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: License :: OSI Approved :: MIT License
20
+ Classifier: Operating System :: OS Independent
21
+ Classifier: Typing :: Typed
22
+ Requires-Python: >=3.11
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Provides-Extra: test
26
+ Requires-Dist: pytest>=8; extra == "test"
27
+ Dynamic: license-file
28
+
29
+ # multimodal-preprocess-kit
30
+
31
+ [English](https://github.com/AirXsLink/multimodal-preprocess-kit/blob/main/README.md) | [简体中文](https://github.com/AirXsLink/multimodal-preprocess-kit/blob/main/README.zh-CN.md)
32
+
33
+ A framework-agnostic policy kit for chatbot multimodal preprocessing: caption retry, pending-message deferral, caption-mode selection, caption quality checks, and safe fallback.
34
+
35
+ **At a glance (defaults):**
36
+
37
+ | Situation | Decision |
38
+ | --- | --- |
39
+ | Caption `failed` | `drop_media` |
40
+ | Caption `too_short`, or `ready` and under 40 chars | `retry_caption` |
41
+ | Caption `pending`, waited ≤ 90s | `defer` with `retry_after` |
42
+ | Caption `pending`, waited > 90s | `push_without_media` |
43
+ | Caption `ready` and non-empty | `push_now`; screenshots carry `"auto"` |
44
+ | No local file, thumbnails enabled | thumbnail fallback |
45
+ | Media from another message | never borrowed unless explicitly enabled |
46
+
47
+ ## Problem
48
+
49
+ Vision-language captions are often slower than the chat message buffer. A bot may first answer that it cannot see an image, then describe it a second later. Screenshots lose their text when they are summarized instead of transcribed. And when the original media is unavailable, a pipeline may borrow a nearby image, silently attaching the wrong picture to a message.
50
+
51
+ ## What it does NOT do
52
+
53
+ - Calls no model (VL, LLM, or otherwise).
54
+ - Connects to no chat platform and performs no network I/O.
55
+ - Stores no chat history.
56
+ - Reads, decodes, or uploads no media files.
57
+
58
+ ## Install
59
+
60
+ ```bash
61
+ pip install -e .
62
+ ```
63
+
64
+ ## Quick Start
65
+
66
+ ```python
67
+ from mm_preprocess_kit.models import MediaItem, PolicyConfig
68
+ from mm_preprocess_kit.policy import decide
69
+
70
+ media = MediaItem(id="m1", kind="image", caption_status="pending", received_at=0.0)
71
+ decision = decide(media, now=30.0, cfg=PolicyConfig())
72
+ print(decision.action, decision.reason, decision.retry_after) # defer caption_pending 60.0
73
+ ```
74
+
75
+ Screenshots get `caption_mode="auto"`. Resolve it with `choose_caption_mode(width, height, cfg)` once your adapter knows the real pixel size.
76
+
77
+ ## Caption Quality
78
+
79
+ Length is a weak signal: a caption made entirely of placeholders can pass 40
80
+ characters, and a model can copy the instruction back instead of describing the
81
+ image. `caption_quality` adds three cheap heuristics:
82
+
83
+ ```python
84
+ from mm_preprocess_kit import assess_caption, is_usable
85
+
86
+ assess_caption("REM\n" + "\u25a1\n" * 32).issue # "placeholder"
87
+ assess_caption("transcribe every line... do not summarize").issue # "prompt_echo"
88
+ is_usable("21:30") # True
89
+ ```
90
+
91
+ | Rule | Default | Rejects when |
92
+ | --- | --- | --- |
93
+ | `min_meaningful_chars` | 3 | fewer alphanumeric characters |
94
+ | `placeholder_min_count` / `placeholder_ratio` | 4 / 2.0 | placeholders outnumber meaningful characters by more than 2x |
95
+ | `echo_min_hits` | 2 | two or more instruction phrases are copied back |
96
+
97
+ `assess_caption` returns the verdict plus the counts, so a rejected caption can
98
+ be logged instead of silently dropped. Override `CaptionQualityConfig` to change
99
+ the thresholds or supply the echo phrases of your own prompt.
100
+
101
+ ## Policy Config Table
102
+
103
+ | Field | Default | Meaning |
104
+ | --- | --- | --- |
105
+ | `min_caption_chars` | 40 | Captions shorter than this (after trimming) are treated as missing. |
106
+ | `max_defer_seconds` | 90 | Upper bound on how long a pending message may be deferred. |
107
+ | `long_image_min_edge` | 700 | Long-edge threshold that selects `transcribe`. |
108
+ | `long_image_max_edge` | 1400 | Reserved for caller-side resizing. Not enforced in v0.1. |
109
+ | `long_image_max_tokens` | 900 | Reserved for caller-side budgeting. Not enforced in v0.1. |
110
+ | `allow_thumbnail_fallback` | True | Permit a thumbnail when no local file exists. |
111
+ | `allow_borrow_other_media` | False | Permit borrowing another message's media. Off by default. |
112
+
113
+ `long_image_min_edge` is a long-edge rule, not an area rule: an 800x600 image has a long edge of 800 and therefore selects `transcribe` at the default threshold.
114
+
115
+ ## Design Decisions
116
+
117
+ **No borrowing by default.** A missing image is recoverable; a wrong image is not. Attaching another message's media can silently send someone else's picture, so it requires an explicit opt-in (`allow_borrow_other_media=True`).
118
+
119
+ **Prefer text over blocking.** When the deferral window expires, the message is pushed without media. Waiting longer delays every later message in the queue and produces inconsistent "no image" answers. The caption can still arrive later as a follow-up.
120
+
121
+ **Screenshots stay `auto` until the caller knows the size.** `decide` never learns an item's pixel size and never opens the file, so it returns `caption_mode="auto"`. The adapter resolves it with `choose_caption_mode(width, height, cfg)`.
122
+
123
+ **Where this kit deliberately stops.** A production adapter usually does more than these four functions. The gaps below are intentional, and each one changes how you should wire the kit:
124
+
125
+ - **Failure handling.** A real pipeline often pushes a placeholder ("media could not be described") instead of discarding the item. If yours does, map `caption_status="failed"` to `push_without_media`; reserve `drop_media` for pipelines that intentionally drop the item.
126
+ - **Garbage captions.** `caption_quality` covers the common shapes: placeholder density, prompt echo, and captions too short to be meaningful. A caption can still be wrong in ways these heuristics do not see; treat `is_usable` as a cheap filter, not a guarantee.
127
+ - **Text-heavy gating.** `should_retry_caption` applies to every caption. Production may retry only screenshots or long images; call it only for those kinds instead of unconditionally.
128
+ - **Thumbnail semantics.** `can_use_thumbnail` treats `local_path is None` as "no original is available". If the file exists but cannot be decoded, pass `None` rather than a path that will fail later.
129
+
130
+ This kit gives you the decision vocabulary; the adapter still owns these policy details.
131
+
132
+ ## Test
133
+
134
+ ```bash
135
+ pytest -q
136
+ ```
137
+
138
+ ## Compliance
139
+
140
+ This library contains only generic preprocessing policies. It does not include any platform automation implementation.
141
+
142
+ ## License
143
+
144
+ MIT
@@ -0,0 +1,116 @@
1
+ # multimodal-preprocess-kit
2
+
3
+ [English](https://github.com/AirXsLink/multimodal-preprocess-kit/blob/main/README.md) | [简体中文](https://github.com/AirXsLink/multimodal-preprocess-kit/blob/main/README.zh-CN.md)
4
+
5
+ A framework-agnostic policy kit for chatbot multimodal preprocessing: caption retry, pending-message deferral, caption-mode selection, caption quality checks, and safe fallback.
6
+
7
+ **At a glance (defaults):**
8
+
9
+ | Situation | Decision |
10
+ | --- | --- |
11
+ | Caption `failed` | `drop_media` |
12
+ | Caption `too_short`, or `ready` and under 40 chars | `retry_caption` |
13
+ | Caption `pending`, waited ≤ 90s | `defer` with `retry_after` |
14
+ | Caption `pending`, waited > 90s | `push_without_media` |
15
+ | Caption `ready` and non-empty | `push_now`; screenshots carry `"auto"` |
16
+ | No local file, thumbnails enabled | thumbnail fallback |
17
+ | Media from another message | never borrowed unless explicitly enabled |
18
+
19
+ ## Problem
20
+
21
+ Vision-language captions are often slower than the chat message buffer. A bot may first answer that it cannot see an image, then describe it a second later. Screenshots lose their text when they are summarized instead of transcribed. And when the original media is unavailable, a pipeline may borrow a nearby image, silently attaching the wrong picture to a message.
22
+
23
+ ## What it does NOT do
24
+
25
+ - Calls no model (VL, LLM, or otherwise).
26
+ - Connects to no chat platform and performs no network I/O.
27
+ - Stores no chat history.
28
+ - Reads, decodes, or uploads no media files.
29
+
30
+ ## Install
31
+
32
+ ```bash
33
+ pip install -e .
34
+ ```
35
+
36
+ ## Quick Start
37
+
38
+ ```python
39
+ from mm_preprocess_kit.models import MediaItem, PolicyConfig
40
+ from mm_preprocess_kit.policy import decide
41
+
42
+ media = MediaItem(id="m1", kind="image", caption_status="pending", received_at=0.0)
43
+ decision = decide(media, now=30.0, cfg=PolicyConfig())
44
+ print(decision.action, decision.reason, decision.retry_after) # defer caption_pending 60.0
45
+ ```
46
+
47
+ Screenshots get `caption_mode="auto"`. Resolve it with `choose_caption_mode(width, height, cfg)` once your adapter knows the real pixel size.
48
+
49
+ ## Caption Quality
50
+
51
+ Length is a weak signal: a caption made entirely of placeholders can pass 40
52
+ characters, and a model can copy the instruction back instead of describing the
53
+ image. `caption_quality` adds three cheap heuristics:
54
+
55
+ ```python
56
+ from mm_preprocess_kit import assess_caption, is_usable
57
+
58
+ assess_caption("REM\n" + "\u25a1\n" * 32).issue # "placeholder"
59
+ assess_caption("transcribe every line... do not summarize").issue # "prompt_echo"
60
+ is_usable("21:30") # True
61
+ ```
62
+
63
+ | Rule | Default | Rejects when |
64
+ | --- | --- | --- |
65
+ | `min_meaningful_chars` | 3 | fewer alphanumeric characters |
66
+ | `placeholder_min_count` / `placeholder_ratio` | 4 / 2.0 | placeholders outnumber meaningful characters by more than 2x |
67
+ | `echo_min_hits` | 2 | two or more instruction phrases are copied back |
68
+
69
+ `assess_caption` returns the verdict plus the counts, so a rejected caption can
70
+ be logged instead of silently dropped. Override `CaptionQualityConfig` to change
71
+ the thresholds or supply the echo phrases of your own prompt.
72
+
73
+ ## Policy Config Table
74
+
75
+ | Field | Default | Meaning |
76
+ | --- | --- | --- |
77
+ | `min_caption_chars` | 40 | Captions shorter than this (after trimming) are treated as missing. |
78
+ | `max_defer_seconds` | 90 | Upper bound on how long a pending message may be deferred. |
79
+ | `long_image_min_edge` | 700 | Long-edge threshold that selects `transcribe`. |
80
+ | `long_image_max_edge` | 1400 | Reserved for caller-side resizing. Not enforced in v0.1. |
81
+ | `long_image_max_tokens` | 900 | Reserved for caller-side budgeting. Not enforced in v0.1. |
82
+ | `allow_thumbnail_fallback` | True | Permit a thumbnail when no local file exists. |
83
+ | `allow_borrow_other_media` | False | Permit borrowing another message's media. Off by default. |
84
+
85
+ `long_image_min_edge` is a long-edge rule, not an area rule: an 800x600 image has a long edge of 800 and therefore selects `transcribe` at the default threshold.
86
+
87
+ ## Design Decisions
88
+
89
+ **No borrowing by default.** A missing image is recoverable; a wrong image is not. Attaching another message's media can silently send someone else's picture, so it requires an explicit opt-in (`allow_borrow_other_media=True`).
90
+
91
+ **Prefer text over blocking.** When the deferral window expires, the message is pushed without media. Waiting longer delays every later message in the queue and produces inconsistent "no image" answers. The caption can still arrive later as a follow-up.
92
+
93
+ **Screenshots stay `auto` until the caller knows the size.** `decide` never learns an item's pixel size and never opens the file, so it returns `caption_mode="auto"`. The adapter resolves it with `choose_caption_mode(width, height, cfg)`.
94
+
95
+ **Where this kit deliberately stops.** A production adapter usually does more than these four functions. The gaps below are intentional, and each one changes how you should wire the kit:
96
+
97
+ - **Failure handling.** A real pipeline often pushes a placeholder ("media could not be described") instead of discarding the item. If yours does, map `caption_status="failed"` to `push_without_media`; reserve `drop_media` for pipelines that intentionally drop the item.
98
+ - **Garbage captions.** `caption_quality` covers the common shapes: placeholder density, prompt echo, and captions too short to be meaningful. A caption can still be wrong in ways these heuristics do not see; treat `is_usable` as a cheap filter, not a guarantee.
99
+ - **Text-heavy gating.** `should_retry_caption` applies to every caption. Production may retry only screenshots or long images; call it only for those kinds instead of unconditionally.
100
+ - **Thumbnail semantics.** `can_use_thumbnail` treats `local_path is None` as "no original is available". If the file exists but cannot be decoded, pass `None` rather than a path that will fail later.
101
+
102
+ This kit gives you the decision vocabulary; the adapter still owns these policy details.
103
+
104
+ ## Test
105
+
106
+ ```bash
107
+ pytest -q
108
+ ```
109
+
110
+ ## Compliance
111
+
112
+ This library contains only generic preprocessing policies. It does not include any platform automation implementation.
113
+
114
+ ## License
115
+
116
+ MIT
@@ -0,0 +1,32 @@
1
+ """Policy helpers for chatbot multimodal preprocessing."""
2
+
3
+ from .caption_quality import (
4
+ CaptionAssessment,
5
+ CaptionQualityConfig,
6
+ assess_caption,
7
+ count_meaningful,
8
+ count_placeholders,
9
+ is_usable,
10
+ )
11
+ from .fallback import can_borrow_other_media, can_use_thumbnail
12
+ from .models import Decision, MediaItem, PolicyConfig
13
+ from .policy import choose_caption_mode, decide, should_retry_caption
14
+
15
+ __version__ = "0.2.0"
16
+
17
+ __all__ = [
18
+ "CaptionAssessment",
19
+ "CaptionQualityConfig",
20
+ "Decision",
21
+ "MediaItem",
22
+ "PolicyConfig",
23
+ "assess_caption",
24
+ "can_borrow_other_media",
25
+ "can_use_thumbnail",
26
+ "choose_caption_mode",
27
+ "count_meaningful",
28
+ "count_placeholders",
29
+ "decide",
30
+ "is_usable",
31
+ "should_retry_caption",
32
+ ]
@@ -0,0 +1,139 @@
1
+ """Heuristics for judging whether a caption is usable.
2
+
3
+ Every function here is pure: no model calls, no filesystem, no network. The
4
+ heuristics encode three failure modes observed in production:
5
+
6
+ 1. **placeholder-only captions** - the model writes ``□`` for every glyph it
7
+ cannot read. A length check passes because the placeholder is a character.
8
+ 2. **prompt echo** - the model copies the instruction back instead of
9
+ describing the image.
10
+ 3. **too-short captions** - a text-heavy image gets a caption like ``21:30``.
11
+
12
+ The heuristics are deliberately conservative. Rejecting a good caption costs
13
+ one retry; accepting a bad caption puts garbage into the conversation context,
14
+ where the model then answers based on it.
15
+ """
16
+
17
+ from dataclasses import dataclass, field
18
+ from typing import Optional
19
+
20
+ #: Characters that vision models use for glyphs they cannot read.
21
+ PLACEHOLDER_CHARS = frozenset("□■▢▣◻◼◾▪▫�")
22
+
23
+ #: Instruction phrases that, when copied back, indicate prompt echo.
24
+ #: Defaults cover the Chinese and English transcription prompts this kit was
25
+ #: extracted from; pass your own list for a different prompt.
26
+ DEFAULT_ECHO_PHRASES: tuple[str, ...] = (
27
+ "逐行原样抄写",
28
+ "不要总结",
29
+ "不要漏行",
30
+ "看不清的字用",
31
+ "没有文字就只描述画面",
32
+ "不要逐行抄写",
33
+ "保留换行",
34
+ "直接用一句话说明画面",
35
+ "不要复述要求本身",
36
+ "transcribe every line",
37
+ "do not summarize",
38
+ "do not skip",
39
+ "unreadable characters",
40
+ "keep line breaks",
41
+ )
42
+
43
+
44
+ @dataclass
45
+ class CaptionQualityConfig:
46
+ """Thresholds for the caption-quality heuristics."""
47
+
48
+ #: Captions with fewer meaningful characters are treated as unusable.
49
+ min_meaningful_chars: int = 3
50
+ #: A caption needs at least this many placeholders before density matters.
51
+ placeholder_min_count: int = 4
52
+ #: Placeholders must outnumber meaningful characters by this factor.
53
+ placeholder_ratio: float = 2.0
54
+ #: How many distinct echo phrases count as a prompt echo.
55
+ echo_min_hits: int = 2
56
+ #: Phrases that indicate the model copied the instruction back.
57
+ echo_phrases: tuple[str, ...] = field(default=DEFAULT_ECHO_PHRASES)
58
+
59
+
60
+ @dataclass
61
+ class CaptionAssessment:
62
+ """The result of assessing one caption.
63
+
64
+ ``issue`` is ``None`` when the caption is usable, otherwise one of
65
+ ``"empty"``, ``"too_short"``, ``"placeholder"`` or ``"prompt_echo"``.
66
+ The counts are kept so callers can log *why* a caption was rejected.
67
+ """
68
+
69
+ usable: bool
70
+ issue: Optional[str]
71
+ meaningful_chars: int
72
+ placeholder_chars: int
73
+ echo_hits: int
74
+
75
+
76
+ def count_meaningful(text: Optional[str]) -> int:
77
+ """Count alphanumeric characters, ignoring whitespace and punctuation."""
78
+ if not text:
79
+ return 0
80
+ return sum(1 for char in text if char.isalnum())
81
+
82
+
83
+ def count_placeholders(text: Optional[str]) -> int:
84
+ """Count placeholder glyphs such as ``□``."""
85
+ if not text:
86
+ return 0
87
+ return sum(1 for char in text if char in PLACEHOLDER_CHARS)
88
+
89
+
90
+ def count_echo_hits(text: str, cfg: CaptionQualityConfig) -> int:
91
+ """Count how many distinct echo phrases appear in ``text``."""
92
+ lowered = text.casefold()
93
+ return sum(1 for phrase in cfg.echo_phrases if phrase.casefold() in lowered)
94
+
95
+
96
+ def assess_caption(
97
+ caption: Optional[str], cfg: Optional[CaptionQualityConfig] = None
98
+ ) -> CaptionAssessment:
99
+ """Assess a caption and return the verdict plus its evidence."""
100
+ cfg = cfg or CaptionQualityConfig()
101
+ text = caption or ""
102
+ meaningful = count_meaningful(text)
103
+ placeholders = count_placeholders(text)
104
+ echo_hits = count_echo_hits(text, cfg) if text else 0
105
+
106
+ def verdict(issue: Optional[str]) -> CaptionAssessment:
107
+ return CaptionAssessment(
108
+ usable=issue is None,
109
+ issue=issue,
110
+ meaningful_chars=meaningful,
111
+ placeholder_chars=placeholders,
112
+ echo_hits=echo_hits,
113
+ )
114
+
115
+ if not text.strip():
116
+ return verdict("empty")
117
+
118
+ # A caption made only of placeholders is a placeholder caption, not a
119
+ # short one; report the more specific reason.
120
+ if placeholders >= cfg.placeholder_min_count and meaningful == 0:
121
+ return verdict("placeholder")
122
+
123
+ if meaningful < cfg.min_meaningful_chars:
124
+ return verdict("too_short")
125
+
126
+ if placeholders >= cfg.placeholder_min_count and placeholders > meaningful * cfg.placeholder_ratio:
127
+ return verdict("placeholder")
128
+
129
+ if echo_hits >= cfg.echo_min_hits:
130
+ return verdict("prompt_echo")
131
+
132
+ return verdict(None)
133
+
134
+
135
+ def is_usable(
136
+ caption: Optional[str], cfg: Optional[CaptionQualityConfig] = None
137
+ ) -> bool:
138
+ """Return True when a caption is worth injecting into the context."""
139
+ return assess_caption(caption, cfg).usable
@@ -0,0 +1,22 @@
1
+ """Safe fallback policies for media that cannot be delivered.
2
+
3
+ Both helpers are pure predicates. They never fetch, borrow or decode anything;
4
+ they only tell a caller which fallback is permitted by policy.
5
+ """
6
+
7
+ from .models import MediaItem, PolicyConfig
8
+
9
+
10
+ def can_use_thumbnail(media: MediaItem, cfg: PolicyConfig) -> bool:
11
+ """Return True when no local file exists and thumbnails are allowed."""
12
+ return media.local_path is None and cfg.allow_thumbnail_fallback
13
+
14
+
15
+ def can_borrow_other_media(media: MediaItem, cfg: PolicyConfig) -> bool:
16
+ """Return True only when the caller explicitly opts in to borrowing.
17
+
18
+ Borrowing another message's media is unsafe by default: it can silently
19
+ attach the wrong picture to a message. The default is therefore ``False``
20
+ and must be opted into explicitly.
21
+ """
22
+ return cfg.allow_borrow_other_media is True
@@ -0,0 +1,49 @@
1
+ """Data models for multimodal preprocessing decisions."""
2
+
3
+ from dataclasses import dataclass
4
+ from typing import Literal, Optional
5
+
6
+
7
+ @dataclass
8
+ class MediaItem:
9
+ """One media item as it arrives in a chatbot pipeline.
10
+
11
+ ``local_path`` is metadata only. This library never opens, decodes or
12
+ uploads it; it exists so callers can implement their own fetching layer.
13
+ """
14
+
15
+ id: str
16
+ kind: Literal["image", "sticker", "screenshot"]
17
+ local_path: Optional[str] = None
18
+ caption: Optional[str] = None
19
+ caption_status: Literal["ready", "pending", "failed", "too_short"] = "pending"
20
+ received_at: float = 0.0
21
+ sender_key: Optional[str] = None
22
+
23
+
24
+ @dataclass
25
+ class PolicyConfig:
26
+ """Tunable thresholds for the preprocessing policy.
27
+
28
+ ``long_image_max_edge`` and ``long_image_max_tokens`` are reserved for
29
+ callers that resize or budget images themselves; v0.1 does not enforce
30
+ them because it never decodes an image.
31
+ """
32
+
33
+ min_caption_chars: int = 40
34
+ max_defer_seconds: int = 90
35
+ long_image_min_edge: int = 700
36
+ long_image_max_edge: int = 1400
37
+ long_image_max_tokens: int = 900
38
+ allow_thumbnail_fallback: bool = True
39
+ allow_borrow_other_media: bool = False
40
+
41
+
42
+ @dataclass
43
+ class Decision:
44
+ """The outcome of evaluating one media item."""
45
+
46
+ action: Literal["push_now", "defer", "push_without_media", "retry_caption", "drop_media"]
47
+ reason: str
48
+ retry_after: Optional[float] = None
49
+ caption_mode: Optional[Literal["auto", "transcribe", "describe"]] = None
@@ -0,0 +1,81 @@
1
+ """Decision policies for caption readiness and pending-message deferral.
2
+
3
+ Every function here is pure: no network, no filesystem, no wall clock. Callers
4
+ pass ``now`` in, which keeps decisions reproducible and easy to test.
5
+ """
6
+
7
+ from typing import Literal, Optional
8
+
9
+ from .models import Decision, MediaItem, PolicyConfig
10
+
11
+
12
+ def should_retry_caption(caption: Optional[str], cfg: PolicyConfig) -> bool:
13
+ """Return True when a caption is missing or shorter than the threshold."""
14
+ if caption is None:
15
+ return True
16
+ return len(caption.strip()) < cfg.min_caption_chars
17
+
18
+
19
+ def choose_caption_mode(
20
+ width: int, height: int, cfg: PolicyConfig
21
+ ) -> Literal["auto", "transcribe", "describe"]:
22
+ """Pick a caption mode for a screenshot of the given pixel size.
23
+
24
+ Long images are transcribed line by line; everything else is described.
25
+ ``"auto"`` is never returned here; it is a pass-through value only.
26
+ """
27
+ if max(width, height) >= cfg.long_image_min_edge:
28
+ return "transcribe"
29
+ return "describe"
30
+
31
+
32
+ def decide(media: MediaItem, now: float, cfg: PolicyConfig) -> Decision:
33
+ """Decide what to do with one media item at time ``now``.
34
+
35
+ ``now`` and ``media.received_at`` are floats in the same unit (seconds).
36
+
37
+ Resolution order, gated by caption status so that a short or missing
38
+ caption cannot shadow the deferral or failure branches:
39
+
40
+ 1. ``failed`` -> ``drop_media``
41
+ 2. ``too_short`` -> ``retry_caption``
42
+ 3. ``ready`` + short -> ``retry_caption``
43
+ 4. ``pending``, in time -> ``defer``
44
+ 5. ``pending``, too late -> ``push_without_media``
45
+ 6. ``ready``, non-empty -> ``push_now``
46
+ 7. anything else -> ``push_without_media`` (``unknown_state``)
47
+
48
+ A screenshot gets ``caption_mode="auto"`` because this module never learns
49
+ an item's pixel size; the caller resolves ``"auto"`` with
50
+ :func:`choose_caption_mode` once the real width and height are known.
51
+ """
52
+ status = media.caption_status
53
+
54
+ if status == "failed":
55
+ return Decision(action="drop_media", reason="caption_failed")
56
+
57
+ if status == "too_short":
58
+ return Decision(action="retry_caption", reason="caption_too_short")
59
+
60
+ if status == "ready" and should_retry_caption(media.caption, cfg):
61
+ return Decision(action="retry_caption", reason="caption_too_short")
62
+
63
+ if status == "pending":
64
+ # Clamp negative waits (a non-monotonic ``now``) to zero so that a
65
+ # clock jump cannot produce a deferral longer than the configured cap.
66
+ waited = max(0.0, now - media.received_at)
67
+ if waited < cfg.max_defer_seconds:
68
+ return Decision(
69
+ action="defer",
70
+ reason="caption_pending",
71
+ retry_after=cfg.max_defer_seconds - waited,
72
+ )
73
+ return Decision(action="push_without_media", reason="caption_timeout")
74
+
75
+ if status == "ready" and media.caption:
76
+ caption_mode: Optional[Literal["auto", "transcribe", "describe"]] = (
77
+ "auto" if media.kind == "screenshot" else None
78
+ )
79
+ return Decision(action="push_now", reason="caption_ready", caption_mode=caption_mode)
80
+
81
+ return Decision(action="push_without_media", reason="unknown_state")
@@ -0,0 +1,144 @@
1
+ Metadata-Version: 2.4
2
+ Name: multimodal-preprocess-kit
3
+ Version: 0.2.0
4
+ Summary: A framework-agnostic policy kit for chatbot multimodal preprocessing: caption retry, pending-message deferral, caption-mode selection, caption quality checks, and safe fallback.
5
+ Author: multimodal-preprocess-kit contributors
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/AirXsLink/multimodal-preprocess-kit
8
+ Project-URL: Repository, https://github.com/AirXsLink/multimodal-preprocess-kit
9
+ Project-URL: Issues, https://github.com/AirXsLink/multimodal-preprocess-kit/issues
10
+ Project-URL: Changelog, https://github.com/AirXsLink/multimodal-preprocess-kit/blob/main/CHANGELOG.md
11
+ Keywords: chatbot,multimodal,preprocessing,policy,fallback
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: License :: OSI Approved :: MIT License
20
+ Classifier: Operating System :: OS Independent
21
+ Classifier: Typing :: Typed
22
+ Requires-Python: >=3.11
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Provides-Extra: test
26
+ Requires-Dist: pytest>=8; extra == "test"
27
+ Dynamic: license-file
28
+
29
+ # multimodal-preprocess-kit
30
+
31
+ [English](https://github.com/AirXsLink/multimodal-preprocess-kit/blob/main/README.md) | [简体中文](https://github.com/AirXsLink/multimodal-preprocess-kit/blob/main/README.zh-CN.md)
32
+
33
+ A framework-agnostic policy kit for chatbot multimodal preprocessing: caption retry, pending-message deferral, caption-mode selection, caption quality checks, and safe fallback.
34
+
35
+ **At a glance (defaults):**
36
+
37
+ | Situation | Decision |
38
+ | --- | --- |
39
+ | Caption `failed` | `drop_media` |
40
+ | Caption `too_short`, or `ready` and under 40 chars | `retry_caption` |
41
+ | Caption `pending`, waited ≤ 90s | `defer` with `retry_after` |
42
+ | Caption `pending`, waited > 90s | `push_without_media` |
43
+ | Caption `ready` and non-empty | `push_now`; screenshots carry `"auto"` |
44
+ | No local file, thumbnails enabled | thumbnail fallback |
45
+ | Media from another message | never borrowed unless explicitly enabled |
46
+
47
+ ## Problem
48
+
49
+ Vision-language captions are often slower than the chat message buffer. A bot may first answer that it cannot see an image, then describe it a second later. Screenshots lose their text when they are summarized instead of transcribed. And when the original media is unavailable, a pipeline may borrow a nearby image, silently attaching the wrong picture to a message.
50
+
51
+ ## What it does NOT do
52
+
53
+ - Calls no model (VL, LLM, or otherwise).
54
+ - Connects to no chat platform and performs no network I/O.
55
+ - Stores no chat history.
56
+ - Reads, decodes, or uploads no media files.
57
+
58
+ ## Install
59
+
60
+ ```bash
61
+ pip install -e .
62
+ ```
63
+
64
+ ## Quick Start
65
+
66
+ ```python
67
+ from mm_preprocess_kit.models import MediaItem, PolicyConfig
68
+ from mm_preprocess_kit.policy import decide
69
+
70
+ media = MediaItem(id="m1", kind="image", caption_status="pending", received_at=0.0)
71
+ decision = decide(media, now=30.0, cfg=PolicyConfig())
72
+ print(decision.action, decision.reason, decision.retry_after) # defer caption_pending 60.0
73
+ ```
74
+
75
+ Screenshots get `caption_mode="auto"`. Resolve it with `choose_caption_mode(width, height, cfg)` once your adapter knows the real pixel size.
76
+
77
+ ## Caption Quality
78
+
79
+ Length is a weak signal: a caption made entirely of placeholders can pass 40
80
+ characters, and a model can copy the instruction back instead of describing the
81
+ image. `caption_quality` adds three cheap heuristics:
82
+
83
+ ```python
84
+ from mm_preprocess_kit import assess_caption, is_usable
85
+
86
+ assess_caption("REM\n" + "\u25a1\n" * 32).issue # "placeholder"
87
+ assess_caption("transcribe every line... do not summarize").issue # "prompt_echo"
88
+ is_usable("21:30") # True
89
+ ```
90
+
91
+ | Rule | Default | Rejects when |
92
+ | --- | --- | --- |
93
+ | `min_meaningful_chars` | 3 | fewer alphanumeric characters |
94
+ | `placeholder_min_count` / `placeholder_ratio` | 4 / 2.0 | placeholders outnumber meaningful characters by more than 2x |
95
+ | `echo_min_hits` | 2 | two or more instruction phrases are copied back |
96
+
97
+ `assess_caption` returns the verdict plus the counts, so a rejected caption can
98
+ be logged instead of silently dropped. Override `CaptionQualityConfig` to change
99
+ the thresholds or supply the echo phrases of your own prompt.
100
+
101
+ ## Policy Config Table
102
+
103
+ | Field | Default | Meaning |
104
+ | --- | --- | --- |
105
+ | `min_caption_chars` | 40 | Captions shorter than this (after trimming) are treated as missing. |
106
+ | `max_defer_seconds` | 90 | Upper bound on how long a pending message may be deferred. |
107
+ | `long_image_min_edge` | 700 | Long-edge threshold that selects `transcribe`. |
108
+ | `long_image_max_edge` | 1400 | Reserved for caller-side resizing. Not enforced in v0.1. |
109
+ | `long_image_max_tokens` | 900 | Reserved for caller-side budgeting. Not enforced in v0.1. |
110
+ | `allow_thumbnail_fallback` | True | Permit a thumbnail when no local file exists. |
111
+ | `allow_borrow_other_media` | False | Permit borrowing another message's media. Off by default. |
112
+
113
+ `long_image_min_edge` is a long-edge rule, not an area rule: an 800x600 image has a long edge of 800 and therefore selects `transcribe` at the default threshold.
114
+
115
+ ## Design Decisions
116
+
117
+ **No borrowing by default.** A missing image is recoverable; a wrong image is not. Attaching another message's media can silently send someone else's picture, so it requires an explicit opt-in (`allow_borrow_other_media=True`).
118
+
119
+ **Prefer text over blocking.** When the deferral window expires, the message is pushed without media. Waiting longer delays every later message in the queue and produces inconsistent "no image" answers. The caption can still arrive later as a follow-up.
120
+
121
+ **Screenshots stay `auto` until the caller knows the size.** `decide` never learns an item's pixel size and never opens the file, so it returns `caption_mode="auto"`. The adapter resolves it with `choose_caption_mode(width, height, cfg)`.
122
+
123
+ **Where this kit deliberately stops.** A production adapter usually does more than these four functions. The gaps below are intentional, and each one changes how you should wire the kit:
124
+
125
+ - **Failure handling.** A real pipeline often pushes a placeholder ("media could not be described") instead of discarding the item. If yours does, map `caption_status="failed"` to `push_without_media`; reserve `drop_media` for pipelines that intentionally drop the item.
126
+ - **Garbage captions.** `caption_quality` covers the common shapes: placeholder density, prompt echo, and captions too short to be meaningful. A caption can still be wrong in ways these heuristics do not see; treat `is_usable` as a cheap filter, not a guarantee.
127
+ - **Text-heavy gating.** `should_retry_caption` applies to every caption. Production may retry only screenshots or long images; call it only for those kinds instead of unconditionally.
128
+ - **Thumbnail semantics.** `can_use_thumbnail` treats `local_path is None` as "no original is available". If the file exists but cannot be decoded, pass `None` rather than a path that will fail later.
129
+
130
+ This kit gives you the decision vocabulary; the adapter still owns these policy details.
131
+
132
+ ## Test
133
+
134
+ ```bash
135
+ pytest -q
136
+ ```
137
+
138
+ ## Compliance
139
+
140
+ This library contains only generic preprocessing policies. It does not include any platform automation implementation.
141
+
142
+ ## License
143
+
144
+ MIT
@@ -0,0 +1,21 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ mm_preprocess_kit/__init__.py
5
+ mm_preprocess_kit/caption_quality.py
6
+ mm_preprocess_kit/fallback.py
7
+ mm_preprocess_kit/models.py
8
+ mm_preprocess_kit/policy.py
9
+ mm_preprocess_kit/py.typed
10
+ multimodal_preprocess_kit.egg-info/PKG-INFO
11
+ multimodal_preprocess_kit.egg-info/SOURCES.txt
12
+ multimodal_preprocess_kit.egg-info/dependency_links.txt
13
+ multimodal_preprocess_kit.egg-info/requires.txt
14
+ multimodal_preprocess_kit.egg-info/top_level.txt
15
+ tests/test_caption_mode.py
16
+ tests/test_caption_quality.py
17
+ tests/test_decide_actions.py
18
+ tests/test_defer.py
19
+ tests/test_fallback.py
20
+ tests/test_no_borrow.py
21
+ tests/test_retry.py
@@ -0,0 +1,44 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "multimodal-preprocess-kit"
7
+ version = "0.2.0"
8
+ description = "A framework-agnostic policy kit for chatbot multimodal preprocessing: caption retry, pending-message deferral, caption-mode selection, caption quality checks, and safe fallback."
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = { text = "MIT" }
12
+ authors = [{ name = "multimodal-preprocess-kit contributors" }]
13
+ keywords = ["chatbot", "multimodal", "preprocessing", "policy", "fallback"]
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Intended Audience :: Developers",
17
+ "Programming Language :: Python :: 3",
18
+ "Programming Language :: Python :: 3.11",
19
+ "Programming Language :: Python :: 3.11",
20
+ "Programming Language :: Python :: 3.12",
21
+ "Programming Language :: Python :: 3.13",
22
+ "License :: OSI Approved :: MIT License",
23
+ "Operating System :: OS Independent",
24
+ "Typing :: Typed",
25
+ ]
26
+ dependencies = []
27
+
28
+ [project.urls]
29
+ Homepage = "https://github.com/AirXsLink/multimodal-preprocess-kit"
30
+ Repository = "https://github.com/AirXsLink/multimodal-preprocess-kit"
31
+ Issues = "https://github.com/AirXsLink/multimodal-preprocess-kit/issues"
32
+ Changelog = "https://github.com/AirXsLink/multimodal-preprocess-kit/blob/main/CHANGELOG.md"
33
+
34
+ [project.optional-dependencies]
35
+ test = ["pytest>=8"]
36
+
37
+ [tool.setuptools.packages.find]
38
+ include = ["mm_preprocess_kit*"]
39
+
40
+ [tool.setuptools.package-data]
41
+ mm_preprocess_kit = ["py.typed"]
42
+
43
+ [tool.pytest.ini_options]
44
+ testpaths = ["tests"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,24 @@
1
+ """Caption mode selection tests."""
2
+
3
+ from mm_preprocess_kit.models import PolicyConfig
4
+ from mm_preprocess_kit.policy import choose_caption_mode
5
+
6
+
7
+ def test_tall_screenshot_uses_transcribe() -> None:
8
+ assert choose_caption_mode(1200, 3000, PolicyConfig()) == "transcribe"
9
+
10
+
11
+ def test_small_image_uses_describe() -> None:
12
+ # The default threshold (700) would classify 800x600 as transcribe because
13
+ # its long edge is 800. Raise the threshold here so the describe branch is
14
+ # exercised under the documented long-edge rule.
15
+ cfg = PolicyConfig(long_image_min_edge=1000)
16
+ assert choose_caption_mode(800, 600, cfg) == "describe"
17
+
18
+
19
+ def test_boundary_at_threshold_is_transcribe() -> None:
20
+ assert choose_caption_mode(700, 400, PolicyConfig()) == "transcribe"
21
+
22
+
23
+ def test_below_threshold_is_describe() -> None:
24
+ assert choose_caption_mode(699, 400, PolicyConfig()) == "describe"
@@ -0,0 +1,102 @@
1
+ """Caption quality heuristics: real misfires and their negative examples."""
2
+
3
+ from mm_preprocess_kit.caption_quality import (
4
+ CaptionQualityConfig,
5
+ assess_caption,
6
+ count_meaningful,
7
+ count_placeholders,
8
+ is_usable,
9
+ )
10
+
11
+ # A real caption: the model read the drum-brand logo ("REM") and produced a
12
+ # placeholder for every other line.
13
+ PLACEHOLDER_CAPTION = "REM\n" + "\u25a1\n" * 32
14
+
15
+ # A real miss: the model copied the transcription instruction back.
16
+ PROMPT_ECHO_CAPTION = (
17
+ "\u8fd9\u662f\u4e00\u5f20\u53ef\u80fd\u5305\u542b\u6587\u5b57\u7684\u56fe"
18
+ "\uff08\u622a\u56fe/\u7167\u7247\uff09\u3002\u8bf7\u5148\u9010\u884c\u539f"
19
+ "\u6837\u6284\u5199\u56fe\u4e2d\u6240\u6709\u53ef\u89c1\u6587\u5b57\uff0c"
20
+ "\u4fdd\u7559\u6362\u884c\uff0c\u4e0d\u8981\u603b\u7ed3\u3001\u4e0d\u8981\u6f0f"
21
+ "\u884c\uff1b\u770b\u4e0d\u6e05\u7684\u5b57\u7528 \u25a1 \u4ee3\u66ff\u3002"
22
+ )
23
+
24
+
25
+ def test_empty_caption_is_empty() -> None:
26
+ assert assess_caption("").issue == "empty"
27
+ assert is_usable("") is False
28
+
29
+
30
+ def test_whitespace_caption_is_empty() -> None:
31
+ assert assess_caption(" \n\t").issue == "empty"
32
+
33
+
34
+ def test_placeholder_only_caption_is_placeholder() -> None:
35
+ assert assess_caption("\u25a1" * 4).issue == "placeholder"
36
+
37
+
38
+ def test_placeholder_density_rejects_a_real_caption() -> None:
39
+ assessment = assess_caption(PLACEHOLDER_CAPTION)
40
+ assert assessment.usable is False
41
+ assert assessment.issue == "placeholder"
42
+ assert assessment.meaningful_chars == 3
43
+ assert assessment.placeholder_chars == 32
44
+
45
+
46
+ def test_single_placeholder_is_too_short() -> None:
47
+ assert assess_caption("\u25a1").issue == "too_short"
48
+
49
+
50
+ def test_one_character_caption_is_too_short() -> None:
51
+ assert assess_caption("\u95e8").issue == "too_short"
52
+
53
+
54
+ def test_clock_caption_is_usable() -> None:
55
+ # "21:30" is short but has four alphanumeric characters; the length-retry
56
+ # policy (min_caption_chars) is a separate layer.
57
+ assert is_usable("21:30") is True
58
+
59
+
60
+ def test_normal_chinese_caption_is_usable() -> None:
61
+ assert is_usable("\u8fd9\u662f\u4e00\u5f20\u96ea\u666f\u7167\u7247\uff0c\u6811\u6728\u8986\u76d6\u7740\u767d\u96ea\u3002") is True
62
+
63
+
64
+ def test_prompt_echo_is_rejected() -> None:
65
+ assessment = assess_caption(PROMPT_ECHO_CAPTION)
66
+ assert assessment.usable is False
67
+ assert assessment.issue == "prompt_echo"
68
+ assert assessment.echo_hits >= 2
69
+
70
+
71
+ def test_single_echo_phrase_is_not_rejected() -> None:
72
+ # A single phrase may legitimately appear in the image itself.
73
+ assert is_usable("\u8bf7\u5148\u9010\u884c\u539f\u6837\u6284\u5199") is True
74
+
75
+
76
+ def test_english_prompt_echo_is_rejected() -> None:
77
+ caption = "Transcribe every line exactly. Do not summarize. Keep line breaks."
78
+ assert assess_caption(caption).issue == "prompt_echo"
79
+
80
+
81
+ def test_assessment_reports_evidence() -> None:
82
+ assessment = assess_caption(PLACEHOLDER_CAPTION)
83
+ assert assessment.meaningful_chars == 3
84
+ assert assessment.placeholder_chars == 32
85
+ assert assessment.echo_hits == 0
86
+
87
+
88
+ def test_custom_echo_phrases() -> None:
89
+ cfg = CaptionQualityConfig(echo_phrases=("foo", "bar"))
90
+ assert assess_caption("foo bar", cfg).issue == "prompt_echo"
91
+ assert assess_caption("foo only", cfg).usable is True
92
+
93
+
94
+ def test_few_placeholders_below_ratio_is_usable() -> None:
95
+ # "REM" plus four placeholders: 4 is not greater than 3 * 2.
96
+ caption = "REM\n" + "\u25a1\n" * 4
97
+ assert is_usable(caption) is True
98
+
99
+
100
+ def test_counts_ignore_punctuation() -> None:
101
+ assert count_meaningful("\u4f60\u597d\uff0c\u4e16\u754c\uff01") == 4
102
+ assert count_placeholders("\u25a1\u25a0\u25a1") == 3
@@ -0,0 +1,49 @@
1
+ """Decision actions: every branch of ``decide`` gets an assertion."""
2
+
3
+ from mm_preprocess_kit.models import MediaItem, PolicyConfig
4
+ from mm_preprocess_kit.policy import decide
5
+
6
+
7
+ def test_failed_drops_media() -> None:
8
+ media = MediaItem(id="m", kind="image", caption_status="failed")
9
+ decision = decide(media, now=0.0, cfg=PolicyConfig())
10
+ assert decision.action == "drop_media"
11
+ assert decision.reason == "caption_failed"
12
+
13
+
14
+ def test_too_short_retries() -> None:
15
+ media = MediaItem(id="m", kind="image", caption_status="too_short")
16
+ decision = decide(media, now=0.0, cfg=PolicyConfig())
17
+ assert decision.action == "retry_caption"
18
+ assert decision.reason == "caption_too_short"
19
+
20
+
21
+ def test_ready_short_caption_retries() -> None:
22
+ media = MediaItem(id="m", kind="image", caption_status="ready", caption="x" * 10)
23
+ decision = decide(media, now=0.0, cfg=PolicyConfig())
24
+ assert decision.action == "retry_caption"
25
+ assert decision.reason == "caption_too_short"
26
+
27
+
28
+ def test_ready_caption_pushes_now() -> None:
29
+ media = MediaItem(id="m", kind="image", caption_status="ready", caption="x" * 60)
30
+ decision = decide(media, now=0.0, cfg=PolicyConfig())
31
+ assert decision.action == "push_now"
32
+ assert decision.reason == "caption_ready"
33
+ assert decision.caption_mode is None
34
+
35
+
36
+ def test_screenshot_carries_auto_mode() -> None:
37
+ media = MediaItem(
38
+ id="m", kind="screenshot", caption_status="ready", caption="x" * 60
39
+ )
40
+ decision = decide(media, now=0.0, cfg=PolicyConfig())
41
+ assert decision.action == "push_now"
42
+ assert decision.caption_mode == "auto"
43
+
44
+
45
+ def test_unknown_state_pushes_without_media() -> None:
46
+ media = MediaItem(id="m", kind="image", caption_status="bogus") # type: ignore[arg-type]
47
+ decision = decide(media, now=0.0, cfg=PolicyConfig())
48
+ assert decision.action == "push_without_media"
49
+ assert decision.reason == "unknown_state"
@@ -0,0 +1,37 @@
1
+ """Pending-message deferral tests."""
2
+
3
+ import pytest
4
+
5
+ from mm_preprocess_kit.models import MediaItem, PolicyConfig
6
+ from mm_preprocess_kit.policy import decide
7
+
8
+
9
+ def test_pending_within_window_defers() -> None:
10
+ media = MediaItem(id="m1", kind="image", caption_status="pending", received_at=100.0)
11
+ decision = decide(media, now=130.0, cfg=PolicyConfig())
12
+ assert decision.action == "defer"
13
+ assert decision.reason == "caption_pending"
14
+ assert decision.retry_after == pytest.approx(60.0)
15
+
16
+
17
+ def test_pending_past_window_pushes_without_media() -> None:
18
+ media = MediaItem(id="m2", kind="image", caption_status="pending", received_at=0.0)
19
+ decision = decide(media, now=100.0, cfg=PolicyConfig())
20
+ assert decision.action == "push_without_media"
21
+ assert decision.reason == "caption_timeout"
22
+
23
+
24
+ def test_pending_at_exact_deadline_times_out() -> None:
25
+ # Boundary: waiting exactly max_defer_seconds is a timeout, not a
26
+ # deferral with retry_after=0.0.
27
+ media = MediaItem(id="m3", kind="image", caption_status="pending", received_at=0.0)
28
+ decision = decide(media, now=90.0, cfg=PolicyConfig())
29
+ assert decision.action == "push_without_media"
30
+ assert decision.reason == "caption_timeout"
31
+
32
+
33
+ def test_non_monotonic_clock_is_clamped() -> None:
34
+ media = MediaItem(id="m4", kind="image", caption_status="pending", received_at=100.0)
35
+ decision = decide(media, now=50.0, cfg=PolicyConfig())
36
+ assert decision.action == "defer"
37
+ assert decision.retry_after == pytest.approx(90.0)
@@ -0,0 +1,19 @@
1
+ """Thumbnail and borrow fallback tests."""
2
+
3
+ from mm_preprocess_kit.fallback import can_borrow_other_media, can_use_thumbnail
4
+ from mm_preprocess_kit.models import MediaItem, PolicyConfig
5
+
6
+
7
+ def test_missing_local_path_allows_thumbnail() -> None:
8
+ media = MediaItem(id="img", kind="image", local_path=None)
9
+ assert can_use_thumbnail(media, PolicyConfig(allow_thumbnail_fallback=True)) is True
10
+
11
+
12
+ def test_thumbnail_fallback_can_be_disabled() -> None:
13
+ media = MediaItem(id="img", kind="image", local_path=None)
14
+ assert can_use_thumbnail(media, PolicyConfig(allow_thumbnail_fallback=False)) is False
15
+
16
+
17
+ def test_borrow_can_be_opted_in() -> None:
18
+ media = MediaItem(id="img", kind="image")
19
+ assert can_borrow_other_media(media, PolicyConfig(allow_borrow_other_media=True)) is True
@@ -0,0 +1,9 @@
1
+ """Default no-borrow policy tests."""
2
+
3
+ from mm_preprocess_kit.fallback import can_borrow_other_media
4
+ from mm_preprocess_kit.models import MediaItem, PolicyConfig
5
+
6
+
7
+ def test_borrow_is_disabled_by_default() -> None:
8
+ media = MediaItem(id="img", kind="image")
9
+ assert can_borrow_other_media(media, PolicyConfig()) is False
@@ -0,0 +1,12 @@
1
+ """Caption retry threshold tests."""
2
+
3
+ from mm_preprocess_kit.models import PolicyConfig
4
+ from mm_preprocess_kit.policy import should_retry_caption
5
+
6
+
7
+ def test_short_caption_needs_retry() -> None:
8
+ assert should_retry_caption("x" * 35, PolicyConfig()) is True
9
+
10
+
11
+ def test_long_caption_does_not_need_retry() -> None:
12
+ assert should_retry_caption("x" * 50, PolicyConfig()) is False