bathys 0.6.1__py3-none-any.whl

bathys/__init__.py

@@ -0,0 +1,8 @@
+"""Bathys — deep-research MCP server.
+
+One system: SearXNG sonar finds coordinates, Crawl4AI dives for the full text,
+a query-focused distiller keeps only what answers the question. Built to spend
+the model's tokens on answers, not on boilerplate.
+"""
+
+__version__ = "0.6.1"

bathys/agents/HARNESS-DROPIN.md

@@ -0,0 +1,50 @@
+# Bathys — блок для файла инструкций харнесса
+
+Скопируй блок ниже (от `## Веб-доступ…` до конца файла) в файл инструкций
+своего агента: ZCode — `AGENTS.md` (глобальный или проектный); Claude Code —
+`CLAUDE.md`; Cursor — `.cursor/rules/*.mdc`; generic — системный промпт.
+Блок самодостаточен: после него агент выбирает инструменты Bathys нативно и
+не ходит в интернет мимо них.
+
+Опционально (рекомендуется): скопируй `agents/bathys-researcher.md` в каталог
+субагентов (zcode: `~/.zcode/agents/`; claude code: `.claude/agents/`) и
+скиллы из `agents/skills/` — получишь профиль, заточенный под глубокий
+ресёрч через Bathys.
+
+---
+
+## Веб-доступ: всегда через Bathys (локальный поисковый сервис, MCP)
+
+Поиск, чтение страниц и исследования — только через инструменты Bathys.
+Сторонние web-инструменты не использовать: у Bathys свои дистилляция под
+запрос, токен-бюджеты, кэш и метрики.
+
+Выбор инструмента:
+
+- исследовательский вопрос («что/как/почему/сравни») → `deep_research(query)`
+  — ищет, читает топ-источники, возвращает дистиллят под запрос;
+- нужны только ссылки → `web_search(query)`; для программы/скрипта —
+  `web_search(query, as_json=true)`;
+- один известный URL → `read_url(url, query=…)`; несколько (до 10) →
+  `read_urls(urls, query=…)` — общий бюджет, битая страница стоит строку.
+
+Правила:
+
+1. `query` — вопрос, не мешок ключевых слов: дистиллятор отбирает пассажи по
+   смыслу запроса. Максимум 3 итерации на формулировку, дальше — смена угла
+   (термины из найденного, другой язык, `category`).
+2. Ключевой факт — два независимых домена; один источник — «по данным одного
+   источника»; конфликт — показать обе версии с URL.
+3. Каждый нетривиальный факт в ответе сопровождай URL из секций Bathys.
+4. Свежесть — `time_range` (`day`|`week`|`month`|`year`). `refresh=true` дорог
+   (ломает кэш): только при протухшем кэше — `cache HIT` при устаревших
+   данных — и один раз на главный источник.
+5. Сигналы: `(not fetched — …)` — источник не прочитан, работай с остальными;
+   `robots-refused` — сайт запретил чтение, уважай; `No results … tried N
+   engine sets` — помоги формулировкой (синонимы, язык); `Answer:` — мгновенный
+   справочный ответ, спорное подтверди источником.
+6. Футер `[bathys: …]` — статистика (сжатие ch, `cache HIT`/`MISS`, сек);
+   не цитируй его пользователю.
+
+Готовые стратегии — MCP-промпты `bathys_deep_research`, `bathys_source_audit`,
+`bathys_fresh_scan`: бери как стартовый шаблон плана.

bathys/agents/bathys-researcher.md

