AI Counsel

Servidor MCP de consenso deliberativo real, onde modelos de IA debatem e refinam posições em múltiplas rodadas.

GitHub

Experimente este MCPPatrocinado

Documentação

AI Counsel Logo

AI Counsel

Servidor MCP de consenso deliberativo verdadeiro, onde modelos de IA debatem e refinam posições em múltiplas rodadas.

🎬 Veja em Ação

Debate de Modelos na Nuvem (Claude Sonnet, GPT-5.1 Codex, Gemini):

mcp__ai-counsel__deliberate({
  question: "Should we use REST or GraphQL for our new API?",
  participants: [
    {cli: "claude", model: "claude-sonnet-4-5-20250929"},
    {cli: "codex", model: "gpt-5.2-codex"},
    {cli: "gemini", model: "gemini-2.5-pro"}
  ],
  mode: "conference",
  rounds: 3
})

Resultado: Convergiu para arquitetura híbrida (confiança de 0,82-0,95) • Ver transcrição completa

Debate de Modelos Locais (100% privado, zero custos de API):

mcp__ai-counsel__deliberate({
  question: "Should we prioritize code quality or delivery speed?",
  participants: [
    {cli: "ollama", model: "llama3.1:8b"},
    {cli: "ollama", model: "mistral:7b"},
    {cli: "ollama", model: "deepseek-r1:8b"}
  ],
  mode: "conference",
  rounds: 2
})

Resultado: 2 modelos mudaram de posição após o Debate da Rodada 1 • Ver transcrição completa

O Que Torna Isso Diferente

AI Counsel possibilita CONSENSO DELIBERATIVO VERDADEIRO, onde os modelos veem as respostas uns dos outros e refinam posições em múltiplas rodadas:

Modelos participam de debate real (veem e respondem uns aos outros)
Convergência em múltiplas rodadas com votação e níveis de confiança
Trilha de auditoria completa com resumos gerados por IA
Parada antecipada automática quando o consenso é alcançado (economiza custos de API)

Recursos

🎯 Dois Modos: quick (rodada única) ou conference (debate em múltiplas rodadas)
🤖 Adaptadores Mistos: Ferramentas CLI (claude, codex, droid, gemini) + serviços HTTP (ollama, lmstudio, openrouter, nebius)
⚡ Auto-Convergência: Para quando as opiniões se estabilizam (economiza custos de API)
🗳️ Votação Estruturada: Modelos votam com níveis de confiança e justificativas
🧮 Agrupamento Semântico: Opções de voto semelhantes são mescladas automaticamente (similaridade de 0,70+)
🎛️ Parada Controlada pelo Modelo: Modelos decidem quando parar de deliberar
🔬 Deliberação Baseada em Evidências: Modelos podem ler arquivos, pesquisar código, listar arquivos e executar comandos para fundamentar decisões na realidade
💰 Suporte a Modelos Locais: Zero custos de API com Ollama, LM Studio, llamacpp
🔐 Privacidade de Dados: Mantenha todos os dados on-premises com modelos auto-hospedados
🧠 Injeção de Contexto: Encontra automaticamente debates passados semelhantes e injeta contexto para convergência mais rápida
🔍 Busca Semântica: Consulte decisões passadas com a ferramenta query_decisions (encontra contradições, rastreia evolução, analisa padrões)
🛡️ Tolerante a Falhas: Falhas individuais de adaptadores não interrompem a deliberação
📝 Transcrições Completas: Exportações em Markdown com resumos gerados por IA

Início Rápido

Comece a usar em minutos:

Instale – siga os comandos em Instalação para clonar o repositório, criar um virtualenv e instalar os requisitos.
Configure – configure seu cliente MCP usando o exemplo .mcp.json em Configurar no Claude Code.
Execute – inicie o servidor com python server.py e acione a ferramenta deliberate usando os exemplos em Uso.

Experimente uma Deliberação:

// Mix local + cloud models, zero API costs for local models
mcp__ai-counsel__deliberate({
  question: "Should we add unit tests to new features?",
  participants: [
    {cli: "ollama", model: "llama2"},           // Local
    {cli: "lmstudio", model: "mistral"},        // Local
    {cli: "claude", model: "sonnet"}            // Cloud
  ],
  mode: "quick"
})

⚠️ O Tamanho do Modelo Importa para Deliberações

Recomendado: Use modelos de 7B-8B+ parâmetros (Llama-3-8B, Mistral-7B, Qwen-2.5-7B) para saída estruturada confiável e formatação de votos.

Não Recomendado: Modelos abaixo de 3B parâmetros (ex.: Llama-3.2-1B) podem ter dificuldade com instruções complexas e produzir votos inválidos.

