Semantic-Sift

Um middleware MCP baseado em raciocínio que usa heurísticas e modelos neurais BERT para destilar contexto e eliminar ruído.

GitHub

Experimente este MCPPatrocinado

Documentação

🔍 Semantic-Sift

O Middleware com Foco em Raciocínio para Workflows Agênticos de Alta Fidelidade.

"Economiza tokens enquanto preserva o contexto — maximizando o raciocínio, minimizando a alucinação."

O Semantic-Sift é um servidor local de Model Context Protocol (MCP) que atua como uma "Camada de Saneamento" inteligente entre seus dados brutos e a janela de contexto da sua IA.

Embora os LLMs modernos tenham janelas de contexto massivas, a precisão do raciocínio frequentemente degrada à medida que o ruído aumenta. O Semantic-Sift resolve isso destilando logs técnicos, documentos extensos e históricos de chat em contexto de alta densidade usando LLMLingua-2. Ele trata sua janela de contexto como um recurso precioso — otimizando a Relação Sinal-Ruído (SNR) para que seus modelos gastem mais tempo raciocinando e menos tempo navegando por texto padronizado.

🧠 Filosofia: O Estúdio de Dois

O Semantic-Sift é fundamentado na filosofia do Estúdio de Dois: a crença de que o futuro da engenharia é uma parceria de alta fidelidade entre um arquiteto humano e um sidecar de IA soberano. Ao gerenciar o atrito da ingestão de dados brutos, o Sift permite que esse "Estúdio" se concentre em construir sistemas, não apenas aplicar correções. Ele atua como um filtro cognitivo que garante que tanto você quanto seu agente estejam colaborando na representação mais limpa e relevante da verdade técnica.

⚡ Início Rápido (60 segundos)

# 1. Install
pip install "semantic-sift[neural]"

# 2. Onboard your project (writes IDE hooks and opencode.json)
semantic-sift-onboard   # or: ask your AI "Run sift_onboard()"

# 3. Add to your MCP config (example: Cursor / Claude Desktop)
# { "mcpServers": { "semantic-sift": { "command": "semantic-sift" } } }

# 4. Warm up the model (optional — avoids first-call latency)
# Ask your AI: "Run sift_warmup()"

Guia de configuração completo (estrutura de venv, matriz de configuração de IDE, Padrão Soberano): doc/INTEGRATION_ENCYCLOPEDIA.md

🏛️ Valor Multidisciplinar

O Semantic-Sift é uma camada estratégica projetada para gerenciar a atenção em quatro personas profissionais-chave:

Para o Engenheiro Sênior: Um middleware local-first e de baixa latência usando uma abordagem de motor duplo (Peneira Heurística + Reordenador Neural). Ele refina timestamps, texto padronizado repetitivo e JSON redundante antes que cheguem à rede, reduzindo a latência e prevenindo falhas de raciocínio "Perdido no Meio".
Para o Gerente de Projetos: "Seguro de Contexto." Ao reduzir a sobrecarga de tokens em 30-70%, o Sift proporciona ROI direto nos custos de API e reduz o "loop de tentativas" causado por alucinações do modelo em ambientes de dados desordenados.
Para o Pesquisador: Integridade de dados em escala. Suporta MarkItDown (via extra opcional [multi-modal]) para converter .pdf, .docx e .xlsx complexos em Markdown estruturado e destilado, permitindo a síntese rápida de repositórios técnicos massivos sem perder âncoras semânticas críticas.
Para o Parceiro de Conhecimento: Gerenciamento de Carga Cognitiva. O Sift gerencia o atrito da ingestão de dados brutos, permitindo que a parceria humano-IA se concentre em estratégia de alto nível e decisões arquiteturais em vez de triagem manual de dados.

💰 Engenharia de Valor: ROI Operacional vs. Econômico

O Semantic-Sift fornece uma camada dupla de valor. Enquanto os benefícios econômicos dependem do seu plano de cobrança, os benefícios operacionais se aplicam a todos os fluxos de trabalho profissionais.

1. O ROI Econômico (Economia Direta)

Público-alvo: Usuários de planos de API por token (GPT-4o, Claude 3.5).

