Smart AI Bridge

Smart AI Bridge v2.15.0

Orquestração multi-IA orientada por configuração para Claude Code. Adicione qualquer provedor compatível com OpenAI, roteie de forma inteligente e deixe várias IAs colaborarem através do sistema de conselho.

O Que Ele Faz

Smart AI Bridge é um servidor MCP que fica entre o Claude Code e seus backends de IA. Ele fornece 17 ferramentas para operações de arquivo que economizam tokens, fluxos de trabalho multi-IA, verificações de qualidade de código e roteamento inteligente — tudo configurado através de um único arquivo JSON.

• Qualquer provedor compatível com OpenAI funciona. Modelos locais (vLLM, LM Studio, Ollama), APIs em nuvem ou uma mistura de ambos. Os presets incluídos cobrem provedores comuns, mas adicionar o seu próprio é apenas uma entrada de configuração.
• Roteamento inteligente seleciona o melhor backend por tarefa usando um sistema de 4 níveis: seleção forçada, preferências aprendidas, heurísticas baseadas em regras e fallback baseado em saúde.
• Sistema de conselho consulta múltiplos backends no mesmo prompt e retorna todas as respostas para o Claude sintetizar. Estratégias configuráveis (paralela, sequencial, debate, fallback) por tópico.
• Painel web para gerenciar backends e configuração do conselho sem editar arquivos JSON.

Como Funciona

A ideia central: Claude nunca lê o arquivo

A maior parte do contexto do Claude em uma tarefa de codificação é gasta com o conteúdo dos arquivos. O Smart AI Bridge entrega esse trabalho a outro modelo e retorna apenas as conclusões, então o contexto caro fica livre para raciocínio.

sequenceDiagram
    accTitle: How Smart AI Bridge saves tokens
    accDescr: Claude Code calls analyze_file. Smart AI Bridge reads the file and sends its contents to a backend model. The backend returns a structured analysis, and only that analysis is returned to Claude. The file contents never enter Claude's context.
    participant C as Claude Code
    participant S as Smart AI Bridge
    participant F as Your files
    participant B as Backend<br/>(local or cloud)

    C->>S: analyze_file({ filePath, question })
    S->>F: read the file
    S->>B: file contents + question
    B-->>S: structured analysis
    S-->>C: { summary, findings[], confidence, tokens_saved }

    Note over C,S: The file contents never enter Claude's context.<br/>tokens_saved is measured from the real bytes,<br/>not estimated.

modify_file funciona da mesma forma, mas retorna um diff; explore retorna evidências file:line correspondentes; batch_analyze faz isso através de um glob. Cada um desses relata um valor tokens_saved calculado a partir dos caracteres reais lidos versus a resposta real retornada.

Escolhendo um backend: o roteador de 4 níveis

Toda chamada que não nomeia um backend passa pela mesma decisão, em ordem. O primeiro nível que produz um backend saudável vence.

flowchart TD
    accTitle: The four-tier backend routing decision
    accDescr: A tool call is routed in four ordered tiers. Tier 1 uses an explicitly named backend. Otherwise Tier 2 uses a learned preference above 0.7 confidence if that backend is healthy. Otherwise Tier 3 applies complexity and task-type rules. Otherwise Tier 4 takes the first healthy backend in the fallback chain.
    A[Tool call] --> B{"backend named<br/>and not 'auto'?"}
    B -- yes --> T1["<b>Tier 1 · Forced</b><br/>use it as given"]
    B -- no --> C{"learned preference<br/>above 0.7 confidence<br/><i>and</i> that backend healthy?"}
    C -- yes --> T2["<b>Tier 2 · Learned</b><br/>from past outcomes"]
    C -- no --> D{"a rule matches on<br/>complexity / task type?"}
    D -- yes --> T3["<b>Tier 3 · Rules</b><br/>heuristic match"]
    D -- no --> T4["<b>Tier 4 · Fallback</b><br/>first healthy backend<br/>in the chain"]

