agentic_codebase/grounding/
mod.rs

1//! Grounding — Anti-hallucination layer for code claims.
2//!
3//! Verifies that claims about code are backed by graph evidence.
4//! An agent cannot assert that code exists without graph confirmation.
5//!
6//! # Overview
7//!
8//! The grounding system extracts code references from natural-language claims
9//! and checks each one against the [`CodeGraph`]. Claims that reference
10//! symbols, functions, types, or files absent from the graph are flagged as
11//! ungrounded — potential hallucinations.
12//!
13//! # Usage
14//!
15//! ```ignore
16//! use agentic_codebase::grounding::{GroundingEngine, Grounded};
17//!
18//! let engine = GroundingEngine::new(&graph);
19//! let result = engine.ground_claim("The function process_payment validates the amount");
20//! ```
21//!
22//! [`CodeGraph`]: crate::graph::CodeGraph
23
24mod engine;
25
26pub use engine::{extract_code_references, GroundingEngine};
27
28/// Result of grounding a claim against the code graph.
29#[derive(Debug, Clone)]
30pub enum GroundingResult {
31    /// Claim fully supported by graph data.
32    Verified {
33        /// Evidence nodes backing each reference in the claim.
34        evidence: Vec<Evidence>,
35        /// Confidence score in [0.0, 1.0]. Higher means stronger backing.
36        confidence: f32,
37    },
38    /// Claim partially supported — some references found, others not.
39    Partial {
40        /// References that matched graph nodes.
41        supported: Vec<String>,
42        /// References with no graph backing.
43        unsupported: Vec<String>,
44        /// Possible corrections for the unsupported references.
45        suggestions: Vec<String>,
46    },
47    /// No graph backing — potential hallucination.
48    Ungrounded {
49        /// The original claim text.
50        claim: String,
51        /// Similar names from the graph that the claim may have intended.
52        suggestions: Vec<String>,
53    },
54}
55
56/// Evidence backing a code claim.
57///
58/// Each piece of evidence links to a specific node in the [`CodeGraph`]
59/// that supports one or more references in the claim.
60///
61/// [`CodeGraph`]: crate::graph::CodeGraph
62#[derive(Debug, Clone)]
63pub struct Evidence {
64    /// The code-unit ID in the graph.
65    pub node_id: u64,
66    /// Human-readable type label (e.g. "function", "type", "module").
67    pub node_type: String,
68    /// Simple name of the code unit.
69    pub name: String,
70    /// File path where the code unit is defined.
71    pub file_path: String,
72    /// Starting line number (if available).
73    pub line_number: Option<u32>,
74    /// A short code snippet or signature (if available).
75    pub snippet: Option<String>,
76}
77
78/// Trait for grounding code claims against a knowledge source.
79///
80/// Implementors hold a reference to some code knowledge base (typically a
81/// [`CodeGraph`]) and can verify whether natural-language claims about code
82/// are backed by real data.
83///
84/// [`CodeGraph`]: crate::graph::CodeGraph
85pub trait Grounded {
86    /// Verify a natural-language claim about code.
87    ///
88    /// Extracts code references from `claim`, checks each against the
89    /// backing graph, and returns a [`GroundingResult`] indicating full,
90    /// partial, or no support.
91    fn ground_claim(&self, claim: &str) -> GroundingResult;
92
93    /// Find all evidence nodes matching `name`.
94    ///
95    /// Searches by exact name first, then by qualified-name substring.
96    fn find_evidence(&self, name: &str) -> Vec<Evidence>;
97
98    /// Suggest graph names similar to `name` (for typo correction).
99    ///
100    /// Returns up to `limit` suggestions sorted by edit distance.
101    fn suggest_similar(&self, name: &str, limit: usize) -> Vec<String>;
102}
agentic_codebase/grounding/mod.rs

agentic_codebase/grounding/
mod.rs