Proteção do Orçamento: O Sift atua como um filtro local, tipicamente reduzindo o volume de tokens de saída em 30-70%.
Juros Compostos: Em loops agênticos iterativos, essas economias se acumulam rapidamente. Cada caractere removido é dinheiro que permanece no seu orçamento.

2. O ROI Operacional (Qualidade e Desempenho)

Público-alvo: TODOS (incluindo usuários de assinatura "Ilimitada" ou por solicitação).

Precisão de Atenção: Mesmo com contexto "infinito", os LLMs sofrem da síndrome "Perdido no Meio". Ao remover ruído, você garante que todo o poder de raciocínio do modelo esteja focado no sinal técnico, resultando em código de maior qualidade e menos alucinações.
Redução de Latência: Prompts menores = "Tempo até o Primeiro Token" (TTFT) mais rápido. Você gasta menos tempo esperando a "nuvem" processar texto padronizado e mais tempo no seu estado de fluxo.
Seguro de Contexto: Previne erros de "Limite de contexto excedido" em tarefas complexas. O Sift garante que 100% do limite do seu modelo seja preenchido com informação, não formatação.

📚 Índice Mestre de Documentação

Todos os detalhes técnicos, lógica arquitetural e guias de integração são estritamente mantidos no diretório doc/ para prevenir perda de dados por meio de sumarização.

doc/INDEX.md: O roteiro de navegação e fonte de verdade para a estrutura da documentação.
doc/ARCHITECTURE.md: Especificações do Interceptador de Hook Sift, o Núcleo de Destilação (motores Heurístico/Semântico/Classificação) e Cache.
doc/TOOL_REFERENCE.md: Manual operacional exaustivo para todas as ferramentas FastMCP (ex.: sift_read_file, sift_logs, sift_chat, sift_rank).
doc/INTEGRATION_ENCYCLOPEDIA.md: Mapa Mestre de Compatibilidade, lógica do Injetor de Hook, Estruturas de Payload e a Matriz Mestra de Configuração para conectar IDEs (Cursor, Gemini, VS Code, OpenCode, etc.).
doc/TELEMETRY_SPEC.md: Design do rastreamento OpenTelemetry, Detector de Eco (Prevenção de Dupla Triagem), Cabeçalhos de Auditoria e controles de Privacidade.
doc/ORCHESTRATION_BLUEPRINTS.md: Fluxos de trabalho acionáveis para agentes de IA, incluindo árvores de decisão para Ingestão de Arquivos, RAG Multi-Documento e Compactação de Histórico.

🎯 Casos de Uso de Alto Impacto

📚 O Caçador de Conhecimento (Pesquisadores e Arquitetos)

A Dor: Ler PDFs de 50 páginas, especificações complexas em Word ou sites de documentação desorganizados.
A Triagem: Suporta MarkItDown via extra opcional [multi-modal] para ingerir nativamente .pdf, .docx e .xlsx. Converte "ruído" corporativo em Markdown estruturado, permitindo que seu agente sintetize múltiplos documentos de 14MB em uma única rodada.

🛠️ O Caçador de Logs (DevOps e SREs)

A Dor: Encontrar um único erro em 100.000 linhas de logs técnicos.
A Triagem: A Peneira Heurística refina timestamps e texto padronizado em milissegundos. O Hook Subconsciente reordena automaticamente os resultados, para que seu agente veja apenas os blocos de dados mais relevantes.

🧠 O Estrategista de Contexto (Engenheiros de IA)

A Dor: Alucinação de LLM e degradação de raciocínio causadas por fluxos de dados desordenados.
A Triagem: Ao entregar contexto de alta densidade com 95% do significado preservado, o Sift atua como uma Ponte Cognitiva. Garante que a atenção do seu LLM esteja focada exclusivamente no sinal.

⚡ Níveis de Desempenho

O Semantic-Sift é distribuído em dois níveis de desempenho. Escolha com base no seu caso de uso:

	Servidor MCP Python (`pip install semantic-sift`)	Sidecar CLI Rust (`sift-core`)
