Fetch pipeline
You ask a question on Ask, and FACE answers it from your own connected sources. That
answer is one fetch: one run of FACE’s analysis. A fetch reads the data, profiles and
clusters it, runs the analysis agents, and returns a FetchAnalysisResult with
decisions, action cards and evidence documents. A brief on the Briefs page runs
the same fetch on a clock or when new data arrives.
Where you see the result:
- Ask shows the answer first, with its confidence chips. Each run is kept at
/fetch/run/<run id>. - Options shows what you could do about it, and Why shows the rules and sources behind it.
- Actionable Twins shows the action cards the run drafted, waiting for a person.
All of this is served by FetchService.
| RPC | What it does |
|---|---|
RunFetch | Runs a fetch and returns one RunFetchResponse. |
RunFetchStream | Runs the same fetch and streams RunFetchUpdate events as each phase finishes. The last event carries the full result. |
ListTraces / GetTraceDetails | Read back the recorded execution history. |
GenerateSOP | Drafts a Standard Operating Procedure as markdown. |
ListFetchStarters | Returns the suggested questions shown on Ask. |
Briefs are a separate service, SchedulesService, and are covered
below.
Where a fetch runs
The FACE server (the control plane) never runs the pipeline itself. RunFetchStream
forwards the request to a dedicated runner and relays that runner’s stream back. If no
runner can be dialled, the stream ends with a terminal final event that says the
fetch did not run: “dedicated runner unavailable — fetch does not run on the control
plane”. It never falls back to running the fetch locally.
Before any runner time is spent, the server checks the caller’s compute-unit
budget. An exhausted budget ends the stream with a single event whose phase is
denied. A successful fetch is then charged against that budget. Budgets are managed
through MeteringService (see Operations), and you see them on
Settings › Subscription.
The server resolves the connection records the fetch needs and sends them with
the request in dispatched_connections. Credentials travel separately: each bundle is
sealed to the runner’s ephemeral key for that one dispatch (dispatched_credentials,
with dispatch_id). A client can’t set any of these fields, because the server
overwrites them on the forward. How the sealing works is covered in
Security.
Phases
sequenceDiagram
participant C as FACE app
participant CP as FACE server
participant R as Runner
participant M as Model plane
C->>CP: RunFetchStream(RunFetchRequest)
CP->>CP: compute-unit budget check
CP->>R: forward (records + sealed credentials)
R-->>C: phase=data_health (done=false)
R->>R: read sources, profile, cluster, EDA
par Phase 1
R->>M: posture agent (TOON)
and
R->>M: rules reconciliation (TOON)
end
R-->>C: phase=data_health (done=true)
R->>M: Phase 2 hypothesis swarm
R-->>C: phase=scenarios
R->>M: Phase 3 twins decision
R->>R: judging ladder on proposed actions
R-->>C: phase=recommendations
R-->>C: phase=final + RunFetchResponse
RunFetchUpdate.phase names the stage an event reports. The contract lists
data_health, rules, scenarios, recommendations, final and model_text (the
text a model call is producing, as it is produced), plus denied for a budget refusal.
The server also sends progress labels such as sources and data_prep while a stage
runs, so a client should not treat the list as closed. done=false means a stage is
still running. The terminal event always has phase="final", done=true, and a
result.
The runner’s pipeline (runContextEngineeringPipeline) has three phases:
- Phase 1, data alignment. The posture agent and the rules-reconciliation agent
run in parallel over the fetched context. Before they run, the pipeline clusters the
samples (HDBSCAN through
AnalysisService.ClusterRefinement) and runs a per-domain time-series EDA (runDomainTimeSeriesEDA, backed byml/prophet). When two data domains are correlated with|r|at or aboveRunFetchRequest.synapse_threshold(default0.5), the EDA records a measuredCORRELATED_WITHedge between them. - Phase 2, hypothesis swarm. A bounded-parallel swarm runs one agent per scenario
the estate proposes. The swarm has a cap, and its census travels in
FetchAnalysisResult. The scenarios appear on Options. See Simulation & twins. - Phase 3, twins decision. The twins orchestrator turns the grounded findings and simulations into decisions and action cards. Each proposed action goes through the judging ladder before it’s accepted. The accepted cards appear on Actionable Twins. See Agents & oversight.
A Phase-1-only fetch. When session_eda is set, the fetch runs Phase 1 only: data
domains, maturity, rules and the knowledge graph. It never runs the hypothesis or
twins agents. The FACE app does not set it; a question on Ask, a brief and an API call
without it run the full pipeline.
Unary RunFetch returns early. When Phase 1 completes, RunFetch returns the Phase 1
result, and Phases 2 and 3 keep running in the background. RunFetchStream waits until
the recommendations are ready.
What the result carries
FetchAnalysisResult includes the following fields, among others:
decisionsandaction_cards: the structured twin output. See Action cards & money.graph_nodesandgraph_edges: the knowledge graph for the fetched domains.hypothesis_scenarios,hypothesis_impacts,hypothesis_traces,hypothesis_forecastsandhypothesis_anomalies: the swarm’s union of answers. It is a union, not a consensus. Nothing votes on or reconciles the agents.hypothesis_scenarios_inferred,hypothesis_agents_dispatchedandhypothesis_agents_succeeded: the swarm census. These counts are only meaningful whenhypothesis_swarm_ranis true.source_notices: sentences about sources that could not be read, or about where a source’s SQL actually ran. An empty list does not mean every source was fine.action_judgements: the judging ladder’s verdict on every proposed action, whether accepted or rejected. A rejected action appears nowhere else.provenance: how the answer was produced,freshorexact-cache, set by the server.metrics(EvaluationMetrics): these scores are not filled in by the fetch. The response setsunmeasured_reasonto “no evaluation harness ran for this fetch — these scores are absent, not zero”. A client must not render the scores as percentages when that field is set.sql_generated: SQL text drafted by the model from the fetched schemas. It’s informational output, not a record of what was executed.
Repeat fetches can be served from cache. A recent identical fetch (same
connection_id and command) can be replayed from cache. The cache entry must be
younger than FETCH_CACHE_TTL (default 10 minutes); no confidence score decides
reuse, because no fetch path measures one. A cached answer is marked in
provenance and its message says it is a replay. A run whose analysis phases all
failed, or that answered only in part, is never cached.
Traces
ListTraces and GetTraceDetails read the session records that each fetch saves to
the durable record store. A Trace from these RPCs carries the transaction id, the
command, the analysis text and the drafted SQL. If the process has no session store,
ListTraces answers FailedPrecondition instead of returning an empty list, because
“never read” and “nothing recorded” are different answers.
Observed data lineage, meaning which source was read when and where the rows went, is a
different record. It’s served by LineageService.GetSourceActivity. See
Posture & maturity.
SOP generation
GenerateSOP takes a topic, a process_name and optional steps. The prompt is
screened before it reaches the model. A refused prompt returns InvalidArgument, and
the refusal is audit-logged.
The response carries markdown in sop_content and an sop_id. If the model call fails
after the prompt is accepted, the content is the literal SOP Generation Failed.
Suggested questions on Ask
ListFetchStarters returns up to four FetchStarter questions, each with an icon, a
title, a subtitle and prompt_text. They come from the caller’s own data, newest
findings first:
- The newest fetch. The newest run in the caller’s history that succeeded, or the
newest with an analysis: its broken measured rules, its flagged routes and its
scenario verdicts. Run history is scoped as
ListFetchRunsis. - A quick sample of the sources. A bounded read of each active source, with no
model and no fetch run, so a question can name a figure before any fetch has run.
A question built this way carries
sample_rowsandsampled_at_unix_ms. - The connections. What each source’s last Explore described: its tables, row counts and topics.
Each question names its play (claims, disruptions, routes, fulfilment,
cold_chain, maintenance, inventory or fleet), which Ask’s play chips filter on.
The call reads no store: it answers with the set built in the background, says it is
still being prepared (loading), or says why it could not be read.
Briefs
A brief is a scheduled question, and you manage briefs on the Briefs page. Each brief is written for one persona and reads the sources picked for it. With none picked, it reads every connection the instance has when the run fires. Its runs open on Ask like any other run, and the cards they draft wait on Actionable Twins.
SchedulesService provides ListSchedules, CreateSchedule, UpdateSchedule,
SetScheduleActive and DeleteSchedule. A brief fires on one of two triggers:
- Time. A free-text
frequencymaps to an interval: hourly, every 6 hours, daily, weekly or monthly. Unrecognised text maps to hourly. - Event. A connection’s data listener sees the events the trigger asks for. The
brief fires when enough matching events are pending, the first has waited its
debounce time, the cooldown since its last run has passed, and its previous run has
finished. The run is marked
TRIGGER_TYPE_EVENT.
How briefs behave:
- Execution is opt-in. A due brief runs a real fetch only when
SCHEDULE_EXECUTE_FETCH=trueon the server. Otherwise it is recorded as skipped, not as a success, andrun_countdoes not increase. - Briefs run as a service account. A scheduled fetch runs under a short-lived
service-account session (
ROLE_SERVICE_ACCOUNT) minted for the scheduler. - A picked source that is gone is named. At fire time a picked connection that no longer exists is dropped, and the run’s last-run line names it. When none is left, the run is refused with that reason.
- A brief can tell someone. Its
notifysetting (WhatsApp, call or email, and a condition) sends a notice once the run’s background phases end, to the numbers and mailbox on Settings › Integrations (Channels). The outcome is recorded inlast_notify: sent, not needed, not sent (with the reason), or waiting. - Outcomes are recorded as they happened.
last_run_successreflects what the fetch actually returned. A fetch declined by the pipeline, for example for budget, is recorded as a failure. A brief whose previous run hasn’t finished skips that interval instead of stacking.
Reading the results
- A completed fetch is not a complete fetch. Read
source_noticesand the swarm census before treating the result as covering every selected source and scenario. - Progress events report pipeline stages, not answer quality. A
finalevent withsuccess=truemeans the pipeline finished. It doesn’t mean the model’s answer is correct. EvaluationMetricsis not a quality score whileunmeasured_reasonis set.- A cached result is a replay of an earlier run. Its
provenance.computed_atsays when it was produced.