flylight 0.12.4__tar.gz

flylight-0.12.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Madeira Santana
+
+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.

flylight-0.12.4/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: flylight
+Version: 0.12.4
+Summary: Agent-friendly local index for Janelia FlyLight Split-GAL4 resources
+Author: Gustavo Madeira Santana
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# flylight
+
+Agent-friendly local index for Janelia FlyLight Split-GAL4 resources.
+
+Surfaces used:
+
+- CGI site: [splitgal4.janelia.org](https://splitgal4.janelia.org/cgi-bin/splitgal4.cgi)
+- Public bucket: [janelia-flylight-imagery](https://s3.amazonaws.com/janelia-flylight-imagery/)
+- Bucket docs: [README.md](https://s3.amazonaws.com/janelia-flylight-imagery/README.md)
+
+Source order:
+
+1. release manifest json
+2. per-line/per-image S3 metadata json
+3. CGI release summary html
+
+## CLI
+
+PyPI with `pipx`:
+
+```bash
+pipx install flylight
+```
+
+PyPI with plain `pip`:
+
+```bash
+python3 -m pip install flylight
+```
+
+Homebrew:
+
+```bash
+brew tap gumadeiras/tap
+brew install flylight
+flylight --version
+```
+
+From source:
+
+```bash
+python3 -m pip install -e .
+```
+
+## Release
+
+Current release: `v0.12.2`.
+
+Tag pushes like `vX.Y.Z` run the release workflow: build artifacts, create a
+GitHub release, publish to PyPI, and update `gumadeiras/homebrew-tap`.
+
+Release prerequisites:
+
+- PyPI trusted publishing configured for this repo.
+- `HOMEBREW_TAP_TOKEN` repository secret can write to
+  `gumadeiras/homebrew-tap`.
+
+Entry:
+
+```bash
+flylight --help
+python3 janelia_splitgal4.py
+```
+
+Examples:
+
+```bash
+flylight releases
+flylight sync --release 'MB Paper 2014'
+flylight sync --all
+flylight sync --all --force
+flylight sync --all --offline
+flylight sync --all --refresh-cache
+flylight sync --release 'Descending Neurons 2018' --workers 8
+flylight sync-plan --all
+flylight sync-plan --release 'MB Paper 2014' --offline
+flylight reindex
+flylight cache-info
+flylight schema --entity line
+flylight examples --topic release-diff
+flylight snapshot-export --out data/flylight-snapshot.tar.gz
+flylight snapshot-import data/flylight-snapshot.tar.gz --force
+flylight search --expressed-in DNp04 --ad 31B08 --source-kind line-metadata
+flylight search --em-cell-type EPG
+flylight search-text 'DNp04 AND 31B08'
+flylight search-images --area Brain --objective 20x --robot-id 3007645
+flylight search-images --em-cell-type EPG
+flylight show-line SS00724 --release 'Descending Neurons 2018'
+flylight show-image 6878306
+flylight compare-line MB005B
+flylight compare-release 'MB Paper 2014' 'MB Paper 2015'
+flylight show-release 'MB Paper 2014' --include-lines --genotype 34A03
+flylight stats
+flylight export-ndjson --entity line --release 'Descending Neurons 2018'
+flylight export-ndjson --entity image --term MB005B --out data/mb005b.ndjson
+flylight export-ndjson --entity release
+flylight export-ndjson --entity compare-line --line MB005B
+flylight export-ndjson --entity compare-release --left-release 'MB Paper 2014' --right-release 'MB Paper 2015'
+```
+
+## Notes
+
+- HTTP fetches are cache-first by default; cached responses are reused until you pass `--refresh-cache`.
+- `--offline` disables network access and uses cached HTTP responses only.
+- cache path: `data/http_cache`
+- `sync-plan` is a dry-run: source kind, cache coverage, db coverage, skip vs sync decision.
+- `reindex` rebuilds derived searchable fields from stored raw image payloads; use it after schema upgrades on an existing db.
+- `snapshot-export` bundles sqlite + raw manifests + HTTP cache for portable offline reuse.
+- `snapshot-import` restores that bundle on another machine or working copy.
+- `schema` shows agent-facing row shapes and producer commands.
+- `examples` shows canned command recipes for common agent workflows.
+- `sync --all` is incremental by default; unchanged releases skip.
+- `cache-info` also reports cache suffix counts and oldest/newest cached timestamps.
+- missing release manifest: fallback walks line dirs + metadata jsons.
+- CGI summary enriches line-level fields like expressed-in, genotype, AD, DBD.
+- line/image exports include normalized arrays alongside text fields.
+- line/image records now include normalized `em_cell_types` derived from raw `em_cell_type` metadata when present.
+- `search` supports field filters over line metadata: AD, DBD, genotype, expressed-in, robot-id, source-kind.
+- `search` and `search-images` also support exact `--em-cell-type` matching.
+- `search-text` uses SQLite FTS for faster boolean/full-text matching over line text fields.
+- `search-images` supports field filters over image metadata: area, objective, gender, robot-id, roi.
+- `compare-line` shows shared fields for the same line across synced releases.
+- `compare-release` summarizes added, removed, changed, and unchanged lines between two synced releases.
+- `export-ndjson` also supports `compare-line` and `compare-release` entities for agent ingest.
+- local db path: `data/janelia_splitgal4.sqlite`
+- raw manifest cache: `data/raw_manifests/*.json`

flylight-0.12.4/README.md

@@ -0,0 +1,126 @@
+# flylight
+
+Agent-friendly local index for Janelia FlyLight Split-GAL4 resources.
+
+Surfaces used:
+
+- CGI site: [splitgal4.janelia.org](https://splitgal4.janelia.org/cgi-bin/splitgal4.cgi)
+- Public bucket: [janelia-flylight-imagery](https://s3.amazonaws.com/janelia-flylight-imagery/)
+- Bucket docs: [README.md](https://s3.amazonaws.com/janelia-flylight-imagery/README.md)
+
+Source order:
+
+1. release manifest json
+2. per-line/per-image S3 metadata json
+3. CGI release summary html
+
+## CLI
+
+PyPI with `pipx`:
+
+```bash
+pipx install flylight
+```
+
+PyPI with plain `pip`:
+
+```bash
+python3 -m pip install flylight
+```
+
+Homebrew:
+
+```bash
+brew tap gumadeiras/tap
+brew install flylight
+flylight --version
+```
+
+From source:
+
+```bash
+python3 -m pip install -e .
+```
+
+## Release
+
+Current release: `v0.12.2`.
+
+Tag pushes like `vX.Y.Z` run the release workflow: build artifacts, create a
+GitHub release, publish to PyPI, and update `gumadeiras/homebrew-tap`.
+
+Release prerequisites:
+
+- PyPI trusted publishing configured for this repo.
+- `HOMEBREW_TAP_TOKEN` repository secret can write to
+  `gumadeiras/homebrew-tap`.
+
+Entry:
+
+```bash
+flylight --help
+python3 janelia_splitgal4.py
+```
+
+Examples:
+
+```bash
+flylight releases
+flylight sync --release 'MB Paper 2014'
+flylight sync --all
+flylight sync --all --force
+flylight sync --all --offline
+flylight sync --all --refresh-cache
+flylight sync --release 'Descending Neurons 2018' --workers 8
+flylight sync-plan --all
+flylight sync-plan --release 'MB Paper 2014' --offline
+flylight reindex
+flylight cache-info
+flylight schema --entity line
+flylight examples --topic release-diff
+flylight snapshot-export --out data/flylight-snapshot.tar.gz
+flylight snapshot-import data/flylight-snapshot.tar.gz --force
+flylight search --expressed-in DNp04 --ad 31B08 --source-kind line-metadata
+flylight search --em-cell-type EPG
+flylight search-text 'DNp04 AND 31B08'
+flylight search-images --area Brain --objective 20x --robot-id 3007645
+flylight search-images --em-cell-type EPG
+flylight show-line SS00724 --release 'Descending Neurons 2018'
+flylight show-image 6878306
+flylight compare-line MB005B
+flylight compare-release 'MB Paper 2014' 'MB Paper 2015'
+flylight show-release 'MB Paper 2014' --include-lines --genotype 34A03
+flylight stats
+flylight export-ndjson --entity line --release 'Descending Neurons 2018'
+flylight export-ndjson --entity image --term MB005B --out data/mb005b.ndjson
+flylight export-ndjson --entity release
+flylight export-ndjson --entity compare-line --line MB005B
+flylight export-ndjson --entity compare-release --left-release 'MB Paper 2014' --right-release 'MB Paper 2015'
+```
+
+## Notes
+
+- HTTP fetches are cache-first by default; cached responses are reused until you pass `--refresh-cache`.
+- `--offline` disables network access and uses cached HTTP responses only.
+- cache path: `data/http_cache`
+- `sync-plan` is a dry-run: source kind, cache coverage, db coverage, skip vs sync decision.
+- `reindex` rebuilds derived searchable fields from stored raw image payloads; use it after schema upgrades on an existing db.
+- `snapshot-export` bundles sqlite + raw manifests + HTTP cache for portable offline reuse.
+- `snapshot-import` restores that bundle on another machine or working copy.
+- `schema` shows agent-facing row shapes and producer commands.
+- `examples` shows canned command recipes for common agent workflows.
+- `sync --all` is incremental by default; unchanged releases skip.
+- `cache-info` also reports cache suffix counts and oldest/newest cached timestamps.
+- missing release manifest: fallback walks line dirs + metadata jsons.
+- CGI summary enriches line-level fields like expressed-in, genotype, AD, DBD.
+- line/image exports include normalized arrays alongside text fields.
+- line/image records now include normalized `em_cell_types` derived from raw `em_cell_type` metadata when present.
+- `search` supports field filters over line metadata: AD, DBD, genotype, expressed-in, robot-id, source-kind.
+- `search` and `search-images` also support exact `--em-cell-type` matching.
+- `search-text` uses SQLite FTS for faster boolean/full-text matching over line text fields.
+- `search-images` supports field filters over image metadata: area, objective, gender, robot-id, roi.
+- `compare-line` shows shared fields for the same line across synced releases.
+- `compare-release` summarizes added, removed, changed, and unchanged lines between two synced releases.
+- `export-ndjson` also supports `compare-line` and `compare-release` entities for agent ingest.
+- local db path: `data/janelia_splitgal4.sqlite`
+- raw manifest cache: `data/raw_manifests/*.json`

flylight-0.12.4/flylight.egg-info/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: flylight
+Version: 0.12.4
+Summary: Agent-friendly local index for Janelia FlyLight Split-GAL4 resources
+Author: Gustavo Madeira Santana
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# flylight
+
+Agent-friendly local index for Janelia FlyLight Split-GAL4 resources.
+
+Surfaces used:
+
+- CGI site: [splitgal4.janelia.org](https://splitgal4.janelia.org/cgi-bin/splitgal4.cgi)
+- Public bucket: [janelia-flylight-imagery](https://s3.amazonaws.com/janelia-flylight-imagery/)
+- Bucket docs: [README.md](https://s3.amazonaws.com/janelia-flylight-imagery/README.md)
+
+Source order:
+
+1. release manifest json
+2. per-line/per-image S3 metadata json
+3. CGI release summary html
+
+## CLI
+
+PyPI with `pipx`:
+
+```bash
+pipx install flylight
+```
+
+PyPI with plain `pip`:
+
+```bash
+python3 -m pip install flylight
+```
+
+Homebrew:
+
+```bash
+brew tap gumadeiras/tap
+brew install flylight
+flylight --version
+```
+
+From source:
+
+```bash
+python3 -m pip install -e .
+```
+
+## Release
+
+Current release: `v0.12.2`.
+
+Tag pushes like `vX.Y.Z` run the release workflow: build artifacts, create a
+GitHub release, publish to PyPI, and update `gumadeiras/homebrew-tap`.
+
+Release prerequisites:
+
+- PyPI trusted publishing configured for this repo.
+- `HOMEBREW_TAP_TOKEN` repository secret can write to
+  `gumadeiras/homebrew-tap`.
+
+Entry:
+
+```bash
+flylight --help
+python3 janelia_splitgal4.py
+```
+
+Examples:
+
+```bash
+flylight releases
+flylight sync --release 'MB Paper 2014'
+flylight sync --all
+flylight sync --all --force
+flylight sync --all --offline
+flylight sync --all --refresh-cache
+flylight sync --release 'Descending Neurons 2018' --workers 8
+flylight sync-plan --all
+flylight sync-plan --release 'MB Paper 2014' --offline
+flylight reindex
+flylight cache-info
+flylight schema --entity line
+flylight examples --topic release-diff
+flylight snapshot-export --out data/flylight-snapshot.tar.gz
+flylight snapshot-import data/flylight-snapshot.tar.gz --force
+flylight search --expressed-in DNp04 --ad 31B08 --source-kind line-metadata
+flylight search --em-cell-type EPG
+flylight search-text 'DNp04 AND 31B08'
+flylight search-images --area Brain --objective 20x --robot-id 3007645
+flylight search-images --em-cell-type EPG
+flylight show-line SS00724 --release 'Descending Neurons 2018'
+flylight show-image 6878306
+flylight compare-line MB005B
+flylight compare-release 'MB Paper 2014' 'MB Paper 2015'
+flylight show-release 'MB Paper 2014' --include-lines --genotype 34A03
+flylight stats
+flylight export-ndjson --entity line --release 'Descending Neurons 2018'
+flylight export-ndjson --entity image --term MB005B --out data/mb005b.ndjson
+flylight export-ndjson --entity release
+flylight export-ndjson --entity compare-line --line MB005B
+flylight export-ndjson --entity compare-release --left-release 'MB Paper 2014' --right-release 'MB Paper 2015'
+```
+
+## Notes
+
+- HTTP fetches are cache-first by default; cached responses are reused until you pass `--refresh-cache`.
+- `--offline` disables network access and uses cached HTTP responses only.
+- cache path: `data/http_cache`
+- `sync-plan` is a dry-run: source kind, cache coverage, db coverage, skip vs sync decision.
+- `reindex` rebuilds derived searchable fields from stored raw image payloads; use it after schema upgrades on an existing db.
+- `snapshot-export` bundles sqlite + raw manifests + HTTP cache for portable offline reuse.
+- `snapshot-import` restores that bundle on another machine or working copy.
+- `schema` shows agent-facing row shapes and producer commands.
+- `examples` shows canned command recipes for common agent workflows.
+- `sync --all` is incremental by default; unchanged releases skip.
+- `cache-info` also reports cache suffix counts and oldest/newest cached timestamps.
+- missing release manifest: fallback walks line dirs + metadata jsons.
+- CGI summary enriches line-level fields like expressed-in, genotype, AD, DBD.
+- line/image exports include normalized arrays alongside text fields.
+- line/image records now include normalized `em_cell_types` derived from raw `em_cell_type` metadata when present.
+- `search` supports field filters over line metadata: AD, DBD, genotype, expressed-in, robot-id, source-kind.
+- `search` and `search-images` also support exact `--em-cell-type` matching.
+- `search-text` uses SQLite FTS for faster boolean/full-text matching over line text fields.
+- `search-images` supports field filters over image metadata: area, objective, gender, robot-id, roi.
+- `compare-line` shows shared fields for the same line across synced releases.
+- `compare-release` summarizes added, removed, changed, and unchanged lines between two synced releases.
+- `export-ndjson` also supports `compare-line` and `compare-release` entities for agent ingest.
+- local db path: `data/janelia_splitgal4.sqlite`
+- raw manifest cache: `data/raw_manifests/*.json`

flylight-0.12.4/flylight.egg-info/SOURCES.txt

@@ -0,0 +1,25 @@
+LICENSE
+README.md
+janelia_splitgal4.py
+pyproject.toml
+flylight.egg-info/PKG-INFO
+flylight.egg-info/SOURCES.txt
+flylight.egg-info/dependency_links.txt
+flylight.egg-info/entry_points.txt
+flylight.egg-info/top_level.txt
+flylight_cli/__init__.py
+flylight_cli/__main__.py
+flylight_cli/cache.py
+flylight_cli/cli.py
+flylight_cli/core.py
+flylight_cli/db.py
+flylight_cli/examples.py
+flylight_cli/normalize.py
+flylight_cli/query.py
+flylight_cli/records.py
+flylight_cli/reindex.py
+flylight_cli/schema.py
+flylight_cli/snapshot.py
+flylight_cli/sync_plan.py
+tests/test_cli.py
+tests/test_sync_plan.py

flylight-0.12.4/flylight.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

flylight-0.12.4/flylight.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+flylight = flylight_cli.cli:main

flylight-0.12.4/flylight.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+flylight_cli
+janelia_splitgal4

flylight-0.12.4/flylight_cli/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.12.4"

flylight-0.12.4/flylight_cli/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flylight-0.12.4/flylight_cli/cache.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+from dataclasses import dataclass, replace
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import urlparse
+from urllib.request import Request, urlopen
+
+
+DEFAULT_CACHE_DIR = Path("data/http_cache")
+
+
+@dataclass
+class CacheOptions:
+    cache_dir: Path = DEFAULT_CACHE_DIR
+    offline: bool = False
+    refresh: bool = False
+
+
+class OfflineCacheMiss(RuntimeError):
+    pass
+
+
+_cache_options = CacheOptions()
+
+
+def get_cache_options() -> CacheOptions:
+    return _cache_options
+
+
+def set_cache_options(
+    cache_dir: Path | None = None,
+    offline: bool | None = None,
+    refresh: bool | None = None,
+) -> CacheOptions:
+    global _cache_options
+    next_options = replace(_cache_options)
+    if cache_dir is not None:
+        next_options.cache_dir = cache_dir
+    if offline is not None:
+        next_options.offline = offline
+    if refresh is not None:
+        next_options.refresh = refresh
+    if next_options.offline and next_options.refresh:
+        raise ValueError("cannot combine offline mode with refresh-cache")
+    _cache_options = next_options
+    return _cache_options
+
+
+def cache_path_for_url(url: str, cache_dir: Path | None = None) -> Path:
+    cache_dir = cache_dir or _cache_options.cache_dir
+    digest = hashlib.sha256(url.encode("utf-8")).hexdigest()
+    suffix = Path(urlparse(url).path).suffix or ".bin"
+    return cache_dir / digest[:2] / f"{digest}{suffix}"
+
+
+def meta_path_for_cache(cache_path: Path) -> Path:
+    return cache_path.with_suffix(cache_path.suffix + ".meta.json")
+
+
+def ensure_cache_parent(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def load_cached_bytes(url: str, cache_dir: Path | None = None) -> bytes | None:
+    cache_path = cache_path_for_url(url, cache_dir=cache_dir)
+    if not cache_path.exists():
+        return None
+    return cache_path.read_bytes()
+
+
+def cached_at_for_path(cache_path: Path) -> str | None:
+    meta_path = meta_path_for_cache(cache_path)
+    if not meta_path.exists():
+        return None
+    meta = json.loads(meta_path.read_text(encoding="utf-8"))
+    cached_at = meta.get("cached_at")
+    if isinstance(cached_at, str) and cached_at:
+        return cached_at
+    return None
+
+
+def cache_data_paths(cache_dir: Path) -> list[Path]:
+    return [path for path in cache_dir.rglob("*") if path.is_file() and not path.name.endswith(".meta.json")]
+
+
+def cache_entry_for_url(url: str, cache_dir: Path | None = None) -> dict[str, int | str] | None:
+    cache_path = cache_path_for_url(url, cache_dir=cache_dir)
+    if not cache_path.exists():
+        return None
+    payload: dict[str, int | str] = {
+        "url": url,
+        "cache_path": str(cache_path),
+        "bytes": cache_path.stat().st_size,
+        "suffix": cache_path.suffix,
+    }
+    cached_at = cached_at_for_path(cache_path)
+    if cached_at:
+        payload["cached_at"] = cached_at
+    return payload
+
+
+def write_atomic_bytes(path: Path, payload: bytes) -> None:
+    ensure_cache_parent(path)
+    fd, tmp_name = tempfile.mkstemp(
+        dir=path.parent,
+        prefix=f"{path.name}.",
+        suffix=".tmp",
+    )
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(payload)
+        Path(tmp_name).replace(path)
+    except Exception:
+        Path(tmp_name).unlink(missing_ok=True)
+        raise
+
+
+def write_cached_bytes(url: str, payload: bytes, cache_dir: Path | None = None) -> Path:
+    cache_path = cache_path_for_url(url, cache_dir=cache_dir)
+    write_atomic_bytes(cache_path, payload)
+    meta_payload = json.dumps(
+        {
+            "url": url,
+            "cached_at": datetime.now(timezone.utc).replace(microsecond=0).isoformat(),
+            "bytes": len(payload),
+        },
+        indent=2,
+        sort_keys=True,
+    )
+    write_atomic_bytes(meta_path_for_cache(cache_path), meta_payload.encode("utf-8"))
+    return cache_path
+
+
+def fetch_bytes(url: str, user_agent: str) -> bytes:
+    options = get_cache_options()
+    cached = None if options.refresh else load_cached_bytes(url, cache_dir=options.cache_dir)
+    if cached is not None:
+        return cached
+    if options.offline:
+        raise OfflineCacheMiss(f"offline cache miss for {url}; rerun without --offline to warm the cache")
+    req = Request(url, headers={"User-Agent": user_agent})
+    with urlopen(req) as resp:
+        payload = resp.read()
+    write_cached_bytes(url, payload, cache_dir=options.cache_dir)
+    return payload
+
+
+def cache_stats(cache_dir: Path | None = None) -> dict[str, int | str]:
+    cache_dir = cache_dir or _cache_options.cache_dir
+    if not cache_dir.exists():
+        return {
+            "cache_dir": str(cache_dir),
+            "entries": 0,
+            "bytes": 0,
+            "suffix_counts": {},
+            "oldest_cached_at": None,
+            "newest_cached_at": None,
+        }
+    paths = cache_data_paths(cache_dir)
+    suffix_counts: dict[str, int] = {}
+    cached_at_values: list[str] = []
+    for path in paths:
+        suffix = path.suffix or ".bin"
+        suffix_counts[suffix] = suffix_counts.get(suffix, 0) + 1
+        cached_at = cached_at_for_path(path)
+        if cached_at:
+            cached_at_values.append(cached_at)
+    return {
+        "cache_dir": str(cache_dir),
+        "entries": len(paths),
+        "bytes": sum(path.stat().st_size for path in paths),
+        "suffix_counts": suffix_counts,
+        "oldest_cached_at": min(cached_at_values) if cached_at_values else None,
+        "newest_cached_at": max(cached_at_values) if cached_at_values else None,
+    }