python-docs-mcp-server 0.1.2__py3-none-any.whl

mcp_server_python_docs/services/persistent_cache.py

@@ -0,0 +1,147 @@
+"""SQLite-backed cache for completed get_docs results across MCP restarts."""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+import threading
+from pathlib import Path
+from typing import NamedTuple
+
+from pydantic import ValidationError
+
+from mcp_server_python_docs.models import GetDocsResult
+
+logger = logging.getLogger(__name__)
+_NO_ANCHOR_KEY = "\x00mcp-python-docs:no-anchor\x00"
+
+
+class CacheStats(NamedTuple):
+    hits: int = 0
+    misses: int = 0
+    writes: int = 0
+
+
+class PersistentDocsCache:
+    """Persist get_docs results by index fingerprint, version, and request identity."""
+
+    def __init__(self, cache_path: Path, index_path: Path) -> None:
+        self._cache_path = Path(cache_path)
+        # Set after fingerprint stat succeeds; stays "" if init fails so the
+        # cache disables cleanly without leaking partial state.
+        self._fingerprint = ""
+        self._hits = self._misses = self._writes = 0
+        # ``check_same_thread=False`` lets multiple threads share the connection,
+        # but per the Python sqlite3 docs writes must still be serialized by the
+        # application — this lock guards every execute()/commit() and the stats
+        # counters they update.
+        self._lock = threading.Lock()
+        self._conn: sqlite3.Connection | None = None
+        try:
+            self._fingerprint = self._fingerprint_index(Path(index_path))
+            self._cache_path.parent.mkdir(parents=True, exist_ok=True)
+            self._conn = sqlite3.connect(str(self._cache_path), check_same_thread=False)
+            self._conn.execute("PRAGMA journal_mode = WAL")
+            self._conn.execute("PRAGMA synchronous = NORMAL")
+            self._conn.execute(
+                "CREATE TABLE IF NOT EXISTS retrieved_docs_cache ("
+                "index_fingerprint TEXT NOT NULL, version TEXT NOT NULL, slug TEXT NOT NULL, "
+                "anchor TEXT NOT NULL, max_chars INTEGER NOT NULL, start_index INTEGER NOT NULL, "
+                "result_json TEXT NOT NULL, created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP, "
+                "PRIMARY KEY (index_fingerprint, version, slug, anchor, max_chars, start_index))"
+            )
+            self._conn.execute(
+                "DELETE FROM retrieved_docs_cache WHERE index_fingerprint != ?",
+                (self._fingerprint,),
+            )
+            self._conn.commit()
+        except (OSError, sqlite3.Error) as e:
+            if self._conn is not None:
+                self._conn.close()
+                self._conn = None
+            logger.warning("Persistent docs cache disabled: %s", e)
+
+    @property
+    def cache_path(self) -> Path:
+        return self._cache_path
+
+    @staticmethod
+    def _fingerprint_index(index_path: Path) -> str:
+        stat = index_path.stat()
+        return f"{index_path.resolve()}:{stat.st_size}:{stat.st_mtime_ns}"
+
+    @staticmethod
+    def _anchor_key(anchor: str | None) -> str:
+        return _NO_ANCHOR_KEY if anchor is None else anchor
+
+    def stats(self) -> CacheStats:
+        return CacheStats(self._hits, self._misses, self._writes)
+
+    def get(
+        self, *, version: str, slug: str, anchor: str | None, max_chars: int, start_index: int
+    ) -> GetDocsResult | None:
+        if self._conn is None:
+            with self._lock:
+                self._misses += 1
+            return None
+        with self._lock:
+            try:
+                row = self._conn.execute(
+                    "SELECT result_json FROM retrieved_docs_cache WHERE index_fingerprint = ? "
+                    "AND version = ? AND slug = ? AND anchor = ? AND max_chars = ? "
+                    "AND start_index = ?",
+                    (
+                        self._fingerprint,
+                        version,
+                        slug,
+                        self._anchor_key(anchor),
+                        max_chars,
+                        start_index,
+                    ),
+                ).fetchone()
+            except sqlite3.Error as e:
+                self._misses += 1
+                logger.warning("Persistent docs cache read skipped: %s", e)
+                return None
+            if row is None:
+                self._misses += 1
+                return None
+            try:
+                result = GetDocsResult.model_validate_json(row[0])
+            except (ValidationError, ValueError) as e:
+                self._misses += 1
+                logger.warning("Persistent docs cache entry ignored: %s", e)
+                return None
+            self._hits += 1
+            return result
+
+    def put(self, *, result: GetDocsResult, max_chars: int, start_index: int) -> None:
+        if self._conn is None:
+            return
+        with self._lock:
+            try:
+                self._conn.execute(
+                    "INSERT OR REPLACE INTO retrieved_docs_cache "
+                    "(index_fingerprint, version, slug, anchor, max_chars, start_index, "
+                    "result_json) VALUES (?, ?, ?, ?, ?, ?, ?)",
+                    (
+                        self._fingerprint,
+                        result.version,
+                        result.slug,
+                        self._anchor_key(result.anchor),
+                        max_chars,
+                        start_index,
+                        result.model_dump_json(),
+                    ),
+                )
+                self._conn.commit()
+            except (sqlite3.Error, ValueError) as e:
+                logger.warning("Persistent docs cache write skipped: %s", e)
+                return
+            self._writes += 1
+
+    def close(self) -> None:
+        with self._lock:
+            if self._conn is not None:
+                self._conn.close()
+                self._conn = None

