swarm_engine_core/learn/

trigger.rs

//! TrainTrigger - 学習開始条件の判定
//!
//! ## 概要
//!
//! 「いつ学習を開始するか」を判定する。
//!
//! - **CountTrigger**: N 件の Episode が蓄積されたら
//! - **TimeTrigger**: 前回学習から N 秒経過したら
//! - **QualityTrigger**: 成功率が閾値を下回ったら
//! - **OrTrigger / AndTrigger**: 複合条件
//!
//! ## 使用例
//!
//! ```ignore
//! use swarm_engine_core::learn::{TriggerBuilder, TriggerContext};
//!
//! // 100件 OR 1時間で発火
//! let trigger = TriggerBuilder::default_watch();
//!
//! let ctx = TriggerContext {
//!     store: &episode_store,
//!     last_train_at: Some(last_train_timestamp),
//!     last_train_count: 50,
//!     metrics: None,
//! };
//!
//! if trigger.should_train(&ctx)? {
//!     // 学習を開始
//! }
//! ```

use std::sync::Arc;
use std::time::Duration;

use super::store::{EpisodeStore, StoreError};
use crate::util::epoch_millis;

// ============================================================================
// TriggerContext - Trigger 判定に必要な情報
// ============================================================================

/// Trigger 判定のためのコンテキスト
///
/// ## 使い分け
///
/// - **LearnProcess（Episode ベース）**: `store` を指定、`event_count` は None
/// - **LearningSink（イベントベース）**: `store` は None、`event_count` を指定
pub struct TriggerContext<'a> {
    /// Episode ストア（件数確認用、オプション）
    pub store: Option<&'a dyn EpisodeStore>,

    /// 直接指定のイベント/Episode 件数（EpisodeStore がない場合に使用）
    pub event_count: Option<usize>,

    /// 最終学習時刻（Unix timestamp ms）
    pub last_train_at: Option<u64>,

    /// 前回学習時の Episode 件数
    pub last_train_count: usize,

    /// 現在の品質メトリクス（オプション）
    pub metrics: Option<&'a TriggerMetrics>,
}

impl<'a> TriggerContext<'a> {
    /// EpisodeStore ベースのコンテキストを作成
    pub fn with_store(store: &'a dyn EpisodeStore) -> Self {
        Self {
            store: Some(store),
            event_count: None,
            last_train_at: None,
            last_train_count: 0,
            metrics: None,
        }
    }

    /// イベントカウントベースのコンテキストを作成（EpisodeStore 不要）
    pub fn with_count(count: usize) -> Self {
        Self {
            store: None,
            event_count: Some(count),
            last_train_at: None,
            last_train_count: 0,
            metrics: None,
        }
    }

    /// 最終学習時刻を設定
    pub fn last_train_at(mut self, timestamp: u64) -> Self {
        self.last_train_at = Some(timestamp);
        self
    }

    /// 前回学習時の件数を設定
    pub fn last_train_count(mut self, count: usize) -> Self {
        self.last_train_count = count;
        self
    }

    /// メトリクスを設定
    pub fn metrics(mut self, metrics: &'a TriggerMetrics) -> Self {
        self.metrics = Some(metrics);
        self
    }

    /// 現在の件数を取得（event_count 優先、なければ store から取得）
    pub fn current_count(&self) -> Result<usize, TriggerError> {
        if let Some(count) = self.event_count {
            return Ok(count);
        }
        if let Some(store) = self.store {
            return Ok(store.count(None)?);
        }
        // どちらもない場合は 0 を返す（発火しない）
        Ok(0)
    }
}

/// 品質メトリクス
#[derive(Debug, Clone, Default)]
pub struct TriggerMetrics {
    /// 直近 N 件の成功率
    pub recent_success_rate: f64,
    /// 全体の成功率
    pub overall_success_rate: f64,
    /// 直近 N 件のサンプル数
    pub recent_sample_size: usize,
}

// ============================================================================
// TriggerError
// ============================================================================

