AI1SAD

All in 1 Shark Attack Data

AI1SAD is a marine intelligence platform for shark-encounter data, environmental context, replay analysis, and operational surveillance planning.

It combines historical incidents, regional profiles, environmental signals, habitat context, biological events, human exposure, replay case studies, and human-operated drone observation intake into a single FastAPI, frontend, and documentation workspace.

AI1SAD does not predict individual incidents or infer shark intent. It separates calm public warning posture from operational surveillance-priority context for human review.

Current Status

Current development checkpoint:

• Latest completed phase: Phase 25E, UAV Operator Research Brief and Compatibility Matrix
• Latest completed maintenance: Phase 25D-D media attachment security review and metadata hardening
• Current implementation: Phase 26A, GSAF XLS Intake and Delta Tracker
• Next planned phase: Phase 26B, AI1SAD Shark-Human Incident Registry Schema
• Target full working-version launch: September 7, 2026.
• Local demo frontend: http://localhost:5174
• FastAPI docs: http://localhost:8000/docs
• MkDocs portal: http://localhost:8001

AI1SAD is targeting a full working-version launch on September 7, 2026. Current development is focused on evidence provenance, staged upstream data review, replay explainability, UAV operator workflows, and public-safe surveillance outputs.

See:

• Project Status
• Next Phase
• Local Visual QA

Visual Preview

Brand System

Canonical source artwork lives in images/branding. Deployment copies for the docs portal and frontend live under docs/assets/brand and frontend/public/brand.

Replay And Operational Heatmaps

Horseshoe Reef, Western Australia	NSA Panama City Drone Fixture

Michaelmas Island, WA	Lovers Point Whale Carcass

Additional replay artifacts live in docs/assets/case_studies.

What Is Included

• FastAPI backend with public API routes and privacy filtering
• MongoDB collection/index definitions for incidents, signals, alerts, replay, regional packs, and drone observation intake
• React/Vite frontend dashboard for the local AI1SAD demo
• MkDocs documentation portal with branded theme and case-study pages
• Replay library with timeline-separated historical and demo scenarios
• Explainability engine and confidence decomposition
• Warning, activity-hazard, surveillance-priority, and alert outputs
• Regional packs for Florida, Hawaii, Western Australia, Queensland, South Africa, Red Sea, New South Wales, U.S. East Coast, California, and Brazil/Recife planning
• Static/offline adapters for biological events, vessel/fishing context, human exposure, kelp forest habitat, Hawaii habitat, Hawaii tide/current context, and Hawaii water clarity/turbidity context
• Vendor-neutral human-operated drone observation ingestion MVP
• Drone Operator Console for human-entered patrol observations, including shark sightings, no-sighting patrols, carcasses, baitfish activity, poor visibility, and surf-line activity. AI1SAD records observations and recommends surveillance attention; it does not control aircraft or predict individual attacks.
• Metadata-only analyst review fields for annotating observations with review status, outcome, public summary, and private notes
• Local-only media attachment prototype is available behind an explicit configuration gate. Attachments are private by default and are not exposed through public feeds. AI1SAD does not analyze media, infer species, or create sightings from attachments.
• UAV Operator Feedback Intake collects real-world workflow notes from drone operators, lifeguards, researchers, and coastal teams. Feedback is treated as research input only; it does not create sightings, warnings, or public alerts.
• GSAF local import and delta tracking reads manually downloaded .csv, .xlsx, or .xls files into internal staging JSON, preserves source provenance, computes row fingerprints, and reports new, changed, unchanged, duplicate, malformed, and possibly removed upstream rows. Imported rows do not create warnings, alerts, replay facts, drone observations, public feed entries, or scoring changes.
• AI1SAD is planning an Australian archival source tracker for historical newspaper evidence and a Vic Hislop corpus archive for shark-attack case claims, interviews, writings, and museum-era records. These sources will support provenance and behavioral hypothesis review, not automatic shark-intent conclusions.
• Read-only MAVLink telemetry bridge for local fixture replay into existing telemetry endpoints
• One-click Windows local demo launcher and stop scripts

