The architecture
Context Engine
One ingestion substrate. Eight signal categories. Every plane reads the same world.
Most planning systems treat external signals as someone else's problem — a dashboard to look at, an alert to acknowledge. Autonomy ingests them as first-class state. The Context Engine is the substrate that fetches, scores, and routes external evidence to the agents that need to act on it, with tenant-scoped relevance filtering and a single audit trail.
What flows in today
Eight categories of external signal. Public, paid, and partner-provided sources, normalised to one record shape.
| Source | Category | What it carries | Status |
|---|---|---|---|
| FRED | Economic | Federal Reserve Economic Data, headline indicators and yield curves. | Live |
| Open-Meteo / NWS | Weather | Forecasts, watches, warnings, and severe-event geometry. | Live |
| EIA | Energy | Diesel and electricity prices, refinery and grid status. | Live |
| GDELT | Geopolitical | Global event database, real-time geopolitical and trade signals. | Live |
| openFDA | Regulatory | Drug, device, and food enforcement actions and recalls. | Live |
| Google Trends | Sentiment | Search-interest signal across product categories and brands. | Live |
| Sentiment | Topic-tagged community sentiment for early demand and risk signals. | Live | |
| DOT Disruptions | Transport | Federal-DOT incident and infrastructure disruption feed. | Live |
| FMCSA · DAT · SONAR · MarineTraffic | Transport (TMS) | Carrier safety, freight rate, and ocean-AIS feeds for the TMS plane. | Beta |
The source registry is open for tenant-specific extension. New sources land as registry entries, not as new fetcher code.
Every signal gets the same shape
One record, eight pre-computed fields. The agents downstream don't care where it came from.
economic, weather, energy, geopolitical, sentiment, regulatory, commodity, trade, plus product-specific extensions.
Pre-computed against the tenant's canonical state. A weather signal is irrelevant if no tenant site or lane sits in its footprint.
Two orthogonal scores. Magnitude is "how big is this thing"; urgency is "how soon does it bite."
affected_product_tags · affected_region_tags · affected_trm_types — the coarse routing primitives, with structured FK upgrades in flight.
signal_date and expires_at on every record. Stale signals decay automatically; nothing stays "in scope" past its half-life.
summary, title, and embedding_text for retrieval. The Risk Engine's narrator and the agent layer's RAG paths read from the same field.
Same eight fields whether the source is a federal API, a paid commercial feed, or a partner integration. The substrate normalises; the agents specialise.
The Context Broker
One fact, three orthogonal axes, the right consumer.
When does it land?
A diesel-price spike is operational tomorrow; a GDP revision is strategic next quarter. The broker routes by when the signal acts, not by what it is about.
How long does it bite?
A tornado warning is hours; a port strike is weeks; a regulatory rule change is permanent. Duration determines which planning loop owns the response.
Who does it touch?
One supplier, one corridor, one product family, the whole enterprise. Scope tightens or widens the routing without re-classifying the signal.
As time passes, classifications re-mature. A signal that was strategic in February becomes operational in May. The broker re-classifies on its own cadence so consumers always see the right tier.
Event-awareness upgrade, in flight
Today the engine is signal-shaped — each record is "a thing we ingested." The upgrade reframes it as event-shaped — "a thing happening in the world that could hurt us." Every concrete change below is a consequence of that reframe.
External-event entity
A single hurricane, port closure, or commodity shock currently appears as 3–5 separate signals across NWS, GDELT, Reddit, weather APIs, and DOT. The new event entity correlates them so risk edges attach to events, not to redundant signal copies.
Structured entity FKs
Today, affected_product_tags and affected_region_tags are coarse strings ("auto-parts", "southeast-US"). Adding affected_site_ids / affected_lane_ids / affected_supplier_ids / affected_product_ids — populated by a deterministic resolver — narrows risk edges to specific entities instead of whole product families.
Geographic geometry
PostGIS geometry on every signal and event so "which sites fall inside this hurricane cone?" is a single SQL query rather than a tag-match heuristic. Populated from each source's native format (NWS UGC zones, FIPS, lat/lon, polygons).
Source-authority tier
Enum on every source: gov_official / industry_data / news_aggregator / social_signal. Propagates into risk-edge value scoring so an NWS warning and a Reddit post are not implicitly equal.
Severity schemas + event windows
Per-category severity tiers (NWS Watch / Advisory / Warning + Saffir-Simpson; FDA Class I/II/III; transport minor / major / critical), plus event_start / event_end distinct from signal_date. A hurricane forecast issued today projects landfall in 4 days; the risk window is the landfall window.
Clearing / anti-signals
When a watch ends, a recall is resolved, or a strike clears, link the close-out record to the original event and automatically deactivate dependent risk edges. No more "exposed-to-hurricane" two days after landfall passed.
Probabilistic forecasts
Encode "70% chance of Cat 3 landfall Tuesday" with multiple scenario branches. Feeds the conformal-bounded risk derivation in the Risk Engine.
Webhook / streaming refresh
Today every fetch is daily-cadenced. Risk-relevant sources (NWS warnings, port APIs, supplier RSS) need event-driven push so the Risk Engine acts on minutes, not on the next overnight pull.
P0 is required for Risk Engine v1; P1 ships once v1 risk edges are flowing; P2 is opportunistic and driven by observed gaps.
Why a substrate, not a feed
Tenant-scoped relevance
A tornado watch in a region with no tenant site or lane is a zero-relevance signal. The engine pre-filters before the agents see it. No alert fatigue.
One audit trail
Every signal stores its raw payload, its fetched-at timestamp, and the source URL. Every downstream decision can be traced back to the exact wire-format input.
Sources are pluggable
A new source — federal API, paid commercial feed, partner integration — lands as a registry entry that conforms to the standard fetcher contract. No bespoke pipeline per vendor.
The same record drives every plane
A single hurricane signal can route to the demand plane (regional purchasing patterns), the supply plane (inbound disruption), and the transport plane (lane reroute) simultaneously. One signal, one shape, three downstream effects.
The Context Engine is the upstream half of the Risk Engine. Risk relationships are derived edges; the Context Engine is what makes those edges grounded in something other than the canonical state.
See how external signals become decisions
The Context Engine feeds the Risk Engine, which feeds the Decision Stream. One coherent path from external evidence to ranked operator action.