kd-engine 1.0.0__py3-none-any.whl

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 (118) hide show
  1. kd_engine-1.0.0.dist-info/METADATA +19 -0
  2. kd_engine-1.0.0.dist-info/RECORD +118 -0
  3. kd_engine-1.0.0.dist-info/WHEEL +5 -0
  4. kd_engine-1.0.0.dist-info/entry_points.txt +2 -0
  5. kd_engine-1.0.0.dist-info/licenses/LICENSE-MIT +21 -0
  6. kd_engine-1.0.0.dist-info/top_level.txt +1 -0
  7. ytk/__init__.py +2 -0
  8. ytk/__main__.py +21 -0
  9. ytk/batch/__init__.py +39 -0
  10. ytk/batch/runner.py +1149 -0
  11. ytk/cache/__init__.py +34 -0
  12. ytk/cache/v2.py +562 -0
  13. ytk/cleaning/density.py +40 -0
  14. ytk/cleaning/fillers.py +18 -0
  15. ytk/cleaning/sentence_boundary.py +30 -0
  16. ytk/cleaning/service.py +62 -0
  17. ytk/cli.py +1281 -0
  18. ytk/commands/__init__.py +3 -0
  19. ytk/commands/merge.py +600 -0
  20. ytk/config.py +757 -0
  21. ytk/dedup/service.py +166 -0
  22. ytk/doctor.py +891 -0
  23. ytk/dotenv.py +334 -0
  24. ytk/errors.py +38 -0
  25. ytk/extraction/service.py +451 -0
  26. ytk/extraction/strategies/base.py +16 -0
  27. ytk/extraction/strategies/code_block.py +285 -0
  28. ytk/extraction/strategies/heuristic.py +791 -0
  29. ytk/extraction/strategies/local_model.py +56 -0
  30. ytk/extraction/text_context.py +177 -0
  31. ytk/extraction/visual_context.py +159 -0
  32. ytk/ingestion/adapters/__init__.py +1 -0
  33. ytk/ingestion/adapters/_common.py +865 -0
  34. ytk/ingestion/adapters/base.py +160 -0
  35. ytk/ingestion/adapters/bilibili.py +271 -0
  36. ytk/ingestion/adapters/douyin.py +445 -0
  37. ytk/ingestion/adapters/tiktok.py +102 -0
  38. ytk/ingestion/adapters/xiaohongshu.py +758 -0
  39. ytk/ingestion/adapters/youtube.py +74 -0
  40. ytk/ingestion/browser_acquired.py +220 -0
  41. ytk/ingestion/http_client.py +43 -0
  42. ytk/ingestion/local_import.py +202 -0
  43. ytk/ingestion/media.py +468 -0
  44. ytk/ingestion/providers/asr.py +902 -0
  45. ytk/ingestion/providers/base.py +13 -0
  46. ytk/ingestion/providers/dtk_client.py +816 -0
  47. ytk/ingestion/providers/minimax.py +350 -0
  48. ytk/ingestion/providers/transcript_api.py +336 -0
  49. ytk/ingestion/providers/xhs_client.py +646 -0
  50. ytk/ingestion/providers/ytdlp.py +400 -0
  51. ytk/ingestion/registry.py +189 -0
  52. ytk/ingestion/resolver.py +417 -0
  53. ytk/ingestion/search.py +56 -0
  54. ytk/ingestion/service.py +167 -0
  55. ytk/ingestion/subtitles.py +602 -0
  56. ytk/ingestion/transcript_cache.py +212 -0
  57. ytk/ingestion/url_parser.py +53 -0
  58. ytk/ingestion/video_frames.py +292 -0
  59. ytk/ingestion/ytdlp_acquire.py +754 -0
  60. ytk/logging.py +383 -0
  61. ytk/models/common.py +20 -0
  62. ytk/models/content.py +451 -0
  63. ytk/models/knowledge.py +43 -0
  64. ytk/models/migrations.py +262 -0
  65. ytk/models/skill.py +13 -0
  66. ytk/models/source.py +265 -0
  67. ytk/models/topic.py +18 -0
  68. ytk/models/transcript.py +30 -0
  69. ytk/ocr/__init__.py +65 -0
  70. ytk/ocr/engine.py +245 -0
  71. ytk/ocr/layout.py +347 -0
  72. ytk/ocr/pipeline.py +440 -0
  73. ytk/ocr/rapidocr_engine.py +144 -0
  74. ytk/pipeline/acquisition_checkpoint.py +240 -0
  75. ytk/pipeline/artifacts.py +18 -0
  76. ytk/pipeline/orchestrator.py +598 -0
  77. ytk/pipeline/processing_identity.py +18 -0
  78. ytk/pipeline/retry.py +728 -0
  79. ytk/pipeline/runners.py +578 -0
  80. ytk/pipeline/state.py +1107 -0
  81. ytk/pipeline/v2.py +1863 -0
  82. ytk/py.typed +1 -0
  83. ytk/quality/__init__.py +9 -0
  84. ytk/quality/completeness.py +260 -0
  85. ytk/renderers/base.py +9 -0
  86. ytk/renderers/citation_alignment.py +617 -0
  87. ytk/renderers/evidence_formatter.py +362 -0
  88. ytk/renderers/json_renderer.py +13 -0
  89. ytk/renderers/jsonl_renderer.py +18 -0
  90. ytk/renderers/knowledge_doc_renderer.py +1984 -0
  91. ytk/renderers/markdown_renderer.py +540 -0
  92. ytk/renderers/obsidian_renderer.py +138 -0
  93. ytk/renderers/skill_package.py +21 -0
  94. ytk/renderers/source_links.py +309 -0
  95. ytk/renderers/summary_renderer.py +163 -0
  96. ytk/renderers/v2.py +171 -0
  97. ytk/renderers/v2_jsonl.py +165 -0
  98. ytk/renderers/v2_markdown.py +477 -0
  99. ytk/renderers/v2_obsidian.py +113 -0
  100. ytk/renderers/v2_summary.py +220 -0
  101. ytk/segmentation/change_points.py +50 -0
  102. ytk/segmentation/embeddings.py +45 -0
  103. ytk/segmentation/service.py +318 -0
  104. ytk/skill_builder/__init__.py +1 -0
  105. ytk/skill_builder/builder.py +419 -0
  106. ytk/skill_builder/templates/SKILL.md.j2 +85 -0
  107. ytk/skill_builder/templates/evals/evals.json.j2 +25 -0
  108. ytk/skill_builder/templates/examples/example-input.md.j2 +5 -0
  109. ytk/skill_builder/templates/examples/example-output.md.j2 +8 -0
  110. ytk/skill_builder/templates/references/commands.md.j2 +34 -0
  111. ytk/skill_builder/templates/references/concepts.md.j2 +22 -0
  112. ytk/skill_builder/templates/references/configs.md.j2 +31 -0
  113. ytk/skill_builder/templates/references/evidence-policy.md.j2 +27 -0
  114. ytk/skill_builder/templates/references/source-summary.md.j2 +24 -0
  115. ytk/skill_builder/templates/scripts/build_skill.py.j2 +14 -0
  116. ytk/skill_builder/templates/scripts/validate_output.py.j2 +136 -0
  117. ytk/skill_builder/templates.py +29 -0
  118. ytk/text_normalization.py +44 -0