Local Demo

One-Click Windows Launcher

From the repo root, double-click:

start_ai1sad_demo.bat

This starts:

• Backend: http://localhost:8000
• FastAPI docs: http://localhost:8000/docs
• Frontend: http://localhost:5174
• MkDocs: http://localhost:8001

It also opens browser tabs for the frontend, FastAPI docs, and docs portal. FretTrack may occupy 5173, so AI1SAD uses 5174 for the frontend.

Stop the local demo with:

stop_ai1sad_demo.bat

Manual Run

Backend:

python3 -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Windows fallback:

F:\Python310\python.exe -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend:

cd frontend
npm install
npm run dev -- --host 0.0.0.0 --port 5174

MkDocs:

mkdocs serve --dev-addr 0.0.0.0:8001

Core API Areas

• /api/v1/incidents
• /api/v1/stats/yearly
• /api/v1/stats/by-country
• /api/v1/stats/by-region
• /api/v1/stats/by-activity
• /api/v1/stats/by-species
• /api/v1/locations/nearby
• /api/v1/sources
• /api/v1/risk/location
• /api/v1/warnings/location
• /api/v1/warnings/explain
• /api/v1/surveillance/search-zones
• /api/v1/surveillance/explain
• /api/v1/alerts/active
• /api/v1/alerts/evaluate
• /api/v1/packs
• /api/v1/signals/location
• /api/v1/provider-health
• /api/v1/replay/library
• /api/v1/replay/run/{scenario_id}
• /api/v1/drone/active-observations
• /api/v1/drone/surveillance-feed
• /api/v1/uav/operator-feedback

Drone write endpoints are disabled by default unless DRONE_INGEST_ENABLED=true.

Local GSAF intake is a script entry point, not a public API route:

F:\Python310\python.exe -m app.services.gsaf_importer --input data/imports/gsaf/raw/latest_gsaf.xls --report data/imports/gsaf/reports/latest_import_report.json

Raw GSAF spreadsheets and generated staging/report artifacts stay local under data/imports/gsaf/ and must not be committed unless rights are explicitly approved.

Replay Library

The replay library presents evidence-backed operational scenarios with:

• strict timeline separation
• quiet-day comparisons
• factor summaries
• confidence breakdowns
• model/version metadata
• replay JSON artifacts
• heatmap SVG assets
• disclaimers and missing-data notes

Current case-study coverage includes:

• Horseshoe Reef 2026
• Plumpudding Beach Esperance Whale Carcass 2026
• Piedade and Boa Viagem Recife 2026
• Michaelmas Island Albany WA 2026
• Lovers Point Pacific Grove Whale Carcass 2026
• NSA Panama City Florida 2026 Drone Observation Fixture
• Queensland Spearfishing 2026

See the full Replay Library.

Drone Observation Intake

Phase 25A adds a vendor-neutral observation-ingestion path for human-operated coastal-surveillance drones. Phase 25C adds a local Drone Operator Console at /drone-console for human-entered patrol observations:

• mission records
• telemetry points
• source-attributed observations
• no-sighting patrol caveats
• review status
• probable species metadata with provenance
• no-sighting patrol semantics
• public-safe active-observation feed
• surveillance-feed integration
• replay fixture support

AI1SAD supports human-approved surveillance decisions. It does not control aircraft or predict individual attacks.

Consumer Drone App Compatibility

AI1SAD can work alongside any consumer drone flight app through the manual operator workflow. The pilot flies normally using the drone's own app, controller, or manufacturer software. AI1SAD does not need that app to expose an API. The operator records observations in the AI1SAD Drone Operator Console while the drone is flown manually.

This is not the same as direct SDK/API integration. Consumer drone app compatibility means AI1SAD supports the patrol workflow, not that AI1SAD controls the aircraft or reads private app telemetry.

