okf-agents 0.1.0__py3-none-any.whl

okf_agents/__init__.py

@@ -0,0 +1,39 @@
+"""okf-agents: Open Knowledge Format bundles for LangGraph agents."""
+
+from okf_agents.bundle import OKFBundle
+from okf_agents.exceptions import (
+    BundleNotFoundError,
+    BundleValidationError,
+    ConceptNotFoundError,
+    LinkResolutionError,
+    OKFError,
+)
+from okf_agents.indexing import sync_bundle_to_vector_store
+from okf_agents.models import BundleIndex, Concept, ConceptFrontmatter, LinkEdge, SyncResult
+from okf_agents.navigator import create_okf_navigator
+from okf_agents.retriever import OKFGraphRetriever, OKFRetriever
+from okf_agents.router import create_okf_router
+from okf_agents.tools import create_okf_tools
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BundleIndex",
+    "BundleNotFoundError",
+    "BundleValidationError",
+    "Concept",
+    "ConceptFrontmatter",
+    "ConceptNotFoundError",
+    "LinkEdge",
+    "LinkResolutionError",
+    "OKFBundle",
+    "OKFError",
+    "OKFGraphRetriever",
+    "OKFRetriever",
+    "SyncResult",
+    "__version__",
+    "create_okf_navigator",
+    "create_okf_router",
+    "create_okf_tools",
+    "sync_bundle_to_vector_store",
+]

okf_agents/_internal/__init__.py

@@ -0,0 +1 @@
+"""Internal implementation details. Not part of the public API."""

okf_agents/_internal/graph_utils.py

