Obsify

obsify

Permite que un asistente de IA trabaje con archivos sensibles sin que sus valores crudos entren jamás en el contexto del modelo.

obsify es un servidor MCP local y determinista. El modelo de frontera razona sobre la forma — esquemas, gemelos sintéticos, retroalimentación enmascarada — mientras que el código local determinista toca la sustancia y devuelve solo resultados enmascarados y agregados. Sin llamadas a LLM, sin red en tiempo de ejecución: la detección es regex + sumas de verificación + diccionarios + Presidio's NER local.

Incluye soporte para entidades australianas (ABN / ACN / TFN, validados por suma de verificación), detección de credenciales/secretos (claves en la nube, tokens de API, claves privadas, cadenas de conexión a bases de datos), y una capa de enrutamiento impulsada por etiquetas que convierte "cuándo debe el asistente evitar datos crudos" en una decisión determinista y aplicada, no en un juicio subjetivo.

Alcance honesto: run_on_real ejecuta código escrito por el modelo en un sandbox local de mejor esfuerzo y enmascara su salida con el mejor esfuerzo. No es una cárcel. Lee SECURITY.md antes de apuntarlo a algo que no puedas permitirte filtrar. Devuelve agregados.

Por qué

Alimentar documentos confidenciales a un LLM alojado significa que la sustancia sale de tu perímetro. Las respuestas habituales son "no uses el LLM" o "confía en el proveedor". obsify toma un tercer camino — compute-to-data: lleva el código a los datos, no los datos al modelo.

• El modelo ve el esquema de una hoja de cálculo, no sus filas.
• El modelo desarrolla contra un gemelo sintético (valores falsos, estructura real).
• El código de análisis del modelo se ejecuta localmente; solo la salida enmascarada y agregada regresa.

El razonamiento del modelo de frontera se preserva. Solo se eliminan sus ojos sobre los valores crudos.

Herramientas

Herramienta	Qué hace	Devuelve
scan_pii(path)	Escanea un archivo/carpeta en busca de PII	Tipos, ubicaciones, conteos — nunca valores
make_synthetic_twin(path, out)	Gemelo fiel y falso de un libro de Excel	Resumen del esquema; gemelo escrito en out (valores falsificados, verificado sin fugas)
run_on_real(code, data_path)	Compute-to-data: ejecuta tu código localmente contra el archivo real (vinculado a DATA_PATH)	Solo stdout/stderr enmascarado de PII y con límite de tamaño — devuelve agregados
redact_text(text)	Enmascara PII en una cadena a tokens <TYPE>	La cadena redactada
verify_value_free(text, terms)	Verificación de cierre por fallo de que text no filtra ninguno de terms (o sus variantes)	{"value_free": bool}

Documentos admitidos: PDF (texto + tablas; respaldo para tablas complejas vía obsify[tables]), Excel .xlsx/.xlsm, y Word .docx (párrafos + tablas). Los archivos ilegibles o no admitidos se muestran como notas/blind spots explícitos, nunca se descartan silenciosamente. (Sin OCR todavía — las páginas escaneadas/de imagen se marcan como de baja cobertura, no se transcriben.)

Enmascaramiento de entidades conocidas (opcional). Proporciona una lista local .obsify.entities de nombres a ocultar; scan_pii / redact_text los detectan de forma determinista — y las variantes de sufijo/abreviatura que NER omite (BRIGHTWATER HLDGS P/L para Brightwater Holdings Pty Ltd) — como KNOWN_ENTITY. La lista permanece local y nunca entra en el contexto del modelo. Ver docs/known_entities.md.

Demo

Prueba las cinco herramientas en vivo contra datos sintéticos con el MCP Inspector oficial:

python -m obsify.make_corpus --out ./corpus_demo
npx @modelcontextprotocol/inspector obsify-mcp

Llama a scan_pii en ./corpus_demo/ledger.xlsx y confirma que devuelve solo tipos / conteos / ubicaciones — nunca valores. Ver docs/verifying.md.

Pruébalo — corpus sintético

Genera un corpus falso pero realista (todo sintético; ABN/ACN/TFN validados por suma de verificación) que abarque los tres formatos, y luego apunta una herramienta hacia él:

pip install "obsify[demo]"                 # reportlab, for the sample PDFs
python -m obsify.make_corpus --out ./corpus_demo

Escribe un libro de Excel de varias hojas (un campo minado de falsos positivos numéricos), una carta de compromiso en PDF (prosa + tabla de balanza de comprobación), y un memorando de auditoría en DOCX (párrafos + tabla de proveedores). Genial para probar scan_pii / make_synthetic_twin sin tocar datos reales.

Instalación y ejecución como servidor MCP

Requiere Python 3.11+. obsify habla MCP sobre stdio — el cliente lo lanza como un subproceso local; nada se aloja de forma remota. Regístralo con cualquier cliente compatible con MCP (Claude Desktop, Claude Code, Cursor, VS Code, …) añadiendo un bloque a la configuración de ese cliente.

Recomendado — instalación cero vía uvx:

{ "mcpServers": { "obsify": { "command": "uvx", "args": ["--from", "obsify", "obsify-mcp"] } } }

