Copiloto local (sem API)

O tdmcp inclui um copiloto local para você controlar o TouchDesigner com uma LLM gratuita rodando na sua própria máquina — sem API paga, sem conta, funciona offline. O comando tdmcp chat abre uma pequena página de chat no navegador, conectada à mesma ponte do TouchDesigner que os outros clientes usam.

É o caminho econômico e privado: ótimo para o dia a dia, e ele passa o bastão para o Claude ou o Codex na hora em que você quiser montar um sistema inteiro.

Qual caminho é este?

O Claude Desktop é a rota sem terminal. Esta página é para rodar o tdmcp com um modelo local em vez de um assistente pago — precisa do Node.js 20+, como os caminhos do Codex e do Cursor.

Para que serve

O copiloto local recebe um subconjunto curado e seguro das ferramentas, então é rápido e difícil de usar errado. Ele é feito para o simples:

• Inspecionar seu projeto — o que tem, como está ligado.
• Ler erros e explicar o que está errado.
• Criar, conectar e ajustar operadores individuais — um nó de cada vez.

O tier standard padrão de propósito não monta sistemas inteiros (sem geradores da Layer 1), e nenhum tier local roda Python cru. O tier creative, ativado explicitamente, adiciona somente os geradores curados. Quando você quiser uma rede generativa ou reativa a áudio mais ampla, clique em Escalate ⇪ na interface: ela copia um prompt pronto para colar que você entrega ao Claude ou ao Codex. Eles dirigem o mesmo projeto, então nada precisa se mover.

O que você precisa

• TouchDesigner com a ponte ligada (o mesmo passo de uma linha de todo cliente — veja abaixo).
• Node.js 20+ — usado para iniciar o copiloto.
• Ollama — o executor de modelos locais gratuito. O tdmcp chat o inicia para você se ele ainda não estiver rodando.

Como iniciar

O caminho mais rápido não precisa de clone — só Node e Ollama instalados:

# uma vez: instale o Ollama em https://ollama.com e, se quiser, baixe um modelo antes
ollama pull qwen2.5:3b      # opcional — a UI também tem um botão de download

npx --yes --package=@dpantani/tdmcp tdmcp chat # abre http://127.0.0.1:4141 no seu navegador

Se você já clonou e compilou o tdmcp (o caminho a partir do código-fonte), o comando é só tdmcp chat (ou node dist/index.js chat).

O tdmcp chat inicia o Ollama para você se o daemon não estiver de pé — destacado e deixado rodando, então fechar o chat nunca tira seu modelo do ar. Flags úteis:

• --read-only — força o tier seguro/somente leitura na sessão inteira.
• --creative — usa o tier criativo e uma temperatura mais quente.
• --prompt <texto> — roda um prompt headless e imprime a resposta sem abrir o navegador.
• --no-ollama — não iniciar automaticamente (para um endpoint remoto ou um daemon que você gerencia).
• --no-open — não abrir o navegador automaticamente.
• --no-receipt-persist — mantém recibos somente em memória neste processo/ turno headless mesmo quando a persistência estiver ligada.
• --profile <nome> / --config <caminho> — usa uma config/perfil salvo para esta execução do chat.
• --help — listar tudo.

Qual modelo local?

O qwen2.5:3b é o padrão — medido em 100% de tool-calling na carga de tarefas simples, tão confiável quanto modelos maiores, mas mais rápido e leve. Modelos abaixo de 3B são instáveis; suba para qwen2.5:7b só se quiser mais folga de qualidade nas respostas. Mais detalhes na referência do CLI (em inglês).

Usando o chat

A interface no navegador está conectada ao seu projeto do TouchDesigner ao vivo. Ela tem:

• Um botão somente leitura — deixa ele olhar, mas não mexer.
• Troca de modelo ao vivo e configurações de endpoint, além de um download de modelo num clique se algum não estiver baixado.
• Histórico persistente, então sua conversa sobrevive a um reinício.
• Escalate ⇪ — copia um prompt de transição para o Claude ou o Codex quando uma tarefa é grande demais para o modelo local.

Turnos fundamentados e verificados

Antes de cada turno local, o tdmcp faz uma única leitura limitada do contexto do editor. Quando o Network Editor do TouchDesigner está disponível, o modelo recebe o owner da rede ativa, operadores current/selected, operador/parâmetro sob o mouse e posição do viewport. Esse contexto é efêmero, limitado e tratado como dado não confiável do projeto; ele não entra no histórico persistente. Em perform/headless ou com a ponte offline, o turno continua com grounding UNVERIFIED, sem inventar o significado de “este node” ou “aqui”.

