Metadata-Version: 2.5
Name: guetteur
Version: 0.1.0
Summary: Team Drift: a privacy-first active-perception agent. OpenCV 5 depth analysis -> planner -> actions, every claim backed by a re-runnable receipt.
Project-URL: Homepage, https://cloudlabworks.dev/oss/guetteur
Project-URL: Source, https://github.com/cloudlabworks/guetteur
Project-URL: Issues, https://github.com/cloudlabworks/guetteur/issues
Author-email: Alex Alvord <325058966+cloudlabworks@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
License-File: third_party/prove_it_done/LICENSE
Keywords: active-perception,agent,computer-vision,depth,human-in-the-loop,opencv,privacy,receipts
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: <3.13,>=3.12
Requires-Dist: numpy==2.5.4
Requires-Dist: opencv-python-headless==5.0.0.93
Description-Content-Type: text/markdown

# Guetteur (Team Drift): active perception with receipts

*Guetteur* is French for "lookout". An agent watches a space through **depth only**, decides what to look at next
using **OpenCV 5** evidence, stops at a **human gate** before anything outward-facing happens, and attaches a
**re-runnable receipt** to every claim it makes.

> **Status (2026-10-15): submitted to the OpenCV AI Competition powered by AWS.**
> [Devpost entry](https://devpost.com/software/guetteur) · [Narrated demo (3:52)](https://youtu.be/_r8mIRTFzFA) · [Submission receipt](docs/submission/submission-receipt.json).
> AWS judge demo deployed; physical depth capture verified.
> Try [the live dashboard](https://nm4p814bp0.execute-api.us-west-2.amazonaws.com/).
> The published accuracy results remain **synthetic-only**. Three physical OAK-D depth takes
> (empty baseline, walkthrough, item removal) each contain 300 integrity-checked 640x400 frames;
> calibrated replay and real-world accuracy measurement remain open. The AWS demo runs built-in
> synthetic scenes, not a live camera feed. See [current evidence](docs/submission/aws-smoke-summary.json).
>
> Built for the OpenCV AI Competition 2026 (Agentic Vision path). Rules notes with section citations: `docs/RULES_NOTES.md`.

## What it does

```
depth frames ──> OpenCV 5 perception ──> evidence (JSON, no pixels) ──> planner ──> action ──> next perception call
                 inpaint, medianBlur,                                  rule-based    recheck_zone / pause_zone /
                 morphology, connected                                 (LLM slot)    compensate_drift / degrade_zone
                 components, Farneback                                               request_approval  (human gate)
                                                                                          │
                                           every claim ──> claim.json ──> receipts ──> prove-it-done verifier
```

* **Ambiguous evidence changes the next tool call.** A 25 mm change is ~3.5 sigma in one frame; the planner asks
  `recheck_zone(n=7)` and OpenCV 5 re-runs on the integrated window before anyone is bothered.
* **Presence is not a change.** A person-sized blob nearer than the scene pauses that zone.
* **Sensor trouble is not a scene event.** Noise bursts degrade the zone, gain drift is compensated, lost depth escalates as a camera fault.
* **Default is deny.** If no human answers the approval request, nothing is published.
* **Claims carry receipts.** Each claim is re-checked by two independent estimators (numpy-only, and OpenCV frame statistics) against the pinned input, and the vendored [prove-it-done](https://github.com/issaquahd/prove-it-done) verifier judges the ledger. Claims doctored beyond the tolerance (max(8 mm, 25% of the value)) fail: inflated, pointed at the wrong pixels or time, or re-pointed at another recording. Smaller inflations pass by design.

## Quick start (macOS/Linux, Python 3.12, [uv](https://docs.astral.sh/uv/))

```bash
uv sync                                    # pinned: opencv-python-headless==5.0.0.93, numpy==2.5.4, pytest==9.1.1 (see uv.lock)
uv run pytest                              # ~2-3 minutes; includes the real verifier and tamper tests
uv run guetteur scenarios                  # the 11 synthetic scenarios and their ground truth
uv run guetteur demo                       # narrated demo (the judge demo without a camera)
uv run guetteur run subtle_item_removed --verify     # one scenario: trace, alerts, score, receipts
uv run guetteur run person_takes_item --gate timeout # human gate times out -> nothing is published
uv run guetteur run subtle_item_removed --planner naive   # the threshold-and-alert baseline misses it
uv run guetteur eval                       # all scenarios x 3 seeds x 3 planners -> eval/results.json
uv run guetteur bench                      # per-frame runtime on this machine -> eval/runtime.json
uv run guetteur serve                      # the judge dashboard + API on http://127.0.0.1:8080/
```

From PyPI instead of a clone (Python 3.12): `pip install guetteur`, then the same commands without `uv run`
(for example `guetteur demo`). Outputs go under the working directory.

Re-verify any ledger yourself: `uv run guetteur verify-ledger runs/<run>/receipts.md` (runs the vendored
`third_party/prove_it_done/verify_receipts.py`, pinned to prove-it-done commit `d897534`).

## Optional physical-camera capture

An opt-in, depth-only native recorder and operator run sheet are available in
[`docs/REAL_DEPTH_CAPTURE.md`](docs/REAL_DEPTH_CAPTURE.md). Hardware capture and clean shutdown are verified; calibrated replay remains open. This does not change the synthetic-only status of the accuracy evaluation.

## Layout

| Path | What |
| --- | --- |
| `src/guetteur/perception.py` | OpenCV 5 pipeline: holes, denoise, change evidence, morphology, blobs, optical flow, coarse grid |
| `src/guetteur/planner.py` | `Planner` interface, `RulePlanner`, `NaivePlanner` (ablation), `LLMPlanner` slot + action validation |
| `src/guetteur/agent.py` | executor: autonomy policy, evidence guardrails, human gate, trace |
| `src/guetteur/receipts.py`, `check_numpy.py`, `check_cv.py` | claims, ledger writer, the two independent re-checks |
| `src/guetteur/synth.py` | synthetic depth scenes with ground truth (11 scenarios) |
| `src/guetteur/cloud/` | the Lambda handler (also served locally), dashboard page, approval/evidence store |
| `INFRA/` | AWS SAM template for the deployed judge endpoint; optional phase-2 resources are not deployed |
| `deploy/` | credential-free CloudShell deploy kit: `cloudshell-deploy.sh`, `make-artifact.sh`, guardrail check |
| `third_party/prove_it_done/` | vendored verifier (MIT), provenance in `PROVENANCE.md` |
| `tests/` | unit, scenario, receipt/tamper, and API tests |
| `docs/` | `RULES_NOTES.md`, `EVALUATION.md` (generated), `TRACE_EXAMPLE.md`, `report/` (technical report, PDF) |

## Honest limits

* Accuracy metrics are synthetic-only. Physical depth recordings exist, but calibration, interval labels, and held-out replay are still required before a real-world accuracy claim.
* Depth cannot tell *what* an object is; claims say "a region became farther by 24 mm", not "a bottle was removed".
* Changes under ~1 sigma after filtering are invisible (documented miss: `subthreshold_item_removed`).
* The LLM planner is an interface plus tests with a fake model; no model is called.
* The edge/cloud approval path (DynamoDB, S3, authenticated routes) is code plus local tests only; the first AWS deployment is a public synthetic-demo endpoint (`INFRA/README.md`).
* The deployed AWS scope is API Gateway + Lambda arm64 running OpenCV and receipt checks. DynamoDB, S3, and authenticated real-camera approvals remain phase-2 code with local tests only.
* The dashboard gate selector simulates approve/deny/timeout; it is not a deployed authenticated human-approval workflow.
* The demo has API throttling but no reserved-concurrency cap because the account quota could not support the reservation.

## License

MIT (see `LICENSE`). Vendored `third_party/prove_it_done` is MIT as well.
