Semantic-Sift

Un middleware MCP basado en razonamiento que utiliza heurísticas y modelos BERT neuronales para destilar contexto y eliminar ruido.

GitHub
2
Prueba este MCPPatrocinado

Documentación

🔍 Semantic-Sift

El middleware de razonamiento primero para flujos de trabajo agénticos de alta fidelidad.

CI Tests Coverage PyPI Python Security License OSI

"Ahorra tokens mientras preserva el contexto: maximiza el razonamiento, minimiza la alucinación."

Semantic-Sift es un servidor local de Protocolo de Contexto de Modelo (MCP) que actúa como un "Nivel de Saneamiento" inteligente entre tus datos brutos y la ventana de contexto de tu IA.

Si bien los LLM modernos tienen ventanas de contexto masivas, su precisión de razonamiento a menudo se degrada a medida que aumenta el ruido. Semantic-Sift resuelve esto destilando registros técnicos, documentos extensos e historiales de chat en contexto de alta densidad utilizando LLMLingua-2. Trata tu ventana de contexto como un recurso precioso, optimizando la Relación Señal-Ruido (SNR) para que tus modelos pasen más tiempo razonando y menos tiempo navegando por texto repetitivo.

🧠 Filosofía: El Estudio de Dos

Semantic-Sift se basa en la filosofía del Estudio de Dos: la creencia de que el futuro de la ingeniería es una asociación de alta fidelidad entre un arquitecto humano y un copiloto de IA soberano. Al gestionar la fricción de la ingesta de datos brutos, Sift permite que este "Estudio" se centre en construir sistemas, no solo en aplicar parches. Actúa como un filtro cognitivo que garantiza que tanto tú como tu agente colaboren en la representación más limpia y relevante de la verdad técnica.

⚡ Inicio 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()"

Guía de configuración completa (estructura de venv, matriz de configuración de IDE, Patrón Soberano): doc/INTEGRATION_ENCYCLOPEDIA.md

🏛️ Valor Multidisciplinario

Semantic-Sift es una capa estratégica diseñada para gestionar la atención en cuatro perfiles profesionales clave:

  • Para el Ingeniero Senior: Un middleware local-first y de baja latencia que utiliza un enfoque de doble motor (Tamiz Heurístico + Reordenador Neuronal). Refina marcas de tiempo, texto repetitivo y JSON redundante antes de que lleguen al cable, reduciendo la latencia y previniendo fallos de razonamiento por "Perdido en el Medio".
  • Para el Gerente de Proyecto: "Seguro de Contexto." Al reducir la sobrecarga de tokens en un 30-70%, Sift proporciona un ROI directo en los costos de API y reduce el "bucle de reintentos" causado por alucinaciones del modelo en entornos de datos desordenados.
  • Para el Investigador: Integridad de datos a escala. Soporta MarkItDown (a través del extra opcional [multi-modal]) para convertir .pdf, .docx y .xlsx complejos en Markdown estructurado y destilado, permitiendo la síntesis rápida de repositorios técnicos masivos sin perder anclas semánticas críticas.
  • Para el Socio de Conocimiento: Gestión de Carga Cognitiva. Sift gestiona la fricción de la ingesta de datos brutos, permitiendo que la asociación humano-IA se centre en estrategia de alto nivel y decisiones arquitectónicas en lugar de triaje manual de datos.

💰 Ingeniería de Valor: ROI Operativo vs. Económico

Semantic-Sift proporciona una capa dual de valor. Mientras que los beneficios económicos dependen de tu plan de facturación, los beneficios operativos se aplican a cada flujo de trabajo profesional.

1. El ROI Económico (Ahorros Directos)

Objetivo: Usuarios en planes de API por token (GPT-4o, Claude 3.5).

  • Protección de Cartera: Sift actúa como un filtro local, típicamente reduciendo el volumen de tokens salientes en un 30-70%.
  • Interés Compuesto: En bucles agénticos iterativos, estos ahorros se acumulan rápidamente. Cada carácter podado es dinero que permanece en tu presupuesto.

