use serde::de::DeserializeOwned;
use serde_json::{json, Map, Value};
const DEFAULT_BASE_URL: &str = "http://localhost:4141/v1";
#[derive(Debug, thiserror::Error)]
pub enum Error {
#[error("localbrain endpoint not reachable ({0}) — is `localbrain start` running?")]
EndpointDown(String),
#[error("model not ready ({0}) — run `localbrain doctor`")]
ModelNotReady(String),
#[error("request timed out")]
Timeout,
#[error("bad response from endpoint: {0}")]
BadResponse(String),
#[error("model did not return valid JSON matching the requested schema")]
SchemaViolation,
}
pub type Result<T> = std::result::Result<T, Error>;
#[derive(Debug, Default, Clone)]
pub struct ChatOptions {
pub temperature: Option<f32>,
pub max_tokens: Option<u32>,
pub system: Option<String>,
pub stop: Option<Vec<String>>,
}
#[derive(Debug, Clone)]
pub struct Health {
pub ok: bool,
pub model: Option<String>,
}
#[derive(Debug, Clone)]
pub struct Client {
http: reqwest::Client,
base_url: String,
model: Option<String>,
embed_model: Option<String>,
}
impl Default for Client {
fn default() -> Self {
Self::new()
}
}
impl Client {
pub fn new() -> Self {
Self::builder().build()
}
pub fn builder() -> ClientBuilder {
ClientBuilder::default()
}
pub async fn chat(&self, prompt: &str) -> Result<String> {
self.chat_with(prompt, &ChatOptions::default()).await
}
pub async fn chat_with(&self, prompt: &str, opts: &ChatOptions) -> Result<String> {
let mut messages = Vec::new();
if let Some(system) = &opts.system {
messages.push(json!({ "role": "system", "content": system }));
}
messages.push(json!({ "role": "user", "content": prompt }));
let mut body = Map::new();
body.insert("messages".into(), Value::Array(messages));
self.add_common(&mut body, opts);
let data: Value = self.post("/chat/completions", Value::Object(body)).await?;
first_content(&data)
}
pub async fn classify(&self, text: &str, labels: &[&str]) -> Result<String> {
if labels.is_empty() {
return Err(Error::SchemaViolation);
}
let schema = json!({
"type": "object",
"properties": { "label": { "type": "string", "enum": labels } },
"required": ["label"],
"additionalProperties": false
});
let mut body = Map::new();
body.insert(
"messages".into(),
json!([
{ "role": "system", "content": "You are a precise text classifier. Choose exactly one label." },
{ "role": "user", "content": format!("Classify the following text into one of [{}].\n\nText:\n{}", labels.join(", "), text) }
]),
);
body.insert("temperature".into(), json!(0));
body.insert(
"response_format".into(),
json!({ "type": "json_schema", "json_schema": { "name": "classification", "schema": schema } }),
);
if let Some(model) = &self.model {
body.insert("model".into(), json!(model));
}
let data: Value = self.post("/chat/completions", Value::Object(body)).await?;
let content = first_content(&data)?;
let parsed: Value = parse_json(&content)?;
let label = parsed.get("label").and_then(|v| v.as_str());
match label {
Some(l) if labels.contains(&l) => Ok(l.to_string()),
_ => Err(Error::SchemaViolation),
}
}
pub async fn extract<T: DeserializeOwned>(&self, text: &str, schema: Value) -> Result<T> {
let mut body = Map::new();
body.insert(
"messages".into(),
json!([
{ "role": "system", "content": "Extract the requested fields as strict JSON. Use empty/0 values when not present." },
{ "role": "user", "content": format!("Extract fields from this text:\n\n{text}") }
]),
);
body.insert("temperature".into(), json!(0));
body.insert(
"response_format".into(),
json!({ "type": "json_schema", "json_schema": { "name": "extraction", "schema": schema } }),
);
if let Some(model) = &self.model {
body.insert("model".into(), json!(model));
}
let data: Value = self.post("/chat/completions", Value::Object(body)).await?;
let content = first_content(&data)?;
let value: Value = parse_json(&content)?;
serde_json::from_value(value).map_err(|_| Error::SchemaViolation)
}
pub async fn summarize(&self, text: &str) -> Result<String> {
self.summarize_with(text, &ChatOptions::default()).await
}
pub async fn summarize_with(&self, text: &str, opts: &ChatOptions) -> Result<String> {
let prompt = format!("Summarize the following concisely.\n\n{text}");
let mut o = opts.clone();
if o.temperature.is_none() {
o.temperature = Some(0.2);
}
self.chat_with(&prompt, &o).await
}
pub async fn embed(&self, text: &str) -> Result<Vec<f32>> {
let mut body = Map::new();
body.insert("input".into(), json!(text));
if let Some(model) = self.embed_model.as_ref().or(self.model.as_ref()) {
body.insert("model".into(), json!(model));
}
let data: Value = self.post("/embeddings", Value::Object(body)).await?;
let vector = data["data"][0]["embedding"].as_array();
match vector {
Some(arr) => Ok(arr.iter().filter_map(|v| v.as_f64().map(|f| f as f32)).collect()),
None => Err(Error::BadResponse("embeddings response had no vector".into())),
}
}
pub async fn health(&self) -> Result<Health> {
let url = format!("{}/models", self.base_url);
let resp = self.http.get(&url).send().await.map_err(map_reqwest_err)?;
if !resp.status().is_success() {
return Ok(Health { ok: false, model: None });
}
let data: Value = resp.json().await.map_err(|e| Error::BadResponse(e.to_string()))?;
let model = data["data"][0]["id"].as_str().map(str::to_string);
Ok(Health { ok: true, model })
}
fn add_common(&self, body: &mut Map<String, Value>, opts: &ChatOptions) {
if let Some(model) = &self.model {
body.insert("model".into(), json!(model));
}
if let Some(t) = opts.temperature {
body.insert("temperature".into(), json!(t));
}
if let Some(m) = opts.max_tokens {
body.insert("max_tokens".into(), json!(m));
}
if let Some(stop) = &opts.stop {
body.insert("stop".into(), json!(stop));
}
}
async fn post<T: DeserializeOwned>(&self, path: &str, body: Value) -> Result<T> {
let url = format!("{}{}", self.base_url, path);
let resp = self
.http
.post(&url)
.json(&body)
.send()
.await
.map_err(map_reqwest_err)?;
let status = resp.status();
if status.as_u16() == 503 {
return Err(Error::ModelNotReady("still loading".into()));
}
if !status.is_success() {
let detail = resp.text().await.unwrap_or_default();
return Err(Error::BadResponse(format!("HTTP {status}: {detail}")));
}
resp.json::<T>().await.map_err(|e| Error::BadResponse(e.to_string()))
}
}
#[derive(Debug, Default, Clone)]
pub struct ClientBuilder {
base_url: Option<String>,
model: Option<String>,
embed_model: Option<String>,
timeout_secs: Option<u64>,
}
impl ClientBuilder {
pub fn base_url(mut self, url: impl Into<String>) -> Self {
self.base_url = Some(url.into());
self
}
pub fn model(mut self, model: impl Into<String>) -> Self {
self.model = Some(model.into());
self
}
pub fn embed_model(mut self, model: impl Into<String>) -> Self {
self.embed_model = Some(model.into());
self
}
pub fn timeout_secs(mut self, secs: u64) -> Self {
self.timeout_secs = Some(secs);
self
}
pub fn build(self) -> Client {
let base_url = self
.base_url
.or_else(|| std::env::var("LOCALBRAIN_URL").ok())
.unwrap_or_else(|| DEFAULT_BASE_URL.to_string())
.trim_end_matches('/')
.to_string();
let http = reqwest::Client::builder()
.timeout(std::time::Duration::from_secs(self.timeout_secs.unwrap_or(60)))
.build()
.unwrap_or_default();
Client {
http,
base_url,
model: self.model,
embed_model: self.embed_model,
}
}
}
fn first_content(data: &Value) -> Result<String> {
data["choices"][0]["message"]["content"]
.as_str()
.map(str::to_string)
.ok_or_else(|| Error::BadResponse("no content in completion response".into()))
}
fn parse_json(raw: &str) -> Result<Value> {
if let Ok(v) = serde_json::from_str::<Value>(raw) {
return Ok(v);
}
if let (Some(start), Some(end)) = (raw.find('{'), raw.rfind('}')) {
if end > start {
if let Ok(v) = serde_json::from_str::<Value>(&raw[start..=end]) {
return Ok(v);
}
}
}
Err(Error::SchemaViolation)
}
fn map_reqwest_err(e: reqwest::Error) -> Error {
if e.is_timeout() {
Error::Timeout
} else if e.is_connect() {
Error::EndpointDown(e.to_string())
} else {
Error::BadResponse(e.to_string())
}
}