/// Trigger 判定エラー
#[derive(Debug)]
pub enum TriggerError {
    /// Store エラー
    Store(StoreError),
    /// メトリクスが利用不可
    MetricsUnavailable(String),
}

impl std::fmt::Display for TriggerError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Store(e) => write!(f, "Store error: {}", e),
            Self::MetricsUnavailable(msg) => write!(f, "Metrics unavailable: {}", msg),
        }
    }
}

impl std::error::Error for TriggerError {}

impl From<StoreError> for TriggerError {
    fn from(e: StoreError) -> Self {
        Self::Store(e)
    }
}

// ============================================================================
// TrainTrigger Trait
// ============================================================================

/// 学習開始条件を判定する trait
pub trait TrainTrigger: Send + Sync {
    /// 学習を開始すべきか判定
    fn should_train(&self, context: &TriggerContext) -> Result<bool, TriggerError>;

    /// Trigger の名前（ログ用）
    fn name(&self) -> &str;

    /// 人間可読な説明
    fn describe(&self) -> String;
}

// ============================================================================
// CountTrigger - Episode 件数ベース
// ============================================================================

/// N 件の新規 Episode が蓄積されたら発火
pub struct CountTrigger {
    /// 発火閾値
    threshold: usize,
}

impl CountTrigger {
    pub fn new(threshold: usize) -> Self {
        Self { threshold }
    }
}

impl TrainTrigger for CountTrigger {
    fn should_train(&self, ctx: &TriggerContext) -> Result<bool, TriggerError> {
        let current_count = ctx.current_count()?;
        let new_episodes = current_count.saturating_sub(ctx.last_train_count);
        Ok(new_episodes >= self.threshold)
    }

    fn name(&self) -> &str {
        "count"
    }

    fn describe(&self) -> String {
        format!("Train when {} new episodes accumulated", self.threshold)
    }
}

// ============================================================================
// TimeTrigger - 時間ベース
// ============================================================================

/// 前回学習から N 秒経過したら発火
pub struct TimeTrigger {
    /// 発火間隔（秒）
    interval_secs: u64,
}

impl TimeTrigger {
    pub fn new(interval: Duration) -> Self {
        Self {
            interval_secs: interval.as_secs(),
        }
    }

    pub fn hours(hours: u64) -> Self {
        Self {
            interval_secs: hours * 3600,
        }
    }

    pub fn minutes(minutes: u64) -> Self {
        Self {
            interval_secs: minutes * 60,
        }
    }
}

impl TrainTrigger for TimeTrigger {
    fn should_train(&self, ctx: &TriggerContext) -> Result<bool, TriggerError> {
        let Some(last_train) = ctx.last_train_at else {
            // 一度も学習していない → Episode/イベントがあれば発火
            let count = ctx.current_count()?;
            return Ok(count > 0);
        };

        let now = epoch_millis();
        let elapsed_secs = (now.saturating_sub(last_train)) / 1000;
        Ok(elapsed_secs >= self.interval_secs)
    }

    fn name(&self) -> &str {
        "time"
    }

    fn describe(&self) -> String {
        if self.interval_secs >= 3600 {
            format!("Train every {} hours", self.interval_secs / 3600)
        } else if self.interval_secs >= 60 {
            format!("Train every {} minutes", self.interval_secs / 60)
        } else {
            format!("Train every {} seconds", self.interval_secs)
        }
    }
}

// ============================================================================
// QualityTrigger - 品質低下ベース
// ============================================================================

/// 成功率が閾値を下回ったら発火
pub struct QualityTrigger {
    /// 成功率の下限閾値
    threshold: f64,
    /// 最小サンプル数（これ以下なら判定しない）
    min_samples: usize,
}

impl QualityTrigger {
    pub fn new(threshold: f64) -> Self {
        Self {
            threshold,
            min_samples: 10,
        }
    }

    pub fn with_min_samples(mut self, min: usize) -> Self {
        self.min_samples = min;
        self
    }
}

