guetteur 0.1.0__tar.gz

guetteur-0.1.0/.github/dependabot.yml

@@ -0,0 +1,19 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      # codeql-action init/analyze/upload-sarif must run the same version.
+      codeql-action:
+        patterns:
+          - "github/codeql-action*"
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "pip"
+    directory: "/INFRA/layer"
+    schedule:
+      interval: "weekly"

guetteur-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build sdist and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --require-hashes -r requirements/release.txt
+          python -m build --no-isolation
+      - name: Wheel carries the vendored verifier and the dashboard
+        run: |
+          python -m zipfile -l dist/*.whl | grep -q 'guetteur/_vendor/prove_it_done/verify_receipts.py'
+          python -m zipfile -l dist/*.whl | grep -q 'guetteur/cloud/dashboard.html'
+      - name: Console script runs from the wheel
+        run: |
+          python -m venv /tmp/wheel-venv
+          /tmp/wheel-venv/bin/python -m pip install --no-deps dist/*.whl
+          /tmp/wheel-venv/bin/guetteur --help

guetteur-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,101 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build sdist and wheel
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.13"
+      - name: Build
+        run: |
+          python -m pip install --require-hashes -r requirements/release.txt
+          python -m build --no-isolation
+      - name: Attest build provenance
+        id: attest
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+        with:
+          subject-path: dist/*
+      - name: Name provenance bundle
+        env:
+          BUNDLE: ${{ steps.attest.outputs.bundle-path }}
+        run: |
+          set -euo pipefail
+          version="${GITHUB_REF_NAME#v}"
+          mkdir provenance
+          jq -c . "$BUNDLE" > "provenance/guetteur-${version}.intoto.jsonl"
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: provenance
+          path: provenance/
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
+
+  github-release:
+    name: GitHub release with provenance
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: provenance
+          path: provenance/
+      - name: Verify provenance and create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          version="${GITHUB_REF_NAME#v}"
+          bundle="provenance/guetteur-${version}.intoto.jsonl"
+          for f in dist/*; do
+            gh attestation verify "$f" \
+              --bundle "$bundle" \
+              --repo "$GITHUB_REPOSITORY" \
+              --signer-workflow "${GITHUB_REPOSITORY}/.github/workflows/release.yml"
+          done
+          awk -v head="## [${version}]" 'index($0, head) == 1 {p = 1; next} p && /^## / {exit} p' CHANGELOG.md > notes.md
+          test -s notes.md || echo "See CHANGELOG.md." > notes.md
+          gh release create "$GITHUB_REF_NAME" \
+            --repo "$GITHUB_REPOSITORY" \
+            --verify-tag \
+            --title "guetteur ${version}" \
+            --notes-file notes.md \
+            dist/* "$bundle"

guetteur-0.1.0/.github/workflows/scorecard.yml

@@ -0,0 +1,56 @@
+name: Scorecard analysis workflow
+on:
+  push:
+    # Only the default branch is supported.
+    branches:
+    - main
+  schedule:
+    # Weekly on Saturdays.
+    - cron:  '30 1 * * 6'
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      # Needed for Code scanning upload
+      security-events: write
+      # Needed for GitHub OIDC token if publish_results is true
+      id-token: write
+
+    steps:
+      - name: "Checkout code"
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: "Run analysis"
+        uses: ossf/scorecard-action@fa7117db83c52d787ae5a89f350999701505d78e # v2.5.0
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          # Scorecard team runs a weekly scan of public GitHub repos,
+          # see https://github.com/ossf/scorecard#public-data.
+          # Setting `publish_results: true` helps us scale by leveraging your workflow to
+          # extract the results instead of relying on our own infrastructure to run scans.
+          # And it's free for you!
+          publish_results: true
+
+      # Upload the results as artifacts (optional). Commenting out will disable
+      # uploads of run results in SARIF format to the repository Actions tab.
+      # https://docs.github.com/en/actions/advanced-guides/storing-workflow-data-as-artifacts
+      - name: "Upload artifact"
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      # Upload the results to GitHub's code scanning dashboard (optional).
+      # Commenting out will disable upload of results to your repo's Code Scanning dashboard
+      - name: "Upload to code-scanning"
+        uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
+        with:
+          sarif_file: results.sarif

guetteur-0.1.0/.github/workflows/security.yml

@@ -0,0 +1,65 @@
+name: Security
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '41 4 * * 0'
+  workflow_dispatch:
+permissions: read-all
+jobs:
+  codeql:
+    name: CodeQL (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [python, javascript-typescript]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: github/codeql-action/init@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
+        with:
+          languages: ${{ matrix.language }}
+      - uses: github/codeql-action/analyze@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
+        with:
+          category: /language:${{ matrix.language }}
+  osv-scanner:
+    name: OSV-Scanner
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    uses: google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@b1d267aea5211fa648d9d442fa64b90dbdcbdd36 # v2.7.0
+    with:
+      scan-args: |-
+        -r
+        --allow-no-lockfiles
+        ./
+  gitleaks:
+    name: gitleaks
+    if: github.event_name != 'schedule'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install gitleaks (checksum verified)
+        env:
+          GITLEAKS_VERSION: 8.30.1
+          GITLEAKS_SHA256: 551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb
+        run: |
+          cd "$RUNNER_TEMP"
+          curl -sSfL -o gitleaks.tar.gz "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
+          echo "${GITLEAKS_SHA256}  gitleaks.tar.gz" | sha256sum -c -
+          tar -xzf gitleaks.tar.gz gitleaks
+      - name: Scan git history
+        run: '"$RUNNER_TEMP/gitleaks" git --redact --no-banner --verbose .'

guetteur-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.aws-sam/
+build/
+dist/
+*.egg-info/
+# generated clips are reproducible from seeds; the committed demo clips live in data/
+/tmp/
+/runs/
+/eval/runs/
+/data/
+/logs/*.tmp
+docs/report/report.html

guetteur-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

guetteur-0.1.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+First PyPI release.
+
+- `pip install guetteur` installs the `guetteur` command (Python 3.12; pinned `opencv-python-headless==5.0.0.93` and `numpy==2.5.4`).
+- The wheel carries the vendored prove-it-done verifier, so `guetteur verify-ledger`, `run --verify`, `demo` and `eval` work from an install. Outside a git checkout, ledger paths are relative to the working directory.
+- The sdist leaves out run logs, evaluation results and submission material (`logs/`, `eval/`, `docs/submission/`, `docs/report/`).
+- Status unchanged: accuracy results are synthetic-only.
+
+## 2026-11-03
+
+No versioned release yet. This section records the repository as of 2026-11-03.
+
+### Added
+
+- Local prototype of Guetteur (Team Drift): design, tests, evaluation on synthetic scenes and an infrastructure draft (`DESIGN.md`, `docs/EVALUATION.md`, `eval/`, `INFRA/`) (8acbd2b).
+- Technical report draft, PDF and diagrams (`docs/report/`), and a credential-free CloudShell deploy kit (`deploy/`) (a2b9f85).
+- Infrastructure template: reserved-concurrency parameter, 7-day log retention on both log groups, and a `HealthUrl` output (a2b9f85).
+- Opt-in native-depth recording and an operator run sheet (`scripts/record_real_depth.py`, `docs/REAL_DEPTH_CAPTURE.md`) (8c347ea).
+- Depth capture teardown check, `scripts/check_depth_shutdown.py` (3a28344).
+- Submission materials for the OpenCV AI Competition powered by AWS: submission story, evidence files and an updated report (6cc6f25); the narrated AWS demo with its recorded responses (a65bbb5); the submission receipt, captions and hosted demonstration (6b6dd1c).
+- `CONTRIBUTING.md`: contributions are released under the repository's MIT licence, and commits carry a DCO sign-off (#1).
+
+### Changed
+
+- Review fixes: a single render endpoint, write routes that fail shut, phase 2 split out in the infrastructure notes, plainer wording, and a note on oak-events integration (a119bca).
+
+### Fixed
+
+- CloudShell deploy fails on a checksum mismatch, handles `REVIEW_IN_PROGRESS` and validates the concurrency quota (65ed788).
+- The HTTP API access log format includes `$context.requestId`; without it the first real deploy ended in `CREATE_FAILED` (f542531).
+- Depth recording no longer accumulates sampling drift or opens the camera twice (ea55597), and guards camera handoffs (3a28344).

guetteur-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# Contributing
+
+Issues and pull requests are welcome: https://github.com/cloudlabworks/guetteur
+
+## Pull requests
+
+- One change per pull request.
+- By contributing you agree your work is released under the MIT licence in `LICENSE`.
+- Commits must be signed off (DCO). Use `git commit -s`; see https://developercertificate.org/.

guetteur-0.1.0/DESIGN.md

@@ -0,0 +1,251 @@
+# Guetteur (Team Drift) — design document
+
+*OpenCV AI Competition 2026, powered by AWS. Target: Overall entry that also qualifies for the **Agentic Vision Award**.*
+Design baseline of 2026-10-12, status corrected 2026-10-14. ~~Nothing is deployed, registered, submitted or published.~~ The public repository and AWS judge endpoint are live; native physical depth capture is verified. ~~The competition submission is not yet complete.~~ Submitted 2026-10-15; Devpost reports SUBMITTED, 5/5 steps. See `docs/submission/submission-receipt.json`. The day-by-day schedule below is the original plan, not a completion claim. Current evidence is in `docs/submission/` and the technical report.
+Rule citations use the short names defined in `docs/RULES_NOTES.md` (DP-Overview, DP-Rules, OCV).
+
+## 0. Read this first: three things that can sink the entry
+
+1. **Eligibility is unverified.** OCV says "Registration closes Aug 17, 2026" ("Competition at a Glance"), that the build phase is for "all teams that submitted the required proposal" ("Build Phase Details"), and lists "Submit the cloud compute grant proposal" under "Requirements for Participation". DP-Overview still shows a Join button and says teams without a grant "remain eligible to continue". We have not established that Team Drift is registered and has a proposal on file. Alex must check before more effort is spent. (Section 12, ask #1.)
+2. **Deadline is stated two ways.** Devpost's header and countdown: Oct 26, 2026 @ **11:45pm PDT**; DP-Overview body text and OCV: **11:59 p.m. PT**. We plan to 11:45pm and aim to submit on **Oct 25**.
+3. **Nothing here has touched real hardware or AWS.** All results are synthetic; every artifact says so. Real OAK-D recordings and a deployed endpoint are the two things the schedule in section 11 exists to deliver.
+
+## 1. One-paragraph pitch
+
+Guetteur is a privacy-first active-perception agent. It watches a space through **depth only** (a Luxonis OAK-D PoE; colour frames never leave the camera), uses **OpenCV 5** to turn depth frames into small, pixel-free evidence (changed regions, people-shaped occupants, sensor health, drift), and lets an agent decide what to do *next* from that evidence: look again with more frames when the signal is ambiguous, pause a zone while someone is standing in it, compensate for sensor drift instead of reporting a phantom change, or stop and ask a human before anything outward-facing happens (default on silence: deny). Every claim it makes ("the shelf item is gone", "the camera lost depth") is a small JSON object with a **receipt**: two independent re-checks against the pinned input, in the [prove-it-done](https://github.com/issaquahd/prove-it-done) format, so a sceptical judge can re-run them and watch a doctored claim fail. A serverless AWS stack (Lambda on Graviton behind API Gateway) runs the same OpenCV 5 loop and receipt checks behind a judge-facing HTTPS endpoint.
+
+## 2. Problem, users, impact
+
+**Problem.** Camera-based AI usually means shipping pictures to someone else's cloud and trusting the system's summary. Two things go wrong: people's images leave the room, and agents report things nobody can check ("zone clear", "item removed") — including when the sensor itself is broken, drifting, or looking at a person it mistakes for a change.
+
+**Users.** (a) Small operators who want to know "did something change on that shelf / in that equipment room / at that door?" without a video archive: stockrooms, labs, makerspaces, server or network closets, community fridges and tool libraries. (b) Homes and care settings where occupancy and "something changed" matter but pictures are unacceptable (always opt-in, with consent; see section 10). (c) Builders of agent systems who need a reference for *verifiable* vision claims.
+
+**Impact we can honestly claim.** We make no statistical claims about harm reduced. What the project demonstrates and measures: (1) a vision agent that works from depth only, so there is no image to leak; (2) fewer false alarms and fewer silent failures than a threshold-and-alert pipeline on the same evidence (measured, synthetic, section 9); (3) every published claim is independently re-checkable. Real-world benefit is a hypothesis until real recordings are evaluated (section 9.4).
+
+## 3. System at a glance
+
+### 3.1 Architecture (OpenCV 5 + agent + AWS)
+
+```mermaid
+flowchart LR
+  subgraph EDGE["Edge: site network (nothing pictorial leaves)"]
+    CAM["OAK-D PoE<br/>colour frames stay on camera<br/>detections + stereo depth only"]
+    OE["oak-events (MIT, MCP)<br/>person events + 6x8 depth-cell events<br/>(shipped; never keeps a depth frame)"]
+    subgraph LOOP["Guetteur agent loop (Python 3.12)"]
+      PERC["OpenCV 5 perception<br/>inpaint / medianBlur / morphology<br/>connectedComponentsWithStats / Farneback"]
+      PLAN["Planner interface<br/>RulePlanner now / LLM slot later"]
+      EXEC["Executor<br/>autonomy policy + evidence guardrails"]
+      GATE{{"Human gate<br/>default on silence: DENY"}}
+    end
+    CAM -->|"depth frames: new opt-in tap (section 3.3)"| PERC
+    CAM --> OE
+    PERC -->|"evidence JSON (no pixels)"| PLAN --> EXEC
+    EXEC -->|"recheck / pause / compensate / degrade"| PERC
+    EXEC -->|"request_approval"| GATE
+    EXEC --> CLM["claim.json + receipt ledger"]
+  end
+  subgraph AWS["AWS (arm64 / Graviton, serverless, pay-per-use)"]
+    APIGW["API Gateway HTTP API<br/>throttled, HTTPS"]
+    LAM["Lambda arm64<br/>OpenCV 5 loop + both receipt checks<br/>(synthetic scenes for judges)"]
+    EV["PHASE 2: evidence intake<br/>x-edge-key, JSON only, pictures rejected"]
+    DDB[("PHASE 2: DynamoDB TTL<br/>approvals + evidence")]
+    S3[("PHASE 2: S3 7-day<br/>opt-in depth snippets")]
+    CW["CloudWatch logs, alarms,<br/>X-Ray, Budget"]
+  end
+  JUDGE["Judge browser<br/>dashboard + tamper button"] --> APIGW --> LAM
+  CLM -->|"evidence bundle (<= 16 KB)"| APIGW
+  APIGW --> EV --> DDB
+  GATE <-->|"approve / deny"| APIGW
+  LAM --- CW
+  EV -.->|"after human approval"| S3
+  VER["prove-it-done verifier<br/>(vendored, re-runnable by anyone)"] -. re-runs checks .-> CLM
+```
+
+### 3.2 Agent workflow (perception → decision → action), as the Agentic Vision evidence requires (OCV "Final Submission Package")
+
+```mermaid
+flowchart TD
+  F["depth frame t (uint16 mm)"] --> O["PERCEIVE: ZoneObservation<br/>valid_frac, noise_ratio, shift, blobs{snr, dz, size, flow}, persist, 6x8 grid"]
+  O --> S{"salient?<br/>(attention gating)"}
+  S -- no --> F2["next frame (planner not called)"]
+  S -- yes --> P["DECIDE: planner(view) -> Action + rationale + cited numbers"]
+  P --> V{"policy: schema, bounds,<br/>budget, evidence preconditions"}
+  V -- "rejected" --> TR["trace: rejected_by_policy"]
+  V -- "autonomous" --> A1["ACT: recheck_zone(n, k)<br/>pause_zone / degrade_zone<br/>compensate_drift(gain)"]
+  V -- "gated" --> H{"ACT: request_approval -> human"}
+  A1 -->|"changes the NEXT perception call"| O
+  H -- approve --> AL["alert published + baseline adopted"]
+  H -- "deny / timeout" --> NO["nothing published, cooldown"]
+  AL --> CL["claim + receipt ledger"]
+  NO --> CL
+  CL --> VF["verify: file sha256 + numpy re-check + OpenCV re-check"]
+  VF -->|"FAIL = step reopened"| P
+```
+
+The loop is closed in two places that matter for the award: `recheck_zone` changes *how OpenCV is called next* (frames integrated, threshold `k`), and the approval request is sized by what OpenCV measured. A fixed-script pipeline cannot do either (ablation in section 9).
+
+### 3.3 Integration with oak-events: what exists and what is new
+
+`oak-events` (shipped) turns each depth frame into a 6x8 grid of cell medians **in memory and drops the frame**; its privacy claim #2 is that no depth map is stored, and it exposes no frame output. Guetteur's OpenCV 5 pipeline needs full depth frames, so the real-camera input is **new code**, not an existing interface. Two options, to be decided on Day 4 after reading the DepthAI pipeline: (a) a hook inside oak-events' camera layer that hands the frame to Guetteur before it is dropped, or (b) a separate DepthAI pipeline in Guetteur (stereo depth only; colour never linked to a host queue, same privacy environment settings). Either way the **clip recorder is new, opt-in code that deliberately does the one thing oak-events promises not to do (keep depth frames), for evaluation only**, with consent, writing to a local directory, and never enabled in the deployed product. The importer to `.npz` on Day 4 belongs to that recorder. Real stereo frames will not match the synthetic assumptions (320x240, 72° field of view, Gaussian noise): `F_PX`, the noise model and the zone geometry are refit on real frames on Days 4–5 before any real-data number is reported.
+
+### 3.4 Data flow, concretely
+
+| Step | Data | Where | Leaves the edge? |
+| --- | --- | --- | --- |
+| capture | colour + stereo | camera chip | colour: never; depth only to host |
+| perceive | depth `uint16[240,320]` per frame | host RAM | no; frame discarded after analysis |
+| evidence | JSON: scalars, up to 3 blobs, 6x8 signed-mm grid | host | only on escalation, <= 16 KB, pictures rejected by schema |
+| claim | JSON: region, frame windows, asserted value, input digest | host disk | optional, same bundle |
+| receipt | re-check of the claim against the **pinned input** | wherever the input is | see 3.5 |
+
+### 3.5 Privacy model, and exactly what a receipt re-runs against
+
+* **Privacy comes from depth-only sensing.** Colour never reaches the host (inherited from `oak-events`: the colour sensor feeds the on-chip detector only). There is no host-side "redaction" step because there is nothing to redact: no code path reads, writes or sends a picture, and a test (`tests/test_synth_and_privacy.py`) scans code, data and run outputs for image/video files and for imaging calls. Depth still reveals occupancy, silhouettes at close range and timing, so event files are treated as sensitive and kept local.
+* **Receipts need an input to re-run against. Two modes, stated plainly:**
+  1. *Recorded or synthetic clips* (demo, evaluation, judge endpoint): the claim pins the clip by content digest (SHA-256 over the depth bytes); `file:` and digest checks fix it. Anyone can re-run the checks.
+  2. *Live operation*: the raw depth stream is **not retained**. The receipt then re-runs only against the reduced evidence (grid and blob statistics) or against a **short depth snippet kept only after a human approved an escalation** (7-day S3 lifecycle, opt-in). A live claim whose snippet was not kept will be labelled "evidence reduced; not re-derivable from raw" in the ledger and never presented as fully re-checkable. **Planned: not implemented yet** (the prototype only handles pinned clips).
+* **What the judge endpoint serves is synthetic**, labelled in the page and in every API response (`synthetic: true`). The endpoint refuses arbitrary uploads and visitor-chosen paths.
+
+## 4. OpenCV 5 usage (substantive, and central)
+
+Pinned: `opencv-python-headless==5.0.0.93` (reports `cv2.__version__ == "5.0.0"`). Headless because a manylinux **aarch64** wheel exists, so the same pin runs on Apple Silicon and on Lambda arm64.
+
+| Stage | OpenCV 5 call | Purpose |
+| --- | --- | --- |
+| holes | `cv2.inpaint(TELEA)` on 16-bit depth | fill invalid stereo pixels without inventing data when coverage is gone |
+| denoise | `cv2.medianBlur(5)` on 16-bit | speckle; its effect on noise is *measured at calibration* (`filt_gain`), not assumed |
+| change | signed difference to a temporal-median baseline, in units of a fitted range-dependent noise model | per-pixel significance |
+| clean-up | `cv2.morphologyEx` OPEN then CLOSE, elliptical kernel | remove specks, merge fragments |
+| blobs | `cv2.connectedComponentsWithStats` | regions; physical size via the pinhole model |
+| motion | `cv2.calcOpticalFlowFarneback` on 8-bit depth renderings | moving vs static; sway of a person |
+| evidence | `cv2.resize(INTER_AREA)` to 6x8 | the only spatial evidence that may leave the device |
+| receipt #2 | `cv2.mean(mask)`, `cv2.meanStdDev`, `cv2.countNonZero` | independent per-frame region statistics |
+
+Per-stage timings on this Mac are in `eval/runtime.json` (`guetteur bench`). OpenCV 5-specific note: results are reproducible with the pinned wheel; we have not benchmarked against OpenCV 4 and make no performance comparison claim.
+
+## 5. Agent design (Agentic Vision rubric: orchestration and autonomy)
+
+* **Tools the planner can call** (`planner.py`): `continue`, `recheck_zone(n, k)`, `pause_zone(frames)`, `degrade_zone(frames)`, `compensate_drift(gain)` — autonomous; `request_approval(kind)` — gated.
+* **Planner interface**: `plan(PlanView) -> Action`. `RulePlanner` is deterministic and is what evaluation runs. `LLMPlanner` takes any `complete(prompt) -> str` (Bedrock Converse is the intended one), gets the same JSON view (no pixels), must answer in the same schema, and **anything outside policy is rejected and replaced by the rule planner's choice, recorded in the trace**. An LLM can therefore be added without widening what the system is allowed to do.
+* **Autonomy tiers (enforced by the executor, not by the planner):** observe, re-look, re-tune and compensate are autonomous and bounded (recheck n in [3,40], at most 3 rechecks per episode, drift compensation capped at ±20% total); anything that tells a human something happened needs `request_approval`.
+* **Evidence guardrails:** an object claim is refused unless the *current* observation shows a confident, persistent, non-occupant blob in a healthy zone; a sensor claim is refused if coverage and gain look healthy. A planner (or LLM) cannot assert what the pixels do not show.
+* **Attention gating:** the planner is only called when the observation is salient (quiet scenes: ~1% of zone-frames), which is also what makes an LLM planner affordable.
+* **Human control:** `HumanGate.decide()` returns approve, deny, or `None` on no answer; `None` is deny. After a decision there is a cooldown so a persistent condition is not nagged every frame. Approval adopts the new scene as baseline. In the cloud (phase 2, **draft code with local tests only, never run on AWS**), approvals would live in DynamoDB with a TTL and expire to `denied_timeout`; those routes fail shut unless a server-side `EDGE_KEY` is configured and sent, so an anonymous visitor cannot approve anything. The first deploy leaves them out entirely.
+* **Observability:** every planner call writes a trace record (frame, zone, observation summary, action, rationale, cited numbers, outcome, planner ms) to `trace.jsonl`; counters for planner calls, rechecks, pauses, rejections, timeouts; local runs write the JSONL trace and counters today; **planned, not built:** Lambda structured logs and metrics in CloudWatch (the template enables X-Ray tracing and alarms on errors/throttles, untested).
+* **Failure handling:** noise burst → degrade zone and wait; partial depth loss → degrade, then escalate if it persists; total loss → confirm for 3 frames then escalate; drift → compensate, escalate beyond 20%; recheck budget exhausted → drop, do not claim.
+
+## 6. Receipts (prove-it-done, vendored)
+
+Each claim is a done step in a ledger with three receipts through different instruments: `file:` (SHA-256 of the claim JSON), `cmd:` numpy-only re-check (never imports cv2; tested), `cmd:` OpenCV frame-statistics re-check. `--min-instruments 2` is required. Independence is partial and we say so: the two checks share the raw input and the claimed region/window, but not each other's estimator or the live pipeline's thresholds. Negative tests (`tests/test_receipts.py`): inflating the claimed value 2x, pointing it at the wrong pixels (objects) or wrong time (sensor/drift), re-pointing it at another recording, and editing the claim file each make the verifier exit 1 — including when the attacker recomputes the `file:` hash. **Tolerance, stated plainly:** a claim passes if the re-measured value is within max(8 mm, 25% of the claim) (coverage ±0.08, gain ±0.01), so small inflations pass by design; the receipts prove a claim is *consistent with the pinned input*, not that the input is the right one.
+
+## 7. AWS services, free-tier fit, and cost note
+
+All serverless, pay-per-use or free-tier eligible; no idle resources (no NAT gateway, VPC, EC2, load balancer, provisioned capacity or Marketplace subscription).
+
+| Service | Role | Cost note |
+| --- | --- | --- |
+| Lambda (arm64/Graviton, python3.12, 1769 MB) | judge dashboard, `/api/run` (OpenCV 5 loop), `/api/verify` (both receipt checks); phase 2 adds authenticated evidence intake | within Lambda's always-free monthly allowance at demo volumes (unverified for a new account); reserved concurrency 5 caps it. Locally the slowest scenario takes ~2.6 s end to end; Lambda timing is **unmeasured** (25 s timeout) |
+| API Gateway HTTP API | HTTPS front door, throttled | priced per request; within free-tier allowance for new accounts at demo volumes |
+| *(phase 2)* DynamoDB on-demand + TTL | approvals, evidence bundles | far below free allowance; TTL clears it |
+| *(phase 2)* S3 (private, SSE, 7-day lifecycle) | opt-in depth snippets after human approval | negligible |
+| CloudWatch Logs/Alarms, X-Ray, SNS, Budgets | observability and cost guard | within free allowances at this volume; a budget alert at 50%/80% of a cap the owner sets |
+
+* Credits: DP-Overview "FREE AWS CREDITS FOR NEW MEMBERS" describes Free Tier credits at Free Plan sign-up (plus more via activities), subject to current Free Tier terms and expiry; we have not verified current terms, and no account exists yet. The design is meant to stay within those credits with margin; the throttles, reserved concurrency and budget alert are the guard rails.
+* **Graviton:** the Lambda runs on arm64 and the wheel is aarch64, so the same code and pin are used on this Mac and in AWS. We do *not* claim the Best Use of COOL award: COOL (Cloud-Optimized OpenCV Library) is acquired through an AWS Marketplace listing, whose terms and pricing we have not reviewed, and the award requires measured COOL-vs-baseline evidence on Graviton (OCV "Focus Paths"). Optional stretch on Day 12 *only if* the listing is free and takes under an hour; otherwise skip.
+* Template draft: `INFRA/template.yaml` (passes `cfn-lint`; not deployed; `sam validate` and `sam build` not run).
+
+## 8. Judge demo (≤ 5 minutes) and the no-camera fallback
+
+Requirements for the video: team, application working, architecture, principal results (OCV "Final Submission Package"). A working web endpoint is preferred over a screen-share (OCV "Requirements for Participation").
+
+**Primary script (all on the AWS endpoint, ~4:30):**
+
+| Time | Shown | Says |
+| --- | --- | --- |
+| 0:00–0:25 | title card, team, one-line pitch | who we are; depth only; receipts |
+| 0:25–0:55 | architecture + agent-workflow diagrams | OpenCV 5, planner, human gate, AWS |
+| 0:55–1:50 | dashboard: scenario `subtle_item_removed`, planner = rule | one frame is ambiguous (3.5σ) → `recheck_zone(n=7)` → OpenCV re-run → approval request; point at the cited numbers |
+| 1:50–2:20 | same scene, planner = naive | misses it: the evidence changed what the agent did |
+| 2:20–3:00 | `person_takes_item`, gate = approve; then `shelf_item_removed`, gate = timeout | zone pauses while occupied; alert only after they leave; silence = nothing published |
+| 3:00–3:30 | `slow_drift`, `noise_burst`, `lens_obstructed` | sensor trouble ≠ scene event; compensate / wait / escalate |
+| 3:30–4:10 | receipts: click "Tamper: double the claim" | both checks FAIL; show `guetteur verify-ledger` PASS on the honest ledger |
+| 4:10–4:40 | results table + failure case (`subthreshold_item_removed`) | what it cannot do |
+| 4:40–5:00 | what is real vs synthetic; thanks | honest labelling |
+
+**Live-camera segment (optional, +30 s, only if Alex records it):** the OAK-D PoE clip replayed through the same loop, labelled "recorded real depth". If not recorded, the video says plainly that all scenes are synthetic.
+
+**Fallback without the camera or the network:** `uv run guetteur demo` (narrated, deterministic, ~15 s), and `uv run guetteur serve` for the same dashboard at 127.0.0.1. The primary script *is* the no-camera path; the camera is an extra, never a dependency. Every screen shows "SYNTHETIC".
+
+## 9. Evaluation plan
+
+### 9.1 Metrics (all computed against machine-readable ground truth)
+Event-level precision/recall of approval requests; scenario success (no false alert, no miss, required behaviours present); latency from event to request (frames and seconds at 5 fps); planner calls per frame; receipt verification rate (honest ledgers proven); tamper rejection rate; per-frame runtime (median/p95/p99) and per-stage OpenCV timings; policy rejections and approval outcomes.
+
+### 9.2 Scenarios (11, ×3 seeds) and baselines
+Control; obvious item removed; item added; subtle item removed (ambiguous); person walkthrough; person takes item; noise burst; slow gain drift; lens obstructed; partial washout; **sub-noise item removed (expected miss)**. Baselines: *naive* (threshold-and-alert, no executor guardrails), *naive + guardrails*, and the rule agent. Results: `docs/EVALUATION.md` (generated by `guetteur eval`). Snapshot (synthetic, 3 seeds, this Mac): the agent succeeded on 30/30 scenarios that are detectable and missed the 3 documented sub-noise runs (precision 1.00, recall 1.00 excluding that case); the raw threshold baseline succeeded on 12/33 with precision 0.25; 21/21 honest ledgers proven; 24/24 tampered ledgers rejected; median 8.6 ms per frame for both zones (p95 11.6 ms) against a 200 ms budget.
+
+### 9.3 Failure cases we report, not hide
+Sub-noise changes are invisible; depth cannot name objects; a person partly outside a zone can be momentarily read as a small change (the persistence rule absorbs it); thresholds were tuned on the same synthetic family they are scored on (an optimistic bias — the reason real recordings matter); noise is Gaussian in the generator but not on a real stereo pipeline.
+
+### 9.4 What real data would add (needs Alex, section 12)
+15–20 min recordings of depth only from the OAK-D PoE in three conditions (empty shelf/door, a person walking through, an item removed), labelled by Alex. Run through the identical loop; report the same metrics next to the synthetic ones. Without these the report says "synthetic only".
+
+### 9.5 Mapping to the Agentic Vision rubric (DP-Rules "AGENTIC VISION AWARD RUBRIC")
+| Criterion (weight) | Evidence we will point to |
+| --- | --- |
+| Substantive OpenCV 5 + agent integration (30) | section 4 table; traces where OpenCV output sets the next call's arguments |
+| Orchestration and appropriate autonomy (25) | autonomy tiers, bounded rechecks, LLM slot behind policy, human gate |
+| Task effectiveness and evaluation (20) | `docs/EVALUATION.md`, ablation vs naive, failure cases |
+| Failure handling, observability, security, human control (15) | sensor-fault paths, trace + CloudWatch, default-deny gate, JSON-only intake, throttles, tamper tests |
+| UX, documentation, demonstration (10) | dashboard, README, ≤5-min video |
+
+## 10. Responsible use
+
+* Depth-only by construction; no faces, no images, no video stored or sent (DP-Rules "RESPONSIBLE AND ETHICAL USE": surveillance risk needs "appropriate safeguards").
+* Intended for spaces whose owner controls the camera and where people present know it is there; for homes and care settings only with the informed consent of everyone monitored. Not for workplace productivity monitoring, tracking individuals, or covert use. Stated in the README and the report.
+* No identification: the system cannot, and is not designed to, say who someone is.
+* Human control: alerts require a person's approval; silence means no alert; claims are labelled with their evidence basis; failures and limits are published.
+* Truthful labelling (DP-Rules: entries may be rejected for misrepresenting "capabilities, results, benchmarks, or the role of human review"): synthetic data is marked synthetic everywhere; the LLM planner is described as an interface until a model is actually wired.
+* Disclosure: the entry was built with AI coding assistance, and the agent in the product is deterministic code with an optional LLM slot; this is stated in the report (using an assistant to write the entry does not itself qualify as Agentic Vision: OCV "Focus Paths").
+* Security of the public endpoint: scenario names and small JSON only, no uploads, no visitor-chosen paths, body size limit, API throttling, reserved concurrency, no secrets in the repo.
+
+## 11. 14-day schedule (today is Oct 12; Day 1 = Oct 13; deadline Oct 26 11:45pm PDT, submit Oct 25)
+
+| Day | Date | Milestone | Done when |
+| --- | --- | --- | --- |
+| 0 | Mon Oct 12 | prototype, tests, design, template draft (this work) | pytest green, eval + bench logs saved |
+| 1 | Tue Oct 13 | **Alex: confirm eligibility/registration; decide go/no-go**; create repo `cloudlabworks/guetteur` after identity scan | answer recorded; repo exists |
+| 2 | Wed Oct 14 | AWS account (Free Plan), budget alert, `sam validate`; `sam build --use-container` | template validates, build ok |
+| 3 | Thu Oct 15 | first deploy = public **read-only** endpoint (no evidence/approval routes); `/healthz` shows `opencv 5.0.0`, `aarch64`; time every scenario on Lambda against the 25 s timeout | curl receipt passes; timings recorded; repo stays private until then |
+| 4 | Fri Oct 16 | decide the depth tap (section 3.3); new opt-in recorder writes depth-only `.npz`; record real clips (Alex + OAK-D, ~1 h) | 3 labelled clips on disk (outside git if large) |
+| 5 | Sat Oct 17 | **refit `F_PX`, noise model and zones on real frames** (they will differ from 320x240 / 72° / Gaussian); run real clips through the loop; tune only on a held-out split; add real-data metrics | numbers in `docs/EVALUATION.md` |
+| 6 | Sun Oct 18 | LLM planner wired to Bedrock behind the same policy (only if account/model access is straightforward; otherwise leave as interface and say so) | rejection tests pass with the real model |
+| 7 | Mon Oct 19 | deploy phase 2: DynamoDB, S3, evidence/approval routes behind `x-edge-key`; **deployed negative test** (no key / wrong key → 403); S3 snippet re-check function | negative tests pass on AWS |
+| 8 | Tue Oct 20 | edge → cloud path end to end with a real clip; approval round trip through the cloud; **replay of Alex's recorded clips on Lambda** | approval round trip in logs; real-clip result from the endpoint |
+| 9 | Wed Oct 21 | technical report draft (from this document + results) | draft in `docs/REPORT.md` |
+| 10 | Thu Oct 22 | architecture + workflow diagrams final; load/abuse test of the endpoint; cost check against credits | throttle and alarm demonstrated |
+| 11 | Fri Oct 23 | video recording (script in section 8); screenshots | raw video |
+| 12 | Sat Oct 24 | video edit; README polish; fresh-clone test of every command; (optional COOL probe) | clean clone passes |
+| 13 | Sun Oct 25 | **submit** (Alex presses the button); endpoint check from outside the network | submission confirmation saved |
+| 14 | Mon Oct 26 | buffer only; no new features; deadline 11:45pm PDT | — |
+
+Cut order if time slips: COOL probe → LLM wiring → live-camera segment in the video. **Never cut:** deployed endpoint; receipts + tamper demo; failure cases; honest labelling; an approval round trip through the cloud; replay of the recorded real clips on Lambda (without them AWS only replays synthetic scenes, which weakens "a meaningful component on AWS", OCV "Requirements for Participation").
+
+## 12. What needs Alex
+
+1. **Eligibility check (blocking).** Is Team Drift registered on Devpost and did it submit the grant proposal? (Section 0, `docs/RULES_NOTES.md` #1.) If no, decide whether to ask `competition@opencv.org` (the contact on OCV "Contact & Questions") — we will not contact anyone on our own.
+2. **AWS account**: create a Free Plan account under Cloud Lab Works (never a personal or employer account); set the budget figure; enable MFA; confirm the owner's alert email. We have no AWS credentials and did not look for any.
+3. **Budget decision**: choose the monthly budget-alert figure (the template deliberately has no default) and confirm that staying within Free Tier/promo credits is the rule; say whether Bedrock model calls (Day 6) are in or out.
+4. **Camera time**: ~1 hour with the OAK-D PoE on Day 4 (depth-only recordings of an empty shelf/door, a walk-through, an item removed) and a few minutes of labelling. No faces or identifiable people in any clip; anyone in frame must consent.
+5. **Press submit** on Oct 25; the team representative handles the Devpost form (DP-Rules "ELIGIBILITY AND FAIR PLAY").
+6. **Repo publication**: create `cloudlabworks/guetteur` as **private** (OCV "Final Submission Package" allows a private, judge-accessible repository), run the identity scan (noreply email, no employer material) before the first push, and make it judge-accessible only at submission.
+
+## 13. Risks (ranked)
+
+1. Not eligible / no proposal on file (section 0).
+2. Synthetic-only evidence reads as weak "technical execution"; mitigated only by real clips (Day 4–5).
+3. First AWS deployment problems (arm64 layer build needs Docker; Lambda 25 s timeout vs ~2.6 s worst case locally with Lambda timing unmeasured; cold start); Day 2–3 buffer.
+4. Overfit to our own generator: thresholds tuned on the family they are scored on.
+5. "Agentic" read as rules-with-extra-steps: the LLM slot is not wired until Day 6; the award text allows "any framework or model" (OCV "Focus Paths"), and the loop still satisfies "image or video results must influence a subsequent plan, tool call, action, or request for human approval".
+6. Cost or abuse on a public endpoint: throttle, reserved concurrency, budget alert, no uploads.
+7. Devpost/organiser rule drift: the pages defer to an "Official Rules" document we did not find; re-read all pages on Day 12.