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 '/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 is the explicit browser-only choice for caller-supplied Whisper speech-to-text and Kokoro text-to-speech runtimes. It implements arcane-ai-provider/2, downloads nothing on import, and ships no model weights, adapter runtime assets, voices, URLs, catalog, or cloud fallback.

Capacity 4 means up to four segments synthesize at once. Segment 5 and later wait in the SDK’s FIFO queue; they are not dropped. Synthesis may finish out of order, but playback waits for earlier segments and plays exact segment order. Every TTS entrypoint automatically removes repeated same formatting marks from only the outbound speech-input copy; caller, displayed, stored, and model content stays exact.

Use ai.providerRuntime.status('tts', {execution:true}).execution to read the selected device after load. Requested auto with selected wasm identifies fallback; it is not evidence of physical GPU kernel overlap.

Durable chat and retrieval

PersistentAIChatSession.js makes chat persistence explicit. DBOPFSDocumentLibrary.js and DocumentLexicalSearch.js provide bounded document storage, caller-source evaluation, context construction, and lexical ranking without assuming a provider or copying provider runtime assets.

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.