Add server-side BFS entity graph endpoint

ontokit/api/routes/classes.py

@@ -97,26 +97,3 @@ async def delete_class(
     deleted = await service.delete_class(ontology_id, class_iri)
     if not deleted:
         raise HTTPException(status_code=404, detail="Class not found")
-
-
-@router.get("/ontologies/{ontology_id}/classes/{class_iri:path}/hierarchy")
-async def get_class_hierarchy(
-    ontology_id: UUID,
-    class_iri: str,
-    service: Annotated[OntologyService, Depends(get_ontology_service)],
-    direction: str = "both",
-    depth: int = 3,
-) -> dict[str, object]:
-    """
-    Get the class hierarchy around a specific class.
-
-    Args:
-        direction: 'ancestors', 'descendants', or 'both'
-        depth: Maximum depth to traverse
-    """
-    return await service.get_class_hierarchy(
-        ontology_id,
-        class_iri,
-        direction=direction,
-        depth=depth,
-    )

ontokit/api/routes/projects.py

@@ -33,6 +33,7 @@
 from ontokit.models.branch_metadata import BranchMetadata
 from ontokit.models.pull_request import GitHubIntegration, PRStatus, PullRequest
 from ontokit.models.user_github_token import UserGitHubToken
+from ontokit.schemas.graph import EntityGraphResponse
 from ontokit.schemas.owl_class import EntitySearchResponse, OWLClassResponse, OWLClassTreeResponse
 from ontokit.schemas.project import (
     BranchCreate,
@@ -656,6 +657,50 @@ async def get_ontology_tree_children(
     return OWLClassTreeResponse(nodes=nodes, total_classes=total_classes)
 
 
+@router.get(
+    "/{project_id}/ontology/classes/graph",
+    response_model=EntityGraphResponse,
+)
+async def get_ontology_class_graph(
+    project_id: UUID,
+    service: Annotated[ProjectService, Depends(get_service)],
+    ontology: Annotated[OntologyService, Depends(get_ontology)],
+    git: Annotated[GitRepositoryService, Depends(get_git)],
+    user: OptionalUser,
+    class_iri: str = Query(description="IRI of the class to build the graph around"),
+    branch: str | None = Query(default=None, description="Branch to read from"),
+    ancestors_depth: int = Query(default=5, ge=0, le=10),
+    descendants_depth: int = Query(default=2, ge=0, le=10),
+    max_nodes: int = Query(default=200, ge=1, le=500),
+    include_see_also: bool = Query(default=True),
+) -> EntityGraphResponse:
+    """Build a multi-hop entity graph around a class via BFS.
+
+    Returns nodes and edges for visualization, with lineage-based node types.
+    """
+    resolved_branch = branch or git.get_default_branch(project_id)
+    project = await _ensure_ontology_loaded(
+        project_id, service, ontology, user, resolved_branch, git
+    )
+
+    result = await ontology.build_entity_graph(
+        project_id,
+        class_iri,
+        branch=resolved_branch,
+        ancestors_depth=ancestors_depth,
+        descendants_depth=descendants_depth,
+        max_nodes=max_nodes,
+        include_see_also=include_see_also,
+        label_preferences=project.label_preferences,
+    )
+    if result is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Class not found: {class_iri}",
+        )
+    return result
+
+
 @router.get("/{project_id}/ontology/classes/{class_iri:path}", response_model=OWLClassResponse)
 async def get_ontology_class(
     project_id: UUID,

ontokit/schemas/graph.py

@@ -0,0 +1,62 @@
+"""Pydantic models for the Entity Graph API."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+# Node type values produced by the BFS in `OntologyService.build_entity_graph`.
+# Frontend mirror: `GraphNodeType` in `lib/graph/types.ts`.
+GraphNodeType = Literal[
+    "focus",
+    "root",
+    "secondary_root",
+    "class",
+    "individual",
+    "property",
+    "external",
+]
+
+# Edge type values produced by the BFS. Frontend mirror: `GraphEdgeType`.
+GraphEdgeType = Literal[
+    "subClassOf",
+    "equivalentClass",
+    "disjointWith",
+    "seeAlso",
+]
+
+
+class GraphNode(BaseModel):
+    """A node in the entity graph."""
+
+    id: str
+    label: str
+    iri: str
+    definition: str | None = None
+    is_focus: bool = False
+    is_root: bool = False
+    depth: int = 0
+    node_type: GraphNodeType = "class"
+    child_count: int | None = None
+
+
+class GraphEdge(BaseModel):
+    """An edge in the entity graph."""
+
+    id: str
+    source: str
+    target: str
+    edge_type: GraphEdgeType
+    label: str | None = None
+
+
+class EntityGraphResponse(BaseModel):
+    """Complete graph response."""
+
+    focus_iri: str
+    focus_label: str
+    nodes: list[GraphNode]
+    edges: list[GraphEdge]
+    truncated: bool = False
+    total_concept_count: int = 0

ontokit/services/entity_graph_helpers.py

@@ -0,0 +1,76 @@
+"""Helpers for entity-graph BFS — extracted from `OntologyService.build_entity_graph`.
+
+These functions live at module scope so they can be unit-tested directly without
+constructing an `OntologyService` and a loaded ontology graph.
+"""
+
+from __future__ import annotations
+
+from rdflib import Graph, URIRef
+from rdflib.namespace import OWL, RDF, RDFS
+
+
+def get_see_also_targets(graph: Graph, uri: URIRef) -> list[URIRef]:
+    """Extract seeAlso targets from both direct triples and OWL restrictions.
+
+    FOLIO encodes seeAlso as ``owl:Restriction`` with ``owl:someValuesFrom``
+    inside ``rdfs:subClassOf``, not as direct ``rdfs:seeAlso`` triples — both
+    forms are returned, deduplicated, in discovery order.
+    """
+    seen: set[URIRef] = set()
+    targets: list[URIRef] = []
+
+    def _add(ref: URIRef) -> None:
+        if ref not in seen:
+            seen.add(ref)
+            targets.append(ref)
+
+    # Direct rdfs:seeAlso triples
+    for obj in graph.objects(uri, RDFS.seeAlso):
+        if isinstance(obj, URIRef):
+            _add(obj)
+
+    # OWL restrictions: subClassOf -> Restriction(onProperty=seeAlso, someValuesFrom=X)
+    for sc in graph.objects(uri, RDFS.subClassOf):
+        if isinstance(sc, URIRef):
+            continue  # Named superclass, not a restriction
+        # sc is a blank node (restriction)
+        on_prop = next(graph.objects(sc, OWL.onProperty), None)
+        if on_prop == RDFS.seeAlso:
+            for predicate in (OWL.someValuesFrom, OWL.allValuesFrom, OWL.hasValue):
+                for val in graph.objects(sc, predicate):
+                    if isinstance(val, URIRef):
+                        _add(val)
+
+    return targets
+
+
+def get_see_also_referrers(graph: Graph, uri: URIRef) -> list[URIRef]:
+    """Find classes that reference ``uri`` via seeAlso (direct or restriction).
+
+    Reverse of :func:`get_see_also_targets`. Only returns classes (subjects with
+    ``rdf:type owl:Class``) so callers don't surface arbitrary blank nodes.
+    """
+    seen: set[URIRef] = set()
+    referrers: list[URIRef] = []
+
+    def _add(ref: URIRef) -> None:
+        if ref not in seen:
+            seen.add(ref)
+            referrers.append(ref)
+
+    # Direct reverse rdfs:seeAlso
+    for subj in graph.subjects(RDFS.seeAlso, uri):
+        if isinstance(subj, URIRef):
+            _add(subj)
+
+    # Find restrictions that reference uri via someValuesFrom/allValuesFrom/hasValue
+    for predicate in (OWL.someValuesFrom, OWL.allValuesFrom, OWL.hasValue):
+        for restriction in graph.subjects(predicate, uri):
+            on_prop = next(graph.objects(restriction, OWL.onProperty), None)
+            if on_prop == RDFS.seeAlso:
+                for cls in graph.subjects(RDFS.subClassOf, restriction):
+                    if isinstance(cls, URIRef) and (cls, RDF.type, OWL.Class) in graph:
+                        _add(cls)
+
+    return referrers