secondbrain-py 0.2.1__py3-none-any.whl

brain/graph_rag/router.py

@@ -0,0 +1,288 @@
+"""Pure heuristic auto-router for graph retrieval (spec §6d / §17b decisions 3-4).
+
+:func:`route` is a **pure, deterministic, DB-free** function: given the query,
+the requested ``mode``, an optional explicit ``person``, and a pre-fetched list
+of :class:`KnownPerson` candidates, it decides which retrieval path
+:func:`brain.graph_rag.retrieve.graph_rag_search` must dispatch to. Keeping it
+pure means its full branch matrix is unit-testable without a database — the
+caller resolves the DB-derived inputs (the known person entities) and passes
+them in (dependency inversion).
+
+The rule set (spec §17b decision 3; §17c Q6 — the G3-e flip; §17d Q1 — fuse):
+
+1. **Explicit modes are honored** — including an explicit ``global`` request,
+   which now returns :data:`GLOBAL_MODE` (community summaries shipped in G3, so
+   the router dispatches to them; the G2 rejection is gone — spec §17c Q6), and
+   an explicit ``fuse`` request (:data:`FUSE_MODE`; wave G4-c, spec §17d Q1).
+   ``fuse`` is honored ONLY as an explicit request — it is **never** an
+   auto-routed target (the auto branches stay local/themes/global).
+2. **Thematic intent** is detected by a **closed regex grammar** (not an
+   open-ended keyword list): the normalized query matches
+   ``\\bthemes?\\b|\\btopics?\\b|\\bpatterns?\\b|\\btrends?\\b|\\brecurring\\b``
+   **OR** ``\\bhow\\s+(has|have|did|does)\\b.{0,80}\\b(evolve|evolved|change|
+   changed|shift|shifted)\\b`` (case-insensitive).
+3. **Person resolution precedence:** an explicit ``person`` argument first;
+   otherwise a token-boundary scan of the ``known_persons`` against the query.
+4. **Query-match tie-break** among scanned persons: longest matched span →
+   highest ``doc_count`` → lexicographically smallest ``canonical_key``.
+5. **Branches (auto):** ``thematic AND person → themes``;
+   ``thematic AND no person → global`` (the real global community path now — G3-e
+   flipped the former G2 ``global→local`` degradation off); else → ``local``.
+
+**G2 degradation machinery is KEEP-DORMANT (spec §17c Q6):** the
+:data:`DEGRADED_FROM_GLOBAL` / :data:`DEGRADATION_REASON_G2` constants, the
+:class:`RoutingDecision` ``degraded_from`` / ``degradation_reason`` fields, and
+:class:`~brain.errors.GraphModeUnavailable` all **stay defined** for wire
+stability, but G3 **never populates / raises** them — every path below leaves the
+degradation fields ``None`` and no path raises ``GraphModeUnavailable``.
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+__all__ = [
+    "AUTO_MODE",
+    "DEGRADATION_REASON_G2",
+    "DEGRADED_FROM_GLOBAL",
+    "FUSE_MODE",
+    "GLOBAL_MODE",
+    "LOCAL_MODE",
+    "THEMES_MODE",
+    "KnownPerson",
+    "RoutedPerson",
+    "RoutingDecision",
+    "route",
+]
+
+# The retrieval-mode vocabulary (canonical home; re-exported by retrieve.py /
+# the package __init__ so existing ``LOCAL_MODE`` / ``THEMES_MODE`` imports keep
+# working). ``auto`` triggers this router; ``global`` is the community path the
+# router now dispatches to for an explicit request AND the auto
+# thematic-no-person branch (the G3-e flip; spec §17c Q6).
+LOCAL_MODE = "local"
+THEMES_MODE = "themes"
+GLOBAL_MODE = "global"
+AUTO_MODE = "auto"
+# Fuse (wave G4-c; spec §17d Q1): RRF of the local-graph doc leg with the
+# vector/FTS hybrid doc leg. Honored ONLY as an explicit request — the auto
+# router never targets it (auto stays local/themes/global).
+FUSE_MODE = "fuse"
+
+# Degradation signals (spec §17b decision 4) — KEEP-DORMANT after the G3-e flip
+# (spec §17c Q6): retained for wire stability but no longer stamped onto any
+# ``GraphContext`` / ``RoutingDecision`` (the auto thematic-no-person branch now
+# routes to the real GLOBAL_MODE instead of degrading to local).
+DEGRADED_FROM_GLOBAL = "global"
+DEGRADATION_REASON_G2 = "global_unavailable_g2"
+
+# Closed thematic-intent grammar (spec §17b decision 3 — NOT an open keyword
+# list). Compiled once at import; case-insensitive.
+_THEMATIC_KEYWORDS = re.compile(
+    r"\bthemes?\b|\btopics?\b|\bpatterns?\b|\btrends?\b|\brecurring\b",
+    re.IGNORECASE,
+)
+_THEMATIC_EVOLUTION = re.compile(
+    r"\bhow\s+(has|have|did|does)\b.{0,80}\b"
+    r"(evolve|evolved|change|changed|shift|shifted)\b",
+    re.IGNORECASE,
+)
+
+
+@dataclass(frozen=True)
+class KnownPerson:
+    """A candidate person entity for the router's token-boundary scan.
+
+    Pre-fetched (tenant-scoped) by the caller from ``graph_entities`` so the
+    router stays DB-free. ``canonical_key`` is the lowercased People-Hub display
+    name (the dedup key + lexicographic tie-break), ``display_name`` the entity's
+    stored name, and ``doc_count`` the derived mention count (the doc-count
+    tie-break input).
+    """
+
+    canonical_key: str
+    display_name: str
+    doc_count: int = 0
+
+
+@dataclass(frozen=True)
+class RoutedPerson:
+    """The person a query routed to (spec §17b decision 3).
+
+    ``source`` is ``"explicit"`` (from the ``--person`` / MCP ``person`` arg) or
+    ``"scanned"`` (a token-boundary match in the query). For the explicit case
+    ``canonical_key`` / ``doc_count`` are unknown (``None``) — only the caller's
+    stripped person string is carried in ``display_name``. For the scanned case
+    all three mirror the winning :class:`KnownPerson`.
+    """
+
+    display_name: str
+    source: str
+    canonical_key: str | None = None
+    doc_count: int | None = None
+
+
+@dataclass(frozen=True)
+class RoutingDecision:
+    """The pure router's verdict (spec §6d / §17b decisions 3-4).
+
+    ``executed_mode`` is the mode the caller must dispatch to —
+    :data:`LOCAL_MODE`, :data:`THEMES_MODE`, or :data:`GLOBAL_MODE` (the G3-e flip
+    made ``global`` dispatchable for explicit ``mode='global'`` and the auto
+    thematic-no-person branch). ``requested_mode`` echoes the caller's input mode.
+    ``is_thematic`` records the regex-grammar verdict. ``resolved_person`` is the
+    person the query routed to (or ``None``). ``degraded_from`` /
+    ``degradation_reason`` are **KEEP-DORMANT** (spec §17c Q6): defined for wire
+    stability but never populated by G3 — always ``None``.
+    """
+
+    executed_mode: str
+    requested_mode: str
+    is_thematic: bool
+    resolved_person: RoutedPerson | None = None
+    degraded_from: str | None = None
+    degradation_reason: str | None = None
+
+
+def route(
+    query: str,
+    *,
+    mode: str,
+    person: str | None,
+    known_persons: Sequence[KnownPerson],
+) -> RoutingDecision:
+    """Decide the retrieval mode for one query (pure / deterministic).
+
+    See the module docstring for the full rule set. ``known_persons`` is only
+    consulted for the ``auto`` thematic-person scan; explicit modes ignore it.
+    Never raises :class:`~brain.errors.GraphModeUnavailable` — the G3-e flip made
+    ``global`` a dispatchable mode (spec §17c Q6).
+
+    Raises:
+        ValueError: an unrecognized ``mode`` (caller bug).
+    """
+    if mode != AUTO_MODE:
+        return _route_explicit(query, mode, person)
+    return _route_auto(query, person, known_persons)
+
+
+def _route_explicit(query: str, mode: str, person: str | None) -> RoutingDecision:
+    """Honor an explicit (non-``auto``) mode, ``global`` / ``fuse`` included.
+
+    The G2 ``global`` rejection is gone: an explicit ``mode='global'`` now returns
+    a :data:`GLOBAL_MODE` decision (the caller dispatches to the community path).
+    An explicit ``mode='fuse'`` returns a :data:`FUSE_MODE` decision (wave G4-c,
+    spec §17d Q1 — the caller fuses the graph + hybrid doc legs). Local / themes
+    are honored unchanged; an unknown mode is still a caller bug.
+    """
+    if mode not in (LOCAL_MODE, THEMES_MODE, GLOBAL_MODE, FUSE_MODE):
+        raise ValueError(
+            f"unknown graph retrieval mode {mode!r} (expected one of "
+            f"{AUTO_MODE!r} / {LOCAL_MODE!r} / {THEMES_MODE!r} / "
+            f"{GLOBAL_MODE!r} / {FUSE_MODE!r})"
+        )
+    return RoutingDecision(
+        executed_mode=mode,
+        requested_mode=mode,
+        is_thematic=_is_thematic(query),
+        resolved_person=_explicit_person(person),
+    )
+
+
+def _route_auto(
+    query: str, person: str | None, known_persons: Sequence[KnownPerson]
+) -> RoutingDecision:
+    """Run the heuristic branches for ``mode='auto'`` (spec dec. 3; §17c Q6 flip)."""
+    is_thematic = _is_thematic(query)
+    resolved = _explicit_person(person) or _scan_person(query, known_persons)
+
+    if is_thematic and resolved is not None:
+        return RoutingDecision(
+            executed_mode=THEMES_MODE,
+            requested_mode=AUTO_MODE,
+            is_thematic=True,
+            resolved_person=resolved,
+        )
+    if is_thematic:
+        # Thematic but no resolvable person → global (the real community path).
+        # G3-e flipped this off the former G2 ``global→local`` degradation: no
+        # degradation signals are stamped (spec §17c Q6 keeps them dormant).
+        return RoutingDecision(
+            executed_mode=GLOBAL_MODE,
+            requested_mode=AUTO_MODE,
+            is_thematic=True,
+            resolved_person=None,
+        )
+    return RoutingDecision(
+        executed_mode=LOCAL_MODE,
+        requested_mode=AUTO_MODE,
+        is_thematic=False,
+        resolved_person=resolved,
+    )
+
+
+def _is_thematic(query: str) -> bool:
+    """``True`` iff the query matches the closed thematic-intent grammar."""
+    if not query:
+        return False
+    return bool(_THEMATIC_KEYWORDS.search(query) or _THEMATIC_EVOLUTION.search(query))
+
+
+def _explicit_person(person: str | None) -> RoutedPerson | None:
+    """Wrap a non-blank explicit ``person`` arg as the resolved person."""
+    if person is None:
+        return None
+    stripped = person.strip()
+    if not stripped:
+        return None
+    return RoutedPerson(display_name=stripped, source="explicit")
+
+
+def _scan_person(
+    query: str, known_persons: Sequence[KnownPerson]
+) -> RoutedPerson | None:
+    """Token-boundary scan of ``known_persons`` against the query (spec dec. 3-4).
+
+    For each known person, match its ``canonical_key`` and ``display_name``
+    case-insensitively at word boundaries; the person's matched span is the
+    longest matching key. The winner is chosen by longest matched span → highest
+    ``doc_count`` → lexicographically smallest ``canonical_key`` (the
+    ``canonical_key`` is unique per tenant, so the ordering is total and the
+    result deterministic). Returns ``None`` when nothing matches.
+    """
+    if not query or not known_persons:
+        return None
+    lowered = query.lower()
+    best: tuple[int, int, str] | None = None
+    winner: KnownPerson | None = None
+    for candidate in known_persons:
+        span = _best_match_span(lowered, candidate)
+        if span <= 0:
+            continue
+        # Order key: maximize span, then doc_count, then minimize canonical_key.
+        key = (-span, -candidate.doc_count, candidate.canonical_key)
+        if best is None or key < best:
+            best = key
+            winner = candidate
+    if winner is None:
+        return None
+    return RoutedPerson(
+        display_name=winner.display_name,
+        source="scanned",
+        canonical_key=winner.canonical_key,
+        doc_count=winner.doc_count,
+    )
+
+
+def _best_match_span(lowered_query: str, candidate: KnownPerson) -> int:
+    """Longest word-boundary match length of a person's keys (0 = no match)."""
+    best = 0
+    for needle in (candidate.canonical_key, candidate.display_name):
+        normalized = (needle or "").strip().lower()
+        if not normalized:
+            continue
+        pattern = r"\b" + re.escape(normalized) + r"\b"
+        if re.search(pattern, lowered_query):
+            best = max(best, len(normalized))
+    return best