Uma preferência aprendida que é confiante, mas aponta para um backend não saudável, cai para o Nível 3 em vez de ser usada. Falhas de saúde abrem um disjuntor, então um provedor que está fora do ar é pulado em vez de tentado novamente até dar timeout.

Perguntando a vários modelos ao mesmo tempo: o conselho

council envia um prompt para múltiplos backends e retorna cada resposta para o Claude sintetizar. Ele não vota nem escolhe um vencedor — a discordância entre modelos é o sinal, então ela é preservada em vez de ser diluída pela média.

flowchart LR
    accTitle: Council strategies
    accDescr: One prompt is dispatched by a configurable strategy. Parallel queries all backends at once. Sequential runs them in order, each seeing the previous answer. Debate has models respond to each other. Fallback tries the next backend only if the previous failed. Every response is returned to Claude to synthesize.
    Q[One prompt] --> R{strategy}
    R -->|parallel| P[All backends at once]
    R -->|sequential| S[One after another,<br/>each sees the last]
    R -->|debate| D[Models respond<br/>to each other]
    R -->|fallback| F[Next only if<br/>the previous failed]
    P & S & D & F --> A[All responses returned<br/>to Claude to synthesize]

A estratégia é configurável por tópico. Veja docs/COUNCIL.md.

Início Rápido

Não há pacote npm — instale clonando. Requer Node.js >= 18.

1. Clone e instale

git clone https://github.com/Platano78/smart-ai-bridge.git
cd smart-ai-bridge
npm install

Confirme que a instalação está sólida antes de conectá-la a qualquer coisa:

npm test          # expect: all tests pass, 0 failures

2. Configure pelo menos um backend

O servidor inicia e lista todas as 17 ferramentas sem nenhuma chave de API — você só precisa de um backend quando realmente chamar um. Você precisa de um destes:

• um servidor local compatível com OpenAI (llama.cpp, vLLM, LM Studio, Ollama) — descoberto automaticamente em portas comuns, sem chave necessária; ou
• uma chave de API em nuvem de qualquer provedor suportado.

# Set whichever apply -- one is enough
export NVIDIA_API_KEY="your-key"
export OPENAI_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
export GROQ_API_KEY="your-key"

As definições de backend ficam em src/config/backends.json; veja CONFIGURATION.md para a referência completa. Uma chave ausente nunca é um erro — a auditoria de prontidão na inicialização relata tais backends como cannot verify, não como quebrados.

3. Registre com seu cliente MCP

Use um caminho absoluto para src/server.js. Caminhos relativos dependem do cliente honrar cwd, o que nem todo cliente faz.

Claude Code — copie .mcp.json.example para .mcp.json no seu projeto, ou adicione às suas configurações MCP:

{
  "mcpServers": {
    "smart-ai-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/smart-ai-bridge/src/server.js"],
      "env": {
        "NVIDIA_API_KEY": "your-key"
      }
    }
  }
}

Claude Desktop — mesmo bloco, mesclado em claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Qualquer outro cliente MCP — ele fala MCP via stdio. Execute node /absolute/path/src/server.js e fale JSON-RPC com ele. Diagnósticos vão para stderr; stdout carrega apenas tráfego de protocolo.

4. Reinicie o cliente e verifique

Todas as 17 ferramentas aparecem após uma reinicialização. Verifique com uma chamada que não precisa de backend:

@get_analytics({})

Para verificar um backend que você realmente configurou, nomeie-o explicitamente — check_backend_health relata local como crítico quando nenhum modelo local está rodando, o que é esperado em uma configuração somente em nuvem e não significa que a instalação falhou:

@check_backend_health({ "backend": "auto" })

Atualizando uma instalação existente

cd /path/to/smart-ai-bridge
git pull origin main
npm install        # only needed when dependencies changed

Em seguida, reinicie seu cliente MCP (no Claude Code, /mcp reconecta sem uma reinicialização completa).

Ferramentas (17)

Operações de Arquivo que Economizam Tokens