@@ -0,0 +1,91 @@
+---
+name: bathys-researcher
+description: >-
+  Специалист по веб-ресёрчу: весь интернет-доступ — через локальный MCP-сервис
+  Bathys (`deep_research`, `web_search`, `read_url`, `read_urls`). Вызывать для
+  исследования «что/как/почему/сравни» с выверенным ответом и URL-цитированием,
+  проверки спорных утверждений по источникам, свежего среза по теме. Не вызывать
+  для вопросов, отвечаемых из локального кода и контекста без интернета.
+---
+
+# Bathys Researcher — агент глубокого ресёрча
+
+Ты — специалист по веб-исследованиям. Весь твой доступ в интернет идёт
+**только** через MCP-сервис Bathys (`deep_research`, `web_search`, `read_url`,
+`read_urls`). Сторонние web-инструменты не использовать: у Bathys свои
+дистилляция под запрос, бюджеты, кэш и метрики — обход ломает экономику
+и учёт.
+
+## Матрица выбора инструмента
+
+| Ситуация | Инструмент |
+|---|---|
+| Исследовательский вопрос («что/как/почему/сравни») | `deep_research(query)` — поиск + чтение топ-источников + дистиллят под запрос одним вызовом |
+| Нужны только ссылки (пул источников, мониторинг) | `web_search(query)` |
+| Результат нужен программе/скрипту | `web_search(query, as_json=true)` — чистый JSON без футера |
+| Один известный URL | `read_url(url, query=…)` — `query` оставляет только релевантные пассажи |
+| Несколько известных URL (до 10) | `read_urls(urls, query=…)` — общий бюджет; битая страница стоит строку, не вызов |
+
+Правило края: в руках список из 3+ URL — значит `read_urls`, не цикл
+`read_url`. Промпты Bathys (`bathys_deep_research`, `bathys_source_audit`,
+`bathys_fresh_scan`) — готовые стратегии; бери как стартовый шаблон плана,
+а не изобретай с нуля.
+
+## Метод (максимум 3 итерации на одну формулировку)
+
+1. **Запрос — вопрос**, не мешок ключевых слов: дистиллятор Bathys отбирает
+   пассажи по смыслу запроса. RU/EN оба работают; для нишевой темы добавь
+   `language` и англоязычный дубль запроса.
+2. **Первый заход — `deep_research`** с дефолтами (`max_sources=3`). Разбери
+   дистиллят по секциям: (a) что отвечает на вопрос, (b) что противоречит,
+   (c) каких данных не хватает. Уточни запрос терминами из (a)–(c) —
+   терминами предметной области из источников, не своими синонимами — и
+   повтори. После 3 итераций без сдвига смени угол: `web_search` по узкому
+   термину, затем `read_urls` по 2–4 лучшим URL.
+3. **Свежесть**: «сейчас/последние/текущие» → `time_range`
+   (`day`/`week`/`month`/`year`); обзоры версий — `month`, новости — `day`.
+   Про `refresh=true` — раздел «Кэш» ниже.
+4. **Верификация**: ключевое утверждение подтверждено при двух независимых
+   доменах; один источник — пиши «по данным одного источника»; конфликт —
+   покажи обе версии с URL, не выбирай молча сторону.
+5. **Цитируй URL** из секций ответов Bathys — это твой след аудита.
+6. **Стоп**: ответ получен; или 3 итерации без сдвига — скажи, чего не
+   хватило, и предложи сменить угол; или дистиллята достаточно для синтеза.
+
+## Сигналы ответов
+
+- `(not fetched — Причина)` в секции — источник не прочитан; не провал:
+  работай с остальными секциями, при нужде добери URL отдельным `read_url`.
+- `robots-refused` — сайт запретил чтение краулерам: уважай запрет, ищи
+  другой источник той же информации, не обход.
+- `No results … · tried N engine sets · unresponsive: …` — поисковики
+  капризничали, Bathys уже ретраился: помоги формулировкой — синонимы, язык,
+  `category` (`general`/`news`/`it`/`science`).
+- `Answer:` — мгновенный справочный ответ SearXNG: годится как факт, но
+  спорное подтверди источником.
+
+## Кэш и `refresh=true`
+
+`refresh` дорог: ломает кэш и форсит сеть. Единственный повод — протухший
+кэш: футер показывает `cache HIT`, а данные в дистилляте устарели (старые
+даты, старые версии). Тогда один `refresh=true` на главный источник, не на
+пакет. `cache MISS` на повторе означает, что Bathys уже перезабрал данные
+свежими — refresh не нужен. Нюансы футера: `read_url` пишет `cache HIT`/`MISS`,
+`read_urls` — ещё и `MIX` (смешанный), `web_search` ставит токен `cache HIT`
+только на попадании, а футер `deep_research` флага кэша не содержит — там
+ориентируйся на свежесть данных в секциях.
+
+## Бюджеты
+
+Дефолты разумны: `per_source_chars` 3500 (диапазон 300–8000) · `max_sources`
+3 (1–6) · `max_chars` 8000 (300–50000) · пакет `total_chars` 12000
+(300–30000). Поднимай только для систематического разбора (обзор,
+сравнение). Ты получаешь дистиллят — твоя работа синтез, а не пересказ.
+
+## Чего не делать
+
+- `web_search` там, где нужен `deep_research` — получишь ссылки без
+  содержания и потратишь лишние вызовы на дочтение.
+- Читать список URL по одному через `read_url`, если их 3+ — это `read_urls`.
+- `refresh=true` «на всякий случай» и на весь пакет.
+- Выдавать источники за свои слова: каждый нетривиальный факт — с URL.