uvx obtiene obsify de PyPI y lo ejecuta bajo demanda — sin instalación permanente. En la primera ejecución, obsify descarga el modelo NER de spaCy (en_core_web_lg, ~560 MB) una vez y lo almacena en caché; esto obtiene un modelo público y no envía datos de usuario (establece OBSIFY_AUTO_DOWNLOAD=0 para prohibirlo e instala el modelo tú mismo). Las ejecuciones posteriores son instantáneas y totalmente sin conexión.

O instálalo (pip / pipx):

pipx install obsify        # isolated, on PATH  (or: pip install obsify)

Luego apunta el cliente al comando instalado:

{ "mcpServers": { "obsify": { "command": "obsify-mcp" } } }

Reinicia el cliente y las herramientas aparecen. Extras opcionales: obsify[tables] (respaldo de PDF con tablas complejas vía camelot + Ghostscript), obsify[compute] (pandas, útil dentro del código run_on_real).

Problema de PATH (la causa #1 de "el servidor no conecta"): el command debe resolverse en el PATH que ve el cliente. Un cliente GUI puede no compartir el PATH de tu venv. Soluciones: usa uvx/pipx (resolubles globalmente), o da una ruta absoluta — "/path/to/.venv/bin/obsify-mcp" (macOS/Linux) o "C:\\path\\to\\.venv\\Scripts\\obsify-mcp.exe" (Windows).

Desde este repositorio (antes de que esté en PyPI):

pip install "git+https://github.com/Formative-Sum41/obsify.git"   # gets `obsify-mcp` + `obsify`

La capa de enrutamiento — determinista, no un juicio subjetivo

La parte difícil de "ayúdame, pero no leas el archivo confidencial" es decidir cuándo proteger. obsify saca esa decisión del modelo y la pone en el entorno:

1. .obsify.json — un manifiesto de etiquetas que clasifica rutas (public / confidential / restricted).
2. obsify.guard (ejecutado como python -m obsify.guard) — un guardia PreToolUse que bloquea la lectura directa de un archivo etiquetado (salida 2) y redirige al asistente a scan_pii / make_synthetic_twin / run_on_real.
3. Una convención (en CLAUDE.md) para que el asistente prefiera obsify antes incluso de llegar al guardia.

Configúralo con un comando:

obsify init [--dir PATH] [--with-claude-md]

obsify init es no destructivo por diseño — posee exactamente un archivo y te entrega fragmentos para el resto:

• .obsify.json — obsify lo posee; init lo escribe (nunca se sobrescribe sin --force).
• .claude/settings.json — tu archivo: init imprime el bloque del hook PreToolUse para que lo pegues, nunca lo edita (ejecuta código, así que registrarlo es tu decisión).
• CLAUDE.md — tu archivo: la convención es opt-in. Por defecto la imprime; --with-claude-md añade un bloque idempotente envuelto en marcadores que nunca sobrescribe tu contenido.

Convención completa: docs/obsify_routing.md.

Cómo la detección se mantiene precisa

• Identificadores validados por suma de verificación. Los candidatos ABN/ACN/TFN se proponen por regex y se confirman por sus sumas de verificación oficiales, por lo que un número aleatorio nunca se reporta como identificador.
• IDs que requieren contexto. Un número desnudo solo se acepta como ABN/ACN/TFN cuando una palabra etiqueta ("TFN", "ABN", "BSB", …) está cerca — esto elimina la inundación de falsos positivos de IDs de diario secuencial en libros numéricos.
• Supresión de sin letras / NER con dígitos. Números puros, cantidades, fechas y códigos alfanuméricos no se marcan como nombres/orgs; los nombres reales, correos y direcciones (que llevan letras) no se ven afectados. La PII validada sin letras permanece exenta: IDs con suma de verificación (ABN/ACN/TFN/Medicare), tarjetas Luhn, IPs válidas, cuentas adyacentes a BSB, y teléfonos (vía contexto o forma de teléfono) — mientras que un punto decimal aún marca una cantidad, no un teléfono.
• Credenciales, no solo PII. Claves en la nube (AWS/GitHub/Google/Slack/Stripe), JWTs, bloques de claves privadas y cadenas de conexión a bases de datos se marcan como CREDENTIAL por patrones anclados — prefijos de proveedor (AKIA…, ghp_…) o un secret = <value> con puerta de palabra clave, nunca heurísticas de entropía (que inundarían con columnas de libro hexadecimales/base64). Todo el bloque de clave privada BEGIN…END se enmascara, no solo su encabezado, para que no quede ningún cuerpo de clave.

Precisión medida

obsify incluye un harness de evaluación puntuado (eval/ — corpus sintético etiquetado + clave de respuestas + puntuador contra el detector de producción, más una verificación cruzada independiente de terceros). Titular en el corpus sintético: 100% de recall en elementos de detección esperados, 0 falsos positivos en una hoja de tortura numérica de FP (con un guardia de números agrupados), IDs con puerta de contexto desnudos correctamente suprimidos. Verificación cruzada independiente vs Microsoft presidio-research: EMAIL/IBAN 100%, PERSON 94%.

El harness se ganó su lugar — encontró defectos reales, que luego se corrigieron: las tarjetas de crédito y los números de teléfono se suprimían silenciosamente por el filtro de ruido numérico (ahora exentos vía validación de suma de verificación / forma de teléfono), y Medicare, IP, fecha de nacimiento, pasaporte australiano y licencia de conducir no tenían reconocedor (ahora añadidos, con puerta de suma de verificación o contexto). Método completo, números y brechas documentadas restantes (SWIFT/BIC, fechas no DOB): eval/README.md.

Pruebas

pip install -e ".[dev]"
pytest tests/            # or run any file directly: python tests/test_obsify.py

Trece suites (88 pruebas), ejecutadas en CI en Linux + Windows / Python 3.11 + 3.12:

• mcp-protocol — lanza el servidor real sobre stdio y le habla MCP (el mismo camino que un cliente como Claude usa): confirma que las cinco herramientas se registran con esquemas válidos y que las llamadas hacen round-trip a través de JSON-RPC — incluyendo scan_pii devolviendo solo forma, de extremo a extremo.
• checksums — anclado a ejemplos trabajados ABN/ACN/TFN publicados externamente (válidos y corruptos), lo que rompe la circularidad generador↔validador.
• obsify / twin / redaction — los invariantes de privacidad: salida solo de forma, gemelos sin fugas, y una auto-verificación de cierre por fallo.
• precision — los supresores de falsos positivos eliminan el ruido de libros numéricos mientras mantienen nombres reales.
• credentials — los patrones de secretos anclados detectan claves en la nube / tokens / JWTs / bloques de claves privadas / cadenas de conexión, mientras que los genéricos con anclaje de palabra clave se mantienen precisos en prosa (sin entropía).
• routing — la clasificación de bloqueo/permiso del guardia y el contrato no destructivo de obsify init.
• corpus — el corpus sintético PDF+Excel+DOCX de extremo a extremo: detección por formato, extracción de párrafos+tablas de DOCX, y salida solo de forma en cada formato.
• evaluation — el harness puntuado como puerta de regresión (recall, supresión, tortura de FP, brechas).
• robustness — degradación elegante: entradas corruptas/sobredimensionadas/vacías/anidadas/no admitidas nunca fallan y siempre se muestran como notas.
• model / variants — lógica de descarga automática del modelo en primera ejecución; normalización de variantes detrás de verify_value_free.

Para verificación interactiva (MCP Inspector) y la verificación de último tramo con cliente en vivo, ver docs/verifying.md.

Trabajo relacionado

obsify es uno de varios servidores MCP que abordan "deja que una IA toque datos sensibles de forma segura" — son en su mayoría complementarios, resolviendo el mismo problema desde extremos diferentes. Vale la pena saber dónde encaja cada uno:

Herramienta	Enfoque	Mejor para
obsify	Detección + aislamiento de forma: el modelo solo ve forma, gemelos sintéticos y agregados enmascarados — nunca los valores (reales o falsos)	Documentos desordenados y no estructurados (PDF/Excel/DOCX) donde no puedes enumerar PII de antemano; aislamiento estricto de valores; aplicación de cuándo proteger
cloakbox	Pre-saneamiento basado en políticas: tokeniza una base de datos en una copia desidentificada que el modelo consulta libremente	Esquemas conocidos y estructurados donde quieres análisis enriquecidos (joins/agregaciones) sobre una copia limpia referencialmente intacta
redact-mcp	Proxy de ofuscación reversible: el modelo trabaja con datos falsos consistentes; una herramienta proxy hace el viaje de ida y vuelta con llamadas API reales	Flujos de trabajo de pentest y secretos, donde el modelo debe operar con datos realistas y restauras los reales después
cms-ai	Servicio empresarial de redacción: Presidio + spaCy detrás de REST/MCP, multilingüe, escalable	Una API de redacción multilingüe alojada con interfaz de usuario y escala horizontal

Donde obsify es distinto: es el único de estos donde el modelo no recibe ni valores crudos ni un espejo completo para operar — solo forma + agregados enmascarados — combinado con identificadores validados por checksum, detección de credenciales, un guardia de enrutamiento determinista y una garantía estricta de sin-red / sin-LLM. Ese es el extremo de aislamiento más estricto del espectro, ajustado para documentos financieros confidenciales.

Compensación honesta: obsify optimiza el aislamiento de los valores sobre la utilidad de los datos. Si necesitas análisis referencialmente intactos sobre una copia limpia (cloakbox), viajes de ida y vuelta reversibles (redact-mcp), o un servicio alojado multilingüe (cms-ai), esos son la mejor opción — y se complementan bien con obsify en lugar de competir con él.

Contribuciones

Se aceptan PRs — consulta CONTRIBUTING.md para la configuración, el estándar de fusión y los invariantes no negociables (sin llamadas LLM en la biblioteca, sin red en tiempo de ejecución, sin datos reales, forma-no-sustancia). Problemas de seguridad: SECURITY.md (reporta de forma privada).

Licencia

MIT — consulta LICENSE.