Developer onboarding guide to DVSA-API (https://github.com/ravibeta/dvsa-api)

 

Core components to harden for onboarding:

1.      Web API and pipeline entrypoints The apps/videos and agent_kits modules are the primary entrypoints. They should be documented as “developer surfaces”:

a.      REST endpoints for video upload, analysis runs, and analytics queries (e.g., detections per video, per mission).

b.      Agent kits (local_interactive, cloud_autonomous, orchestration) as runnable examples: “run this pipeline on a sample video,” “run unattended in the cloud,” “partition and merge large runs.”

Spec: stabilize and document:

c.      VideoUploadAPIView contract (request/response JSON, supported storage backends).

d.      RunAnalysisView contract (which routines, which adapters, how to pass parameters).

e.      A canonical run_pipeline signature and its expected inputs/outputs.

2.      Analytics routines and model adapters The apps.analytics routines and custom_model ONNX adapter are your equivalent of ADE’s “schemas and extraction logic.”

Spec:

a.      Define a canonical detection schema (id, label, bbox, confidence, world_coord, source, model_version, mission, project).

b.      Document how to register a new routine in apps.analytics.routines and how to plug in a new adapter (e.g., Triton, Ray Serve, Rekognition, Azure Vision).

c.      Provide at least one sample custom model (ONNX) with labels and a ready‑to‑run routine (custom_onnx_detection) that uses real aerial imagery.

3.      Storage adapters and data layout The storage adapters already support Azure/S3/local. For onboarding, you want a standard layout for drone video and frames:

a.      Video objects (original uploads) in videos/ or raw/.

b.      Extracted frames in frames/ with predictable naming (video_id/frame_id.jpg).

c.      Detections in a structured store (DB + optional S3 JSON manifests).

Spec:

d.      Document the storage layout and how to configure it via .env (AZURE_*, S3 settings, local paths).

e.      Provide a sample storage_config.yaml or .env snippet for each backend.

4.      Observability and run introspection You already have an observability app; onboarding needs developer‑visible run introspection:

a.      Per‑run logs and metrics (frames processed, detections per label, latency).

b.      Simple UI or API to fetch “run summary” for a video.

Spec:

c.      Define a RunSummary API: given video_id, return counts, latency stats, and links to detections.

d.      Add a minimal HTML or JSON view that developers can hit in a browser or via curl.

Developer‑facing “Gallery” for drone video with a Drone Sensing Gallery that lives in docs/gallery.md and a small static front‑end:

Examples (each with a sample video, screenshots, and a short description):

·        “Detect vehicles in high‑resolution aerial imagery”

·        “Track moving objects across frames and compute trajectories”

·        “Detect construction equipment and safety violations on job sites”

·        “Detect crop health anomalies using NDVI or RGB imagery”

·        “Detect people and vehicles near restricted zones (geofenced alerts)”

·        “Handle shaky drone footage and variable frame rates”

·        “Handle mixed resolutions and camera poses (different drones)”

Spec:

·        For each gallery item, provide:

o   A sample video (or short clip) in infra/demo/videos/.

o   A JSON manifest of detections.

o   A short narrative: what the pipeline does, which routines/adapters are used, and how to run it (agent_kits command or API call).

·        Add a simple static page (Django template or React/Vue) that lists these examples with links to run them locally.

Sample projects layout (ADE‑style) where ADE organizes sample projects into Workflows, Use_Cases, Events inside dvsa‑api (or as a sibling repo):

·        sample_projects/Workflows/

o   basic_ingest_and_detect/ — minimal pipeline: upload video, extract frames, run a detector, store detections, query via API.

o   batch_analysis_with_celery/ — show Celery‑driven large video analysis.

o   cloud_autonomous_runner/ — show FastAPI cloud runner processing videos from a queue.

·        sample_projects/Use_Cases/

o   traffic_monitoring/ — detect vehicles, compute counts per road segment.

o   construction_site_safety/ — detect people vs equipment, flag proximity violations.

o   agriculture_scouting/ — detect crop stress regions.

·        sample_projects/Events/

o   Hackathon or conference demos (e.g., “Drone Safety Demo 2026”).

·        sample_projects/Other/

o   Utilities: frame extractor scripts, dataset converters, labeling helpers.

Each sample project should have:

·        Its own README.md with setup and usage.

·        A requirements.txt or pointer to dvsa‑api’s requirements/base.txt.

·        A small test suite (pytest) that validates the pipeline on a tiny sample video.

Developer quickstart (drone video version) with existing local dev setup in the README.md.

Spec for a Drone Video Quickstart:

·        Step 0: clone dvsa‑api, create venv, install requirements/base.txt, configure .env (DB, Celery, storage).

·        Step 1: run Django + Celery (python manage.py runserver, celery -A config worker -l info).

·        Step 2: run agent_kits.local_interactive.cli_wrapper with a provided sample video:

Bash:

python -m agent_kits.local_interactive.cli_wrapper run \
  --video file:///path/to/sample_drone_video.json \
  --routine custom_onnx_detection \
  --dry-run

·        Step 3: run a non‑dry pipeline and then query detections via REST:

Bash:

curl -s http://localhost:8000/api/analytics/videos/1/detections/ | jq .

·        Step 4: open the Gallery page and see the run visualized.

The quickstart should be a single docs/quickstart_drone_video.md plus a demo.sh that automates most of it.

Contracts and schemas to make dvsa‑api “plug‑and‑play” for developers with specific JSON contracts:

·        Video upload request/response.

·        Frame representation (id, timestamp, s3_uri or local path, camera_pose, sensor_meta).

·        Detection representation (as above).

·        Mission/project metadata (tags, geofences, sampling policies).

Spec:

·        Add docs/contracts/video.json, frame.json, detection.json, mission.json.

·        Ensure apps/videos and apps/analytics endpoints return these canonical shapes.

·        Document how agent_kits expect video manifests (e.g., JSON describing video URI, frame extraction settings, mission metadata).

Front‑end and visualization for dvsa-api add to the existing dvsa-ui (https://github.com/ravibeta/dvsa-ui) the following:

·        A simple web UI that:

o   Lists videos and their analysis status.

o   Shows detections overlaid on frames (bounding boxes, labels, confidence).

o   Shows geospatial overlays (world_coord on a map) for trajectories.

Spec:

·        Add a minimal front‑end under apps/frontend or frontend/:

o   Use Django templates or a small SPA (React/Vue).

o   Consume existing REST endpoints (videos, analytics/detections).

·        Provide a “Gallery” view that links to each sample project and shows screenshots.

Tests, CI, and reproducibility to make dvsa‑api safe to extend:

·        Expand tests/ to include:

o   Pipeline tests for each sample project (run on tiny videos).

o   Contract tests for REST endpoints (JSON shapes).

o   Adapter tests (ONNX, cloud AI, Rekognition) with mocks.

·        CI:

o   Run pytest -q on every PR.

o   Optionally run a small end‑to‑end demo (sample video) in CI with mocked adapters.

Spec:

·        Add tests/sample_projects/ with one test per sample.

·        Add scripts/run_demo_pipeline.sh that CI can call.

Infra and deployment templates with exisitng infra/terraform and docker‑compose.

Spec:

·        Provide a infra/demo/drone_sensing_stack/:

o   docker‑compose for Django, DB, Celery, storage (local or S3 emulator).

o   Optional OTel/Honeycomb observability if you keep that spec.

·        Provide Terraform or Bicep templates for cloud deployment (Azure, AWS) with:

o   dvsa‑api app service / ECS.

o   Storage (blob/S3).

o   Queue/broker (Redis, RabbitMQ).

Implementation checklist (high‑level) roadmap:

·        Week 1–2:

o   Define and document canonical contracts (video, frame, detection, mission).

o   Harden apps/videos and apps/analytics endpoints to use them.

o   Add one end‑to‑end sample project (basic_ingest_and_detect).

·        Week 3–4:

o   Build Drone Sensing Gallery (docs/gallery.md + simple UI).

o   Add 2–3 use‑case sample projects (traffic, construction, agriculture).

o   Add quickstart doc and demo.sh.

·        Week 5–6:

o   Expand tests and CI for sample projects.

o   Add infra demo stack and cloud deployment templates.

o   Polish docs (docs/integrations, docs/contracts, docs/gallery).

References: previous article: https://1drv.ms/w/c/d609fb70e39b65c8/IQBLgFai-AMCSJvSvzTXi5sXAd-RcY1cWwzO9iImLLwr9RU?e=GNbf9c