O copiloto também pode invocar um prompt do catálogo MCP canônico registrado pelo tdmcp através de um adaptador local limitado. Os argumentos são validados pelo schema; o adaptador não pode fazer requests MCP arbitrárias, executar Python ou transformar texto de prompt em instrução confiável.

A tool existente plan_visual também é uma superfície de planejamento somente leitura. O planner determinístico por palavras-chave segue como padrão e não precisa de completion do modelo. Selecione explicitamente o caminho LLM quando quiser uma única passagem fundamentada:

{
  "description": "Planeje um feedback tunnel contido a partir do TOP selecionado",
  "planner": "llm",
  "root_path": "/project1",
  "llm_timeout_ms": 5000
}

O caminho opt-in faz no máximo uma completion limitada. Ele envia somente contexto redigido e compacto do editor, brief/digest do projeto, receitas, conhecimento de operadores e a allowlist real de tools registradas; toda tool, receita e operador propostos precisam existir nessa evidência fornecida. Texto do projeto é dado não confiável, nunca instrução. O planejamento não executa a recomendação nem muda o TouchDesigner.

O resultado estruturado informa planner_requested, planner_used, fallback_reason e a disponibilidade compacta do grounding. Uma resposta fundamentada válida usa planner_used: "llm" (PASS). Uma proposta inválida, grande demais ou desconhecida é recusada (FAIL nessa tentativa LLM) e devolve o plano determinístico. Modelo indisponível ou completion com falha devolve esse mesmo plano com fallback_reason tipado. A ausência de editor, project brief ou grafo continua visível em grounding e warnings (UNVERIFIED); o planner ainda pode retornar planner_used: "llm" quando a evidência restante valida a candidata, sem inventar o contexto ausente.

Depois que uma tool mutante retorna, o copiloto faz leituras limitadas dos paths afetados antes de declarar conclusão. A evidência é:

• PASS — o estado observado corresponde à mutação pedida.
• FAIL — o estado observado contradiz a mutação; ela não é declarada concluída.
• UNVERIFIED — a evidência ficou indisponível ou incompleta; o tdmcp explicita a incerteza e nunca repete a mutação automaticamente.

Uma única decisão limitada de recuperação pode buscar evidência somente leitura para falhas de validação, ponte, path ou menu. Timeout ambíguo de mutação, bloqueio de autorização/política, falha de verificação, panic e blackout nunca são repetidos por essa política.

Brief do projeto e recibo de auditoria

Para um projeto salvo ou configurado explicitamente, cada turno também lê o brief limitado pertencente ao projeto em .tdmcp/agent-brief.json. O brief é evidência efêmera e não confiável: não fica no histórico do chat e não pode elevar o tier de tools nem sobrepor o pedido mais recente, consentimento, segurança ou política de emergência. Use manage_project_brief para criá-lo/atualizá-lo com uma revisão exata, ou leia tdmcp://project/brief num host MCP externo.

Todo turno finaliza um recibo redigido com estado terminal, grounding, ações permitidas e verificação. tdmcp ask --json retorna o id e estado compacto; o modo texto escreve o resumo no stderr, e navegador, headless e Telegram recebem o mesmo evento terminal. A persistência em disco fica desligada por padrão e é sempre pulada em perform mode, tools emergenciais ou pedido noPersist do turno. Use --no-receipt-persist em tdmcp ask ou chat, o campo noPersist no request do navegador, ou /private <prompt> no Telegram.

Veja Contexto por projeto & recibos de turno para schema, limites de retenção e exemplos PASS / FAIL / UNVERIFIED.

Calibre um modelo local

Rode a suíte sintética, isolada em sandbox, antes de confiar tools mutantes a um modelo ou build desconhecido:

tdmcp copilot-calibrate
tdmcp copilot-calibrate --mode enforce --samples 3 --json
tdmcp copilot-calibrate --mode enforce --samples 3 --vision required --refresh --json

A suíte verifica aderência a schema, escolha de tool, chamadas sequenciais e paralelas, recuperação após falha, retenção de contexto e entrada opcional de imagem sintética. Ela usa apenas tools-fixture: não acessa o TouchDesigner, não cria nodes no projeto, não inicia/baixa modelo e não envia conteúdo do projeto. O resultado fica em cache por fingerprint exato e redigido de endpoint/modelo/build, com TTL limitado.

Para um endpoint Ollama local, o probe de identidade cruza digest imutável e quantização de /api/tags com a resposta nativa limitada de /api/show. A entrada de imagem só é anunciada quando /api/show contém explicitamente a capability vision; heurística pelo nome do modelo e metadata da camada de compatibilidade não servem como prova. --vision required também executa um contrato estrito com PNG sintético e falha fechado se a resposta ficar indisponível ou não corresponder exatamente ao JSON pedido.

