localbrain 0.1.1

Rust client for a localbrain endpoint — free, private, local AI (chat / classify / extract / summarize / embed). Talks to a local OpenAI-compatible model; no API key.
Documentation

localbrain (Rust client)

Crates.io docs.rs License: MIT

Rust client for a localbrain endpoint — free, private, local AI. It makes async HTTP calls to a local, OpenAI-compatible model, so it's a tiny dependency (reqwest + serde). No API key.

# Cargo.toml
[dependencies]
localbrain = "0.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
use localbrain::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let ai = Client::new(); // LOCALBRAIN_URL, or http://localhost:4141/v1

    let reply  = ai.chat("Summarize: ...").await?;
    let label  = ai.classify(text, &["work", "personal", "urgent"]).await?; // one label
    let vector = ai.embed("find me by meaning").await?;                     // Vec<f32>
    Ok(())
}

Getting an endpoint

This crate is only the client. To download a model and serve the endpoint it talks to, run the CLI in your project once (Node tool):

npx localbrain          # one-time setup
npx localbrain start    # serves http://localhost:4141/v1

Run inside a Cargo project and npx localbrain now wires Rust for you: it adds this crate to Cargo.toml and generates a src/ai.rs helper. In a Leptos crate it detects the leptos dependency, adds localbrain as an optional dependency behind your ssr feature, and generates a #[server] function instead. Every edit is shown as a diff first and is reversible with localbrain undo. You can still wire it by hand using the examples below.

Confirm it's alive without writing any code:

localbrain try "Cancel my plan please"   # prints a real response
localbrain try                            # quick classify + extract demo

Run the example

The crate ships a runnable example. With an endpoint up:

cargo run --example basic

It chats, classifies, and extracts a typed struct — a copy-paste starting point for your own code. See examples/basic.rs.

API

Client::new()                                   // from LOCALBRAIN_URL / default
Client::builder().base_url(..).model(..).build()

ai.chat(prompt).await?                 -> String
ai.chat_with(prompt, &opts).await?     -> String   // ChatOptions { temperature, max_tokens, system, stop }
ai.classify(text, &["a","b"]).await?   -> String   // exactly one label
ai.extract::<T>(text, schema).await?   -> T         // T: Deserialize; schema is a serde_json JSON Schema
ai.summarize(text).await?              -> String
ai.embed(text).await?                  -> Vec<f32>
ai.health().await?                     -> Health

Errors are a typed localbrain::Error (EndpointDown, ModelNotReady, Timeout, BadResponse, SchemaViolation).

Structured extraction:

use serde::Deserialize;
use serde_json::json;

#[derive(Deserialize)]
struct Invoice { vendor: String, total: f64 }

let schema = json!({
    "type": "object",
    "properties": { "vendor": {"type":"string"}, "total": {"type":"number"} },
    "required": ["vendor", "total"]
});
let invoice: Invoice = ai.extract("Invoice from Acme for $42", schema).await?;

Framework examples

Axum

[dependencies]
localbrain = "0.1"
axum = "0.7"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
serde = { version = "1", features = ["derive"] }
use axum::{extract::State, routing::post, Json, Router};
use localbrain::Client;
use serde::{Deserialize, Serialize};
use std::sync::Arc;

#[derive(Deserialize)]
struct In { text: String }
#[derive(Serialize)]
struct Out { label: String }

async fn triage(State(ai): State<Arc<Client>>, Json(inp): Json<In>) -> Result<Json<Out>, String> {
    let label = ai
        .classify(&inp.text, &["billing", "support", "sales"])
        .await
        .map_err(|e| e.to_string())?;
    Ok(Json(Out { label }))
}

#[tokio::main]
async fn main() {
    let ai = Arc::new(Client::new());
    let app = Router::new().route("/triage", post(triage)).with_state(ai);
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Actix Web

[dependencies]
localbrain = "0.1"
actix-web = "4"
serde = { version = "1", features = ["derive"] }
use actix_web::{post, web, App, HttpResponse, HttpServer, Responder};
use localbrain::Client;
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct In { text: String }
#[derive(Serialize)]
struct Out { label: String }

#[post("/triage")]
async fn triage(ai: web::Data<Client>, body: web::Json<In>) -> impl Responder {
    match ai.classify(&body.text, &["billing", "support", "sales"]).await {
        Ok(label) => HttpResponse::Ok().json(Out { label }),
        Err(e) => HttpResponse::InternalServerError().body(e.to_string()),
    }
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    let ai = web::Data::new(Client::new());
    HttpServer::new(move || App::new().app_data(ai.clone()).service(triage))
        .bind(("0.0.0.0", 3000))?
        .run()
        .await
}

Leptos

Leptos components run as WASM in the browser, so call localbrain from a server function (#[server]) — its body only compiles/runs on the server, which is where the AI call belongs. Make the crate a server-only (optional) dependency enabled by your ssr feature:

[dependencies]
leptos = "0.7"
serde = { version = "1", features = ["derive"] }
# server-only:
localbrain = { version = "0.1", optional = true }

[features]
hydrate = ["leptos/hydrate"]
ssr = ["leptos/ssr", "dep:localbrain"]   # localbrain only in the server build
use leptos::prelude::*;

// Runs on the server; the browser calls it over HTTP automatically.
#[server]
pub async fn triage(text: String) -> Result<String, ServerFnError> {
    use localbrain::Client;
    let ai = Client::new(); // LOCALBRAIN_URL, or http://localhost:4141/v1
    ai.classify(&text, &["billing", "support", "sales"])
        .await
        .map_err(|e| ServerFnError::new(e.to_string()))
}

#[component]
pub fn Triage() -> impl IntoView {
    let action = ServerAction::<Triage>::new();
    view! {
        <button on:click=move |_| { action.dispatch(Triage { text: "the invoice is overdue".into() }); }>
            "Classify"
        </button>
        <p>{move || action.value().get().map(|r| format!("{r:?}"))}</p>
    }
}

Leptos 0.6: use use leptos::*; and create_server_action::<Triage>() instead of ServerAction::<Triage>::new(). The #[server] function body is identical.

Because localbrain sits behind the ssr feature and is only used inside #[server] bodies, it never enters your WASM/client bundle.

Plain Tokio

See examples/basic.rs — run it with cargo run --example basic while an endpoint is up.

Notes

  • Small local model: great at classify / extract / summarize / route / light chat — not GPT-class reasoning. For hard tasks, keep a cloud model and route only those calls out.
  • Client is cheap to clone() (shares one connection pool) — store it in your app state.

License

MIT