2. El ROI Operativo (Calidad y Rendimiento)

Objetivo: TODOS (incluidos usuarios de suscripción "Ilimitada" o por solicitud).

  • Precisión de Atención: Incluso con contexto "infinito", los LLM sufren del síndrome de "Perdido en el Medio". Al eliminar el ruido, aseguras que todo el poder de razonamiento del modelo se enfoque en la señal técnica, resultando en código de mayor calidad y menos alucinaciones.
  • Reducción de Latencia: Prompts más pequeños = Tiempo más rápido al Primer Token (TTFT). Pasas menos tiempo esperando que la "nube" procese texto repetitivo y más tiempo en tu estado de flujo.
  • Seguro de Contexto: Previene errores de "Límite de contexto excedido" en tareas complejas. Sift asegura que el 100% del límite de tu modelo esté lleno de información, no de formato.

📚 Índice Maestro de Documentación

Todos los detalles técnicos, lógica arquitectónica y guías de integración se mantienen estrictamente en el directorio doc/ para prevenir la pérdida de datos a través de la resumición.

  • doc/INDEX.md: La hoja de ruta de navegación y la fuente de verdad para la estructura de documentación.
  • doc/ARCHITECTURE.md: Especificaciones del Interceptor de Gancho Sift, el Núcleo de Destilación (motores Heurístico/Semántico/Clasificación) y el Caché.
  • doc/TOOL_REFERENCE.md: Manual exhaustivo del operador para todas las herramientas FastMCP (p. ej., sift_read_file, sift_logs, sift_chat, sift_rank).
  • doc/INTEGRATION_ENCYCLOPEDIA.md: Mapa Maestro de Compatibilidad, lógica del Inyector de Ganchos, Estructuras de Payload y la Matriz Maestra de Configuración para conectar IDEs (Cursor, Gemini, VS Code, OpenCode, etc.).
  • doc/TELEMETRY_SPEC.md: Diseño del rastreo OpenTelemetry, Detector de Eco (Prevención de Doble Sifting), Cabeceras de Auditoría y controles de Privacidad.
  • doc/ORCHESTRATION_BLUEPRINTS.md: Flujos de trabajo accionables para agentes de IA, incluidos árboles de decisión de Ingesta de Archivos, RAG Multi-Documento y Compactación de Historial.

🎯 Casos de Uso de Alto Impacto

📚 El Cazador de Conocimiento (Investigadores y Arquitectos)

  • El Dolor: Leer PDFs de 50 páginas, especificaciones complejas de Word o sitios de documentación desordenados.
  • El Sift: Soporta MarkItDown a través del extra opcional [multi-modal] para ingerir nativamente .pdf, .docx y .xlsx. Convierte el "ruido" corporativo en Markdown estructurado, permitiendo que tu agente sintetice múltiples documentos de 14MB en un solo turno.

🛠️ El Cazador de Registros (DevOps y SREs)

  • El Dolor: Encontrar un solo error en 100,000 líneas de registros técnicos.
  • El Sift: El Tamiz Heurístico refina marcas de tiempo y texto repetitivo en milisegundos. El Gancho Subconsciente reordena automáticamente los resultados, para que tu agente solo vea los bloques de datos más relevantes.

🧠 El Estratega de Contexto (Ingenieros de IA)

  • El Dolor: Alucinación de LLM y degradación del razonamiento causadas por flujos de datos desordenados.
  • El Sift: Al entregar contexto de alta densidad con el 95% del significado preservado, Sift actúa como un Puente Cognitivo. Asegura que la atención de tu LLM se enfoque exclusivamente en la señal.

⚡ Niveles de Rendimiento

Semantic-Sift se distribuye en dos niveles de rendimiento. Elige según tu caso de uso:

Servidor MCP Python (pip install semantic-sift)Sidecar CLI Rust (sift-core)
Sifting heurístico de registros✅ ~500ms✅ <1ms (nativo)
Sifting semántico neuronal✅ ~500ms (PyTorch)✅ ~150ms (ONNX)
Dependencia de PythonRequeridaNinguna
Toolchain de RustNo requeridoNo requerido (precompilado)
Entrega víaRueda PyPI (incluye sift-core precompilado)Empaquetado en la rueda; usa fetch_sift_core.py para instalaciones de desarrollo