Modelos Disponíveis: claude (opus 4.5, sonnet, haiku), codex (gpt-5.2-codex, gpt-5.1-codex-max, gpt-5.1-codex-mini, gpt-5.2), droid, gemini, adaptadores HTTP (ollama, lmstudio, openrouter). Consulte Referência de Modelos CLI para detalhes completos.

🧠 Controle de Esforço de Raciocínio

Controle a profundidade de raciocínio por participante para adaptadores codex e droid:
participants: [
  {cli: "codex", model: "gpt-5.2-codex", reasoning_effort: "high"},    // Raciocínio profundo
  {cli: "droid", model: "gpt-5.1-codex-max", reasoning_effort: "low"}   // Resposta rápida
]
Codex: none, minimal, low, medium, high, xhigh

Droid: off, low, medium, high

Padrões de configuração definidos em config.yaml, substituições por participante em tempo de execução

Para escolhas de modelos e fluxo do seletor, consulte Registro de Modelos e Seletor.

Instalação

Pré-requisitos

Python 3.11+: python3 --version
Pelo menos uma ferramenta de IA (opcional - adaptadores HTTP funcionam sem CLI):
- Claude CLI: https://docs.claude.com/en/docs/claude-code/setup
- Codex CLI: https://github.com/openai/codex
- Droid CLI: https://github.com/Factory-AI/factory
- Gemini CLI: https://github.com/google-gemini/gemini-cli

Configuração

git clone https://github.com/blueman82/ai-counsel.git
cd ai-counsel
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux; Windows: .venv\Scripts\activate
pip install -r requirements.txt
python3 -m pytest tests/unit -v  # Verify installation

✅ Pronto para usar! O servidor inclui dependências principais além de backends de convergência opcionais (scikit-learn, sentence-transformers) para melhor precisão.

Configuração

Edite config.yaml para configurar adaptadores e definições:

adapters:
  claude:
    type: cli
    command: "claude"
    args: ["-p", "--model", "{model}", "--settings", "{\"disableAllHooks\": true}", "{prompt}"]
    timeout: 300

  ollama:
    type: http
    base_url: "http://localhost:11434"
    timeout: 120
    max_retries: 3

defaults:
  mode: "quick"
  rounds: 2
  max_rounds: 5

Nota: Use type: cli para ferramentas CLI e type: http para adaptadores HTTP (Ollama, LM Studio, OpenRouter).

Configuração do Registro de Modelos

Controle quais modelos estão disponíveis para seleção no registro de modelos. Cada modelo pode ser habilitado ou desabilitado sem remover sua definição:

model_registry:
  claude:
    - id: "claude-sonnet-4-5-20250929"
      label: "Claude Sonnet 4.5"
      tier: "balanced"
      default: true
      enabled: true  # Model is active and available
    - id: "claude-opus-4-20250514"
      label: "Claude Opus 4"
      tier: "premium"
      enabled: false  # Temporarily disabled (cost control, testing, etc.)

Comportamento do Campo Habilitado:

enabled: true (padrão) - O modelo aparece em list_models e pode ser selecionado para deliberações
enabled: false - O modelo fica oculto da seleção, mas a definição é mantida para reativação fácil
Modelos desabilitados não podem ser usados mesmo se especificados explicitamente em chamadas deliberate
A seleção padrão de modelos ignora modelos desabilitados automaticamente

Casos de Uso:

Controle de Custos: Desabilite modelos caros temporariamente sem perder configuração
Testes: Habilite/desabilite modelos específicos durante testes de integração
Implantação em Etapas: Configure novos modelos como desabilitados, habilite quando estiver pronto
Ajuste de Desempenho: Desabilite modelos lentos durante iteração rápida
Conformidade: Restrinja temporariamente modelos pendentes de aprovação

Análise Aprofundada dos Recursos Principais

Detecção de Convergência e Parada Automática

Os modelos convergem automaticamente e param de deliberar quando as opiniões se estabilizam, economizando tempo e custos de API. Status: Convergido (≥85% de similaridade), Refinando (40-85%), Divergindo (<40%) ou Impasse (desacordo estável). A votação tem precedência: quando os modelos votam, a convergência reflete o resultado da votação.

→ Guia Completo - Limiares, backends, configuração

Votação Estruturada

Os modelos votam com níveis de confiança (0,0-1,0), justificativas e sinais de continue_debate. Os votos determinam o consenso: Unânime (3-0), Maioria (2-1) ou Empate. Opções semelhantes são mescladas automaticamente no limiar de similaridade de 0,70+.

→ Guia Completo - Estrutura de votos, exemplos, integração