mcp_server_python_docs/services/search.py

@@ -0,0 +1,111 @@
+"""Search service — handles search_docs for all kind values.
+
+Extracts the search logic from server.py into a service class.
+Receives sqlite3.Connection and synonyms dict via constructor.
+No MCP types imported — dependency rule enforced.
+"""
+from __future__ import annotations
+
+import sqlite3
+
+from mcp_server_python_docs.models import SearchDocsResult
+from mcp_server_python_docs.retrieval.query import (
+    build_match_expression,
+    classify_query,
+    expand_synonyms,
+)
+from mcp_server_python_docs.retrieval.ranker import (
+    lookup_symbols_exact,
+    search_examples,
+    search_sections,
+    search_symbols,
+)
+from mcp_server_python_docs.services.observability import log_tool_call
+from mcp_server_python_docs.services.version_resolution import resolve_version_permissive
+
+
+class SearchService:
+    """Search service dispatching queries through classifier, synonym expansion,
+    and FTS5/symbol fast-path."""
+
+    def __init__(self, db: sqlite3.Connection, synonyms: dict[str, list[str]]) -> None:
+        self._db = db
+        self._synonyms = synonyms
+        self._last_synonym_expanded: bool = False
+        self._last_resolution: str = "none"
+        # Note: _symbol_exists uses direct SQL (not the version-scoped symbol
+        # cache) because classify_query's callback has no version context.
+
+    def _resolve_version(self, version: str | None) -> str | None:
+        """Resolve and validate version using shared resolution logic.
+
+        Returns None if version was None -- search is intentionally
+        cross-version so LLMs see results from all versions and can
+        compare (CR-01 documented design decision).
+
+        Raises VersionNotFoundError for unknown versions (MVER-03).
+        """
+        return resolve_version_permissive(self._db, version)
+
+    def _symbol_exists(self, name: str) -> bool:
+        """Check if a symbol name exists in the symbols table."""
+        row = self._db.execute(
+            "SELECT 1 FROM symbols WHERE qualified_name = ? LIMIT 1",
+            (name,),
+        ).fetchone()
+        return row is not None
+
+    @log_tool_call("search_docs")
+    def search(
+        self,
+        query: str,
+        version: str | None = None,
+        kind: str = "auto",
+        max_results: int = 5,
+    ) -> SearchDocsResult:
+        """Execute a search query using the retrieval layer.
+
+        Routes queries through classifier -> synonym expansion -> FTS5 or
+        symbol fast-path. Returns SearchDocsResult with hits list.
+        """
+        # Validate version if explicitly provided (MVER-03)
+        resolved_version = self._resolve_version(version)
+
+        # Track synonym expansion for observability (OPS-01)
+        original_tokens = set(query.lower().split()) if query.strip() else set()
+        expanded = expand_synonyms(query, self._synonyms)
+        self._last_synonym_expanded = expanded != original_tokens
+
+        # Classify query for routing (RETR-04)
+        query_type = classify_query(query, self._symbol_exists)
+
+        # Symbol fast-path: skip FTS5 entirely
+        if kind == "symbol" or (kind == "auto" and query_type == "symbol"):
+            hits = lookup_symbols_exact(self._db, query, resolved_version, max_results)
+            if hits:
+                self._last_resolution = "exact"
+                return SearchDocsResult(hits=hits)
+            # Fall through to FTS if symbol lookup found nothing and kind is auto
+            if kind == "symbol":
+                self._last_resolution = "exact"
+                return SearchDocsResult(hits=[], note=None)
+
+        # FTS5 path: build match expression with synonym expansion (RETR-05)
+        match_expr = build_match_expression(query, self._synonyms)
+
+        # Route to appropriate FTS5 table based on kind
+        if kind == "section":
+            hits = search_sections(self._db, match_expr, resolved_version, max_results)
+        elif kind == "example":
+            hits = search_examples(self._db, match_expr, resolved_version, max_results)
+        elif kind == "page":
+            # Page search uses sections with broader matching
+            hits = search_sections(self._db, match_expr, resolved_version, max_results)
+        else:
+            # kind == "auto": try sections first, fall back to symbols FTS
+            hits = search_sections(self._db, match_expr, resolved_version, max_results)
+            if not hits:
+                hits = search_symbols(self._db, match_expr, resolved_version, max_results)
+
+        self._last_resolution = "fts"
+        return SearchDocsResult(hits=hits)