Rueda PyPI (pip install semantic-sift): El binario sift-core precompilado está incluido — no se requiere toolchain de Rust.

Instalación editable/desarrollo (pip install -e .): El paso de compilación de Rust se omite. Ejecuta una vez para obtener el binario precompilado:

python scripts/fetch_sift_core.py

Marcador opcional [native]: Para herramientas de gestión de dependencias que necesitan un identificador explícito, pip install semantic-sift[native] está disponible como un extra sin operación (el binario siempre está incluido en la rueda).

🚀 Inicio Rápido

1. Instalación

Opción A: Instalación Rápida (PyPI)

ℹ️ Lo que obtienes: La rueda PyPI incluye el binario Rust sift-core precompilado — no se requiere toolchain de Rust. El extra [neural] añade PyTorch (~1.5 GB) para el respaldo de payloads grandes usando LLMLingua-2; [multi-modal] añade MarkItDown para la ingesta de PDF/DOCX/XLSX. Espera varios minutos para la primera instalación debido al tamaño de descarga de PyTorch.

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

Opción B: Patrón Soberano (Recomendado)

Clona el repositorio para acceder al código fuente nativo del sidecar Rust y a los benchmarks:

⚠️ Compilador de Rust Requerido: El Patrón Soberano compila sift-core desde el código fuente. Debes tener el compilador de Rust instalado (rustup.rs) antes de ejecutar el comando de instalación a continuación. Si no deseas instalar Rust, usa la Opción A (PyPI) en su lugar.

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]

Consejo para Windows (descubrimiento de entorno uv): Si uv no logra encontrar tu entorno (error: "No se encontró un entorno virtual"), apunta explícitamente a tu intérprete: uv pip install -e . --python venv312\Scripts\python.exe

Nota: Si estás usando el Patrón de Doble Repositorio Soberano de Context-Pipe, semantic-sift se instala de forma cruzada en context-pipe/venv (a través de uv pip install -e ../semantic-sift). El venv312 anterior solo se necesita para el runtime ML independiente o para ejecutar server.py directamente.

🐍 Guía de Entorno de Python

Elegir la ruta de Python correcta para tu configuración MCP es crítico para la estabilidad:

Tipo de ConfiguraciónEjemplo de RutaVentajasDesventajas
Venv Dedicado (Win).../semantic-sift/venv312/Scripts/python.exeDependencias aisladas, sin conflictos de versión de torch.Ligeramente más espacio en disco.
Venv Dedicado (Mac/Linux).../semantic-sift/venv312/bin/pythonMismo beneficio de aislamiento en Unix.Igual.
Python GlobalC:/Users/User/AppData/Local/.../python.exeBibliotecas compartidas, configuración rápida.Alto riesgo de conflictos de versión (p. ej., discrepancias de transformers).

Recomendación: Usa siempre la ruta de Venv Dedicado en tu mcp_config.json para asegurar que el núcleo de sifting esté aislado y sea confiable.

Nota sobre Orquestación: Semantic-Sift es un "Núcleo de Inteligencia". Para flujos de trabajo complejos con múltiples herramientas, recomendamos encarecidamente instalar Context-Pipe, el conmutador universal que enruta datos nativamente a Semantic-Sift sin bloquear tu IDE.

Para herramientas de desarrollo (mypy, pytest):

uv pip install -e .[dev]

Binario Rust para instalaciones editables: pip install -e . omite el paso de compilación de Rust, por lo que sift-core no estará en tu PATH. En lugar de compilar desde el código fuente, descarga el binario precompilado para tu plataforma desde la versión correspondiente de GitHub en un solo comando:

python scripts/fetch_sift_core.py

Esto coloca sift-core[.exe] directamente en el directorio Scripts/bin de tu entorno activo. Vuelve a ejecutarlo cada vez que actualices la versión.

