obsify

Позвольте ИИ-ассистенту работать с конфиденциальными файлами, не допуская попадания их исходных значений в контекст модели.

obsify — это локальный, детерминированный MCP-сервер. Пограничная модель рассуждает о форме — схемах, синтетических двойниках, маскированной обратной связи — в то время как детерминированный локальный код касается сути и возвращает только маскированные, агрегированные результаты. Никаких вызовов LLM, никакой сети во время выполнения: обнаружение — это регулярные выражения + контрольные суммы + словари + локальный NER от Presidio.

Он поставляется с поддержкой австралийских сущностей (ABN / ACN / TFN, с проверкой контрольной суммы) и управляемым метками уровнем маршрутизации, который превращает вопрос «когда ассистенту следует избегать исходных данных» из оценочного суждения в детерминированное, принудительное решение.

Честная область применения: run_on_real выполняет написанный моделью код в песочнице с максимальными усилиями и маскирует его вывод с максимальными усилиями. Это не тюрьма. Прочтите SECURITY.md, прежде чем направлять его на что-либо, утечку чего вы не можете себе позволить. Возвращайте агрегаты.

Зачем

Передача конфиденциальных документов размещенной LLM означает, что суть покидает ваш периметр. Обычные ответы — «не используйте LLM» или «доверяйте провайдеру». obsify выбирает третий путь — вычисления к данным: принесите код к данным, а не данные к модели.

• Модель видит схему электронной таблицы, а не ее строки.

• Модель разрабатывается на основе синтетического двойника (фальшивые значения, реальная структура).

• Код анализа модели выполняется локально; возвращается только маскированный, агрегированный вывод.

Рассуждения пограничной модели сохраняются. Удаляется только ее взгляд на исходные значения.

Related MCP server: Cloakbox

Инструменты

Поддерживаемые документы: PDF (текст + таблицы; запасной вариант для сложных таблиц через obsify[tables]), Excel .xlsx/.xlsm и Word .docx (абзацы + таблицы). Нечитаемые или неподдерживаемые файлы отображаются как явные примечания/слепые зоны, никогда не отбрасываются молча. (Пока нет OCR — отсканированные/изображенные страницы помечаются как низкопокрытие, не транскрибируются.)

Маскирование известных сущностей (опционально). Предоставьте локальный список .obsify.entities имен для скрытия; scan_pii / redact_text детерминированно их ловят — а также варианты суффиксов/аббревиатур, которые NER пропускает (BRIGHTWATER HLDGS P/L для Brightwater Holdings Pty Ltd) — как KNOWN_ENTITY. Список остается локальным и никогда не попадает в контекст модели. См. docs/known_entities.md.

Демонстрация

Пощупайте все пять инструментов вживую на синтетических данных с помощью официального MCP Inspector:

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

Вызовите scan_pii на ./corpus_demo/ledger.xlsx и убедитесь, что он возвращает только типы / количество / местоположения — никогда значения. См. docs/verifying.md.

Попробуйте — синтетический корпус

Сгенерируйте поддельный, но реалистичный корпус (все синтетическое; ABN/ACN/TFN проверены контрольной суммой), охватывающий все три формата, затем наведите на него инструмент:

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

Он создает многолистовой реестр Excel (числовое минное поле ложных срабатываний), PDF-письмо о назначении (проза + таблица оборотно-сальдовой ведомости) и DOCX-меморандум аудита (абзацы + таблица поставщиков). Отлично подходит для обкатки scan_pii / make_synthetic_twin без касания реальных данных.

Установка и запуск в качестве MCP-сервера

Требуется Python 3.11+. obsify общается по MCP через stdio — клиент запускает его как локальный подпроцесс; ничего не размещается удаленно. Зарегистрируйте его в любом клиенте, поддерживающем MCP (Claude Desktop, Claude Code, Cursor, VS Code, …), добавив один блок в конфигурацию этого клиента.

Рекомендуется — установка без установки через uvx:

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

uvx загружает obsify из PyPI и запускает его по требованию — без постоянной установки. При первом запуске obsify загружает модель NER spaCy (en_core_web_lg, ~560 МБ) один раз и кэширует ее; загружается публичная модель, пользовательские данные не отправляются (установите OBSIFY_AUTO_DOWNLOAD=0, чтобы запретить это и установить модель самостоятельно). Последующие запуски мгновенны и полностью офлайн.

Или установите (pip / pipx):

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

Затем укажите клиенту на установленную команду:

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

Перезапустите клиент, и инструменты появятся. Дополнительные опции: obsify[tables] (запасной вариант для сложных таблиц PDF через camelot + Ghostscript), obsify[compute] (pandas, удобно внутри кода run_on_real).

Подводный камень PATH (основная причина «сервер не подключается»): command должен разрешаться в PATH, который видит клиент. GUI-клиент может не разделять PATH вашего виртуального окружения. Исправления: используйте uvx/pipx (глобально разрешаемый), или укажите абсолютный путь — "/path/to/.venv/bin/obsify-mcp" (macOS/Linux) или "C:\\path\\to\\.venv\\Scripts\\obsify-mcp.exe" (Windows).

Из этого репозитория (до публикации на PyPI):

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