Adaptadores HTTP e Modelos Locais

Execute Ollama, LM Studio, OpenRouter ou Nebius para custos de API flexíveis e opções de privacidade. Combine com modelos na nuvem (Claude, GPT-4) em uma única deliberação.

→ Guias de Configuração - Ollama, LM Studio, OpenRouter, análise de custos

Estendendo o AI Counsel

Adicione novas ferramentas CLI ou adaptadores HTTP para adequar à sua infraestrutura. Processo simples de 3 a 5 etapas com exemplos e padrões de teste.

→ Guia do Desenvolvedor - Tutoriais passo a passo, exemplos do mundo real

Deliberação Baseada em Evidências

Fundamente decisões de design na realidade consultando código, arquivos e dados reais:

// MCP client example (e.g., Claude Code)
mcp__ai_counsel__deliberate({
  question: "Should we migrate from SQLite to PostgreSQL?",
  participants: [
    {cli: "claude", model: "sonnet"},
    {cli: "codex", model: "gpt-4"}
  ],
  rounds: 3,
  working_directory: process.cwd()  // Required - enables tools to access your files
})

Durante a deliberação, os modelos podem:

📄 Ler arquivos: TOOL_REQUEST: {"name": "read_file", "arguments": {"path": "config.yaml"}}
🔍 Pesquisar código: TOOL_REQUEST: {"name": "search_code", "arguments": {"pattern": "database.*connect"}}
📋 Listar arquivos: TOOL_REQUEST: {"name": "list_files", "arguments": {"pattern": "*.sql"}}
⚙️ Executar comandos: TOOL_REQUEST: {"name": "run_command", "arguments": {"command": "git", "args": ["log", "--oneline"]}}

Fluxo de trabalho de exemplo:

O Modelo A propõe PostgreSQL com base em suposições
O Modelo B solicita: read_file para verificar a configuração atual
A ferramenta retorna: database: sqlite, max_connections: 10
O Modelo B pesquisa: search_code por consultas de banco de dados
A ferramenta retorna: 50+ consultas com JOINs complexos
Os modelos convergem: "PostgreSQL é necessário pela complexidade das consultas e escala"
Decisão fundamentada em evidências, não em opinião

Benefícios:

Decisões enraizadas no estado atual, não em suposições
Aplica-se a revisões de código, escolhas de arquitetura, estratégia de testes
Trilha de auditoria completa de evidências nas transcrições

Ferramentas Suportadas:

read_file - Ler conteúdo de arquivos (máx. 1MB)
search_code - Pesquisar padrões regex (ripgrep ou fallback em Python)
list_files - Listar arquivos que correspondem a padrões glob
run_command - Executar comandos seguros somente leitura (ls, git, grep, etc.)

Configuração

Controle o comportamento das ferramentas em config.yaml:

Diretório de Trabalho (Obrigatório):

Defina o parâmetro working_directory ao chamar a ferramenta deliberate
As ferramentas resolvem caminhos relativos a partir deste diretório
Exemplo: working_directory: process.cwd() em clientes MCP JavaScript

Segurança das Ferramentas (deliberation.tool_security):

exclude_patterns: Bloquear acesso a diretórios sensíveis (padrão: transcripts/, .git/, node_modules/)
max_file_size_bytes: Limite de tamanho de arquivo para read_file (padrão: 1MB)
command_whitelist: Comandos seguros para run_command (ls, grep, find, cat, head, tail)

Árvore de Arquivos (deliberation.file_tree):

enabled: Injetar estrutura do repositório nos prompts da Rodada 1 (padrão: true)
max_depth: Limite de profundidade de diretórios (padrão: 3)
max_files: Número máximo de arquivos a incluir (padrão: 100)

Requisitos Específicos por Adaptador:

Adaptador	Comportamento do Diretório de Trabalho	Configuração
Claude	Isolamento automático via subprocesso `{working_directory}`	Nenhuma configuração especial necessária
Codex	Sem isolamento real - pode acessar qualquer arquivo	Consideração de segurança: modelos podem ler fora de `{working_directory}`
Droid	Isolamento automático via subprocesso `{working_directory}`	Nenhuma configuração especial necessária
Gemini	Impõe limites do espaço de trabalho	Obrigatório: flag `--include-directories {working_directory}`
Ollama/LMStudio	N/A - adaptadores HTTP	Sem restrições de acesso ao sistema de arquivos

Saiba Mais:

Referência Completa de Configuração - Todas as definições de config.yaml explicadas
Isolamento do Diretório de Trabalho - Como os adaptadores lidam com caminhos de arquivo
Modelo de Segurança das Ferramentas - Listas de permissão, limites e exclusões
Adicionando Ferramentas Personalizadas - Guia do desenvolvedor para estender o sistema de ferramentas

