[NOTICKET] feat(orchestrator): flat 6-intent router + gate + check skill

Rework the intent router from the 3-way source_hint classifier to a flat
6-intent handler router (chat, help, problem_statement, check,
unstructured_flow, structured_flow). Structured/unstructured data modality on
the slow path stays the Planner's job, not the router's.

- orchestration.py: RouterDecision { intent, rewritten_query, confidence };
kept GPT-4o + the classify() seam.
- intent_router.md: v2 prompt (labels, disambiguation, per-intent few-shots).
- chat_handler.py: dispatch on intent; chat/unstructured_flow/structured_flow/
check wired; problem_statement/help stubbed; back-compat source_hint on the
SSE intent event.
- gate.py: deterministic gate (structured_flow requires interview pass) +
AnalysisState stub contract (pending the lead's table).
- handlers/check.py: check_data/check_knowledge tool-pick + table render.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/agents/chat_handler.py

@@ -2,12 +2,14 @@
 
 End-to-end flow per user message:
 
-  1. `IntentRouter.classify` → `chat` / `unstructured` / `structured`.
-  2. Route:
-       - `chat`         → no context. Pass straight to ChatbotAgent.
-       - `structured`   → CatalogReader → QueryService → QueryResult.
-       - `unstructured` → DocumentRetriever (placeholder, raises until TAB
-                          ships) → list[DocumentChunk].
+  1. `OrchestratorAgent.classify` → RouterDecision (one of six intents).
+  2. Route by intent:
+       - `chat`              → no context. Pass straight to ChatbotAgent.
+       - `structured_flow`   → CatalogReader → slow path / QueryService.
+       - `unstructured_flow` → DocumentRetriever (placeholder, raises until TAB
+                               ships) → list[DocumentChunk].
+       - `check`             → check_data / check_knowledge tool → rendered table.
+       - `problem_statement` / `help` → placeholder (handlers pending).
   3. `ChatbotAgent.astream` → yield text tokens.
   4. Wrap each step into an SSE-style event dict so the API endpoint can
      stream them as Server-Sent Events.
@@ -33,6 +35,7 @@ from src.middlewares.logging import get_logger
 from src.retrieval.base import RetrievalResult
 
 from .chatbot import ChatbotAgent, DocumentChunk
+from .handlers.check import run_check
 from .orchestration import OrchestratorAgent
 
 if TYPE_CHECKING:
@@ -71,6 +74,7 @@ class ChatHandler:
             Callable[[str], SlowPathCoordinator] | None
         ) = None,
         analysis_store: AnalysisStore | None = None,
+        check_invoker_factory: Callable[[str], Any] | None = None,
         enable_tracing: bool = False,
     ) -> None:
         self._intent_router = intent_router
@@ -88,6 +92,9 @@ class ChatHandler:
         self._enable_slow_path = enable_slow_path
         self._slow_path_factory = slow_path_coordinator_factory
         self._analysis_store = analysis_store
+        # `check` skill: builds the data-access invoker (check_data/check_knowledge)
+        # per request with the authenticated user_id. Injectable for tests.
+        self._check_invoker_factory = check_invoker_factory
 
     # ------------------------------------------------------------------
     # Lazy default-dep builders
@@ -125,6 +132,14 @@ class ChatHandler:
             self._document_retriever = RetrievalRouter()
         return self._document_retriever
 
+    def _get_check_invoker(self, user_id: str) -> Any:
+        """Build the per-request data-access invoker for the `check` skill."""
+        if self._check_invoker_factory is not None:
+            return self._check_invoker_factory(user_id)
+        from ..tools.data_access import DataAccessToolInvoker
+
+        return DataAccessToolInvoker(user_id, self._get_catalog_reader())
+
     # ------------------------------------------------------------------
     # Public entry
     # ------------------------------------------------------------------
@@ -147,7 +162,12 @@ class ChatHandler:
             yield {"event": "error", "data": f"Could not classify message: {e}"}
             return
 
