API Reference

Complete reference for OMEN interfaces, data contracts, canonical models, event types, and SDK APIs

This page documents every public interface, data model, event type, and contract defined in the OMEN SDK and engine.

Canonical Data Models

Source: sdk/contracts/canonical_models.py (Pydantic v2)

Enumerations

TrackType

Value	Description
`FRIENDLY`	Blue-force / allied track
`HOSTILE`	Confirmed or suspected hostile
`UNKNOWN`	Unidentified track
`NEUTRAL`	Non-combatant / civilian

ThreatLevel

Value	Description
`LOW`	Minimal threat
`MEDIUM`	Moderate threat
`HIGH`	Significant threat
`CRITICAL`	Immediate danger

WaypointType

Value	Description
`DEPARTURE`	Mission start point
`CHECKPOINT`	In-route check point
`OBJECTIVE`	Mission objective
`ARRIVAL`	Mission end point
`ALTERNATE`	Alternate / divert point

AirspaceType

Value	Description
`CLASS_A`	Class A controlled airspace
`CLASS_B`	Class B controlled airspace
`CLASS_C`	Class C controlled airspace
`RESTRICTED`	Restricted airspace (R-xxxx)
`PROHIBITED`	Prohibited airspace (P-xxxx)
`DANGER`	Danger area
`TFR`	Temporary Flight Restriction
`MOA`	Military Operations Area
`WARNING`	Warning area
`OTHER`	Other / unclassified airspace type

Core Models

EntityMetadata

Shared metadata for all canonical entities:

Field	Type	Constraints	Description
`entity_id`	`str`	Required	Unique entity identifier
`source_id`	`str`	Required	Source system identifier
`source_format`	`str`	Required	Original data format (e.g., “cot”, “geojson”)
`ingested_at`	`datetime`	Required	Timestamp when ingested into OMEN
`sourced_at`	`datetime`	Optional	Timestamp from the source system
`confidence`	`float`	0.0–1.0	Source confidence score
`completeness`	`float`	0.0–1.0	Data completeness score
`is_stale`	`bool`	Default: False	Whether the entity has exceeded TTL
`provenance`	`list[str]`	Default: []	Chain of processing stages
`classification`	`str`	Default: “UNCLASSIFIED”	Data classification level

TrackPosition (Immutable)

Field	Type	Constraints	Description
`latitude`	`float`	-90.0 to 90.0	WGS-84 latitude
`longitude`	`float`	-180.0 to 180.0	WGS-84 longitude
`altitude_m`	`float`	Optional	Altitude in meters
`heading_deg`	`float`	0.0 to 360.0	Heading in degrees
`speed_mps`	`float`	Optional	Speed in meters/second

Track

Field	Type	Description
`metadata`	`EntityMetadata`	Standard entity metadata
`callsign`	`str`	Optional callsign label
`track_type`	`TrackType`	FRIENDLY, HOSTILE, UNKNOWN, NEUTRAL
`position`	`TrackPosition`	Current geospatial position

Route

Field	Type	Description
`metadata`	`EntityMetadata`	Standard entity metadata
`route_id`	`str`	Unique route identifier
`waypoints`	`list[RouteWaypoint]`	Ordered list of waypoints
`total_distance_nm`	`float`	Total route distance in nautical miles
`estimated_duration_min`	`float`	Estimated duration in minutes

RouteWaypoint

Field	Type	Description
`id`	`str`	Waypoint identifier
`name`	`str`	Waypoint name
`latitude`	`float`	WGS-84 latitude
`longitude`	`float`	WGS-84 longitude
`altitude_ft`	`float`	Altitude in feet
`waypoint_type`	`WaypointType`	Type of waypoint

Threat

Field	Type	Description
`metadata`	`EntityMetadata`	Standard entity metadata
`threat_type`	`str`	Type of threat (e.g., “SAM”, “AAA”)
`position`	`TrackPosition`	Threat location
`engagement_radius_nm`	`float`	Engagement envelope radius in nautical miles
`threat_level`	`ThreatLevel`	LOW, MEDIUM, HIGH, CRITICAL

Airspace

Field	Type	Description
`metadata`	`EntityMetadata`	Standard entity metadata
`name`	`str`	Airspace name
`airspace_type`	`AirspaceType`	Type of airspace
`geometry`	`dict`	GeoJSON geometry (Polygon)
`lower_alt_ft`	`float`	Lower altitude limit
`upper_alt_ft`	`float`	Upper altitude limit
`effective_start`	`datetime`	When the airspace becomes active
`effective_end`	`datetime`	When the airspace expires
`schedule`	`str`	Optional schedule description
`controlling_agency`	`str`	Controlling authority

Notam

Field	Type	Description
`metadata`	`EntityMetadata`	Standard entity metadata
`notam_id`	`str`	NOTAM identifier
`notam_type`	`str`	NOTAM type code
`text`	`str`	NOTAM text content
`affected_area`	`dict`	GeoJSON geometry or radius
`lower_alt_ft`	`float`	Lower altitude limit
`upper_alt_ft`	`float`	Upper altitude limit
`effective_start`	`datetime`	When the NOTAM takes effect
`effective_end`	`datetime`	When the NOTAM expires
`issuing_authority`	`str`	Issuing authority

MissionEvent

Field	Type	Description
`metadata`	`EntityMetadata`	Standard entity metadata
`event_subtype`	`str`	Specific event type
`description`	`str`	Event description
`related_entity_ids`	`list[str]`	IDs of related entities
`severity`	`str`	INFO, CAUTION, or WARNING

