fix: use query params for graph routes to avoid greedy :path capture

JohnRDOrazio · claude · JohnRDOrazio · commit 69f933ef78fe · 2026-04-11T16:04:07.000+02:00
The {class_iri:path}/graph route pattern was broken because FastAPI's
:path converter greedily captures /graph as part of the IRI. Move
class_iri to a query parameter and reorder routes before path-parameter
routes. Also removes the dead hierarchy endpoint (unimplemented stub),
fixes mypy no-any-return errors with TYPE_CHECKING import, fixes ruff
ARG001 unused depth param, and adds comprehensive tests for
build_entity_graph.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/ontokit/api/routes/classes.py b/ontokit/api/routes/classes.py
@@ -58,6 +58,39 @@ async def create_class(
     return await service.create_class(ontology_id, owl_class)
 
 
+@router.get(
+    "/ontologies/{ontology_id}/classes/graph",
+    response_model=EntityGraphResponse,
+)
+async def get_class_graph(
+    ontology_id: UUID,
+    service: Annotated[OntologyService, Depends(get_ontology_service)],
+    class_iri: str = Query(description="IRI of the class to build the graph around"),
+    branch: str = "main",
+    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 = True,
+) -> EntityGraphResponse:
+    """Build a multi-hop entity graph around a class via BFS.
+
+    Returns nodes and edges for visualization, with lineage-based node types
+    for ontology-agnostic coloring (root, ancestor, focus, descendant, etc.).
+    """
+    result = await service.build_entity_graph(
+        ontology_id,
+        class_iri,
+        branch=branch,
+        ancestors_depth=ancestors_depth,
+        descendants_depth=descendants_depth,
+        max_nodes=max_nodes,
+        include_see_also=include_see_also,
+    )
+    if result is None:
+        raise HTTPException(status_code=404, detail="Class not found")
+    return result
+
+
 @router.get("/ontologies/{ontology_id}/classes/{class_iri:path}", response_model=OWLClassResponse)
 async def get_class(
     ontology_id: UUID,
@@ -98,59 +131,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,
-    )
-
-
-@router.get(
-    "/ontologies/{ontology_id}/classes/{class_iri:path}/graph",
-    response_model=EntityGraphResponse,
-)
-async def get_class_graph(
-    ontology_id: UUID,
-    class_iri: str,
-    service: Annotated[OntologyService, Depends(get_ontology_service)],
-    branch: str = "main",
-    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 = True,
-) -> EntityGraphResponse:
-    """Build a multi-hop entity graph around a class via BFS.
-
-    Returns nodes and edges for visualization, with lineage-based node types
-    for ontology-agnostic coloring (root, ancestor, focus, descendant, etc.).
-    """
-    result = await service.build_entity_graph(
-        ontology_id,
-        class_iri,
-        branch=branch,
-        ancestors_depth=ancestors_depth,
-        descendants_depth=descendants_depth,
-        max_nodes=max_nodes,
-        include_see_also=include_see_also,
-    )
-    if result is None:
-        raise HTTPException(status_code=404, detail="Class not found")
-    return result
diff --git a/ontokit/api/routes/projects.py b/ontokit/api/routes/projects.py
@@ -630,6 +630,47 @@ 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)
+    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,
+    )
+    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,
@@ -695,49 +736,6 @@ async def get_ontology_class_ancestors(
     return OWLClassTreeResponse(nodes=nodes, total_classes=total_classes)
 
 
-@router.get(
-    "/{project_id}/ontology/classes/{class_iri:path}/graph",
-    response_model=EntityGraphResponse,
-)
-async def get_ontology_class_graph(
-    project_id: UUID,
-    class_iri: str,
-    service: Annotated[ProjectService, Depends(get_service)],
-    ontology: Annotated[OntologyService, Depends(get_ontology)],
-    git: Annotated[GitRepositoryService, Depends(get_git)],
-    user: OptionalUser,
-    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)
-    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,
-    )
-    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/search", response_model=EntitySearchResponse)
 async def search_ontology_entities(
     project_id: UUID,
diff --git a/ontokit/services/ontology.py b/ontokit/services/ontology.py
@@ -1,7 +1,9 @@
 """Ontology service for managing OWL ontologies."""
 
+from __future__ import annotations
+
 from dataclasses import dataclass
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
 from typing import Literal as TypingLiteral
 from uuid import UUID
 
@@ -33,6 +35,9 @@
 )
 from ontokit.services.storage import StorageService
 