bathys/agents/skills/bathys-deep-dive/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: bathys-deep-dive
+description: >-
+  Глубокое исследование одного вопроса через Bathys: 1–3 итерации
+  `deep_research`, верификация по двум независимым доменам, ответ с
+  URL-цитированием. Применять, когда вопрос требует понимания («почему X»,
+  «как устроен Y», «что выбрать»), а не справочного факта. Не для проверки
+  готовых URL (bathys-source-audit), свежих новостей (промпт
+  `bathys_fresh_scan`) и простого поиска ссылок (`web_search`).
+---
+
+# Bathys Deep Dive — глубокое исследование одного вопроса
+
+## Когда применять
+
+- Вопрос требует понимания, а не факта: «почему X», «как устроен Y», «что
+  выбрать между Z и W»; ответ ляжет в решение (выбор библиотеки, диагноз,
+  оценка рисков).
+- Не для: проверка готовых URL или утверждения — скилл `bathys-source-audit`;
+  свежий срез по теме — промпт `bathys_fresh_scan`; просто список ссылок —
+  `web_search`.
+
+## Процедура
+
+1. **Заход.** `deep_research(query, max_sources=3)` с запросом-вопросом.
+   Без предварительного `web_search`: первый заход уже ищет и читает
+   топ-источники.
+2. **Разбор дистиллята.** Из секций `## i.` выпиши: (a) что отвечает на
+   вопрос, (b) что противоречит, (c) каких данных не хватает.
+3. **Вторая итерация.** Переформулируй запрос терминами из (a)–(c) —
+   терминами предметной области, найденными в источниках, не своими
+   синонимами. Не хватает конкретики: `web_search` по узкому термину →
+   `read_urls` по 2–4 лучшим URL с `query=…`. Максимум 3 итерации на
+   формулировку, дальше — смена угла, не шестой заход.
+4. **Свежесть.** Обзоры версий/цен/событий: `time_range="month"` (новости —
+   `day`; допустимо `day`/`week`/`month`/`year`). `refresh=true` — только
+   при протухшем кэше (`cache HIT`, а данные устарели), один раз на главный
+   источник.
+5. **Верификация.** Ключевые утверждения — 2 независимых домена; один
+   источник — «по данным одного источника»; конфликт — показать обе версии
+   с URL.
+6. **Синтез.** Вывод первым предложением; далее 3–7 пунктов, у каждого
+   нетривиального факта — URL; в конце «что не удалось проверить».
+
+## Выход
+
+- Вердикт/ответ + аргументация с URL у каждого нетривиального факта.
+- Абзац «ограничения вывода»: возраст данных, единственные источники,
+  непроверенные пункты.
+
+## Анти-паттерны
+
+- Пересказ дистиллята целиком — это сырьё, не ответ.
+- Больше 3 итераций без смены угла.
+- `Answer:` из выдачи как проверенный факт без подтверждения источником.

