codebase-brain-mcp 0.1.0__py3-none-any.whl

codebase_brain_mcp/brain.py

@@ -0,0 +1,395 @@
+"""The engine behind the MCP tools: index repositories, search them, and gather cited evidence for questions."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Literal
+
+from . import analysis, history, sources
+from .analysis import DriftReport, ImpactReport, definition_span
+from .chunking import chunk_file
+from .config import Settings
+from .embeddings import Embedder, make_embedder
+from .history import BlameShare, Commit, LineChange, PullRequest
+from .store import Store, StoredChunk
+
+RRF_K = 60
+"""Reciprocal-rank-fusion constant; 60 is the value from the original paper and works well untuned."""
+CANDIDATES = 50
+EMBED_BATCH_FILES = 16
+HISTORY_LIMIT = 5_000
+"""Commits read per indexing run; enough for the history that matters, bounded for huge repos."""
+MAX_PULL_REQUESTS = 5
+_NAME = re.compile(r"^[A-Za-z0-9._-]{1,100}$")
+
+ProgressFn = Callable[[int, int, str], None]
+SearchMode = Literal["hybrid", "keyword", "vector"]
+SEARCH_MODES: tuple[SearchMode, ...] = ("hybrid", "keyword", "vector")
+
+
+class BrainError(ValueError):
+    """A request the brain can't serve, with a message meant for the user."""
+
+
+@dataclass(frozen=True)
+class IndexReport:
+    repo: str
+    root: str
+    commit: str | None
+    files_seen: int
+    files_indexed: int
+    files_unchanged: int
+    files_removed: int
+    chunks_total: int
+    commits_added: int
+    commits_total: int
+    seconds: float
+    full_rebuild: bool
+
+
+@dataclass(frozen=True)
+class Hit:
+    chunk: StoredChunk
+    score: float
+    keyword_rank: int | None
+    vector_rank: int | None
+
+
+@dataclass(frozen=True)
+class HistoryReport:
+    repo: str
+    path: str
+    start_line: int
+    end_line: int
+    symbol: str | None
+    blame: list[BlameShare]
+    changes: list[LineChange]
+    pull_requests: list[PullRequest]
+    github: str | None
+
+
+@dataclass(frozen=True)
+class RepoInfo:
+    name: str
+    source: str
+    root: str
+    commit: str | None
+    indexed_at: str
+    files: int
+    chunks: int
+    commits: int = 0
+    languages: dict[str, int] = field(default_factory=dict)
+
+
+class Brain:
+    def __init__(self, settings: Settings, embedder: Embedder | None = None):
+        self.settings = settings
+        self.embedder = embedder or make_embedder(settings)
+        self._stores: dict[str, Store] = {}
+
+    # ---- indexing -------------------------------------------------------------------------
+    def index(self, source: str, name: str | None = None, progress: ProgressFn | None = None) -> IndexReport:
+        """Index (or re-index) a local directory or an https git URL. Unchanged files are skipped."""
+        started = time.monotonic()
+        name = self._valid_name(name or sources.default_name(source))
+        if not self.settings.allow_local_paths and not sources.is_url(source):
+            raise BrainError("This server only indexes public https git URLs, not local paths.")
+        root = sources.resolve(source, self.settings.clone_dir)
+        files = sources.iter_files(root, self.settings.max_file_bytes)
+        if len(files) > self.settings.max_files:
+            raise BrainError(
+                f"{source} has {len(files)} indexable files, over this server's limit of {self.settings.max_files}."
+            )
+        store = self._store(name)
+
+        meta = store.get_meta()
+        full_rebuild = (
+            meta.get("embed_model") != self.embedder.model_id or meta.get("schema_version") != store.schema_version
+        )
+        if full_rebuild:
+            store.clear()
+        known = store.file_hashes()
+        current = {f.path: f for f in files}
+
+        removed = [path for path in known if path not in current]
+        for path in removed:
+            store.remove_file(path)
+
+        changed = [f for f in files if known.get(f.path) != _sha(f.text)]
+        notify = progress or (lambda done, total, message: None)
+        notify(0, len(changed), f"{len(changed)} of {len(files)} files need indexing")
+        for start in range(0, len(changed), EMBED_BATCH_FILES):
+            batch = changed[start : start + EMBED_BATCH_FILES]
+            per_file = [chunk_file(f.path, f.language, f.text) for f in batch]
+            vectors = self.embedder.embed_documents([_embedding_text(c) for chunks in per_file for c in chunks])
+            offset = 0
+            for file, chunks in zip(batch, per_file, strict=True):
+                store.replace_file(
+                    file.path, _sha(file.text), file.language, chunks, vectors[offset : offset + len(chunks)]
+                )
+                offset += len(chunks)
+            notify(min(start + len(batch), len(changed)), len(changed), batch[-1].path)
+
+        commit = sources.head_commit(root)
+        commits_added = 0
+        if history.is_git_repo(root):
+            notify(len(changed), len(changed), "reading git history")
+            since = None if full_rebuild else meta.get("history_head") or None
+            commits_added = store.add_commits(history.commits(root, since, HISTORY_LIMIT))
+        store.set_meta(
+            source=source,
+            root=str(root),
+            commit=commit or "",
+            embed_model=self.embedder.model_id,
+            history_head=commit or "",
+            schema_version=store.schema_version,
+            indexed_at=datetime.now(UTC).isoformat(timespec="seconds"),
+        )
+        return IndexReport(
+            repo=name,
+            root=str(root),
+            commit=commit,
+            files_seen=len(files),
+            files_indexed=len(changed),
+            files_unchanged=len(files) - len(changed),
+            files_removed=len(removed),
+            chunks_total=store.counts()["chunks"],
+            commits_added=commits_added,
+            commits_total=store.commit_count(),
+            seconds=round(time.monotonic() - started, 2),
+            full_rebuild=full_rebuild,
+        )
+
+    # ---- retrieval ------------------------------------------------------------------------
+    def search(
+        self,
+        query: str,
+        repo: str | None = None,
+        k: int = 8,
+        path_prefix: str | None = None,
+        kinds: list[str] | None = None,
+        mode: SearchMode = "hybrid",
+    ) -> list[Hit]:
+        """Hybrid search: BM25 keywords and vector similarity, merged with reciprocal-rank fusion.
+        ``mode`` can switch to one retriever alone; the evals use that to measure what each adds."""
+        query = query.strip()
+        if not query:
+            raise BrainError("The query is empty.")
+        if mode not in SEARCH_MODES:
+            raise BrainError(f"mode must be one of {', '.join(SEARCH_MODES)}.")
+        store = self._store(self.resolve_repo(repo))
+        keyword_ids = store.keyword_search(query, CANDIDATES) if mode != "vector" else []
+        vector_ids = store.vector_search(self.embedder.embed_query(query), CANDIDATES) if mode != "keyword" else []
+
+        scores: dict[int, float] = {}
+        for ranked in (keyword_ids, vector_ids):
+            for rank, chunk_id in enumerate(ranked, start=1):
+                scores[chunk_id] = scores.get(chunk_id, 0.0) + 1.0 / (RRF_K + rank)
+        chunks = store.get_chunks(list(scores))
+        keyword_rank = {cid: r for r, cid in enumerate(keyword_ids, start=1)}
+        vector_rank = {cid: r for r, cid in enumerate(vector_ids, start=1)}
+
+        hits = []
+        for chunk_id in sorted(scores, key=scores.__getitem__, reverse=True):
+            chunk = chunks[chunk_id]
+            if path_prefix and not chunk.path.startswith(path_prefix):
+                continue
+            if kinds and chunk.kind not in kinds:
+                continue
+            hits.append(
+                Hit(
+                    chunk=chunk,
+                    score=round(scores[chunk_id], 5),
+                    keyword_rank=keyword_rank.get(chunk_id),
+                    vector_rank=vector_rank.get(chunk_id),
+                )
+            )
+            if len(hits) == k:
+                break
+        return hits
+
+    # ---- history --------------------------------------------------------------------------
+    def explain_history(
+        self,
+        repo: str | None,
+        path: str | None = None,
+        symbol: str | None = None,
+        start: int | None = None,
+        end: int | None = None,
+        max_commits: int = 8,
+    ) -> HistoryReport:
+        """How a function, a line range or a whole file came to be: blame shares, the commits that
+        changed it (with the relevant diff), and the pull requests those commits came from."""
+        name = self.resolve_repo(repo)
+        store = self._store(name)
+        root = Path(store.get_meta()["root"])
+        if symbol:
+            matches = store.find_symbol(symbol, path)
+            if not matches:
+                where = f" in {path}" if path else ""
+                raise BrainError(f"No function, class or section called {symbol!r}{where}. Try search first.")
+            path, start, end, symbol = definition_span(matches)
+        if not path:
+            raise BrainError("Give a path (optionally with start and end lines) or a symbol.")
+        target = self._file_in(root, path)
+        if not history.is_git_repo(root):
+            raise BrainError(f"{name} isn't a git repository, so it has no history to explain.")
+        total = len(target.read_text(encoding="utf-8", errors="replace").splitlines())
+        start, end = max(1, start or 1), min(total, end or total)
+        if start > end:
+            raise BrainError(f"{path} has {total} lines.")
+        try:
+            changes = history.line_history(root, path, start, end, max(1, min(max_commits, 30)))
+            shares = history.blame(root, path, start, end)[:5]
+        except sources.SourceError as exc:
+            raise BrainError(f"git couldn't read the history of {path}: {exc}") from exc
+        slug = history.github_slug(root)
+        return HistoryReport(
+            repo=name,
+            path=path,
+            start_line=start,
+            end_line=end,
+            symbol=symbol,
+            blame=shares,
+            changes=changes,
+            pull_requests=self._pull_requests(store, slug, changes),
+            github=slug,
+        )
+
+    def search_history(self, query: str, repo: str | None = None, k: int = 5) -> list[Commit]:
+        """Commits whose message matches the query (BM25)."""
+        if not query.strip():
+            raise BrainError("The query is empty.")
+        return self._store(self.resolve_repo(repo)).search_commits(query, k)
+
+    def _pull_requests(self, store: Store, slug: str | None, changes: list[LineChange]) -> list[PullRequest]:
+        numbers = list(dict.fromkeys(n for change in changes for n in change.commit.prs))[:MAX_PULL_REQUESTS]
+        if not slug:
+            return []
+        prs = []
+        for number in numbers:
+            pr = store.cached_pull_request(number)
+            if pr is None:
+                if self.settings.fetch_pull_requests:
+                    pr = history.fetch_pull_request(slug, number, self.settings.github_token)
+                    store.cache_pull_request(pr)
+                else:
+                    pr = PullRequest(number=number, url=f"https://github.com/{slug}/pull/{number}")
+            prs.append(pr)
+        return prs
+
+    # ---- structure ------------------------------------------------------------------------
+    def impact_of_change(self, repo: str | None, symbol: str, path: str | None = None, depth: int = 2) -> ImpactReport:
+        """What uses ``symbol``, directly and transitively, including the tests that exercise it."""
+        store = self._store(self.resolve_repo(repo))
+        matches = store.find_symbol(symbol, path)
+        if not matches:
+            where = f" in {path}" if path else ""
+            raise BrainError(f"No function, class or method called {symbol!r}{where}. Try search first.")
+        target_path, start, end, _ = definition_span(matches)
+        target = next(c for c in matches if c.path == target_path)
+        return analysis.impact_of_change(store, target, (start, end), depth)
+
+    def find_doc_drift(
+        self, repo: str | None, path_prefix: str | None = None, check_history: bool = True, limit: int = 50
+    ) -> DriftReport:
+        """Documentation that no longer matches the code."""
+        store = self._store(self.resolve_repo(repo))
+        return analysis.find_doc_drift(store, Path(store.get_meta()["root"]), path_prefix, check_history, limit)
+
+    # ---- repositories ---------------------------------------------------------------------
+    def repos(self) -> list[RepoInfo]:
+        index_dir = self.settings.index_dir
+        names = sorted(p.stem for p in index_dir.glob("*.db")) if index_dir.is_dir() else []
+        return [info for info in (self.repo_info(n) for n in names) if info is not None]
+
+    def repo_info(self, name: str) -> RepoInfo | None:
+        store = self._store(name)
+        meta = store.get_meta()
+        if "indexed_at" not in meta:
+            return None
+        counts = store.counts()
+        return RepoInfo(
+            name=name,
+            source=meta.get("source", ""),
+            root=meta.get("root", ""),
+            commit=meta.get("commit") or None,
+            indexed_at=meta["indexed_at"],
+            files=counts["files"],
+            chunks=counts["chunks"],
+            commits=store.commit_count(),
+            languages=store.languages(),
+        )
+
+    def resolve_repo(self, repo: str | None) -> str:
+        """The repo to use: the one named, or the only one indexed."""
+        if repo:
+            name = self._valid_name(repo)
+            if not (self.settings.index_dir / f"{name}.db").exists():
+                raise BrainError(f"No index named {name!r}. Run index_repo first.")
+            return name
+        names = [info.name for info in self.repos()]
+        if len(names) == 1:
+            return names[0]
+        if not names:
+            raise BrainError("Nothing is indexed yet. Run index_repo with a local path or an https git URL.")
+        raise BrainError(f"Several repos are indexed ({', '.join(names)}); say which one with repo=.")
+
+    def read_lines(self, repo: str | None, path: str, start: int, end: int) -> str:
+        """Exact lines from an indexed file, for following up on a citation."""
+        info = self.repo_info(self.resolve_repo(repo))
+        if info is None:
+            raise BrainError("That repo isn't indexed.")
+        target = self._file_in(Path(info.root), path)
+        lines = target.read_text(encoding="utf-8", errors="replace").splitlines()
+        start, end = max(1, start), min(len(lines), end)
+        if start > end:
+            raise BrainError(f"{path} has {len(lines)} lines.")
+        return "\n".join(f"{n:>5}  {lines[n - 1]}" for n in range(start, end + 1))
+
+    @staticmethod
+    def _file_in(root: Path, path: str) -> Path:
+        """``path`` inside ``root``, refusing anything that escapes it."""
+        root = root.resolve()
+        target = (root / path).resolve()
+        if not target.is_relative_to(root) or not target.is_file():
+            raise BrainError(f"{path!r} isn't a file in this repository.")
+        return target
+
+    def close(self) -> None:
+        for store in self._stores.values():
+            store.close()
+        self._stores.clear()
+
+    def store_for(self, repo: str | None) -> Store:
+        """The index of an indexed repo, for read-only analysis such as evals."""
+        return self._store(self.resolve_repo(repo))
+
+    def _store(self, name: str) -> Store:
+        if name not in self._stores:
+            self._stores[name] = Store(self.settings.index_dir / f"{name}.db")
+        return self._stores[name]
+
+    @staticmethod
+    def _valid_name(name: str) -> str:
+        if not _NAME.match(name) or name.startswith("."):
+            raise BrainError("Repo names may use letters, digits, '.', '_' and '-' only.")
+        return name
+
+
+def _sha(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8", errors="replace")).hexdigest()
+
+
+def _embedding_text(chunk) -> str:
+    """What the model sees: where the chunk lives and what it's called, then the code itself."""
+    header = f"File: {chunk.path}"
+    if chunk.symbol:
+        header += f"\n{chunk.kind.capitalize()}: {chunk.symbol}"
+    return f"{header}\n\n{chunk.text}"

codebase_brain_mcp/chunking.py

@@ -0,0 +1,196 @@
+"""Split files into chunks that follow the code's own structure.
+
+Python is split by function and class (with exact line numbers, from ``ast``), Markdown by heading,
+and everything else into overlapping line windows. Chunks that are still too long are windowed
+again but keep their symbol, so a citation always says which function it came from.
+"""
+
+from __future__ import annotations
+
+import ast
+import builtins
+import re
+from dataclasses import dataclass, replace
+
+WINDOW_LINES = 60
+WINDOW_OVERLAP = 10
+MAX_CHUNK_LINES = 120
+_HEADING = re.compile(r"^(#{1,6})\s+(.*?)\s*#*\s*$")
+_IGNORED_NAMES = set(dir(builtins)) | {"self", "cls", "super", "typing", "t", "_"}
+
+
+@dataclass(frozen=True)
+class Chunk:
+    path: str
+    start_line: int
+    """1-based, inclusive."""
+    end_line: int
+    """1-based, inclusive."""
+    kind: str
+    """function, class, method, module, section, or code."""
+    symbol: str | None
+    text: str
+    refs: tuple[str, ...] = ()
+    """Names this chunk uses: calls, attributes and imports (Python only). Feeds impact_of_change."""
+    params: tuple[str, ...] | None = None
+    """Parameter names when the chunk is a function or method; None otherwise. Feeds find_doc_drift."""
+    accepts_any_keyword: bool = False
+    """True when the function takes ``**kwargs``, so any keyword argument is valid."""
+
+    @property
+    def citation(self) -> str:
+        return f"{self.path}:{self.start_line}-{self.end_line}"
+
+
+def chunk_file(path: str, language: str, text: str) -> list[Chunk]:
+    lines = text.splitlines()
+    if not any(line.strip() for line in lines):
+        return []
+    if language == "python":
+        try:
+            tree = ast.parse(text)
+        except (SyntaxError, ValueError):
+            return _windows(path, lines, 1, len(lines), "code", None)
+        chunks = [piece for chunk in _python_chunks(path, lines, tree) for piece in _split_long(chunk, lines)]
+        return _with_python_facts(chunks, tree)
+    if language == "markdown":
+        chunks = _markdown_chunks(path, lines)
+    else:
+        chunks = _windows(path, lines, 1, len(lines), "code", None)
+    return [piece for chunk in chunks for piece in _split_long(chunk, lines)]
+
+
+def _python_chunks(path: str, lines: list[str], tree: ast.Module) -> list[Chunk]:
+    chunks: list[Chunk] = []
+    covered: list[tuple[int, int]] = []
+    for node in tree.body:
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            continue
+        start, end = _span(node)
+        covered.append((start, end))
+        if isinstance(node, ast.ClassDef):
+            chunks.extend(_class_chunks(path, lines, node, start, end))
+        else:
+            chunks.append(_make(path, lines, start, end, "function", node.name))
+    # Whatever sits between definitions (imports, constants, module docstring) is one "module" chunk each.
+    cursor = 1
+    for start, end in [*sorted(covered), (len(lines) + 1, len(lines) + 1)]:
+        gap_start, gap_end = cursor, start - 1
+        while gap_start <= gap_end and not lines[gap_start - 1].strip():
+            gap_start += 1
+        while gap_end >= gap_start and not lines[gap_end - 1].strip():
+            gap_end -= 1
+        if gap_start <= gap_end:
+            chunks.append(_make(path, lines, gap_start, gap_end, "module", None))
+        cursor = max(cursor, end + 1)
+    return sorted(chunks, key=lambda c: c.start_line)
+
+
+def _with_python_facts(chunks: list[Chunk], tree: ast.Module) -> list[Chunk]:
+    """Attach the names each chunk uses, and the parameters of each function chunk."""
+    uses: list[tuple[int, str]] = []
+    signatures: dict[int, tuple[tuple[str, ...], bool]] = {}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load):
+            uses.append((node.lineno, node.id))
+        elif isinstance(node, ast.Attribute) and isinstance(node.ctx, ast.Load):
+            uses.append((node.lineno, node.attr))
+        elif isinstance(node, ast.ImportFrom):
+            uses.extend((node.lineno, alias.name) for alias in node.names)
+            if node.module:
+                uses.extend((node.lineno, part) for part in node.module.split("."))
+        elif isinstance(node, ast.Import):
+            uses.extend((node.lineno, part) for alias in node.names for part in alias.name.split("."))
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            args = node.args
+            names = [a.arg for a in (*args.posonlyargs, *args.args, *args.kwonlyargs)]
+            signatures[_span(node)[0]] = (tuple(n for n in names if n not in ("self", "cls")), args.kwarg is not None)
+    result = []
+    for chunk in chunks:
+        own = chunk.symbol.rsplit(".", 1)[-1] if chunk.symbol else None
+        refs = sorted(
+            {
+                name
+                for line, name in uses
+                if chunk.start_line <= line <= chunk.end_line
+                and name not in _IGNORED_NAMES
+                and name != own
+                and len(name) > 2
+            }
+        )
+        signature = signatures.get(chunk.start_line) if chunk.kind in ("function", "method") else None
+        result.append(
+            replace(
+                chunk,
+                refs=tuple(refs),
+                params=signature[0] if signature else None,
+                accepts_any_keyword=bool(signature and signature[1]),
+            )
+        )
+    return result
+
+
+def _class_chunks(path: str, lines: list[str], node: ast.ClassDef, start: int, end: int) -> list[Chunk]:
+    if end - start + 1 <= MAX_CHUNK_LINES:
+        return [_make(path, lines, start, end, "class", node.name)]
+    # A big class: its header (up to the first method) plus one chunk per method.
+    methods = [m for m in node.body if isinstance(m, (ast.FunctionDef, ast.AsyncFunctionDef))]
+    header_end = (_span(methods[0])[0] - 1) if methods else end
+    chunks = [_make(path, lines, start, header_end, "class", node.name)]
+    for method in methods:
+        m_start, m_end = _span(method)
+        chunks.append(_make(path, lines, m_start, m_end, "method", f"{node.name}.{method.name}"))
+    return chunks
+
+
+def _span(node: ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef) -> tuple[int, int]:
+    decorators = node.decorator_list
+    start = min([node.lineno, *(d.lineno for d in decorators)])
+    return start, node.end_lineno or node.lineno
+
+
+def _markdown_chunks(path: str, lines: list[str]) -> list[Chunk]:
+    chunks: list[Chunk] = []
+    trail: list[str] = []
+    section_start, section_symbol = 1, None
+    in_fence = False
+    for number, line in enumerate(lines, start=1):
+        if line.lstrip().startswith(("```", "~~~")):
+            in_fence = not in_fence
+        match = None if in_fence else _HEADING.match(line)
+        if not match:
+            continue
+        if number > section_start:
+            chunks.append(_make(path, lines, section_start, number - 1, "section", section_symbol))
+        level = len(match.group(1))
+        trail = [*trail[: level - 1], match.group(2)]
+        section_start, section_symbol = number, " > ".join(trail)
+    chunks.append(_make(path, lines, section_start, len(lines), "section", section_symbol))
+    return [c for c in chunks if c.text.strip()]
+
+
+def _windows(path: str, lines: list[str], start: int, end: int, kind: str, symbol: str | None) -> list[Chunk]:
+    chunks = []
+    step = WINDOW_LINES - WINDOW_OVERLAP
+    cursor = start
+    while cursor <= end:
+        stop = min(cursor + WINDOW_LINES - 1, end)
+        chunk = _make(path, lines, cursor, stop, kind, symbol)
+        if chunk.text.strip():
+            chunks.append(chunk)
+        if stop == end:
+            break
+        cursor += step
+    return chunks
+
+
+def _split_long(chunk: Chunk, lines: list[str]) -> list[Chunk]:
+    if chunk.end_line - chunk.start_line + 1 <= MAX_CHUNK_LINES:
+        return [chunk]
+    return _windows(chunk.path, lines, chunk.start_line, chunk.end_line, chunk.kind, chunk.symbol)
+
+
+def _make(path: str, lines: list[str], start: int, end: int, kind: str, symbol: str | None) -> Chunk:
+    return Chunk(
+        path=path, start_line=start, end_line=end, kind=kind, symbol=symbol, text="\n".join(lines[start - 1 : end])
+    )

