docs/SYSTEM_BEHAVIOR.md

JackAILocal System Behavior

Layers

1. The Gradio Builder accepts a real hardware profile, recommends compatible models, and exports manifests or builder packages.
2. Platform builders prepare a local folder, USB drive, or external SSD and validate the resulting payload.
3. jackailocald serves the WebUI and routes requests only to reachable local AI engines.

Runtime

The Rust runtime serves static WebUI files and these primary APIs:

GET  /api/status
GET  /api/features
GET  /api/models
POST /v1/chat/completions
GET  /api/threads
POST /api/threads
POST /api/threads/:id/messages
POST /api/vision/analyze
GET  /api/voice/status
POST /api/voice/transcribe
POST /api/voice/synthesize
POST /api/packs/export
POST /api/packs/import
POST /api/agent/recommend
GET  /api/phone
POST /api/phone
POST /api/runtime/restart

Chat and SCOUT use installed Ollama models. An OpenAI-compatible llama.cpp server can be used as an explicit local chat fallback. Voice uses whisper.cpp and Piper binaries and models stored in the package.

POST /api/agent/recommend adds a local LLM-in-the-loop for client configuration and model selection review. It uses only installed local models, enforces the <=32B catalog policy, prefers Gemma 4 12B (gemma4:12b) when present, and returns an explicit error when a requested agent model is unavailable.

The runtime reports a feature as available only when the required local engine and model are available.

Storage

workspace/threads/       conversation JSON files
workspace/documents/     user notes
workspace/settings/      local settings and phone pairing token
workspace/exports/       encrypted packs and support ZIPs
workspace/voice/         temporary voice files
workspace/scout/         SCOUT workspace
models/ollama/           Ollama model store
models/whisper/          speech-to-text models
models/piper/            text-to-speech models

Threads are persistent and support filtering, rename, and individual deletion.

Phone Access

The default bind is 127.0.0.1:4891. Phone Access must be enabled explicitly. After restart, the runtime binds to 0.0.0.0:4891, generates a LAN URL and QR code, and requires X-JackAILocal-Token for non-loopback API requests.

Transfer Packs

Transfer packs use AES-256-GCM with PBKDF2-HMAC-SHA256. Passphrases are not stored. Imported settings are sanitized so a pack cannot silently enable Phone Access or transfer a pairing token.

Builders

Builders install selected Ollama models, install Voice assets, generate a SHA-256 manifest, and refuse success when required files are missing. The source package and target path must not overlap.

Offline Boundary

Normal use does not require internet after models and Voice assets are present. The runtime has no cloud inference fallback. A capability that cannot run locally returns an explicit unavailable or error response.