ferrox_inference/
lib.rs

1//! Ferrox — a pure-Rust GGUF / MoE inference engine.
2//!
3//! This crate is a **facade**. It contains no logic of its own: it
4//! re-exports the workspace under one name so a dependent writes one
5//! line in `Cargo.toml` instead of six, and so the project is findable
6//! on crates.io (the name `ferrox` belongs to an unrelated crate).
7//!
8//! The command-line tools are not here. `cargo install ferrox-cli`
9//! installs the `ferrox` binary; `ferrox-server` is the
10//! OpenAI-compatible HTTP server. Shipping a second binary called
11//! `ferrox` from this crate would just fight the first one over
12//! `~/.cargo/bin`.
13//!
14//! # Layout
15//!
16//! The stack, bottom to top:
17//!
18//! | Module | Crate | What it is |
19//! |---|---|---|
20//! | [`gguf`] | `ferrox-gguf` | GGUF mmap reader, sharded checkpoints |
21//! | [`quant`] | `ferrox-quant` | Block layouts and fused dequant+dot |
22//! | [`safetensors`] | `ferrox-safetensors` | SafeTensors mmap reader |
23//! | [`core`] | `ferrox-core` | Tensor ops, RoPE, GQA, KV cache |
24//! | [`moe`] | `ferrox-moe` | Expert routing and dispatch |
25//! | [`models`] | `ferrox-models` | Loaders and decoder stacks |
26//! | [`api`] | `ferrox-api` | Route constants + wire DTOs (feature `api`) |
27//!
28//! # Example
29//!
30//! ```no_run
31//! use ferrox_inference::gguf::ShardedGguf;
32//!
33//! let file = ShardedGguf::open("model.gguf")?;
34//! println!("{} tensors", file.tensor_count());
35//! # Ok::<(), Box<dyn std::error::Error>>(())
36//! ```
37//!
38//! # Features
39//!
40//! - `metal` — Apple Metal kernels. Apple Silicon only.
41//! - `cuda` — CUDA/NVRTC kernels. Needs a CUDA toolkit at build time.
42//!   Held to "must compile": there is no pinned benchmark host and no
43//!   published receipts for it. See `docs/FEATURES.md`.
44//! - `api` — pull in `ferrox-api` for client-side route constants.
45//!
46//! Neither GPU feature is on by default, because both are wrong to
47//! assume: `metal` does not build off Apple Silicon and `cuda` needs a
48//! toolkit that most machines do not have.
49
50#![forbid(unsafe_code)]
51
52pub use ferrox_core as core;
53pub use ferrox_gguf as gguf;
54pub use ferrox_models as models;
55pub use ferrox_moe as moe;
56pub use ferrox_quant as quant;
57pub use ferrox_safetensors as safetensors;
58
59#[cfg(feature = "api")]
60pub use ferrox_api as api;
61
62/// The workspace version this facade was built from.
63///
64/// Every crate in the workspace shares one version, so this is the
65/// version of the whole engine, not just of the facade.
66pub const VERSION: &str = env!("CARGO_PKG_VERSION");
67
68#[cfg(test)]
69mod tests {
70    /// The facade is only useful if it actually re-exports. These
71    /// paths would fail to COMPILE -- not merely assert false -- if a
72    /// module were dropped from `lib.rs`, which is the failure mode
73    /// worth catching: a facade that silently stops re-exporting one
74    /// layer looks fine until a dependent upgrades and cannot build.
75    #[allow(dead_code)]
76    fn every_layer_is_reachable_through_the_facade() {
77        let _: Option<super::gguf::ShardedGguf> = None;
78        let _: Option<super::quant::QuantError> = None;
79        let _: Option<super::core::cache::KvCache> = None;
80        let _: Option<super::safetensors::SafetensorsFile> = None;
81        let _ = std::mem::size_of::<super::models::Decoder>();
82        let _ = std::mem::size_of::<super::moe::MoeLayerConfig>();
83    }
84
85    #[test]
86    fn version_is_the_workspace_version() {
87        assert_eq!(super::VERSION, env!("CARGO_PKG_VERSION"));
88        assert!(!super::VERSION.is_empty());
89    }
90}
ferrox_inference/lib.rs

ferrox_inference/
lib.rs
