Merge pull request #39 from HendrikReh/feat/apex-2gn-agentic-search

feat(rag-server): add routed agentic search foundation

Author: HendrikReh

Justfile

@@ -65,6 +65,10 @@ integration-test: up
     CARGO_TARGET_DIR={{target_dir_itest}} cargo test -p rag-core --test integration_lifecycle -- --ignored --nocapture
     CARGO_TARGET_DIR={{target_dir_itest}} cargo test -p rag-core --test integration_retrieval -- --ignored --nocapture
 
+# Offline benchmark for routed agentic search.
+agentic-eval: up
+    CARGO_TARGET_DIR={{target_dir_itest}} cargo test -p rag-server --test agentic_eval -- --ignored --nocapture --test-threads=1
+
 # Optional provider/native smoke tests.
 # These require extra local setup such as PDFium, Tesseract, or live LLM credentials.
 smoke-test: up

config/agents/agentic_search_v1.yaml

@@ -0,0 +1,40 @@
+# Routed search milestone-1 graph:
+# - route the query deterministically
+# - fall back to a single-pass baseline answer for simple facts
+# - otherwise retrieve evidence and compose the answer from retrieved chunks
+
+agent_id: agentic_search_v1
+description: >
+  Routed search agent that deterministically selects between a single-pass
+  baseline answer and an evidence-first composition branch.
+spec_version: "1.0"
+
+required_tools:
+  - retrieval.dense
+  - retrieval.sparse
+  - retrieval.hybrid
+  - retrieval.fts
+  - retrieval.expand_chunk_neighbors
+  - retrieval.fetch_document
+
+tasks:
+  - route_query
+  - baseline_answer
+  - retrieve_evidence
+  - compose_answer
+  - final_answer
+
+graph:
+  start_task: route_query
+  tasks:
+    - route_query
+    - baseline_answer
+    - retrieve_evidence
+    - compose_answer
+    - final_answer
+  edges:
+    - { from: route_query, to: retrieve_evidence, condition_key: route_to_agentic_search }
+    - { from: route_query, to: baseline_answer }
+    - { from: retrieve_evidence, to: compose_answer }
+    - { from: baseline_answer, to: final_answer }
+    - { from: compose_answer, to: final_answer }

crates/agent-core/src/lib.rs

@@ -12,20 +12,22 @@
 //! - [`ports`] — Adapter traits (`RetrievalPort`, `ChatPort`, `ApprovalPort`)
 //! - [`types`] — Domain value types (`AgentState`, query/result structs)
 //! - [`classify`] — Deterministic query classification heuristics
+//! - [`route`] — Deterministic routed-search heuristics
 //! - [`runtime`] — `AgentRuntime` trait and the graph-flow-backed implementation
 
 pub mod classify;
 pub mod ports;
+pub mod route;
 pub mod runtime;
 pub mod spec;
 pub mod types;
 
-pub use ports::{ApprovalPort, ChatPort, RetrievalPort};
+pub use ports::{ApprovalPort, BaselineAnswerPort, ChatPort, RetrievalPort};
 pub use runtime::AgentRuntime;
 pub use spec::{
     AgentContextProfile, AgentDedupeMode, AgentGuardrailsProfile, AgentPolicies,
     AgentReactActionType, AgentReactConfig, AgentReactStopConditions, AgentRegistry,
     AgentRetrievalMode, AgentRetrievalProfile, AgentRetrievalStep, AgentSpec, AgentToolFilters,
     DefaultToolRegistry, GuardrailActionMode, ToolRegistry, substitute_placeholders,
 };
-pub use types::{AgentRunResult, AgentState, QueryType};
+pub use types::{AgentRunResult, AgentState, QueryType, RouteDecision, RoutePath};

crates/agent-core/src/ports.rs

@@ -4,18 +4,67 @@
 //! Implementations live outside this crate (typically in `rag-server`), keeping
 //! agent-core free of concrete storage, LLM, or approval-UI dependencies.
 
