Skip to content
svg-engine

API: ai/nlu

@mosaicoo/svg-engine/ai/nlu is the opt-in natural-language layer (headless, no Material/CDK). It turns a phrase like “draw a red circle” into an editor action: a rule-based engine matches the text against registered intents, extracts slots, and either returns ranked candidates or auto-executes the best one. An optional local-LLM layer handles requests the rules can’t.

import { NaturalLanguageService, builtinNluPlugin } from '@mosaicoo/svg-engine/ai/nlu';

The engine

Section titled “The engine”
APIDescriptionUse it to
NaturalLanguageServiceThe intent registry + matcher. registerIntent(intent) → Disposable; parse(text, ctx, opts?) returns ranked NluCandidate[]; execute(text, ctx, opts?) parses and auto-runs the top match when confident; intents/intentsCount signals.Register intents and turn text into editor actions.
builtinNluPluginA plugin (install via provideSvgEnginePlugin(builtinNluPlugin)) that auto-discovers every menu command as an intent and adds built-ins like create-shape, set-fill, move-selected, resize-selected, duplicate-selected.Get a working command vocabulary out of the box.
discoverMenuIntents(...) / discoverMenuIntentsReactive(...)Convert MenuContributionRegistry entries into intents — once, or continuously as plugins install.Expose your menus to natural language automatically.
const nlu = inject(NaturalLanguageService);
const result = await nlu.execute('desenhe um círculo vermelho', { injector });
if (!result.executed) console.log(result.rejection); // why it didn't run

Core types

Section titled “Core types”
TypeDescription
NluIntentAn intent definition: id, keywords, optional actionKeywords/slots/destructive/description, and execute(slots, ctx).
NluContextThe per-call context — carries the injector so an intent can resolve editor services.
NluCandidateA parse result: the matched intent, a confidence in [0,1], extracted slots, and the matches that explain it.
NluSlotSchemaA slot’s shape: number, color, shape, enum, string, point or gradient, with optional/default/anchor keywords.
NluParseOptionsthreshold (default 0.3) and maxResults (default 5).
NluExecuteOptionsAdds autoExecuteThreshold (default 0.7) and confirmGate (a confirmation hook — required for destructive intents).
NluExecuteResultThe outcome: executed, the candidate, alternatives, and a rejection reason (no-match, below-threshold, confirmation-declined, destructive-no-gate, execute-error, or null).
NluLanguageDetected language: pt, en or unknown.

Optional LLM layer

Section titled “Optional LLM layer”

For requests the rule-based engine can’t resolve, escalate to a chat LLM (e.g. a local Ollama server). The contract is pluggable.

APIDescription
AiChatProvider / AI_CHAT_PROVIDERThe LLM backend contract (chat(messages, opts?), isConfigured, defaultModel) and its injection token (defaults to none).
provideOllamaChat(config?)Wire up the built-in Ollama provider. Config: baseUrl, model, models.
DEFAULT_OLLAMA_BASE_URL / DEFAULT_OLLAMA_MODEL / DEFAULT_OLLAMA_MODELSDefaults: http://localhost:11434, qwen2.5:3b, and a small list of suggested Qwen models.
LlmIntentResolverServiceThe escalation layer: resolvePlan(text, ctx) asks the LLM to break a complex request into a multi-step intent plan; resolveAndExecute(text, ctx) runs it.
AiChatMessage / AiChatOptionsThe chat message (role, content) and per-call options (model, format, temperature, …).

Voice contract

Section titled “Voice contract”

ai/nlu defines the voice provider contract; the actual implementations live in ai/nlu-ui (Web Speech) and ai/nlu-voice-wasm (on-device Whisper).

APIDescription
VoiceProviderA speech-recognition provider: isSupported/listening/lastError signals, listen(lang?, options?) → transcript, stop().
VoiceEngineWhich engine to use: web-speech, whisper or auto.
VOICE_WHISPER_PROVIDERInjection token for the optional Whisper provider (defaults to none).