bathys/agents/skills/bathys-source-audit/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: bathys-source-audit
+description: >-
+  Аудит утверждений и источников через Bathys: пакетное чтение URL под тезис
+  (`read_urls`), кросс-поиск опровержений (`deep_research`), вердикт по
+  каждому пункту. Применять, когда URL уже есть (от пользователя, из чужого
+  ответа, из код-ревью) или нужно проверить утверждение «X, потому что
+  <URL>». Не для открытого исследования без исходных ссылок
+  (bathys-deep-dive).
+---
+
+# Bathys Source Audit — аудит источников и утверждений
+
+## Когда применять
+
+- Есть список ссылок и нужно проверить, что они действительно говорят то,
+  что заявлено.
+- Нужно проверить одно утверждение: «X правда, потому что <URL>».
+- Нужна актуальность: «это ещё так в текущих версиях?»
+
+## Процедура
+
+1. **Пакетное чтение.** `read_urls(urls, query=…)` — в `query` спорный тезис
+   словами: дистилляция вплотную к проверяемому утверждению, а не «вообще о
+   чём статья». До 10 URL одним вызовом; битые отвалятся строкой
+   `(not fetched — …)` — это не провал.
+2. **Контекст источника.** Для каждого URL: домен/автор, дата (`published`
+   в хитах поиска или дата в дистилляте), первоисточник или пересказ.
+3. **Кросс-проверка.** Спорный тезис → `deep_research` с запросом вида
+   «X критика / X опровержение / X alternatives»: ищи расхождения, а не
+   подтверждения; при споре об актуальности добавь `time_range`.
+4. **Свежесть.** Проверка «как сейчас» — один `refresh=true` на главный
+   источник (повод: `cache HIT` при устаревших данных), не на весь пакет.
+5. **Вердикт по каждому пункту**: подтверждено (≥2 независимых домена) /
+   частично (1 источник) / опровергнуто (опровержение с URL) / непроверяемо
+   (`robots-refused`, 404 — указать причину).
+
+## Выход
+
+Таблица «тезис → вердикт → источники (URL)» + абзац общего вывода. Каждый
+вердикт содержит хотя бы один URL либо явную причину его отсутствия.
+
+## Анти-паттерны
+
+- Читать URL «вообще» без `query` — дистиллят размоется, проверка станет
+  «похоже на правду».
+- Считать два пересказа одного пресс-релиза независимыми источниками.
+- Обходить `robots-refused`: фиксируй отказ и ищи другой первоисточник.

bathys/batch.py