+if TYPE_CHECKING:
+    from ontokit.schemas.graph import EntityGraphResponse
+
 # Map file extensions to RDF formats
 FORMAT_MAP = {
     ".owl": "xml",
@@ -120,7 +125,7 @@ class LabelPreference:
     language: str | None  # None means any language or no language tag
 
     @classmethod
-    def parse(cls, pref_string: str) -> "LabelPreference | None":
+    def parse(cls, pref_string: str) -> LabelPreference | None:
         """
         Parse a preference string like 'rdfs:label@en' or 'skos:prefLabel'.
 
@@ -340,17 +345,6 @@ async def delete_class(self, ontology_id: UUID, class_iri: str) -> bool:
         # TODO: Implement class deletion
         raise NotImplementedError("Class deletion pending")
 
-    async def get_class_hierarchy(
-        self,
-        ontology_id: UUID,
-        class_iri: str,
-        direction: str = "both",
-        depth: int = 3,
-    ) -> dict[str, Any]:
-        """Get class hierarchy around a specific class."""
-        # TODO: Implement hierarchy traversal
-        raise NotImplementedError("Hierarchy implementation pending")
-
     async def build_entity_graph(
         self,
         ontology_id: UUID,
@@ -361,7 +355,7 @@ async def build_entity_graph(
         max_nodes: int = 200,
         include_see_also: bool = True,
         max_see_also_per_node: int = 5,
-    ) -> "EntityGraphResponse | None":
+    ) -> EntityGraphResponse | None:
         """Build a multi-hop graph around a class via BFS.
 
         Traverses ancestors (subClassOf upward), descendants (subClassOf downward),
@@ -405,12 +399,13 @@ def _is_external(iri: str) -> bool:
 
         def _is_root_class(uri: URIRef) -> bool:
             parents = [
-                p for p in graph.objects(uri, RDFS.subClassOf)
+                p
+                for p in graph.objects(uri, RDFS.subClassOf)
                 if isinstance(p, URIRef) and p != owl_thing
             ]
             return len(parents) == 0
 
-        def _classify_node(uri: URIRef, is_focus: bool, depth: int) -> str:
+        def _classify_node(uri: URIRef, is_focus: bool, _depth: int) -> str:
             iri = str(uri)
             if is_focus:
                 return "focus"
@@ -419,7 +414,11 @@ def _classify_node(uri: URIRef, is_focus: bool, depth: int) -> str:
             # Check if individual (instance, not a class)
             if (uri, RDF.type, OWL.Class) not in graph:
                 for rdf_type in graph.objects(uri, RDF.type):
-                    if rdf_type in (OWL.ObjectProperty, OWL.DatatypeProperty, OWL.AnnotationProperty):
+                    if rdf_type in (
+                        OWL.ObjectProperty,
+                        OWL.DatatypeProperty,
+                        OWL.AnnotationProperty,
+                    ):
                         return "property"
                 return "individual"
             if _is_root_class(uri):
@@ -438,7 +437,8 @@ def _get_definition(uri: URIRef) -> str | None:
 
         def _child_count(uri: URIRef) -> int:
             return sum(
-                1 for s in graph.subjects(RDFS.subClassOf, uri)
+                1
+                for s in graph.subjects(RDFS.subClassOf, uri)
                 if isinstance(s, URIRef) and (s, RDF.type, OWL.Class) in graph
             )
 
@@ -449,7 +449,7 @@ def _make_node(uri: URIRef, depth: int) -> GraphNode | None:
             total_discovered[0] += 1
             if len(visited) >= max_nodes:
                 return None
-            is_focus = (uri == class_uri)
+            is_focus = uri == class_uri
             node = GraphNode(
                 id=iri,
                 label=_get_label(uri),
@@ -469,7 +469,9 @@ def _add_edge(source: str, target: str, edge_type: str, label: str | None = None
             if eid in edge_ids:
                 return
             edge_ids.add(eid)
-            edges.append(GraphEdge(id=eid, source=source, target=target, edge_type=edge_type, label=label))
+            edges.append(
+                GraphEdge(id=eid, source=source, target=target, edge_type=edge_type, label=label)
+            )
 
         # Create focus node
         focus_node = _make_node(class_uri, 0)
diff --git a/tests/unit/test_entity_graph.py b/tests/unit/test_entity_graph.py