-        yield {"event": "intent", "data": decision.model_dump_json()}
+        intent = decision.intent
+        # Back-compat: the frontend still reads `source_hint` off the intent event.
+        # Derive it from the new intent until the frontend migrates to `intent`.
+        event_data = decision.model_dump()
+        event_data["source_hint"] = _intent_to_source_hint(intent)
+        yield {"event": "intent", "data": json.dumps(event_data)}
 
         rewritten = decision.rewritten_query or message
         query_result = None
@@ -155,7 +175,7 @@ class ChatHandler:
         raw_chunks: Any = None
 
         # ---- 2. Route ------------------------------------------------
-        if decision.source_hint == "structured":
+        if intent == "structured_flow":
             try:
                 # One memoizing reader per request: the same catalog is otherwise
                 # re-fetched from the catalog DB 4-5x across the slow-path run. This
@@ -182,7 +202,7 @@ class ChatHandler:
                 )
                 yield {"event": "error", "data": f"Structured query failed: {e}"}
                 return
-        elif decision.source_hint == "unstructured":
+        elif intent == "unstructured_flow":
             try:
                 raw_chunks = await self._get_document_retriever().retrieve(
                     rewritten, user_id
@@ -201,13 +221,35 @@ class ChatHandler:
                 )
                 yield {"event": "error", "data": f"Document retrieval failed: {e}"}
                 return
+        elif intent == "check":
+            try:
+                invoker = self._get_check_invoker(user_id)
+                text = await run_check(rewritten, invoker)
+            except Exception as e:
+                logger.error("check route failed", user_id=user_id, error=str(e))
+                yield {"event": "error", "data": f"Lookup failed: {e}"}
+                return
+            yield {"event": "chunk", "data": text}
+            yield {"event": "done", "data": ""}
+            return
+        elif intent in ("problem_statement", "help"):
+            # The router emits these new intents, but their handlers are not wired
+            # yet (PS skill is the lead's; help skill deferred). Placeholder keeps
+            # dispatch exhaustive; real handlers land in a follow-up step.
+            logger.info("unwired intent stub", intent=intent)
+            yield {"event": "chunk", "data": _stub_message(intent)}
+            yield {"event": "done", "data": ""}
+            return
         # else: chat path — no context
 
         # ---- 2b. Emit sources ---------------------------------------
-        sources = _build_sources(
-            decision.source_hint, user_id, query_result, raw_chunks
+        sources = _build_sources(intent, user_id, query_result, raw_chunks)
+        logger.info(
+            "built sources",
+            intent=intent,
+            sources_count=len(sources),
+            raw_chunks_count=len(raw_chunks) if raw_chunks else 0,
         )
-        logger.info("built sources", source_hint=decision.source_hint, sources_count=len(sources), raw_chunks_count=len(raw_chunks) if raw_chunks else 0)
         yield {"event": "sources", "data": json.dumps(sources)}
 
         # ---- 3. Stream answer ----------------------------------------
@@ -378,19 +420,33 @@ class ChatHandler:
         yield {"event": "done", "data": ""}
 
 
+def _intent_to_source_hint(intent: str) -> str:
+    """Map a router intent to the legacy `source_hint` value (frontend back-compat)."""
+    if intent == "structured_flow":
+        return "structured"
+    if intent == "unstructured_flow":
+        return "unstructured"
+    return "chat"
+
+
+def _stub_message(intent: str) -> str:
+    """Placeholder reply for intents whose handlers are not wired yet."""
+    return f"The '{intent}' route is recognized but not wired up yet."
+
+
 def _build_sources(
-    source_hint: str,
+    intent: str,
     user_id: str,
     query_result: Any,
     raw_chunks: Any,
 ) -> list[dict[str, Any]]:
     """Build the sources payload for the SSE `sources` event.
 
-    - structured: one entry per executed table (table_name only).
-    - unstructured: deduped by (document_id, page_label), Phase 1 shape.
+    - structured_flow: one entry per executed table (table_name only).
+    - unstructured_flow: deduped by (document_id, page_label), Phase 1 shape.
     - chat or error: empty list.
     """
-    if source_hint == "structured":
+    if intent == "structured_flow":
         if query_result is None or getattr(query_result, "error", None):
             return []
         table_name = getattr(query_result, "table_name", "") or ""
@@ -402,7 +458,7 @@ def _build_sources(
             "page_label": None,
         }]
 
