Pumas Library

Pumas Library is a desktop and Rust library for keeping AI model files, metadata, downloads, and local-runtime configuration in one place.

Its main capabilities are:

• an SQLite-indexed local model library with full-text search;
• Hugging Face search, metadata lookup, and resumable downloads;
• local import, integrity reconciliation, and repair;
• typed resolution of model artifacts and runtime requirements; and
• optional local inference integrations for Ollama, llama.cpp, ONNX Runtime, and Torch.

Repository Layout

Path	Responsibility
rust/crates/pumas-core	Model library, persistence, downloads, runtime profiles, and public Rust API
rust/crates/pumas-rpc	Local HTTP/JSON-RPC sidecar used by the desktop app
rust/crates/pumas-app-manager	Optional runtime installation and process integration
rust/crates/pumas-uniffi	Experimental UniFFI adapter and generators
frontend	React renderer
electron	Desktop main process, preload boundary, and packaging
torch-server	Optional Python Torch inference sidecar

See Architecture for process and ownership details.

Desktop Quick Start

The root launchers share one Node implementation.

./launcher.sh --install
./launcher.sh --build
./launcher.sh --run

On Windows:

.\launcher.ps1 --install
.\launcher.ps1 --build
.\launcher.ps1 --run

Release-mode local builds use --build-release followed by --run-release. Run either launcher with --help for the complete command and exit-code contract.

Inference integrations are included in the default desktop build. Build the model-library-only variant with:

PUMAS_INFERENCE_PLUGINS=false ./launcher.sh --build-release

PUMAS_LAUNCHER_ROOT=/path/to/root selects a specific library root. A launcher root contains launcher-data/ and shared-resources/; the model library itself lives under shared-resources/models/.

Rust Usage

PumasApi is the owning API. Construction fails when another process already owns the same launcher root. Use PumasLocalClient to connect to a running owner, or PumasReadOnlyLibrary for indexed read-only access.

use pumas_library::{PumasApi, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let api = PumasApi::builder("/path/to/pumas")
        .auto_create_dirs(true)
        .build()
        .await?;

    for model in api.list_models().await? {
        println!("{}", model.official_name);
    }

    Ok(())
}

The crate is currently consumed from this workspace:

[dependencies]
pumas-library = { path = "rust/crates/pumas-core" }

Verification

./scripts/rust/check.sh
npm run -w frontend lint
npm run -w frontend check:types
npm run -w frontend test:run
npm run -w electron lint
npm run -w electron test
npm run test:launcher
python3 -m unittest discover -s torch-server/tests

Use ./launcher.sh --test for the launcher-owned aggregate flow. A passing build or startup smoke is not evidence for every runtime or release contract; see Development and Releasing.

Platform and Binding Status

Linux x64 is the primary development and runtime target. CI also compiles and packages Windows x64 and macOS arm64 artifacts, but runtime evidence on those platforms is narrower.

Binding generators exist for Python, Kotlin, Swift, Ruby, and C#, with a local C# smoke harness. These surfaces are not yet backed by a complete host/runtime support matrix. The Rustler crate is experimental and does not currently expose the core library API. See Native bindings.

Documentation

• Documentation index
• Contributing
• Releasing
• Security
• Current standards audit

License

Pumas Library is licensed under the MIT License.