> ## Documentation Index > Fetch the complete documentation index at: https://docs.kaleidoswap.com/llms.txt > Use this file to discover all available pages before exploring further. # KaleidoMind: On-Device AI Engine for Bitcoin Wallets > On-device reasoning engine behind agentic KaleidoSwap wallets, with a tiered request funnel, one tool contract across hosts, and confirm-before-spend built in [KaleidoMind](https://github.com/kaleidoswap/kaleido-mind) (`@kaleidorg/mind`) is a local-first, agentic reasoning and tool-calling engine for a multi-L2 Bitcoin wallet. It is a pure library, an `Engine` for the agentic loop, a `ToolRegistry` with pluggable `ToolSource`s, a `SkillRegistry`, and an injected `LLMProvider`, that runs identically on a phone and a laptop. The design starts from a hard constraint: small on-device models are slow and unreliable at multi-step planning. KaleidoMind avoids asking them to do that work. KaleidoMind does not run by itself, it is a library embedded by a host: the [Rate mobile wallet](https://github.com/kaleidoswap/Rate) (React Native, fully on-device QVAC), the [Desktop App](/desktop-app/getting-started/introduction)'s Tauri sidecar, or an eval and benchmark harness. **[KaleidoAgent](/ai-tools/kaleido-agent) does not currently use this library**, it has its own separate agent loop. See [Relationship to KaleidoAgent](#relationship-to-kaleidoagent) below. ## The Tiered Funnel Most requests never reach the model at all. | Tier | Example | Cost | | ----------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------- | | `T0` fast path | "balance", "address", "btc price" | Zero inferences, instant | | `T2` recipe | "pay bob 3 EUR", "buy 0.001 BTC" | About one inference (the model may assist slot extraction), then a deterministic chain, confirm-gated | | `T1` agentic loop | Everything else | Skill-scoped LLM, can P2P-delegate hard or novel chains to a paired desktop's bigger model | * **T0, fast path.** Deterministic pattern match, no inference. Balance checks, addresses, spot prices. * **T2, recipe engine.** A skill carries the ordered plan (resolve, price, convert, confirm, send); the model only fills the slots. That makes multi-step flows reliable even on a \~0.6B parameter model, instead of asking the model to plan the whole chain itself. * **T1, full agentic loop.** Everything else, scoped to the skill's own tool list so a small model never has to reason over the entire tool surface at once. Discovery flows (for example merchant-finder) intentionally lean more on the model for natural-language understanding. ## One Tool Contract, Many Transports The model sees identical tool names and schemas everywhere, only *how a tool executes* differs by surface: | Surface | Tool execution | Confirm before spend | | ------------- | --------------------------------------------------------------------------------------------- | ------------------------------------- | | Mobile (Rate) | In-process WDK adapters (fully on-device, private); P2P-delegate to a paired desktop optional | Confirmation sheet | | Desktop | `kaleido-mcp` (namespaced `spark_*`/`rln_*`/`arkade_*`) plus a `kaleido` CLI mirror | Confirmation dialog | | Eval / CLI | Canned stub handlers for reproducible benchmarks | Auto-approve (asserts the gate fired) | The canonical tool contract lives in core as `ToolDef[]`, with a `spend` flag that maps to `requiresConfirmation: true`. Every fund-moving tool carries this flag, the **Engine pauses and calls the host's `onConfirm`** before executing, so the model can never bypass a spend gate. The confirmation sheet gets a deterministic, voice-first readback (for example *"Send 4,800 sats to bob over Spark. Confirm?"*) built from the resolved call, not generated by the model, so a wrong unit or recipient surfaces where it can be caught. ### Per-Layer Wallet Tools | Layer | Status | Tools | | --------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Spark | Shipped | `spark_get_balance` 路 `spark_get_address` 路 `spark_create_invoice` 路 `spark_send` 馃敀 | | RLN / RGB | Shipped | `rln_get_balances` 路 `rln_get_node_info` 路 `rln_list_channels` 路 `rln_create_ln_invoice` 路 `rln_create_rgb_invoice` 路 `rln_pay_invoice` 馃敀 路 `rln_send_asset` 馃敀 | | Arkade | Shipped | `arkade_get_balance` 路 `arkade_get_address` 路 `arkade_send` 馃敀 | | Liquid | Planned, not implemented | `liquid_get_balance` 路 `liquid_create_invoice` 路 `liquid_send` 馃敀 (type-defined in the contract, no adapter yet) | Plus cross-cutting router tools: `get_balances(layer?)`, `resolve_contact(name)`, `get_price(asset?, fiat?)`, `fiat_to_sats(amount, currency)`, `get_swap_quote`/`execute_swap`, and the unified `send_payment(asset, amount, to, layer?)` that picks the rail automatically. ### KaleidoSwap Trading & LSPS1 Separate contracts for DEX trading (`kaleidoswap_get_quote`, `kaleidoswap_place_order`, `kaleidoswap_atomic_init`/`execute`/`status`) and LSP-agnostic channel orders (`lsp_get_info`, `lsp_estimate_fees`, `lsp_create_order`, `lsp_get_order`). The atomic swap chain runs as a single confirm-gated recipe (`kaleidoswapAtomicRecipe`): quote, create receive invoice, init, pay, execute. ## Skills Skills are Agent-Skills-spec playbooks (`SKILL.md` plus progressive disclosure) that scope which tools are visible and, for deterministic recipes, carry the plan itself. Bundled skills include payments, receive, per-layer routing (Spark/RLN/Arkade), atomic swaps, and a more model-leveraging merchant-discovery skill (location plus BTC Map, via pluggable embedding selectors). ## QVAC: On-Device Inference LLM, embedding, speech-to-text, and text-to-speech inference all run through the [QVAC SDK](https://www.npmjs.com/package/@qvac/sdk), locally on-device by default, or delegated to an explicitly paired, user-controlled desktop for heavier work. Published as the `@kaleidorg/mind/qvac` subpath so the SDK stays a peer dependency rather than a hard requirement of core. Memory and RAG (long-term recall, wallet-history retrieval, merchant discovery) also route through QVAC's embeddings, with near-duplicate consolidation to keep memory from bloating. ## Where It Runs | Host | Role | | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | [Rate](https://github.com/kaleidoswap/Rate) | React Native mobile wallet, with local LLM, speech-to-text, neural text-to-speech, and the hands-free voice loop | | [Desktop App](/desktop-app/getting-started/introduction) | Runs the engine as in-app chat, hosts it as a namespaced MCP and CLI (`apps/provider`), and can act as the paired inference peer for a phone | The fastest way to try it is the Desktop App. [Download the latest release](https://kaleidoswap.com/downloads) and follow the [installation guide](/desktop-app/getting-started/installation). ## Relationship to KaleidoAgent [KaleidoAgent](/ai-tools/kaleido-agent) is a separate, always-on Node.js server (Nanobot runtime, scheduling, Telegram) that predates KaleidoMind's `Engine` and has **not** been migrated onto it, it runs its own agent loop against Anthropic or OpenAI directly. The two are conceptually the same idea (an agentic loop over a tool registry with a confirm gate) implemented twice. Converging them, having KaleidoAgent host KaleidoMind's `Engine` instead of its own loop, is a known, not-yet-started integration path; until then, treat them as independent systems that both consume `kaleido-mcp`. ## Publishing & Subpaths Published from `packages/core` as `@kaleidorg/mind`, with subpaths: `./mcp` (MCP tool source helpers), `./skills` (skill loader), `./logger`, and `./qvac` (the on-device inference adapter). Companion apps: `apps/cli` (`@kaleidorg/mind-cli`) for terminal and eval use, and `apps/provider` (`@kaleidorg/mind-provider`), the Tauri desktop sidecar that the Desktop App embeds.