use std::collections::HashMap;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::Arc;
use std::time::{Duration, Instant};
use parking_lot::RwLock;
use serde::{Deserialize, Serialize};
use crate::error::Result;
use crate::index::{HnswConfig, HnswIndex, SearchResult};
use crate::types::{ChunkId, TenantId};
use super::access_tracker::AccessTracker;
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HotTierConfig {
pub capacity_percentage: f32,
pub max_chunks: usize,
pub min_promotion_score: f32,
pub eviction_check_interval: Duration,
pub hnsw_config: HnswConfig,
}
impl Default for HotTierConfig {
fn default() -> Self {
Self {
capacity_percentage: 0.10,
max_chunks: 50_000,
min_promotion_score: 0.3,
eviction_check_interval: Duration::from_secs(60),
hnsw_config: HnswConfig {
max_connections: 16,
ef_construction: 200,
ef_search: 30, max_elements: 50_000,
dimension: 384,
persist_graph_dump: true,
search_lock_budget_ms: None,
backfill_hnsw_on_startup: false,
},
}
}
}
#[derive(Debug, Clone)]
pub struct HotChunkEntry {
pub chunk_id: ChunkId,
pub embedding: Vec<f32>,
pub promoted_at: i64,
pub promotion_score: f32,
pub tenant_id: TenantId,
}
#[derive(Debug, Clone)]
pub struct HotTierStats {
pub chunk_count: usize,
pub capacity_used: f32,
pub version: u64,
pub avg_promotion_score: f32,
}
pub struct HotTier {
index: HnswIndex,
chunks: RwLock<HashMap<ChunkId, HotChunkEntry>>,
config: HotTierConfig,
version: AtomicU64,
access_tracker: Option<Arc<RwLock<AccessTracker>>>,
}
impl HotTier {
pub fn new(config: HotTierConfig) -> Self {
let index = HnswIndex::new(config.hnsw_config.clone());
Self {
index,
chunks: RwLock::new(HashMap::new()),
config,
version: AtomicU64::new(0),
access_tracker: None,
}
}
pub fn with_access_tracker(config: HotTierConfig, tracker: Arc<RwLock<AccessTracker>>) -> Self {
let mut tier = Self::new(config);
tier.access_tracker = Some(tracker);
tier
}
pub fn promote(
&self,
chunk_id: ChunkId,
embedding: Vec<f32>,
tenant_id: TenantId,
promotion_score: f32,
) -> Result<bool> {
let mut chunks = self.chunks.write();
if chunks.contains_key(&chunk_id) {
return Ok(false);
}
let current_len = chunks.len();
if current_len >= self.config.max_chunks {
return Ok(false);
}
self.index.insert(&chunk_id, &embedding)?;
let entry = HotChunkEntry {
chunk_id: chunk_id.clone(),
embedding,
promoted_at: current_time_ms(),
promotion_score,
tenant_id,
};
chunks.insert(chunk_id, entry);
self.version.fetch_add(1, Ordering::SeqCst);
Ok(true)
}
pub fn demote(&self, chunk_id: &ChunkId) -> bool {
let mut chunks = self.chunks.write();
if chunks.remove(chunk_id).is_some() {
self.version.fetch_add(1, Ordering::SeqCst);
true
} else {
false
}
}
pub fn contains(&self, chunk_id: &ChunkId) -> bool {
self.chunks.read().contains_key(chunk_id)
}
pub fn search(&self, query_embedding: &[f32], k: usize) -> Result<Vec<SearchResult>> {
let results = self.index.search(query_embedding, k)?;
let chunks = self.chunks.read();
let filtered: Vec<SearchResult> = results
.into_iter()
.filter(|r| chunks.contains_key(&r.chunk_id))
.collect();
if let Some(ref tracker) = self.access_tracker {
use super::access_tracker::AccessEvent;
let tracker = tracker.write();
for result in &filtered {
tracker.record_access(AccessEvent::new(result.chunk_id.clone()));
}
}
Ok(filtered)
}
pub fn search_with_timing(
&self,
query_embedding: &[f32],
k: usize,
) -> Result<(Vec<SearchResult>, Duration)> {
let start = Instant::now();
let results = self.search(query_embedding, k)?;
let elapsed = start.elapsed();
Ok((results, elapsed))
}
pub fn len(&self) -> usize {
self.chunks.read().len()
}
pub fn is_empty(&self) -> bool {
self.len() == 0
}
pub fn version(&self) -> u64 {
self.version.load(Ordering::SeqCst)
}
pub fn evict_if_needed(&self, total_indexed: usize) -> usize {
let capacity = self.calculate_capacity(total_indexed);
let current = self.len();
if current <= capacity {
return 0;
}
let to_evict = current - capacity;
self.evict_lowest_score(to_evict)
}
fn evict_lowest_score(&self, n: usize) -> usize {
if n == 0 {
return 0;
}
let mut chunks = self.chunks.write();
let mut entries: Vec<_> = chunks
.iter()
.map(|(id, entry)| (id.clone(), entry.promotion_score))
.collect();
entries.sort_by(|a, b| a.1.partial_cmp(&b.1).unwrap_or(std::cmp::Ordering::Equal));
let mut evicted = 0;
for (chunk_id, _) in entries.into_iter().take(n) {
if chunks.remove(&chunk_id).is_some() {
evicted += 1;
}
}
if evicted > 0 {
self.version.fetch_add(1, Ordering::SeqCst);
}
evicted
}
fn calculate_capacity(&self, total_indexed: usize) -> usize {
let percentage_capacity = (total_indexed as f32 * self.config.capacity_percentage) as usize;
percentage_capacity.min(self.config.max_chunks)
}
pub fn get_stats(&self) -> HotTierStats {
let chunks = self.chunks.read();
let count = chunks.len();
let avg_score = if count > 0 {
chunks.values().map(|e| e.promotion_score).sum::<f32>() / count as f32
} else {
0.0
};
let capacity_used = if self.config.max_chunks > 0 {
count as f32 / self.config.max_chunks as f32
} else {
0.0
};
HotTierStats {
chunk_count: count,
capacity_used,
version: self.version(),
avg_promotion_score: avg_score,
}
}
pub fn min_promotion_score(&self) -> f32 {
self.config.min_promotion_score
}
pub fn config(&self) -> &HotTierConfig {
&self.config
}
}
fn current_time_ms() -> i64 {
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_millis() as i64)
.unwrap_or(0)
}
#[cfg(test)]
mod tests {
use super::*;
fn normalize(v: &mut [f32]) {
let norm: f32 = v.iter().map(|x| x * x).sum::<f32>().sqrt();
if norm > 0.0 {
for x in v.iter_mut() {
*x /= norm;
}
}
}
fn make_config() -> HotTierConfig {
HotTierConfig {
capacity_percentage: 0.5,
max_chunks: 100,
min_promotion_score: 0.3,
eviction_check_interval: Duration::from_secs(60),
hnsw_config: HnswConfig {
max_connections: 16,
ef_construction: 200,
ef_search: 30,
max_elements: 100,
dimension: 4,
persist_graph_dump: true,
search_lock_budget_ms: None,
backfill_hnsw_on_startup: false,
},
}
}
#[test]
fn test_promote_and_search() {
let config = make_config();
let tier = HotTier::new(config);
let chunk_id = ChunkId::new();
let tenant_id = TenantId::new("test").unwrap();
let mut embedding = vec![1.0, 0.0, 0.0, 0.0];
normalize(&mut embedding);
let added = tier
.promote(chunk_id.clone(), embedding.clone(), tenant_id, 0.5)
.unwrap();
assert!(added);
assert_eq!(tier.len(), 1);
assert!(tier.contains(&chunk_id));
let results = tier.search(&embedding, 1).unwrap();
assert_eq!(results.len(), 1);
assert_eq!(results[0].chunk_id, chunk_id);
assert!(results[0].score > 0.99); }
#[test]
fn test_promote_duplicate() {
let config = make_config();
let tier = HotTier::new(config);
let chunk_id = ChunkId::new();
let tenant_id = TenantId::new("test").unwrap();
let mut embedding = vec![1.0, 0.0, 0.0, 0.0];
normalize(&mut embedding);
let added1 = tier
.promote(chunk_id.clone(), embedding.clone(), tenant_id.clone(), 0.5)
.unwrap();
assert!(added1);
let added2 = tier
.promote(chunk_id.clone(), embedding.clone(), tenant_id, 0.5)
.unwrap();
assert!(!added2);
assert_eq!(tier.len(), 1);
}
#[test]
fn test_demote() {
let config = make_config();
let tier = HotTier::new(config);
let chunk_id = ChunkId::new();
let tenant_id = TenantId::new("test").unwrap();
let mut embedding = vec![1.0, 0.0, 0.0, 0.0];
normalize(&mut embedding);
tier.promote(chunk_id.clone(), embedding.clone(), tenant_id, 0.5)
.unwrap();
assert_eq!(tier.len(), 1);
let removed = tier.demote(&chunk_id);
assert!(removed);
assert_eq!(tier.len(), 0);
assert!(!tier.contains(&chunk_id));
let results = tier.search(&embedding, 1).unwrap();
assert!(results.is_empty());
}
#[test]
fn test_version_tracking() {
let config = make_config();
let tier = HotTier::new(config);
let chunk_id = ChunkId::new();
let tenant_id = TenantId::new("test").unwrap();
let mut embedding = vec![1.0, 0.0, 0.0, 0.0];
normalize(&mut embedding);
let v0 = tier.version();
tier.promote(chunk_id.clone(), embedding, tenant_id, 0.5)
.unwrap();
let v1 = tier.version();
assert!(v1 > v0, "Version should increment on promote");
tier.demote(&chunk_id);
let v2 = tier.version();
assert!(v2 > v1, "Version should increment on demote");
}
#[test]
fn test_eviction() {
let mut config = make_config();
config.max_chunks = 5;
let tier = HotTier::new(config);
let tenant_id = TenantId::new("test").unwrap();
for i in 0..5 {
let chunk_id = ChunkId::new();
let mut embedding = vec![i as f32, (i + 1) as f32, (i + 2) as f32, (i + 3) as f32];
normalize(&mut embedding);
tier.promote(chunk_id, embedding, tenant_id.clone(), i as f32 * 0.1)
.unwrap();
}
assert_eq!(tier.len(), 5);
let evicted = tier.evict_lowest_score(2);
assert_eq!(evicted, 2);
assert_eq!(tier.len(), 3);
}
#[test]
fn test_stats() {
let config = make_config();
let tier = HotTier::new(config);
let tenant_id = TenantId::new("test").unwrap();
for i in 0..3 {
let chunk_id = ChunkId::new();
let mut embedding = vec![i as f32, (i + 1) as f32, (i + 2) as f32, (i + 3) as f32];
normalize(&mut embedding);
let score = (i + 1) as f32 * 0.2; tier.promote(chunk_id, embedding, tenant_id.clone(), score)
.unwrap();
}
let stats = tier.get_stats();
assert_eq!(stats.chunk_count, 3);
assert!(stats.version > 0);
assert!((stats.avg_promotion_score - 0.4).abs() < 0.01); assert!(stats.capacity_used > 0.0);
}
#[test]
fn test_search_with_timing() {
let config = make_config();
let tier = HotTier::new(config);
let chunk_id = ChunkId::new();
let tenant_id = TenantId::new("test").unwrap();
let mut embedding = vec![1.0, 0.0, 0.0, 0.0];
normalize(&mut embedding);
tier.promote(chunk_id.clone(), embedding.clone(), tenant_id, 0.5)
.unwrap();
let (results, duration) = tier.search_with_timing(&embedding, 1).unwrap();
assert_eq!(results.len(), 1);
assert!(duration.as_nanos() > 0); }
#[test]
fn test_capacity_calculation() {
let mut config = make_config();
config.capacity_percentage = 0.10;
config.max_chunks = 1000;
let tier = HotTier::new(config);
assert_eq!(tier.calculate_capacity(500), 50);
assert_eq!(tier.calculate_capacity(20000), 1000);
}
#[test]
fn test_config_defaults() {
let config = HotTierConfig::default();
assert_eq!(config.capacity_percentage, 0.10);
assert_eq!(config.max_chunks, 50_000);
assert_eq!(config.min_promotion_score, 0.3);
assert_eq!(config.hnsw_config.ef_search, 30); }
}