SensorReading

Field	Type	Description
`metadata`	`EntityMetadata`	Standard entity metadata
`sensor_id`	`str`	Sensor identifier
`parameter`	`str`	Measured parameter name
`value`	`float`	Measurement value
`unit`	`str`	Unit of measurement
`is_anomalous`	`bool`	Whether this reading is anomalous

Union Type

CanonicalEntity = Track | Route | Threat | Airspace | Notam | MissionEvent | SensorReading

Plugin Interface

Source: sdk/interfaces/plugin_interface.py

IPlugin (Abstract Base Class)

from abc import ABC, abstractmethod

class IPlugin(ABC):
    @property
    @abstractmethod
    def plugin_id(self) -> str:
        """Unique plugin identifier."""

    @abstractmethod
    def on_start(self, config: dict) -> None:
        """Called by engine when plugin is loaded. Receives plugin config."""

    @abstractmethod
    def on_stop(self) -> None:
        """Called during graceful shutdown."""

    @abstractmethod
    def on_event(self, event: dict) -> list[Any]:
        """Handle incoming event. Return list of output events (may be empty)."""

IAdapter (Abstract Base Class)

class IAdapter(ABC):
    @property
    @abstractmethod
    def adapter_id(self) -> str:
        """Unique adapter identifier."""

    @property
    @abstractmethod
    def supported_formats(self) -> list[str]:
        """List of supported input format strings."""

    @abstractmethod
    def ingest(self, raw: Any) -> list[Any]:
        """Parse raw data into canonical entities."""

    @abstractmethod
    def validate(self, raw: Any) -> ValidationResult:
        """Validate raw input structure."""

    @abstractmethod
    def health(self) -> AdapterHealth:
        """Return current adapter health status."""

    @abstractmethod
    def schema(self) -> dict:
        """Return JSON Schema describing expected input format."""

IEventBus (Protocol)

class IEventBus(Protocol):
    def publish(self, topic: str, event: Any) -> None: ...
    def subscribe(self, topic: str, handler: Callable) -> str: ...
    def unsubscribe(self, subscription_id: str) -> None: ...

IService (Abstract Base Class)

class IService(ABC):
    @property
    @abstractmethod
    def service_id(self) -> str: ...

    @abstractmethod
    async def start(self) -> None: ...

    @abstractmethod
    async def stop(self) -> None: ...

    @abstractmethod
    def health(self) -> ServiceHealth: ...

Result Types

ValidationResult

Field	Type	Description
`valid`	`bool`	Whether validation passed
`errors`	`list[str]`	List of validation error messages

AdapterHealth

Field	Type	Description
`adapter_id`	`str`	Adapter identifier
`healthy`	`bool`	Whether the adapter is healthy
`last_ingestion`	`datetime`	Timestamp of last successful ingestion
`ingestion_count`	`int`	Total successful ingestions
`error_count`	`int`	Total ingestion errors
`message`	`str`	Optional status message

ServiceHealth

Field	Type	Description
`service_id`	`str`	Service identifier
`healthy`	`bool`	Whether the service is healthy
`uptime_seconds`	`float`	Time since service start
`message`	`str`	Optional status message
`details`	`dict`	Optional implementation-specific details

Engine Runtime API

Source: engine/core/runtime.py

PluginManifest

Field	Type	Description
`id`	`str`	Unique plugin identifier
`name`	`str`	Human-readable name
`version`	`str`	Semantic version
`capabilities`	`list[str]`	Declared capabilities (e.g., “subscribe:track_update”)
`dependencies`	`list[str]`	Required plugin IDs
`schema`	`dict`	Configuration JSON Schema
`classification`	`str`	Data classification level
`ai_assisted`	`bool`	Whether the plugin uses AI capabilities

PluginRuntime Methods

Method	Parameters	Returns	Description
`register`	`plugin: IPlugin, manifest: PluginManifest`	`None`	Register plugin (duplicate ID raises error)
`start_plugin`	`plugin_id: str, config: dict`	`None`	Load and initialize plugin
`stop_plugin`	`plugin_id: str`	`None`	Graceful shutdown
`dispatch_event`	`event: dict`	`list[Any]`	Route event to all running plugins
`running_plugins`	—	`list[str]`	Active plugin IDs
`get`	`plugin_id: str`	`IPlugin`	Get plugin instance
`get_manifest`	`plugin_id: str`	`PluginManifest`	Get plugin manifest

InProcessEventBus Methods

Method	Parameters	Returns	Description
`publish`	`topic: str, event: Any`	`None`	Publish event to topic
`subscribe`	`topic: str, handler: Callable`	`str`	Subscribe and get subscription ID
`unsubscribe`	`subscription_id: str`	`None`	Remove subscription

TypeScript Interfaces

Source: sdk/interfaces/plugin_interface.ts

Event Types

Type	Fields	Description
`OmenEvent`	type, timestamp, source, payload	Base event structure
`TrackUpdateEvent`	track: Track	Blue-force or other track position update
`ProximityAlertEvent`	track_a, track_b, distance_nm	Two tracks within alert radius
`ConnectivityStateChangeEvent`	state, bandwidth_kbps, latency_ms	DDIL connectivity transition
`EnergyStateChangeEvent`	mode, battery_soc_pct, thermal_state	Energy mode change