obsify

Lassen Sie einen KI-Assistenten an sensiblen Dateien arbeiten, ohne dass deren Rohwerte jemals in den Kontext des Modells gelangen.

obsify ist ein lokaler, deterministischer MCP-Server. Das Frontier-Modell denkt über die Struktur nach – Schemata, synthetische Zwillinge, maskiertes Feedback – während deterministischer lokaler Code die Substanz berührt und nur maskierte, aggregierte Ergebnisse zurückgibt. Keine LLM-Aufrufe, kein Netzwerk zur Laufzeit: Erkennung erfolgt per Regex + Prüfsummen + Wörterbücher + Presidio's lokalem NER.

Es wird mit australischer Entitätsunterstützung (ABN / ACN / TFN, prüfsummenvalidiert) und einer labelgesteuerten Routing-Ebene ausgeliefert, die „Wann sollte der Assistent Rohdaten vermeiden“ zu einer deterministischen, erzwungenen Entscheidung und nicht zu einer Ermessensentscheidung macht.

Ehrlicher Geltungsbereich: run_on_real führt modellgeschriebenen Code in einer Best-Effort-lokalen Sandbox aus und maskiert dessen Ausgabe Best-Effort. Es ist kein Gefängnis. Lesen Sie SECURITY.md, bevor Sie es auf etwas richten, dessen Verlust Sie sich nicht leisten können. Geben Sie Aggregate zurück.

Warum

Die Einspeisung vertraulicher Dokumente in ein gehostetes LLM bedeutet, dass die Substanz Ihre Grenzen verlässt. Die üblichen Antworten sind „Verwenden Sie das LLM nicht“ oder „Vertrauen Sie dem Anbieter.“ obsify geht einen dritten Weg — Compute-to-Data: Bringen Sie den Code zu den Daten, nicht die Daten zum Modell.

• Das Modell sieht das Schema einer Tabelle, nicht ihre Zeilen.

• Das Modell entwickelt anhand eines synthetischen Zwillings (gefälschte Werte, echte Struktur).

• Der Analysecode des Modells wird lokal ausgeführt; nur maskierte, aggregierte Ausgabe wird zurückgegeben.

Das Denken des Frontier-Modells bleibt erhalten. Nur seine Augen auf Rohwerte werden entfernt.

Related MCP server: Cloakbox

Werkzeuge

Unterstützte Dokumente: PDF (Text + Tabellen; komplexe Tabellen-Fallback via obsify[tables]), Excel .xlsx/.xlsm und Word .docx (Absätze + Tabellen). Nicht lesbare oder nicht unterstützte Dateien werden als explizite Hinweise/blinde Flecken ausgewiesen, niemals stillschweigend verworfen. (Noch keine OCR — gescannte/Bild- Seiten werden als abdeckungsarm gekennzeichnet, nicht transkribiert.)

Maskierung bekannter Entitäten (optional). Stellen Sie eine lokale .obsify.entities-Liste mit zu verbergenden Namen bereit; scan_pii / redact_text fangen sie deterministisch ab – sowie die Suffix-/Abkürzungsvarianten, die NER übersieht (BRIGHTWATER HLDGS P/L für Brightwater Holdings Pty Ltd) – als KNOWN_ENTITY. Die Liste bleibt lokal und gelangt niemals in den Kontext des Modells. Siehe docs/known_entities.md.

Demo

Testen Sie alle fünf Werkzeuge live gegen synthetische Daten mit dem offiziellen MCP Inspector:

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

Rufen Sie scan_pii für ./corpus_demo/ledger.xlsx auf und bestätigen Sie, dass es nur Typen / Anzahlen / Orte zurückgibt – niemals Werte. Siehe docs/verifying.md.

Testen Sie es – synthetisches Korpus

Generieren Sie ein gefälschtes, aber realistisches Korpus (alles synthetisch; ABN/ACN/TFN sind prüfsummenvalidiert), das alle drei Formate umfasst, und richten Sie dann ein Werkzeug darauf:

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

Es schreibt eine mehrblättrige Excel-Tabelle (ein numerisches False-Positive-Minenfeld), ein PDF-Anschreiben (Prosatext + Probebilanz-Tabelle) und ein DOCX-Prüfvermerk (Absätze + Lieferantentabelle). Großartig, um die Reifen von scan_pii / make_synthetic_twin zu testen, ohne echte Daten zu berühren.