Ferramenta	Descrição
analyze_file	Backend lê e analisa arquivos, retorna descobertas estruturadas
modify_file	Backend aplica edições em linguagem natural, retorna diff
batch_analyze	Analisa múltiplos arquivos via padrões glob; grepFilter estreita por conteúdo primeiro, singlePass responde em uma chamada
batch_modify	Aplica as mesmas instruções em múltiplos arquivos
generate_file	Gera código a partir de uma especificação em linguagem natural
explore	Responde perguntas sobre o codebase usando busca inteligente

Todas exceto generate_file retornam um campo tokens_saved medido para aquela chamada específica: os caracteres de conteúdo de arquivo que o backend leu em seu nome, menos os caracteres da resposta devolvida. Ambos os lados são medidos a partir dos dados reais em vez de assumidos, então o valor reflete o que realmente aconteceu naquela chamada — embora a conversão caractere-para-token (~4 caracteres por token) seja ela própria aproximada, então trate o resultado como um bom indicador em vez de uma contagem exata de tokens. Varia enormemente com o tamanho do arquivo e comprimento da resposta: um arquivo pequeno pode não economizar nada. Não publicamos nenhuma porcentagem de destaque porque não medimos uma que pudéssemos defender.

Fluxos de Trabalho Multi-IA

Ferramenta	Descrição
ask	Roteamento inteligente com seleção automática ou forçada de backend
council	Consenso multi-IA entre backends configuráveis
dual_iterate	Loop de gerar, revisar, corrigir entre dois backends
parallel_agents	Fluxo de trabalho TDD com decomposição e portões de qualidade
spawn_subagent	Agentes de IA especializados (10 papéis incluindo TDD)

Qualidade de Código

Ferramenta	Descrição
review	Revisão de segurança, desempenho e qualidade
refactor	Refatoração entre arquivos com atualização de referências

Infraestrutura

Ferramenta	Descrição
check_backend_health	Diagnósticos de saúde para backends específicos
backup_restore	Gerenciamento de backups com carimbo de data/hora
write_files_atomic	Escritas atômicas multi-arquivo com backup
get_analytics	Análise de uso e recomendações de otimização

Roteamento Inteligente

O roteador seleciona backends usando um sistema de prioridade de 4 níveis:

1. Forçado — seleção explícita de backend (model="my_backend")
2. Aprendizado — preferências aprendidas de resultados passados (confiança >0.7)
3. Regras — heurísticas de complexidade e tipo de tarefa
4. Fallback — fallback baseado em saúde através da cadeia de prioridade

Quando um backend resolvido falha — um que o roteador escolheu, porque você passou backend: "auto" ou deixou uma regra de roteamento escolher — a solicitação automaticamente cai para o próximo backend saudável na cadeia.

Um backend que você nomeou explicitamente não faz cascata. Ele recebe uma tentativa, e se essa falhar você recebe um erro dizendo isso, distinguindo "sua pista foi tentada e falhou" de "sua pista não pôde ser tentada de forma alguma". Isso é deliberado: as chaves de API são suas, e redirecionar silenciosamente uma solicitação que você fixou em uma pista pode gastar seu crédito em pistas que você nunca pediu. Passe backend: "auto" quando quiser a cadeia.

Disjuntores protegem cada backend (5 falhas consecutivas acionam um resfriamento de 30 segundos).

Nomes de Backend

Existem duas camadas de nomenclatura de backend, e ambas são intencionais:

• Nomes amigáveis são o que você passa para as ferramentas (ex.: backend: "glm" ou model="groq"). São aliases estáveis e neutros em relação ao provedor.
• Nomes internos são os identificadores de registro/configuração usados em src/config/backends.json e análises.

Os presets mapeiam da seguinte forma:

Nome amigável	Nome interno	Tipo de adaptador
local	local	local
deepseek	nvidia_deepseek	nvidia_deepseek
glm	nvidia_glm	nvidia_glm
gemini	gemini	gemini
groq	groq_llama	groq

