Bathys

Единый локальный поисковый сервис глубокого ресёрча для ИИ-агентов. Это самостоятельный продукт, а не обёртка над чужими сервисами: Bathys реализует весь конвейер сам — метапоиск с дедупликацией и живучестью к блокировкам, двухъярусное извлечение (HTTP-движок по умолчанию, headless-браузер только для JS-страниц), пятистадийную дистилляцию под запрос с жёсткими бюджетами, TTL-кэш сырца, robots-этику, метрики и диагностику. Метапоиск и извлечение оформлены как сменные внутренние движки (SearXNG, Crawl4AI) — их можно заменить, продукт останется Bathys. Облачных квот нет; LLM внутри нет — синтез остаётся за вызывающим агентом, дистилляция детерминированная (BM25).

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

Навигация: ⚡ Quick start · 🧹 Удаление · 🔌 Подключение · 🧠 Научить агента · 🧭 Кейсы · 🛠 Инструменты · 📊 Экономия токенов · 📚 Документация · 📍 Статус

⚡ Quick start

Вариант 1 — установочный скрипт (рекомендуется; Python ≥ 3.10):

curl -fsSL https://raw.githubusercontent.com/Korrnals/bathys/main/install.sh | bash

Скрипт ставит пакет с PyPI в приватный venv (~/.local/share/bathys/venv, без sudo), добавляет его в PATH и запускает полную настройку. Повторный запуск — безопасное обновление.

Вариант 2 — pip (то же самое вручную):

pip install bathys
bathys setup

Что делает bathys setup:

SearXNG устанавливать отдельно не нужно — бэкенд поднимается автоматически при первом поиске: сначала проверяется внешний инстанс, затем docker/podman, затем нативный режим (клон в BATHYS_SEARXNG_HOME).

npm install -g bathys-mcp
bathys-mcp setup

git clone https://github.com/Korrnals/bathys.git && cd bathys
python3.12 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/bathys setup

BATHYS_INSTALL_VERSION=0.7.0 bash install.sh

🧹 Удаление

bathys uninstall               # снять Bathys со всех харнессов
bathys uninstall hermes zcode   # точечно, только указанные
bathys uninstall --purge        # + удалить venv, кэш и данные

uninstall удаляет только записи bathys из конфигов харнессов (перед изменением создаётся бэкап *.bathys-backup-*; чужие серверы и субагенты не затрагиваются). --purge дополнительно удаляет каталоги ~/.local/share/bathys и ~/.cache/bathys; строку bathys/venv/bin из .profile/.bashrc удалите вручную. Подробности и восстановление из бэкапа — в runbook.

🔌 Подключение к харнессу

Автоматически — весь стек: bathys setup (см. выше) прописывает сервер во все найденные харнессы.

Точечно — когда нужно именно здесь:

bathys install                # автодетект всех установленных харнессов
bathys install hermes         # только Hermes (отсутствующий конфиг создастся)
bathys install --list         # все поддерживаемые таргеты с путями
bathys install --print-config # готовые блоки для ручной вставки

Детектируются zcode, Claude Code, Claude Desktop, Cursor, VS Code-семейство (Cline / Roo Code / Kilo Code), Gemini CLI, Windsurf, Zed, opencode, goose, Hermes; форматы каждого — свои (JSON-схемы и YAML-контуры goose/hermes), запись идемпотентна с бэкапом. Для Pi (badlogic pi-mono), у которого нет MCP-конфига, — дроп-ин в AGENTS.md. Кастомные интеграции — в каталоге integrations/.

{
  "mcpServers": {
    "bathys": {
      "command": "/path/to/bathys",
      "env": { "BATHYS_SEARXNG_HOME": "/path/to/searxng-home" }
    }
  }
}

🧠 Научить агента работать эффективно

Конфиг — только половина дела. Из коробки харнесс получает instructions-playbook (матрицу выбора инструментов), annotations и три стратегии-промпта — bathys_deep_research, bathys_source_audit, bathys_fresh_scan, — так что выбирает инструменты Bathys уже нативно. Сильнее — профиль: субагент agents/bathys-researcher.md с двумя скиллами, которому глубокий ресёрч делегируется целиком; для клиентов, не показывающих MCP instructions, — дроп-ин agents/HARNESS-DROPIN.md в AGENTS.md / CLAUDE.md / .cursor/rules.