2. Conecta el MCP

CRÍTICO: Para rutas de configuración exactas para Cursor, Gemini, OpenCode, VS Code y Claude, consulta la Matriz Maestra de Configuración.

3. Auto-Onboarding

Una vez conectado, pregunta a tu Asistente de IA:

"Ejecuta sift_onboard() para configurar este proyecto."

📊 Comandos de Telemetría y Gestión

Semantic-Sift opera de forma invisible, pero siempre puedes auditar su rendimiento y ahorros de tokens sin quemar tokens de LLM para hacerlo.

  • CLI de Terminal:
    • Ejecuta semantic-sift-stats para imprimir un panel global de tus ahorros de tokens, latencia y aciertos de caché.
    • Ejecuta semantic-sift-onboard para inicializar manualmente Sift en cualquier proyecto (soporta --env y --dry-run).
  • Prompts MCP: Los clientes compatibles (Claude Desktop, Cursor, Zed) mostrarán un prompt sift_dashboard en su interfaz (a menudo a través de un comando de barra o botón) para inyectar instantáneamente tus estadísticas de telemetría en el chat.
  • OpenCode y CLI de Gemini: La herramienta sift_onboard() inyecta automáticamente comandos de barra personalizados nativos /sift-stats y /sift-onboard en la configuración de tu IDE.

🦀 Sidecar Rust Nativo (Aplicaciones Meechi y de Escritorio)

Para aplicaciones de alto rendimiento y locales primero (como Meechi), Semantic-Sift proporciona un binario nativo de Rust (sift-core). Este sidecar está optimizado para portabilidad y velocidad, con cero dependencias de Python.

🔀 El Motor Híbrido (semantic-sift-cli)

Para ofrecer lo mejor de ambos mundos, instalar el paquete de Python también expone el comando semantic-sift-cli. Este actúa como un Enrutador Inteligente:

  • Para tareas cortas (<30,000 caracteres), se conecta instantáneamente al Rust sift-core de baja latencia (ONNX).
  • Para tareas masivas por lotes, carga dinámicamente el framework PyTorch de alto rendimiento con Flash Attention para evitar la explosión de memoria.

Comparación de Características

CaracterísticaServidor MCP de PythonRust Sift-Core (Sidecar)
Cribado Heurístico de Registros✅✅ (Nativo)
Compresión Semántica✅ (PyTorch)✅ (ONNX)
Ingestión Multimodal✅ (vía [multi-modal])❌ (Solo Texto)
Formatos Soportados.pdf, .xlsx, .docx, .html, .txt.txt, .log, .out (Texto)
Latencia de Inicio3-5 segundos~10ms
Tamaño del Binario~1.5GB (con modelos)~15MB

Nota: Para aplicaciones nativas como Meechi, recomendamos una estrategia de Ingestión por Niveles: use el frontend de la aplicación (por ejemplo, pdf.js) para extraer texto, y luego envíelo al sidecar de Rust para un cribado semántico de alta velocidad.

✨ Ver Demo del 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 Operativo

Si eres un Agente de IA (por ejemplo, Gemini CLI, Cursor, Claude Code) leyendo este repositorio, sigue este protocolo:

  1. Inicialización: Llama a sift_onboard() para registrar hooks en segundo plano. Usa sift_onboard(dry_run=True) para previsualizar todas las acciones planificadas sin escribir ningún archivo.
  2. Asesoramiento de Contexto: Antes de leer archivos grandes (>1,000 caracteres), llama a sift_analyze_file(path) para determinar la proporción de ruido.
  3. Cribado Obligatorio: Si el ruido > 15%, canaliza los datos a través de sift_logs o sift_chat antes de incluirlos en el razonamiento. Para documentos, usa sift_doc(text, rate=0.4) — ajusta rate (0.1–0.9) para intercambiar profundidad de compresión por fidelidad.
  4. Clasificación: Usa sift_rank para identificar los fragmentos más relevantes semánticamente para la consulta del usuario.
  5. Extracción: Al destilar PDFs o contenido extraído, usa sift_extraction(content, show_diff=True) para ver exactamente qué se eliminó y verificar la fidelidad.

