intent_classifier/
types.rs

1//! Core types for intent classification
2//!
3//! This module defines the fundamental types used throughout the intent classification library.
4
5use chrono::{DateTime, Utc};
6use serde::{Deserialize, Serialize};
7use std::collections::HashMap;
8use std::fmt;
9use uuid::Uuid;
10
11/// Custom error types for the intent classification system
12#[derive(Debug, thiserror::Error)]
13pub enum IntentError {
14    #[error("Classification failed: {0}")]
15    ClassificationFailed(String),
16    
17    #[error("Invalid parameter '{parameter}': {message}")]
18    InvalidParameter { parameter: String, message: String },
19    
20    #[error("Training failed: {0}")]
21    TrainingFailed(String),
22    
23    #[error("Serialization error: {0}")]
24    SerializationError(#[from] serde_json::Error),
25    
26    #[error("Invalid confidence value: {0}")]
27    InvalidConfidence(String),
28}
29
30/// Result type for intent classification operations
31pub type Result<T> = std::result::Result<T, IntentError>;
32
33/// Unique identifier for intents
34#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
35pub struct IntentId(pub String);
36
37impl fmt::Display for IntentId {
38    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
39        write!(f, "{}", self.0)
40    }
41}
42
43impl From<String> for IntentId {
44    fn from(s: String) -> Self {
45        IntentId(s)
46    }
47}
48
49impl From<&str> for IntentId {
50    fn from(s: &str) -> Self {
51        IntentId(s.to_string())
52    }
53}
54
55/// Confidence score (0.0 to 1.0)
56#[derive(Debug, Clone, Copy, PartialEq, PartialOrd, Serialize, Deserialize)]
57pub struct Confidence(f64);
58
59impl Confidence {
60    /// Create a new confidence score
61    pub fn new(value: f64) -> Result<Self> {
62        if (0.0..=1.0).contains(&value) {
63            Ok(Confidence(value))
64        } else {
65            Err(IntentError::InvalidParameter {
66                parameter: "confidence".to_string(),
67                message: format!("Confidence must be between 0.0 and 1.0, got {}", value),
68            })
69        }
70    }
71    
72    /// Get the confidence value
73    pub fn value(&self) -> f64 {
74        self.0
75    }
76    
77    /// Check if confidence is high (>= 0.8)
78    pub fn is_high(&self) -> bool {
79        self.0 >= 0.8
80    }
81    
82    /// Check if confidence is medium (0.5 to 0.8)
83    pub fn is_medium(&self) -> bool {
84        self.0 >= 0.5 && self.0 < 0.8
85    }
86    
87    /// Check if confidence is low (< 0.5)
88    pub fn is_low(&self) -> bool {
89        self.0 < 0.5
90    }
91}
92
93impl Default for Confidence {
94    fn default() -> Self {
95        Confidence(1.0)
96    }
97}
98
99impl From<Confidence> for f64 {
100    fn from(confidence: Confidence) -> Self {
101        confidence.0
102    }
103}
104
105/// Intent classification result
106#[derive(Debug, Clone, Serialize, Deserialize)]
107pub struct IntentPrediction {
108    /// The predicted intent
109    pub intent: IntentId,
110    
111    /// Confidence score for the prediction
112    pub confidence: Confidence,
113    
114    /// Alternative intents with their confidence scores
115    pub alternative_intents: Vec<(IntentId, Confidence)>,
116    
117    /// Human-readable reasoning for the classification
118    pub reasoning: String,
119}
120
121/// Training example for intent classification
122#[derive(Debug, Clone, Serialize, Deserialize)]
123pub struct TrainingExample {
124    /// The input text
125    pub text: String,
126    
127    /// The correct intent for this text
128    pub intent: IntentId,
129    
130    /// Confidence score for this example (0.0 to 1.0)
131    pub confidence: f64,
132    
133    /// Source of this training example
134    pub source: TrainingSource,
135}
136
137/// Source of training data
138#[derive(Debug, Clone, Serialize, Deserialize)]
139pub enum TrainingSource {
140    /// Bootstrap data provided with the library
141    Bootstrap,
142    
143    /// User-provided feedback
144    UserFeedback,
145    
146    /// Programmatically added examples
147    Programmatic,
148}
149
150/// Feature vector for machine learning
151#[derive(Debug, Clone, Serialize, Deserialize)]
152pub struct FeatureVector {
153    /// Text-based features (e.g., TF-IDF)
154    pub text_features: Vec<f64>,
155    
156    /// Context-based features (e.g., text length, word count)
157    pub context_features: Vec<f64>,
158    
159    /// Additional metadata features
160    pub metadata: HashMap<String, f64>,
161}
162
163/// Configuration for the intent classifier
164#[derive(Debug, Clone, Serialize, Deserialize)]
165pub struct ClassifierConfig {
166    /// Number of dimensions for feature vectors
167    pub feature_dimensions: usize,
168    
169    /// Maximum vocabulary size
170    pub max_vocabulary_size: usize,
171    
172    /// Minimum confidence threshold for predictions
173    pub min_confidence_threshold: f64,
174    
175    /// Number of feedback examples required before retraining
176    pub retraining_threshold: usize,
177    
178    /// Whether to enable debug logging
179    pub debug_mode: bool,
180}
181
182impl Default for ClassifierConfig {
183    fn default() -> Self {
184        Self {
185            feature_dimensions: 1000,
186            max_vocabulary_size: 10000,
187            min_confidence_threshold: 0.3,
188            retraining_threshold: 10,
189            debug_mode: false,
190        }
191    }
192}
193
194/// Statistics about the classifier
195#[derive(Debug, Clone, Serialize, Deserialize)]
196pub struct ClassifierStats {
197    /// Number of training examples
198    pub training_examples: usize,
199    
200    /// Size of the vocabulary
201    pub vocabulary_size: usize,
202    
203    /// Number of known intents
204    pub intent_count: usize,
205    
206    /// Number of user feedback examples
207    pub feedback_examples: usize,
208    
209    /// Last update timestamp
210    pub last_updated: Option<DateTime<Utc>>,
211}
212
213/// Feedback for improving the classifier
214#[derive(Debug, Clone, Serialize, Deserialize)]
215pub struct IntentFeedback {
216    /// The original text that was classified
217    pub text: String,
218    
219    /// The intent that was predicted
220    pub predicted_intent: IntentId,
221    
222    /// The correct intent (according to user feedback)
223    pub actual_intent: IntentId,
224    
225    /// User satisfaction score (1.0 to 5.0)
226    pub satisfaction_score: f64,
227    
228    /// Additional notes from the user
229    pub notes: Option<String>,
230    
231    /// Timestamp of the feedback
232    pub timestamp: DateTime<Utc>,
233}
234
235/// Intent classification request
236#[derive(Debug, Clone, Serialize, Deserialize)]
237pub struct ClassificationRequest {
238    /// The text to classify
239    pub text: String,
240    
241    /// Optional context information
242    pub context: Option<HashMap<String, String>>,
243    
244    /// Whether to include alternative intents in the response
245    pub include_alternatives: bool,
246    
247    /// Whether to include reasoning in the response
248    pub include_reasoning: bool,
249}
250
251/// Intent classification response
252#[derive(Debug, Clone, Serialize, Deserialize)]
253pub struct ClassificationResponse {
254    /// The classification result
255    pub prediction: IntentPrediction,
256    
257    /// Processing time in milliseconds
258    pub processing_time_ms: f64,
259    
260    /// Request ID for tracking
261    pub request_id: Uuid,
262}
intent_classifier/types.rs

intent_classifier/
types.rs
