Pular para o conteúdo
svg-engine

API: ai/nlu

@mosaicoo/svg-engine/ai/nlu é a camada de linguagem natural opt-in (headless, sem Material/CDK). Ela transforma uma frase como “desenhe um círculo vermelho” numa ação do editor: um engine baseado em regras casa o texto com intents registrados, extrai slots e retorna candidatos ranqueados ou auto-executa o melhor. Uma camada de LLM local opcional cuida do que as regras não dão conta.

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

O engine

Seção intitulada “O engine”
APIDescriçãoUse para
NaturalLanguageServiceO registry de intents + matcher. registerIntent(intent) → Disposable; parse(text, ctx, opts?) retorna NluCandidate[] ranqueados; execute(text, ctx, opts?) faz parse e auto-executa o melhor quando confiante; signals intents/intentsCount.Registrar intents e transformar texto em ações do editor.
builtinNluPluginUm plugin (instale via provideSvgEnginePlugin(builtinNluPlugin)) que auto-descobre todo comando de menu como intent e adiciona built-ins como create-shape, set-fill, move-selected, resize-selected, duplicate-selected.Ter um vocabulário de comandos funcional de imediato.
discoverMenuIntents(...) / discoverMenuIntentsReactive(...)Convertem entradas do MenuContributionRegistry em intents — uma vez, ou continuamente conforme plugins são instalados.Expor seus menus à linguagem natural automaticamente.
const nlu = inject(NaturalLanguageService);
const result = await nlu.execute('desenhe um círculo vermelho', { injector });
if (!result.executed) console.log(result.rejection); // por que não rodou

Tipos centrais

Seção intitulada “Tipos centrais”
TipoDescrição
NluIntentDefinição de intent: id, keywords, opcionais actionKeywords/slots/destructive/description, e execute(slots, ctx).
NluContextO contexto por-chamada — carrega o injector para o intent resolver serviços do editor.
NluCandidateUm resultado de parse: o intent casado, uma confidence em [0,1], os slots extraídos e os matches que o explicam.
NluSlotSchemaA forma de um slot: number, color, shape, enum, string, point ou gradient, com optional/default/anchor keywords.
NluParseOptionsthreshold (padrão 0.3) e maxResults (padrão 5).
NluExecuteOptionsAdiciona autoExecuteThreshold (padrão 0.7) e confirmGate (hook de confirmação — obrigatório para intents destructive).
NluExecuteResultO resultado: executed, o candidate, alternatives, e um motivo de rejection (no-match, below-threshold, confirmation-declined, destructive-no-gate, execute-error ou null).
NluLanguageIdioma detectado: pt, en ou unknown.

Camada LLM opcional

Seção intitulada “Camada LLM opcional”

Para pedidos que o engine de regras não resolve, escale para um LLM de chat (ex.: um servidor Ollama local). O contrato é plugável.

APIDescrição
AiChatProvider / AI_CHAT_PROVIDERO contrato do backend LLM (chat(messages, opts?), isConfigured, defaultModel) e seu token de injeção (padrão nenhum).
provideOllamaChat(config?)Conecta o provider Ollama built-in. Config: baseUrl, model, models.
DEFAULT_OLLAMA_BASE_URL / DEFAULT_OLLAMA_MODEL / DEFAULT_OLLAMA_MODELSPadrões: http://localhost:11434, qwen2.5:3b, e uma pequena lista de modelos Qwen sugeridos.
LlmIntentResolverServiceA camada de escalada: resolvePlan(text, ctx) pede ao LLM para quebrar um pedido complexo num plano de intents em múltiplos passos; resolveAndExecute(text, ctx) o executa.
AiChatMessage / AiChatOptionsA mensagem de chat (role, content) e as opções por-chamada (model, format, temperature, …).

Contrato de voz

Seção intitulada “Contrato de voz”

O ai/nlu define o contrato do provider de voz; as implementações de fato vivem em ai/nlu-ui (Web Speech) e ai/nlu-voice-wasm (Whisper on-device).

APIDescrição
VoiceProviderUm provider de reconhecimento de fala: signals isSupported/listening/lastError, listen(lang?, options?) → transcrição, stop().
VoiceEngineQual engine usar: web-speech, whisper ou auto.
VOICE_WHISPER_PROVIDERToken de injeção do provider Whisper opcional (padrão nenhum).