@@ -0,0 +1,86 @@
+"""Batch reading of known URLs: no search step, one shared character budget.
+
+The read_urls counterpart of Engine.research for the case where the caller
+already holds the links (Tavily Extract parity). Dives run in parallel through
+the engine dive semaphore; a failed page degrades to a one-line section and
+frees its share of the budget for the pages that came back.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+
+from . import distill
+from .core import Engine, _ch
+from .searx import normalize_url
+
+_MAX_URLS = 10
+
+
+async def read_many(engine: Engine, urls: list[str], *, query: str | None,
+                    total_chars: int, refresh: bool = False) -> str:
+    started = time.monotonic()
+    total_chars = max(300, min(30_000, total_chars))
+
+    # Dedup by normalized URL (utm/fragment cleanup), keep the first spelling.
+    kept: list[str] = []
+    seen: set[str] = set()
+    for u in urls:
+        u = (u or "").strip()
+        if not u:
+            continue
+        key = normalize_url(u)
+        if not key or key in seen:
+            continue
+        seen.add(key)
+        kept.append(u)
+    if not kept:
+        raise ValueError("read_urls: expected 1-10 http(s) urls, got none")
+    skipped, kept = kept[_MAX_URLS:], kept[:_MAX_URLS]
+
+    async def dive(u: str):
+        async with engine._dive_sem:
+            try:
+                # max_chars here is only an upper bound for the throwaway
+                # distill inside _read; shares are cut after the gather.
+                return await engine._read(u, query=query, max_chars=total_chars,
+                                          refresh=refresh), None
+            except Exception as e:
+                # _read raises "{Class}: {msg}" both fresh and from the error cache.
+                return None, str(e) or e.__class__.__name__
+
+    results = await asyncio.gather(*(dive(u) for u in kept))
+
+    ok = sum(1 for res, _ in results if res is not None)
+    share = total_chars // ok if ok else 0
+    remainder = total_chars - share * ok if ok else 0
+
+    sections: list[str] = []
+    fetched = returned = 0
+    first_ok = True
+    for i, ((res, err), u) in enumerate(zip(results, kept), 1):
+        if res is None:
+            sections.append(f"## {i}. {u}\n(not fetched — {err})")
+            continue
+        budget = share + (remainder if first_ok else 0)
+        first_ok = False
+        slim = distill.slim_markdown(res.page.text)
+        distilled = distill.passages(slim, query, budget)
+        fetched += res.page.raw_chars
+        returned += len(distilled)
+        sections.append(f"## {i}. {res.page.title or u}\n{res.page.url}\n\n{distilled}")
+    if skipped:
+        sections.append("Skipped (over the 10-url limit): " + ", ".join(skipped))
+    secs = round(time.monotonic() - started, 1)
+    cache_flags = {res.cache_hit for res, _ in results if res is not None}
+    cache = ("HIT" if cache_flags == {True} else
+             "MISS" if cache_flags == {False} else "MIX") if cache_flags else None
+    engine._log_metrics("read_urls", cache=cache, chars_in=fetched, chars_out=returned,
+                        secs=secs, ok=ok > 0,
+                        error=None if ok else "all_failed")
+    sections.append(
+        f"[bathys: batch {len(kept)} urls · {ok}/{len(kept)} ok · "
+        f"{_ch(fetched)} ch fetched → {_ch(returned)} ch returned · {secs}s]"
+    )
+    return "\n\n".join(sections)

bathys/cache.py

@@ -0,0 +1,47 @@
+"""Tiny SQLite TTL cache.
+
+Pages are cached raw (clean markdown); distillation happens after a cache hit,
+so re-reading the same URL with a different query never re-downloads anything.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+import threading
+import time
+from pathlib import Path
+
+
+def key(*parts: object) -> str:
+    return hashlib.sha256("\x1f".join(str(p) for p in parts).encode()).hexdigest()
+
+
+class Cache:
+    key = staticmethod(key)
+
+    def __init__(self, path: Path) -> None:
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+        self._db = sqlite3.connect(path, check_same_thread=False)
+        self._db.execute(
+            "CREATE TABLE IF NOT EXISTS cache (k TEXT PRIMARY KEY, exp REAL NOT NULL, v TEXT NOT NULL)"
+        )
+        self._db.execute("CREATE INDEX IF NOT EXISTS cache_exp ON cache (exp)")
+
+    def get(self, k: str) -> tuple[bool, object]:
+        with self._lock:
+            row = self._db.execute("SELECT exp, v FROM cache WHERE k = ?", (k,)).fetchone()
+        if row is None or row[0] <= time.time():
+            return False, None
+        return True, json.loads(row[1])
+
+    def set(self, k: str, value: object, ttl: int) -> None:
+        with self._lock, self._db:
+            self._db.execute(
+                "INSERT INTO cache (k, exp, v) VALUES (?, ?, ?) "
+                "ON CONFLICT(k) DO UPDATE SET exp = excluded.exp, v = excluded.v",
+                (k, time.time() + ttl, json.dumps(value, ensure_ascii=False)),
+            )

bathys/compose.yaml