Removidos: nvidia_qwen / qwen3. A pista especialista em código da NVIDIA serviu um modelo Qwen. A NVIDIA desde então a aposentou, e seu catálogo agora lista nenhum modelo Qwen de qualquer tipo — então os nomes foram removidos completamente em vez de mantidos como aliases apontando para uma pista com nome diferente. nvidia_qwen e qwen3 não resolvem mais para nada.

Use nvidia_glm (alias amigável: glm). Se você tem um force_backend: "nvidia_qwen" or a config carrying "type": "nvidia_qwen", change it to nvidia_glm salvo.

Isso não afeta modelos Qwen que você executa localmente. A ponte ainda os detecta no seu próprio roteador e aplica tratamento específico para Qwen (inferência de capacidade, tokens FIM, supressão de raciocínio) — isso não tem nada a ver com a pista aposentada da NVIDIA.

O backend compatível com OpenAI é enviado sob o nome interno openai_chatgpt (tipo de adaptador openai) e é alcançado através de roteamento inteligente em vez de um alias amigável. Para a ferramenta ask, openai é aceito como um alias de compatibilidade para o backend compatível com OpenAI configurado. Backends personalizados que você adiciona via configuração usam seu campo name diretamente como o nome interno.

Deriva de Backend e Aposentadoria de Modelo

Provedores aposentam modelos sem aviso, e a falha é silenciosa até que uma solicitação falhe. Duas coisas capturam isso:

Uma auditoria de prontidão na inicialização. Ela verifica o modelo de cada backend configurado contra o catálogo do provedor e imprime descobertas no stderr. Ela roda apenas depois que o handshake MCP é concluído e nunca é aguardada, então não pode atrasar ou abortar a inicialização. Desative-a com SAB_DISABLE_READINESS_AUDIT=true.

Uma sonda sob demanda que envia a cada backend configurado uma conclusão real:

npm run audit:backends            # human-readable table
npm run audit:backends -- --json  # machine-readable

Uma conclusão real é a única verificação confiável — ids de modelo aparecem na listagem /v1/models de um provedor que ainda retornam 404 para uma determinada conta. Backends são classificados OK, RETIRED, TRANSIENT, ERROR, NO_MODEL ou NO_KEY. Ela sai com código não-zero apenas em RETIRED, ERROR ou NO_MODEL, então pode servir de portão para CI.

Um backend sem chave de API nunca é relatado como quebrado. Você fornece suas próprias chaves e a maioria das configurações usa um único provedor, então uma chave não definida relata como cannot verify — <VAR> not set e não falha a execução. O backend local é verificado apenas por acessibilidade, nunca por catálogo: seu "model": "dynamic" configurado é um identificador, não um id de catálogo.

Quando um modelo foi aposentado, o erro resultante diz isso explicitamente — nomeando o backend, o modelo, o texto de fim de vida do provedor e candidatos de substituição ao vivo — em vez de aparecer como uma falha HTTP genérica. Aposentadoria é um erro de configuração, então abre o disjuntor imediatamente em vez de ser tentada novamente; saturação (429/5xx) e falhas de autenticação (401) são deliberadamente não tratadas como aposentadoria.

Confiabilidade de Resposta (v2.4.0)

Todos os handlers usam um pipeline de resposta unificado (extractResponseText) que lida corretamente com todas as formas conhecidas de resposta de LLM — strings brutas, formatos de chat/completion da OpenAI, reasoning_content de modelos de pensamento, partes de conteúdo de array e candidatos Gemini. Saída repetitiva de modelos locais é automaticamente colapsada, e descobertas de análise são deduplicadas e limitadas.

Integridade de Escrita

fs.writeFile resolver não garante que os bytes no disco correspondam ao que foi solicitado — gravações curtas ou parciais, ENOSPC, codificação corrompida ou um gravador concorrente sobrescrevendo o arquivo entre a gravação e o retorno deixam o conteúdo do disco divergente do conteúdo pretendido, enquanto a chamada de gravação em si resolve de forma limpa.

Todo caminho que grava conteúdo que você considera importante lê de volta e compara antes de relatar sucesso:

Caminho	O que é verificado
modify_file gravação automática	arquivo modificado, além do backup que ele faz primeiro
generate_file gravação automática	arquivo gerado e seu arquivo de testes gerado
write_files_atomic write	cada arquivo gravado, além de cada backup
write_files_atomic append	arquivo cresceu exatamente pelo comprimento anexado e termina exatamente com esses bytes
write_files_atomic rollback	cada arquivo restaurado (o backup só é desvinculado após a restauração ser confirmada)
batch_modify	modificações (via modify_file) e seu rollback restaura
parallel_agents	cada arquivo de código gerado
backup_restore	o backup, o snapshot pré-restauração e a própria restauração

Uma incompatibilidade gera WRITE_VERIFY_MISMATCH — nomeando o arquivo, o comprimento esperado vs. real e a primeira linha divergente — em vez de relatar success: true sobre um arquivo corrompido.

Os caminhos de recuperação recebem o mesmo tratamento deliberadamente: um backup que falhou silenciosamente é pior do que nenhum backup, porque um rollback posterior restauraria bytes corrompidos sobre o original.

Não verificado, por design: artefatos de execução internos e arquivos de estado que são registros em vez de entregáveis — parallel_agents' decomposed.json/results.json/quality-*.json/synthesis.json, backup_restore's .meta.json sidecar, o armazenamento de padrões e os threads de conversa.

Sistema de Conselho

O conselho consulta múltiplos backends no mesmo prompt e retorna todas as respostas para Claude sintetizar. Tópicos como coding, architecture e security mapeiam cada um para um conjunto de backends e uma estratégia (paralela, sequencial, debate ou fallback).

Veja docs/COUNCIL.md para documentação completa.

Painel

Um painel web opcional fornece interface para gerenciamento de backends (ativar/desativar, prioridades, verificações de saúde) e configuração do conselho (estratégias, mapeamento de tópicos).

Veja docs/DASHBOARD.md para configuração e referência da API.

SmartCrusher (Compressão de Resultados de Ferramentas)

Resultados grandes de ferramentas — análises longas de arquivos, respostas do conselho, saídas em lote — podem preencher rapidamente a janela de contexto de Claude. O SmartCrusher reduz arrays superdimensionados antes da serialização usando uma estratégia de manter/descartar ponderada por saliência, inserindo uma linha sentinela para que Claude saiba que os dados foram descarregados.

Desativado por padrão. Ative somente após executar a avaliação de fidelidade contra seu próprio modelo local.

Ativar

# One-time env override (no config edit needed)
SAB_COMPRESSION_ENABLED=true node src/server.js

# Or permanently in src/config/backends.json:
# "compression": { "enabled": true }

Avaliação de Fidelidade (executar antes de ativar)

A avaliação verifica se respostas comprimidas preservam a precisão factual em comparação com os originais. Requer uma API local compatível com OpenAI — use qualquer modelo que você normalmente executa:

RUN_CRUSH_EVAL=1 \
  CRUSH_EVAL_BASE_URL=http://127.0.0.1:<port>/v1 \
  CRUSH_EVAL_MODEL=<your-model-id> \
  npx vitest run tests/compression/probeFidelity.test.js

Verifique a saída para original=N/15 vs crushed=M/15 por dimensão. Se as pontuações comprimidas caírem mais de 2 pontos em qualquer dimensão, deixe a compressão desativada — o modelo avalia de forma diferente da configuração de referência.

Adicionando um Backend

Via Painel (recomendado): Inicie o servidor com SAB_DASHBOARD=true, então use a interface web em http://localhost:3456 (substitua com SAB_DASHBOARD_PORT) para adicionar, remover, ativar/desativar e re-priorizar backends sem editar JSON. O painel também permite definir/limpar uma chave de API por backend (armazenada no data/backends-secrets.json ignorado pelo git, modo 0600 — nunca gravado no src/config/backends.json rastreado); uma chave armazenada entra em vigor imediatamente, sem necessidade de reinicialização, e supera o fallback process.env do backend.