mcp_server_python_docs/services/version.py

@@ -0,0 +1,47 @@
+"""Version service — lists available documentation versions.
+
+Trivial service that queries doc_sets table. Kept as a class
+for symmetry with SearchService and ContentService.
+No MCP types imported — dependency rule enforced.
+"""
+from __future__ import annotations
+
+import sqlite3
+
+from mcp_server_python_docs.models import ListVersionsResult, VersionInfo
+from mcp_server_python_docs.services.observability import log_tool_call
+
+
+class VersionService:
+    """Version listing service for list_versions tool.
+
+    Trivial service that queries doc_sets table. Kept as a class
+    for symmetry with SearchService and ContentService.
+    """
+
+    def __init__(self, db: sqlite3.Connection) -> None:
+        self._db = db
+
+    @log_tool_call("list_versions")
+    def list_versions(self) -> ListVersionsResult:
+        """List all available documentation versions from doc_sets table."""
+        rows = self._db.execute(
+            """
+            SELECT version, language, label, is_default, built_at
+            FROM doc_sets
+            ORDER BY version DESC
+            """
+        ).fetchall()
+
+        versions = [
+            VersionInfo(
+                version=row["version"],
+                language=row["language"],
+                label=row["label"],
+                is_default=bool(row["is_default"]),
+                built_at=row["built_at"] or "",
+            )
+            for row in rows
+        ]
+
+        return ListVersionsResult(versions=versions)

mcp_server_python_docs/services/version_resolution.py

@@ -0,0 +1,79 @@
+"""Shared version resolution logic for all services.
+
+Centralizes version validation and default resolution to avoid
+duplication across SearchService and ContentService (CR-01, WR-01).
+"""
+from __future__ import annotations
+
+import sqlite3
+
+from mcp_server_python_docs.errors import VersionNotFoundError
+
+
+def validate_version(db: sqlite3.Connection, version: str) -> str:
+    """Validate that a version exists in doc_sets. Returns the version string.
+
+    Raises VersionNotFoundError with available versions list if not found (MVER-03).
+    """
+    row = db.execute(
+        "SELECT version FROM doc_sets WHERE version = ?",
+        (version,),
+    ).fetchone()
+    if row is None:
+        available = [
+            r[0]
+            for r in db.execute(
+                "SELECT version FROM doc_sets ORDER BY version"
+            ).fetchall()
+        ]
+        raise VersionNotFoundError(
+            f"version {version!r} not found; available: {available}"
+        )
+    return version
+
+
+def resolve_default_version(db: sqlite3.Connection) -> str:
+    """Resolve the default version from doc_sets.
+
+    Prefers is_default=1 row, falls back to highest version.
+    Raises VersionNotFoundError if no versions exist.
+    """
+    row = db.execute(
+        "SELECT version FROM doc_sets WHERE is_default = 1 LIMIT 1"
+    ).fetchone()
+    if row is None:
+        row = db.execute(
+            "SELECT version FROM doc_sets ORDER BY version DESC LIMIT 1"
+        ).fetchone()
+    if row is None:
+        raise VersionNotFoundError("No versions available in index")
+    return row[0]
+
+
+def resolve_version_strict(db: sqlite3.Connection, version: str | None) -> str:
+    """Resolve version to a concrete version string. Never returns None.
+
+    Used by ContentService where a specific version is always needed
+    (e.g., to look up a document by slug + version).
+
+    - If version is provided, validates it exists.
+    - If version is None, resolves to default version.
+    """
+    if version is not None:
+        return validate_version(db, version)
+    return resolve_default_version(db)
+
+
+def resolve_version_permissive(db: sqlite3.Connection, version: str | None) -> str | None:
+    """Resolve version, allowing None to mean 'all versions'.
+
+    Used by SearchService where None means cross-version search
+    (intentional design -- LLMs benefit from seeing results across
+    all versions so they can compare and pick the right one).
+
+    - If version is provided, validates it exists.
+    - If version is None, returns None (search all versions).
+    """
+    if version is not None:
+        return validate_version(db, version)
+    return None