Triagem heurística de logs	✅ ~500ms	✅ <1ms (nativo)
Triagem semântica neural	✅ ~500ms (PyTorch)	✅ ~150ms (ONNX)
Dependência Python	Necessária	Nenhuma
Toolchain Rust	Não necessária	Não necessária (pré-compilado)
Entrega via	Wheel PyPI (inclui `sift-core` pré-compilado)	Empacotado no wheel; use `fetch_sift_core.py` para instalações de desenvolvimento

Wheel PyPI (pip install semantic-sift): O binário sift-core pré-compilado está incluído — nenhuma toolchain Rust necessária.

Instalação editável/desenvolvimento (pip install -e .): A etapa de compilação Rust é ignorada. Execute uma vez para buscar o binário pré-compilado:

python scripts/fetch_sift_core.py

Marcador opcional [native]: Para ferramentas de gerenciamento de dependências que precisam de um identificador explícito, pip install semantic-sift[native] está disponível como um extra no-op (o binário está sempre incluído no wheel).

🚀 Início Rápido

1. Instalação

Opção A: Instalação Rápida (PyPI)

ℹ️ O que você obtém: O wheel PyPI inclui o binário Rust sift-core pré-compilado — nenhuma toolchain Rust necessária. O extra [neural] adiciona PyTorch (~1,5 GB) para fallback de payloads grandes usando LLMLingua-2; [multi-modal] adiciona MarkItDown para ingestão de PDF/DOCX/XLSX. Espere vários minutos para a primeira instalação devido ao tamanho do download do PyTorch.

uv venv
# Windows: .\.venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
uv pip install semantic-sift[neural,multi-modal]

Opção B: Padrão Soberano (Recomendado)

Clone o repositório para obter acesso ao código-fonte nativo do sidecar Rust e benchmarks:

⚠️ Compilador Rust Necessário: O Padrão Soberano compila sift-core a partir do código-fonte. Você deve ter o compilador Rust instalado (rustup.rs) antes de executar o comando de instalação abaixo. Se você não quiser instalar Rust, use a Opção A (PyPI).

git clone https://github.com/luismichio/semantic-sift.git
cd semantic-sift
# Use Python 3.12 for torch/CUDA compatibility
python3.12 -m venv venv312
# Windows:
.\venv312\Scripts\activate
# macOS/Linux:
# source venv312/bin/activate
uv pip install -e .[neural,multi-modal]

Dica para Windows (descoberta de ambiente uv): Se uv falhar ao encontrar seu ambiente (erro: "Nenhum ambiente virtual encontrado"), aponte explicitamente para seu interpretador: uv pip install -e . --python venv312\Scripts\python.exe

Nota: Se você estiver usando o Padrão de Repositório Duplo Soberano do Context-Pipe, semantic-sift é instalado de forma cruzada em context-pipe/venv (via uv pip install -e ../semantic-sift). O venv312 acima só é necessário para o runtime ML autônomo ou para executar server.py diretamente.

🐍 Orientação de Ambiente Python

Escolher o caminho Python correto para sua configuração MCP é crítico para a estabilidade:

Tipo de Configuração	Exemplo de Caminho	Prós	Contras
Venv Dedicado (Win)	`.../semantic-sift/venv312/Scripts/python.exe`	Dependências isoladas, sem conflitos de versão do torch.	Um pouco mais de espaço em disco.
Venv Dedicado (Mac/Linux)	`.../semantic-sift/venv312/bin/python`	Mesmo benefício de isolamento no Unix.	Igual.
Python Global	`C:/Users/User/AppData/Local/.../python.exe`	Bibliotecas compartilhadas, configuração rápida.	Alto risco de conflitos de versão (ex.: incompatibilidades de `transformers`).

Recomendação: Sempre use o caminho Venv Dedicado no seu mcp_config.json para garantir que o núcleo de triagem seja isolado e confiável.

Nota sobre Orquestração: O Semantic-Sift é um "Núcleo de Inteligência". Para fluxos de trabalho complexos com múltiplas ferramentas, recomendamos fortemente instalar o Context-Pipe, o switchboard universal que roteia dados nativamente para o Semantic-Sift sem bloquear sua IDE.

Para ferramentas de desenvolvimento (mypy, pytest):

uv pip install -e .[dev]

