ferrum-engine 0.8.2

//! # Ferrum Engine
//!
//! LLM inference engine orchestration layer with strong streaming support.
//!
//! ## Overview
//!
//! This crate provides the main inference engine implementation that orchestrates
//! all the components from other ferrum crates:
//!
//! - Request admission and scheduling (ferrum-scheduler)
//! - KV-cache allocation and management (ferrum-kv)
//! - Tokenization and incremental decoding (ferrum-tokenizer)
//! - Logits processing and sampling (ferrum-sampler)
//! - Model execution and weight loading (ferrum-models)
//! - Runtime and compute backends (ferrum-runtime)
//!
//! ## Design Principles
//!
//! - **Strong Streaming**: TTFT optimization and consistent inter-token latency
//! - **Orchestration Layer**: Compose components rather than implement functionality
//! - **Batch Processing**: Dynamic continuous batching for throughput
//! - **Pipeline Optimization**: Prefill→decode loops with minimal overhead
//! - **Registry Pattern**: Dynamic component registration and lookup
//!
//! ## Usage
//!
//! ### Using the Engine Builder (Recommended)
//!
//! ```rust,ignore
//! use ferrum_engine::{EngineBuilder, EngineConfig};
//!
//! let config = EngineConfig::default();
//! let engine = EngineBuilder::new(config)
//!     .with_scheduler("fifo")
//!     .with_sampler("greedy")
//!     .build()
//!     .await?;
//! ```
//!
//! ### Registering Custom Components
//!
//! ```rust,ignore
//! use ferrum_engine::{ComponentRegistry, global_registry};
//!
//! let registry = global_registry();
//! registry.register_backend_factory("my_backend", Arc::new(MyBackendFactory));
//! ```

pub mod builder;
pub mod continuous_engine;
pub mod embedding_engine;
pub(crate) mod layer_split;
pub mod modality_stubs;
pub mod parallel;
pub mod pipeline;
mod product_composition;
pub mod recurrent_state;
pub mod registry;
pub(crate) mod resource_lifecycle;
pub mod speculative;
pub mod tensor_factory;
pub mod transcription_engine;
pub mod tts_engine;
#[cfg(feature = "cuda")]
pub mod vnext_determinism;

// Re-exports of interfaces
pub use ferrum_interfaces::engine::{EmbedEngine, LlmInferenceEngine, TranscribeEngine, TtsEngine};
pub use ferrum_interfaces::{
    IncrementalTokenizer, InferenceEngine as InferenceEngineInterface, KvCacheManager,
    ModelExecutor, Sampler, SchedulerInterface as Scheduler, Tokenizer,
};

pub use ferrum_types::{
    BatchId, EngineConfig, EngineStatus, FerrumError, InferenceRequest, InferenceResponse,
    RequestId, Result, StreamChunk,
};

// Re-exports from implementation crates
pub use ferrum_scheduler::BatchPlan;

// Re-exports of engine implementation
pub use continuous_engine::{ContinuousBatchEngine, SequenceState};

// Re-exports of pipeline
pub use pipeline::{
    ChunkedPrefillConfig, ChunkedPrefillExecutor, ExecutionPhase, PipelineConfig, PipelineExecutor,
};

pub use recurrent_state::{
    InMemoryRecurrentStateConfig, InMemoryRecurrentStateHandle, InMemoryRecurrentStateManager,
};

// Re-exports of builder
pub use builder::{
    create_engine, create_prepared_product_engine, create_product_engine, EngineBuilder,
};

// Re-exports of registry
pub use registry::{
    global_registry, set_global_registry, ComponentConfig, ComponentFactory, ComponentMetadata,
    ComponentRegistry, ContinuousBatchSchedulerFactory, DefaultKvCacheFactory,
    FifoSchedulerFactory, GreedySampler, GreedySamplerFactory, HuggingFaceTokenizerFactory,
    LlmExecutorFactory, MultinomialSamplerFactory, PagedKvCacheFactory, PrioritySchedulerFactory,
    StubExecutorFactory, StubTokenizer, StubTokenizerFactory,
};

// Back-compat alias for the renamed factory (PR A).
#[allow(deprecated)]
pub use registry::CandleExecutorFactory;

// Re-exports of parallel module
pub use parallel::{
    global_device_manager, DeviceCapability, DeviceInfo, DeviceManager, LayerDistribution,
    ParallelConfig, ParallelExecutor, ParallelExecutorFactory, ParallelismType,
    TensorParallelConfig, TensorParallelGroup,
};

/// Create default inference engine with MVP configuration
///
/// This is a convenience function that uses the default registry.
pub async fn create_default_engine(
    config: EngineConfig,
) -> Result<Box<dyn LlmInferenceEngine + Send + Sync>> {
    create_engine(config).await
}

// ============================================================================
// Integration Tests
// ============================================================================

#[cfg(test)]
mod integration_tests {
    use super::*;

    fn test_config() -> EngineConfig {
        let mut config = EngineConfig::default();
        config.model.model_id = ferrum_types::ModelId::new("test-model");
        config.backend.device = ferrum_types::Device::CPU;
        config
    }

    #[tokio::test]
    async fn test_create_engine_via_builder() {
        let engine = EngineBuilder::new(test_config())
            .with_tokenizer("stub")
            .with_executor("stub")
            .build()
            .await;

        assert!(engine.is_ok());
    }

    #[tokio::test]
    async fn test_create_engine_convenience() {
        let engine = create_default_engine(test_config()).await;

        assert!(engine.is_ok());
    }

    #[test]
    fn test_global_registry() {
        let registry = global_registry();

        // Should have default factories
        assert!(registry.list_tokenizers().contains(&"stub".to_string()));
        assert!(registry
            .list_samplers()
            .contains(&"multinomial".to_string()));
    }

    #[test]
    fn test_custom_registry() {
        let registry = ComponentRegistry::new();
        assert!(registry.list_tokenizers().is_empty());

        registry.register_defaults();
        assert!(!registry.list_tokenizers().is_empty());
    }
}