Skip to main content

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}