use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use crate::error::MemoryError;
use crate::id::{AgentId, MemoryId, SessionId, Tag};
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum EpisodeKind {
Observation,
Action,
Inference,
Interaction,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Episode {
pub id: MemoryId,
pub agent_id: AgentId,
pub session_id: SessionId,
pub kind: EpisodeKind,
pub content: String,
pub timestamp: DateTime<Utc>,
pub strength: f32,
pub tags: Vec<Tag>,
}
impl Episode {
pub fn new(
agent_id: AgentId,
session_id: SessionId,
kind: EpisodeKind,
content: impl Into<String>,
strength: f32,
tags: Vec<Tag>,
) -> Result<Self, MemoryError> {
if !(0.0..=1.0).contains(&strength) {
return Err(MemoryError::InvalidConfidence { value: strength });
}
Ok(Self {
id: MemoryId::new(),
agent_id,
session_id,
kind,
content: content.into(),
timestamp: Utc::now(),
strength,
tags,
})
}
pub fn with_timestamp(
agent_id: AgentId,
session_id: SessionId,
kind: EpisodeKind,
content: impl Into<String>,
strength: f32,
tags: Vec<Tag>,
timestamp: DateTime<Utc>,
) -> Result<Self, MemoryError> {
if !(0.0..=1.0).contains(&strength) {
return Err(MemoryError::InvalidConfidence { value: strength });
}
Ok(Self {
id: MemoryId::new(),
agent_id,
session_id,
kind,
content: content.into(),
timestamp,
strength,
tags,
})
}
}
#[cfg(test)]
mod tests {
use super::*;
fn make_ids() -> (AgentId, SessionId) {
(AgentId::new(), SessionId::new())
}
#[test]
fn test_episode_new_valid_strength_returns_ok() {
let (a, s) = make_ids();
let ep = Episode::new(a, s, EpisodeKind::Observation, "saw something", 0.8, vec![]);
assert!(ep.is_ok());
}
#[test]
fn test_episode_new_strength_zero_is_valid() {
let (a, s) = make_ids();
let ep = Episode::new(a, s, EpisodeKind::Action, "did nothing", 0.0, vec![]);
assert!(ep.is_ok());
}
#[test]
fn test_episode_new_strength_one_is_valid() {
let (a, s) = make_ids();
let ep = Episode::new(a, s, EpisodeKind::Inference, "deduced", 1.0, vec![]);
assert!(ep.is_ok());
}
#[test]
fn test_confidence_invalid_range_returns_error_above_one() {
let (a, s) = make_ids();
let err = Episode::new(a, s, EpisodeKind::Observation, "x", 1.1, vec![]).unwrap_err();
assert!(matches!(err, MemoryError::InvalidConfidence { value } if (value - 1.1).abs() < 1e-5));
}
#[test]
fn test_confidence_invalid_range_returns_error_negative() {
let (a, s) = make_ids();
let err = Episode::new(a, s, EpisodeKind::Observation, "x", -0.1, vec![]).unwrap_err();
assert!(matches!(err, MemoryError::InvalidConfidence { .. }));
}
#[test]
fn test_episode_content_stored_correctly() {
let (a, s) = make_ids();
let ep = Episode::new(a, s, EpisodeKind::Interaction, "hello world", 0.5, vec![])
.unwrap();
assert_eq!(ep.content, "hello world");
}
#[test]
fn test_episode_tags_stored_correctly() {
let (a, s) = make_ids();
let tags = vec![Tag::new("important"), Tag::new("urgent")];
let ep = Episode::new(a, s, EpisodeKind::Observation, "x", 0.5, tags.clone()).unwrap();
assert_eq!(ep.tags, tags);
}
#[test]
fn test_episode_kind_variants_are_distinct() {
assert_ne!(EpisodeKind::Observation, EpisodeKind::Action);
assert_ne!(EpisodeKind::Inference, EpisodeKind::Interaction);
}
#[test]
fn test_episode_with_timestamp_stores_timestamp() {
let (a, s) = make_ids();
let ts = DateTime::parse_from_rfc3339("2025-01-01T00:00:00Z")
.unwrap()
.with_timezone(&Utc);
let ep =
Episode::with_timestamp(a, s, EpisodeKind::Observation, "x", 0.5, vec![], ts).unwrap();
assert_eq!(ep.timestamp, ts);
}
}