Skip to main content

product_os_models/
lib.rs

1#![warn(missing_docs)]
2
3//! # product-os-models
4//!
5//! A unified machine learning library providing LLM inference, classical ML training,
6//! deep learning (Burn), custom computational graph building, and
7//! ML tooling -- all behind feature flags for minimal dependency footprint.
8//!
9//! ## Architecture
10//!
11//! This crate uses a **unified trait hierarchy** where all model types implement
12//! the base [`ModelKind`] trait, with extension traits for specific capabilities:
13//!
14//! - [`Trainable`] -- models that can be trained on data
15//! - **LlmCapable** -- large language models with generation capabilities (behind `llm`)
16//! - [`Educatable`] -- models with educational content
17//! - [`PretrainedLoadable`] -- models that can load pre-trained weights
18//!
19//! ## Feature Flags
20//!
21//! ### Core
22//!
23//! | Feature | Description |
24//! |---------|-------------|
25//! | `core` | Lightweight traits, types, and errors (no heavy dependencies) |
26//! | `std` | Standard library support (enabled by default) |
27//!
28//! ### LLM Inference
29//!
30//! | Feature | Description |
31//! |---------|-------------|
32//! | `llm` | Local LLM inference via Candle (enables `candle-core`, `candle-nn`, etc.) |
33//! | `llm-api` | Remote LLM backends shared plumbing (requires `product-os-request`) |
34//! | `llm-ollama` | Ollama API backend (implies `llm-api`) |
35//! | `llm-vllm` | vLLM API backend (implies `llm-api`) |
36//! | `llm-sglang` | SGLang API backend (implies `llm-api`) |
37//! | `llm-max` | MAX API backend (implies `llm-api`) |
38//!
39//! ### Hardware Acceleration (require `llm`)
40//!
41//! | Feature | Description |
42//! |---------|-------------|
43//! | `metal` | Apple Metal GPU backend for Candle (macOS / Apple Silicon) |
44//! | `accelerate` | Apple Accelerate framework for BLAS on macOS |
45//! | `cuda` | NVIDIA CUDA GPU backend for Candle |
46//!
47//! ### Deep Learning & Burn
48//!
49//! | Feature | Description |
50//! |---------|-------------|
51//! | `dl-core` | Deep learning foundation via Burn |
52//! | `dl-mlp` | Multi-layer perceptron architecture (implies `dl-core`) |
53//! | `dl-cnn` | Convolutional neural network architecture (implies `dl-core`) |
54//! | `dl-rnn` | Recurrent neural network architecture (implies `dl-core`) |
55//! | `dl-transformer` | Transformer architecture (implies `dl-core`) |
56//! | `burn-backend` | Burn with Candle compute backend (implies `llm`) |
57//!
58//! ### ML Toolkit Modules
59//!
60//! | Feature | Description |
61//! |---------|-------------|
62//! | `classical` | Classical ML (linear regression, SVM, k-means, decision trees, etc.) |
63//! | `data` | Data loading, schema inference, and dataset management |
64//! | `preprocessing` | Feature engineering and data transformation pipelines |
65//! | `experiments` | Experiment tracking, run comparison, and metric logging |
66//! | `tuning` | Hyperparameter optimisation (grid, random, Bayesian) |
67//! | `custom-graph` | Custom computational graph builder for research models |
68//! | `inference` | Inference runtime for trained models |
69//! | `onnx` | ONNX model export and import (implies `inference`) |
70//!
71//! **Moved to `product-os-ml-tooling`:** `eda`, `interpretability`, `registry`
72//!
73//! ### Other
74//!
75//! | Feature | Description |
76//! |---------|-------------|
77//! | `remote` | Download models from Hugging Face Hub (`hf-hub`) |
78//!
79//! ### Bundles
80//!
81//! | Feature | Description |
82//! |---------|-------------|
83//! | `ml-full` | All ML toolkit modules (classical + DL + data + preprocessing + ...) |
84//! | `all` | Everything: `ml-full` + `llm` + all API backends |
85//!
86//! ## Quick Start
87//!
88//! ### Using the unified trait hierarchy (core only)
89//!
90//! ```rust
91//! use product_os_models::core::traits::{ModelKind, ModelCategory};
92//! // Implement ModelKind for your own model kind...
93//! ```
94//!
95//! ### Using an Ollama backend (requires `llm` + `llm-api` features)
96//!
97//! ```rust,ignore
98//! use product_os_models::llm::parameters::Parameters;
99//! use product_os_models::llm::model::ModelDefinition;
100//! use product_os_models::llm::backends::ollama::Ollama;
101//!
102//! let model_def = ModelDefinition {
103//!     name: "llama3".to_string(),
104//!     external_model_name: "llama3:8b".to_string(),
105//!     ..Default::default()
106//! };
107//!
108//! let mut params = Parameters::new(model_def);
109//! params.root_url = Some("http://localhost:11434".to_string());
110//!
111//! let backend = Ollama::new(params);
112//! ```
113
114// ---------------------------------------------------------------------------
115// Core types, traits, and error definitions (always available)
116// ---------------------------------------------------------------------------
117
118/// Core types, traits, and error definitions for the unified ML platform.
119pub mod core;
120
121/// Optional shared inference runtimes (ONNX Runtime session helpers).
122#[cfg(feature = "ort-runtime")]
123pub mod runtime;
124
125// ---------------------------------------------------------------------------
126// LLM inference capabilities (existing product-os-models functionality)
127// ---------------------------------------------------------------------------
128
129/// LLM inference module: local Candle execution and remote API backends.
130#[cfg(feature = "llm")]
131pub mod llm;
132
133// ---------------------------------------------------------------------------
134// Backward-compatible re-exports
135//
136// The original public modules (model, parameters, model_response, model_runner,
137// predefined_models, backends, local, models) are re-exported from their new
138// locations under llm/ so that existing code using
139// `product_os_models::model::*` continues to work.
140// ---------------------------------------------------------------------------
141
142/// Core LLM model traits and types (re-exported for backward compatibility).
143#[cfg(feature = "llm")]
144pub use llm::model;
145
146/// LLM parameters (re-exported for backward compatibility).
147#[cfg(feature = "llm")]
148pub use llm::parameters;
149
150/// LLM model response (re-exported for backward compatibility).
151#[cfg(feature = "llm")]
152pub use llm::model_response;
153
154/// LLM model runner (re-exported for backward compatibility).
155#[cfg(feature = "llm")]
156pub use llm::model_runner;
157
158/// Per-request chat HTTP overrides (Ollama `think`, etc.).
159#[cfg(feature = "llm")]
160pub use llm::ExecuteChatExtras;
161
162/// Predefined LLM model configurations (re-exported for backward compatibility).
163#[cfg(feature = "llm")]
164pub use llm::predefined_models;
165
166/// API backends: Ollama, vLLM, SGLang, MAX (re-exported for backward compatibility).
167///
168/// Requires **both** `llm` (for the `llm` module to exist) and `llm-api`
169/// (for the backends sub-module to be compiled).
170#[cfg(all(feature = "llm", feature = "llm-api"))]
171pub use llm::backends;
172
173/// CLI subprocess backends shared infrastructure (Codex, Claude, Cursor).
174#[cfg(all(feature = "llm", feature = "llm-cli"))]
175pub use llm::cli;
176
177/// Local model execution: GGUF, SafeTensors (re-exported for backward compatibility).
178#[cfg(feature = "llm")]
179pub use llm::local;
180
181/// Model architectures: Llama, Qwen, Phi, Generic (re-exported for backward compatibility).
182#[cfg(feature = "llm")]
183pub use llm::models;
184
185// ---------------------------------------------------------------------------
186// New ML toolkit modules (stubs -- implemented in subsequent sub-plans)
187// ---------------------------------------------------------------------------
188
189/// Data loading, schema inference, and dataset management.
190#[cfg(feature = "data")]
191pub mod data;
192
193/// Data preprocessing and feature engineering pipelines.
194#[cfg(feature = "preprocessing")]
195pub mod preprocessing;
196
197/// Classical ML models (linear regression, SVM, k-means, decision trees, etc.).
198#[cfg(feature = "classical")]
199pub mod classical;
200
201/// Deep learning models and training via Burn.
202#[cfg(feature = "dl-core")]
203#[path = "dl/mod.rs"]
204pub mod dl;
205
206/// Experiment tracking and run comparison.
207#[cfg(feature = "experiments")]
208pub mod experiments;
209
210/// Hyperparameter tuning: grid search, random search, and Bayesian optimization.
211#[cfg(feature = "tuning")]
212pub mod tuning;
213
214/// Reinforcement learning (DQN, PPO).
215#[cfg(feature = "rl")]
216pub mod rl;
217
218/// Custom computational graph builder.
219///
220/// Provides a DSL over Burn's autodiff for building custom ML architectures
221/// from first principles. Users define computational graphs with operations,
222/// activations, losses, and optimizers using mathematical expressions.
223#[cfg(feature = "custom-graph")]
224pub mod custom;
225
226/// Inference runtime and model serving.
227#[cfg(feature = "inference")]
228pub mod inference;
229
230/// Text-to-speech (TTS) inference from path-loaded safetensors.
231///
232/// For embedded use (e.g. iOS/Android): app downloads model weights,
233/// then passes the directory path. No network in this crate.
234#[cfg(feature = "tts")]
235pub mod tts;
236
237// NOTE: The following modules have been moved to product-os-ml-tooling:
238// - `registry` -- model registry (now in product_os_ml_tooling::ml::registry)
239// - `interpretability` -- model explainability (now in product_os_ml_tooling::ml::interpretability)
240// - `eda` -- exploratory data analysis (now in product_os_ml_tooling::ml::eda)
241
242// ---------------------------------------------------------------------------
243// Convenience re-exports from core
244// ---------------------------------------------------------------------------
245
246#[cfg(feature = "llm")]
247pub use core::LlmCapable;
248pub use core::{
249    ArtifactFormat, DetectedObject, Educatable, MetricLogger, ModelCapabilities, ModelCategory,
250    ModelError, ModelInput, ModelKind, ModelOutput, ModelTensor, PretrainedLoadable, Trainable,
251};
252
253#[cfg(feature = "inference")]
254pub use inference::{InferenceEngine, InferenceMetadata};