Normalized AI

Choose the normalized surface

Provider runtime and normalized state

AIProviderRuntime.js owns admitted provider registration, configuration, lifecycle, cancellation, speech mute state, and normalized request routing. AIRuntimeState.js publishes the normalized aggregate and independent llm, stt, and tts role states. Applications should consume those state records instead of inferring readiness from a loaded module or protocol label.

Runtime AI module

AI.js provides the default AI class and named browser-speech and lifecycle constants. Import the default binding for explicit use, or load the module for its lifecycle and wait for ai-ready before reading globalThis.ai.

import AI from '/node_modules/arcane-os/runtime/arcane/modules/AI.js';

// The application supplies this runtime argument; never put its key in source.
async function sayHello(applicationRuntime) {
    const ai = new AI();
    ai.twinKey = applicationRuntime.twinKey;
    try {
        const response = await ai.fetchRequest(
            {
                messages: [{role: 'user', content: 'Hello!'}]
            }
        );
        console.log(JSON.stringify(response, null, 2));
    } catch (error) {
        console.error(error.code, error.message);
    }
}

Core Arcane.ai

globalThis.Arcane.ai is a distinct provider-neutral Core surface. Ordinary applications call profile() and chat(); Settings-only provider mutation remains separately available.

async function explainActiveModelAfterUserChoice() {
    const profile = await globalThis.Arcane.ai.profile();
    const result = await globalThis.Arcane.ai.chat({
        expectedProvider: profile.provider,
        messages: [{role: 'user', content: 'Explain the active model in one sentence.'}]
    });
    console.info(result.message.content);
}

Browser-WASM local text inference

Browser-WASM local AI is an explicit browser-only option for a caller-configured GGUF model. It packages the Wllama engine, not model weights. It neither supplies native or speech APIs nor executes returned tools. A normal cache miss can download; load({offline:true}) requires a compatible DBOPFS cache and successful Wllama loading.

Browser speech providers

Browser speech offers caller-selected Whisper and Kokoro, native browser recognition and synthesis, and TWiN Cloud TTS through arcane-ai-provider/2. Importing starts no download or speech. Local models use selected upstream assets; native voices come from the actual browser catalog and may use remote services; cloud TTS requires an application key.

Kokoro defaults to four synthesis sessions; cloud TTS defaults to four complete jobs through final audio. Further jobs wait in FIFO order. Playback preserves input order. Browser-native synthesis prepares silent descriptors and owns actual playback release; its audio-file APIs report export unavailability. Shared AI and SpeechPlayback remove repeated same formatting marks from their outbound speech-input copy; direct native provider preparation preserves its input; caller, displayed, stored, and model content stays exact.

Use ai.providerRuntime.status('tts', {execution:true}).execution to read the selected device after load. Local speech auto tries WebNN NPU, WebGPU, then WASM; an explicit backend does not fall back. Status reports successful upstream loading, not physical accelerator use for every operation.

For native Core speech, Nemotron retains recognition and speaker scope across utterance endpoints; Magpie produces ordered PCM or complete audio. Shared capture and playback uses the existing AI provider, microphone and output owners. Complete snapshots, external endpoint/drain controls and joined utterance cancellation remain separate from application-owned conversational meaning. A speech-only AI constructor passes null for both LLM service and model.

Durable chat and retrieval

PersistentAIChatSession.js makes chat persistence explicit. DBOPFSDocumentLibrary.js and DocumentLexicalSearch.js provide complete document storage, caller-source evaluation, context construction and lexical ranking. A persist:false turn participates only in its active operation and then leaves retained transcript, recurring context, durable storage and memory.

Advanced provider APIs

Arcane Ollama is provider-specific and lower-level. Some admitted applications can call Ollama chat, generate, or embed methods; diagnostics and management are more restricted, and some operations intentionally fail. Never send a renderer directly to 127.0.0.1:11434.

Availability, errors, and fallback

Feature-detect the selected normalized surface and inspect effective capabilities when a native call is unavailable. Local and cloud providers keep their documented availability and error codes. Arcane does not silently switch providers after failure.