Пошаговая инструкция «из коробки → субагент → дроп-ин» и таблица сигналов футеров — в «Живых кейсах», раздел C.

🧭 Ходовые кейсы

Сравнение технологий. На вопрос «что выбрать под нагрузку в 2026?» агент делает один deep_research, доуточняет запрос терминами из найденного и верифицирует вывод по двум источникам: один вызов вместо цепочки «поиск + N чтений», в контекст попадает 7.5k символов вместо ~35k.

[bathys: 34 raw hits, top 8 considered · dove 3 pages · 35669 ch fetched → 7508 ch returned · 1.3s]

Аудит спорного утверждения. «Правда ли, что в X упали замеры?» — агент берёт стратегию bathys_source_audit: пакетно читает ссылки из обсуждения, ищет опровержения и выносит вердикт по каждому тезису с URL. Битая ссылка стоит одну строку, а не сорванный вызов.

Свежий срез. «Что нового в Y за две недели?» — стратегия bathys_fresh_scan: поиск с time_range=week, пакетное чтение, сводка с датами; протухший cache HIT лечится одним refresh=true.

Полный разбор всех кейсов — пользовательских, автономных агентов и эксплуатации — с живыми диалогами: docs/getting-started/cases.md.

🛠 Инструменты

Поиск сужается общими фильтрами time_range, category, engines, language. Живой футер ответа показывает сжатие и кэш: [bathys: 41 raw hits, top 3 considered · dove 3 pages · 35669 ch fetched → 7508 ch returned · 3.2s].

📊 Экономия токенов

Шкала честная и символьная, токены ≈ chars/4; каждая цифра взята из футера реального вызова.

• Двухъярусное извлечение — обычные страницы читает собственный HTTP-движок (миллисекунды, без браузера), JS-оболочки — headless-Chromium; дальше дистилляция под запрос с жёсткими бюджетами символов.
• Кэш сырца до дистилляции — SQLite хранит сырой текст, поэтому перечитать страницу под другим углом можно бесплатно и без сети.
• Ноль облачных квот — deep_research заменяет цепочку «поиск + N чтений», то есть N+1 списаний квоты, одним локальным вызовом.

Методика и пороги — в docs/operations/metrics.md.

📚 Документация

Вне docs/: agents/ — субагент, скиллы, дроп-ин · integrations/ — кастомные интеграции (hermes, pi, zcode) · install.sh — установочный скрипт · npm/bathys-mcp/ — NPM-обёртка · tests/ — юнит-тесты · CHANGELOG.md — история выпусков.

📍 Статус

0.10.0. Выпускная история: v0.2 «Качество выдачи» (ретраи, здоровье движков), v0.3 «Паритет с Tavily» (read_urls, JSON-режим), v0.4 «Эксплуатация» (robots-этика, метрики, bathys-doctor), v0.5 «Identity & Harness» (репозиционирование, промпты, субагент), v0.6 «Native Install» (bathys install), v0.7 «Ship & Setup» (двухъярусное извлечение, bathys setup, однострочник, uninstall) — итоги в CHANGELOG.md.

Репозиторий: github.com/Korrnals/bathys. Пакет опубликован: PyPI bathys (pip install), однострочник установки — выше. До 1.0: публикация npm-обёртки bathys-mcp и первый прогон Docker-образа; CI (matrix 3.10–3.12 + shellcheck) уже в репозитории.

🙏 Благодарности

Bathys стоит на плечах выдающихся открытых проектов — спасибо их авторам и сообществам:

• SearXNG — движок метапоиска (AGPL-3.0): Bathys запускает его как отдельный процесс и говорит с ним по локальному JSON API; исходники не модифицируются и не распространяются внутри пакета.
• Crawl4AI — браузерный ярус извлечения (Apache-2.0).
• MCP Python SDK (MIT), httpx (BSD-3), Playwright (Apache-2.0).

Полные атрибуции и условия использования каждого компонента — в THIRD_PARTY_NOTICES.md.

⚖️ Лицензия

Код Bathys — MIT. Компоненты, которые Bathys устанавливает и использует, лицензированы отдельно и перечислены в THIRD_PARTY_NOTICES.md (в частности, SearXNG — под AGPL-3.0, с соблюдением её условий).