Уровень маршрутизации — детерминированный, а не оценочное суждение

Сложная часть «помоги мне, но не читай конфиденциальный файл» — это решение, когда защищать. obsify переносит это решение из модели в среду:

1. .obsify.json — манифест меток, классифицирующий пути (public / confidential / restricted).

2. obsify.guard (запуск python -m obsify.guard) — защита PreToolUse, которая блокирует прямое чтение помеченного файла (код выхода 2) и перенаправляет ассистента на scan_pii / make_synthetic_twin / run_on_real.

3. Соглашение (в CLAUDE.md), чтобы ассистент предпочитал obsify до того, как столкнется с защитой.

Настройте одной командой:

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

obsify init неразрушающий по замыслу — он владеет ровно одним файлом и предоставляет вам фрагменты для остального:

• .obsify.json — obsify владеет этим; init записывает его (никогда не перезаписывается без --force).

• .claude/settings.json — ваш файл: init выводит блок хука PreToolUse для вставки, никогда не редактирует его (он выполняет код, поэтому регистрация — ваше решение).

• CLAUDE.md — ваш файл: соглашение опционально. По умолчанию выводится; --with-claude-md добавляет обернутый маркером, идемпотентный блок, который никогда не затирает ваш контент.

Полное соглашение: docs/obsify_routing.md.

Как обнаружение остается точным

• Идентификаторы с проверкой контрольной суммы. Кандидаты ABN/ACN/TFN предлагаются регулярным выражением и подтверждаются официальными контрольными суммами, поэтому случайное число никогда не сообщается как идентификатор.

• Идентификаторы, требующие контекста. Голое число принимается как ABN/ACN/TFN только тогда, когда рядом есть слово-метка ("TFN", "ABN", "BSB", …) — это устраняет поток ложных срабатываний последовательных идентификаторов журналов в числовых реестрах.

• Подавление безбуквенных / NER с цифрами. Чистые числа, суммы, даты и буквенно-цифровые коды не помечаются как имена/организации; реальные имена, email-адреса и адреса (которые содержат буквы) не затрагиваются. Проверенные безбуквенные PII остаются исключенными: идентификаторы с контрольной суммой (ABN/ACN/TFN/Medicare), карты Luhn, допустимые IP-адреса, счета рядом с BSB и телефоны (через контекст или форму телефона) — в то время как десятичная точка по-прежнему обозначает сумму, а не телефон.

Измеренная точность

obsify поставляется с оценочной обвязкой (eval/ — размеченный синтетический корпус + ключ ответов + оценщик против поставляемого детектора, плюс независимая сторонняя перекрестная проверка). Заголовок на синтетическом корпусе: 100% полнота по ожидаемым для обнаружения элементам, 0 ложных срабатываний на числовом листе FP-пыток (с защитой от групповых номеров), голые контекстно-ограниченные ID корректно подавлены. Независимая перекрестная проверка против Microsoft presidio-research: EMAIL/IBAN 100%, PERSON 94%.

Обвязка оправдала себя — она нашла реальные дефекты, которые были затем исправлены: кредитные карты и номера телефонов молча подавлялись фильтром числового шума (теперь исключены через проверку контрольной суммы / форму телефона), а Medicare, IP, дата рождения, австралийский паспорт и водительские права не имели распознавателя (теперь добавлены, с проверкой контрольной суммы или контекстом). Полный метод, цифры и оставшиеся задокументированные пробелы (SWIFT/BIC, даты не-ДР): eval/README.md.

Тесты

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

Двенадцать наборов (73 теста), запускаемых в CI на Linux + Windows / Python 3.11 + 3.12:

• mcp-protocol — запускает реальный сервер через stdio и общается с ним по MCP (тот же путь, что использует клиент вроде Claude): подтверждает, что все пять инструментов регистрируются с корректными схемами и что вызовы проходят полный цикл через JSON-RPC — включая scan_pii, возвращающий только форму, от начала до конца.

• checksums — привязаны к опубликованным внешним примерам ABN/ACN/TFN (корректным и поврежденным), что разрывает циклическую зависимость генератор↔валидатор.

• obsify / twin / redaction — инварианты приватности: вывод только формы, двойники без утечек и самопроверка с отказом по умолчанию.

• precision — подавители ложных срабатываний устраняют шум числового реестра, сохраняя реальные имена.

• routing — классификация блокировки/разрешения защиты и неразрушающий контракт obsify init.

• corpus — синтетический корпус PDF+Excel+DOCX от начала до конца: обнаружение по форматам, извлечение абзацев+таблиц DOCX и вывод только формы для каждого формата.

• evaluation — оценочная обвязка как регрессионный шлюз (полнота, подавление, FP-пытки, пробелы).

• robustness — корректная деградация: поврежденные/слишком большие/пустые/вложенные/неподдерживаемые входные данные никогда не вызывают сбой и всегда отображаются как примечания.

• model / variants — логика автоматической загрузки модели при первом запуске; нормализация вариантов за verify_value_free.

Для интерактивной проверки (MCP Inspector) и проверки последней мили в живом клиенте см. docs/verifying.md.

Лицензия

MIT — см. LICENSE.