impl TrainTrigger for QualityTrigger {
    fn should_train(&self, ctx: &TriggerContext) -> Result<bool, TriggerError> {
        let metrics = ctx.metrics.ok_or_else(|| {
            TriggerError::MetricsUnavailable("QualityTrigger requires metrics".into())
        })?;

        // サンプル数が不足していれば発火しない
        if metrics.recent_sample_size < self.min_samples {
            return Ok(false);
        }

        Ok(metrics.recent_success_rate < self.threshold)
    }

    fn name(&self) -> &str {
        "quality"
    }

    fn describe(&self) -> String {
        format!(
            "Train when success rate < {:.0}% (min {} samples)",
            self.threshold * 100.0,
            self.min_samples
        )
    }
}

// ============================================================================
// ManualTrigger - 常に false（CLI 用）
// ============================================================================

/// 常に false を返す（手動実行時は Trigger をバイパス）
pub struct ManualTrigger;

impl TrainTrigger for ManualTrigger {
    fn should_train(&self, _ctx: &TriggerContext) -> Result<bool, TriggerError> {
        Ok(false)
    }

    fn name(&self) -> &str {
        "manual"
    }

    fn describe(&self) -> String {
        "Manual trigger only".into()
    }
}

// ============================================================================
// NeverTrigger - テスト/無効化用
// ============================================================================

/// 常に false（自動学習無効化用）
pub struct NeverTrigger;

impl TrainTrigger for NeverTrigger {
    fn should_train(&self, _ctx: &TriggerContext) -> Result<bool, TriggerError> {
        Ok(false)
    }

    fn name(&self) -> &str {
        "never"
    }

    fn describe(&self) -> String {
        "Never triggers".into()
    }
}

// ============================================================================
// AlwaysTrigger - テスト用
// ============================================================================

/// 常に true（テスト用）
pub struct AlwaysTrigger;

impl TrainTrigger for AlwaysTrigger {
    fn should_train(&self, _ctx: &TriggerContext) -> Result<bool, TriggerError> {
        Ok(true)
    }

    fn name(&self) -> &str {
        "always"
    }

    fn describe(&self) -> String {
        "Always triggers".into()
    }
}

// ============================================================================
// OrTrigger - いずれかが true なら発火
// ============================================================================

/// いずれかの Trigger が true なら発火
pub struct OrTrigger {
    triggers: Vec<Arc<dyn TrainTrigger>>,
}

impl OrTrigger {
    pub fn new(triggers: Vec<Arc<dyn TrainTrigger>>) -> Self {
        Self { triggers }
    }
}

impl TrainTrigger for OrTrigger {
    fn should_train(&self, ctx: &TriggerContext) -> Result<bool, TriggerError> {
        for trigger in &self.triggers {
            if trigger.should_train(ctx)? {
                return Ok(true);
            }
        }
        Ok(false)
    }

    fn name(&self) -> &str {
        "or"
    }

    fn describe(&self) -> String {
        let names: Vec<_> = self.triggers.iter().map(|t| t.name()).collect();
        format!("OR({})", names.join(", "))
    }
}

// ============================================================================
// AndTrigger - 全てが true なら発火
// ============================================================================

/// 全ての Trigger が true なら発火
pub struct AndTrigger {
    triggers: Vec<Arc<dyn TrainTrigger>>,
}

impl AndTrigger {
    pub fn new(triggers: Vec<Arc<dyn TrainTrigger>>) -> Self {
        Self { triggers }
    }
}

impl TrainTrigger for AndTrigger {
    fn should_train(&self, ctx: &TriggerContext) -> Result<bool, TriggerError> {
        if self.triggers.is_empty() {
            return Ok(false);
        }
        for trigger in &self.triggers {
            if !trigger.should_train(ctx)? {
                return Ok(false);
            }
        }
        Ok(true)
    }

    fn name(&self) -> &str {
        "and"
    }

    fn describe(&self) -> String {
        let names: Vec<_> = self.triggers.iter().map(|t| t.name()).collect();
        format!("AND({})", names.join(", "))
    }
}

// ============================================================================
// TriggerBuilder - 便利なファクトリ
// ============================================================================

