Skip to content

Commit 9d3c597

Browse files
authored
feat: adjustable radius API (#18)
* fix: add radius parameter to FrameMonitor and threshold to FrameCoverage Previously FrameMonitor used hardcoded RADIUS from env var, inconsistent with BKFrameMonitor and RustBKFrameMonitor which accept radius in their constructors. This change makes all monitors consistent. - Add FrameMonitor(radius=) constructor parameter - Add FrameCoverage(threshold=) constructor parameter - Add threshold parameter to get_frame_cov() - Create docs/api.md with comprehensive API reference - Update docs/frame_cov.md configuration section * ignore fuzz link * radius API analysis * feat: change default RADIUS from 5 to 10 Based on empirical analysis of Zelda fuzzing dataset: - radius=5: linear growth, no convergence (growth rate 0.55) - radius=10: converging behavior (growth rate 0.36) The new default provides better convergence characteristics for games with high visual entropy while still distinguishing meaningfully different game states. See radius_analysis_report.md for full experimental results. * bump version
1 parent 55ed037 commit 9d3c597

10 files changed

Lines changed: 1260 additions & 612 deletions

File tree

.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,5 @@ prof/
2020
# Rust build artifacts
2121
target/
2222
Cargo.lock
23+
24+
fuzz

AGENTS.md

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,9 @@ Future metrics (e.g., audio coverage, state-graph coverage) will follow the same
5353
│ ├── videos/ # Small sample MP4s for integration tests
5454
│ └── smb/ # Super Smash Bros recordings for stress tests
5555
├── docs/
56-
│ └── design.md # Architecture and design documentation
56+
│ ├── api.md # API reference documentation
57+
│ ├── frame_cov.md # Architecture and design documentation
58+
│ └── tuning.md # Radius/threshold tuning guide with empirical results
5759
├── rustfmt.toml # Rust formatting config
5860
├── .pre-commit-config.yaml # Pre-commit hooks (Python + Rust)
5961
├── .github/workflows/ # CI: pytest, mypy, ruff, pylint, rust (fmt/clippy/test)
@@ -74,7 +76,9 @@ Run Rust linting: `cargo clippy --all-targets --all-features -- -D warnings`
7476

7577
## Design
7678

77-
See [docs/design.md](docs/design.md) for the coverage framework architecture, frame coverage pipeline, BK-tree optimization, and loading strategies.
79+
See [docs/frame_cov.md](docs/frame_cov.md) for the coverage framework architecture, frame coverage pipeline, BK-tree optimization, and loading strategies.
80+
81+
See [docs/api.md](docs/api.md) for detailed API reference documentation including configuration options.
7882

7983
## Key Modules (quick reference)
8084

@@ -88,7 +92,7 @@ See [docs/design.md](docs/design.md) for the coverage framework architecture, fr
8892
| `writer.py` | `write_mp4()`, `write_mp4_cv2()` |
8993
| `stitch.py` | `stitch_images()` (panorama via AffineStitcher) |
9094
| `generator.py` | Hypothesis strategies: `frames()`, `frames_lists` |
91-
| `env.py` | `RADIUS` env var (Hamming distance threshold, default `5`) |
95+
| `env.py` | `RADIUS` env var (default Hamming distance threshold, `10`); use constructor params to override |
9296

9397
## Environment and Dependencies
9498

@@ -142,7 +146,7 @@ Some tests require assets in `assets/videos/` or `assets/smb/` and will skip if
142146

143147
### Environment variables for tests
144148

145-
- `RADIUS` — Hamming distance threshold (default `5`).
149+
- `RADIUS`Default Hamming distance threshold (default `10`). Prefer passing `radius=` to monitor constructors.
146150
- `N_MAX` — Maximum number of recordings to process in monotonicity tests (default `100`).
147151

148152
## Benchmarks

0 commit comments

Comments
 (0)