brain/graph_rag/schema.py

@@ -0,0 +1,320 @@
+"""Frozen value objects for the GraphRAG layer (no DB logic).
+
+Two families live here:
+
+* **Row mirrors** — :class:`GraphEntity`, :class:`EntityMention`,
+  :class:`EdgeContribution`, :class:`Edge` map 1:1 onto the migration-012 tables
+  (``graph_entities``, ``graph_entity_mentions``, ``graph_edge_contributions``,
+  ``graph_relationships``). The raw ``embedding`` vector is deliberately *not*
+  carried on :class:`GraphEntity` — like :class:`brain.queries.DocumentRow` and
+  :class:`brain.search.SearchResult`, these are read-side value objects, not
+  storage handles.
+* **Retrieval value objects** — :class:`ThemeGroup`, :class:`GraphContext`,
+  :class:`GraphExplanation` are the wire shape returned by graph retrieval
+  (spec §6/§9, §4 D8). They are populated by the G2 retrieval code; the field
+  set here is the v1 contract and later waves may extend it additively.
+
+All tenantized rows / queries carry ``tenant_id`` (spec §4 D9). It defaults to
+``"default"`` — the fixed tenant used by single-user local deployments — so the
+local construction path is unchanged. ``ThemeGroup`` is the one exception: it is
+a derived grouping over an already tenant-scoped subgraph, not a row mirror, so
+it carries no ``tenant_id`` of its own.
+
+All classes are ``frozen=True`` dataclasses. ``SearchResult`` is referenced only
+under ``TYPE_CHECKING`` (with ``from __future__ import annotations``) so this
+module never imports :mod:`brain.search` at runtime — keeping it free of any
+import cycle with the ingest pipeline that later wires graph reconciliation in.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..search import SearchResult
+
+
+@dataclass(frozen=True)
+class GraphEntity:
+    """An entity node — mirrors a ``graph_entities`` row.
+
+    ``entity_type`` is one of ``person``/``org``/``project``/``topic``/``tool``
+    (DB ``CHECK``-enforced). ``canonical_key`` is the dedup key (a resolved
+    person-key for people, ``lower(name)`` for concepts) and is unique per
+    ``(tenant_id, entity_type, canonical_key)``. ``tenant_id`` scopes the row to
+    one tenant (spec §4 D9); single-user local deployments use the fixed default
+    tenant ``"default"``. ``doc_count`` is *derived* from mentions and refreshed
+    by the aggregate rebuild — never authoritative on write.
+    """
+
+    id: str
+    entity_type: str
+    name: str
+    canonical_key: str
+    tenant_id: str = "default"
+    description: str | None = None
+    doc_count: int = 0
+    # Person-scoped count for the active retrieval (themes mode): distinct docs
+    # where this entity co-occurs with the queried person. None when not
+    # scope-computed (local/global/entity modes). Derived per-query, never stored.
+    scoped_doc_count: int | None = None
+    properties: dict[str, Any] = field(default_factory=dict)
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+@dataclass(frozen=True)
+class EntityMention:
+    """A per-document entity mention — mirrors a ``graph_entity_mentions`` row.
+
+    Source-of-truth row: re-ingest deletes and reinserts a document's mentions.
+    ``source`` records provenance — ``"people"`` for the people pipeline or
+    ``"extractor:<model>@<ver>"`` for the concept extractor. ``tenant_id`` scopes
+    the row to one tenant (part of the row's primary key; spec §4 D9).
+    """
+
+    entity_id: str
+    document_id: str
+    source: str
+    tenant_id: str = "default"
+    mention_count: int = 1
+
+
+@dataclass(frozen=True)
+class EdgeContribution:
+    """A per-document raw co-occurrence — mirrors ``graph_edge_contributions``.
+
+    Source-of-truth row holding the *raw* window co-occurrence count between two
+    entities within one document. Endpoints are canonicalized ``src_id < dst_id``
+    (DB ``CHECK``-enforced). No generic suppression or weighting is applied here;
+    those are derive/query-time concerns. ``tenant_id`` scopes the row to one
+    tenant (part of the row's primary key; spec §4 D9).
+    """
+
+    document_id: str
+    src_id: str
+    dst_id: str
+    tenant_id: str = "default"
+    cooccur_count: int = 1
+
+
+@dataclass(frozen=True)
+class Edge:
+    """A derived aggregate relationship — mirrors a ``graph_relationships`` row.
+
+    ``weight`` is the normative association metric: normalized lift in ``(0, 1]``
+    (recomputed from contributions; doubles as the BFS path affinity). ``co_count``
+    is ``SUM`` of contribution counts and ``doc_count`` the distinct-document
+    count. Endpoints are canonicalized ``src_id < dst_id`` (DB ``CHECK``-enforced).
+    ``tenant_id`` scopes the row to one tenant (part of the row's primary key;
+    spec §4 D9).
+    """
+
+    src_id: str
+    dst_id: str
+    weight: float
+    tenant_id: str = "default"
+    rel_type: str = "co_occurs"
+    co_count: int = 0
+    doc_count: int = 0
+    updated_at: datetime | None = None
+
+
+@dataclass(frozen=True)
+class CommunityMember:
+    """A community ↔ entity membership — mirrors ``graph_community_members``.
+
+    Wave G3 (spec §17c Q1). One row per entity in a detected community.
+    ``member_rank`` orders entities within the community (0-based, most-central
+    first) and ``member_weight`` is the entity's weighted degree inside the
+    community subgraph; both are DB ``CHECK``-enforced non-negative. At detection
+    time the owning ``community_key`` is not yet assigned (a reused key is matched
+    by Jaccard, a new one minted at persist), so it defaults to the empty string
+    until the persistence layer fills it in. ``tenant_id`` scopes the row to one
+    tenant (part of the row's primary key; spec §4 D9).
+    """
+
+    entity_id: str
+    member_rank: int = 0
+    member_weight: float = 0.0
+    community_key: str = ""
+    tenant_id: str = "default"
+
+
+@dataclass(frozen=True)
+class CommunityRecord:
+    """A detected community — mirrors a ``graph_communities`` row (wave G3).
+
+    Single-level only (``level`` pinned to 0; spec §17c Q1 / §15). ``community_key``
+    is the durable, stable identity preserved across rebuilds by Jaccard matching
+    (spec §17c Q3/Q7). ``source_graph_hash`` is the tenant-graph dirty fingerprint
+    (an edge hash over ordered ``graph_relationships``); ``members_hash`` is the
+    per-community identity hash over the sorted member entity ids. The aggregate
+    stats (``member_count``/``edge_count``/``total_weight``) describe the
+    community subgraph. The ``summary*`` fields are populated lazily/eagerly at
+    build/refresh by G3-c (NULL here at detection); like :class:`GraphEntity` the
+    raw ``summary_embedding`` vector is deliberately not carried (read-side value
+    object, not a storage handle). ``tenant_id`` scopes the row to one tenant
+    (part of the row's primary key; spec §4 D9).
+    """
+
+    community_key: str
+    source_graph_hash: str
+    members_hash: str
+    tenant_id: str = "default"
+    level: int = 0
+    build_version: str = "networkx-louvain-v1"
+    member_count: int = 0
+    edge_count: int = 0
+    total_weight: float = 0.0
+    summary: str | None = None
+    summary_model: str | None = None
+    summary_at: datetime | None = None
+
+
+@dataclass(frozen=True)
+class ThemeGroup:
+    """A cluster of related entities for the "themes with X" headline (spec §6b).
+
+    Produced by the scoped-subgraph grouping over X's documents. ``entities`` are
+    the group's key entities, ``doc_ids`` the representative X-documents, and
+    ``score`` the group's total in-scope normalized lift (the ranking metric).
+    ``summary`` is an optional on-demand ``summarize_group()`` Ollama synthesis
+    (top-K groups only, when ``--synthesize``/MCP ``synthesize=true``).
+    """
+
+    group_id: int
+    entities: list[GraphEntity] = field(default_factory=list)
+    doc_ids: list[str] = field(default_factory=list)
+    score: float = 0.0
+    summary: str | None = None
+
+
+@dataclass(frozen=True)
+class CommunityGroup:
+    """A detected community surfaced by global retrieval (spec §6c / §17c Q4-Q5).
+
+    The ranked unit of the **global** path (wave G3-d): each group is one
+    ``graph_communities`` community that surfaced from the community-level RRF
+    (FTS over ``summary_tsv`` fused with vector cosine over ``summary_embedding``;
+    :func:`brain.graph_rag.global_._retrieve_global`). Distinct from
+    :class:`ThemeGroup` (a derived entity cluster over a person's scoped
+    subgraph) — a ``CommunityGroup`` mirrors a persisted, pre-summarized
+    community.
+
+    ``community_key`` is the durable community identity, ``level`` the (single)
+    detection level (pinned 0; spec §17c Q1), ``member_count`` the full community
+    size, and ``score`` the fused RRF score (the ranking metric). ``summary`` is
+    the eager community summary (NULL when Ollama was unavailable at build —
+    the community then ranked on its FTS leg only). ``entities`` are the
+    representative member entities (top by ``member_rank``) and ``doc_ids`` the
+    representative documents that most mention the community's entities.
+    """
+
+    community_key: str
+    level: int = 0
+    member_count: int = 0
+    score: float = 0.0
+    summary: str | None = None
+    entities: list[GraphEntity] = field(default_factory=list)
+    doc_ids: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class GraphExplanation:
+    """Per-query graph-retrieval diagnostic (spec §6a/§9; §4 D8).
+
+    The graph analogue of :class:`brain.search.SearchExplanation`. Records the
+    seeds, resolved scope, traversal parameters, and pruning telemetry so a
+    caller can see *why* a :class:`GraphContext` looks the way it does. Populated
+    by the G2 retrieval code; provisional fields default to safe empties so the
+    object is constructible before that wave lands. ``tenant_id`` records the
+    tenant the query was scoped to (spec §4 D9 — every graph query injects it).
+    """
+
+    mode: str
+    tenant_id: str = "default"
+    seed_entity_ids: list[str] = field(default_factory=list)
+    person_keys: list[str] = field(default_factory=list)
+    depth: int = 0
+    frontier_cap: int = 0
+    min_edge_weight: float = 0.0
+    nodes_visited: int = 0
+    edges_considered: int = 0
+    generic_df_cap: int | None = None
+    matched_filters: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class GraphContext:
+    """The distinct envelope returned by graph retrieval (spec §4 D8, §6, §9).
+
+    Themes/communities are *not* document hits, so graph retrieval returns this
+    shape rather than faking :class:`brain.search.SearchResult` parity. ``mode``
+    is the resolved retrieval mode (``local``/``themes``/``global``); ``person``
+    is set for scoped "themes with X" queries. ``docs`` reuses ``SearchResult``
+    for the document-hit portion. ``themes`` is populated for ``themes`` mode,
+    ``communities`` for ``global`` mode (wave G3-d; spec §17c Q5), and
+    ``entities`` for ``local`` mode. ``tenant_id`` records the tenant the query
+    was scoped to (spec §4 D9 — every graph query injects it).
+
+    Degradation signals (``requested_mode`` / ``degraded_from`` /
+    ``degradation_reason``) are **KEPT DORMANT** (spec §17c Q6): they are now
+    **always** ``None``. They date to the wave-G2 era, when an ``auto`` thematic
+    query with no resolvable person degraded ``global`` → ``local`` and recorded
+    the substitution here. The G3-e router flip made ``global`` a real, executing
+    mode, so that degradation no longer happens and no code path populates these
+    fields. They are retained on the dataclass purely for wire/JSON stability
+    (the MCP + CLI ``--json`` shape keeps the keys) — not removed.
+    """
+
+    session_id: str
+    mode: str
+    query: str
+    tenant_id: str = "default"
+    person: str | None = None
+    themes: list[ThemeGroup] = field(default_factory=list)
+    communities: list[CommunityGroup] = field(default_factory=list)
+    entities: list[GraphEntity] = field(default_factory=list)
+    docs: list[SearchResult] = field(default_factory=list)
+    explanation: GraphExplanation | None = None
+    requested_mode: str | None = None
+    degraded_from: str | None = None
+    degradation_reason: str | None = None
+
+
+@dataclass(frozen=True)
+class EntitySummary:
+    """Lightweight entity row for listing — projected from ``graph_entities``.
+
+    Returned by :func:`brain.graph_rag.relational.list_entities` for the
+    ``brain graphrag entities`` admin surface. Does not carry the raw
+    ``embedding`` vector (a storage handle, not a wire value — same convention
+    as :class:`GraphEntity` and :class:`CommunityRecord`).
+    """
+
+    entity_type: str
+    name: str
+    canonical_key: str
+    doc_count: int
+    description: str | None = None
+
+
+@dataclass(frozen=True)
+class GraphStats:
+    """At-a-glance graph overview for ``brain graphrag stats``.
+
+    Produced by :func:`brain.graph_rag.relational.graph_stats` from the
+    tenant's relational tables. ``counts_by_type`` maps each ``entity_type``
+    present in ``graph_entities`` to its row count; ``total_entities`` is their
+    sum. ``top_entities`` are the top-10 entities by ``doc_count`` (the same
+    slice ``brain graphrag entities --limit 10`` would return with sort=docs).
+    """
+
+    counts_by_type: Mapping[str, int]
+    total_entities: int
+    total_relationships: int
+    total_communities: int
+    top_entities: tuple[EntitySummary, ...]