docs/reports/router_kb_stack_route_map.md

Router KB Stack Route Map

This document maps the live router knowledgebase stack as it exists in the current canary lane. It focuses on the control flow that matters for router docs, lifecycle, search, replacements, fleet parsing, survey handling, and the bounded GPT orchestration hook.

1. Top-Level Entry Points

• backend/app/knowledgebase/core.py::_explicit_mode_from_message()
  • Chooses the coarse router domain before retrieval starts.
  • Routes obvious router lifecycle / router docs questions into the workbook-backed lane.
• backend/app/knowledgebase/core.py::handle_message()
  • Main dispatcher.
  • Applies mode normalization, workbook bootstrap, and final provenance assembly.
• backend/app/knowledgebase/core.py::_router_workbook_fast_answer()
  • Primary workbook-backed execution path for router docs and router lifecycle questions.
  • Builds the execution plan first, then branches to compare / details / lifecycle / fleet / replacements / search / antenna / survey / guided advisor renderers.

2. Query Planning And Intent Routing

• backend/app/rapid_router/router_intelligence.py::parse_router_intelligence_query()
  • Deterministic parser for router-specific intent, device tokens, search filters, survey context, and current-only defaults.
  • Produces the shared RouterIntelligenceQuery object.
• backend/app/knowledgebase/core.py::_router_workbook_build_execution_plan()
  • Builds the execution contract before answer generation.
  • Calls the bounded GPT orchestration hook only when the query is ambiguous enough to justify it.
• backend/app/knowledgebase/core.py::_router_workbook_gpt_orchestrated_query()
  • Bounded GPT planner / reranker.
  • Allowed output: intent, device texts, manufacturer text, current_only, limit, search filters, survey key, and a short reason.
  • Not allowed: facts, specs, lifecycle values, pricing, or policy.
• backend/app/knowledgebase/core.py::_router_query_plan_from_response()
  • Converts the parsed/orchestrated query into the canonical RouterQueryPlan.
  • Carries intent, answer mode, evidence mode, clarification policy, entities, candidate families, and required fields.

3. Retrieval Branches

Router Docs

• backend/app/knowledgebase/core.py::_details_result()
  • Workbook-backed single-device detail renderer.
• backend/app/knowledgebase/core.py::_compare_result()
  • Workbook-backed compare renderer with conservative field handling.
• backend/app/knowledgebase/core.py::_router_workbook_ranked_search()
  • Current-only shortlist / feature-filter search path.
• backend/app/knowledgebase/core.py::_router_workbook_survey_interpretation()
  • Survey interpretation branch.
• backend/app/knowledgebase/core.py::_router_workbook_vehicle_5g_recommendation_fast()
  • Vehicle / antenna family decision branch.

Router Lifecycle

• backend/app/knowledgebase/core.py::_lifecycle_result()
  • Lifecycle status, EOS / EOL, and migration ranking path.
• backend/app/knowledgebase/core.py::_fleet_result()
  • Fleet ranking and phased replacement path.
• backend/app/knowledgebase/core.py::_replacements_result()
  • Replacement lane rendering for single-device replacement asks.
• backend/app/knowledgebase/core.py::_build_router_workbook_fleet_row_views()
  • Shared row parser used by fleet import and fleet lifecycle rendering.
• backend/app/knowledgebase/core.py::_router_workbook_replacement_evidence_from_analysis()
  • Shared evidence builder for replacement lanes.

Guided Advisor

• backend/app/knowledgebase/core.py::_router_workbook_guided_advisor_questions()
  • Structured intake question set.
• backend/app/knowledgebase/core.py::_handle_router_workbook_guided_advisor_followup()
  • Stateful intake loop and shortlist generation.

4. Evidence Rendering And Provenance

• backend/app/knowledgebase/core.py::RouterEvidenceItem
  • Canonical evidence item for router answer traces and source bundles.
• backend/app/knowledgebase/core.py::RouterFleetEvidenceRow
  • Canonical row-level evidence for fleet and replacement ordering.
• backend/app/knowledgebase/core.py::_router_evidence_item()
  • Normalizes source type, document, model alias, field label, values, provenance, confidence, and uncertainty flags.
• backend/app/knowledgebase/core.py::_router_trace_evidence_bundle()
  • Converts answer traces into structured evidence.
• backend/app/knowledgebase/core.py::_router_source_evidence_bundle()
  • Converts cited source entries into structured evidence.
• backend/app/knowledgebase/core.py::_dedupe_router_evidence_bundle()
  • Deduplicates evidence so the final meta payload stays small and stable.
• backend/app/knowledgebase/core.py::_fleet_result() and _replacements_result()
  • Renderer entry points that surface structured row evidence back into the final answer.

5. Alias / Entity Resolution

• backend/app/rapid_router/router_intelligence.py::extract_router_device_tokens()
  • Tokenizes and canonicalizes likely router model references.
• backend/app/rapid_router/router_intelligence.py::_prune_shadowed_router_device_tokens()
  • Removes shadow tokens when a longer canonical alias already covers the same model family.
• backend/app/knowledgebase/core.py::_normalize_router_model()
  • Core alias normalizer that follows the catalog alias map.
• backend/app/knowledgebase/core.py::_router_workbook_resolve_detail_or_family()
  • Workbook-side exact / family / alias resolution contract.
• backend/app/knowledgebase/core.py::_router_workbook_collapse_family_ambiguity()
  • Collapses ambiguous family matches only when the candidate set is safe to collapse.

6. Data Sources And Runtime Stores

• backend/app/rapid_router/catalog_db.py
  • Catalog normalization and current-store search behavior.
• backend/data/rapid_router/store.json
  • Rapid Router runtime store.
• backend/app/knowledgebase/data/normalized/router_safe_5g_target_overlay.csv
  • Router alias / target overlay.
• routers_eos_eol_by_sku.csv
  • Lifecycle source table used for EOS/EOL and fallback migration paths.

7. What Is Still Missing

The route is now explicit, but a few global pieces are still missing for a truly stable router lane:

• A single resolver object that every branch can inspect directly, rather than deriving resolution state from raw token lists in multiple places.
• A richer evidence record that includes citation anchors, source-table context, and entity-role metadata for every branch, not just fleet / replacements.
• A route profiler that records timing by stage so the slow multi-entity paths can be targeted instead of guessed at.
• Artifact freshness governance for the legacy 20-case smoke slice versus the 140-case benchmark pack.