@@ -0,0 +1,22 @@
+# Used by bathys when a container engine (docker/podman) is available.
+# Settings are mounted from the bundled searxng-settings.yml.
+# Image pinned to the same upstream commit as the native-mode SHA pin
+# (config.SEARXNG_REF) — re-pin both together, quarterly (F-302).
+services:
+  searxng:
+    image: searxng/searxng:2026.9.5-c7f3080aa
+    container_name: bathys-searxng
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:8888:8080"
+    volumes:
+      - ./searxng-settings.yml:/etc/searxng/settings.yml:ro
+    environment:
+      - SEARXNG_BASE_URL=http://127.0.0.1:8888/
+    cap_drop: [ALL]
+    cap_add: [CHOWN, SETGID, SETUID]
+    logging:
+      driver: json-file
+      options:
+        max-size: "1m"
+        max-file: "1"

bathys/config.py

@@ -0,0 +1,71 @@
+"""Runtime configuration, read once from the environment with sane defaults."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    v = os.environ.get(name)
+    if v is None:
+        return default
+    return v.strip().lower() not in {"", "0", "false", "no", "off"}
+
+
+# Pinned SearXNG source commit (F-302, supply-chain). The upstream repo has no
+# git tags; this full SHA is reviewable on github.com/searxng/searxng and matches
+# the docker image tag pinned in compose.yaml (2026.9.5-c7f3080aa). Re-pin
+# deliberately (quarterly), never silently track master.
+SEARXNG_REF = "c7f3080aac5de13b619c4a5ab36590a2c5165e1c"
+
+
+@dataclass(frozen=True)
+class Config:
+    searxng_url: str
+    auto_start: bool
+    start_mode: str  # "auto" | "docker" | "native"
+    start_cmd: str | None
+    searxng_ref: str
+    data_dir: Path
+    cache_dir: Path
+    searxng_home: Path
+    search_ttl: int
+    page_ttl: int
+    search_timeout: float
+    crawl_timeout: float
+    startup_timeout: float
+    search_min_interval: float
+    search_retries: int
+    dive_concurrency: int
+    respect_robots: bool
+    metrics: bool
+
+    @classmethod
+    def load(cls) -> "Config":
+        data_dir = Path(
+            os.environ.get("BATHYS_DATA_DIR", str(Path.home() / ".local" / "share" / "bathys"))
+        ).expanduser()
+        return cls(
+            searxng_url=os.environ.get("BATHYS_SEARXNG_URL", "http://127.0.0.1:8888").rstrip("/"),
+            auto_start=_env_bool("BATHYS_AUTO_START", True),
+            start_mode=(os.environ.get("BATHYS_START_MODE") or "auto").strip().lower(),
+            start_cmd=os.environ.get("BATHYS_START_CMD") or None,
+            searxng_ref=(os.environ.get("BATHYS_SEARXNG_REF") or SEARXNG_REF).strip(),
+            data_dir=data_dir,
+            cache_dir=Path(os.environ.get("BATHYS_CACHE_DIR", str(Path.home() / ".cache" / "bathys"))).expanduser(),
+            searxng_home=Path(
+                os.environ.get("BATHYS_SEARXNG_HOME", str(data_dir / "searxng-home"))
+            ).expanduser(),
+            search_ttl=int(os.environ.get("BATHYS_SEARCH_TTL", "3600")),
+            page_ttl=int(os.environ.get("BATHYS_PAGE_TTL", "86400")),
+            search_timeout=float(os.environ.get("BATHYS_SEARCH_TIMEOUT", "15")),
+            crawl_timeout=float(os.environ.get("BATHYS_CRAWL_TIMEOUT", "40")),
+            startup_timeout=float(os.environ.get("BATHYS_STARTUP_TIMEOUT", "90")),
+            search_min_interval=float(os.environ.get("BATHYS_SEARCH_MIN_INTERVAL", "1.0")),
+            search_retries=max(0, min(3, int(os.environ.get("BATHYS_SEARCH_RETRIES", "2")))),
+            dive_concurrency=max(1, min(8, int(os.environ.get("BATHYS_DIVE_CONCURRENCY", "4")))),
+            respect_robots=_env_bool("BATHYS_ROBOTS", True),
+            metrics=_env_bool("BATHYS_METRICS", True),
+        )