-    if source_hint == "unstructured" and raw_chunks:
+    if intent == "unstructured_flow" and raw_chunks:
         seen: set[tuple[Any, Any]] = set()
         sources: list[dict[str, Any]] = []
         for item in raw_chunks:

src/agents/gate.py

@@ -0,0 +1,71 @@
+"""Deterministic routing gate — policy check over the router's intent.
+
+After the LLM router picks an intent, the gate checks it against the per-analysis
+Analysis State and returns the **effective** intent: allow as-is, or redirect. No
+LLM, no I/O in `gate()` itself.
+
+Only one rule has teeth in v1: an analytical request (`structured_flow`) requires a
+passed interview (`interview_status == "pass"`); otherwise it is redirected to
+`problem_statement` so the user defines the goal first. Everything else passes
+through. `generate_report` is not a router intent (button/report API), so it is not
+gated here.
+
+`AnalysisState` + `get_analysis_state` are a **stub contract** today — the real
+per-analysis row is owned by the lead (Postgres). Field names are pinned to match
+the planned table so the swap is zero-change. See `ORCHESTRATOR_REWORK_PLAN.md` §4.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from src.agents.orchestration import Intent
+from src.middlewares.logging import get_logger
+
+logger = get_logger("gate")
+
+InterviewStatus = Literal["not_pass", "pass"]
+
+
+class AnalysisState(BaseModel):
+    """Per-analysis state the gate reads every turn (stub contract).
+
+    Owned by the lead's Analysis State table; consumed here read-only.
+    `report_status` is `no_report` or a version tag (`V1`, `V2`, …) — unused by the
+    gate today, carried for the dispatch layer.
+    """
+
+    user_id: str
+    data_source_ids: list[str] = Field(default_factory=list)
+    interview_status: InterviewStatus = "not_pass"
+    report_status: str = "no_report"
+
+
+def gate(intent: Intent, state: AnalysisState) -> Intent:
+    """Return the effective intent after applying the deterministic gate policy.
+
+    `structured_flow` requires `interview_status == "pass"`; otherwise redirect to
+    `problem_statement`. All other intents pass through unchanged.
+    """
+    if intent == "structured_flow" and state.interview_status != "pass":
+        logger.info(
+            "gate redirect",
+            requested=intent,
+            effective="problem_statement",
+            reason="interview_not_passed",
+        )
+        return "problem_statement"
+    return intent
+
+
+async def get_analysis_state(analysis_id: str) -> AnalysisState:
+    """Load the Analysis State for an analysis (STUB).
+
+    Returns the table-default state until the lead's Postgres-backed reader lands.
+    Swap this body for the real query; the signature + return type stay frozen so
+    the dispatch layer never changes.
+    """
+    logger.debug("get_analysis_state stub", analysis_id=analysis_id)
+    return AnalysisState(user_id="", interview_status="not_pass")

src/agents/handlers/__init__.py

@@ -0,0 +1 @@
+"""Deterministic skill handlers dispatched by the orchestrator (non-LLM)."""

src/agents/handlers/check.py

@@ -0,0 +1,64 @@
+"""`check` skill handler — deterministic data/document inventory (no LLM).
+
+The router emits a single `check` intent; this handler picks the concrete tool
+(`check_data` for structured sources, `check_knowledge` for documents) and renders
+the tool's `ToolOutput` table into a markdown reply. Tool selection is a cheap
+keyword cue today; once Analysis State is wired it can prefer the bound-source
+type. See `ORCHESTRATOR_REWORK_PLAN.md` §2.
+
+The data-access invoker never throws (§8.4); `render_tool_output` handles the
+`error` envelope defensively.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from src.tools.contracts import ToolOutput
+
+if TYPE_CHECKING:
+    from src.agents.slow_path.invoker import ToolInvoker
+
+# Cues that point at documents rather than structured data. Anything else → data.
+_KNOWLEDGE_CUES = (
+    "document",
+    "docs",
+    "doc ",
+    "file",
+    "pdf",
+    "docx",
+    ".txt",
+    "uploaded",
+    "knowledge",
+)
+
+
+def pick_check_tool(message: str) -> str:
+    """Choose `check_knowledge` for document-flavoured asks, else `check_data`."""
+    lowered = message.lower()
+    if any(cue in lowered for cue in _KNOWLEDGE_CUES):
+        return "check_knowledge"
+    return "check_data"
+
+
+def render_tool_output(out: ToolOutput) -> str:
+    """Render a `check_*` ToolOutput table into a markdown reply."""
+    if out.kind == "error":
+        return f"Sorry, I couldn't look that up: {out.error}"
+    columns = out.columns or []
+    rows = out.rows or []
+    if not rows:
+        return "Nothing registered yet — I don't see any matching sources."
+    header = "| " + " | ".join(columns) + " |"
+    separator = "| " + " | ".join("---" for _ in columns) + " |"
+    body = "\n".join(
+        "| " + " | ".join(str(cell) for cell in row) + " |" for row in rows
+    )
+    return f"{header}\n{separator}\n{body}"
+
+
+async def run_check(message: str, invoker: ToolInvoker) -> str:
+    """Pick the check tool, invoke it (no args = inventory), render the result."""
+    tool = pick_check_tool(message)
+    out = await invoker.invoke(tool, {})
+    return render_tool_output(out)

