swarm-engine-core 0.1.6

//! Selection - ノード選択アルゴリズム
//!
//! # 設計思想: TypeAliasPolicyPattern
//!
//! 各 Selection アルゴリズムは独立した struct として実装され、
//! `SelectionLogic` trait を実装する。
//!
//! - **ロジックの分離**: 各アルゴリズムの実装が独立
//! - **型による制約**: Operator の型パラメータで組み合わせを制約可能
//! - **Config 連携**: `SelectionKind` enum で Config/serde 対応
//! - **動的切り替え**: `AnySelection` で enum dispatch による動的ディスパッチ
//!
//! # 統計情報
//!
//! Selection アルゴリズムは `SwarmStats`（collector/stats.rs）を Single Source of Truth
//! として使用する。各メソッドは `&SwarmStats` を引数に取り、アクション統計を参照する。
//!
//! # モジュール構成
//!
//! | モジュール | 内容 |
//! |-----------|------|
//! | `stats` | `NodeStats`（後方互換） |
//! | `kind` | Selection の種類（`SelectionKind` enum） |
//! | `fifo` | FIFO 選択 |
//! | `ucb1` | UCB1 選択 |
//! | `greedy` | Greedy 選択 |
//! | `thompson` | Thompson Sampling 選択 |
//! | `any` | 動的選択ラッパー（`AnySelection`） |
//!
//! # 使用例
//!
//! ```ignore
//! use swarm_engine_core::exploration::selection::{Fifo, Ucb1, SelectionLogic};
//!
//! // 静的型付け（コンパイル時に Selection が決定）
//! let fifo = Fifo::new();
//! let ucb1 = Ucb1::new(1.41);
//!
//! // 動的切り替え（実行時に Selection を変更可能）
//! let any = AnySelection::from_kind(SelectionKind::Ucb1, 1.41);
//! ```

mod any;
mod fifo;
mod greedy;
mod kind;
mod stats;
mod thompson;
mod ucb1;

use std::fmt::Debug;

use crate::exploration::map::{GraphMap, MapNodeId, MapState};
use crate::learn::LearnedProvider;
use crate::online_stats::SwarmStats;

// ============================================================================
// Re-exports
// ============================================================================

// Stats (SwarmStats を使用、NodeStats は後方互換のため残す)
pub use stats::NodeStats;

// Kind
pub use kind::SelectionKind;

// Selection implementations
pub use fifo::Fifo;
pub use greedy::Greedy;
pub use thompson::Thompson;
pub use ucb1::Ucb1;

// Dynamic wrapper
pub use any::AnySelection;

// ============================================================================
// SelectionLogic trait
// ============================================================================

/// ノード選択ロジック
///
/// 次に探索するノードを選択する責務を持つ。
/// SwarmStats を参照してスコアベースの選択が可能。
///
/// # 実装者向け
///
/// - `next()`: 1ノード選択（デフォルト実装あり）
/// - `select()`: 複数ノード選択（必須）
/// - `score()`: スコア計算（デバッグ/可視化用）
/// - `name()`: アルゴリズム名
pub trait SelectionLogic<N, E, S>: Send + Sync
where
    N: Debug + Clone,
    E: Debug + Clone,
    S: MapState,
{
    /// 次のノードを1つ選択
    fn next(
        &self,
        map: &GraphMap<N, E, S>,
        stats: &SwarmStats,
        provider: &dyn LearnedProvider,
    ) -> Option<MapNodeId>;

    /// 次のノードを複数選択
    fn select(
        &self,
        map: &GraphMap<N, E, S>,
        count: usize,
        stats: &SwarmStats,
        provider: &dyn LearnedProvider,
    ) -> Vec<MapNodeId>;

    /// ノードのスコアを計算
    fn score(
        &self,
        action: &str,
        target: Option<&str>,
        stats: &SwarmStats,
        provider: &dyn LearnedProvider,
    ) -> f64;

    /// 名前
    fn name(&self) -> &str;
}

// ============================================================================
// Legacy Aliases (後方互換性)
// ============================================================================

/// FifoSelection の別名（後方互換）
pub type FifoSelection = Fifo;

/// Ucb1Selection の別名（後方互換）
pub type Ucb1Selection = Ucb1;

/// GreedySelection の別名（後方互換）
pub type GreedySelection = Greedy;

/// ThompsonSelection の別名（後方互換）
pub type ThompsonSelection = Thompson;