/// Trigger を構築するためのファクトリ
pub struct TriggerBuilder;

impl TriggerBuilder {
    /// N 件ごとに学習
    pub fn every_n_episodes(n: usize) -> Arc<dyn TrainTrigger> {
        Arc::new(CountTrigger::new(n))
    }

    /// N 時間ごとに学習
    pub fn every_hours(hours: u64) -> Arc<dyn TrainTrigger> {
        Arc::new(TimeTrigger::hours(hours))
    }

    /// N 分ごとに学習
    pub fn every_minutes(minutes: u64) -> Arc<dyn TrainTrigger> {
        Arc::new(TimeTrigger::minutes(minutes))
    }

    /// 成功率が閾値以下で学習
    pub fn on_quality_drop(threshold: f64) -> Arc<dyn TrainTrigger> {
        Arc::new(QualityTrigger::new(threshold))
    }

    /// 100件 OR 1時間（典型的な設定）
    pub fn default_watch() -> Arc<dyn TrainTrigger> {
        Arc::new(OrTrigger::new(vec![
            Self::every_n_episodes(100),
            Self::every_hours(1),
        ]))
    }

    /// 手動のみ
    pub fn manual() -> Arc<dyn TrainTrigger> {
        Arc::new(ManualTrigger)
    }

    /// 無効化
    pub fn never() -> Arc<dyn TrainTrigger> {
        Arc::new(NeverTrigger)
    }

    /// 常に実行
    pub fn always() -> Arc<dyn TrainTrigger> {
        Arc::new(AlwaysTrigger)
    }
}

// ============================================================================
// Tests
// ============================================================================

#[cfg(test)]
mod tests {
    use super::*;
    use crate::learn::store::{EpisodeDto, InMemoryEpisodeStore};
    use crate::learn::{EpisodeId, EpisodeMetadata, Outcome};

    fn create_test_store(count: usize) -> InMemoryEpisodeStore {
        let store = InMemoryEpisodeStore::new();
        for _ in 0..count {
            let dto = EpisodeDto {
                id: EpisodeId::new(),
                learn_model: "test".to_string(),
                outcome: Outcome::success(1.0),
                metadata: EpisodeMetadata::new(),
                record_ids: vec![],
            };
            store.append(&dto).unwrap();
        }
        store
    }