Drone / Flight App Type	AI1SAD Support Path	API Required?
Any consumer drone flight app	Manual Drone Operator Console + media/evidence reference	No
DJI Fly / DJI Pilot	Manual workflow now; future read-only SDK research possible	No for current workflow
Ophelia GO / M RC PRO / Holy Stone-class apps	Manual workflow only + post-flight media reference	No
Generic Wi-Fi camera drone apps	Manual workflow + map-pin observation	No
ArduPilot / PX4 / Pixhawk	Read-only MAVLink telemetry bridge	Yes, MAVLink

AI1SAD works with consumer drone apps by running beside them, not inside them.

AI1SAD recommends surveillance attention. Humans approve missions. Drone operators fly missions. AI1SAD ingests observations.

AI1SAD does not:

• control consumer drone apps
• autonomously fly aircraft
• bypass manufacturer software
• require drone-app API access for manual workflows
• create shark sightings from telemetry alone
• fetch or analyze media
• predict individual shark attacks

It also does not add:

• autonomous takeoff or landing
• waypoint execution
• offboard flight control
• MAVLink command transmission
• DJI-specific dependencies
• computer vision inference
• file upload or image hosting
• public media attachment release or binary media upload

See:

• UAV Operator Research Brief
• UAV Compatibility Matrix
• UAV Operator Feedback Intake
• Drone Operator Console
• Drone Observation Ingestion
• Observation Analyst Review
• Local Media Attachment Prototype
• Media Attachment Storage Design
• Drone Mission Workflow
• Drone Data Contract
• Drone Operations Safety
• MAVLink Telemetry Bridge

Safety And Privacy

AI1SAD is designed for research, documentation, replay analysis, and operational planning. It is not a replacement for official beach, lifeguard, maritime, wildlife, or emergency guidance.

Public API responses must not expose:

• victim names
• private notes
• internal analyst notes
• restricted-source content
• exact sensitive addresses
• MongoDB credentials
• provider API keys
• private media paths
• raw exception details

Operational recommendations require human review. Scores support interpretation and prioritization; they do not guarantee safety outcomes.

Validation Snapshot

Latest validation is recorded in Project Status.

Lovers Point backend freshness fix validation:

• Focused Lovers Point carcass test: 1 passed
• Biological events provider tests: 13 passed
• Full backend tests: 296 passed, 3 warnings
• Replay freshness behavior: biological-event freshness can be evaluated at scenario time for strict replay; default live/API scoring still uses current time.
• No scoring weights, fixture dates, provider adapters, replay artifacts, frontend dependencies, or dependency-security files changed.
• MkDocs build: passed with the known Material advisory banner
• README local links/images check: 55 checked, passed
• Secret scan: no credential patterns matched
• Prohibited-language scan: guardrail/disclaimer matches only
• Git whitespace check: passed with CRLF normalization warnings only

Documentation Map

• API
• Schema
• Privacy
• Usage Policy
• Disclaimer
• Data Quality
• Current Data Sources
• GSAF Import And Delta Tracking
• Australian Archival News Tracker
• Vic Hislop Corpus Archive
• Replay Library
• Surveillance Engine
• Explainability Engine
• Alert Engine
• Regional Packs
• Provider Health
• Frontend Dashboard
• Brand Identity
• Brand Deployment Map
• Dependency Security Review
• Media Attachment Storage Design
• Drone Operator Console

Development Notes

Install backend dependencies:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env

Required local environment values:

MONGODB_URI=<your-mongodb-atlas-connection-string>
MONGODB_DATABASE=AI1SAD
SHARK_ATTACK_API_TITLE=AI1SAD Shark Attack Data API
ADMIN_EVENTS_ENABLED=false
ADMIN_SURVEILLANCE_ENABLED=false
ADMIN_ALERTS_ENABLED=false
DRONE_INGEST_ENABLED=false

Run backend tests:

python -m pytest -q

Run frontend tests/build:

cd frontend
npm test
npm run build

Build docs:

mkdocs build

License

AI1SAD code is licensed under the Apache License 2.0. Data sources, incident records, public advisories, imagery, and third-party datasets may have separate licenses, terms, attribution requirements, and privacy restrictions.