O painel vincula-se a 127.0.0.1 apenas por padrão — não tem autenticação, portanto não deve ser acessível fora da máquina. Substitua com SAB_DASHBOARD_HOST se precisar que seja acessível em outro lugar; um host não-loopback imprime um aviso na inicialização nomeando o risco.

Via Arquivo de Configuração: Qualquer provedor compatível com OpenAI pode ser adicionado como uma entrada de configuração em src/config/backends.json:

{
  "name": "my_provider",
  "type": "openai",
  "endpoint": "https://api.my-provider.com/v1",
  "model": "my-model",
  "apiKeyEnvVar": "MY_PROVIDER_API_KEY",
  "maxTokens": 8192,
  "priority": 7,
  "enabled": true
}

Veja EXTENDING.md para detalhes sobre adicionar tipos de adaptadores personalizados.

Documentação

Documento	Descrição
AGENTS.md	Contrato de instalação/execução para agentes de IA e harnesses de agentes, além de regras do repositório
CHANGELOG.md	Histórico de versões
CONFIGURATION.md	Referência completa de configuração
EXTENDING.md	Adicionando backends, handlers e ferramentas
EXAMPLES.md	Exemplos de uso
docs/DASHBOARD.md	Configuração do painel e API
docs/COUNCIL.md	Detalhes do sistema de conselho

Requisitos

• Node.js >= 18.0.0
• Pelo menos um backend configurado (modelo local ou chave de API em nuvem)
• Claude Code ou Claude Desktop para integração MCP

Testes

npm test              # Run the unit + integration suite (Vitest)
npm run test:watch    # Watch mode
npm run test:bench    # Performance benchmarks (25 benchmarks, 6 categories)
npm run audit:backends # Probe every configured backend with a real completion

# SmartCrusher fidelity eval (opt-in, requires a running local model):
RUN_CRUSH_EVAL=1 \
  CRUSH_EVAL_BASE_URL=http://127.0.0.1:<port>/v1 \
  CRUSH_EVAL_MODEL=<your-model-id> \
  npx vitest run tests/compression/probeFidelity.test.js

Notas de Segurança

• Nunca comprometa chaves de API no controle de versão. Use exclusivamente variáveis de ambiente.
• Os exemplos de configuração do Claude Code acima usam valores de espaço reservado — substitua-os por suas chaves reais ou referencie um arquivo .env.
• Gire imediatamente qualquer chave vazada acidentalmente.

Modelo de Ameaças

Smart AI Bridge é um servidor MCP local confiável. Ele é projetado para rodar como um subprocesso stdio de um único cliente que você controla (Claude Code ou Claude Desktop) em sua própria máquina, e assume que esse cliente é confiável.

Dentro desse limite:

• As ferramentas de arquivo têm acesso total ao sistema de arquivos por design. write_files_atomic, modify_file, backup_restore e as ferramentas de leitura/análise operam em quaisquer caminhos que o cliente chamador fornecer. Elas não são isoladas em uma raiz de projeto. safeReadFile resolve caminhos e rejeita bytes nulos (defesa contra truques de injeção de caminho), mas não confina o acesso a um espaço de trabalho.
• A validação de argumentos acontece no limite da ferramenta. Chamadas de ferramentas são validadas contra o JSON Schema de cada ferramenta (via Ajv) antes do despacho; chamadas malformadas são rejeitadas com um erro estruturado. Isso protege contra entrada malformada, não contra um cliente hostil.
• Chamadas de ferramentas são executadas com os privilégios do processo do servidor. Execute-o como seu usuário normal, não como root.

Essa postura é apropriada para o caso de uso pretendido de agente local de usuário único. Não é adequada para expor o servidor a chamadores não confiáveis ou multi-tenant pela rede. Se você precisar disso, coloque um proxy autenticador na frente e adicione confinamento de raiz de espaço de trabalho aos handlers de arquivo primeiro — nenhum dos dois é fornecido aqui.

Licença

Apache-2.0