Spatial Agents uses Apple's Foundation Models to generate intelligence products — situation reports, anomaly assessments, and causal narratives — entirely on-device with no cloud dependency.
On-device models have constrained context windows (4,096 tokens). Every prompt must fit within a strict budget that allocates space for system instructions, tool schemas, data payload, and model response.
System instructions: ~30 tokens
Tool schemas: ~80-200 tokens
Data payload: up to 15% of context window (~614 tokens)
Response space: remaining tokens
The budget manager measures token consumption for each component and compresses payloads when they exceed allocation. When the FM SDK is unavailable, it falls back to a conservative 4-characters-per-token estimate.
Versioned prompt templates are organized by domain. Each template defines system instructions, a user prompt with data placeholders, and an expected output schema.
| Template | Domain | Purpose |
|---|---|---|
| Maritime Situation Report | Maritime | Vessel activity analysis for an H3 cell |
| Maritime Anomaly Detection | Maritime | Dark vessels, route deviations, density anomalies |
| Aviation Situation Report | Aviation | Flight patterns and altitude distributions |
| Causal Graph Narration | Cross-domain | Natural language explanation of causal chains |
FM outputs are validated against Pydantic schemas before delivery to clients. Semantic checks verify that summaries meet minimum length, observations are present, and confidence scores are within valid ranges. Invalid outputs are rejected with detailed error messages.
The eval harness supports two modes: live evaluation using the FM SDK and dry-run mode that renders prompts, measures tokens, and validates structure without calling the model. This enables regression testing across model versions and development without hardware dependencies.
| Endpoint | Returns |
|---|---|
/api/intelligence/{h3_cell} | FM situation report with activity summary |
/api/budget | Current token budget allocation |