Auditable agentic visual inspection that knows when to act, reinspect, or ask a human.
IX-VisualAuthority is a judge-ready OpenCV 5 inspection agent by Bryce Lovell for the OpenCV AI Competition 2026, powered by AWS. It measures whether an image is trustworthy, aligns it to a known-good reference, localizes differences, chooses the next visual tool, and stops at an explicit human boundary before a high-impact quarantine.
This is not a chatbot around a classifier. A measured visual result changes the next plan and the actions the system is allowed to propose.
| Requirement | Working proof in this repository |
|---|---|
| Substantive OpenCV 5 | Laplacian quality gate, ORB, Hamming matching, RANSAC homography, CIELAB difference, morphology, contours, ROI verification |
| Agentic vision | visual output → validated next-tool choice → focused reinspection → governed disposition |
| AWS integration | optional Amazon Bedrock Converse tool use, encrypted/versioned S3 evidence, CloudWatch metrics, ARM64 ECS Fargate CloudFormation |
| Human control | the agent can propose quarantine but a named human must approve it |
| Auditability | canonical SHA-256 linked receipts, world-state fingerprint, export and independent verification |
| Failure behavior | live blur, displacement, occlusion, anonymous approval, invalid planner, and tamper cases |
| Reproducibility | pinned runtime, deterministic media, Windows/Unix scripts, Docker, strict tests, evaluation JSON, release verifier, ARM64 CI |
flowchart TD
A[Reference + observation] --> B[OpenCV quality]
B -->|bad frame| C[Recapture / hold]
B -->|usable| D[OpenCV registration]
D -->|reliable| E[OpenCV localization]
D -->|unreliable| C
E -->|clear| F[Pass]
E -->|occluded| C
E -->|local region| G[OpenCV ROI verification]
G --> H{Authority firewall}
H -->|confirmed defect| I[Named human approval]
I --> J[Simulated command + state re-observation]
The deterministic planner makes the built-in demo fully offline and repeatable. The optional Bedrock planner uses the same closed tool vocabulary. Its output is validated locally, failures are recorded, and neither planner can bypass the authority firewall.
Requirements: Git and Python 3.12 on PATH.
git clone https://github.com/BryceWDesign/IX-VisualAuthority.git
cd IX-VisualAuthority
.\scripts\setup.ps1
.\scripts\run-demo.ps1Open http://127.0.0.1:8000. The OpenAPI contract is at http://127.0.0.1:8000/api/docs.
git clone https://github.com/BryceWDesign/IX-VisualAuthority.git
cd IX-VisualAuthority
python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
./scripts/run-demo.shNo AWS account, dataset, model weight, CDN, external font, or JavaScript package is required for the five built-in cases.
| Scene | Visual plan | Expected result |
|---|---|---|
| Nominal | quality → register → localize | pass |
| Local defect | quality → register → localize → ROI verify | quarantine_pending_approval |
| Motion blur | quality → stop | recapture |
| Camera offset | quality → register → localize | pass after alignment |
| Large occlusion | quality → register → localize | hold for visibility |
On the defect case, enter a real demonstrator name to cross the human boundary. The included adapter records a simulated quarantine command and world-twin acknowledgement. It does not actuate equipment or claim a physical sensor result.
.\.venv\Scripts\pytest.exe --cov --cov-report=term-missing --cov-fail-under=85
.\.venv\Scripts\python.exe -m ix_visual_authority evaluate --output evidence\evaluation.json
.\.venv\Scripts\python.exe scripts\verify_release.pyCurrent checked-in local result, generated on Python 3.12.13 / OpenCV 5.0.0 / x86_64 Linux:
| Gate | Measured result |
|---|---|
| Automated tests | 41 passed |
| Declared scenario outcomes | 5 / 5 |
| Declared ordered tool plans | 5 / 5 |
| Receipt-complete runs | 5 / 5 |
| Unsafe-scene false passes, single-score baseline | 2 |
| Unsafe-scene false passes, IX-VisualAuthority | 0 |
| Anonymous high-impact approval blocked | yes |
| Mutated receipt rejected | yes |
| Test coverage gate | ≥ 85% |
The raw evaluation JSON is the source of truth and
includes per-scene latency. It is a deterministic synthetic functional benchmark,
not an estimate of factory accuracy or generalization. The simple baseline is a
global normalized-correlation score without quality, registration, ROI,
authority, or receipts. Regenerated per-run images and bundles stay in the ignored
evidence/sample_runs/ working directory.
Bedrock selects the next client-side visual tool through the Converse API; the application executes the OpenCV operation and validates the subsequent state.
$env:IXVA_PLANNER = "bedrock"
$env:AWS_REGION = "us-east-1"
$env:IXVA_BEDROCK_MODEL_ID = "your-enabled-tool-use-model-or-profile"
.\scripts\run-demo.ps1Use a model/profile that supports Converse tool use and rely on the standard AWS SDK credential chain. Do not put credentials in this repository. Evidence marks each choice as Bedrock, deterministic, or deterministic fallback.
The supplied stack runs an ARM64 container on ECS Fargate behind an Application Load Balancer and connects it to private S3 evidence storage and CloudWatch.
- Build and push the container for
linux/arm64. - Validate and deploy infra/cloudformation.yaml.
- Run the full demo runbook against the returned URL.
- Add that actual working URL to Devpost.
Exact PowerShell commands, IAM boundaries, Bedrock parameters, verification, and cleanup are in AWS deployment.
Claim status: this checked-in evaluation proves local x86_64 execution. It does not claim that AWS or Graviton was run. The Graviton capture script refuses to write proof unless it detects both ARM64 and an AWS execution environment.
| Route | Purpose |
|---|---|
GET /api/health |
OpenCV version, planner, artifact-store health |
GET /api/scenarios |
declared demo cases and expected plans |
POST /api/inspect |
inspect a built-in deterministic case |
POST /api/inspect/upload |
inspect a base64 reference/observation pair |
POST /api/runs/{id}/approval |
named approve/reject decision |
GET /api/runs/{id}/evidence |
export the complete receipt chain |
POST /api/evidence/verify |
verify chain sequence, links, hashes, count, head |
GET /api/metrics |
in-process run, disposition, and receipt totals |
src/ix_visual_authority/
vision.py OpenCV 5 visual tools
planner.py deterministic + Bedrock tool planners
authority.py fail-closed action policy
orchestrator.py plan/observe/act/reobserve loop
evidence.py canonical receipt chain and artifact store
world_twin.py versioned asset state and fingerprint
api.py FastAPI judge/operator contract
static/ dependency-free responsive interface
infra/ ARM64 ECS Fargate CloudFormation
tests/ visual, agent, authority, evidence, API, AWS tests
evidence/ reproducible raw evaluation result
submission/ Devpost copy, pitch, video script, demo/final checklists
docs/ architecture, report, evaluation, AWS, safety, security
- Technical report
- Architecture
- Evaluation design
- Testing and release gates
- Security model
- Responsible use and limitations
- Prior work and clean-room boundary
- Devpost-ready story
- 4:35 video script
- Final submission checklist
The receipt chain detects alteration, deletion, insertion, or reordering against a trusted head. It is not a digital signature: an attacker able to replace and recompute an entire bundle could create a new internally consistent head. A production deployment should sign or externally anchor run heads, use production identity, and preserve them through an independent retention system.
Copyright © 2026 Bryce Lovell. All rights reserved.
This repository is source-available under the custom Hackathon Evaluation License, not MIT or Apache. It permits competition organizers and judges to clone, run, and inspect the project for evaluation while reserving production, redistribution, derivative-work, and commercial rights. Competition-submitted materials remain subject to the official competition terms. This is not legal advice.
The five author-owned donor repositories informed architectural ideas but no donor source file is copied into or imported by this runtime. See PRIOR_WORK.md and third-party notices. OpenAI Codex assistance is disclosed in AI_DISCLOSURE.md.