litertlm_rs/lib.rs
1//! Safe Rust bindings to the LiteRT-LM **C API 1.0.0**, covering every
2//! public header of Google's official prebuilt package:
3//!
4//! | Header | Rust API |
5//! |----------------------|-----------------------------------------------------------------------|
6//! | `engine.h` | [`EngineSettings`], [`Engine`], [`Session`], sampler / decoding configs, tokenizer, streaming, benchmarking |
7//! | `conversation.h` | [`Conversation`], [`ConversationConfig`], [`ConversationOptionalArgs`] |
8//! | `embedding_engine.h` | [`EmbeddingEngine`], [`EmbeddingEngineSettings`], [`EmbeddingOptions`] |
9//! | `model_info.h` | [`LoadedFile`] |
10//! | `experimental.h` | [`experimental`] (no stability guarantees) |
11//! | `error_reporter.h` | [`Error`], [`StatusCode`], [`last_error_message`] |
12//!
13//! # What changed in 1.0.0
14//!
15//! The C API is now fully status-code based, so nearly every operation
16//! returns [`Result`]. Highlights:
17//!
18//! * [`Error`] carries the C status code **and** the library's thread-local
19//! error message, captured at the moment of failure.
20//! * Sessions and conversations keep their [`Engine`] alive, so the C API's
21//! "destroy children before the engine" rule cannot be violated.
22//! * After `cancel_process`, a session/conversation can only be dropped; this
23//! is enforced ([`Error::UseAfterCancel`]).
24//! * The loaded library's C API version is verified once before the first
25//! engine is created ([`check_api_version`]).
26//! * New: [`SpeculativeDecodingConfig`], [`Session::clone_session`],
27//! single-threaded execution, [`EmbeddingEngine`], [`LoadedFile`],
28//! [`experimental`].
29//!
30//! Setters that can only fail on a NULL pointer (impossible here) keep the
31//! chainable `&mut Self` style; setters that can really fail return
32//! `Result<&mut Self>`.
33//!
34//! See the README for a function-by-function list.
35
36#[macro_use]
37mod util;
38
39mod config;
40mod conversation;
41mod embedding;
42mod engine;
43mod error;
44pub mod experimental;
45mod model_info;
46mod results;
47pub mod stream;
48mod types;
49mod version;
50
51pub use litertlm_sys;
52
53pub use config::{
54 ConversationConfig, ConversationOptionalArgs, InputData, NoRepeatNgramConfig,
55 RepetitionPenaltyConfig, SamplerParams, SessionConfig, SpeculativeDecodingConfig,
56 SuppressTokensConfig, ThinkingConfig,
57};
58pub use conversation::Conversation;
59pub use embedding::{
60 EmbeddingEngine, EmbeddingEngineSettings, EmbeddingOptions, EmbeddingResponse,
61 EmbeddingResponseRef, EmbeddingResponses,
62};
63pub use engine::{Engine, EngineSettings, Session};
64pub use error::{clear_last_error, last_error_message, Error, Result, StatusCode};
65pub use model_info::LoadedFile;
66pub use results::{
67 BenchmarkInfo, DetokenizeResult, Responses, TokenUnion, TokenUnionRef, TokenUnions,
68 TokenizeResult,
69};
70pub use stream::StreamChunk;
71pub use types::{
72 ActivationDataType, BackendType, ConstraintProviderType, ConstraintType, InputDataType,
73 InputOverflowStrategy, LogSeverity, Modality, ModelType, NpuBrand, SamplerType,
74 SpeculativeDecodingMode, TokenUnionType,
75};
76pub use version::{api_version, check_api_version, ApiVersion};
77
78use litertlm_sys as sys;
79
80/// Sets the minimum log severity for the underlying C++ library. Call this
81/// once, before creating an [`Engine`], to quiet (or increase) its stderr
82/// logging. It writes straight to stderr, independent of anything in Rust,
83/// so this is the only way to control it.
84///
85/// Wraps `litert_lm_set_min_log_level`.
86pub fn set_min_log_level(level: LogSeverity) -> Result<()> {
87 util::check(
88 unsafe { sys::litert_lm_set_min_log_level(level.into()) },
89 "litert_lm_set_min_log_level",
90 )
91}
92
93/// Extracts and concatenates just the plain text from a message JSON object
94/// of the shape `{"role": "...", "content": [{"type": "text", "text":
95/// "..."}, ...]}` -- i.e. what [`Conversation::send_message`] or each stream
96/// chunk's [`StreamChunk::text`] returns. Non-text content blocks are
97/// skipped. Returns an empty string if the JSON doesn't match the expected
98/// shape, since callers usually just want "whatever text is in here, if
99/// any".
100pub fn extract_text(message_json: &str) -> String {
101 let Ok(value) = serde_json::from_str::<serde_json::Value>(message_json) else {
102 return String::new();
103 };
104 let Some(content) = value.get("content").and_then(|c| c.as_array()) else {
105 return String::new();
106 };
107 content
108 .iter()
109 .filter(|block| block.get("type").and_then(|t| t.as_str()) == Some("text"))
110 .filter_map(|block| block.get("text").and_then(|t| t.as_str()))
111 .collect::<Vec<_>>()
112 .join("")
113}