bug2context 0.1.0__py3-none-any.whl

bug2context/pipeline/ocr.py

@@ -0,0 +1,207 @@
+"""Stage 3: read on-screen text from frames.
+
+Two backends, picked at runtime: Apple's Vision framework on macOS (better on
+UI text, offline, no install) and tesseract everywhere else. Both are optional
+— with neither available the pipeline still produces a frames-only bundle.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import shutil
+import tempfile
+from pathlib import Path
+
+from PIL import Image
+
+_ERROR_HINTS = re.compile(
+    r"\b(error|exception|fatal|crash|crashed|failed|failure|warning|traceback|"
+    r"undefined|null|nan|denied|unauthorized|forbidden|timeout|timed out|"
+    r"offline|no internet|not found|invalid|unable to|cannot|can't)\b",
+    re.IGNORECASE,
+)
+_STACK_FRAME = re.compile(r"\w+\.(kt|java|dart|swift|py|js|ts|rb|go|php):\d+")
+_HTTP_ERROR = re.compile(r"\b[45]\d{2}\b")
+
+
+def _vision_available() -> bool:
+    try:
+        import Vision  # noqa: F401
+        from Foundation import NSURL  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+def available_backend() -> str | None:
+    """Name of the OCR backend that will be used, or None if there is none."""
+    if _vision_available():
+        return "vision"
+    if shutil.which("tesseract") is not None:
+        try:
+            import pytesseract  # noqa: F401
+        except ImportError:
+            return None
+        return "tesseract"
+    return None
+
+
+def _read_vision(path: Path) -> list[str]:
+    import Vision
+    from Foundation import NSURL
+
+    handler = Vision.VNImageRequestHandler.alloc().initWithURL_options_(
+        NSURL.fileURLWithPath_(str(path)), None
+    )
+    request = Vision.VNRecognizeTextRequest.alloc().init()
+    request.setRecognitionLevel_(Vision.VNRequestTextRecognitionLevelAccurate)
+    request.setUsesLanguageCorrection_(False)  # keep identifiers like RideRequest.kt
+    handler.performRequests_error_([request], None)
+
+    lines = []
+    for observation in request.results() or []:
+        candidates = observation.topCandidates_(1)
+        if candidates:
+            lines.append(str(candidates[0].string()))
+    return lines
+
+
+def _read_tesseract(path: Path) -> list[str]:
+    import pytesseract
+
+    text = pytesseract.image_to_string(Image.open(path))
+    return [line.strip() for line in text.splitlines() if line.strip()]
+
+
+CACHE_DIR = Path("~/.cache/bug2context/ocr").expanduser()
+"""Where recognised text is remembered between runs.
+
+Reading a frame costs a flat ~1.6 s and dominates everything else, while the
+frames themselves are reproducible: extracting the same video twice was
+measured to yield byte-identical PNGs. So the same picture never has to be
+read twice, which is what makes re-running a video with different settings
+cheap. Entries are a few hundred bytes of text; delete the directory to reset.
+"""
+
+
+def _cache_key(data: bytes, backend: str, upscale: int) -> str:
+    return f"{hashlib.sha256(data).hexdigest()}-{backend}-{upscale}"
+
+
+def _cache_read(key: str) -> list[str] | None:
+    try:
+        return json.loads((CACHE_DIR / f"{key}.json").read_text())
+    except (OSError, json.JSONDecodeError):
+        return None  # a cold or damaged cache is not an error
+
+
+def _cache_write(key: str, lines: list[str]) -> None:
+    try:
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        (CACHE_DIR / f"{key}.json").write_text(json.dumps(lines))
+    except OSError:
+        pass  # an unwritable cache must never fail the run
+
+
+UPSCALE_BELOW_WIDTH = 1600
+"""Frames at least this wide are read as they are.
+
+Upscaling exists to rescue text that recompression smeared on a small frame.
+On a 2880x1864 desktop capture it changed nothing measurable (198 lines either
+way) while building a 5760x3728 image per frame — pure waste.
+"""
+
+
+def read_text(
+    path: Path, upscale: int = 1, backend: str | None = None, cache: bool = True
+) -> list[str]:
+    """Text lines visible in the frame, in reading order. Empty if no backend."""
+    backend = backend or available_backend()
+    if backend is None:
+        return []
+
+    key = None
+    if cache:
+        key = _cache_key(path.read_bytes(), backend, upscale)
+        remembered = _cache_read(key)
+        if remembered is not None:
+            return remembered
+
+    lines = _recognise(path, upscale, backend)
+    if key is not None:
+        _cache_write(key, lines)
+    return lines
+
+
+def _recognise(path: Path, upscale: int, backend: str) -> list[str]:
+    reader = _read_vision if backend == "vision" else _read_tesseract
+    if upscale <= 1:
+        return reader(path)
+
+    image = Image.open(path)
+    if image.width >= UPSCALE_BELOW_WIDTH:
+        return reader(path)
+
+    with tempfile.TemporaryDirectory() as tmp:
+        enlarged = Path(tmp) / "upscaled.png"
+        image.resize(
+            (image.width * upscale, image.height * upscale), Image.LANCZOS
+        ).save(enlarged)
+        return reader(enlarged)
+
+
+def _normalize(line: str) -> str:
+    return re.sub(r"\s+", " ", line).strip().casefold()
+
+
+def is_fragment(line: str, min_letters: int = 3, letter_ratio: float = 0.4) -> bool:
+    """Whether a line is OCR debris rather than something someone wrote.
+
+    Screen recordings are full of icons, signal bars and clocks, and OCR turns
+    them into things like `.lll (100 4`, `9011(1004` or `»`. Two cheap signals
+    separate them from real UI text: how many letters there are at all, and what
+    share of the line they make up.
+
+    Calibrated on 36 lines from a real Android capture: 34 correct, and both
+    misses were debris that leaked through rather than text that was lost —
+    losing a real line is the expensive direction.
+    """
+    if not line:
+        return True
+    letters = sum(character.isalpha() for character in line)
+    return letters < min_letters or letters / len(line) < letter_ratio
+
+
+def relevant_lines(
+    lines: list[str], previous: list[str], limit: int = 12
+) -> list[str]:
+    """Pick the lines worth putting in the report.
+
+    Two things earn a line a place: it looks like a failure, or it is new since
+    the last frame. Screens are mostly chrome that repeats across every frame —
+    reprinting it buries the signal an agent is looking for.
+    """
+    seen = {_normalize(line) for line in previous}
+    picked: list[str] = []
+    already: set[str] = set()
+
+    for line in lines:
+        key = _normalize(line)
+        if not key or key in already:
+            continue
+        looks_like_failure = bool(
+            _ERROR_HINTS.search(line)
+            or _STACK_FRAME.search(line)
+            or _HTTP_ERROR.search(line)
+        )
+        # A failure overrides the fragment test: an error rendered oddly is
+        # still the most important thing on screen.
+        if not looks_like_failure and is_fragment(line):
+            continue
+        if looks_like_failure or key not in seen:
+            picked.append(line.strip())
+            already.add(key)
+
+    return picked[:limit]

bug2context-0.1.0.dist-info/METADATA

@@ -0,0 +1,232 @@
+Metadata-Version: 2.5
+Name: bug2context
+Version: 0.1.0
+Summary: Turns bug screen recordings into structured, chronological context for AI agents.
+Project-URL: Homepage, https://github.com/emanueld92/bug2context
+Project-URL: Issues, https://github.com/emanueld92/bug2context/issues
+Author: Emanuel Duran
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bug-report,claude,debugging,llm,mcp,ocr,screen-recording
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Software Development :: Bug Tracking
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: imagehash>=4.3
+Requires-Dist: mcp>=1.2
+Requires-Dist: pillow>=11.0
+Requires-Dist: typer>=0.15
+Provides-Extra: audio
+Requires-Dist: faster-whisper>=1.1; extra == 'audio'
+Provides-Extra: ocr
+Requires-Dist: pyobjc-framework-vision>=10.3; (sys_platform == 'darwin') and extra == 'ocr'
+Requires-Dist: pytesseract>=0.3.13; extra == 'ocr'
+Description-Content-Type: text/markdown
+
+# bug2context
+
+Turns a screen recording of a bug into structured, chronological context an AI
+agent can actually read.
+
+Screenshots lose the story: bugs happen fast, a still frame has no timeline, and
+the logs and the narration live somewhere else entirely. LLMs don't take video.
+This distills a recording into one markdown chronology — key frames, the text on
+screen, device logs and spoken narration, all on the same clock.
+
+- **No SDK.** Works on any video, including one someone sent you over WhatsApp.
+- **Local-first.** Nothing leaves your machine. No account, no API key, no cloud.
+- **MCP-native.** Claude Code calls it as a tool; you just point at the file.
+
+```bash
+uv run bug2context            # guided menu
+uv run bug2context process bug.mp4 --out bundle/
+```
+
+Running it with no arguments opens a menu — record an Android device, process a
+video you already have, or list previous bundles — and writes to
+`~/.bug2context/`, which is where the MCP server looks. Everything it does is
+reachable through the flags below; it just stops you having to remember them.
+
+## What comes out
+
+```
+- `[00:00]` 🖼 `frames/frame_001_00-00.png` — start of recording
+      OCR: Cart 2 items
+- `[00:04]` 🖼 `frames/frame_002_00-04.png` — screen changed
+      OCR: Applying discount..
+- `[00:04]` 📋 W/DiscountEngine: rate field missing
+- `[00:06]` 🖼 `frames/frame_003_00-06.png` — screen changed
+      OCR: TypeError: cannot read 'rate'
+- `[00:06]` 📋 E/RideService: NullPointerException at RideRequest.kt:142
+- `[00:06]` 📋 F/AndroidRuntime: FATAL EXCEPTION: main
+- `[00:06]` 🎙 "ahí está, explota al aplicar el descuento"
+```
+
+A full run is in [examples/report.md](examples/report.md).
+
+```
+bundle/
+├── report.md    the chronology above
+├── frames/      the key frames, named by timestamp
+└── meta.json    the same data, structured, for programmatic use
+```
+
+## Install
+
+Requires [`ffmpeg`](https://ffmpeg.org) on PATH (`brew install ffmpeg`).
+
+```bash
+git clone https://github.com/emanueld92/bug2context
+cd bug2context
+uv sync --extra ocr        # OCR: Apple Vision on macOS, tesseract elsewhere
+uv sync --extra audio      # optional: spoken narration
+```
+
+Every stage is optional and degrades quietly: no OCR backend still gives you
+frames, no audio track still gives you the visual timeline.
+
+## Use it from Claude Code
+
+```bash
+claude mcp add bug2context -- uvx --from /path/to/bug2context bug2context-mcp
+```
+
+Then just ask: *"analiza este video del bug: ~/Desktop/crash.mp4"*.
+
+| Tool | Purpose |
+|---|---|
+| `analyze_bug_video` | Video → chronological report (returns the text itself) |
+| `get_frame` | Fetch one frame as an image so the agent can look at it |
+| `list_bundles` | Previously processed bundles, newest first |
+
+Bundles default to `~/.bug2context/<video>-<timestamp>/`.
+
+## Android: screen + logcat in one command
+
+```bash
+uv run bug2context record --seconds 60 --package com.example.app --out bundle/
+```
+
+Reproduce the bug while it records. Both streams start from a single host
+timestamp — that anchor is what makes a stack trace land next to the frame
+showing the crash.
+
+**Pass `--package`.** Level filtering alone is not enough on a real phone: a
+2 min capture held 7,634 W/E/F lines and *none* came from the app under test —
+they were all `AppOpsControllerImpl`, `GNSSMGT` and friends. Scoping to the
+app's process left 35. Crash tags (`AndroidRuntime`, `DEBUG`) are kept
+regardless of process, since a crash report is the whole point.
+
+Logs are captured unfiltered and scoped afterwards, so an app that crashes and
+restarts still has its death recorded. Consecutive identical entries fold into
+one with a `(×N)` count — framework chatter arrives in bursts of fifteen.
+
+Already have a log file? Merge it into any video:
+
+```bash
+uv run bug2context process bug.mp4 --logcat logcat.txt --log-tag RideService
+```
+
+Reads both `-v time` and `-v threadtime`. `--log-levels` defaults to `WEF` and
+`--log-max-lines` to 80, ranked by severity so a cap never trades the crash for
+boot chatter. `--log-pid` scopes to a process when you already know it. If the device clock and the
+recorder disagree, `--log-offset` shifts everything by N seconds; with no
+`--video-started-at`, the first log entry becomes the anchor.
+
+`screenrecord` caps at 3 minutes, so `record` refuses longer rather than handing
+back a silently truncated video. Ctrl-C cuts a recording short safely — the file
+is finalised on the device first, because killing the local adb leaves one
+`ffprobe` cannot open.
+
+Videos over 10 minutes are refused with the `ffmpeg` command to trim them
+(`--max-duration 0` overrides). Nothing scales badly with length except time,
+but it scales linearly: decoding alone runs at about a third of real time.
+
+## Narration
+
+```bash
+uv run bug2context process bug.mp4 --transcribe --language es
+```
+
+Off by default: it downloads a model on first use and is the slowest stage,
+while most recordings have no voice-over. Skipped automatically when there is no
+audio track, or the track is quieter than −50 dB — whisper invents confident
+sentences out of silence, so that guard is about output quality, not just speed.
+
+## How frames get picked
+
+ffmpeg over-produces candidates (scene cuts **and** a fixed interval, so slowly
+changing screens are not skipped), then perceptual hashing collapses the
+near-duplicates. `--max-frames` caps the result, always keeping the opening frame
+and then whichever changed most.
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--scene-threshold` | `0.08` | ffmpeg scene score for a cut |
+| `--interval-seconds` | `1.0` | forced sample when no cut fires |
+| `--max-frames` | auto | one frame per 2 s, between 20 and 40 |
+| `--phash-distance` | `4` | below this, frames count as duplicates |
+| `--ocr-upscale` | `2` | enlarge before OCR; skipped above 1600 px wide |
+
+Measured end to end, OCR on:
+
+| Source | Result | Time |
+|---|---|---|
+| synthetic 3 min, 1080×1920 | 19 frames | 8.5 s |
+| Android capture, 2 min, 720×1612 @ ~12 fps | 118 candidates → 20 frames | 16 s |
+| macOS capture, 90 s, 2880×1864 @ 60 fps | 97 candidates → 18 frames | 86 s |
+
+Recognised text is cached by frame content in `~/.cache/bug2context/`, so
+re-running a video with different settings only pays for what actually changed —
+measured 9.0 s cold against 3.3 s warm on a 44 s clip, identical output.
+Extracting the same video twice yields byte-identical frames, which is what
+makes the cache safe. Delete the directory to reset it.
+
+Retina desktop recordings are the slow case and there is no trick to remove:
+the cost is decoding 60 fps at 5.4 megapixels (26 s) plus OCR, which Vision
+charges at ~1.6 s per frame regardless of size. Budget roughly real time for
+those; phone captures stay far under it.
+
+On `--ocr-upscale`: a stack trace on a recompressed 1080×1920 frame read as
+`Null PointerSxception Ride Requestkt14` at 1× and correctly as
+`NullPointerException Ride Request kt 142` at 3×. Raise it for badly
+recompressed sources — ask for the video as a file, not as a WhatsApp video.
+It is skipped on frames already 1600 px or wider, where it changed nothing
+measurable while building a 5760×3728 image per frame.
+
+OCR also drops lines that are debris rather than text — `»`, `.lll (100 4`,
+a misread status-bar clock. On a real capture that removed 41 of 210 report
+lines and no real text. A line that looks like a failure is never dropped.
+
+## Known limitation
+
+Perceptual hashing compares visual *structure*. It sees navigation, dialogs and
+error banners, but it cannot detect a small **text-only** change on an otherwise
+identical layout — measured on 1080×1920 those differences fall inside the noise
+floor at every hash size, so no `--phash-distance` value separates them.
+
+OCR does not rescue this: it runs on frames that survive deduplication, so a
+screen already collapsed is never read. Reading every candidate instead measured
+48–59 s for a 3 min video, over the entire time budget. If your bug *is* a small
+text change on an identical screen, record cropped or at lower resolution so the
+text occupies more of the frame.
+
+## Development
+
+```bash
+uv sync --extra ocr
+uv run pytest -q
+```
+
+183 tests. Device recording is mocked on purpose — a test suite should not record
+anyone's phone. Whisper is opt-in via `BUG2CONTEXT_TEST_WHISPER=1` so the suite
+stays offline.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

bug2context-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+bug2context/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+bug2context/android.py,sha256=XX19DZxQg-9IrehJD42FQGKSd9oQXo2HnyzBH1zbZtU,6162
+bug2context/cli.py,sha256=ID6UovrcEHXu4yN60WV__BC8nmkuSU3gE6BBMa0vd1g,3330
+bug2context/config.py,sha256=Bj9uhXk1N0kQV3HuvMXzu0YZRkN9uML83aADeNY57jQ,3742
+bug2context/mcp_server.py,sha256=VSLaN355Ve2jPdzlThMppC9J3Fgp_74lgufuO9FRpck,3985
+bug2context/menu.py,sha256=0iI0aOUYD8bi-_3212wWgMSRbgp-Eli9xjj5Ge97fUI,5189
+bug2context/pipeline/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bug2context/pipeline/assemble.py,sha256=jXRqQumUCgw4IUn7ftihfG9rHRKVHmKiki1EePZf3Ug,7716
+bug2context/pipeline/audio.py,sha256=qICN0nlkCwx8z7uRp_OR_2FKRc-_6SbTivd2CKugWB4,2886
+bug2context/pipeline/frames.py,sha256=73CxnecQKEh6ElTfXn8ndl4OKYrfPzl-0Pcc6bLpbe8,6469
+bug2context/pipeline/logs.py,sha256=HrdUyRgYKTbrMZ6cI6l78oMFe7ilPBXar0CB1hiaK0g,6318
+bug2context/pipeline/ocr.py,sha256=gZMkn7OJlAZ16McJd5QakpL0bd6gSQwD0DjfRp3IZqw,6909
+bug2context-0.1.0.dist-info/METADATA,sha256=zB5TcOoYZyCbcH7mnrmn1UyIC9p4ppUjUNby2Br3Je4,9614
+bug2context-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+bug2context-0.1.0.dist-info/entry_points.txt,sha256=tkAPuQLRV7d95vt6nfLlTDE64CHnSKOTuBu1TnQe2k8,98
+bug2context-0.1.0.dist-info/licenses/LICENSE,sha256=S4R_xraCVRSr_RmXOEOlNHfHfsj0rru0OKndzGfIofw,1070
+bug2context-0.1.0.dist-info/RECORD,,

bug2context-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

bug2context-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+bug2context = bug2context.cli:app
+bug2context-mcp = bug2context.mcp_server:main

bug2context-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emanuel Duran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.