llm_kernel/
lib.rs

1#![deny(missing_docs)]
2//! # llm-kernel
3//!
4//! Foundation library for Rust AI-native applications.
5//!
6//! Provides a composable, feature-gated set of modules for building
7//! LLM-powered tools, agents, and servers:
8//!
9//! | Feature       | Module       | Description                                         |
10//! |---------------|-------------|-----------------------------------------------------|
11//! | `provider`    | [`provider`]  | Provider catalog, model descriptors, pricing — **default** |
12//! | `client-async`| [`llm`]       | Async LLM client (OpenAI, Anthropic) with SSE streaming |
13//! | `discovery`   | [`discovery`] | Dynamic model discovery (models.dev, Ollama, OpenAI-compat) |
14//! | `secrets`     | [`secrets`]   | SecretVault — dotenv-style credential management |
15//! | `store`       | [`store`]     | SQLite init helpers (WAL, PRAGMA, schema versioning) |
16//! | `config`      | [`config`]    | TOML config loader with auto-create from template |
17//! | `graph`       | [`graph`]     | Knowledge graph — SQLite, FTS5, smart recall, BFS traversal |
18//! | `mcp`         | [`mcp`]       | MCP server framework — JSON-RPC 2.0, stdio transport |
19//! | `tokens`      | [`tokens`]    | Token estimation with Unicode-script heuristics |
20//! | `install`     | [`install`]   | AI tool installation wizard (Claude, Cursor, Copilot, etc.) |
21//! | `search`      | [`search`]    | Hybrid search with Reciprocal Rank Fusion |
22//! | `embedding`   | [`embedding`] | Embedding provider trait + cosine similarity |
23//! | `telemetry`   | [`telemetry`] | Telemetry framework — enum-gated events, no PII |
24//! | `safety`      | [`safety`]    | Secret masking, error classification, output sanitization |
25//!
26//! ## Quick start
27//!
28//! The [`prelude`] module re-exports the most commonly used types:
29//!
30//! ```no_run
31//! use llm_kernel::prelude::*;
32//! ```
33
34// `embedding-fastembed` (static ONNX Runtime archive) and
35// `embedding-fastembed-dynamic-linking` (runtime `libonnxruntime.{so,dll,dylib}`
36// load) are mutually exclusive. Enabling both unifies `ort-download-binaries-*`
37// and `ort-load-dynamic` on the shared `fastembed`/`ort-sys` crate, which makes
38// ort-sys skip the static-archive download and silently expect a runtime dylib
39// llm-kernel never ships — the original #50/#55 failure mode. Force a hard
40// build error so the conflict can never be silent. See `Cargo.toml` feature
41// docs and #55.
42#[cfg(all(
43    feature = "embedding-fastembed",
44    feature = "embedding-fastembed-dynamic-linking"
45))]
46compile_error!(
47    "embedding-fastembed and embedding-fastembed-dynamic-linking are mutually exclusive \
48     (static vs dynamic ONNX Runtime linking). Enabling both triggers Cargo feature \
49     unification that silently disables the static link path (#50/#55). Enable exactly one."
50);
51
52// Every reqwest-backed feature needs a TLS crypto provider. reqwest 0.13's
53// `rustls` feature pins aws-lc-rs (needs cmake/nasm to cross-compile); the
54// `rustls-ring` feature swaps in the pure-Rust ring provider (#93). Without
55// one of them the build succeeds but reqwest panics at runtime when the
56// first client is built — force a hard build error instead.
57#[cfg(all(
58    any(
59        feature = "client-async",
60        feature = "discovery-async",
61        feature = "elastic"
62    ),
63    not(any(feature = "rustls-aws-lc-rs", feature = "rustls-ring"))
64))]
65compile_error!(
66    "client-async / discovery-async / elastic require a TLS provider feature: \
67     enable `rustls-aws-lc-rs` (default; aws-lc-rs needs a C toolchain) or \
68     `rustls-ring` (pure Rust, cross-compiles without cmake/nasm). \
69     With default-features = false you must add one of them explicitly."
70);
71
72// Enabling both unifies reqwest to `rustls` + `rustls-no-provider`, where the
73// aws-lc-rs feature silently wins and `rustls-ring` is ignored. Reject it.
74#[cfg(all(feature = "rustls-ring", feature = "rustls-aws-lc-rs"))]
75compile_error!("rustls-ring and rustls-aws-lc-rs are mutually exclusive; enable exactly one.");
76
77/// TLS provider bootstrap (`rustls-ring`). Internal.
78pub(crate) mod tls;
79
80/// Error types and result alias for llm-kernel.
81pub mod error;
82
83#[cfg(feature = "provider")]
84pub mod provider;
85
86#[cfg(feature = "discovery")]
87pub mod discovery;
88
89#[cfg(feature = "secrets")]
90pub mod secrets;
91
92#[cfg(feature = "client-async")]
93pub mod llm;
94
95#[cfg(feature = "store")]
96pub mod store;
97
98#[cfg(feature = "config")]
99pub mod config;
100
101#[cfg(feature = "graph")]
102pub mod graph;
103
104#[cfg(feature = "mcp")]
105pub mod mcp;
106
107#[cfg(feature = "tokens")]
108pub mod tokens;
109
110#[cfg(feature = "install")]
111pub mod install;
112
113#[cfg(feature = "search")]
114pub mod search;
115
116#[cfg(any(feature = "embedding", feature = "embedding-openai"))]
117pub mod embedding;
118
119#[cfg(feature = "telemetry")]
120pub mod telemetry;
121
122#[cfg(feature = "safety")]
123pub mod safety;
124
125pub mod prelude;
126
127/// Returns the crate name (`"llm-kernel"`).
128pub fn name() -> &'static str {
129    "llm-kernel"
130}
131
132/// Returns the crate version (from `Cargo.toml`).
133pub fn version() -> &'static str {
134    env!("CARGO_PKG_VERSION")
135}
llm_kernel/lib.rs

llm_kernel/
lib.rs
