[Epic] AI-Powered Seismic Intelligence Assistant — v2.0

[GiZano]

Description

QuakeGuard v1.0 establishes a robust distributed sensor network capable of detecting, processing, and alerting users about seismic events in real time. Version 2.0 elevates the platform from a passive monitoring system to an intelligent seismic analysis assistant by integrating a natural language AI layer on top of the existing PostgreSQL/PostGIS data foundation.

By the time this epic begins, the database will contain real timestamped seismic readings, zone assignments, magnitude estimates, and alert history from deployed sensors — exactly the structured context an AI model needs to provide genuinely meaningful, data-grounded responses.

This epic is scoped for summer development after the school contest submission and targets the GF Marilli contest as its primary showcase milestone.

AI Strategy: Development and contest demo use Ollama running locally inside Docker — zero API costs, zero internet dependency, zero rate limits. The architecture uses a provider abstraction layer so switching to a production API (Claude, OpenAI) requires changing a single environment variable.

Objective

Integrate a conversational AI assistant into the QuakeGuard platform that allows both technical and non-technical users to query the seismic network in natural language, receive automatic situation reports after detected events, and gain actionable insights from historical sensor data — without writing a single database query.

Guidelines

Before submitting, please verify:

• This epic does not duplicate any existing open issue
• The feature spans Backend, Frontend, and a new AI Integration layer
• This epic is explicitly scoped as post-v1.0 and must not be started before the school contest submission
• Sub-issues will be created for each task list item before development begins

Proposed Solution

Architecture Overview

User natural language query
        ↓
POST /ai/query
        ↓
Query router fetches relevant PostgreSQL/PostGIS context
        ↓
AI Provider abstraction layer
        ↓
Ollama (local, free) ←→ Claude API (production swap)
        ↓
Natural language response → mobile app

AI Provider Abstraction

A dedicated src/ai_provider.py module exposes a single query_ai(prompt, context) function. The active provider is controlled by the AI_PROVIDER environment variable (ollama by default). Adding a new provider requires implementing one async function — no changes to endpoints or business logic.

Backend — New AI Query Endpoint

POST /ai/query accepts a natural language question, fetches relevant database context, and returns an AI-generated response. Protected by verify_api_key and rate-limited via Redis.

Example interactions:

• "How many M3+ events occurred in Northern Italy this month?"
• "Which zone has been most active in the last 7 days?"
• "Explain what happened during the alert at 14:32 in plain language"
• "Are there coverage gaps in the sensor network in Central Italy?"

Backend — Automatic Situation Reports

After a CRITICAL alert the worker automatically generates a plain-language situation report for the affected zone and pushes it to connected mobile clients via WebSocket alongside the alert payload.

Frontend — Assistant Tab

A new fourth tab in the bottom navigator providing a chat interface for natural language queries. Chat history maintained in a new Zustand slice.

Frontend — Situation Report Card

Dashboard updated to display an auto-generated situation report card below the alert history feed on CRITICAL events.

Alternatives Considered

Claude API / OpenAI as primary: Rejected for development and contest — introduces API costs and internet dependency during live demos. Retained as the production upgrade path via the provider abstraction layer.

Fine-tuned seismic domain model: Rejected — requires large labeled datasets and significant compute. Ollama with injected database context achieves equivalent quality at zero cost.

On-device mobile AI: Rejected — current mobile hardware cannot run models capable of meaningful data reasoning with acceptable latency.

Hardcoded natural language templates: Rejected — covers only anticipated query patterns with no flexibility for novel questions.

Task List

Infrastructure

• Add ollama service to docker-compose.yml with persistent volume
• Add AI_PROVIDER, OLLAMA_URL, OLLAMA_MODEL to .env and docker-compose.yml
• Create model pull script to download the chosen Ollama model on first boot
• Document provider swap procedure in CONTRIBUTING.md

Backend

• Create src/ai_provider.py with provider abstraction interface
• Implement Ollama provider via httpx async client
• Implement Claude API provider stub for production upgrade path
• Create src/ai.py context assembly module for database query results
• Implement POST /ai/query endpoint with rate limiting and API key protection
• Build query router to determine relevant database tables from question intent
• Implement automatic situation report generation in worker.py post-CRITICAL alert
• Add SituationReport model to models.py
• Add GET /ai/situation-reports/{zone_id} retrieval endpoint

Frontend

• Add Assistant tab to app/(tabs)/_layout.tsx
• Create app/(tabs)/assistant.tsx chat screen
• Create useAssistantStore Zustand slice for chat session state
• Create useAiQuery TanStack Query mutation hook
• Update Dashboard to display situation report card on CRITICAL alert
• Create SituationReportCard shared component

Documentation

• Document Ollama setup and model selection in Wiki
• Document provider swap procedure for production deployment
• Add example queries to hardware setup guide