Solução de Problemas

Erros de "Arquivo não encontrado":

Certifique-se de que working_directory está definido corretamente na chamada do seu cliente MCP
Use o padrão de descoberta: list_files → read_file
Verifique se os caminhos de arquivo são relativos ao diretório de trabalho

Erros de "Acesso negado: Caminho corresponde ao padrão de exclusão":

As ferramentas bloqueiam transcripts/, .git/, node_modules/ por padrão
Personalize via deliberation.tool_security.exclude_patterns no config.yaml

Erros do Gemini "O caminho do arquivo deve estar dentro do espaço de trabalho":

Verifique se a flag --include-directories do Gemini usa o placeholder {working_directory}
Consulte a configuração específica do adaptador acima

Erros de tempo limite da ferramenta:

Aumente deliberation.tool_security.tool_timeout para operações lentas
Padrão: 10 segundos para operações de arquivo, 30 segundos para comandos

Saiba Mais:

Adicionando Ferramentas Personalizadas - Guia do desenvolvedor para estender o sistema de ferramentas
Arquitetura e Segurança - Como as ferramentas funcionam internamente
Armadilhas Comuns - Configurações avançadas e problemas conhecidos

Memória do Grafo de Decisões

O AI Counsel aprende com deliberações passadas para acelerar decisões futuras. Duas capacidades principais:

1. Injeção Automática de Contexto

Ao iniciar uma nova deliberação, o sistema:

Pesquisa debates passados por perguntas semelhantes (similaridade semântica)
Encontra as top-k decisões mais relevantes (configurável, padrão: 3)
Injeta contexto nos prompts da Rodada 1 automaticamente
Resultado: Modelos começam com conhecimento institucional, convergem mais rápido

2. Busca Semântica com `query_decisions`

Consulte deliberações passadas programaticamente:

Buscar semelhantes: Encontre decisões relacionadas a uma pergunta
Encontrar contradições: Detecte decisões passadas conflitantes
Rastrear evolução: Veja como as opiniões mudaram ao longo do tempo
Analisar padrões: Identifique temas recorrentes

Configuração (opcional - os padrões funcionam imediatamente):

decision_graph:
  enabled: true                       # Auto-injection on by default
  db_path: "decision_graph.db"        # Resolves to project root (works for any user/folder)
  similarity_threshold: 0.6           # Adjust to control context relevance
  max_context_decisions: 3            # How many past decisions to inject

Funciona para qualquer usuário a partir de qualquer diretório - o caminho do banco de dados é resolvido em relação à raiz do projeto.

→ Início Rápido | Configuração | Injeção de Contexto

Uso

Iniciar o Servidor

python server.py

Configurar no Claude Code

Opção A: Configuração do Projeto (Recomendada) - Crie .mcp.json:

{
  "mcpServers": {
    "ai-counsel": {
      "type": "stdio",
      "command": ".venv/bin/python",
      "args": ["server.py"],
      "env": {}
    }
  }
}

Opção B: Configuração do Usuário - Adicione ao ~/.claude.json com caminhos absolutos.

Após a configuração, reinicie o Claude Code.

Seleção de Modelos e Padrões de Sessão

Descubra os modelos permitidos para cada adaptador executando a ferramenta MCP list_models.
Defina padrões por sessão com set_session_models; deixe model em branco em deliberate para usar esses padrões.
Instruções completas e exemplos de solicitações estão em Registro de Modelos e Seletor.

Exemplos

Modo Rápido:

mcp__ai-counsel__deliberate({
  question: "Should we migrate to TypeScript?",
  participants: [{cli: "claude", model: "sonnet"}, {cli: "codex", model: "gpt-5.2-codex"}],
  mode: "quick"
})

Modo Conferência (multirrodadas):

mcp__ai-counsel__deliberate({
  question: "JWT vs session-based auth?",
  participants: [
    {cli: "claude", model: "sonnet"},
    {cli: "codex", model: "gpt-5.2-codex"}
  ],
  rounds: 3,
  mode: "conference"
})

Pesquisar Decisões Passadas:

mcp__ai-counsel__query_decisions({
  query_text: "database choice",
  threshold: 0.5,  // NEW! Adjust sensitivity (0.0-1.0, default 0.6)
  limit: 5
})
// Returns: Similar past deliberations with consensus and similarity scores

