> ## Documentation Index
> Fetch the complete documentation index at: https://resq-dependabot-github-actions-github-actions-478e18be3d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Models

<a id="resq_mcp.models" />

# resq\_mcp.models

Domain models for the ResQ MCP server.

These Pydantic models define the core data contracts for the three main subsystems:

* PDIE (Predictive Disaster Intelligence Engine)
* DTSOP (Digital Twin Simulation & Optimization Platform)
* HCE (Hybrid Coordination Engine)

All datetime fields use timezone-aware UTC timestamps for consistency across
distributed systems and audit logging.

<a id="resq_mcp.models.annotations" />

## annotations

<a id="resq_mcp.models.UTC" />

## UTC

<a id="resq_mcp.models.datetime" />

## datetime

<a id="resq_mcp.models.Literal" />

## Literal

<a id="resq_mcp.models.BaseModel" />

## BaseModel

<a id="resq_mcp.models.Field" />

## Field

<a id="resq_mcp.models.Coordinates" />

## Coordinates Objects

```python theme={null}
class Coordinates(BaseModel)
```

Geographic coordinates with status indicator.

Represents a geographic point in decimal degrees (WGS84 datum)
with an associated status flag for monitoring.

**Attributes**:

* `lat` - Latitude in decimal degrees (-90 to +90).
* `lng` - Longitude in decimal degrees (-180 to +180).
* `status` - Current status indicator (e.g., "clear", "critical").

**Example**:

> > > coords = Coordinates(lat=37.3417, lng=-121.9751, status="clear")
> > > print(f"Position: \{coords.lat}, \{coords.lng}")

<a id="resq_mcp.models.Coordinates.lat" />

#### lat

<a id="resq_mcp.models.Coordinates.lng" />

#### lng

<a id="resq_mcp.models.Coordinates.status" />

#### status

<a id="resq_mcp.models.Sector" />

## Sector Objects

```python theme={null}
class Sector(BaseModel)
```

A monitored geographic sector in the drone surveillance network.

Sectors are predefined geographic zones monitored by the drone fleet
for disaster detection and response coordination.

**Attributes**:

* `id` - Unique sector identifier (e.g., "Sector-1").
* `coordinates` - Center point coordinates with status.

<a id="resq_mcp.models.Sector.id" />

#### id

<a id="resq_mcp.models.Sector.coordinates" />

#### coordinates

<a id="resq_mcp.models.DetectedObject" />

## DetectedObject Objects

```python theme={null}
class DetectedObject(BaseModel)
```

An object detected by drone sensors during surveillance.

Represents the output of edge AI object detection running on drone
hardware or ground processing stations.

**Attributes**:

* `name` - Human-readable name of detected object (default: "None").
* `type` - Classification type (e.g., "fire", "vehicle", "person").
* `confidence` - Detection confidence score (0.0 to 1.0).
* `description` - Detailed description of the detection.

<a id="resq_mcp.models.DetectedObject.name" />

#### name

<a id="resq_mcp.models.DetectedObject.type" />

#### type

<a id="resq_mcp.models.DetectedObject.confidence" />

#### confidence

<a id="resq_mcp.models.DetectedObject.description" />

#### description

<a id="resq_mcp.models.DisasterScenario" />

## DisasterScenario Objects

```python theme={null}
class DisasterScenario(BaseModel)
```

A disaster scenario template for simulation and detection.

Defines the characteristics of a disaster type that can be detected
by drone surveillance or used as input for digital twin simulations.

**Attributes**:

* `type` - Disaster category (e.g., "wildfire", "flood", "earthquake").
* `name` - Human-readable scenario name.
* `confidence` - Detection confidence or scenario likelihood (0.0 to 1.0).
* `description` - Detailed scenario description including characteristics.

<a id="resq_mcp.models.DisasterScenario.type" />

#### type

<a id="resq_mcp.models.DisasterScenario.name" />

#### name

<a id="resq_mcp.models.DisasterScenario.confidence" />

#### confidence

<a id="resq_mcp.models.DisasterScenario.description" />

#### description

<a id="resq_mcp.models.SectorAnalysis" />

## SectorAnalysis Objects

```python theme={null}
class SectorAnalysis(BaseModel)
```

Complete analysis result from a sector surveillance scan.

Contains all detection data, evidence links, and recommended actions
from a drone sector scan. Used for incident reporting and blockchain
evidence submission.

**Attributes**:

* `sector_id` - Identifier of the scanned sector.
* `timestamp` - UTC timestamp of the analysis (auto-generated).
* `status` - Overall status (e.g., "clear", "CRITICAL\_ALERT").
* `detected_object` - Primary object or hazard detected.
* `disaster_type` - Classified disaster type if applicable.
* `confidence` - Detection confidence score (0.0 to 1.0).
* `description` - Detailed analysis description.
* `coordinates` - Geographic coordinates of the detection.
* `video_proof_url` - NeoFS/IPFS URL for video evidence.
* `recommended_action` - Suggested next action (e.g., "IMMEDIATE\_REPORT\_TO\_BLOCKCHAIN").

<a id="resq_mcp.models.SectorAnalysis.sector_id" />

#### sector\_id

<a id="resq_mcp.models.SectorAnalysis.timestamp" />

#### timestamp

<a id="resq_mcp.models.SectorAnalysis.status" />

#### status

<a id="resq_mcp.models.SectorAnalysis.detected_object" />

#### detected\_object

<a id="resq_mcp.models.SectorAnalysis.disaster_type" />

#### disaster\_type

<a id="resq_mcp.models.SectorAnalysis.confidence" />

#### confidence

<a id="resq_mcp.models.SectorAnalysis.description" />

#### description

<a id="resq_mcp.models.SectorAnalysis.coordinates" />

#### coordinates

<a id="resq_mcp.models.SectorAnalysis.video_proof_url" />

#### video\_proof\_url

<a id="resq_mcp.models.SectorAnalysis.recommended_action" />

#### recommended\_action

<a id="resq_mcp.models.SectorStatusSummary" />

## SectorStatusSummary Objects

```python theme={null}
class SectorStatusSummary(BaseModel)
```

Condensed status summary for network-wide sector monitoring.

Lightweight representation used in network status dashboards and
overview displays. Excludes detailed evidence and coordinates.

**Attributes**:

* `status` - Current sector status indicator.
* `detected_object` - Primary detected object or "None".
* `confidence` - Overall confidence score for the status.

<a id="resq_mcp.models.SectorStatusSummary.status" />

#### status

<a id="resq_mcp.models.SectorStatusSummary.detected_object" />

#### detected\_object

<a id="resq_mcp.models.SectorStatusSummary.confidence" />

#### confidence

<a id="resq_mcp.models.NetworkStatus" />

## NetworkStatus Objects

```python theme={null}
class NetworkStatus(BaseModel)
```

Aggregate status of the entire drone surveillance network.

Provides a network-wide view of all monitored sectors and critical
alert counts for operator dashboards and system health monitoring.

**Attributes**:

* `timestamp` - UTC timestamp of the status snapshot (auto-generated).
* `total_sectors` - Total number of monitored sectors.
* `sectors` - Mapping of sector IDs to their status summaries.
* `critical_alerts` - Count of sectors with critical alerts active.

<a id="resq_mcp.models.NetworkStatus.timestamp" />

#### timestamp

<a id="resq_mcp.models.NetworkStatus.total_sectors" />

#### total\_sectors

<a id="resq_mcp.models.NetworkStatus.sectors" />

#### sectors

<a id="resq_mcp.models.NetworkStatus.critical_alerts" />

#### critical\_alerts

<a id="resq_mcp.models.SwarmStatus" />

## SwarmStatus Objects

```python theme={null}
class SwarmStatus(BaseModel)
```

Real-time operational status of the drone swarm.

Aggregates health metrics across all drones in the fleet including
battery levels, connectivity status, and deployment state.

**Attributes**:

* `timestamp` - UTC timestamp of the status snapshot (auto-generated).
* `total_drones` - Total number of drones in the fleet.
* `active_drones` - Number of drones currently deployed and operational.
* `average_battery` - Fleet-wide average battery percentage (0-100).
* `network_status` - Overall network health (e.g., "operational", "degraded").
* `last_sync` - UTC timestamp of last successful sync with ground station.

<a id="resq_mcp.models.SwarmStatus.timestamp" />

#### timestamp

<a id="resq_mcp.models.SwarmStatus.total_drones" />

#### total\_drones

<a id="resq_mcp.models.SwarmStatus.active_drones" />

#### active\_drones

<a id="resq_mcp.models.SwarmStatus.average_battery" />

#### average\_battery

<a id="resq_mcp.models.SwarmStatus.network_status" />

#### network\_status

<a id="resq_mcp.models.SwarmStatus.last_sync" />

#### last\_sync

<a id="resq_mcp.models.DeploymentRequest" />

## DeploymentRequest Objects

```python theme={null}
class DeploymentRequest(BaseModel)
```

Request for immediate drone deployment to a specific sector.

Used by operators or automated systems to request drone dispatch
to sectors requiring surveillance or emergency response.

**Attributes**:

* `sector_id` - Target sector identifier for deployment.
* `priority` - Deployment urgency level (low/medium/high/critical).
  Higher priority requests preempt lower priority missions.

<a id="resq_mcp.models.DeploymentRequest.sector_id" />

#### sector\_id

<a id="resq_mcp.models.DeploymentRequest.priority" />

#### priority

<a id="resq_mcp.models.DeploymentStatus" />

## DeploymentStatus Objects

```python theme={null}
class DeploymentStatus(BaseModel)
```

Response status for a drone deployment request.

Provides confirmation and tracking information for a deployment request
including assigned drone and estimated arrival time.

**Attributes**:

* `status` - Deployment state (e.g., "deployed", "en\_route", "completed").
* `sector_id` - Target sector identifier.
* `priority` - Assigned priority level.
* `drone_id` - Identifier of the assigned drone unit.
* `eta_seconds` - Estimated time to arrival in seconds.
* `timestamp` - UTC timestamp of the status update (auto-generated).

<a id="resq_mcp.models.DeploymentStatus.status" />

#### status

<a id="resq_mcp.models.DeploymentStatus.sector_id" />

#### sector\_id

<a id="resq_mcp.models.DeploymentStatus.priority" />

#### priority

<a id="resq_mcp.models.DeploymentStatus.drone_id" />

#### drone\_id

<a id="resq_mcp.models.DeploymentStatus.eta_seconds" />

#### eta\_seconds

<a id="resq_mcp.models.DeploymentStatus.timestamp" />

#### timestamp

<a id="resq_mcp.models.VulnerabilityMap" />

## VulnerabilityMap Objects

```python theme={null}
class VulnerabilityMap(BaseModel)
```

Static vulnerability assessment data for a geographic sector.

Part of PDIE (Predictive Disaster Intelligence Engine) system.
Contains precomputed risk factors, infrastructure data, and population
metrics used for predictive disaster modeling and resource allocation.

**Attributes**:

* `sector_id` - Sector identifier this map applies to.
* `population_density` - Human population density category.
* `critical_infrastructure` - List of critical facilities (e.g., "hospital", "power-substation").
* `flood_risk` - Flood vulnerability score (0.0 to 1.0).
* `fire_risk` - Fire vulnerability score (0.0 to 1.0).
* `last_updated` - UTC timestamp of last data update (auto-generated).

**Notes**:

Risk scores are precomputed from historical data, terrain analysis,
and infrastructure density. Updated periodically via GIS integration.

<a id="resq_mcp.models.VulnerabilityMap.sector_id" />

#### sector\_id

<a id="resq_mcp.models.VulnerabilityMap.population_density" />

#### population\_density

<a id="resq_mcp.models.VulnerabilityMap.critical_infrastructure" />

#### critical\_infrastructure

<a id="resq_mcp.models.VulnerabilityMap.flood_risk" />

#### flood\_risk

<a id="resq_mcp.models.VulnerabilityMap.fire_risk" />

#### fire\_risk

<a id="resq_mcp.models.VulnerabilityMap.last_updated" />

#### last\_updated

<a id="resq_mcp.models.PreAlert" />

## PreAlert Objects

```python theme={null}
class PreAlert(BaseModel)
```

Probabilistic disaster forecast from LSTM/GNN predictive models.

Part of PDIE system. Generated by machine learning models that analyze
weather patterns, sensor data, and historical trends to predict potential
disasters before they occur. Enables proactive resource positioning.

**Attributes**:

* `alert_id` - Unique alert identifier (e.g., "PRE-A1B2C3D4").
* `sector_id` - Target sector for the prediction.
* `predicted_disaster_type` - Expected disaster type (e.g., "wildfire", "flood").
* `probability` - Forecast confidence (0.0 to 1.0).
* `forecast_horizon_hours` - Time until predicted event (hours from now).
* `vulnerability_context` - Associated sector vulnerability data.
* `generated_at` - UTC timestamp of forecast generation (auto-generated).

**Example**:

> > > alert = PreAlert(
> > > ...     alert\_id="PRE-123ABC",
> > > ...     sector\_id="Sector-1",
> > > ...     predicted\_disaster\_type="wildfire",
> > > ...     probability=0.85,
> > > ...     forecast\_horizon\_hours=12,
> > > ...     vulnerability\_context=vuln\_map
> > > ... )

<a id="resq_mcp.models.PreAlert.alert_id" />

#### alert\_id

<a id="resq_mcp.models.PreAlert.sector_id" />

#### sector\_id

<a id="resq_mcp.models.PreAlert.predicted_disaster_type" />

#### predicted\_disaster\_type

