Skip to content

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.

RPCWhat it does
RunFetchRuns a fetch and returns one RunFetchResponse.
RunFetchStreamRuns the same fetch and streams RunFetchUpdate events as each phase finishes. The last event carries the full result.
ListTraces / GetTraceDetailsRead back the recorded execution history.
GenerateSOPDrafts a Standard Operating Procedure as markdown.
ListFetchStartersReturns 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:

  1. 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 by ml/prophet). When two data domains are correlated with |r| at or above RunFetchRequest.synapse_threshold (default 0.5), the EDA records a measured CORRELATED_WITH edge between them.
  2. 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.
  3. 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:

  • decisions and action_cards: the structured twin output. See Action cards & money.
  • graph_nodes and graph_edges: the knowledge graph for the fetched domains.
  • hypothesis_scenarios, hypothesis_impacts, hypothesis_traces, hypothesis_forecasts and hypothesis_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_dispatched and hypothesis_agents_succeeded: the swarm census. These counts are only meaningful when hypothesis_swarm_ran is 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, fresh or exact-cache, set by the server.
  • metrics (EvaluationMetrics): these scores are not filled in by the fetch. The response sets unmeasured_reason to “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 ListFetchRuns is.
  • 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_rows and sampled_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 frequency maps 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=true on the server. Otherwise it is recorded as skipped, not as a success, and run_count does 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 notify setting (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 in last_notify: sent, not needed, not sent (with the reason), or waiting.
  • Outcomes are recorded as they happened. last_run_success reflects 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_notices and the swarm census before treating the result as covering every selected source and scenario.
  • Progress events report pipeline stages, not answer quality. A final event with success=true means the pipeline finished. It doesn’t mean the model’s answer is correct.
  • EvaluationMetrics is not a quality score while unmeasured_reason is set.
  • A cached result is a replay of an earlier run. Its provenance.computed_at says when it was produced.