Binário Rust para instalações editáveis: pip install -e . ignora a etapa de compilação Rust, então sift-core não estará no seu PATH. Em vez de compilar a partir do código-fonte, baixe o binário pré-compilado para sua plataforma da release correspondente no GitHub em um único comando:
python scripts/fetch_sift_core.py
Isso coloca sift-core[.exe] diretamente no diretório Scripts/bin do seu ambiente ativo. Execute novamente sempre que atualizar a versão.

2. Conecte o MCP

CRÍTICO: Para caminhos de configuração exatos para Cursor, Gemini, OpenCode, VS Code e Claude, consulte a Matriz Mestra de Configuração.

3. Onboarding Automático

Após conectar, pergunte ao seu Assistente de IA:

"Execute sift_onboard() para configurar este projeto."

📊 Comandos de Telemetria e Gerenciamento

O Semantic-Sift opera de forma invisível, mas você pode sempre auditar seu desempenho e economia de tokens sem queimar tokens de LLM para isso.

CLI de Terminal:
- Execute semantic-sift-stats para imprimir um painel global de sua economia de tokens, latência e acertos de cache.
- Execute semantic-sift-onboard para inicializar manualmente o Sift em qualquer projeto (suporta --env e --dry-run).
Prompts MCP: Clientes compatíveis (Claude Desktop, Cursor, Zed) exibirão um prompt sift_dashboard em sua interface (frequentemente via comando de barra ou botão) para injetar instantaneamente suas estatísticas de telemetria no chat.
OpenCode e Gemini CLI: A ferramenta sift_onboard() injeta automaticamente comandos de barra personalizados nativos /sift-stats e /sift-onboard na configuração da sua IDE.

🦀 Sidecar Rust Nativo (Aplicativos Meechi e Desktop)

Para aplicações de alta performance e prioridade local (como o Meechi), o Semantic-Sift fornece um binário nativo em Rust (sift-core). Esse sidecar é otimizado para portabilidade e velocidade, com zero dependências de Python.

🔀 O Motor Híbrido (`semantic-sift-cli`)

Para oferecer o melhor dos dois mundos, instalar o pacote Python também expõe o comando semantic-sift-cli. Ele atua como um Roteador Inteligente:

Para tarefas curtas (<30.000 caracteres), ele aciona instantaneamente o sift-core em Rust (ONNX) de baixa latência.
Para tarefas em lote massivas, ele carrega dinamicamente o framework PyTorch de alta produtividade com Flash Attention para evitar explosão de memória.

Comparação de Recursos

Recurso	Servidor MCP Python	Rust Sift-Core (Sidecar)
Peneiramento Heurístico de Logs	✅	✅ (Nativo)
Compressão Semântica	✅ (PyTorch)	✅ (ONNX)
Ingestão Multimodal	✅ (via `[multi-modal]`)	❌ (Somente Texto)
Formatos Suportados	.pdf, .xlsx, .docx, .html, .txt	.txt, .log, .out (Texto)
Latência de Inicialização	3-5 segundos	~10ms
Tamanho do Binário	~1,5GB (com modelos)	~15MB

Nota: Para aplicativos nativos como o Meechi, recomendamos uma estratégia de Ingestão em Camadas: use o frontend do aplicativo (ex.: pdf.js) para extrair texto e, em seguida, envie-o para o sidecar Rust para peneiramento semântico de alta velocidade.

✨ Ver Demonstração do Sidecar Nativo

Uso:

# Sift a log file instantly
cat app.log | sift-core logs

# Perform neural semantic compression
cat document.txt | sift-core semantic --model ./models/llmlingua2 --rate 0.4

🤖 Para Agentes de IA: Protocolo Operacional

Se você é um Agente de IA (ex.: Gemini CLI, Cursor, Claude Code) lendo este repositório, siga este protocolo:

Inicialização: Chame sift_onboard() para registrar hooks em segundo plano. Use sift_onboard(dry_run=True) para pré-visualizar todas as ações planejadas sem gravar nenhum arquivo.
Aviso de Contexto: Antes de ler arquivos grandes (>1.000 caracteres), chame sift_analyze_file(path) para determinar a taxa de ruído.
Peneiramento Obrigatório: Se o ruído > 15%, canalize os dados por sift_logs ou sift_chat antes de incluí-los no raciocínio. Para documentos, use sift_doc(text, rate=0.4) — ajuste rate (0,1–0,9) para equilibrar profundidade de compressão versus fidelidade.
Classificação: Use sift_rank para identificar os trechos mais semanticamente relevantes para o prompt do usuário.
Extração: Ao destilar PDFs ou conteúdo raspado, use sift_extraction(content, show_diff=True) para ver exatamente o que foi removido e verificar a fidelidade.

🛡️ Segurança e Testes

O Semantic-Sift é construído sobre uma Linha de Base de Zero Vulnerabilidades:

Pytest: 100% de taxa de aprovação na integridade heurística.
Bandit (SAST): Análise estática automatizada para padrões Python.
Pip-Audit (SCA): Monitoramento da cadeia de suprimentos em tempo real para 0 vulnerabilidades conhecidas.

Controles de privacidade e telemetria:

Defina SIFT_TELEMETRY_OPTED_IN=true para habilitar a telemetria (opt-in; desativada por padrão).
Defina SIFT_TELEMETRY_DISABLED=true (interruptor de desativação legado) para desativar a telemetria completamente.
Defina SIFT_TELEMETRY_TTL_DAYS=90 (padrão) para controlar quantos dias de histórico de sessão são retidos em .pipe_telemetry.json antes que entradas antigas sejam removidas.
Defina SIFT_TELEMETRY_URL=https://your-endpoint para rotear pulsos de metadados para seu próprio endpoint.
Defina SIFT_PULSE_RATE_LIMIT_S=10 (padrão) para controlar a frequência de pulsos de telemetria assíncronos.

Controles de segurança:

Defina SIFT_ALLOW_GLOBAL_READS=true para permitir sift_read_file / sift_analyze_file fora da raiz do espaço de trabalho (a proteção contra travessia de caminho está ativada por padrão).

Controles de desempenho:

Defina SIFT_HOOK_TIMEOUT_MS=3000 para limitar a latência semântica do hook antes do fallback heurístico.
Defina SIFT_MODEL_READY_WAIT_MS=1200 para controlar o tempo de espera de aquecimento do modelo semântico antes de retornar a saída em modo heurístico.
Defina SIFT_COMPACTION_FIDELITY_THRESHOLD=0.3 (padrão) para controlar o limite de sobreposição de vocabulário abaixo do qual um aviso de compactação de baixa fidelidade é emitido.
Defina SIFT_RANK_TOP_N=3 (padrão) para definir o número padrão de resultados retornados por sift_rank quando top_n não é passado explicitamente.

Controles de registro de hooks:

Defina SIFT_LOG_FILE para substituir o caminho do log do hook (padrão: .gemini/sift_debug.log).
Defina SIFT_LOG_LEVEL (DEBUG, INFO, WARNING, ERROR) para controlar a verbosidade do log do hook.

Consulte SECURITY.md para nossa política de segurança completa.

O esquema de telemetria e os detalhes do endpoint estão documentados em doc/TELEMETRY_SPEC.md.

🔗 O Ecossistema (Studio of Two)

O Semantic-Sift é um membro de destaque da infraestrutura Studio of Two. Ele é projetado para funcionar em harmonia de alta fidelidade com:

Context-Pipe: O painel de controle universal para engenharia de contexto. Enquanto o Sift fornece a inteligência, o Context-Pipe fornece a orquestração. Recomendamos fortemente usar o Context-Pipe para encadear nós do Sift com ferramentas de mascaramento, busca e ingestão multimodal.

⚖️ Licenciamento

O Semantic-Sift é licenciado sob a Apache License 2.0. Consulte LICENSE.md para detalhes.

🤝 Contribuições

O Semantic-Sift é Open Source, mas Fechado para Contribuições.

Para manter a visão arquitetural estrita do "Studio of Two" e manter a sobrecarga de manutenção em zero absoluto, este repositório não aceita pull requests externos. Encorajamos você a usar, incorporar e bifurcar o código sob a licença permissiva Apache 2.0, mas por favor, não envie PRs para novos recursos ou correções de bugs. Consulte CONTRIBUTING.md para detalhes.