    fn create_context<'a>(
        store: &'a dyn EpisodeStore,
        last_train_at: Option<u64>,
        last_train_count: usize,
        metrics: Option<&'a TriggerMetrics>,
    ) -> TriggerContext<'a> {
        TriggerContext {
            store: Some(store),
            event_count: None,
            last_train_at,
            last_train_count,
            metrics,
        }
    }

    // ------------------------------------------------------------------------
    // CountTrigger Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_count_trigger_below_threshold() {
        let store = create_test_store(5);
        let trigger = CountTrigger::new(10);
        let ctx = create_context(&store, None, 0, None);

        assert!(!trigger.should_train(&ctx).unwrap());
    }

    #[test]
    fn test_count_trigger_at_threshold() {
        let store = create_test_store(10);
        let trigger = CountTrigger::new(10);
        let ctx = create_context(&store, None, 0, None);

        assert!(trigger.should_train(&ctx).unwrap());
    }

    #[test]
    fn test_count_trigger_with_previous_count() {
        let store = create_test_store(15);
        let trigger = CountTrigger::new(10);

        // 前回 10 件で学習済み → 新規 5 件 → 発火しない
        let ctx = create_context(&store, None, 10, None);
        assert!(!trigger.should_train(&ctx).unwrap());

        // 前回 5 件で学習済み → 新規 10 件 → 発火する
        let ctx = create_context(&store, None, 5, None);
        assert!(trigger.should_train(&ctx).unwrap());
    }

    // ------------------------------------------------------------------------
    // TimeTrigger Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_time_trigger_first_time_with_episodes() {
        let store = create_test_store(5);
        let trigger = TimeTrigger::hours(1);
        let ctx = create_context(&store, None, 0, None);

        // 初回で Episode あり → 発火
        assert!(trigger.should_train(&ctx).unwrap());
    }

    #[test]
    fn test_time_trigger_first_time_no_episodes() {
        let store = create_test_store(0);
        let trigger = TimeTrigger::hours(1);
        let ctx = create_context(&store, None, 0, None);

        // 初回で Episode なし → 発火しない
        assert!(!trigger.should_train(&ctx).unwrap());
    }

    #[test]
    fn test_time_trigger_not_elapsed() {
        let store = create_test_store(5);
        let trigger = TimeTrigger::hours(1);
        let now = epoch_millis();
        let ctx = create_context(&store, Some(now - 1000), 0, None); // 1秒前

        assert!(!trigger.should_train(&ctx).unwrap());
    }

    #[test]
    fn test_time_trigger_elapsed() {
        let store = create_test_store(5);
        let trigger = TimeTrigger::hours(1);
        let now = epoch_millis();
        let ctx = create_context(&store, Some(now - 3601 * 1000), 0, None); // 1時間1秒前

        assert!(trigger.should_train(&ctx).unwrap());
    }

    // ------------------------------------------------------------------------
    // QualityTrigger Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_quality_trigger_no_metrics() {
        let store = create_test_store(5);
        let trigger = QualityTrigger::new(0.5);
        let ctx = create_context(&store, None, 0, None);

        assert!(trigger.should_train(&ctx).is_err());
    }

    #[test]
    fn test_quality_trigger_insufficient_samples() {
        let store = create_test_store(5);
        let trigger = QualityTrigger::new(0.5).with_min_samples(10);
        let metrics = TriggerMetrics {
            recent_success_rate: 0.3, // 閾値以下
            overall_success_rate: 0.5,
            recent_sample_size: 5, // サンプル不足
        };
        let ctx = create_context(&store, None, 0, Some(&metrics));

        assert!(!trigger.should_train(&ctx).unwrap());
    }

    #[test]
    fn test_quality_trigger_above_threshold() {
        let store = create_test_store(5);
        let trigger = QualityTrigger::new(0.5);
        let metrics = TriggerMetrics {
            recent_success_rate: 0.7,
            overall_success_rate: 0.7,
            recent_sample_size: 20,
        };
        let ctx = create_context(&store, None, 0, Some(&metrics));

        assert!(!trigger.should_train(&ctx).unwrap());
    }

    #[test]
    fn test_quality_trigger_below_threshold() {
        let store = create_test_store(5);
        let trigger = QualityTrigger::new(0.5);
        let metrics = TriggerMetrics {
            recent_success_rate: 0.3,
            overall_success_rate: 0.5,
            recent_sample_size: 20,
        };
        let ctx = create_context(&store, None, 0, Some(&metrics));

        assert!(trigger.should_train(&ctx).unwrap());
    }

    // ------------------------------------------------------------------------
    // OrTrigger Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_or_trigger_all_false() {
        let store = create_test_store(5);
        let trigger = OrTrigger::new(vec![
            Arc::new(CountTrigger::new(100)),
            Arc::new(NeverTrigger),
        ]);
        let ctx = create_context(&store, None, 0, None);

        assert!(!trigger.should_train(&ctx).unwrap());
    }

    #[test]
    fn test_or_trigger_one_true() {
        let store = create_test_store(5);
        let trigger = OrTrigger::new(vec![Arc::new(AlwaysTrigger), Arc::new(NeverTrigger)]);
        let ctx = create_context(&store, None, 0, None);

        assert!(trigger.should_train(&ctx).unwrap());
    }

    // ------------------------------------------------------------------------
    // AndTrigger Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_and_trigger_empty() {
        let store = create_test_store(5);
        let trigger = AndTrigger::new(vec![]);
        let ctx = create_context(&store, None, 0, None);

        assert!(!trigger.should_train(&ctx).unwrap());
    }

    #[test]
    fn test_and_trigger_all_true() {
        let store = create_test_store(5);
        let trigger = AndTrigger::new(vec![Arc::new(AlwaysTrigger), Arc::new(AlwaysTrigger)]);
        let ctx = create_context(&store, None, 0, None);

        assert!(trigger.should_train(&ctx).unwrap());
    }

    #[test]
    fn test_and_trigger_one_false() {
        let store = create_test_store(5);
        let trigger = AndTrigger::new(vec![Arc::new(AlwaysTrigger), Arc::new(NeverTrigger)]);
        let ctx = create_context(&store, None, 0, None);

        assert!(!trigger.should_train(&ctx).unwrap());
    }

    // ------------------------------------------------------------------------
    // TriggerBuilder Tests
    // ------------------------------------------------------------------------

    #[test]
    fn test_trigger_builder_default_watch() {
        let trigger = TriggerBuilder::default_watch();
        assert_eq!(trigger.name(), "or");
        assert!(trigger.describe().contains("OR"));
    }

    #[test]
    fn test_trigger_describe() {
        assert_eq!(
            CountTrigger::new(50).describe(),
            "Train when 50 new episodes accumulated"
        );
        assert_eq!(TimeTrigger::hours(2).describe(), "Train every 2 hours");
        assert_eq!(
            TimeTrigger::minutes(30).describe(),
            "Train every 30 minutes"
        );
        assert!(QualityTrigger::new(0.5).describe().contains("50%"));
    }

    // ------------------------------------------------------------------------
    // TriggerContext Builder Tests (for LearningSink integration)
    // ------------------------------------------------------------------------

    #[test]
    fn test_context_with_count_no_store() {
        // EpisodeStore なしで event_count のみ指定
        let ctx = TriggerContext::with_count(15);
        let trigger = CountTrigger::new(10);

        // 15 件（新規 15）>= 10 → 発火
        assert!(trigger.should_train(&ctx).unwrap());
    }

    #[test]
    fn test_context_with_count_below_threshold() {
        let ctx = TriggerContext::with_count(5);
        let trigger = CountTrigger::new(10);

        // 5 件 < 10 → 発火しない
        assert!(!trigger.should_train(&ctx).unwrap());
    }

    #[test]
    fn test_context_with_count_and_last_train_count() {
        let ctx = TriggerContext::with_count(20).last_train_count(15);
        let trigger = CountTrigger::new(10);

        // 20 - 15 = 5 件（新規）< 10 → 発火しない
        assert!(!trigger.should_train(&ctx).unwrap());
    }

    #[test]
    fn test_context_builder_fluent() {
        let metrics = TriggerMetrics {
            recent_success_rate: 0.3,
            overall_success_rate: 0.5,
            recent_sample_size: 20,
        };

        let now = epoch_millis();
        let ctx = TriggerContext::with_count(100)
            .last_train_at(now - 3600 * 1000) // 1時間前
            .last_train_count(50)
            .metrics(&metrics);

        // CountTrigger: 100 - 50 = 50 >= 10 → 発火
        let count_trigger = CountTrigger::new(10);
        assert!(count_trigger.should_train(&ctx).unwrap());

        // TimeTrigger: 1時間経過 >= 30分 → 発火
        let time_trigger = TimeTrigger::minutes(30);
        assert!(time_trigger.should_train(&ctx).unwrap());

        // QualityTrigger: 0.3 < 0.5 → 発火
        let quality_trigger = QualityTrigger::new(0.5);
        assert!(quality_trigger.should_train(&ctx).unwrap());
    }

    #[test]
    fn test_time_trigger_with_count_first_time() {
        // EpisodeStore なし、初回（last_train_at なし）、イベントあり → 発火
        let ctx = TriggerContext::with_count(5);
        let trigger = TimeTrigger::hours(1);

        assert!(trigger.should_train(&ctx).unwrap());
    }

    #[test]
    fn test_time_trigger_with_count_first_time_no_events() {
        // EpisodeStore なし、初回、イベントなし → 発火しない
        let ctx = TriggerContext::with_count(0);
        let trigger = TimeTrigger::hours(1);

        assert!(!trigger.should_train(&ctx).unwrap());
    }
}