How it works

This page walks through one assistant turn end to end: what the model sees, how tool calls execute, where the hard limits are, and how structured results become the cards, charts, and reports the operator ends up with.

The context payload

Every model call carries a fresh JSON snapshot of the console, rebuilt at the start of each tool round so multi-step turns always reason about the current scene, not a stale one:

Field	Contents
simulation	The sim clock (UTC timestamp), playback state, and the scenario window
fleet, nodes, links	The operator fleet topology: satellites, ground stations, data centers, and their links with live utilization, latency, capacity
selection	The currently selected asset or link, if any
metrics	Precomputed fleet percentiles: p50, p90, p95, p99, mean, min, max for link latency, link utilization, and node utilization
predictions	Prediction outputs for the selected asset, including a short-horizon outlook and any ML results for the current selection
context_refs	The authoritative list of assets, links, and groups the operator pinned this turn (globe click or the @ menu, up to 8 pins). Node and link refs carry live utilization, capacity, position, latency, and a short-horizon outlook (1, 3, and 5 minute risks with headroom). Group refs carry member count, average utilization, and a top-utilization member sample
constellation_catalog	The available catalog constellation groups and which are active
billing	The plan, remaining queries for guests, and the allowed ML fidelity tiers

Two scoping rules matter:

• When context_refs is non-empty, nodes and links are scoped to the pinned assets and their endpoints, not the full fleet. Pinning is how an operator makes one gateway or one link the subject of the turn.
• When the operator @-mentions an asset or group, the matching pins are treated as the primary subject of the question.

Operators can also attach up to 4 images or text files per message; attachments are first-class context for that turn.

Bounded history

The request carries the session history under a byte budget (about 500 KB, with headroom under the API payload cap). Messages are kept newest-first until the budget is exhausted; the latest user message always survives. Attachments ride only on the latest user message; earlier turns keep a text marker noting they were omitted. When older turns are dropped, the window says so, so the model knows history was trimmed rather than silently missing.

Tool rounds and caps

A turn is a loop of up to 8 tool rounds:

1. The model returns text and, if it wants to act, tool calls.
2. The console streams each planned call into the transcript as a running step, executes them all deterministically, and resolves each step to done or error with a one-line outcome derived from the structured result.
3. The structured results are appended to the conversation and the loop continues with fresh context.

Hard limits, all reported rather than hidden:

• 8 rounds per turn. If the model is still calling tools at the cap, the console requests one final synthesis turn so the answer is written from the results already gathered instead of ending abruptly.
• 60,000 characters per tool result. Oversized payloads are truncated with an explicit inline marker stating how many characters were cut. The engines are designed to return compact final results, so this is a backstop, not the norm.
• 24 data points per chart digest. Rendered charts are fed back to the model as a digest capped at 24 labels and values per series; the full chart still renders for the operator.

The local fast path

Simple, unambiguous requests never reach the model at all. A local intent layer answers them instantly from the same deterministic engines:

• Fleet chart requests with explicit chart verbs ("chart the latency percentiles", "show a utilization histogram") render the matching fleet preset chart with a metric summary.
• Latency-over-time requests render the P90-over-time line chart from the replay timeline.
• Prediction-outlook questions about the pinned or selected asset answer from the short-horizon outlook already in context.

The fast path deliberately defers to the model whenever routing judgment is needed: anything naming a NORAD or COSPAR id, entity verbs (select, isolate, zoom, tell me about, where is), any show or hide of a named constellation, and any per-group breakdown request ("latency by ground station", "heatmap of X across Y"). Those must route through the real tools so the answer is scoped and honest.

Cancellation

The operator can stop a turn at any point. Stopping does not roll anything back: scene actions that already executed (selections, camera moves, scenario mutations) stay applied, because the operator watched them happen. The transcript keeps whatever text and results were already produced and appends a plain "Stopped." marker. A turn is never silently discarded.

Determinism

Two layers make turns repeatable:

• Temperature 0. The model runs fully greedy, so the same question against the same context plans the same tool calls. The model expresses intent; the executor decides what is executable.
• Deterministic execution. Every engine is pure: no randomness, no wall-clock dependence. The same question at the same sim time with the same filters returns the identical result, down to the calculation string.

Dev and production backends

The chat endpoint is a thin, single-call proxy around one shared server function: the development server plugin and the production deployment both call the same code with the same request and response contract. The proxy resolves the plan, gates guest query limits, injects the system instruction and tool catalog, and returns the raw model turn. The client owns the agentic loop, because only the client holds the live simulation state the tools act on.

Planning versus execution

The system enforces one invariant pipeline for analytical requests: Intent, then Scope and Filters, then the Deterministic Dataset, then Calculations, then Results, then Visualization, then Explanation. In practice the model plans in read-act-read cycles:

1. Read before acting: get_scene_state, get_fleet_summary, or get_entity_detail to establish what is actually loaded.
2. Establish the dataset: apply every filter first and state it. If the question needs links or timeline frames and the fleet is not in a replay, set_timeline_mode("replay") is part of establishing the dataset, not a visualization step. The agent never dead-ends on "no data" when the cause is an unloaded fleet; it loads the replay, states that it did, and continues.
3. Compute through the deterministic tools.
4. Visualize as an output: camera framing, selection of exactly the participating assets, context layers, then charts and panels. The globe must reflect the exact dataset that was computed on, never a decorative approximation.
5. Explain last: the expandable calculation with inputs, filters, formula, sample counts, exclusions, and assumptions.

How results become insight cards, charts, and reports

The executor emits four kinds of structured output alongside the raw results the model reads:

• Summaries: one-line factual statements of what each action did ("Selected OW-0417.", "Imported 12 assets.").
• Charts: rendered specs (bar, line, scatter, donut, histogram, and more), deduplicated by title within a turn.
• Forecast cards: rendered ML prediction results with model tier and confidence.
• Insight cards: the deterministic source-of-truth card for every metric answer, rendered by the app rather than narrated by the model. A card carries the headline value with units, the scope line (operator, filter state, timeline mode, timestamp), the method, the exact calculation, facts (sample size of denominator, exclusions with the rule, outliers, 95 percent confidence band), a table of the actual assets that participated, and notes (low-sample warnings, truncation, group caps).

A turn that used tools and produced charts or insight cards earns an analysis artifact: the summaries, charts (with regeneration metadata pointing back at the producing tool call), insight cards, and the tool names, packaged for the Reports workspace. Plain conversational turns stay chat-only. See Reports and workflows.

The step trace

Every tool call is observable. Steps appear in order, grouped by round, labeled in operator language ("Optimize network contact time (top 3)", "p90 link_latency_ms", "Show starlink"), and resolve with the salient outcome: entity resolution ("resolved to OneWeb-0276"), match counts ("142/648 match"), sample sizes with exclusions ("n=296, 4 excluded"), window coverage ("58 pts / 58 frames, window truncated"), optimizer outcomes ("3 pick(s), 214 access min", "target not reached"), and errors. The trace is the operator's real-time view of the agent chain and is kept with the message afterwards.