Request Routing And Conversation Orchestration
This page describes the bounded agentic control plane. Routing and authorized source scope are resolved before the evidence regime and workload strategy. Persisted actions and request-bound source IDs are resolved structurally. Open-ended natural language is interpreted by one multilingual typed intent classifier on a cold route, or by its context-safe Valkey cache entry on a warm route. Terminal facts and document listings then skip scope planning and answer retrieval; only the shared constrained language-realization contract may run.
Public Modes
The API/user-facing execution override is:
auto- the backend chooses the evidence regime.creative- evidence is optional. The answer may combine enabled source evidence with model reasoning, hypothesis, or opinion.grounded- evidence is mandatory for factual claims. The answer must stay confined to permitted enabled sources and abstain or clarify when support is insufficient.
chat, chat_map_reduce, and agent_map_refine_compose are internal workload
strategies. They are not public evidence modes.
Legacy request value casual is accepted as a compatibility alias for
creative, but new clients should send creative.
Conversation Spine
flowchart TD
A["Chat request or persisted answer action"] --> B["Authorize user, workspace, and conversation"]
B --> C["Resolve enabled active-source boundary"]
C --> SR{"Structural route"}
SR -->|"Persisted expansion action"| X["Load immutable result set<br/>revalidate enabled documents<br/>return next 20"]
SR -->|"Selected document IDs"| SB["Bind permitted selected sources"]
SR -->|"Natural-language request"| D["Build immutable ContextPacket<br/>typed state + bounded recent turns"]
SB --> D
D --> T["Multilingual typed intent classifier<br/>no phrase lists or language-specific rules"]
VC["Separate application-cache Valkey<br/>best effort and never source of truth"] -.-> T
T --> MC{"Typed signal needs older context<br/>and no authoritative referent exists?"}
MC -->|"Yes, once"| OM["Search conversation memory-v2<br/>untrusted context only"]
OM -->|"Relevant turns found"| T
MC -->|"No"| R{"Semantic route resolver<br/>validated typed fields only"}
OM -->|"No relevant turn"| R
R -->|"Typed source reference or source follow-up"| S["SourceArbitrationService<br/>bind enabled permitted documents"]
R -->|"Assistant name, product name, or document count"| F["TrustedApplicationFactsService"]
R -->|"Which documents concern topic X?"| DS["Versioned DocumentSetDiscoveryService<br/>persist complete ordered result set"]
R -->|"Ambiguous application concept"| P["Bounded enabled-document relevance probe"]
R -->|"Answer execution required"| BP["Typed scope planning and retrieval"]
P -->|"Relevant document found"| S
P -->|"No document match"| BP
S --> BP
VC -.-> P
VC -.-> DS
BP --> M{"Evidence regime"}
M -->|"Auto"| AU{"Resolve factual versus interpretive intent"}
M -->|"Creative"| CR["Creative<br/>bound evidence + reasoning or opinion"]
M -->|"Grounded"| GR["Grounded<br/>permitted evidence only"]
AU -->|"Factual or source-dependent"| GR
AU -->|"Ideation, opinion, or personal interpretation"| CR
CR --> W{"Internal workload strategy"}
GR --> W
W -->|"Small direct scope"| CH["chat"]
W -->|"Large evidence scope without multi-step work"| MR["chat_map_reduce<br/>Map document partials<br/>Reduce into final answer"]
W -->|"Explicit multi-step document work"| AMRC["agent_map_refine_compose"]
AMRC --> MAP["MAP<br/>Create typed work items<br/>Run bounded parallel document research"]
MAP --> REF["REFINE<br/>Validate findings and support<br/>Expand evidence and retry within bounds"]
REF --> CMP["COMPOSE<br/>Compose only supported typed results<br/>with the regime-specific composer"]
REF -.-> ACC["Durable typed accumulator<br/>attempts, coverage, citations, continuation pages"]
ACC -.-> CMP
F --> O["Shared output contracts"]
DS --> O
X --> O
CH --> O
MR --> O
CMP --> O
O --> Z["Language, citations, tables/charts,<br/>integrity and support validation"]
Z --> Q["Persist answer, citations, lineage,<br/>routing state, and answer actions"]
Q --> OB["Durable conversation-memory outbox"]
Q --> SSE["Final stream event"]
OB --> MW["Asynchronous memory-v2 indexing"]
Web appears in the target architecture later as another permitted evidence channel. It is intentionally deferred in this slice; the current behavior is to skip web retrieval when no web tool is available.
Direct Workspace Answers
Trusted application facts are selected from the multilingual typed intent, then terminate without scope planning, document retrieval, or general answer generation. On a cold route, the compact classifier is still required to understand arbitrary user language; on an identical context-safe warm route, its Valkey result is reused. They cover unambiguous identity and unfiltered active-document count. Language realization uses the shared reply-language contract and cannot change the trusted value.
This path is intentionally narrow. Conceptual questions prefer a relevant enabled document when one exists. A query such as “which documents belong to topic X?” always uses versioned discovery, never generic workspace inventory.
Ordered Routing And Context
Routing uses this precedence:
persisted answer action
request-bound selected source IDs
one multilingual typed intent classification
typed explicit title, alias, or source ID
typed source-dependent follow-up plus authoritative routing state
typed trusted current fact
typed topic document-set discovery
bounded enabled-document probe for ambiguous application concepts
typed scope planning and retrieval for answer execution
The resolver never parses natural-language words, suffixes, or language-specific patterns. The immutable context packet contains typed routing state and a bounded newest-N turn window. Older semantic memory is searched at most once, only when the classifier explicitly requests prior context and no authoritative referent exists. Classification runs once more only if that search returns relevant turns. Memory may recover goals or source references, but it is untrusted and cannot support a Grounded factual claim without fresh permitted evidence.
Explicit titles use normalized exact and alias matching before a bounded profile fallback. Multiple plausible matches produce a clarification. Missing or disabled sources never cause a silent workspace-wide search.
Document Discovery And Expansion
Document-set discovery fuses exhaustive catalog/profile lexical matches with bounded multilingual text and semantic matches. It filters enabled active sources, calibrates and deduplicates ranks, and persists the complete ordered algorithmic match set. The ambiguous-concept routing probe is deliberately different: it performs one bounded catalog query and bounded text/semantic legs, because a routing decision does not need an exhaustive result set.
The first page contains at most 20 matches. Larger sets include the exact set
size and an opaque durable expand_document_result_set action. Each action is
immutable and idempotent, revalidates current source access, refills around
disabled documents, and owns the next action. Expansion pages persist with
continuation_of_query_id and the client merges them into the original answer
after both live streaming and history reload. Workload continuation tokens are
not used for inventory expansion.
Planner Role
The planner is a bounded orchestrator input, not the final executor. Its first, compact phase classifies natural language in any language and emits typed evidence/output needs:
candidate answer mode or task family
source/reference signals
requested scope and operation
preferred answer shape
requested depth and reasoning effort
reply language hint
whether prior conversation context or a prior source is required
whether the request requires genuinely multi-step document work
These typed fields, rather than re-parsing the question, drive routing. A later
scope-planning phase is called only when answer execution still needs document
selection. The planner must not treat chat or agent as public modes.
Deterministic orchestration resolves the evidence regime and then the workload
strategy.
Evidence Regime Resolution
auto chooses between Creative and Grounded:
Creative is appropriate for opinion, hypothesis, synthesis, general reasoning, and evidence-optional questions.
Grounded is appropriate for strict document/source extraction, quotes, tables, exact source facts, and source-confined requests.
An explicit creative or grounded override sets the evidence regime directly.
The override does not choose the physical workload executor.
Evidence Binding
Both regimes use the same active-knowledge boundary: disabled workspace sources must be invisible to retrieval and source binding.
Creative:
may proceed without source evidence when no useful reference/scope exists
binds enabled workspace sources when the question references them or a source scope exists
cites evidence-backed claims
may add clearly bounded model reasoning, hypothesis, or opinion
Grounded:
binds permitted enabled evidence before answering
uses only that evidence for factual claims
returns an insufficient-evidence answer or intelligent clarification when the source support is not enough
Workload Strategy
Workload planning runs after the evidence regime and evidence-binding decision.
chathandles bounded single-task execution.chat_map_reducehandles large evidence context when the task is still a simple synthesis.agent_map_refine_composehandles complex, multi-source, multi-step work with the existing bounded Map -> Refine -> Accumulate -> Compose executor.
The same workload strategies are available under both Creative and Grounded. The evidence regime controls what the executor is allowed to claim; the workload strategy controls how much work is needed to produce the answer.
Agentic selection has priority over evidence-size pressure: a multi-step task is
never downgraded to chat_map_reduce. Map creates typed per-document work items
and runs bounded workers. Refine validates requested fields, evidence support,
and citations, and permits only configured retrieval/retry attempts inside the
routed scope. A durable accumulator preserves refined continuation-page work,
but it is state inside the Map-Refine-Compose method rather than a fourth
reasoning agent. Compose uses only supported typed results and permitted
citations. Agentic composition never falls through to the legacy map-reduce
reducer.
Latency, Cache, And Memory
The response path records authorization, context, routing, arbitration, trusted facts, source probing, discovery, planning, retrieval, persistence, and SSE timings. Document work records Map, Refine, Accumulate, and Compose separately. The routing benchmark records cold/warm p50 and p95 total latency, time to first progress, and time to first answer content. Numeric SLOs are locked only from repeatable live measurements on the target hardware and model configuration.
Application caching uses a Valkey namespace and policy separate from model-residency state. Typed intent keys include the normalized question, request-mode and source-bound context, bounded recent turns, authoritative conversation routing state, and classifier version. Discovery keys also include workspace catalog revision and algorithm version. Count/catalog truth, result sets, final answers, and conversation memory remain durable-source concerns; cache failures are misses. Typed routing and discovery use short single-flight leases to collapse duplicate cold work.
Routing state is updated synchronously. Typed memory-v2 episodes are durably enqueued, then embedded and indexed asynchronously. Identity, count, and result expansion turns are not embedded. Historical indexing is an explicit, checkpointed, idempotent CLI operation; it does not run as hidden API-startup work. V1 retrieval remains a temporary compatibility fallback.