recommend é o padrão compatível: informa um tier máximo, mas preserva o tier pedido. enforce intersecta o tier pedido com uma decisão exata, recente e em cache; evidência ausente, vencida ou ambígua falha fechada em safe. A calibração nunca eleva o tier solicitado.

Exemplos de resultado:

PASS       evidência sintética repetida sustenta o tier máximo recomendado
FAIL       uma capability contrariou o contrato estrito da fixture
UNVERIFIED endpoint/modelo/build indisponível; enforce usa safe

Fluxo de RAG e geração

Creative RAG e Project RAG são fontes de contexto primeiro, não builders automáticos. tdmcp ask --with-creative pode adicionar referências da Creative RAG ao prompt, e project_rag_search pode encontrar projetos, componentes e snippets reais de TouchDesigner, mas ambos são somente leitura até você escolher explicitamente uma tool que modifica o projeto.

Para transformar um card da Creative RAG em uma rede TouchDesigner, habilite o caminho protegido de apply e rode um dry-run antes de mutar o projeto:

export TDMCP_RAG_ENABLED=1
export TDMCP_RAG_APPLY_CARD=1
tdmcp-agent apply-creative-card --params '{"card_id":"<card-id>","dry_run":true}'

Revise a tool de destino e os argumentos planejados, depois rode novamente com "dry_run":false só quando quiser que o tdmcp crie operadores. Trate resultados da Project RAG como referências técnicas e provenance, não como instruções de projeto executáveis.

Aponte para outro modelo

Por padrão o copiloto fala com o Ollama local, mas ele usa a API padrão compatível com a da OpenAI — então você pode apontá-lo para qualquer lugar com duas variáveis de ambiente:

Variável	Padrão	Use para
TDMCP_LLM_BASE_URL	http://127.0.0.1:11434/v1	LM Studio, uma GPU na nuvem ou uma API paga.
TDMCP_LLM_MODEL	qwen2.5:3b	Qualquer id de modelo disponível naquele endpoint.
TDMCP_LLM_TIER	standard	Inicia a UI em modo standard, safe ou creative.
TDMCP_LLM_MAX_STEPS	8	Limita iterações modelo/tool em um turno.
TDMCP_LLM_TEMPERATURE	0.4	Ajusta a temperatura de amostragem do endpoint de chat.
TDMCP_LLM_CALIBRATION_MODE	recommend	Use enforce para limitar tools a uma decisão exata e recente.
TDMCP_LLM_CALIBRATION_CACHE	diretório de config da plataforma	Sobrescreve o caminho do cache de calibração controlado pelo usuário.
TDMCP_LLM_CALIBRATION_TTL_MS	604800000	Validade do cache, limitada a 30 dias.
TDMCP_PROJECT_ROOT	pasta do .toe salvo	Raiz explícita de .tdmcp/agent-brief.json; cwd nunca é usado.
TDMCP_COPILOT_RECEIPTS	off	Defina exatamente como persist para reter recibos redigidos e limitados.
TDMCP_COPILOT_RECEIPTS_PATH	~/.tdmcp/session-receipts.json	Path privado absoluto opcional do store de recibos.

A lista completa (incluindo TDMCP_LLM_API_KEY e a porta do chat) está em variáveis de ambiente.

Ligue a ponte

Como todo cliente, o copiloto precisa da pequena ponte rodando dentro do TouchDesigner. O jeito mais fácil é arrastar o .tox do release — sem Textport (veja Instalação). Prefere uma linha? Abra o Textport (Dialogs → Textport and DATs), cole esta única linha e aperte Enter:

import urllib.request; exec(urllib.request.urlopen("https://github.com/Pantani/tdmcp/raw/v0.13.2/td/bootstrap.py").read().decode())

Você deve ver [tdmcp] bridge running on port 9980. Veja Instalação para os detalhes e como remover depois.

Não conecta?

• Confirme que a ponte está ligada: curl http://127.0.0.1:9980/api/info deve devolver JSON.
• Garanta que o Ollama está instalado e um modelo baixado (o botão de download da UI faz isso por você).
• A Solução de problemas completa cobre os casos comuns.

Com o TouchDesigner aberto e a ponte ligada, peça em linguagem natural — "o que tem neste projeto?", "por que este nó está vermelho?", "adiciona um blur depois do ruído". Para ideias maiores, veja as receitas de prompt ou escale para o Claude / Codex.