codebase_brain_mcp/config.py

@@ -0,0 +1,58 @@
+"""Settings, read once from the environment."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_EMBED_MODEL = "BAAI/bge-small-en-v1.5"
+DEFAULT_MAX_FILE_BYTES = 512_000
+DEFAULT_MAX_FILES = 20_000
+
+
+@dataclass(frozen=True)
+class Settings:
+    home: Path
+    """Where indexes and cloned repositories live."""
+
+    embedder: str
+    """``fastembed`` (real local model) or ``hash`` (offline, for tests)."""
+
+    embed_model: str
+    max_file_bytes: int
+    """Files larger than this are skipped; they are almost always generated or data."""
+
+    github_token: str | None = None
+    """Optional. Only used to read PR titles and descriptions (raises the API rate limit)."""
+
+    fetch_pull_requests: bool = True
+
+    allow_local_paths: bool = True
+    """Whether index_repo may read local directories. Off by default when serving over HTTP, so remote
+    clients can only index public git URLs, never the server's own files."""
+
+    max_files: int = DEFAULT_MAX_FILES
+    """Repositories with more indexable files than this are refused, to bound time and disk."""
+
+    @property
+    def index_dir(self) -> Path:
+        return self.home / "indexes"
+
+    @property
+    def clone_dir(self) -> Path:
+        return self.home / "clones"
+
+
+def load_settings() -> Settings:
+    home = Path(os.environ.get("CODEBASE_BRAIN_HOME", Path.home() / ".codebase-brain")).expanduser()
+    return Settings(
+        home=home,
+        embedder=os.environ.get("CODEBASE_BRAIN_EMBEDDER", "fastembed"),
+        embed_model=os.environ.get("CODEBASE_BRAIN_EMBED_MODEL", DEFAULT_EMBED_MODEL),
+        max_file_bytes=int(os.environ.get("CODEBASE_BRAIN_MAX_FILE_BYTES", DEFAULT_MAX_FILE_BYTES)),
+        github_token=os.environ.get("GITHUB_TOKEN") or None,
+        fetch_pull_requests=os.environ.get("CODEBASE_BRAIN_FETCH_PRS", "1") != "0",
+        allow_local_paths=os.environ.get("CODEBASE_BRAIN_ALLOW_LOCAL_PATHS", "1") != "0",
+        max_files=int(os.environ.get("CODEBASE_BRAIN_MAX_FILES", DEFAULT_MAX_FILES)),
+    )