hirn_engine/observability/
write_path.rs

1use std::fmt;
2
3use hirn_core::types::{AgentId, Namespace};
4use hirn_core::{HirnError, MemoryId, TextRetention};
5
6use crate::admission::AdmissionDecision;
7
8#[derive(Debug, Clone, Copy, PartialEq, Eq)]
9pub enum RememberStatus {
10    Accepted,
11    Rejected,
12    Deferred,
13    Merged,
14    Failed,
15}
16
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub enum EmbeddingDisposition {
19    Provided,
20    Generated,
21    PendingRetry,
22    Missing,
23}
24
25#[derive(Debug, Clone, Copy, PartialEq, Eq)]
26pub enum WritePathOperationStatus {
27    Disabled,
28    SkippedFastPath,
29    Unavailable,
30    Applied,
31}
32
33#[derive(Debug, Clone)]
34pub struct AdmissionExplanation {
35    pub decision: AdmissionDecision,
36    pub controllers_consulted: Vec<String>,
37}
38
39#[derive(Debug, Clone, Copy, PartialEq)]
40pub struct RpeExplanation {
41    pub enabled: bool,
42    pub score: Option<f32>,
43    pub max_similarity: Option<f32>,
44    pub threshold: f32,
45    pub is_fast_path: bool,
46}
47
48#[derive(Debug, Clone, Copy, PartialEq, Eq)]
49pub struct WritePathOperationExplanation {
50    pub status: WritePathOperationStatus,
51    pub count: usize,
52}
53
54impl WritePathOperationExplanation {
55    #[must_use]
56    pub const fn disabled() -> Self {
57        Self {
58            status: WritePathOperationStatus::Disabled,
59            count: 0,
60        }
61    }
62
63    #[must_use]
64    pub const fn skipped_fast_path() -> Self {
65        Self {
66            status: WritePathOperationStatus::SkippedFastPath,
67            count: 0,
68        }
69    }
70
71    #[must_use]
72    pub const fn unavailable() -> Self {
73        Self {
74            status: WritePathOperationStatus::Unavailable,
75            count: 0,
76        }
77    }
78
79    #[must_use]
80    pub const fn applied(count: usize) -> Self {
81        Self {
82            status: WritePathOperationStatus::Applied,
83            count,
84        }
85    }
86}
87
88#[derive(Debug, Clone, PartialEq)]
89pub enum InterferenceDisposition {
90    None,
91    TriggerConsolidation {
92        namespaces: Vec<Namespace>,
93        backlog_score: f32,
94        cause: &'static str,
95    },
96    Suppressed {
97        reason: &'static str,
98        backlog_score: f32,
99    },
100}
101
102#[derive(Debug, Clone, PartialEq)]
103pub struct InterferenceExplanation {
104    pub score: f32,
105    pub disposition: InterferenceDisposition,
106}
107
108#[derive(Debug, Clone)]
109pub struct RememberExplanation {
110    pub status: RememberStatus,
111    pub actor_id: AgentId,
112    pub namespace: Namespace,
113    pub bypass_admission: bool,
114    pub memory_id: Option<MemoryId>,
115    pub admission: Option<AdmissionExplanation>,
116    pub embedding: EmbeddingDisposition,
117    pub rpe: Option<RpeExplanation>,
118    pub text_retention: TextRetention,
119    pub resources_extracted: bool,
120    pub prospective_indexing: WritePathOperationExplanation,
121    pub svo_extraction: WritePathOperationExplanation,
122    pub interference: Option<InterferenceExplanation>,
123    pub arrival_sequence: Option<u64>,
124    pub error: Option<String>,
125}
126
127impl RememberExplanation {
128    #[must_use]
129    pub(crate) fn new(
130        actor_id: AgentId,
131        namespace: Namespace,
132        bypass_admission: bool,
133        embedding: EmbeddingDisposition,
134        text_retention: TextRetention,
135    ) -> Self {
136        Self {
137            status: RememberStatus::Accepted,
138            actor_id,
139            namespace,
140            bypass_admission,
141            memory_id: None,
142            admission: None,
143            embedding,
144            rpe: None,
145            text_retention,
146            resources_extracted: false,
147            prospective_indexing: WritePathOperationExplanation::disabled(),
148            svo_extraction: WritePathOperationExplanation::disabled(),
149            interference: None,
150            arrival_sequence: None,
151            error: None,
152        }
153    }
154}
155
156#[derive(Debug)]
157pub struct RememberFailure {
158    pub error: HirnError,
159    pub explanation: RememberExplanation,
160}
161
162impl RememberFailure {
163    #[must_use]
164    pub(crate) fn new(error: HirnError, explanation: RememberExplanation) -> Self {
165        Self { error, explanation }
166    }
167}
168
169impl fmt::Display for RememberFailure {
170    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
171        write!(f, "{}", self.error)
172    }
173}
174
175impl std::error::Error for RememberFailure {
176    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
177        Some(&self.error)
178    }
179}
hirn_engine/observability/write_path.rs

hirn_engine/observability/
write_path.rs