mcp_server_python_docs/storage/__init__.py

@@ -0,0 +1 @@
+"""Storage layer: SQLite connection management and schema."""

mcp_server_python_docs/storage/db.py

@@ -0,0 +1,146 @@
+"""SQLite connection management with RO/RW split, WAL mode, and FTS5 check."""
+from __future__ import annotations
+
+import importlib.resources
+import logging
+import platform
+import sqlite3
+from pathlib import Path
+
+import platformdirs
+
+from mcp_server_python_docs.errors import FTS5UnavailableError
+
+logger = logging.getLogger(__name__)
+
+
+def get_cache_dir() -> Path:
+    """Resolve cache directory via platformdirs (STOR-10).
+
+    Returns ~/.cache/mcp-python-docs/ on Linux,
+    ~/Library/Caches/mcp-python-docs/ on macOS, etc.
+    """
+    return Path(platformdirs.user_cache_dir("mcp-python-docs"))
+
+
+def get_index_path() -> Path:
+    """Return the default index.db path."""
+    return get_cache_dir() / "index.db"
+
+
+def _set_common_pragmas(conn: sqlite3.Connection) -> None:
+    """Set PRAGMAs that are safe for both read-only and read-write connections."""
+    conn.execute("PRAGMA synchronous = NORMAL")
+    conn.execute("PRAGMA foreign_keys = ON")
+
+
+def _set_readonly_pragmas(conn: sqlite3.Connection) -> None:
+    """Set PRAGMAs for read-only serving connections (STOR-07)."""
+    _set_common_pragmas(conn)
+
+
+def _set_readwrite_pragmas(conn: sqlite3.Connection) -> None:
+    """Set PRAGMAs for read-write ingestion connections (STOR-07)."""
+    conn.execute("PRAGMA journal_mode = WAL")
+    _set_common_pragmas(conn)
+
+
+def get_readonly_connection(path: str | Path) -> sqlite3.Connection:
+    """Open a read-only connection for serving (STOR-06).
+
+    Uses SQLite URI mode with ?mode=ro to prevent accidental writes.
+    """
+    path = Path(path)
+    conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True, check_same_thread=False)
+    _set_readonly_pragmas(conn)
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def get_readwrite_connection(path: str | Path) -> sqlite3.Connection:
+    """Open a read-write connection for ingestion (STOR-06).
+
+    Creates parent directories if needed. Sets WAL mode for
+    concurrent reads during ingestion.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(path))
+    _set_readwrite_pragmas(conn)
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def assert_fts5_available(conn: sqlite3.Connection) -> None:
+    """Check FTS5 availability with platform-aware error message (STOR-08).
+
+    Works on both read-only and read-write connections:
+    - RW: attempts CREATE/DROP of a temp FTS5 table (definitive check)
+    - RO: falls back to PRAGMA compile_options when CREATE fails due to
+      readonly mode (not a missing-FTS5 error)
+
+    Raises FTS5UnavailableError with actionable guidance:
+    - Linux x86-64: suggests pysqlite3-binary
+    - macOS/Windows/ARM: suggests uv python install or python.org
+    """
+    try:
+        conn.execute("CREATE VIRTUAL TABLE temp._fts5_check USING fts5(x)")
+        conn.execute("DROP TABLE temp._fts5_check")
+        return  # FTS5 confirmed via CREATE
+    except sqlite3.OperationalError as e:
+        error_msg = str(e).lower()
+        # If the error is about readonly (not missing FTS5), check compile_options
+        if "readonly" in error_msg or "read-only" in error_msg:
+            opts = [row[0] for row in conn.execute("PRAGMA compile_options")]
+            if "ENABLE_FTS5" in opts:
+                return  # FTS5 is compiled in
+        # FTS5 genuinely unavailable -- build platform-specific hint
+        system = platform.system()
+        machine = platform.machine()
+        if system == "Linux" and machine == "x86_64":
+            hint = (
+                "Install the pysqlite3-binary fallback:\n"
+                "  pip install 'python-docs-mcp-server[pysqlite3]'"
+            )
+        else:
+            hint = (
+                "Install a Python build with FTS5 support:\n"
+                "  uv python install\n"
+                "Or install Python from python.org (includes FTS5)."
+            )
+        raise FTS5UnavailableError(
+            f"SQLite FTS5 extension is not available in this Python build.\n{hint}"
+        ) from e
+
+
+def bootstrap_schema(conn: sqlite3.Connection) -> None:
+    """Create all tables and FTS5 indexes from schema.sql (STOR-01, STOR-09).
+
+    Loads the complete DDL from storage/schema.sql via importlib.resources.
+    All CREATE statements use IF NOT EXISTS for idempotency -- running this
+    twice on the same database is a no-op.
+
+    FTS5 virtual tables are dropped and recreated on every bootstrap to ensure
+    the tokenizer configuration matches the current schema.sql. This is safe
+    because FTS5 external-content tables are derived data that can be rebuilt
+    from canonical tables via the 'rebuild' command.
+
+    Warning:
+        This function uses ``executescript()``, which issues an implicit
+        ``COMMIT`` before executing the DDL. Do not call ``bootstrap_schema()``
+        while a transaction with uncommitted writes is in progress -- those
+        writes will be silently committed.
+    """
+    # Drop FTS5 virtual tables first so they can be recreated with the
+    # correct tokenizer. IF NOT EXISTS would skip recreation if the table
+    # exists with a different tokenizer -- there is no ALTER for FTS5.
+    _FTS_TABLES = ("sections_fts", "symbols_fts", "examples_fts")
+    for fts_table in _FTS_TABLES:
+        assert fts_table.isidentifier(), f"Invalid table name: {fts_table}"
+        conn.execute(f"DROP TABLE IF EXISTS {fts_table}")
+
+    # Load and execute the full schema DDL
+    ref = importlib.resources.files("mcp_server_python_docs.storage") / "schema.sql"
+    with importlib.resources.as_file(ref) as schema_path:
+        schema_sql = schema_path.read_text()
+    conn.executescript(schema_sql)

mcp_server_python_docs/storage/schema.sql

@@ -0,0 +1,136 @@
+-- schema.sql — python-docs-mcp-server storage schema
+-- Version: Phase 2 (2026-04-16)
+--
+-- Design decisions:
+--   - FTS5 tokenizer: unicode61 remove_diacritics 2 tokenchars '._'
+--     Porter stemming is deliberately NOT applied (STOR-02). Preserving
+--     dots and underscores as token characters ensures Python identifiers
+--     like asyncio.TaskGroup and json.dumps are indexed as single tokens.
+--   - sections.uri has NO standalone UNIQUE constraint (STOR-04). Cross-version
+--     URI overlap is safe; uniqueness is enforced only by UNIQUE(document_id, anchor).
+--   - symbols uses UNIQUE(doc_set_id, qualified_name, symbol_type) (STOR-03)
+--     instead of UNIQUE(doc_set_id, qualified_name), allowing the same name
+--     to appear as both a function and a method.
+--   - doc_sets.language defaults to 'en' (STOR-05), reserving space for
+--     future i18n without a migration.
+
+-- ────────────────────────────────────────────────────
+-- Canonical tables (source of truth)
+-- ────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS doc_sets (
+    id          INTEGER PRIMARY KEY,
+    source      TEXT NOT NULL DEFAULT 'python-docs',
+    version     TEXT NOT NULL,
+    language    TEXT NOT NULL DEFAULT 'en',
+    label       TEXT NOT NULL,
+    is_default  INTEGER NOT NULL DEFAULT 0,
+    base_url    TEXT,
+    built_at    TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(source, version, language)
+);
+
+CREATE TABLE IF NOT EXISTS documents (
+    id               INTEGER PRIMARY KEY,
+    doc_set_id       INTEGER NOT NULL REFERENCES doc_sets(id) ON DELETE CASCADE,
+    uri              TEXT NOT NULL,
+    slug             TEXT NOT NULL,
+    title            TEXT NOT NULL,
+    content_text     TEXT NOT NULL,
+    char_count       INTEGER NOT NULL,
+    UNIQUE(doc_set_id, slug)
+);
+
+CREATE TABLE IF NOT EXISTS sections (
+    id               INTEGER PRIMARY KEY,
+    document_id      INTEGER NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    uri              TEXT NOT NULL,
+    anchor           TEXT NOT NULL,
+    heading          TEXT NOT NULL,
+    level            INTEGER NOT NULL,
+    ordinal          INTEGER NOT NULL,
+    content_text     TEXT NOT NULL,
+    char_count       INTEGER NOT NULL,
+    UNIQUE(document_id, anchor)
+);
+
+CREATE TABLE IF NOT EXISTS symbols (
+    id               INTEGER PRIMARY KEY,
+    doc_set_id       INTEGER NOT NULL REFERENCES doc_sets(id) ON DELETE CASCADE,
+    qualified_name   TEXT NOT NULL,
+    normalized_name  TEXT NOT NULL,
+    module           TEXT,
+    symbol_type      TEXT,
+    document_id      INTEGER REFERENCES documents(id) ON DELETE SET NULL,
+    section_id       INTEGER REFERENCES sections(id) ON DELETE SET NULL,
+    uri              TEXT NOT NULL,
+    anchor           TEXT,
+    UNIQUE(doc_set_id, qualified_name, symbol_type)
+);
+
+CREATE TABLE IF NOT EXISTS examples (
+    id               INTEGER PRIMARY KEY,
+    section_id       INTEGER REFERENCES sections(id) ON DELETE CASCADE,
+    code             TEXT NOT NULL,
+    language         TEXT NOT NULL DEFAULT 'python',
+    is_doctest       INTEGER NOT NULL DEFAULT 0,
+    ordinal          INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE TABLE IF NOT EXISTS synonyms (
+    id               INTEGER PRIMARY KEY,
+    concept          TEXT NOT NULL,
+    expansion        TEXT NOT NULL,
+    UNIQUE(concept)
+);
+
+CREATE TABLE IF NOT EXISTS redirects (
+    id               INTEGER PRIMARY KEY,
+    doc_set_id       INTEGER NOT NULL REFERENCES doc_sets(id) ON DELETE CASCADE,
+    old_uri          TEXT NOT NULL,
+    new_uri          TEXT NOT NULL,
+    UNIQUE(doc_set_id, old_uri)
+);
+
+CREATE TABLE IF NOT EXISTS ingestion_runs (
+    id               INTEGER PRIMARY KEY,
+    source           TEXT NOT NULL,
+    version          TEXT NOT NULL,
+    status           TEXT NOT NULL,
+    started_at       TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    finished_at      TEXT,
+    artifact_hash    TEXT,
+    notes            TEXT
+);
+
+-- ────────────────────────────────────────────────────
+-- FTS5 virtual tables (retrieval aid, not source of truth)
+--
+-- All use external content mode: data lives in canonical tables,
+-- FTS indexes are rebuilt via INSERT INTO <fts>(fts) VALUES('rebuild').
+--
+-- Tokenizer: unicode61 remove_diacritics 2 tokenchars '._'
+--   - unicode61: Unicode-aware tokenization
+--   - remove_diacritics 2: map diacritical chars to ASCII equivalents
+--   - tokenchars '._': treat dots and underscores as token characters
+--     (not separators), so asyncio.TaskGroup is one token
+--   - NO porter stemming: preserves exact Python identifier search
+-- ────────────────────────────────────────────────────
+
+CREATE VIRTUAL TABLE IF NOT EXISTS sections_fts USING fts5(
+    heading, content_text,
+    content='sections', content_rowid='id',
+    tokenize="unicode61 remove_diacritics 2 tokenchars '._'"
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS symbols_fts USING fts5(
+    qualified_name, module,
+    content='symbols', content_rowid='id',
+    tokenize="unicode61 remove_diacritics 2 tokenchars '._'"
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS examples_fts USING fts5(
+    code,
+    content='examples', content_rowid='id',
+    tokenize="unicode61 remove_diacritics 2 tokenchars '._'"
+);