-use crate::types::{CheckpointDecision, PendingCheckpoint, ScoredChunk};
+use crate::types::{CheckpointDecision, GroundedAnswer, PendingCheckpoint, ScoredChunk};
 
 /// Hybrid retrieval capability.
 #[async_trait::async_trait]
 pub trait RetrievalPort: Send + Sync {
-    /// Execute hybrid search (dense + sparse with RRF fusion).
+    async fn search_dense(
+        &self,
+        collection: &str,
+        query: &str,
+        tenant: &str,
+        limit: u64,
+    ) -> anyhow::Result<Vec<ScoredChunk>>;
+
+    async fn search_sparse(
+        &self,
+        collection: &str,
+        query: &str,
+        tenant: &str,
+        limit: u64,
+    ) -> anyhow::Result<Vec<ScoredChunk>>;
+
     async fn search_hybrid(
         &self,
         collection: &str,
         query: &str,
         tenant: &str,
     ) -> anyhow::Result<Vec<ScoredChunk>>;
+
+    async fn search_fts(
+        &self,
+        collection: &str,
+        query: &str,
+        tenant: &str,
+        limit: u64,
+    ) -> anyhow::Result<Vec<ScoredChunk>>;
+
+    async fn expand_chunk_neighbors(
+        &self,
+        tenant: &str,
+        document_id: &str,
+        chunk_index: i32,
+        before: i32,
+        after: i32,
+    ) -> anyhow::Result<Vec<ScoredChunk>>;
+
+    async fn fetch_document(
+        &self,
+        tenant: &str,
+        document_id: &str,
+    ) -> anyhow::Result<serde_json::Value>;
+}
+
+#[async_trait::async_trait]
+pub trait BaselineAnswerPort: Send + Sync {
+    async fn answer_single_shot(
+        &self,
+        query: &str,
+        collection: &str,
+        tenant: &str,
+        language: Option<&str>,
+    ) -> anyhow::Result<GroundedAnswer>;
 }
 
 /// LLM summarization / answer generation capability.

crates/agent-core/src/route.rs