<a id="resq_mcp.models.PreAlert.probability" />

#### probability

<a id="resq_mcp.models.PreAlert.forecast_horizon_hours" />

#### forecast\_horizon\_hours

<a id="resq_mcp.models.PreAlert.vulnerability_context" />

#### vulnerability\_context

<a id="resq_mcp.models.PreAlert.generated_at" />

#### generated\_at

<a id="resq_mcp.models.SimulationRequest" />

## SimulationRequest Objects

```python theme={null}
class SimulationRequest(BaseModel)
```

Request for high-fidelity physics simulation in digital twin.

Part of DTSOP system. Triggers physics-based simulation in Unity/Unreal
Engine for accurate disaster propagation modeling and strategy validation.

**Attributes**:

* `scenario_id` - Unique scenario identifier for this simulation.
* `sector_id` - Geographic sector to simulate.
* `disaster_type` - Type of disaster to model (e.g., "flood", "wildfire").
* `parameters` - Simulation parameters (e.g., \{"wind\_speed": 15.5, "water\_level": 2.3}).
* `priority` - Processing priority (standard queued, urgent fast-tracked).

**Notes**:

Simulations run asynchronously. Monitor progress via the returned
simulation ID and resource subscription (resq://simulations/\{id}).

<a id="resq_mcp.models.SimulationRequest.scenario_id" />

#### scenario\_id

<a id="resq_mcp.models.SimulationRequest.sector_id" />

#### sector\_id

<a id="resq_mcp.models.SimulationRequest.disaster_type" />

#### disaster\_type

<a id="resq_mcp.models.SimulationRequest.parameters" />

#### parameters

e.g., wind\_speed, water\_level

<a id="resq_mcp.models.SimulationRequest.priority" />

#### priority

<a id="resq_mcp.models.OptimizationStrategy" />

## OptimizationStrategy Objects

```python theme={null}
class OptimizationStrategy(BaseModel)
```

Reinforcement learning-optimized deployment and evacuation strategy.

Part of DTSOP system. Generated by RL agents trained on thousands of
simulated disaster scenarios to optimize resource allocation and
evacuation routing under various constraints.

**Attributes**:

* `strategy_id` - Unique strategy identifier (e.g., "STRAT-X1Y2Z3W4").
* `related_alert_id` - Pre-alert or incident ID this strategy addresses.
* `recommended_deployment` - Mapping of drone types to recommended counts
  (e.g., \{"surveillance": 2, "payload": 1}).
* `evacuation_routes` - Ordered list of recommended evacuation routes.
* `estimated_success_rate` - Predicted success probability (0.0 to 1.0)
  based on simulation outcomes.
* `simulation_proof_url` - NeoFS/IPFS URL for simulation evidence and logs.

**Notes**:

Success rate derived from Monte Carlo simulations across varying
disaster intensities and communication scenarios.

<a id="resq_mcp.models.OptimizationStrategy.strategy_id" />

#### strategy\_id

<a id="resq_mcp.models.OptimizationStrategy.related_alert_id" />

#### related\_alert\_id

<a id="resq_mcp.models.OptimizationStrategy.recommended_deployment" />

#### recommended\_deployment

drone\_type -> count

<a id="resq_mcp.models.OptimizationStrategy.evacuation_routes" />

#### evacuation\_routes

<a id="resq_mcp.models.OptimizationStrategy.estimated_success_rate" />

#### estimated\_success\_rate

<a id="resq_mcp.models.OptimizationStrategy.simulation_proof_url" />

#### simulation\_proof\_url

<a id="resq_mcp.models.IncidentReport" />

## IncidentReport Objects

```python theme={null}
class IncidentReport(BaseModel)
```

Initial incident report from Edge AI, human observers, or sensors.

Part of HCE (Hybrid Coordination Engine) system. Represents unvalidated
incident detection requiring cross-reference and validation before
triggering full response protocols.

**Attributes**:

* `incident_id` - Unique incident identifier.
* `source` - Detection source (edge\_ai=onboard processing, human\_report=operator,
  sensor\_network=ground sensors).
* `sector_id` - Geographic sector of the incident.
* `detected_type` - Incident classification (e.g., "fire", "collision", "flooding").
* `confidence` - Detection confidence from source (0.0 to 1.0).
* `evidence_url` - Optional URL to evidence (video, photos) on IPFS/NeoFS.
* `timestamp` - UTC timestamp of detection (auto-generated).

**Notes**:

High-confidence reports (>0.85) may auto-confirm. Lower confidence
reports cross-referenced with PDIE predictions and other sources.

<a id="resq_mcp.models.IncidentReport.incident_id" />

#### incident\_id

<a id="resq_mcp.models.IncidentReport.source" />

#### source

<a id="resq_mcp.models.IncidentReport.sector_id" />

#### sector\_id

<a id="resq_mcp.models.IncidentReport.detected_type" />

#### detected\_type

<a id="resq_mcp.models.IncidentReport.confidence" />

#### confidence

<a id="resq_mcp.models.IncidentReport.evidence_url" />

#### evidence\_url

<a id="resq_mcp.models.IncidentReport.timestamp" />

#### timestamp

<a id="resq_mcp.models.IncidentValidation" />

## IncidentValidation Objects

```python theme={null}
class IncidentValidation(BaseModel)
```

Validation result after cross-referencing an incident report.

Part of HCE system. Produced after comparing incident reports against
PDIE predictions, sensor networks, and historical data to confirm
authenticity and trigger appropriate response protocols.

**Attributes**:

* `incident_id` - ID of the incident being validated.
* `is_confirmed` - Whether the incident is confirmed as genuine.
* `validation_source` - System or agent that performed validation
  (e.g., "SpoonOS-HCE-Validator", "Human-Operator").
* `correlated_pre_alert_id` - Related PDIE pre-alert if correlation found.
* `notes` - Detailed validation reasoning and cross-reference results.

**Example**:

> > > validation = IncidentValidation(
> > > ...     incident\_id="INC-123",
> > > ...     is\_confirmed=True,
> > > ...     validation\_source="SpoonOS-HCE-Validator",
> > > ...     notes="Confirmed via PDIE correlation and sensor data"
> > > ... )

<a id="resq_mcp.models.IncidentValidation.incident_id" />

#### incident\_id

<a id="resq_mcp.models.IncidentValidation.is_confirmed" />

#### is\_confirmed

<a id="resq_mcp.models.IncidentValidation.validation_source" />

#### validation\_source

e.g., "SpoonOS-Validator"

<a id="resq_mcp.models.IncidentValidation.correlated_pre_alert_id" />

#### correlated\_pre\_alert\_id

<a id="resq_mcp.models.IncidentValidation.notes" />

#### notes

<a id="resq_mcp.models.MissionParameters" />

## MissionParameters Objects

```python theme={null}
class MissionParameters(BaseModel)
```

Authorized mission parameters pushed to drone via HCE.

Part of HCE system. Defines the authorized action space and risk
parameters for autonomous drone operations. Includes blockchain hash
for immutable audit trail of mission authorizations.

**Attributes**:

* `mission_id` - Unique mission identifier (e.g., "MISS-A1B2C3D4").
* `target_sector` - Assigned operational sector.
* `authorized_actions` - List of permitted autonomous actions
  (e.g., \["autonomous\_flight", "payload\_release\_authorized"]).
* `risk_tolerance` - Maximum acceptable risk level (0.0 to 1.0).
  Lower values restrict aggressive maneuvers.
* `strategy_hash` - Blockchain transaction hash linking to strategy record
  for immutable audit trail (format: "0xHEXDIGITS").
* `timestamp` - UTC timestamp of parameter push (auto-generated).

  Security Note:
  Authorized actions are validated against drone firmware capabilities.
  Unauthorized actions are rejected by ResQ-OS security layer.

<a id="resq_mcp.models.MissionParameters.mission_id" />

#### mission\_id

<a id="resq_mcp.models.MissionParameters.target_sector" />

#### target\_sector

<a id="resq_mcp.models.MissionParameters.authorized_actions" />

#### authorized\_actions

<a id="resq_mcp.models.MissionParameters.risk_tolerance" />

#### risk\_tolerance

<a id="resq_mcp.models.MissionParameters.strategy_hash" />

#### strategy\_hash

blockchain link

<a id="resq_mcp.models.MissionParameters.timestamp" />

#### timestamp

<a id="resq_mcp.models.ErrorResponse" />

## ErrorResponse Objects

```python theme={null}
class ErrorResponse(BaseModel)
```

Standard error response for failed operations.

Used across all subsystems to provide consistent error messaging.
Returned instead of raising exceptions for expected error conditions
(e.g., invalid sector ID, missing data).

**Attributes**:

* `status` - Always "error" to distinguish from success responses.
* `message` - Human-readable error description.

**Example**:

> > > error = ErrorResponse(message="Sector not found")
> > > if isinstance(result, ErrorResponse):
> > > ...     print(f"Error: \{result.message}")

<a id="resq_mcp.models.ErrorResponse.status" />

#### status

<a id="resq_mcp.models.ErrorResponse.message" />

#### message