mullama 0.3.0

Comprehensive Rust bindings for llama.cpp with memory-safe API and advanced features
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

//! Builder patterns for complex configurations
//!
//! This module provides fluent, ergonomic builder patterns for configuring
//! Mullama components. Builders enforce correct construction order and
//! provide sensible defaults while allowing fine-grained control.
//!
//! ## Features
//!
//! - **Fluent API**: Chainable method calls for readable configuration
//! - **Type safety**: Compile-time guarantees about required parameters
//! - **Validation**: Built-in validation with helpful error messages
//! - **Defaults**: Sensible defaults for all optional parameters
//! - **Presets**: Quick configuration for common use cases
//! - **Progressive disclosure**: Start simple, add complexity as needed
//!
//! ## Example
//!
//! ```rust,ignore
//! use mullama::builder::{ModelBuilder, ContextBuilder, SamplerBuilder};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), mullama::MullamaError> {
//!     // Build a complete model with fluent API
//!     let model = ModelBuilder::new()
//!         .path("path/to/model.gguf")
//!         .gpu_layers(32)
//!         .context_size(4096)
//!         .memory_mapping(true)
//!         .build()
//!         .await?;
//!
//!     // Build context with advanced configuration
//!     let context = ContextBuilder::new(model.clone())
//!         .context_size(4096)
//!         .batch_size(512)
//!         .threads(8)
//!         .embeddings(true)
//!         .flash_attention(true)
//!         .build()
//!         .await?;
//!
//!     // Build sophisticated sampling strategy
//!     let sampler = SamplerBuilder::new()
//!         .temperature(0.8)
//!         .top_k(50)
//!         .nucleus(0.95)
//!         .penalties(|p| p
//!             .repetition(1.1)
//!             .frequency(0.1)
//!             .presence(0.1)
//!         )
//!         .build(model.clone())?;
//!
//!     Ok(())
//! }
//! ```

mod context;
mod model;
mod sampler;

pub use context::ContextBuilder;
pub use model::ModelBuilder;
pub use sampler::{PenaltyBuilder, SamplerBuilder};

/// Preset configurations for builders
pub mod presets {
    use super::*;

    /// Creative writing model configuration
    pub fn creative_model(builder: ModelBuilder) -> ModelBuilder {
        builder
            .gpu_layers(24)
            .context_size(4096)
            .memory_mapping(true)
    }

    /// Performance optimized model configuration
    pub fn performance_optimized(builder: ModelBuilder) -> ModelBuilder {
        builder
            .gpu_layers(99) // Offload as much as possible
            .memory_mapping(true)
            .memory_locking(false)
            .tensor_validation(false) // Skip validation for speed
    }

    /// Memory optimized model configuration
    pub fn memory_optimized(builder: ModelBuilder) -> ModelBuilder {
        builder
            .gpu_layers(0) // Use CPU only
            .memory_mapping(true)
            .memory_locking(false)
    }

    /// Creative sampling configuration
    pub fn creative_sampling(builder: SamplerBuilder) -> SamplerBuilder {
        builder
            .temperature(0.9)
            .top_k(60)
            .nucleus(0.95)
            .penalties(|p| p.repetition(1.15))
    }

    /// Precise sampling configuration
    pub fn precise_sampling(builder: SamplerBuilder) -> SamplerBuilder {
        builder
            .temperature(0.2)
            .top_k(10)
            .nucleus(0.85)
            .penalties(|p| p.repetition(1.05))
    }

    /// Balanced sampling configuration
    pub fn balanced_sampling(builder: SamplerBuilder) -> SamplerBuilder {
        builder
            .temperature(0.7)
            .top_k(40)
            .nucleus(0.9)
            .penalties(|p| p.repetition(1.1).frequency(0.1).presence(0.1))
    }
}