Skip to content

Latest commit

 

History

History
173 lines (141 loc) · 6.6 KB

PRD.md

File metadata and controls

173 lines (141 loc) · 6.6 KB

LURCHER — Product Requirements Document

ANIMA Wave-10 WARDOG Module #26

  • Codename: LURCHER
  • Focus: UAV/Drone tracking for Shenzhen Robot Fair defense scenarios
  • Paper: Layer-Guided UAV Tracking (LGTrack), arXiv:2602.13636
  • Reference code: https://github.com/XiaoMoc/LGTrack
  • Current phase: Initial autopilot bootstrap completed

1. Objective

Build a production-ready ANIMA module that reproduces and adapts LGTrack’s layer-guided ViT tracking for UAV defense workloads, with mandatory dual backend support (mlx, cuda, cpu) and YOLO26-compatible integration points.

2. Non-Negotiable Constraints

  • Scope only inside project_lurcher/.
  • All runtime entrypoints must accept --backend mlx|cuda|cpu|auto.
  • Cross-backend numerical parity targets:
    • fp32: atol <= 1e-4
    • fp16: atol <= 1e-2
  • If detector hooks are needed, default family is YOLO26.
  • Shared datasets are read-only.

3. Paper Verification Summary

3.1 What was verified

  • Paper PDF exists locally and was fully read (papers/2602.13636.pdf).
  • Reference implementation exists and is non-empty (repositories/LGTrack).
  • Core claims and training recipe were extracted from paper sections §3.x and §4.x.
  • Core reported benchmark points captured:
    • UAVDT: Prec 82.8, Succ 60.4, 258.7 FPS (GPU)
    • CPU speed reference: 59.4 FPS

3.2 Red flags

  • External reproductions/citations are still limited (new paper risk).
  • Upstream repo lacks explicit license file.
  • Public UAVDT URL reliability was inconsistent during checks.
  • Upstream codebase targets older CUDA/PyTorch versions.

3.3 Verdict

Paper is usable for implementation and adaptation. Continue execution with CTO visibility on risks.

4. Scope

4.1 In scope

  • Implement paper-grounded components:
    • SGLA dynamic deep-layer selection
    • GGCA attention refinement
    • ORR occlusion-robust consistency loss
  • Build train/infer scaffolds in src/anima_lurcher/.
  • Generate full PRD/task suite and execution index.
  • Provide dataset preflight tooling and reproducibility checklist.

4.2 Out of scope (current wave checkpoint)

  • Full scale multi-day training on 1.8M internal data.
  • Final ROS2/Gazebo deployment hardening.
  • TensorRT packaging and full edge benchmark matrix.

5. Target Users and Use Cases

  • ANIMA perception engineers reproducing paper baselines.
  • Wave-10 integrators composing multi-module UAV defense stack.
  • Shenzhen demo operators requiring low-latency UAV tracking under occlusion.

6. Functional Requirements

FR-1: Configuration and bootstrap

  • Central TOML config exists and loads deterministically.
  • Paper hyperparameters are represented explicitly in config.

FR-2: Core model scaffold

  • A testable LGTrack-like model exists with:
    • Transformer token flow
    • SGLA selector and labels
    • GGCA feature refinement
    • ORR training-time consistency branch

FR-3: Inference entrypoint

  • CLI inference smoke path runs on CPU by default.
  • YOLO26 loader hook is present and lazy.

FR-4: Training entrypoint

  • CLI dry-run training loop executes end-to-end.
  • Includes bbox loss, ORR loss, and SGLA selector supervision.

FR-5: Verification and tests

  • Unit tests cover config/device/model shape assumptions.
  • All tests run from project root with pytest -q.

FR-6: Documentation

  • Full ASSETS.md, prds/, and tasks/ suite exists.
  • NEXT_STEPS.md and MODULE_TODO.md reflect current state.

7. Non-Functional Requirements

  • Deterministic behavior for smoke tests.
  • No hard dependency on MLX/CUDA for CPU smoke tests.
  • Backends resolved in priority order when auto is used.
  • Codebase remains modular for later API/ROS2 integration.

8. Architecture Overview

8.1 High-level flow

  1. Input template/search images.
  2. Patch embedding + Transformer blocks.
  3. SGLA predicts optimal deep layer activation after saturation point (l*=8).
  4. Search tokens reshaped to feature map and refined by GGCA.
  5. Score/box heads produce prediction maps.
  6. Training mode computes ORR consistency under Cox-style masking.

8.2 Current file map

  • src/anima_lurcher/device.py — backend resolver and tolerance helpers
  • src/anima_lurcher/config.py — typed config loading
  • src/anima_lurcher/model/sgla.py — selector and similarity labels
  • src/anima_lurcher/model/attention.py — GGCA implementation
  • src/anima_lurcher/model/occlusion.py — ORR masking/loss helpers
  • src/anima_lurcher/model/lgtrack.py — assembled LGTrackLite model
  • src/anima_lurcher/infer.py — inference smoke entrypoint
  • src/anima_lurcher/train.py — training dry-run entrypoint
  • src/anima_lurcher/yolo26.py — YOLO26 integration hook

9. Data Plan

  • Shared volume first: /Volumes/AIFlowDev/RobotFlowLabs/datasets/
  • Preflight script: bash scripts/download_data.sh
  • Current observed state:
    • VisDrone staging folder found
    • UAVDT/DroneVehicle/SeaDronesSee presence not yet fully validated locally
    • 1.8M internal dataset not yet enumerated

10. Milestones and Exit Gates

M1 — Verification + Scaffold (completed)

  • Paper/repo verified
  • Initial code scaffold
  • Unit tests green
  • PRD/task suite generated

M2 — Reference reproduction

  • Wire real dataset loaders
  • Reproduce close-to-paper metrics on UAVDT/UAV123/DTB70
  • Document deviations and reasons

M3 — Wave adaptation

  • Integrate YOLO26 tracks and internal 1.8M data
  • Run dual backend parity checks
  • Produce updated benchmark report

M4 — Integration

  • API serving + Docker profile
  • ROS2 bridge and launch artifacts
  • Production export and monitoring

11. Acceptance Criteria (Current Deliverable)

  • Paper and repo read/verified with explicit risk notes.
  • Initial LGTrack-based code exists and runs smoke paths.
  • Tests pass locally (5 passed).
  • Full 7-PRD suite exists under prds/.
  • Granular task suite exists under tasks/ with build order index.
  • YOLO26 default is represented in configuration and integration hook.

12. Dependencies

  • Internal datasets and model storage mounts.
  • Optional GPU server for heavy training.
  • Sibling Wave-10 YOLO26 fine-tune output (if consumed directly).

13. Risks and Mitigations

  • Reproduction drift vs paper numbers.
    • Mitigation: keep phase-2 benchmark report with exact settings and deltas.
  • Dataset gaps or format inconsistencies.
    • Mitigation: data adapter layer + schema checks before training.
  • Backend divergence (MLX vs CUDA).
    • Mitigation: parity tests with tolerance thresholds in CI.

14. Deliverables in this pass

  • Full documentation scaffold for /anima-autopilot execution.
  • Executable initial code package for LGTrack adaptation.
  • Verification ledger updates and actionable next steps.