Installation und Ausführung als MCP-Server

Erfordert Python 3.11+. obsify spricht MCP über stdio – der Client startet es als lokalen Unterprozess; nichts wird remote gehostet. Registrieren Sie es bei jedem MCP-fähigen Client (Claude Desktop, Claude Code, Cursor, VS Code, …), indem Sie einen Block zur Konfiguration dieses Clients hinzufügen.

Empfohlen – Installation ohne Installation via uvx:

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

uvx holt obsify von PyPI und führt es bei Bedarf aus – keine dauerhafte Installation. Beim ersten Start laden Sie das spaCy NER-Modell (en_core_web_lg, ~560 MB) einmal herunter und zwischenspeichern es; dies holt ein öffentliches Modell und sendet keine Benutzerdaten (setzen Sie OBSIFY_AUTO_DOWNLOAD=0, um es zu verbieten und das Modell selbst zu installieren). Spätere Ausführungen sind sofort und vollständig offline.

Oder installieren Sie es (pip / pipx):

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

Dann weisen Sie den Client auf den installierten Befehl:

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

Starten Sie den Client neu und die Werkzeuge erscheinen. Optionale Extras: obsify[tables] (komplexe Tabellen-PDF- Fallback via camelot + Ghostscript), obsify[compute] (pandas, praktisch innerhalb von run_on_real-Code).

PATH-Falle (Hauptgrund Nr. 1 für „Server verbindet nicht“): Der command muss im PATH aufgelöst werden können, den der Client sieht. Ein GUI-Client teilt möglicherweise nicht den PATH Ihrer venv. Lösungen: Verwenden Sie uvx/pipx (global auflösbar) oder geben Sie einen absoluten Pfad an – "/pfad/zu/.venv/bin/obsify-mcp" (macOS/Linux) oder "C:\\pfad\zu\\.venv\\Scripts\\obsify-mcp.exe" (Windows).

Aus diesem Repository (bevor es auf PyPI ist):

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

Die Routing-Ebene – deterministisch, keine Ermessensentscheidung

Der schwierige Teil von „Hilf mir, aber lies die vertrauliche Datei nicht“ ist die Entscheidung, wann geschützt werden muss. obsify verlagert diese Entscheidung aus dem Modell in die Umgebung:

1. .obsify.json – ein Label-Manifest, das Pfade klassifiziert (public / confidential / restricted).

2. obsify.guard (ausgeführt als python -m obsify.guard) – ein PreToolUse-Guard, der das direkte Lesen einer gelabelten Datei blockiert (Exit 2) und den Assistenten an scan_pii / make_synthetic_twin / run_on_real weiterleitet.

3. Eine Konvention (in CLAUDE.md), sodass der Assistent obsify bevorzugt, bevor er überhaupt auf den Guard trifft.

Richten Sie es mit einem Befehl ein:

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

obsify init ist von Grund auf nicht destruktiv – es besitzt genau eine Datei und gibt Ihnen Schnipsel für den Rest:

• .obsify.json – obsify besitzt dies; init schreibt es (niemals ohne --force überschrieben).

• .claude/settings.json – Ihre Datei: init gibt den PreToolUse-Hook-Block zum Einfügen aus, bearbeitet ihn nie (da er Code ausführt, ist die Registrierung Ihre Entscheidung).

• CLAUDE.md – Ihre Datei: die Konvention ist opt-in. Standardmäßig wird sie ausgegeben; --with-claude-md hängt einen markierungsumschlossenen, idempotenten Block an, der Ihren Inhalt niemals überschreibt.

Vollständige Konvention: docs/obsify_routing.md.

Wie die Erkennung präzise bleibt

• Prüfsummenvalidierte Identifikatoren. ABN/ACN/TFN-Kandidaten werden per Regex vorgeschlagen und durch ihre offiziellen Prüfsummen bestätigt, sodass eine zufällige Zahl niemals als Identifikator gemeldet wird.