@@ -0,0 +1,127 @@
+use crate::types::{QueryClass, RetrievalProfileId, RouteDecision, RoutePath};
+
+pub fn route_query(query: &str) -> RouteDecision {
+    let lower = query.to_ascii_lowercase();
+
+    let has_compare =
+        lower.contains("compare ") || lower.contains("tradeoff") || lower.contains("vs ");
+    let has_how_to =
+        lower.contains("how do i") || lower.contains("runbook") || lower.contains("steps");
+    let has_ambiguity = lower.contains("which ") || lower.contains("difference between");
+    let has_exploratory = lower.contains("find ")
+        || lower.contains("show me")
+        || lower.contains("search for")
+        || lower.contains("overview of")
+        || lower.contains("documents about")
+        || lower.contains("docs about");
+    let has_time = lower.contains("today") || lower.contains("latest") || lower.contains("current");
+
+    // QueryClass uses first-match precedence. We still retain every matched
+    // heuristic in `reasons` below so run output shows the full signal set
+    // that the deterministic router observed.
+    let (selected_path, query_class, retrieval_profile, needs_multi_hop) = if has_compare {
+        (
+            RoutePath::AgenticSearch,
+            QueryClass::MultiHopResearch,
+            RetrievalProfileId::BroadThenExpand,
+            true,
+        )
+    } else if has_how_to {
+        (RoutePath::AgenticSearch, QueryClass::Procedural, RetrievalProfileId::LexicalFirst, false)
+    } else if has_ambiguity {
+        (
+            RoutePath::AgenticSearch,
+            QueryClass::AmbiguityDisambiguation,
+            RetrievalProfileId::LexicalFirst,
+            false,
+        )
+    } else if has_exploratory {
+        (
+            RoutePath::AgenticSearch,
+            QueryClass::ExploratorySearch,
+            RetrievalProfileId::BroadThenExpand,
+            false,
+        )
+    } else {
+        (RoutePath::SinglePassRag, QueryClass::SimpleFact, RetrievalProfileId::SimpleHybrid, false)
+    };
+
+    let mut reasons = Vec::new();
+    if has_compare {
+        reasons.push("compare".to_string());
+    }
+    if has_how_to {
+        reasons.push("procedural".to_string());
+    }
+    if has_ambiguity {
+        reasons.push("ambiguity".to_string());
+    }
+    if has_exploratory {
+        reasons.push("exploratory".to_string());
+    }
+    if reasons.is_empty() {
+        reasons.push("default".to_string());
+    }
+    if has_time {
+        reasons.push("time_sensitive".to_string());
+    }
+
+    RouteDecision {
+        selected_path,
+        query_class,
+        retrieval_profile,
+        ambiguity: has_ambiguity,
+        needs_multi_hop,
+        needs_high_evidence: has_compare || has_how_to || has_exploratory,
+        time_sensitive: has_time,
+        normalized_filters: Vec::new(),
+        reasons,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn simple_fact_routes_to_single_pass_rag() {
+        let decision = route_query("What is Rust?");
+        assert_eq!(decision.selected_path, RoutePath::SinglePassRag);
+        assert_eq!(decision.query_class, QueryClass::SimpleFact);
+        assert_eq!(decision.retrieval_profile, RetrievalProfileId::SimpleHybrid);
+    }
+
+    #[test]
+    fn multi_hop_query_routes_to_agentic_search() {
+        let decision = route_query("Compare Rust and Python tradeoffs for async services");
+        assert_eq!(decision.selected_path, RoutePath::AgenticSearch);
+        assert_eq!(decision.query_class, QueryClass::MultiHopResearch);
+        assert_eq!(decision.retrieval_profile, RetrievalProfileId::BroadThenExpand);
+        assert!(decision.needs_multi_hop);
+    }
+
+    #[test]
+    fn procedural_query_prefers_lexical_first() {
+        let decision = route_query("How do I rotate API keys in the auth runbook?");
+        assert_eq!(decision.selected_path, RoutePath::AgenticSearch);
+        assert_eq!(decision.query_class, QueryClass::Procedural);
+        assert_eq!(decision.retrieval_profile, RetrievalProfileId::LexicalFirst);
+    }
+
+    #[test]
+    fn multi_signal_queries_use_first_match_precedence() {
+        let decision = route_query("Compare steps to rotate API keys");
+        assert_eq!(decision.selected_path, RoutePath::AgenticSearch);
+        assert_eq!(decision.query_class, QueryClass::MultiHopResearch);
+        assert_eq!(decision.retrieval_profile, RetrievalProfileId::BroadThenExpand);
+        assert_eq!(decision.reasons, vec!["compare".to_string(), "procedural".to_string()]);
+    }
+
+    #[test]
+    fn exploratory_query_routes_to_agentic_search() {
+        let decision = route_query("Find documents about rollback timing for release incidents");
+        assert_eq!(decision.selected_path, RoutePath::AgenticSearch);
+        assert_eq!(decision.query_class, QueryClass::ExploratorySearch);
+        assert_eq!(decision.retrieval_profile, RetrievalProfileId::BroadThenExpand);
+    }
+}

crates/agent-core/src/runtime/graph_flow/keys.rs

@@ -6,6 +6,8 @@ pub const QUERY: &str = "query";
 pub const COLLECTION: &str = "collection";
 pub const TENANT: &str = "tenant";
 pub const QUERY_TYPE: &str = "query_type";
+pub const ROUTE_DECISION: &str = "route_decision";
+pub const ROUTE_TO_AGENTIC_SEARCH: &str = "route_to_agentic_search";
 pub const SEARCH_RESULTS: &str = "search_results";
 pub const SUMMARY: &str = "summary";
 pub const FINAL_ANSWER: &str = "final_answer";