🛡️ Seguridad y Pruebas

Semantic-Sift está construido sobre una Línea Base de Cero Vulnerabilidades:

  • Pytest: 100% de tasa de aprobación en integridad heurística.
  • Bandit (SAST): Análisis estático automatizado para patrones de Python.
  • Pip-Audit (SCA): Monitoreo en tiempo real de la cadena de suministro para 0 vulnerabilidades conocidas.

Controles de privacidad y telemetría:

  • Establece SIFT_TELEMETRY_OPTED_IN=true para habilitar la telemetría (opt-in; deshabilitada por defecto).
  • Establece SIFT_TELEMETRY_DISABLED=true (interruptor de apagado heredado) para deshabilitar la telemetría por completo.
  • Establece SIFT_TELEMETRY_TTL_DAYS=90 (por defecto) para controlar cuántos días de historial de sesión se conservan en .pipe_telemetry.json antes de que se eliminen las entradas antiguas.
  • Establece SIFT_TELEMETRY_URL=https://your-endpoint para enrutar pulsos de metadatos a tu propio endpoint.
  • Establece SIFT_PULSE_RATE_LIMIT_S=10 (por defecto) para controlar la frecuencia de pulsos de telemetría asíncrona.

Controles de seguridad:

  • Establece SIFT_ALLOW_GLOBAL_READS=true para permitir sift_read_file / sift_analyze_file fuera de la raíz del espacio de trabajo (la protección contra traversal de rutas está activada por defecto).

Controles de rendimiento:

  • Establece SIFT_HOOK_TIMEOUT_MS=3000 para limitar la latencia semántica del hook antes de la fallback heurística.
  • Establece SIFT_MODEL_READY_WAIT_MS=1200 para controlar el tiempo de espera de calentamiento del modelo semántico antes de devolver la salida en modo heurístico.
  • Establece SIFT_COMPACTION_FIDELITY_THRESHOLD=0.3 (por defecto) para controlar el umbral de solapamiento de vocabulario por debajo del cual se emite una advertencia de compactación de baja fidelidad.
  • Establece SIFT_RANK_TOP_N=3 (por defecto) para establecer el número predeterminado de resultados devueltos por sift_rank a nivel de servidor cuando top_n no se pasa explícitamente.

Controles de registro de hooks:

  • Establece SIFT_LOG_FILE para sobrescribir la ruta del registro de hooks (por defecto: .gemini/sift_debug.log).
  • Establece SIFT_LOG_LEVEL (DEBUG, INFO, WARNING, ERROR) para controlar la verbosidad del registro de hooks.

Consulta SECURITY.md para nuestra política de seguridad completa.

El esquema de telemetría y los detalles del endpoint están documentados en doc/TELEMETRY_SPEC.md.

🔗 El Ecosistema (Studio of Two)

Semantic-Sift es un miembro insignia de la infraestructura Studio of Two. Está diseñado para trabajar en armonía de alta fidelidad con:

  • Context-Pipe: El conmutador universal para la ingeniería de contexto. Mientras Sift proporciona la inteligencia, Context-Pipe proporciona la orquestación. Recomendamos encarecidamente usar Context-Pipe para encadenar nodos de Sift con herramientas de enmascaramiento, búsqueda e ingestión multimodal.

⚖️ Licencia

Semantic-Sift está licenciado bajo la Apache License 2.0. Consulta LICENSE.md para más detalles.

🤝 Contribuciones

Semantic-Sift es de Código Abierto, pero Cerrado a Contribuciones.

Para mantener la estricta visión arquitectónica del "Studio of Two" y mantener el costo de mantenimiento en cero absoluto, este repositorio no acepta pull requests externos. Te animamos a usar, incrustar y bifurcar el código bajo la licencia permisiva Apache 2.0, pero por favor no envíes PRs para nuevas características o correcciones de errores. Consulta CONTRIBUTING.md para más detalles.