ytk/ocr/pipeline.py ADDED
@@ -0,0 +1,440 @@
1
+ """T32.1 / T32.2 — OCR enrichment: image evidence and budget-bound frame evidence.
2
+
3
+ :func:`run_ocr_for_content` walks the image assets of a content bundle in the
4
+ post's original order, OCRs each one (tiling long images through
5
+ :mod:`ytk.ocr.layout`) and returns ``ContentBlock`` objects with
6
+ ``ImageRegionLocator`` evidence in ORIGINAL image pixels. An image-note block
7
+ never carries a time locator (A22), and one failed image yields the successful
8
+ blocks plus a diagnostic — never a crash and never invented text.
9
+
10
+ :func:`run_ocr_for_frames` is the T32.2 path: it consumes the frame list that
11
+ the media service already sampled and applies a hard budget (max frames, minimum
12
+ spacing, per-frame and total pixel ceilings) before any recognition work. It
13
+ never re-acquires media, so an existing audio/ASR path is never re-downloaded
14
+ merely because frame OCR is enabled. Recognised frames become
15
+ ``VideoFrameLocator`` blocks with the frame time in seconds; consecutive
16
+ near-identical frames (same slide) are de-duplicated.
17
+
18
+ Block ``order`` always continues after the blocks already present in the bundle.
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import hashlib
24
+ import json
25
+ import logging
26
+ import math
27
+ from collections.abc import Mapping, Sequence
28
+ from dataclasses import asdict, dataclass, fields
29
+ from importlib.metadata import PackageNotFoundError, version
30
+ from pathlib import Path
31
+ from typing import Any
32
+
33
+ from pydantic import TypeAdapter
34
+
35
+ from ytk.cache.v2 import LayeredCache
36
+ from ytk.models.content import (
37
+ ContentBlock,
38
+ ContentBundle,
39
+ ImageRegionLocator,
40
+ VideoFrameLocator,
41
+ make_block_id,
42
+ )
43
+ from ytk.ocr.engine import ModelPaths, OCREngine, OCRLine, get_engine
44
+ from ytk.ocr.layout import (
45
+ LongImageResult,
46
+ Tile,
47
+ TileBudget,
48
+ normalize_text,
49
+ ocr_long_image,
50
+ plan_tiles,
51
+ text_similarity,
52
+ )
53
+
54
+ LOGGER = logging.getLogger(__name__)
55
+ _OCR_RESULT_ADAPTER = TypeAdapter(LongImageResult)
56
+
57
+ DEFAULT_MAX_FRAMES = 12
58
+ DEFAULT_MIN_FRAME_INTERVAL_S = 1.0
59
+ DEFAULT_MAX_FRAME_PIXELS = 4_000_000
60
+ DEFAULT_MAX_TOTAL_FRAME_PIXELS = 24_000_000
61
+ DEFAULT_FRAME_DUPLICATE_SIMILARITY = 0.9
62
+
63
+
64
+ @dataclass(frozen=True)
65
+ class FrameOCRBudget:
66
+ """Hard ceiling for the video-frame OCR stage (T32.2)."""
67
+
68
+ max_frames: int = DEFAULT_MAX_FRAMES
69
+ min_interval_s: float = DEFAULT_MIN_FRAME_INTERVAL_S
70
+ max_pixels: int = DEFAULT_MAX_FRAME_PIXELS
71
+ max_total_pixels: int = DEFAULT_MAX_TOTAL_FRAME_PIXELS
72
+ duplicate_similarity: float = DEFAULT_FRAME_DUPLICATE_SIMILARITY
73
+
74
+ def __post_init__(self) -> None:
75
+ if self.max_frames < 0:
76
+ raise ValueError("max_frames must be >= 0")
77
+ if self.min_interval_s < 0:
78
+ raise ValueError("min_interval_s must be >= 0")
79
+ if self.max_pixels < 1:
80
+ raise ValueError("max_pixels must be >= 1")
81
+ if self.max_total_pixels < 1:
82
+ raise ValueError("max_total_pixels must be >= 1")
83
+ if not 0.0 <= self.duplicate_similarity <= 1.0:
84
+ raise ValueError("duplicate_similarity must be within [0, 1]")
85
+
86
+ @classmethod
87
+ def from_mapping(
88
+ cls, value: Mapping[str, Any] | FrameOCRBudget | None
89
+ ) -> FrameOCRBudget:
90
+ if value is None:
91
+ return cls()
92
+ if isinstance(value, FrameOCRBudget):
93
+ return value
94
+ return cls(**dict(value))
95
+
96
+
97
+ def _resolve_engine(engine: OCREngine | None) -> OCREngine:
98
+ return engine if engine is not None else get_engine()
99
+
100
+
101
+ def _coerce_tile_budget(
102
+ value: TileBudget | Mapping[str, Any] | None,
103
+ ) -> TileBudget:
104
+ return TileBudget.from_mapping(value)
105
+
106
+
107
+ def _image_size(path: Path) -> tuple[int, int]:
108
+ from PIL import Image
109
+
110
+ with Image.open(path) as handle:
111
+ return handle.size
112
+
113
+
114
+ def _clamp_bbox(
115
+ bbox: Sequence[float], image_width: int, image_height: int
116
+ ) -> tuple[float, float, float, float] | None:
117
+ x0, y0, x1, y1 = (float(value) for value in bbox)
118
+ x0 = max(0.0, min(x0, float(image_width)))
119
+ x1 = max(0.0, min(x1, float(image_width)))
120
+ y0 = max(0.0, min(y0, float(image_height)))
121
+ y1 = max(0.0, min(y1, float(image_height)))
122
+ if x1 <= x0 or y1 <= y0:
123
+ return None
124
+ return (round(x0, 2), round(y0, 2), round(x1, 2), round(y1, 2))
125
+
126
+
127
+ def _image_block(
128
+ *,
129
+ source_id: str,
130
+ image_index: int,
131
+ image_width: int,
132
+ image_height: int,
133
+ line: OCRLine,
134
+ order: int,
135
+ ) -> ContentBlock | None:
136
+ text = line.text.strip()
137
+ if not text:
138
+ return None
139
+ bbox = _clamp_bbox(line.bbox, image_width, image_height)
140
+ if bbox is None:
141
+ return None
142
+ locator = ImageRegionLocator(
143
+ image_index=image_index,
144
+ image_width=image_width,
145
+ image_height=image_height,
146
+ bbox=bbox,
147
+ tile_offset=line.tile_offset,
148
+ )
149
+ return ContentBlock(
150
+ block_id=make_block_id(source_id, locator, text),
151
+ source_id=source_id,
152
+ kind="ocr",
153
+ raw_text=text,
154
+ order=order,
155
+ locator=locator,
156
+ )
157
+
158
+
159
+ def _frame_block(
160
+ *,
161
+ source_id: str,
162
+ time: float,
163
+ image_width: int,
164
+ image_height: int,
165
+ line: OCRLine,
166
+ order: int,
167
+ ) -> ContentBlock | None:
168
+ text = line.text.strip()
169
+ if not text:
170
+ return None
171
+ locator = VideoFrameLocator(
172
+ time=float(time),
173
+ image_width=image_width,
174
+ image_height=image_height,
175
+ bbox=_clamp_bbox(line.bbox, image_width, image_height),
176
+ )
177
+ return ContentBlock(
178
+ block_id=make_block_id(source_id, locator, text),
179
+ source_id=source_id,
180
+ kind="ocr",
181
+ raw_text=text,
182
+ order=order,
183
+ locator=locator,
184
+ )
185
+
186
+
187
+ def _next_order(content: ContentBundle) -> int:
188
+ return max((block.order for block in content.blocks), default=-1) + 1
189
+
190
+
191
+ def _ocr_cache_parts(engine: OCREngine, budget: TileBudget, source_id: str) -> dict[str, object] | None:
192
+ paths = getattr(engine, "model_paths", None)
193
+ if not isinstance(paths, ModelPaths):
194
+ return None # unversioned/injected engines cannot establish safe reuse
195
+ try:
196
+ parameter_builder = getattr(engine, "engine_params", None)
197
+ parameters = parameter_builder() if callable(parameter_builder) else getattr(engine, "params", {})
198
+ if isinstance(parameters, Mapping):
199
+ paths = ModelPaths(paths.root, *[
200
+ Path(parameters.get(f"{name}.model_path") or path)
201
+ for name, path in (("Det", paths.det), ("Cls", paths.cls), ("Rec", paths.rec))
202
+ ])
203
+ runtimes = {}
204
+ for distribution in ("rapidocr", "onnxruntime", "Pillow"):
205
+ try:
206
+ runtimes[distribution] = version(distribution)
207
+ except PackageNotFoundError:
208
+ runtimes[distribution] = "not-installed"
209
+ return {
210
+ "source_id": source_id, "backend": engine.name,
211
+ "models": paths.fingerprint(), "runtime": runtimes,
212
+ "parameters": parameters, "tile_budget": asdict(budget),
213
+ "processor_version": "image-ocr-v1",
214
+ "layout_sha256": hashlib.sha256(Path(__file__).with_name("layout.py").read_bytes()).hexdigest(),
215
+ "engine_sha256": hashlib.sha256(Path(__file__).with_name("rapidocr_engine.py").read_bytes()).hexdigest(),
216
+ }
217
+ except (OSError, ValueError, TypeError) as exc:
218
+ LOGGER.debug("OCR caching unavailable: %s", exc)
219
+ return None
220
+
221
+
222
+ def _read_cached_ocr(raw: bytes, path: Path, budget: TileBudget) -> LongImageResult | None:
223
+ try:
224
+ payload = json.loads(raw)
225
+ for value, model in ((payload, LongImageResult), *[(line, OCRLine) for line in payload["lines"]], *[(tile, Tile) for tile in payload["tiles"]]):
226
+ if not isinstance(value, dict) or set(value) - {field.name for field in fields(model)}:
227
+ return None
228
+ result = _OCR_RESULT_ADAPTER.validate_json(raw, strict=True)
229
+ width, height = _image_size(path)
230
+ if (result.image_width, result.image_height) != (width, height):
231
+ return None
232
+ if result.tiles != plan_tiles(width, height, budget=budget) or result.tiled != (len(result.tiles) > 1):
233
+ return None
234
+ for line in result.lines:
235
+ ImageRegionLocator(image_index=1, image_width=width, image_height=height, bbox=line.bbox)
236
+ if not math.isfinite(line.score) or not 0 <= line.score <= 1:
237
+ return None
238
+ if any(value < 0 for value in line.tile_offset):
239
+ return None
240
+ return result
241
+ except (OSError, ValueError, TypeError, KeyError):
242
+ return None
243
+
244
+
245
+ def _ocr_one_image(
246
+ engine: OCREngine, path: Path, budget: TileBudget,
247
+ cache: LayeredCache | None, key_parts: Mapping[str, object] | None,
248
+ ) -> LongImageResult:
249
+ key = None
250
+ if cache is not None and key_parts is not None:
251
+ with path.open("rb") as handle:
252
+ key = {**key_parts, "image_sha256": hashlib.file_digest(handle, "sha256").hexdigest()}
253
+ cached = cache.get("ocr", key)
254
+ if cached is not None:
255
+ result = _read_cached_ocr(cached, path, budget)
256
+ if result is not None:
257
+ return result
258
+ result = ocr_long_image(engine, path, budget=budget)
259
+ if cache is not None and key is not None:
260
+ cache.put("ocr", key, json.dumps(asdict(result), ensure_ascii=False).encode("utf-8"))
261
+ return result
262
+
263
+
264
+ def run_ocr_for_content(
265
+ content: ContentBundle,
266
+ output_dir: Path,
267
+ *,
268
+ engine: OCREngine | None = None,
269
+ tile_budget: TileBudget | Mapping[str, Any] | None = None,
270
+ diagnostics: list[str] | None = None,
271
+ cache: LayeredCache | None = None,
272
+ ) -> list[ContentBlock]:
273
+ """OCR every image asset of *content*, in original order, into evidence blocks.
274
+
275
+ ``engine=None`` resolves the configured engine (and raises
276
+ :class:`~ytk.errors.ModelUnavailableError` when it is not provisioned).
277
+ A :class:`~ytk.ocr.engine.NullOCR` engine is an explicit "OCR off" run.
278
+ """
279
+ notes = diagnostics if diagnostics is not None else []
280
+ resolved_engine = _resolve_engine(engine)
281
+ if getattr(resolved_engine, "name", "") == "null":
282
+ notes.append("OCR disabled: null engine, no text produced")
283
+ return []
284
+
285
+ images = sorted(
286
+ (asset for asset in content.assets if asset.media_type == "image"),
287
+ key=lambda asset: asset.order,
288
+ )
289
+ if not images:
290
+ notes.append("OCR skipped: content has no image assets")
291
+ return []
292
+
293
+ budget = _coerce_tile_budget(tile_budget)
294
+ source_id = content.source.source_id
295
+ key_parts = _ocr_cache_parts(resolved_engine, budget, source_id)
296
+ if key_parts is not None and cache is None:
297
+ cache = LayeredCache()
298
+ next_order = _next_order(content)
299
+ blocks: list[ContentBlock] = []
300
+
301
+ for image_index, asset in enumerate(images, start=1):
302
+ path = Path(output_dir) / asset.relative_path
303
+ if not path.is_file():
304
+ notes.append(
305
+ f"OCR skipped image {image_index}: asset file is missing "
306
+ f"({asset.relative_path})"
307
+ )
308
+ continue
309
+ try:
310
+ result = _ocr_one_image(resolved_engine, path, budget, cache, key_parts)
311
+ except Exception as exc: # one bad image must not abort the note
312
+ notes.append(f"OCR failed for image {image_index} ({asset.relative_path}): {exc}")
313
+ continue
314
+ for line in result.lines:
315
+ block = _image_block(
316
+ source_id=source_id,
317
+ image_index=image_index,
318
+ image_width=result.image_width,
319
+ image_height=result.image_height,
320
+ line=line,
321
+ order=next_order + len(blocks),
322
+ )
323
+ if block is not None:
324
+ blocks.append(block)
325
+ return blocks
326
+
327
+
328
+ def _frames_similar(
329
+ previous: Sequence[str], current: Sequence[str], threshold: float
330
+ ) -> bool:
331
+ if not previous and not current:
332
+ return True
333
+ if not previous or not current:
334
+ return False
335
+ joined_previous = "".join(sorted(previous))
336
+ joined_current = "".join(sorted(current))
337
+ return text_similarity(joined_previous, joined_current) >= threshold
338
+
339
+
340
+ def run_ocr_for_frames(
341
+ frames: Sequence[tuple[float, str | Path]],
342
+ *,
343
+ source_id: str,
344
+ engine: OCREngine | None = None,
345
+ frame_budget: FrameOCRBudget | Mapping[str, Any] | None = None,
346
+ start_order: int = 0,
347
+ dedupe: bool = True,
348
+ tile_budget: TileBudget | Mapping[str, Any] | None = None,
349
+ diagnostics: list[str] | None = None,
350
+ ) -> list[ContentBlock]:
351
+ """OCR already-sampled video frames into ``VideoFrameLocator`` evidence.
352
+
353
+ *frames* is ``[(frame_time_seconds, frame_path), ...]``; nothing is sampled
354
+ or fetched here. The budget is applied before recognition, so an
355
+ over-budget video stops at the ceiling instead of silently spending more.
356
+ """
357
+ notes = diagnostics if diagnostics is not None else []
358
+ resolved_engine = _resolve_engine(engine)
359
+ if getattr(resolved_engine, "name", "") == "null":
360
+ notes.append("frame OCR disabled: null engine, no text produced")
361
+ return []
362
+ budget = FrameOCRBudget.from_mapping(frame_budget)
363
+
364
+ candidates = sorted(
365
+ ((float(time), Path(path)) for time, path in frames), key=lambda item: item[0]
366
+ )
367
+ accepted: list[tuple[float, Path]] = []
368
+ total_pixels = 0
369
+ last_time: float | None = None
370
+ for time, path in candidates:
371
+ if len(accepted) >= budget.max_frames:
372
+ notes.append(f"frame OCR budget reached: max_frames={budget.max_frames}")
373
+ break
374
+ if last_time is not None and (time - last_time) < budget.min_interval_s:
375
+ notes.append(
376
+ f"frame at {time:.3f}s skipped: closer than "
377
+ f"min_interval_s={budget.min_interval_s:g}"
378
+ )
379
+ continue
380
+ if not path.is_file():
381
+ notes.append(f"frame at {time:.3f}s skipped: file is missing ({path.name})")
382
+ continue
383
+ try:
384
+ width, height = _image_size(path)
385
+ except Exception as exc:
386
+ notes.append(f"frame at {time:.3f}s skipped: unreadable image ({exc})")
387
+ continue
388
+ pixels = width * height
389
+ if pixels > budget.max_pixels:
390
+ notes.append(
391
+ f"frame at {time:.3f}s skipped: {pixels}px exceeds max_pixels={budget.max_pixels}"
392
+ )
393
+ continue
394
+ if total_pixels + pixels > budget.max_total_pixels:
395
+ notes.append(
396
+ f"frame OCR pixel budget exhausted ({total_pixels}px used, "
397
+ f"max_total_pixels={budget.max_total_pixels})"
398
+ )
399
+ break
400
+ accepted.append((time, path))
401
+ total_pixels += pixels
402
+ last_time = time
403
+
404
+ tile_budget_resolved = _coerce_tile_budget(tile_budget)
405
+ blocks: list[ContentBlock] = []
406
+ previous_texts: list[str] | None = None
407
+ for time, path in accepted:
408
+ try:
409
+ result: LongImageResult = ocr_long_image(
410
+ resolved_engine, path, budget=tile_budget_resolved
411
+ )
412
+ except Exception as exc:
413
+ notes.append(f"frame OCR failed at {time:.3f}s: {exc}")
414
+ continue
415
+ texts = [normalize_text(line.text) for line in result.lines]
416
+ if dedupe and previous_texts is not None and _frames_similar(
417
+ previous_texts, texts, budget.duplicate_similarity
418
+ ):
419
+ notes.append(f"frame at {time:.3f}s de-duplicated: same text as the previous frame")
420
+ continue
421
+ for line in result.lines:
422
+ block = _frame_block(
423
+ source_id=source_id,
424
+ time=time,
425
+ image_width=result.image_width,
426
+ image_height=result.image_height,
427
+ line=line,
428
+ order=start_order + len(blocks),
429
+ )
430
+ if block is not None:
431
+ blocks.append(block)
432
+ previous_texts = texts
433
+ return blocks
434
+
435
+
436
+ __all__ = [
437
+ "FrameOCRBudget",
438
+ "run_ocr_for_content",
439
+ "run_ocr_for_frames",
440
+ ]
@@ -0,0 +1,144 @@
1
+ """T32.1 — RapidOCR implementation (lazy load, explicit model paths, no download).
2
+
3
+ The engine is constructed only when the first image is recognised: the ONNX
4
+ sessions cost ~0.4 s and ~450 MB RSS on first use (measured, see models.md), so
5
+ `RapidOCR(...)` (≈6 ms) is deferred and the heavy session init happens inside the
6
+ first :meth:`RapidOCREngine.recognize`.
7
+
8
+ Every model file is passed explicitly (``Det.model_path``/``Cls.model_path``/
9
+ ``Rec.model_path``); pointing RapidOCR at a bare model root would make it
10
+ silently download missing models from modelscope, which is forbidden at
11
+ inference time (A16).
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import threading
17
+ from collections.abc import Mapping
18
+ from dataclasses import dataclass, field
19
+ from pathlib import Path
20
+ from typing import Any
21
+
22
+ from ytk.errors import ModelUnavailableError
23
+ from ytk.ocr.engine import ModelPaths, OCRLine, resolve_model_paths
24
+
25
+
26
+ @dataclass
27
+ class RapidOCREngine:
28
+ """Thin, deterministic wrapper around the installed ``rapidocr`` package."""
29
+
30
+ name: str = field(default="rapidocr", init=False)
31
+
32
+ model_paths: ModelPaths | None = None
33
+ model_dir: str | Path | None = None
34
+ log_level: str = "warning"
35
+ params: Mapping[str, Any] = field(default_factory=dict)
36
+
37
+ def __post_init__(self) -> None:
38
+ if self.model_paths is None:
39
+ self.model_paths = resolve_model_paths(self.model_dir)
40
+ self._engine: Any | None = None
41
+ self._lock = threading.Lock()
42
+
43
+ # -- configuration -------------------------------------------------------
44
+ def engine_params(self) -> dict[str, str]:
45
+ """Explicit per-model paths plus CLI-overridable extra params."""
46
+ assert self.model_paths is not None
47
+ params = self.model_paths.engine_params()
48
+ params.setdefault("Global.log_level", self.log_level)
49
+ params.update({str(key): str(value) for key, value in self.params.items()})
50
+ return params
51
+
52
+ # -- lazy engine ---------------------------------------------------------
53
+ def _get_engine(self) -> Any:
54
+ if self._engine is not None:
55
+ return self._engine
56
+ with self._lock:
57
+ if self._engine is not None:
58
+ return self._engine
59
+ try:
60
+ from rapidocr import RapidOCR
61
+ except Exception as exc: # pragma: no cover - import boundary
62
+ raise ModelUnavailableError(
63
+ "the rapidocr package could not be imported; no download is attempted "
64
+ "at inference time. Install the optional OCR extra: "
65
+ "uv pip install --python .venv/bin/python rapidocr==3.10.0"
66
+ ) from exc
67
+ self._engine = RapidOCR(params=self.engine_params())
68
+ return self._engine
69
+
70
+ # -- recognition ---------------------------------------------------------
71
+ def recognize(self, image: Any) -> list[OCRLine]:
72
+ """Recognise one image (bytes/path/PIL) and return lines in engine order."""
73
+ pil = _load_pil(image)
74
+ if pil.width < 4 or pil.height < 4:
75
+ return []
76
+ engine = self._get_engine()
77
+ try:
78
+ output = engine(pil)
79
+ except FileNotFoundError as exc:
80
+ raise ModelUnavailableError(
81
+ f"RapidOCR model file disappeared while loading: {exc}"
82
+ ) from exc
83
+ return _output_to_lines(output, image_width=pil.width, image_height=pil.height)
84
+
85
+
86
+ def _load_pil(image: Any) -> Any:
87
+ import io
88
+
89
+ from PIL import Image
90
+
91
+ if isinstance(image, Image.Image):
92
+ return image if image.mode == "RGB" else image.convert("RGB")
93
+ if isinstance(image, (bytes, bytearray)):
94
+ return Image.open(io.BytesIO(bytes(image))).convert("RGB")
95
+ if isinstance(image, (str, Path)):
96
+ return Image.open(Path(image)).convert("RGB")
97
+ raise TypeError(f"unsupported OCR image input: {type(image)!r}")
98
+
99
+
100
+ def _quad_to_bbox(quad: Any) -> tuple[float, float, float, float]:
101
+ """Convert a 4-point polygon (RapidOCR box) into an ``xyxy`` rectangle."""
102
+ points = [(float(x), float(y)) for x, y in quad]
103
+ xs = [point[0] for point in points]
104
+ ys = [point[1] for point in points]
105
+ return (min(xs), min(ys), max(xs), max(ys))
106
+
107
+
108
+ def _output_to_lines(
109
+ output: Any, *, image_width: int, image_height: int
110
+ ) -> list[OCRLine]:
111
+ """Map a ``RapidOCROutput`` into ``OCRLine`` objects (engine order kept)."""
112
+ boxes = getattr(output, "boxes", None)
113
+ texts = getattr(output, "txts", None)
114
+ scores = getattr(output, "scores", None)
115
+ if boxes is None or texts is None:
116
+ return []
117
+ lines: list[OCRLine] = []
118
+ for position, (box, text) in enumerate(zip(boxes, texts, strict=False)):
119
+ raw_text = str(text).strip()
120
+ if not raw_text:
121
+ continue
122
+ x0, y0, x1, y1 = _quad_to_bbox(box)
123
+ x0, x1 = max(0.0, min(x0, float(image_width))), max(0.0, min(x1, float(image_width)))
124
+ y0, y1 = max(0.0, min(y0, float(image_height))), max(0.0, min(y1, float(image_height)))
125
+ if x1 <= x0 or y1 <= y0:
126
+ continue
127
+ score = 1.0
128
+ if scores is not None and position < len(scores):
129
+ try:
130
+ score = float(scores[position])
131
+ except (TypeError, ValueError):
132
+ score = 1.0
133
+ lines.append(
134
+ OCRLine(
135
+ text=raw_text,
136
+ bbox=(round(x0, 2), round(y0, 2), round(x1, 2), round(y1, 2)),
137
+ score=score,
138
+ line_index=position,
139
+ )
140
+ )
141
+ return lines
142
+
143
+
144
+ __all__ = ["RapidOCREngine"]