OSSS.ai.orchestration.routing.db_query_router¶
OSSS.ai.orchestration.routing.db_query_router
¶
DB Query Router (signals-only, no side effects).
This module is intentionally pure and stable: - It does NOT mutate execution_state. - It does NOT decide graph patterns directly. - It returns structured RoutingSignals that the Planner can consume.
Long-term design
request + exec_state --> RoutingSignals --> Planner --> ExecutionPlan --> GraphFactory
The bug you’ve been hitting happens when routing runs after the graph is compiled. This file avoids that by producing signals early (planning phase), and never “forcing” graph decisions inside the router.
Integration points: - Call compute_db_query_signals(exec_state, request, ...) during the planning pipeline (before GraphFactory.create_graph). - If signals.locked is True and signals.target == "data_query", the Planner should return an ExecutionPlan(pattern="data_query", agents=[...], entry_point="refiner", ...).
Heuristics (configurable): - Query prefix commands: "query ", "sql ", "select ", etc. - Known data-query topics/collections (from DataQueryRoute registry or exec_state hints) - Classifier intent/domain/topic signals - Lightweight keyword hints ("database", "table", etc.)
This is intentionally conservative: it should only route to data_query when there are clear signals; otherwise it returns target=None and lets other rules decide.
RoutingSignals
dataclass
¶
Structured routing result consumed by planning.
target
Intended entry target (e.g. "data_query", "refiner"). None means "no strong opinion; let planner decide".
locked
When True, planner should treat target as forced (higher priority than other rules).
reason
Human-readable reason (stable string for observability).
key
Optional stable categorization key, e.g. "action", "crud", "query_prefix".
DBQueryRouter
¶
Thin wrapper around compute_db_query_signals for dependency injection.
Example
router = DBQueryRouter(known_topics=data_query_registry.topics()) signals = router.compute(exec_state, request)
compute_db_query_signals(exec_state, request, *, query_prefixes=DEFAULT_QUERY_PREFIXES, db_keywords=DEFAULT_DB_KEYWORDS, known_topics=None, known_collections=None, lock_on_prefix=True, lock_on_known_topic=True)
¶
Return routing signals indicating whether this request should start in data_query.
This function is pure and safe to call multiple times.
Strong signals (can lock): - Query prefix (e.g. "query consents") - Classifier primary topic matches known data-query topics/collections
Medium signals (do NOT lock by default): - intent=="action" AND domain in DEFAULT_DATA_DOMAINS AND db keyword present
If no strong signals are present, returns RoutingSignals(target=None).