framesig 0.1.0__tar.gz → 0.1.2__tar.gz

{framesig-0.1.0/src/framesig.egg-info → framesig-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framesig
-Version: 0.1.0
+Version: 0.1.2
 Summary: Detect on-screen events in any video by pixel signature — declarative YAML, cached scores, game-agnostic.
 Author-email: Fernando Aporta Franco <ferinazumaDEV@users.noreply.github.com>
 License: MIT
@@ -17,14 +17,16 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy<3,>=1.24
-Requires-Dist: opencv-python-headless<5,>=4.8
+Requires-Dist: opencv-python-headless<6,>=4.8
 Requires-Dist: PyYAML<7,>=6
 Provides-Extra: dev
-Requires-Dist: pytest<9,>=7; extra == "dev"
+Requires-Dist: pytest<10,>=7; extra == "dev"
 Dynamic: license-file
 
 # framesig
 
+[English](README.md) · **Español**: [README.es.md](README.es.md)
+
 **Find *when* something happens on screen — in any video, from any game or source — by its pixel signature.**
 
 ![Python](https://img.shields.io/badge/python-3.9%2B-blue) ![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Tests](https://img.shields.io/badge/tests-88%20passing-brightgreen)
@@ -60,6 +62,12 @@ framesig doesn't know what a "kill" or a "death screen" looks like — and it do
 
 framesig needs only `numpy`, `opencv-python-headless` and `PyYAML`. (`ffmpeg` on your `PATH` is optional — it's used only to *generate* the sample clip in `gen-sample` / `demo`; scanning real videos does not need it.)
 
+```bash
+pip install framesig
+```
+
+Or from a clone, to hack on it:
+
 ```bash
 git clone https://github.com/ferinazumaDEV/framesig
 cd framesig
@@ -245,8 +253,8 @@ The suite includes an end-to-end test that renders the synthetic clip with ffmpe
 framesig is one of a set of small, dependency-light tools I build and maintain in the open — focused utilities that each do one job well and turn messy input into clean, structured output. If framesig fits into your pipeline, these siblings share the same engineering-first philosophy:
 
 - [The GEO Handbook](https://github.com/ferinazumaDEV/generative-engine-optimization-handbook) — the open reference on getting content cited by AI answer engines (ChatGPT, Perplexity, Google AI Overviews, Gemini, Copilot).
-- [typedout](https://github.com/ferinazumaDEV/typedout) — reliable structured output from any LLM: schema-validated JSON with tolerant repair and retries.
-- [politeclient](https://github.com/ferinazumaDEV/politeclient) — a polite, bulletproof HTTP client for Python: retries with backoff, per-host rate-limiting, caching, pagination.
+- [typedout](https://github.com/ferinazumaDEV/typedout) — reliable structured output from OpenAI and Anthropic, with a provider interface for others: schema-validated JSON with tolerant repair and retries.
+- [politeclient](https://github.com/ferinazumaDEV/politeclient) — a careful, well-behaved HTTP client for Python: retries with backoff, per-host rate-limiting, caching, pagination.
 - [scaffld](https://github.com/ferinazumaDEV/scaffld) — scaffold fully-wired Python projects (tests, CI, pre-commit, license) from templates, with a TUI.
 - Hub & writing: [zentimes.es](https://zentimes.es).
 

{framesig-0.1.0 → framesig-0.1.2}/README.md

@@ -1,5 +1,7 @@
 # framesig
 
+[English](README.md) · **Español**: [README.es.md](README.es.md)
+
 **Find *when* something happens on screen — in any video, from any game or source — by its pixel signature.**
 
 ![Python](https://img.shields.io/badge/python-3.9%2B-blue) ![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Tests](https://img.shields.io/badge/tests-88%20passing-brightgreen)
@@ -35,6 +37,12 @@ framesig doesn't know what a "kill" or a "death screen" looks like — and it do
 
 framesig needs only `numpy`, `opencv-python-headless` and `PyYAML`. (`ffmpeg` on your `PATH` is optional — it's used only to *generate* the sample clip in `gen-sample` / `demo`; scanning real videos does not need it.)
 
+```bash
+pip install framesig
+```
+
+Or from a clone, to hack on it:
+
 ```bash
 git clone https://github.com/ferinazumaDEV/framesig
 cd framesig
@@ -220,8 +228,8 @@ The suite includes an end-to-end test that renders the synthetic clip with ffmpe
 framesig is one of a set of small, dependency-light tools I build and maintain in the open — focused utilities that each do one job well and turn messy input into clean, structured output. If framesig fits into your pipeline, these siblings share the same engineering-first philosophy:
 
 - [The GEO Handbook](https://github.com/ferinazumaDEV/generative-engine-optimization-handbook) — the open reference on getting content cited by AI answer engines (ChatGPT, Perplexity, Google AI Overviews, Gemini, Copilot).
-- [typedout](https://github.com/ferinazumaDEV/typedout) — reliable structured output from any LLM: schema-validated JSON with tolerant repair and retries.
-- [politeclient](https://github.com/ferinazumaDEV/politeclient) — a polite, bulletproof HTTP client for Python: retries with backoff, per-host rate-limiting, caching, pagination.
+- [typedout](https://github.com/ferinazumaDEV/typedout) — reliable structured output from OpenAI and Anthropic, with a provider interface for others: schema-validated JSON with tolerant repair and retries.
+- [politeclient](https://github.com/ferinazumaDEV/politeclient) — a careful, well-behaved HTTP client for Python: retries with backoff, per-host rate-limiting, caching, pagination.
 - [scaffld](https://github.com/ferinazumaDEV/scaffld) — scaffold fully-wired Python projects (tests, CI, pre-commit, license) from templates, with a TUI.
 - Hub & writing: [zentimes.es](https://zentimes.es).
 

{framesig-0.1.0 → framesig-0.1.2}/pyproject.toml

@@ -4,9 +4,12 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "framesig"
-version = "0.1.0"
+version = "0.1.2"
 description = "Detect on-screen events in any video by pixel signature — declarative YAML, cached scores, game-agnostic."
 readme = "README.md"
+# Version policy: this floor is a minimum, not a recommendation, and everything below 3.11 is
+# compatibility rather than support. 0.2.0 raises the floor to 3.11 (3.10 reaches end of life in
+# October 2026). Nothing changes within 0.1.x.
 requires-python = ">=3.9"
 license = { text = "MIT" }
 authors = [{ name = "Fernando Aporta Franco", email = "ferinazumaDEV@users.noreply.github.com" }]
@@ -28,12 +31,12 @@ classifiers = [
 ]
 dependencies = [
     "numpy>=1.24,<3",
-    "opencv-python-headless>=4.8,<5",
+    "opencv-python-headless>=4.8,<6",
     "PyYAML>=6,<7",
 ]
 
 [project.optional-dependencies]
-dev = ["pytest>=7,<9"]
+dev = ["pytest>=7,<10"]
 
 [project.scripts]
 framesig = "framesig.cli:main"

{framesig-0.1.0 → framesig-0.1.2}/src/framesig/__init__.py

@@ -41,7 +41,7 @@ from .regions import Region
 from .scanner import ScanResult, detect_all, scan_video
 from .videogen import GroundTruth, SampleVideo, generate_sample_video
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 
 __all__ = [
     "__version__",

{framesig-0.1.0 → framesig-0.1.2}/src/framesig/cache.py

@@ -17,11 +17,19 @@ from __future__ import annotations
 
 import hashlib
 import json
+import os
+import tempfile
 from pathlib import Path
 from typing import Any
 
 CACHE_VERSION = 2
 
+#: Keys :meth:`ScanResult.from_payload` reads. A file missing any of them is not
+#: a usable cache entry, however well-formed its JSON is -- validating only the
+#: version used to let ``{"version": 2}`` through as a hit, and the consumer
+#: then died on a KeyError far from the actual problem.
+_REQUIRED_KEYS = ("video", "meta", "timestamps", "scores")
+
 
 def video_fingerprint(path: str | Path) -> dict[str, Any]:
     """Cheap identity for a video file: absolute path, byte size and mtime."""
@@ -57,29 +65,64 @@ class ScoreCache:
         """Return the cached payload for ``key``, or ``None`` on a miss.
 
         A corrupt or unreadable cache file is treated as a miss rather than an
-        error, so a bad cache can never break a scan.
+        error, so a bad cache can never break a scan. "Corrupt" covers bytes
+        that are not UTF-8, text that is not JSON, JSON that is not an object,
+        the wrong cache version, and an object that does not carry what the
+        consumer will ask for. Any of those means: recompute.
         """
         path = self._path_for(key)
-        if not path.exists():
+        try:
+            raw = path.read_bytes()
+        except OSError:
             return None
         try:
-            payload = json.loads(path.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError):
+            payload = json.loads(raw.decode("utf-8"))
+        # UnicodeDecodeError is a ValueError, not an OSError, so catching
+        # (OSError, JSONDecodeError) missed it entirely: a cache file holding
+        # arbitrary bytes -- a truncated write, a file from another tool, a disk
+        # error -- raised out of load() and killed the scan it was meant to
+        # protect. JSONDecodeError is itself a ValueError, so one clause covers
+        # both without widening to bare Exception.
+        except ValueError:
             return None
         if not isinstance(payload, dict) or payload.get("version") != CACHE_VERSION:
             return None
+        if not all(key_name in payload for key_name in _REQUIRED_KEYS):
+            return None
+        if not isinstance(payload.get("scores"), dict):
+            return None
         return payload
 
     def store(self, key: str, payload: dict[str, Any]) -> Path:
         """Write ``payload`` under ``key`` and return the file path.
 
         The write is atomic (temp file + replace) so a crash mid-write cannot
-        leave a half-written cache behind.
+        leave a half-written cache behind, and each write uses a temporary of
+        its own so two processes sharing a cache directory cannot collide.
+
+        Concurrency beyond that is last-writer-wins. Two writers producing
+        scores for the same key produce the same scores -- the key is a digest
+        of the video and the score-relevant config -- so which one lands does
+        not change the answer.
         """
         self.directory.mkdir(parents=True, exist_ok=True)
         payload = {**payload, "version": CACHE_VERSION}
         path = self._path_for(key)
-        tmp = path.with_suffix(".json.tmp")
-        tmp.write_text(json.dumps(payload), encoding="utf-8")
-        tmp.replace(path)
+
+        # A shared name like scores_<key>.json.tmp meant two writers used the
+        # same temporary: the first replace() moved it away and the second
+        # failed with FileNotFoundError on a path it had legitimately written.
+        # mkstemp gives each writer its own, in the destination directory so
+        # os.replace stays a rename within one filesystem, and therefore atomic.
+        handle, tmp_name = tempfile.mkstemp(
+            dir=self.directory, prefix=f"scores_{key}.", suffix=".json.tmp"
+        )
+        tmp = Path(tmp_name)
+        try:
+            with os.fdopen(handle, "w", encoding="utf-8") as fh:
+                json.dump(payload, fh)
+            os.replace(tmp, path)
+        except BaseException:
+            tmp.unlink(missing_ok=True)
+            raise
         return path

{framesig-0.1.0 → framesig-0.1.2/src/framesig.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framesig
-Version: 0.1.0
+Version: 0.1.2
 Summary: Detect on-screen events in any video by pixel signature — declarative YAML, cached scores, game-agnostic.
 Author-email: Fernando Aporta Franco <ferinazumaDEV@users.noreply.github.com>
 License: MIT
@@ -17,14 +17,16 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy<3,>=1.24
-Requires-Dist: opencv-python-headless<5,>=4.8
+Requires-Dist: opencv-python-headless<6,>=4.8
 Requires-Dist: PyYAML<7,>=6
 Provides-Extra: dev
-Requires-Dist: pytest<9,>=7; extra == "dev"
+Requires-Dist: pytest<10,>=7; extra == "dev"
 Dynamic: license-file
 
 # framesig
 
+[English](README.md) · **Español**: [README.es.md](README.es.md)
+
 **Find *when* something happens on screen — in any video, from any game or source — by its pixel signature.**
 
 ![Python](https://img.shields.io/badge/python-3.9%2B-blue) ![License: MIT](https://img.shields.io/badge/license-MIT-green) ![Tests](https://img.shields.io/badge/tests-88%20passing-brightgreen)
@@ -60,6 +62,12 @@ framesig doesn't know what a "kill" or a "death screen" looks like — and it do
 
 framesig needs only `numpy`, `opencv-python-headless` and `PyYAML`. (`ffmpeg` on your `PATH` is optional — it's used only to *generate* the sample clip in `gen-sample` / `demo`; scanning real videos does not need it.)
 
+```bash
+pip install framesig
+```
+
+Or from a clone, to hack on it:
+
 ```bash
 git clone https://github.com/ferinazumaDEV/framesig
 cd framesig
@@ -245,8 +253,8 @@ The suite includes an end-to-end test that renders the synthetic clip with ffmpe
 framesig is one of a set of small, dependency-light tools I build and maintain in the open — focused utilities that each do one job well and turn messy input into clean, structured output. If framesig fits into your pipeline, these siblings share the same engineering-first philosophy:
 
 - [The GEO Handbook](https://github.com/ferinazumaDEV/generative-engine-optimization-handbook) — the open reference on getting content cited by AI answer engines (ChatGPT, Perplexity, Google AI Overviews, Gemini, Copilot).
-- [typedout](https://github.com/ferinazumaDEV/typedout) — reliable structured output from any LLM: schema-validated JSON with tolerant repair and retries.
-- [politeclient](https://github.com/ferinazumaDEV/politeclient) — a polite, bulletproof HTTP client for Python: retries with backoff, per-host rate-limiting, caching, pagination.
+- [typedout](https://github.com/ferinazumaDEV/typedout) — reliable structured output from OpenAI and Anthropic, with a provider interface for others: schema-validated JSON with tolerant repair and retries.
+- [politeclient](https://github.com/ferinazumaDEV/politeclient) — a careful, well-behaved HTTP client for Python: retries with backoff, per-host rate-limiting, caching, pagination.
 - [scaffld](https://github.com/ferinazumaDEV/scaffld) — scaffold fully-wired Python projects (tests, CI, pre-commit, license) from templates, with a TUI.
 - Hub & writing: [zentimes.es](https://zentimes.es).
 

{framesig-0.1.0 → framesig-0.1.2}/src/framesig.egg-info/SOURCES.txt

@@ -20,6 +20,7 @@ src/framesig.egg-info/entry_points.txt
 src/framesig.egg-info/requires.txt
 src/framesig.egg-info/top_level.txt
 tests/test_cache.py
+tests/test_cache_resilience.py
 tests/test_cli.py
 tests/test_config.py
 tests/test_detectors.py

framesig-0.1.2/src/framesig.egg-info/requires.txt

@@ -0,0 +1,6 @@
+numpy<3,>=1.24
+opencv-python-headless<6,>=4.8
+PyYAML<7,>=6
+
+[dev]
+pytest<10,>=7

framesig-0.1.2/tests/test_cache_resilience.py

@@ -0,0 +1,114 @@
+"""A bad cache must never break a scan, and two writers must not collide.
+
+Audit findings F04 and F05.
+
+F04: ``ScoreCache.load`` documented that a corrupt or unreadable file is a miss,
+but caught only ``(OSError, json.JSONDecodeError)``. ``UnicodeDecodeError`` is a
+``ValueError``, so a cache file holding arbitrary bytes raised straight out of
+``load()`` and killed the scan the cache exists to speed up. Validation was also
+thin enough that ``{"version": 2}`` counted as a hit, and the consumer then died
+on a ``KeyError`` far from the real problem.
+
+F05: every write of a key used the same temporary name, so two writers sharing a
+cache directory raced: the first ``replace()`` moved the shared temporary away
+and the second failed with ``FileNotFoundError`` on a file it had written.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+
+import pytest
+
+from framesig.cache import CACHE_VERSION, ScoreCache
+
+GOOD = {
+    "video": "sample.mp4",
+    "meta": {"duration": 1.0},
+    "timestamps": [0.0, 0.1],
+    "scores": {"flash": [0.0, 1.0]},
+}
+
+CORRUPT = [
+    pytest.param(b"\xff\xfe", id="not-utf8"),
+    pytest.param(b"\x00\x01\x02\x03", id="binary-garbage"),
+    pytest.param(b'{"version": 2, "scores"', id="truncated-json"),
+    pytest.param(b"[1, 2, 3]", id="json-but-not-an-object"),
+    pytest.param(b'{"version": 99, "video": "v", "meta": {}, "timestamps": [], "scores": {}}',
+                 id="wrong-version"),
+    pytest.param(b'{"version": 2}', id="no-payload-keys"),
+    pytest.param(b'{"version": 2, "video": "v", "meta": {}, "timestamps": []}',
+                 id="missing-scores"),
+    pytest.param(b'{"version": 2, "video": "v", "meta": {}, "timestamps": [], "scores": []}',
+                 id="scores-not-an-object"),
+    pytest.param(b"", id="empty-file"),
+]
+
+
+@pytest.mark.parametrize("contents", CORRUPT)
+def test_corrupt_cache_is_a_miss_not_an_exception(tmp_path, contents):
+    (tmp_path / "scores_bad.json").write_bytes(contents)
+    assert ScoreCache(tmp_path).load("bad") is None
+
+
+def test_a_good_entry_still_loads(tmp_path):
+    """The validation must not be so strict that nothing survives it."""
+    cache = ScoreCache(tmp_path)
+    cache.store("ok", GOOD)
+    loaded = cache.load("ok")
+    assert loaded is not None
+    assert loaded["scores"] == GOOD["scores"]
+    assert loaded["version"] == CACHE_VERSION
+
+
+def test_missing_file_is_a_miss(tmp_path):
+    assert ScoreCache(tmp_path).load("never-written") is None
+
+
+def test_two_writers_on_one_key_do_not_collide(tmp_path):
+    """F05: a barrier after the temporary write forces the interleaving."""
+    cache = ScoreCache(tmp_path)
+    barrier = threading.Barrier(2, timeout=10)
+    errors: list[BaseException] = []
+
+    original_replace = __import__("os").replace
+
+    def slow_replace(src, dst):
+        barrier.wait()          # both writers hold a temporary at this point
+        return original_replace(src, dst)
+
+    def writer(index):
+        try:
+            payload = {**GOOD, "scores": {"flash": [float(index)]}}
+            cache.store("shared", payload)
+        except BaseException as exc:      # noqa: BLE001 - the test is about what escapes
+            errors.append(exc)
+
+    import framesig.cache as cache_module
+    monkeypatched = getattr(cache_module, "os")
+    real = monkeypatched.replace
+    monkeypatched.replace = slow_replace
+    try:
+        threads = [threading.Thread(target=writer, args=(i,)) for i in range(2)]
+        for thread in threads:
+            thread.start()
+        for thread in threads:
+            thread.join(timeout=15)
+    finally:
+        monkeypatched.replace = real
+
+    assert not errors, f"a writer raised: {errors!r}"
+
+    # Whichever landed, the file must be complete and valid -- not half-written.
+    written = json.loads((tmp_path / "scores_shared.json").read_text(encoding="utf-8"))
+    assert written["version"] == CACHE_VERSION
+    assert written["scores"]["flash"] in ([0.0], [1.0])
+    assert cache.load("shared") is not None
+
+
+def test_no_temporary_files_are_left_behind(tmp_path):
+    cache = ScoreCache(tmp_path)
+    for i in range(5):
+        cache.store(f"key{i}", GOOD)
+    assert list(tmp_path.glob("*.tmp")) == []

{framesig-0.1.0 → framesig-0.1.2}/tests/test_end_to_end.py

@@ -6,6 +6,7 @@ that framesig recovers exactly the events baked into it, at the right times.
 
 from __future__ import annotations
 
+import json
 from pathlib import Path
 
 import pytest
@@ -97,3 +98,31 @@ def test_detect_all_passes_the_scan_sample_period(sample_video, config, tmp_path
     (cut,) = detect_all(config, result)["scene_cut"]
     assert cut.samples == 1
     assert cut.duration == pytest.approx(result.meta["sample_period"])
+
+
+def test_scan_recomputes_when_the_cache_file_is_corrupt(sample_video, config, tmp_path):
+    """Audit finding F04, the half the unit tests do not cover.
+
+    tests/test_cache_resilience.py proves ScoreCache.load() treats corrupt
+    bytes and useless payloads as a miss. This proves the *consumer* survives
+    them: a scan over a poisoned cache must recompute, return the same scores as
+    a clean scan, and leave a valid cache file behind -- not raise, and not
+    report from_cache=True for data it could not have read.
+    """
+    first = scan_video(sample_video.path, config, cache_dir=str(tmp_path))
+    assert first.from_cache is False
+    cache_files = list(Path(tmp_path).glob("scores_*.json"))
+    assert len(cache_files) == 1, cache_files
+    cache_file = cache_files[0]
+
+    for garbage in (b"\xff\xfe", b'{"version": 2}', b'{"version": 2, "scores"'):
+        cache_file.write_bytes(garbage)
+        again = scan_video(sample_video.path, config, cache_dir=str(tmp_path))
+        assert again.from_cache is False, f"served a hit from {garbage!r}"
+        assert again.timestamps == first.timestamps
+        assert again.scores == first.scores
+        rewritten = json.loads(cache_file.read_text(encoding="utf-8"))
+        assert rewritten["version"] == 2 and rewritten["scores"] == first.scores
+
+    # And the repaired cache is a real hit again.
+    assert scan_video(sample_video.path, config, cache_dir=str(tmp_path)).from_cache is True

framesig-0.1.0/src/framesig.egg-info/requires.txt

@@ -1,6 +0,0 @@
-numpy<3,>=1.24
-opencv-python-headless<5,>=4.8
-PyYAML<7,>=6
-
-[dev]
-pytest<9,>=7