@@ -0,0 +1,86 @@
+"""Dependency-free directed-graph helpers for the bundle link graph.
+
+Adjacency maps use concept IDs and hold deduplicated, ID-sorted neighbor
+lists so every traversal is deterministic. No graph package is used.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+
+from okf_agents.models import LinkEdge
+
+__all__ = [
+    "breadth_first_reachable",
+    "build_adjacency",
+    "merge_adjacency",
+]
+
+Adjacency = dict[str, list[str]]
+
+
+def build_adjacency(edges: Iterable[LinkEdge]) -> tuple[Adjacency, Adjacency]:
+    """Build ``(outbound, inbound)`` adjacency maps from resolved edges.
+
+    Unresolved edges are excluded because their targets are not loaded
+    concepts. Neighbor lists are deduplicated and sorted by concept ID.
+    """
+    outbound: dict[str, set[str]] = {}
+    inbound: dict[str, set[str]] = {}
+    for edge in edges:
+        if not edge.resolved:
+            continue
+        outbound.setdefault(edge.source_id, set()).add(edge.target_id)
+        inbound.setdefault(edge.target_id, set()).add(edge.source_id)
+    return (
+        {node: sorted(targets) for node, targets in outbound.items()},
+        {node: sorted(sources) for node, sources in inbound.items()},
+    )
+
+
+def merge_adjacency(
+    first: Mapping[str, Sequence[str]],
+    second: Mapping[str, Sequence[str]],
+) -> Adjacency:
+    """Merge two adjacency maps into deduplicated, ID-sorted neighbor lists."""
+    merged: dict[str, set[str]] = {}
+    for adjacency in (first, second):
+        for node, neighbors in adjacency.items():
+            merged.setdefault(node, set()).update(neighbors)
+    return {node: sorted(neighbors) for node, neighbors in merged.items()}
+
+
+def breadth_first_reachable(
+    adjacency: Mapping[str, Sequence[str]],
+    start: str,
+    hops: int,
+) -> list[str]:
+    """Return node IDs reachable from ``start`` within ``hops`` edges.
+
+    Nodes are marked visited when enqueued, so cycles terminate and each
+    node appears at most once. ``start`` itself is excluded. Results are
+    ordered by distance from ``start``, then by ID within each distance.
+
+    Raises:
+        ValueError: If ``hops`` is negative.
+    """
+    if hops < 0:
+        raise ValueError(f"hops must be non-negative, got {hops}")
+    visited = {start}
+    reachable: list[str] = []
+    frontier = [start]
+    for _ in range(hops):
+        next_frontier = sorted(
+            {
+                neighbor
+                for node in frontier
+                for neighbor in adjacency.get(node, ())
+                if neighbor not in visited
+            }
+        )
+        if not next_frontier:
+            break
+        visited.update(next_frontier)
+        reachable.extend(next_frontier)
+        frontier = next_frontier
+    return reachable

okf_agents/_internal/parser.py

@@ -0,0 +1,285 @@
+"""Pure parsing functions for OKF v0.1 concept files and bundle indexes.
+
+Every function is side-effect free: no filesystem writes and no network
+access. Invalid input raises
+:class:`~okf_agents.exceptions.BundleValidationError` keyed by the
+root-relative source path so the bundle loader can aggregate failures.
+"""
+
+from __future__ import annotations
+
+import posixpath
+import re
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import ValidationError
+
+from okf_agents.exceptions import BundleValidationError
+from okf_agents.models import BundleIndex, Concept, ConceptFrontmatter, LinkEdge
+
+__all__ = [
+    "extract_internal_links",
+    "normalize_link_target",
+    "parse_bundle_index",
+    "parse_concept",
+    "parse_frontmatter",
+    "split_frontmatter",
+    "synthesize_bundle_index",
+]
+
+_FRONTMATTER_DELIMITER = "---"
+_STANDARD_FRONTMATTER_KEYS = ("type", "title", "description", "resource", "tags", "timestamp")
+_MD_SUFFIX = ".md"
+
+# Standard inline links only: images are excluded by the lookbehind, and
+# reference-style links and autolinks never match because they lack "(...)".
+_INLINE_LINK_RE = re.compile(
+    r"(?<!!)\[(?P<anchor>[^\]]*)\]\((?P<target>[^()\s]+)(?:\s+\"[^\"]*\")?\)"
+)
+_URL_SCHEME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
+_FENCE_RE = re.compile(r"^ {0,3}(```|~~~)")
+_H1_RE = re.compile(r"^# +(?P<title>.+?) *#* *$")
+_LIST_ITEM_RE = re.compile(r"^(?:[-*+]|\d+[.)]) ")
+
+
+def _invalid(source: str, reason: str) -> BundleValidationError:
+    return BundleValidationError({source: reason})
+
+
+def split_frontmatter(raw: str, *, source: str) -> tuple[dict[str, Any], str]:
+    """Split raw concept text into its YAML frontmatter mapping and body.
+
+    The text must start with a ``---`` line and contain a matching closing
+    ``---`` line; both delimiters accept LF or CRLF endings. The returned
+    body excludes the frontmatter and both delimiter lines, preserving the
+    original line endings.
+
+    Raises:
+        BundleValidationError: If a delimiter is missing, the YAML is
+            malformed, or the frontmatter is not a mapping.
+    """
+    lines = raw.splitlines(keepends=True)
+    if not lines or lines[0].rstrip("\r\n") != _FRONTMATTER_DELIMITER:
+        raise _invalid(source, "missing opening '---' frontmatter delimiter")
+    close_index = next(
+        (
+            index
+            for index, line in enumerate(lines[1:], start=1)
+            if line.rstrip("\r\n") == _FRONTMATTER_DELIMITER
+        ),
+        None,
+    )
+    if close_index is None:
+        raise _invalid(source, "missing closing '---' frontmatter delimiter")
+    yaml_text = "".join(lines[1:close_index])
+    body = "".join(lines[close_index + 1 :])
+    try:
+        mapping = yaml.safe_load(yaml_text)
+    except yaml.YAMLError as exc:
+        raise _invalid(source, f"malformed YAML frontmatter: {exc}") from exc
+    if mapping is None:
+        mapping = {}
+    if not isinstance(mapping, dict):
+        raise _invalid(source, "frontmatter must be a YAML mapping")
+    return mapping, body
+
+
+def parse_frontmatter(mapping: dict[str, Any], *, source: str) -> ConceptFrontmatter:
+    """Validate a frontmatter mapping into a :class:`ConceptFrontmatter`.
+
+    Standard keys become typed fields; every unknown key is kept only in
+    ``extra``.
+
+    Raises:
+        BundleValidationError: If ``type`` is missing or empty, or any
+            field has an invalid type.
+    """
+    standard = {key: mapping[key] for key in _STANDARD_FRONTMATTER_KEYS if key in mapping}
+    extra = {key: value for key, value in mapping.items() if key not in _STANDARD_FRONTMATTER_KEYS}
+    if "type" not in standard:
+        raise _invalid(source, "frontmatter is missing required key 'type'")
+    try:
+        return ConceptFrontmatter(**standard, extra=extra)
+    except ValidationError as exc:
+        reasons = "; ".join(
+            f"{'.'.join(str(loc) for loc in error['loc'])}: {error['msg']}"
+            for error in exc.errors()
+        )
+        raise _invalid(source, f"invalid frontmatter: {reasons}") from exc
+
+
+def normalize_link_target(target: str, *, source_id: str, source: str) -> str | None:
+    """Normalize an inline-link target to a concept ID, or return ``None``.
+
+    ``None`` marks targets that are not internal Markdown links: external
+    URLs (any scheme or protocol-relative), fragment-only links, and
+    targets without a ``.md`` suffix. Fragments are stripped first.
+    Bundle-relative targets (``/path/file.md``) resolve from the bundle
+    root; all other targets resolve from the source concept's directory.
+
+    Raises:
+        BundleValidationError: If the target traverses outside the bundle.
+    """
+    if _URL_SCHEME_RE.match(target) or target.startswith("//"):
+        return None
+    path_part = target.split("#", 1)[0]
+    if not path_part.endswith(_MD_SUFFIX):
+        return None
+    if path_part.startswith("/"):
+        candidate = posixpath.normpath(path_part.lstrip("/"))
+    else:
+        candidate = posixpath.normpath(posixpath.join(posixpath.dirname(source_id), path_part))
+    if candidate == ".." or candidate.startswith("../"):
+        raise _invalid(source, f"link target escapes the bundle: {target!r}")
+    return candidate[: -len(_MD_SUFFIX)]
+
+
+def extract_internal_links(body: str, *, source_id: str, source: str) -> list[LinkEdge]:
+    """Extract internal inline Markdown links as unresolved edges.
+
+    Returns one :class:`LinkEdge` (``resolved=False``) per link occurrence
+    in document order, retaining repeats so callers can build a multigraph.
+    Image syntax, links inside fenced code blocks, and targets rejected by
+    :func:`normalize_link_target` are ignored.
+
+    Raises:
+        BundleValidationError: If any link target escapes the bundle.
+    """
+    edges: list[LinkEdge] = []
+    fence_marker: str | None = None
+    for line in body.splitlines():
+        fence_match = _FENCE_RE.match(line)
+        if fence_match:
+            marker = fence_match.group(1)
+            if fence_marker is None:
+                fence_marker = marker
+            elif marker == fence_marker:
+                fence_marker = None
+            continue
+        if fence_marker is not None:
+            continue
+        for match in _INLINE_LINK_RE.finditer(line):
+            target_id = normalize_link_target(
+                match.group("target"), source_id=source_id, source=source
+            )
+            if target_id is not None:
+                edges.append(
+                    LinkEdge(
+                        source_id=source_id,
+                        target_id=target_id,
+                        anchor_text=match.group("anchor"),
+                    )
+                )
+    return edges
+
+
+def parse_concept(raw: str, *, bundle_root: Path, file_path: Path) -> Concept:
+    """Parse one concept file from raw text plus its bundle and file paths.
+
+    The returned model preserves ``raw`` verbatim, excludes the
+    frontmatter delimiters from ``body``, exposes ``path`` as the resolved
+    absolute path string, and deduplicates ``outbound_links`` in
+    first-seen order.
+
+    Raises:
+        BundleValidationError: Keyed by the root-relative path when the
+            frontmatter is invalid, a link escapes the bundle, or the file
+            lies outside the bundle root.
+    """
+    resolved_root = bundle_root.resolve()
+    resolved_file = file_path if file_path.is_absolute() else resolved_root / file_path
+    resolved_file = resolved_file.resolve()
+    try:
+        relative = resolved_file.relative_to(resolved_root)
+    except ValueError as exc:
+        raise _invalid(str(file_path), "concept file lies outside the bundle root") from exc
+    source = relative.as_posix()
+    concept_id = source[: -len(_MD_SUFFIX)] if source.endswith(_MD_SUFFIX) else source
+
+    mapping, body = split_frontmatter(raw, source=source)
+    frontmatter = parse_frontmatter(mapping, source=source)
+    edges = extract_internal_links(body, source_id=concept_id, source=source)
+    outbound_links = list(dict.fromkeys(edge.target_id for edge in edges))
+    return Concept(
+        id=concept_id,
+        path=str(resolved_file),
+        frontmatter=frontmatter,
+        body=body,
+        outbound_links=outbound_links,
+        raw=raw,
+    )
+
+
+def _extract_title_and_description(markdown: str) -> tuple[str | None, str | None]:
+    """Return the first H1 title and first non-heading paragraph, if any."""
+    title: str | None = None
+    paragraph: list[str] = []
+    fenced = False
+    for line in markdown.splitlines():
+        if _FENCE_RE.match(line):
+            if paragraph:
+                break
+            fenced = not fenced
+            continue
+        if fenced:
+            continue
+        stripped = line.strip()
+        if not stripped:
+            if paragraph:
+                break
+            continue
+        if stripped.startswith("#"):
+            if paragraph:
+                break
+            h1 = _H1_RE.match(stripped)
+            if h1 and title is None:
+                title = h1.group("title")
+            continue
+        if not paragraph and _LIST_ITEM_RE.match(stripped):
+            # A link list is not a descriptive paragraph.
+            continue
+        paragraph.append(stripped)
+    description = " ".join(paragraph) if paragraph else None
+    return title, description
+
+
+def parse_bundle_index(raw: str, *, source: str = "index.md") -> BundleIndex:
+    """Parse a root ``index.md`` into a :class:`BundleIndex`.
+
+    ``body`` is the original Markdown, ``title`` the first H1 when
+    present, ``description`` the first non-heading paragraph when present,
+    and ``concept_ids`` the normalized internal link targets deduplicated
+    in first-seen order.
+
+    Raises:
+        BundleValidationError: If any link target escapes the bundle.
+    """
+    title, description = _extract_title_and_description(raw)
+    edges = extract_internal_links(raw, source_id="index", source=source)
+    concept_ids = list(dict.fromkeys(edge.target_id for edge in edges))
+    return BundleIndex(title=title, description=description, body=raw, concept_ids=concept_ids)
+
+
+def synthesize_bundle_index(concepts: Sequence[Concept], *, title: str = "Index") -> BundleIndex:
+    """Synthesize an in-memory index for a bundle without a root ``index.md``.
+
+    Concepts are listed in ascending concept-ID order as bundle-relative
+    Markdown links labelled by frontmatter title when available. Nothing
+    is written to disk.
+    """
+    ordered = sorted(concepts, key=lambda concept: concept.id)
+    lines = [f"# {title}", ""]
+    lines.extend(
+        f"- [{concept.frontmatter.title or concept.id}](/{concept.id}{_MD_SUFFIX})"
+        for concept in ordered
+    )
+    body = "\n".join(lines) + "\n"
+    return BundleIndex(
+        title=title,
+        description=None,
+        body=body,
+        concept_ids=[concept.id for concept in ordered],
+    )

okf_agents/bundle.py

@@ -0,0 +1,288 @@
+"""Eager, immutable loading and querying of OKF v0.1 bundles.
+
+:class:`OKFBundle` discovers every concept Markdown file under a bundle
+root, parses all of them up front, and builds directed-link indexes for
+lookup, lexical search, and breadth-first traversal. Bundles are
+immutable after loading; every collection-returning method returns a new
+list so callers cannot mutate bundle internals.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Literal
+
+from okf_agents._internal.graph_utils import (
+    breadth_first_reachable,
+    build_adjacency,
+    merge_adjacency,
+)
+from okf_agents._internal.parser import (
+    extract_internal_links,
+    parse_bundle_index,
+    parse_concept,
+    synthesize_bundle_index,
+)
+from okf_agents.exceptions import (
+    BundleNotFoundError,
+    BundleValidationError,
+    ConceptNotFoundError,
+)
+from okf_agents.models import BundleIndex, Concept, LinkEdge
+
+__all__ = ["OKFBundle"]
+
+_RESERVED_FILENAMES = frozenset({"index.md", "log.md"})
+_ROOT_INDEX = "index.md"
+_DIRECTIONS = ("out", "in", "both")
+
+# Search field weights per the shared contracts: title > tags > description > body.
+_TITLE_WEIGHT = 4
+_TAGS_WEIGHT = 3
+_DESCRIPTION_WEIGHT = 2
+_BODY_WEIGHT = 1
+
+
+class OKFBundle:
+    """A fully loaded OKF bundle: concepts, link graph, and root index.
+
+    Construct with :meth:`load`; the initializer is an internal detail.
+    """
+
+    def __init__(
+        self,
+        *,
+        root: Path,
+        concepts: dict[str, Concept],
+        edges_from: dict[str, list[LinkEdge]],
+        edges_to: dict[str, list[LinkEdge]],
+        index: BundleIndex,
+    ) -> None:
+        self._root = root
+        self._concepts = concepts
+        self._edges_from = edges_from
+        self._edges_to = edges_to
+        self._index = index
+        all_edges = [edge for edges in edges_from.values() for edge in edges]
+        self._out_adjacency, self._in_adjacency = build_adjacency(all_edges)
+        self._both_adjacency = merge_adjacency(self._out_adjacency, self._in_adjacency)
+
+    @classmethod
+    def load(cls, path: str | Path) -> OKFBundle:
+        """Eagerly load the bundle rooted at ``path``.
+
+        Every concept file (any ``.md`` except reserved ``index.md`` and
+        ``log.md`` at any depth) is parsed up front and validation
+        failures are aggregated into one error. A root ``index.md`` is
+        parsed when present and synthesized in memory otherwise.
+
+        Raises:
+            BundleNotFoundError: If ``path`` does not exist, is not a
+                directory, or cannot be read.
+            BundleValidationError: If any concept file is invalid, keyed
+                by stable root-relative paths.
+        """
+        root = Path(path).resolve()
+        if not root.is_dir():
+            raise BundleNotFoundError(str(path))
+        try:
+            concept_files = sorted(
+                (
+                    file
+                    for file in root.rglob("*.md")
+                    if file.is_file() and file.name not in _RESERVED_FILENAMES
+                ),
+                key=lambda file: file.relative_to(root).as_posix(),
+            )
+        except OSError as exc:
+            raise BundleNotFoundError(str(path)) from exc
+
+        concepts: dict[str, Concept] = {}
+        failures: dict[str, str] = {}
+        for file in concept_files:
+            relative = file.relative_to(root).as_posix()
+            try:
+                raw = file.read_text(encoding="utf-8")
+            except UnicodeDecodeError:
+                failures[relative] = "file is not valid UTF-8"
+                continue
+            except OSError as exc:
+                failures[relative] = f"file could not be read: {exc}"
+                continue
+            try:
+                concept = parse_concept(raw, bundle_root=root, file_path=file)
+            except BundleValidationError as exc:
+                failures.update(exc.failed_files)
+                continue
+            concepts[concept.id] = concept
+
+        index = cls._load_index(root, concepts, failures)
+        if failures:
+            raise BundleValidationError(failures)
+        assert index is not None  # index parsing only fails alongside a failure entry
+
+        edges_from: dict[str, list[LinkEdge]] = {}
+        edges_to: dict[str, list[LinkEdge]] = {}
+        for concept_id in sorted(concepts):
+            concept = concepts[concept_id]
+            source = f"{concept_id}.md"
+            edges = [
+                edge.model_copy(update={"resolved": edge.target_id in concepts})
+                for edge in extract_internal_links(
+                    concept.body, source_id=concept_id, source=source
+                )
+            ]
+            edges_from[concept_id] = edges
+            for edge in edges:
+                if edge.resolved:
+                    edges_to.setdefault(edge.target_id, []).append(edge)
+        return cls(
+            root=root,
+            concepts=concepts,
+            edges_from=edges_from,
+            edges_to=edges_to,
+            index=index,
+        )
+
+    @staticmethod
+    def _load_index(
+        root: Path,
+        concepts: dict[str, Concept],
+        failures: dict[str, str],
+    ) -> BundleIndex | None:
+        """Parse the root ``index.md`` or synthesize one in memory."""
+        index_path = root / _ROOT_INDEX
+        if not index_path.is_file():
+            return synthesize_bundle_index(list(concepts.values()))
+        try:
+            raw = index_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as exc:
+            failures[_ROOT_INDEX] = f"index could not be read: {exc}"
+            return None
+        try:
+            return parse_bundle_index(raw, source=_ROOT_INDEX)
+        except BundleValidationError as exc:
+            failures.update(exc.failed_files)
+            return None
+
+    @property
+    def root(self) -> Path:
+        """The resolved bundle root directory."""
+        return self._root
+
+    @property
+    def concept_count(self) -> int:
+        """Number of loaded concepts."""
+        return len(self._concepts)
+
+    def get(self, concept_id: str) -> Concept:
+        """Return the concept with the given ID.
+
+        Raises:
+            ConceptNotFoundError: If ``concept_id`` is not in the bundle.
+        """
+        try:
+            return self._concepts[concept_id]
+        except KeyError:
+            raise ConceptNotFoundError(concept_id) from None
+
+    def index(self) -> BundleIndex:
+        """Return a copy of the parsed or synthesized root index."""
+        return self._index.model_copy(deep=True)
+
+    def all_concepts(self) -> list[Concept]:
+        """Return every concept, sorted by concept ID."""
+        return [self._concepts[concept_id] for concept_id in sorted(self._concepts)]
+
+    def search(self, query: str, top_k: int = 5) -> list[Concept]:
+        """Weighted, case-insensitive lexical search over all concepts.
+
+        Each case-folded query token partially matches (substring) the
+        title (weight 4), tags (3), description (2), and body (1); a
+        concept must match at least one token. Results rank by descending
+        score, then concept ID, capped at ``top_k``.
+
+        Raises:
+            ValueError: If ``top_k`` is less than 1.
+        """
+        if top_k < 1:
+            raise ValueError(f"top_k must be at least 1, got {top_k}")
+        tokens = re.findall(r"\w+", query.casefold())
+        if not tokens:
+            return []
+        scored: list[tuple[int, str]] = []
+        for concept_id in sorted(self._concepts):
+            concept = self._concepts[concept_id]
+            frontmatter = concept.frontmatter
+            title = (frontmatter.title or "").casefold()
+            tags = [tag.casefold() for tag in frontmatter.tags]
+            description = (frontmatter.description or "").casefold()
+            body = concept.body.casefold()
+            score = 0
+            for token in tokens:
+                if token in title:
+                    score += _TITLE_WEIGHT
+                if any(token in tag for tag in tags):
+                    score += _TAGS_WEIGHT
+                if token in description:
+                    score += _DESCRIPTION_WEIGHT
+                if token in body:
+                    score += _BODY_WEIGHT
+            if score > 0:
+                scored.append((score, concept_id))
+        scored.sort(key=lambda item: (-item[0], item[1]))
+        return [self._concepts[concept_id] for _, concept_id in scored[:top_k]]
+
+    def links_from(self, concept_id: str) -> list[LinkEdge]:
+        """Return copies of the outbound edges of a concept in document order.
+
+        Unresolved edges (broken links) are included with
+        ``resolved=False``.
+
+        Raises:
+            ConceptNotFoundError: If ``concept_id`` is not in the bundle.
+        """
+        self.get(concept_id)
+        return [edge.model_copy() for edge in self._edges_from.get(concept_id, [])]
+
+    def backlinks(self, concept_id: str) -> list[LinkEdge]:
+        """Return copies of the inbound edges of a concept.
+
+        Edges are ordered by source concept ID, then document order
+        within each source.
+
+        Raises:
+            ConceptNotFoundError: If ``concept_id`` is not in the bundle.
+        """
+        self.get(concept_id)
+        return [edge.model_copy() for edge in self._edges_to.get(concept_id, [])]
+
+    def neighbors(
+        self,
+        concept_id: str,
+        hops: int = 1,
+        direction: Literal["out", "in", "both"] = "out",
+    ) -> list[Concept]:
+        """Return concepts reachable within ``hops`` links of a concept.
+
+        Breadth-first over resolved edges only; the starting concept is
+        excluded and cycles terminate. Results are ordered by distance,
+        then concept ID.
+
+        Raises:
+            ConceptNotFoundError: If ``concept_id`` is not in the bundle.
+            ValueError: If ``hops`` is negative or ``direction`` is not
+                one of ``"out"``, ``"in"``, or ``"both"``.
+        """
+        self.get(concept_id)
+        if direction not in _DIRECTIONS:
+            raise ValueError(f"direction must be one of {_DIRECTIONS}, got {direction!r}")
+        if direction == "out":
+            adjacency = self._out_adjacency
+        elif direction == "in":
+            adjacency = self._in_adjacency
+        else:
+            adjacency = self._both_adjacency
+        reachable = breadth_first_reachable(adjacency, concept_id, hops)
+        return [self._concepts[reached_id] for reached_id in reachable]