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
24pub mod citation;
25mod engine;
26pub mod hallucination;
27pub mod truth;
28
29pub use citation::{
30    Citation, CitationEngine, CitationStrength, CodeLocation, GroundedClaim, UngroundedClaim,
31    UngroundedReason,
32};
33pub use engine::{extract_code_references, GroundingEngine};
34pub use hallucination::{
35    Hallucination, HallucinationCheck, HallucinationDetector, HallucinationSeverity,
36    HallucinationType,
37};
38pub use truth::{MaintainedTruth, TruthInvalidation, TruthMaintainer, TruthStatus};
39
40/// Result of grounding a claim against the code graph.
41#[derive(Debug, Clone)]
42pub enum GroundingResult {
43    /// Claim fully supported by graph data.
44    Verified {
45        /// Evidence nodes backing each reference in the claim.
46        evidence: Vec<Evidence>,
47        /// Confidence score in [0.0, 1.0]. Higher means stronger backing.
48        confidence: f32,
49    },
50    /// Claim partially supported — some references found, others not.
51    Partial {
52        /// References that matched graph nodes.
53        supported: Vec<String>,
54        /// References with no graph backing.
55        unsupported: Vec<String>,
56        /// Possible corrections for the unsupported references.
57        suggestions: Vec<String>,
58    },
59    /// No graph backing — potential hallucination.
60    Ungrounded {
61        /// The original claim text.
62        claim: String,
63        /// Similar names from the graph that the claim may have intended.
64        suggestions: Vec<String>,
65    },
66}
67
68/// Evidence backing a code claim.
69///
70/// Each piece of evidence links to a specific node in the [`CodeGraph`]
71/// that supports one or more references in the claim.
72///
73/// [`CodeGraph`]: crate::graph::CodeGraph
74#[derive(Debug, Clone)]
75pub struct Evidence {
76    /// The code-unit ID in the graph.
77    pub node_id: u64,
78    /// Human-readable type label (e.g. "function", "type", "module").
79    pub node_type: String,
80    /// Simple name of the code unit.
81    pub name: String,
82    /// File path where the code unit is defined.
83    pub file_path: String,
84    /// Starting line number (if available).
85    pub line_number: Option<u32>,
86    /// A short code snippet or signature (if available).
87    pub snippet: Option<String>,
88}
89
90/// Trait for grounding code claims against a knowledge source.
91///
92/// Implementors hold a reference to some code knowledge base (typically a
93/// [`CodeGraph`]) and can verify whether natural-language claims about code
94/// are backed by real data.
95///
96/// [`CodeGraph`]: crate::graph::CodeGraph
97pub trait Grounded {
98    /// Verify a natural-language claim about code.
99    ///
100    /// Extracts code references from `claim`, checks each against the
101    /// backing graph, and returns a [`GroundingResult`] indicating full,
102    /// partial, or no support.
103    fn ground_claim(&self, claim: &str) -> GroundingResult;
104
105    /// Find all evidence nodes matching `name`.
106    ///
107    /// Searches by exact name first, then by qualified-name substring.
108    fn find_evidence(&self, name: &str) -> Vec<Evidence>;
109
110    /// Suggest graph names similar to `name` (for typo correction).
111    ///
112    /// Returns up to `limit` suggestions sorted by edit distance.
113    fn suggest_similar(&self, name: &str, limit: usize) -> Vec<String>;
114}
agentic_codebase/grounding/mod.rs

agentic_codebase/grounding/
mod.rs