src/agents/orchestration.py

@@ -1,13 +1,17 @@
-"""OrchestratorAgent — classifies a user message and emits source_hint.
+"""OrchestratorAgent — classifies a user message into one of six intents.
 
-Output: needs_search (bool) + source_hint ∈ { chat, unstructured, structured }
-+ rewritten_query (standalone form of the user's question, history-resolved).
+Output: RouterDecision { intent, rewritten_query, confidence }.
 
-Phase 2 replaces the previous intent-classification body. The class name
-is preserved so existing import sites (`from src.agents.orchestration
-import OrchestratorAgent`) keep working. The default LLM chain is
-constructed lazily so the module is import-safe even without `.env`
-populated.
+The router is a **handler-level** intent classifier, not a data-modality
+classifier: `structured_flow` routes to the slow Planner spine and
+`unstructured_flow` to the fast RAG path; the structured/unstructured data mix on
+the slow path is the Planner's job, not the router's. See
+`ORCHESTRATOR_REWORK_PLAN.md`.
+
+The class name `OrchestratorAgent` is preserved so existing import sites
+(`from src.agents.orchestration import OrchestratorAgent`) keep working. The
+default LLM chain is built lazily so the module is import-safe even without
+`.env` populated.
 """
 
 from __future__ import annotations
@@ -25,7 +29,14 @@ from src.middlewares.logging import get_logger
 
 logger = get_logger("orchestrator")
 
-SourceHint = Literal["chat", "unstructured", "structured"]
+Intent = Literal[
+    "chat",
+    "help",
+    "problem_statement",
+    "check",
+    "unstructured_flow",
+    "structured_flow",
+]
 
 _PROMPT_PATH = (
     Path(__file__).resolve().parent.parent
@@ -35,21 +46,29 @@ _PROMPT_PATH = (
 )
 
 
-class IntentRouterDecision(BaseModel):
+class RouterDecision(BaseModel):
     """LLM output. Pydantic so it can be used with `with_structured_output`."""
 
-    needs_search: bool = Field(
-        ..., description="True if we must look at the user's data to answer."
-    )
-    source_hint: SourceHint = Field(
+    intent: Intent = Field(
         ...,
-        description="Which downstream path: 'chat' (no lookup), "
-        "'unstructured' (PDF/DOCX/TXT prose), 'structured' (DB / tabular file).",
+        description=(
+            "Handler route for this message: 'chat' (conversational, no data), "
+            "'help' (what-to-do-next guidance), 'problem_statement' (define or "
+            "refine the analysis goal), 'check' (inventory: what data/documents "
+            "exist), 'unstructured_flow' (answer from documents, fast RAG), or "
+            "'structured_flow' (analytical question over data, slow Planner path)."
+        ),
     )
     rewritten_query: str | None = Field(
         None,
-        description="Standalone version of the question, history-resolved. "
-        "Null when needs_search=false.",
+        description=(
+            "Standalone version of the question, history-resolved. Null for "
+            "'chat' and 'help' (no data lookup needed)."
+        ),
+    )
+    confidence: float | None = Field(
+        None,
+        description="Classifier confidence in [0, 1]. Optional.",
     )
 
 
@@ -74,11 +93,11 @@ def _build_default_chain() -> Runnable:
             ("human", "{message}"),
         ]
     )
-    return prompt | llm.with_structured_output(IntentRouterDecision)
+    return prompt | llm.with_structured_output(RouterDecision)
 
 
 class OrchestratorAgent:
-    """Classifies a user message into chat / unstructured / structured.
+    """Classifies a user message into one of the six router intents.
 
     Inject `structured_chain` for tests; default builds the production
     Azure OpenAI chain on first use.
@@ -97,18 +116,14 @@ class OrchestratorAgent:
         message: str,
         history: list[BaseMessage] | None = None,
         callbacks: list | None = None,
-    ) -> IntentRouterDecision:
+    ) -> RouterDecision:
         chain = self._ensure_chain()
         payload = {"message": message, "history": history or []}
         if callbacks:
-            decision: IntentRouterDecision = await chain.ainvoke(
+            decision: RouterDecision = await chain.ainvoke(
                 payload, config={"callbacks": callbacks}
             )
         else:
             decision = await chain.ainvoke(payload)
-        logger.info(
-            "intent classified",
-            source_hint=decision.source_hint,
-            needs_search=decision.needs_search,
-        )
+        logger.info("intent classified", intent=decision.intent)
         return decision

src/config/prompts/intent_router.md

@@ -1,82 +1,119 @@
-You are the intent router for an AI data assistant. Given a user's latest message (and optionally recent conversation history), decide which downstream path should handle it.
+You are the intent router for an AI data assistant. Given a user's latest message (and optionally recent conversation history), decide which downstream **handler** should process it. You classify the route only — you do not answer the question.
 
 ## Output
 
 Return three fields:
 
-- **`needs_search`** — `true` if we must look at the user's data to answer; `false` for greetings, farewells, off-topic chitchat, or meta questions about the assistant itself.
-- **`source_hint`** — one of:
-  - `chat` — no data lookup needed (greetings, farewells, generic small talk).
-  - `unstructured` — the user is asking about a topic, concept, feature, or factual knowledge that may exist in uploaded documents (PDF / DOCX / TXT). The user does not need to explicitly mention a document.
-  - `structured` — the user is asking a **data question** answerable from a database or a tabular file (CSV / XLSX / Parquet). This includes counts, sums, top-N, filters, comparisons, trends, joins across registered structured sources.
-- **`rewritten_query`** — a **standalone** version of the user's question that incorporates necessary context from history. If the original message is already standalone, return it unchanged. If `needs_search` is `false`, leave this empty/null.
+- **`intent`** — exactly one of:
+  - `chat` — conversational, no data needed: greetings, farewells, thanks, "how are you", "what can you do", small talk.
+  - `help` — the user wants to know **what to do next** or how the process works ("what's the next step?", "how do I start?", "what should I do now?").
+  - `problem_statement` — the user wants to **define or refine the analysis goal**: the business problem, objectives, what to increase/decrease, targets/success metrics — or is answering questions about the goal.
+  - `check` — the user wants an **inventory** of what they have: "what data do I have?", "what columns are in this table?", "what documents did I upload?", "describe my dataset". This is metadata/listing, not analysis.
+  - `unstructured_flow` — the user asks about a **topic, concept, feature, explanation, or factual knowledge** that may live in uploaded documents (PDF/DOCX/TXT). Pure document Q&A. The user need not mention a document.
+  - `structured_flow` — the user asks an **analytical question over their data**: counts, sums, top-N, filters, comparisons, trends, correlations, segments, share-of-total, joins across structured sources. This routes to the slow analytical path.
+- **`rewritten_query`** — a **standalone** version of the user's question, with context from history resolved. If the message is already standalone, copy it verbatim. Leave empty/null for `chat` and `help`.
+- **`confidence`** — your confidence in the chosen intent, a number in [0, 1].
 
 ## Routing rules
 
-1. If the message is ONLY a pure greeting / farewell / thanks / "how are you" / "what can you do" / compliment with no factual question → `chat` + `needs_search=false`.
-2. If the message asks a data question answerable from a database or tabular file (counts, sums, top-N, filters, comparisons, trends, sheet rows, table columns) → `structured` + `needs_search=true`.
-3. If the message asks about a topic, concept, feature, explanation, summary, or factual knowledge — even without explicitly mentioning a document — route to `unstructured` + `needs_search=true`. The user may have uploaded relevant documents covering that topic.
-4. If ambiguous between structured and unstructured → prefer `unstructured`. Only prefer `structured` if there are clear signals of tabular/numeric data questions.
-5. Cross-source comparison ("compare DB sales to the customers.csv file") → `structured`. The planner sees both source types in one prompt and can correlate.
+1. Pure greeting / farewell / thanks / "what can you do" / compliment with no task → `chat`.
+2. "What do I do next / how do I proceed / where do I start" → `help`.
+3. The user states or refines a goal, objective, target, or success metric, or answers a goal-defining question → `problem_statement`.
+4. "What data / columns / tables / documents do I have", "describe my data", inventory or metadata requests → `check`.
+5. A question answerable from document prose — a topic, concept, feature, explanation, summary, or factual knowledge, even without naming a document → `unstructured_flow`.
+6. An analytical question answerable by computing over tabular/DB data (counts, sums, top-N, filters, comparisons, trends, correlations, segments) → `structured_flow`.
+
+## Disambiguation (the boundaries that matter)
+
+- **`check` vs `structured_flow`** — "what do I have / describe it" → `check`; "analyze / compute / trend / correlate / compare it" → `structured_flow`.
+- **`unstructured_flow` vs `structured_flow`** — pure document/concept Q&A → `unstructured_flow`; anything needing computation over tabular/DB data → `structured_flow`. **When in doubt between "analytical AND also needs document context" → `structured_flow`** (the analytical path can pull document context itself). Only choose `unstructured_flow` for *pure* document questions with no computation.
+- **`help` vs `problem_statement`** — "what's next?" → `help`; "here is my goal / let's define the objective" → `problem_statement`.
+- **`chat` vs everything else** — only use `chat` when there is no task and no data question at all.
 
 ## Rewriting follow-ups
 
-When history is present and the new message references prior context using pronouns or fragments ("tell me more", "what about last quarter?", "and by region?"), expand the rewritten_query into a fully standalone question. Example:
+When history is present and the new message references prior context with pronouns or fragments ("tell me more", "what about last quarter?", "and by region?"), expand `rewritten_query` into a fully standalone question. Example:
 
   History: "What was our top product last month?" → "Pro Plan Annual at $487k"
   Message: "How does that compare to Q1?"
   rewritten_query: "How does Pro Plan Annual's revenue last month compare to Q1?"
 
-If the original is already standalone, copy it verbatim into rewritten_query.
+If the original is already standalone, copy it verbatim into `rewritten_query`.
 
 ## Few-shot examples
 
 ```
 User: "Hi"
-→ needs_search=false, source_hint="chat", rewritten_query=null
+→ intent="chat", rewritten_query=null, confidence=0.99
 
 User: "Bye, thanks"
-→ needs_search=false, source_hint="chat", rewritten_query=null
+→ intent="chat", rewritten_query=null, confidence=0.99
 
 User: "What can you do?"
-→ needs_search=false, source_hint="chat", rewritten_query=null
+→ intent="chat", rewritten_query=null, confidence=0.95
 
-User: "How many orders did we get last month?"
-→ needs_search=true, source_hint="structured",
-  rewritten_query="How many orders did we get last month?"
+User: "Okay I uploaded my data, what do I do next?"
+→ intent="help", rewritten_query=null, confidence=0.93
+
+User: "How does this work? Where should I start?"
+→ intent="help", rewritten_query=null, confidence=0.9
+
+User: "I want to reduce customer churn next quarter, target under 5%."
+→ intent="problem_statement",
+  rewritten_query="Define the analysis goal: reduce customer churn next quarter to under 5%.",
+  confidence=0.9
+
+User: "My goal is to grow revenue in the north region."
+→ intent="problem_statement",
+  rewritten_query="Define the analysis goal: grow revenue in the north region.",
+  confidence=0.88
+
+User: "What data do I have?"
+→ intent="check", rewritten_query="What data sources do I have?", confidence=0.95
+
+User: "What columns are in the orders table?"
+→ intent="check", rewritten_query="What columns are in the orders table?", confidence=0.93
+
+User: "What documents have I uploaded?"
+→ intent="check", rewritten_query="What documents have I uploaded?", confidence=0.93
 
 User: "What does the Q1 board memo say about churn?"
-→ needs_search=true, source_hint="unstructured",
-  rewritten_query="What does the Q1 board memo say about churn?"
+→ intent="unstructured_flow",
+  rewritten_query="What does the Q1 board memo say about churn?", confidence=0.9
 
-User: "Top 5 customers by revenue this year"
-→ needs_search=true, source_hint="structured",
-  rewritten_query="Top 5 customers by revenue this year"
+User: "jelaskan tentang machine learning"
+→ intent="unstructured_flow", rewritten_query="Explain machine learning", confidence=0.85
 
 User: "apa key feature dari iot connectivity?"
-→ needs_search=true, source_hint="unstructured",
-  rewritten_query="What are the key features of IoT connectivity?"
+→ intent="unstructured_flow",
+  rewritten_query="What are the key features of IoT connectivity?", confidence=0.85
 
-User: "jelaskan tentang machine learning"
-→ needs_search=true, source_hint="unstructured",
-  rewritten_query="Explain machine learning"
+User: "How many orders did we get last month?"
+→ intent="structured_flow",
+  rewritten_query="How many orders did we get last month?", confidence=0.92
+
+User: "Top 5 customers by revenue this year"
+→ intent="structured_flow",
+  rewritten_query="Top 5 customers by revenue this year", confidence=0.93
 
-User: "bagaimana cara kerja neural network?"
-→ needs_search=true, source_hint="unstructured",
-  rewritten_query="How does a neural network work?"
+User: "Is there a correlation between discount and units sold?"
+→ intent="structured_flow",
+  rewritten_query="Is there a correlation between discount and units sold?", confidence=0.9
 
-User: "what is the main purpose of this system?"
-→ needs_search=true, source_hint="unstructured",
-  rewritten_query="What is the main purpose of this system?"
+User: "How has monthly revenue trended by region, and what stands out?"
+→ intent="structured_flow",
+  rewritten_query="How has monthly revenue trended by region this year, and what is unusual?",
+  confidence=0.88
 
 History: assistant: "Pro Plan Annual led at $487,200 in April."
 User: "And in March?"
-→ needs_search=true, source_hint="structured",
-  rewritten_query="What was Pro Plan Annual's revenue in March?"
+→ intent="structured_flow",
+  rewritten_query="What was Pro Plan Annual's revenue in March?", confidence=0.9
 ```
 
 ## Constraints
 
-- Do not invent data. If the question is factual or knowledge-based (not clearly tabular), route to `unstructured` and let the retriever decide. Only route to `structured` if the question clearly involves counts, sums, filters, or trends from tabular sources.
+- Pick exactly one `intent`. Do not invent values outside the six listed.
+- Prefer `unstructured_flow` over `structured_flow` only for pure knowledge/document questions; prefer `structured_flow` whenever computation over data is involved.
 - Do not refuse — refusal happens later in guardrails. Just classify.
 - One JSON object as output; no prose, no markdown.