About DVSA-API:
ORIGIN:
This document is split into ORIGIN and CURRENT-STATE of DVSA-API.
ORIGIN repository:
https://github.com/ravibeta/ezvision/tree/main/venv/my_droneworld_api and https://github.com/ravibeta/ezvision/tree/main/venv/my_droneworld_ui
The repository contains a two-tier DroneWorld web application for uploading drone/video footage, indexing and analyzing it, and presenting managed video records through a browser UI. It is split into a Django-based REST backend and a React/TypeScript frontend.
Overall architecture
Layer Location Role
Backend API venv/my_droneworld_api Django service that stores video metadata, accepts uploads, invokes analysis/indexing logic, and exposes API routes
Frontend UI venv/my_droneworld_ui React/TypeScript single-page application for registration, sign-in/out, video upload, and video management
Analysis domain venv/my_droneworld_api/videos The main Django app containing models, handlers, routing, serializers, signals, and substantial video-analysis/indexing modules
The code layout suggests a workflow of: user authenticates in the UI → uploads an MP4/video → backend persists a video record → backend processes/indexes video → UI retrieves and manages the resulting video information.
Backend: my_droneworld_api
This portion is a conventional Django project, evidenced by manage.py, project-level settings.py, urls.py, and ASGI/WSGI entrypoints. It has a dedicated videos application where the functional logic resides.
Key backend components
• my_droneworld_api/views.py, urls.py, and serializers.py provide project-level API configuration and serialization infrastructure.
• videos/models.py defines persistent domain models for video-related entities. Its presence alongside Django migrations indicates the system is intended to track video state and metadata in a relational database rather than treating uploads as transient jobs.
• videos/views.py is the main HTTP-handler layer, while videos/urls.py binds the application’s video-oriented endpoints.
• videos/serializers.py shapes video data for API responses and request handling; signals.py suggests lifecycle-triggered behavior, such as automatically kicking off processing after model creation or change.
• admin.py likely exposes these models for operational access through the Django admin interface.
Video intelligence pipeline
The videos app is much more than a CRUD upload service. It contains three substantial analysis-oriented Python modules:
• analyzer_functions.py — approximately 21 KB of reusable analysis functions.
• myvideoanalyzer.py — approximately 53 KB, likely the principal orchestration/analysis implementation.
• myvideoindexer.py — approximately 35 KB, likely responsible for creating searchable or structured indexes from video-derived content.
• perplexity.py — a small integration/helper module, potentially intended for LLM-assisted interaction or analysis.
That split is a sensible design for drone-video intelligence: keep API request handling in views, persistence in models, reusable computer-vision/data functions separate, and high-level analysis/indexing routines in specialized modules. It also makes it possible to evolve toward asynchronous job execution without rewriting the API surface.
Backend dependencies and deployment shape
The presence of requirements.txt, ASGI, and WSGI suggests the backend can run in traditional Django server environments and potentially under an async-capable deployment stack.
A notable repository-layout caveat: placing application code beneath venv/ is unconventional. Normally, venv is excluded from source control and reserved for local Python virtual-environment files. Here it appears to be a project directory name or a checked-in location for application code rather than a standard disposable virtual environment.
Frontend: my_droneworld_ui
The frontend is a React application written in TypeScript. The root includes package.json, a large npm lockfile, tsconfig.json, a standard public/ directory, and a typical src/ implementation directory.
Main user-facing capabilities
The source filenames reveal the core product surface:
• RegistrationPage.tsx — new-user registration flow.
• SignIn.tsx and SignOut.tsx — authentication entry/exit flows.
• UserContext.tsx — shared client-side user/session state.
• UploadVideoPage.tsx, Uploader.tsx, and MP4Uploader.tsx — video-upload experience, explicitly including MP4 support.
• VideoManager.tsx — a management interface for uploaded/processed videos.
• Privacy.tsx — a privacy-policy or privacy-information page.
• Header.tsx and Footer.tsx — persistent site chrome.
• App.tsx — top-level application composition and likely routing/navigation state.
The UI therefore appears designed as an end-user portal rather than merely an internal analyst console: it includes account creation, authentication state, privacy messaging, media upload, and a post-upload management experience.
Functional interpretation
At a product level, DroneWorld appears to be a lightweight drone/video analytics platform with these responsibilities:
1. Identity and access — register users, sign them in, maintain user context, and sign them out.
2. Media ingestion — provide browser-side video upload components, including an MP4-specific uploader.
3. Backend video management — create and maintain persisted records for submitted videos.
4. Video processing — invoke dedicated analyzer logic to derive information from the footage.
5. Indexing and retrieval readiness — organize processed video-derived information through a separate indexer module.
6. Results management — show users their videos and likely their processing/output state in VideoManager.
For your broader drone analytics work, the important design idea is the separation between ingestion, analysis, and indexing. That is the right boundary if you eventually want to replace local/synchronous processing with queued GPU workers, cloud object storage, temporal metadata stores, vector retrieval, or LLM-assisted querying—without disrupting the UI and REST contract.
CURRENT-STATE of DVSA-API (https://github.com/ravibeta/dvsa-api)
dvsa-api is the production-oriented successor to the earlier DroneWorld/EZVision backend: it retains the original platform’s video ingestion, Azure-connected indexing, computer-vision analysis, and chat-style reasoning, but reorganizes those capabilities into a modular, testable, offline-first drone-video-sensing platform. It has grown from a Django video-analysis API into an extensible system for CV inference, retrieval and LLM reasoning, observability, distributed orchestration, and MCP-native agent integration.
Evolution from DroneWorld
The earlier my_droneworld_api was a Django service focused on video records, upload/processing handlers, dedicated video-analysis and indexing modules, and integrations around Azure/video intelligence. dvsa-api explicitly ports and generalizes that runtime: the commit history identifies a migration of the remaining EZVision/DroneWorld runtime into core.azure.SessionAzureEnvironment, including AI Vision vectorization and image analysis, Azure Blob/SAS handling, Azure Video Indexer workflows, Foundry agentic runtime, CV routines, Perplexity retrieval, and document/geolocation indexing.
The change is architectural, not merely a rename:
Area Original DroneWorld backend DVSA API
Application shape Django project with a central videos app and large analysis/indexing modules Django platform organized into domain apps plus reusable core, reasoning, agent, connector, and infrastructure packages
Video processing Video upload, analysis, and indexing closely concentrated around video modules Video entities, asynchronous analytics routines, Azure ingestion/indexing, model adapters, metadata, and observability are distinct subsystems
Cloud integration Azure-oriented service logic embedded in the original backend Session-scoped, configurable Azure environment with dry-run, SDK, and Terraform-oriented provisioning approaches
Intelligence layer Video analysis plus early retrieval/chat capabilities CV routines, model selection, structured commentary, semantic aggregation, selectable reasoning models, Azure Foundry sessions, multi-agent missions, and MCP tools/resources
Deployment/testing Conventional Django dependency and application layout Docker Compose, Terraform modules, Kubernetes-related artifacts, GitHub Actions workflows, offline deterministic paths, and broad automated test coverage
The repository history deliberately frames this as a preservation-and-extension effort: later agent-kit bridges call the production VideoUploadAPIView and ChatAPIView in process rather than reimplementing their behavior, so the newer agent workflows can reuse Azure Blob upload, SAS issuance, VideoEntity registration, signal-driven indexing, parsing, permissions, and agentic synthesis already implemented by the live DVSA application.
Core application platform
At its foundation, DVSA is a Django/DRF service with a substantially cleaner domain decomposition than the predecessor:
• apps/users provides the application’s user domain, including a custom Django user model.
• apps/videos owns account-scoped VideoEntity and ImageEntity concepts, video upload, video views, and chat-oriented interactions.
• apps/analytics contains the reusable drone-vision analysis routines and analysis job execution.
• apps/observability persists, queries, aggregates, and exports analysis commentary events.
• apps/storage supports storage-facing workflows.
• core centralizes cross-cutting exception handling, pagination, permissions, and Azure services.
The project is built around conventional Django operational entrypoints—manage.py, configuration modules, requirements sets, and tests—but adds Docker Compose, a Dockerfile, a Makefile, infrastructure directories, and environment templates for repeatable local, containerized, and cloud-oriented deployment.
A practical implication is that DVSA is both an API service and an integration platform: a user can interact through REST endpoints, but downstream systems can also consume it as a model-serving, data-enrichment, or agentic-analytics component.
Video analytics and models
The central workload remains aerial/drone video intelligence. Early commits added a modular apps/analytics/routines package composed of pure NumPy-input/JSON-output functions discoverable through a registry; the Django layer exposes routine discovery and analysis execution, with Celery handling background video-analysis tasks.
Classical CV and spatial routines
The built-in analytic layer includes:
• Color and threshold detection with contour-derived bounding boxes and centroids.
• Zone counting using spatial geometry and nearest-neighbor centroid tracking.
• Parking-spot occupancy based on edge features, optionally with an SVM and a heuristic fallback.
• Spatial clustering with DBSCAN or HDBSCAN.
• RGB histograms and dominant-color extraction.
• Motion analysis through MOG2 background subtraction and dense optical flow.
• Homography estimation, point mapping, and image warping.
• SAHI-style tiled detection with non-maximum-suppression merging.
These routines target practical drone-video cases: counting objects in geographically meaningful regions, tracking moving entities, assessing parking occupancy, detecting scene change or flow, aligning aerial frames, and improving small-object detection through tiling.
Pluggable detection models
DVSA moves beyond fixed analysis code by supporting custom detection models behind a unified contract: load, infer, and close, producing detections in the consistent form {label, score, bbox: [x, y, w, h]}.
It supports or catalogs multiple model/runtime paths:
• ONNX through a custom detector with preprocessing, output-layout tolerance, original-frame coordinate mapping, tiled inference, IoU/NMS merging, and injectable sessions for testability.
• PyTorch/TorchScript and .pt models, with SAHI-style tiling.
• Ultralytics YOLO models in PyTorch or ONNX form.
• Azure Custom Vision exports converted to ONNX-compatible model specifications.
• A model selector that chooses a model using task, desired classes, altitude, and image resolution.
The curated model catalog expanded to 15 aerial/overhead-oriented choices, including general detectors such as YOLOv5, Faster R-CNN, and DETR; domain models for xView, UAVDT, DIOR, HRSC2016 ships, and SpaceNet buildings; and Azure Custom Vision exports. This reflects a strategy of model portability and selection policy rather than committing the platform to a single inference framework.
Cloud, retrieval, and reasoning
DVSA’s cloud architecture is encapsulated in core/azure, rather than being interwoven directly into views. The commit history describes SessionAzureEnvironment as the integration boundary that provides deterministic per-session naming, setup/teardown, resource isolation, and a dry-run path when Azure credentials or SDKs are absent.
Azure-connected data plane
When configured, the Azure layer can support:
• Azure Blob Storage for source video, frame extraction, frame upload/copy/read operations, and SAS URL generation.
• Azure AI Vision for image vectorization—described as 1,536-dimensional padded embeddings—and image analysis.
• Azure AI Search for indexing frames/documents with account ID, descriptions, object labels, bounding boxes, and geotags.
• Azure Video Indexer for video upload, insight retrieval, project/render operations, and download workflows.
• Azure AI Foundry/OpenAI-style agent execution for knowledge-grounded chat, function/tool invocation, and object/scene querying.
The provisioning model separates shared infrastructure—such as storage, AI Search, and Foundry/OpenAI deployments—from per-session logical isolation through index filtering and blob prefixes. It offers dry-run, Azure SDK, and Terraform-related execution modes, plus a REST lifecycle endpoint for creating or deleting a session-scoped Azure environment.
Reasoning model layer
dvsa_api/reasoning adds a bring-your-own reasoning-model system beside the visual detection stack. A model is discovered from a folder containing a manifest and adapter, then routed through a selection policy such as named selection, cost optimization, latency optimization, or privacy-first selection.
The platform also includes an Azure Foundry provider designed around ephemeral per-session deployments. It supports provisioning, inference, cost and quota limits, TTL/inactivity handling, heartbeat logic, and idempotent teardown; importantly, it defaults to an offline dry-run capability so development and unit testing do not require Azure credentials or live resources.
This means DVSA can use deterministic local/offline reasoning in development, a drop-in custom reasoning adapter for specialized deployments, or managed Azure Foundry capacity when cloud-scale or managed-model execution is desired.
Observability and agents
A key maturation over the original backend is that DVSA treats analytic outputs as traceable operational events rather than only final detections.
Commentary-based observability
The observability subsystem transforms low-level routine outputs into wide “commentary” events carrying trace, span, and correlation identifiers. Events can be stored through in-memory or Django database sinks, listed and aggregated over REST, and emitted in a guarded manner so telemetry does not cause an analysis job to fail.
The platform can project that commentary into OpenTelemetry-shaped logs, metrics, and traces over OTLP/HTTP JSON, with buffered/fan-out sinks and best-effort export semantics. It also threads video FPS, frame stride, and trace IDs through analyses so commentary records have meaningful segment boundaries and can be correlated back to the stored Analysis run.
On top of raw events, a semantic aggregation agent can summarize lower-level observations into a higher-level agent:semantic event. Its design is provider-agnostic: an offline deterministic echo client and template fallback are available, while an Azure OpenAI/VLM path can be selected when configured.
Multi-agent control plane
The repository’s dvsa_api/mcp package contains an opt-in multi-agent control plane for operational missions such as anomaly triage, incident response, and human escalation. It provides:
• Agent contracts and typed task/message schemas.
• Folder-based agent discovery, manifests, allow lists, and policies for round-robin, load-aware, latency-optimized, or priority selection.
• In-process agents plus a remote/container HTTP shim.
• An in-memory message bus designed to be replaceable with Redis or Kafka.
• A planner that validates mission templates as task DAGs.
• An executor with concurrency waves, retries/backoff, timeouts, fallback agents, cancellation, dynamic follow-up tasks, and upstream-result passing.
• Example missions for urban accident response and infrastructure inspection.
This subsystem is optional and defaults to an in-memory, offline-deterministic mode. That makes it useful for prototyping multi-agent drone-analysis workflows locally, while leaving open a path to production message buses and remote agents.
MCP protocol server
The same package additionally provides a separate, standards-facing Model Context Protocol server over JSON-RPC 2.0. This lets Claude Desktop, command-line clients, or other MCP-compatible hosts access DVSA without modifying the platform core.
Its registered tools include:
• dvsa.detect_anomalies
• dvsa.run_reasoning
• dvsa.extract_features
• dvsa.get_tracks
• dvsa.get_frames
It also exposes resources such as dvsa://frames, dvsa://tracks, and dvsa://sensor, backed by local files, URLs, or DVSA API endpoints.
The terminology deserves care: the repository uses “MCP” in two related but distinct senses—an internal multi-agent control plane and an external Model Context Protocol server. Both coexist intentionally: one orchestrates DVSA missions, while the other lets external AI clients call DVSA capabilities and retrieve DVSA data.
Agent kits and integrations
The agent_kits framework packages DVSA’s analytics into four independently usable operating modes built atop a common deterministic pipeline and Pydantic schemas (RunInput, Detection, RunOutput). The package includes its own versioning, migration notes, security documentation, tests, and an explicit security guide.
Kit Intended use Main characteristics
Local interactive Human-supervised local work CLI commands for video fetching, frame extraction, inference, output writing, and end-to-end runs; dry-run and “always ask” control gates
Cloud autonomous Service-oriented execution FastAPI /run, /metrics, /healthz, and /readyz endpoints; validation, retries, graceful shutdown, Prometheus-style counters, Docker/Kubernetes support
Orchestration Parallelizing large analysis jobs Time-window and spatial-tile partitioning, configurable overlap, worker templates, deterministic merging, IoU deduplication, confidence-conflict handling, optional critic
Integrations and triggers Event-driven automation GitHub Actions example, Slack slash-command integration, signature-verified generic webhooks, payload conversion, and in-memory run tracking
The more recent bridge connects these kits to the production Django endpoints through APIRequestFactory and forced authentication. This allows an agent run to ingest video through the actual VideoUploadAPIView, trigger its Azure Blob/SAS and signal-driven indexing behavior, and route a question through ChatAPIView for agentic synthesis—rather than diverging into a copied offline implementation. The bridge remains opt-in, dependency-injected, and testable without Django, DRF, or Azure services.
The project also includes a Databricks connector for Delta-to-context mapping, remote or in-cluster inference, batch execution, streaming via Auto Loader and foreachBatch, MLflow helpers, notebooks, job templates, and local Spark emulation. Thus, DVSA can serve not only request/response workloads but also batch and streaming geospatial/video analytics pipelines.
In short, DVSA is best understood as an industrialized DroneWorld/EZVision platform: a Django API at the center, with modular drone-video CV, Azure indexing and retrieval, model and LLM extensibility, structured observability, agentic workflows, MCP access, and batch/streaming integration paths surrounding it. Its recurring design principle is offline-first, deterministic operation with cloud services and advanced agents activated only when explicitly configured.