// NEW! Empty results include helpful diagnostics:
{
  "type": "similar_decisions",
  "count": 0,
  "results": [],
  "diagnostics": {
    "total_decisions": 125,
    "best_match_score": 0.45,
    "near_misses": [{"question": "Database indexing...", "score": 0.45}],
    "suggested_threshold": 0.45,
    "message": "No results found above threshold 0.6. Best match scored 0.450. Try threshold=0.45..."
  }
}

// Find contradictions
mcp__ai-counsel__query_decisions({
  operation: "find_contradictions"
})
// Returns: Decisions where consensus conflicts

// Trace evolution
mcp__ai-counsel__query_decisions({
  query: "microservices architecture",
  operation: "trace_evolution"
})
// Returns: How opinions evolved over time on this topic

Transcrições

Todas as deliberações são salvas em transcripts/ com resumos gerados por IA e histórico completo do debate.

Arquitetura

ai-counsel/
├── server.py                # MCP server entry point
├── config.yaml              # Configuration
├── adapters/                # CLI/HTTP adapters
│   ├── base.py             # Abstract base
│   ├── base_http.py        # HTTP base
│   └── [adapter implementations]
├── deliberation/            # Core engine
│   ├── engine.py           # Orchestration
│   ├── convergence.py      # Similarity detection
│   └── transcript.py       # Markdown generation
├── models/                  # Data models (Pydantic)
├── tests/                   # Unit/integration/e2e tests
└── decision_graph/         # Optional memory system

Central de Documentação

Primeiros Passos

Início Rápido - Configuração em 5 minutos
Instalação - Pré-requisitos e configuração detalhados
Exemplos de Uso - Modos rápido e conferência

Conceitos Principais

Detecção de Convergência - Parada automática, limites, backends
Votação Estruturada - Estrutura de votos, tipos de consenso, agrupamento de votos
Deliberação Baseada em Evidências - Fundamente decisões na realidade com read_file, search_code, list_files, run_command
Memória de Grafo de Decisões - Aprendendo com decisões passadas

Configuração e Ajustes

Adaptadores HTTP - Configuração do Ollama, LM Studio, OpenRouter
Referência de Configuração - Todas as opções YAML
Guia de Migração - De cli_tools para adaptadores

Desenvolvimento

Adicionando Adaptadores - Desenvolvimento de adaptadores CLI e HTTP
CLAUDE.md - Arquitetura, fluxo de trabalho de desenvolvimento, armadilhas
Registro de Modelos e Seletor - Gerenciando modelos permitidos e ferramentas seletoras MCP

Referência

Solução de Problemas - Problemas com adaptadores HTTP
Documentação do Grafo de Decisões - Recursos avançados de memória

Desenvolvimento

Executando Testes

pytest tests/unit -v                    # Unit tests (fast)
pytest tests/integration -v -m integration  # Integration tests
pytest --cov=. --cov-report=html       # Coverage report

Consulte CLAUDE.md para o fluxo de trabalho de desenvolvimento e notas de arquitetura.

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feature/your-feature)
Escreva testes primeiro (fluxo de trabalho TDD)
Implemente a funcionalidade
Garanta que todos os testes passem
Envie um PR com descrição clara

Licença

Licença MIT - consulte o arquivo LICENSE

Créditos

Construído com:

MCP SDK - Protocolo de Contexto de Modelo
Pydantic - Validação de dados
pytest - Framework de testes

Inspirado pela necessidade de consenso deliberativo de IA verdadeiro além da coleta paralela de opiniões.

Status

GitHub stars GitHub forks GitHub last commit

Pronto para Produção - Consenso deliberativo multimodelo com memória de grafo de decisões entre usuários, votação estruturada e parada antecipada adaptativa para decisões técnicas críticas!

AI Counsel

Documentação

AI Counsel

🎬 Veja em Ação

O Que Torna Isso Diferente

Recursos

Início Rápido

Instalação

Pré-requisitos

Configuração

Configuração

Configuração do Registro de Modelos

Análise Aprofundada dos Recursos Principais

Detecção de Convergência e Parada Automática

Votação Estruturada

Adaptadores HTTP e Modelos Locais

Estendendo o AI Counsel

Deliberação Baseada em Evidências

Configuração

Solução de Problemas

Memória do Grafo de Decisões

1. Injeção Automática de Contexto

2. Busca Semântica com query_decisions

Uso

Iniciar o Servidor

Configurar no Claude Code

Seleção de Modelos e Padrões de Sessão

Exemplos

Transcrições

Arquitetura

Central de Documentação

Primeiros Passos

Conceitos Principais

Configuração e Ajustes

Desenvolvimento

Referência

Desenvolvimento

Executando Testes

Contribuindo

Licença

Créditos

Status

2. Busca Semântica com `query_decisions`