• Kontextabhängige IDs. Eine bloße Zahl wird nur dann als ABN/ACN/TFN akzeptiert, wenn ein Label-Wort („TFN“, „ABN“, „BSB“, …) in der Nähe ist – dies unterdrückt die False-Positive-Flut durch sequenzielle Journal-IDs in numerischen Tabellen.

• Buchstabenlose / NER-mit-Ziffern-Unterdrückung. Reine Zahlen, Beträge, Daten und alphanumerische Codes werden nicht als Namen/Organisationen gekennzeichnet; echte Namen, E-Mails und Adressen (die Buchstaben enthalten) sind nicht betroffen. Validierte buchstabenlose PII bleibt ausgenommen: Prüfsummen-IDs (ABN/ACN/TFN/Medicare), Luhn-Karten, gültige IPs, BSB-bezogene Konten und Telefone (via Kontext oder Telefonform) – während ein Dezimalpunkt immer noch einen Betrag und kein Telefon kennzeichnet.

Gemessene Genauigkeit

obsify wird mit einem bewerteten Evaluierungs-Framework ausgeliefert (eval/ – beschriftetes synthetisches Korpus + Antwortschlüssel + Bewerter gegen den ausgelieferten Detektor, plus eine unabhängige Drittanbieter-Kreuzprüfung). Überschrift auf dem synthetischen Korpus: 100 % Recall bei erwarteten Erkennungselementen, 0 False Positives auf einer numerischen FP-Foltertabelle (mit einer gruppierten Zahlensperre), bloße kontextabhängige IDs korrekt unterdrückt. Unabhängige Kreuzprüfung vs. Microsoft presidio-research: EMAIL/IBAN 100 %, PERSON 94 %.

Das Framework hat sich bezahlt gemacht – es fand echte Fehler, die dann behoben wurden: Kreditkarten und Telefonnummern wurden stillschweigend durch den numerischen Rauschfilter unterdrückt (jetzt ausgenommen via Prüfsummen- validierung / Telefonform), und Medicare, IP, Geburtsdatum, AU-Pass und Führerschein hatten keinen Erkenner (jetzt hinzugefügt, prüfsummen- oder kontextabhängig). Vollständige Methode, Zahlen und verbleibende dokumentierte Lücken (SWIFT/BIC, Nicht-Geburtsdaten): eval/README.md.

Tests

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

Zwölf Suiten (73 Tests), ausgeführt in CI unter Linux + Windows / Python 3.11 + 3.12:

• mcp-protocol – startet den echten Server über stdio und spricht MCP mit ihm (derselbe Weg, den ein Client wie Claude verwendet): bestätigt, dass alle fünf Werkzeuge mit gültigen Schemata registriert sind und dass Aufrufe durch JSON-RPC hin und zurück gehen – einschließlich scan_pii, das nur die Struktur, Ende-zu-Ende zurückgibt.

• checksums – verankert an extern veröffentlichten ABN/ACN/TFN-Arbeitsbeispielen (gültig und korrupt), was die Generator↔Validator-Zirkularität durchbricht.

• obsify / twin / redaction – die Datenschutzinvarianten: nur Strukturausgabe, leak-freie Zwillinge und eine Fail-Closed-Selbstprüfung.

• precision – die False-Positive-Unterdrücker töten numerisches Tabellenrauschen, während echte Namen erhalten bleiben.

• routing – die Block-/Erlaubnis-Klassifizierung des Guards und der nicht-destruktive Vertrag von obsify init.

• corpus – das synthetische PDF+Excel+DOCX-Korpus Ende-zu-Ende: formatbezogene Erkennung, DOCX- Absatz+Tabellen-Extraktion und nur Strukturausgabe über jedes Format.

• evaluation – das bewertete Framework als Regressionstor (Recall, Unterdrückung, FP-Folter, Lücken).

• robustness – Graceful Degradation: korrupte/überdimensionierte/leere/verschachtelte/nicht unterstützte Eingaben stürzen nie ab und werden immer als Hinweise ausgewiesen.

• model / variants – Logik zum automatischen Herunterladen des Modells beim ersten Start; Variantennormalisierung hinter verify_value_free.

Für interaktive Verifizierung (MCP Inspector) und die letzte Meile des Live-Clients siehe docs/verifying.md.

Lizenz

MIT – siehe LICENSE.