Phase 5.5-5.9: Plugin-Marketplace, Agent Memory, GraphRAG, Subagents, External Agent API

5.5 Plugin-Marketplace: - New plugin: marketplace/ (models, routes, services, schemas, config) - MarketplaceListing model (global, no tenant_id) - Ed25519 signature verification via PluginSignature - Endpoints: list, detail, install, verify, categories - Config: MARKETPLACE_SERVER_URL setting 5.6 Agent Memory (persistent): - New plugin: agent_memory/ (models, routes, services, schemas) - AgentMemory model with embedding vector(768) + HNSW index - store_memory() with auto-embedding - retrieve_relevant_memories() with pgvector cosine similarity - Semantic search endpoint 5.7 GraphRAG: - New plugin: graph_rag/ (models, routes, services, provider, schemas) - EntityRelationship model (source/target type+id, relationship_type, metadata) - BFS graph traversal (bidirectional, configurable depth) - GraphRAGSearchProvider registered in unified_search 5.8 Subagents / Multi-Agent: - AgentCoordinator class (create_subtask, wait_for_subtask, aggregate, cancel) - AgentSubtask model + migration 0002_agent_subtasks.sql - 6 new API endpoints for subtask management - Tools registered in AI tool registry 5.9 External Agent API: - external_api.py: POST /run, GET /status, POST /stream (SSE) - Bearer API token authentication - Rate limiting: 10 req/min per token - ExternalAgentRequest/Response schemas 3 new plugins registered in main.py and __init__.py All files py_compile clean
2026-08-04 15:06:23 +02:00
parent 597aea1c23
commit 000c969b13
36 changed files with 3118 additions and 2 deletions
@@ -0,0 +1,5 @@
+"""GraphRAG plugin package."""
+
+from app.plugins.builtins.graph_rag.plugin import GraphRAGPlugin
+
+__all__ = ["GraphRAGPlugin"]
@@ -0,0 +1,20 @@
+-- GraphRAG plugin initial migration: creates entity_relationships table
+CREATE TABLE IF NOT EXISTS entity_relationships (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    tenant_id UUID NOT NULL,
+    source_type VARCHAR(50) NOT NULL,
+    source_id UUID NOT NULL,
+    target_type VARCHAR(50) NOT NULL,
+    target_id UUID NOT NULL,
+    relationship_type VARCHAR(50) NOT NULL,
+    metadata JSONB DEFAULT '{}'::jsonb,
+    owner_id UUID REFERENCES users(id) ON DELETE SET NULL,
+    deleted_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS ix_entity_relationships_source ON entity_relationships(tenant_id, source_type, source_id);
+CREATE INDEX IF NOT EXISTS ix_entity_relationships_target ON entity_relationships(tenant_id, target_type, target_id);
+CREATE INDEX IF NOT EXISTS ix_entity_relationships_type ON entity_relationships(tenant_id, relationship_type);
+CREATE INDEX IF NOT EXISTS ix_entity_relationships_source_target ON entity_relationships(tenant_id, source_type, source_id, target_type, target_id);
+CREATE INDEX IF NOT EXISTS ix_entity_relationships_owner ON entity_relationships(owner_id);
@@ -0,0 +1,52 @@
+"""EntityRelationship model for GraphRAG — stores relationships between entities."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from sqlalchemy import Index, String
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.core.db import Base, TenantMixin
+from app.models.owned_mixin import OwnedMixin
+
+
+class EntityRelationship(Base, TenantMixin, OwnedMixin):
+    """Directed relationship between two entities in the knowledge graph.
+
+    Stores typed relationships (e.g., 'works_for', 'has_email', 'related_to')
+    between any two entities in the system. Used for GraphRAG traversal.
+    """
+
+    __tablename__ = "entity_relationships"
+    __table_args__ = (
+        Index("ix_entity_relationships_source", "tenant_id", "source_type", "source_id"),
+        Index("ix_entity_relationships_target", "tenant_id", "target_type", "target_id"),
+        Index("ix_entity_relationships_type", "tenant_id", "relationship_type"),
+        Index("ix_entity_relationships_source_target", "tenant_id", "source_type", "source_id", "target_type", "target_id"),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), primary_key=True, default=uuid.uuid4
+    )
+    source_type: Mapped[str] = mapped_column(
+        String(50), nullable=False, comment="Entity type of the source (e.g. 'contact', 'company', 'file')"
+    )
+    source_id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), nullable=False, comment="UUID of the source entity"
+    )
+    target_type: Mapped[str] = mapped_column(
+        String(50), nullable=False, comment="Entity type of the target (e.g. 'contact', 'email', 'task')"
+    )
+    target_id: Mapped[uuid.UUID] = mapped_column(
+        PGUUID(as_uuid=True), nullable=False, comment="UUID of the target entity"
+    )
+    relationship_type: Mapped[str] = mapped_column(
+        String(50), nullable=False, comment="Type of relationship (e.g. 'works_for', 'has_email', 'related_to')"
+    )
+    metadata: Mapped[dict[str, Any] | None] = mapped_column(
+        JSONB, nullable=True, default=dict, comment="Arbitrary metadata about the relationship"
+    )
@@ -0,0 +1,58 @@
+"""GraphRAG plugin — entity relationship graph with BFS traversal and search provider."""
+
+from __future__ import annotations
+
+from app.plugins.base import BasePlugin
+from app.plugins.manifest import PluginManifest, PluginRouteDef
+
+
+class GraphRAGPlugin(BasePlugin):
+    """GraphRAG plugin for entity relationship graph with BFS traversal."""
+
+    manifest = PluginManifest(
+        name="graph_rag",
+        version="1.0.0",
+        display_name="GraphRAG",
+        description="Entity relationship graph with BFS traversal and unified search integration. Stores typed relationships between entities for knowledge graph exploration.",
+        dependencies=["unified_search"],
+        routes=[
+            PluginRouteDef(
+                path="/api/v1/graph",
+                module="app.plugins.builtins.graph_rag.routes",
+                router_attr="router",
+            ),
+        ],
+        events=[],
+        migrations=["0001_initial.sql"],
+        permissions=[
+            "graph:read",
+            "graph:write",
+        ],
+        is_core=True,
+        author="LeoCRM Team",
+        min_app_version="1.0.0",
+        contract_version="1.0.0",
+    )
+
+    async def on_activate(self, db, service_container, event_bus) -> None:
+        """Activate plugin: register GraphRAG search provider."""
+        from app.plugins.builtins.graph_rag.provider import GraphRAGSearchProvider
+        from app.plugins.builtins.unified_search.provider_registry import get_search_registry
+
+        registry = get_search_registry()
+        try:
+            registry.register(GraphRAGSearchProvider())
+        except Exception:
+            import logging
+            logging.getLogger(__name__).exception("Failed to register GraphRAGSearchProvider")
+
+        await super().on_activate(db, service_container, event_bus)
+
+    async def on_deactivate(self, db, service_container, event_bus) -> None:
+        """Deactivate plugin: unregister search provider and contract."""
+        from app.plugins.builtins.unified_search.provider_registry import get_search_registry
+        get_search_registry().unregister("graph_relationship")
+
+        from app.plugins.builtins.contracts import get_contract_registry
+        get_contract_registry().unregister(self.manifest.name)
+        await super().on_deactivate(db, service_container, event_bus)
@@ -0,0 +1,165 @@
+"""GraphRAGSearchProvider — registers GraphRAG as a search provider in unified_search."""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import Any
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.plugins.builtins.unified_search.base_provider import BaseSearchProvider
+
+logger = logging.getLogger(__name__)
+
+
+class GraphRAGSearchProvider(BaseSearchProvider):
+    """Search provider for GraphRAG entity relationships.
+
+    Enables full-text and semantic search over relationship metadata
+    and entity types in the knowledge graph.
+    """
+
+    entity_type = "graph_relationship"
+
+    async def _search_fts_filtered(
+        self,
+        db: AsyncSession,
+        tsquery: str,
+        tenant_id: uuid.UUID,
+        limit: int,
+        visible_ids: set[uuid.UUID] | None,
+    ) -> list[dict[str, Any]]:
+        """Full-text search on relationship metadata and types."""
+        if visible_ids is not None:
+            sql = text(
+                """
+                SELECT r.*, ts_rank(
+                    to_tsvector('pg_catalog.german',
+                        coalesce(r.relationship_type, '') || ' ' ||
+                        coalesce(r.source_type, '') || ' ' ||
+                        coalesce(r.target_type, '') || ' ' ||
+                        coalesce(r.metadata::text, '')
+                    ),
+                    to_tsquery('pg_catalog.german', :q)
+                ) AS rank
+                FROM entity_relationships r
+                WHERE r.tenant_id = :tid
+                  AND r.deleted_at IS NULL
+                  AND to_tsvector('pg_catalog.german',
+                      coalesce(r.relationship_type, '') || ' ' ||
+                      coalesce(r.source_type, '') || ' ' ||
+                      coalesce(r.target_type, '') || ' ' ||
+                      coalesce(r.metadata::text, '')
+                  ) @@ to_tsquery('pg_catalog.german', :q)
+                  AND r.id = ANY(:visible_ids)
+                ORDER BY rank DESC
+                LIMIT :lim
+                """
+            )
+            result = await db.execute(
+                sql,
+                {
+                    "q": tsquery,
+                    "tid": tenant_id,
+                    "lim": limit,
+                    "visible_ids": list(visible_ids),
+                },
+            )
+        else:
+            sql = text(
+                """
+                SELECT r.*, ts_rank(
+                    to_tsvector('pg_catalog.german',
+                        coalesce(r.relationship_type, '') || ' ' ||
+                        coalesce(r.source_type, '') || ' ' ||
+                        coalesce(r.target_type, '') || ' ' ||
+                        coalesce(r.metadata::text, '')
+                    ),
+                    to_tsquery('pg_catalog.german', :q)
+                ) AS rank
+                FROM entity_relationships r
+                WHERE r.tenant_id = :tid
+                  AND r.deleted_at IS NULL
+                  AND to_tsvector('pg_catalog.german',
+                      coalesce(r.relationship_type, '') || ' ' ||
+                      coalesce(r.source_type, '') || ' ' ||
+                      coalesce(r.target_type, '') || ' ' ||
+                      coalesce(r.metadata::text, '')
+                  ) @@ to_tsquery('pg_catalog.german', :q)
+                ORDER BY rank DESC
+                LIMIT :lim
+                """
+            )
+            result = await db.execute(
+                sql,
+                {"q": tsquery, "tid": tenant_id, "lim": limit},
+            )
+        rows = result.mappings().all()
+        return [dict(r) for r in rows]
+
+    async def _search_vector_filtered(
+        self,
+        db: AsyncSession,
+        embedding: list[float],
+        tenant_id: uuid.UUID,
+        limit: int,
+        visible_ids: set[uuid.UUID] | None,
+    ) -> list[dict[str, Any]]:
+        """Semantic search is not yet supported for graph relationships.
+
+        Returns empty list — relationships are searched via FTS on metadata.
+        """
+        return []
+
+    async def get_embedding_text(
+        self, db: AsyncSession, entity_id: uuid.UUID, tenant_id: uuid.UUID
+    ) -> str:
+        """Get text for embedding generation."""
+        sql = text(
+            """
+            SELECT relationship_type, source_type, source_id, target_type, target_id, metadata
+            FROM entity_relationships
+            WHERE id = :eid AND tenant_id = :tid
+            """
+        )
+        result = await db.execute(sql, {"eid": entity_id, "tid": tenant_id})
+        row = result.mappings().first()
+        if not row:
+            return ""
+        parts = [
+            row.get("relationship_type", ""),
+            row.get("source_type", ""),
+            str(row.get("source_id", "")),
+            row.get("target_type", ""),
+            str(row.get("target_id", "")),
+            str(row.get("metadata", {})),
+        ]
+        return " ".join(str(p) for p in parts if p)
+
+    def to_search_result(self, entity: object) -> dict[str, Any]:
+        """Convert relationship to search result dict."""
+        if isinstance(entity, dict):
+            return {
+                "entity_type": self.entity_type,
+                "entity_id": str(entity.get("id", "")),
+                "title": f"{entity.get('source_type', '?')} --[{entity.get('relationship_type', '?')}]--> {entity.get('target_type', '?')}",
+                "snippet": str(entity.get("metadata", {})),
+                "score": float(entity.get("rank", 0.0)),
+                "data": {
+                    "source_type": entity.get("source_type"),
+                    "source_id": str(entity.get("source_id", "")),
+                    "target_type": entity.get("target_type"),
+                    "target_id": str(entity.get("target_id", "")),
+                    "relationship_type": entity.get("relationship_type"),
+                },
+            }
+        return {
+            "entity_type": self.entity_type,
+            "entity_id": str(getattr(entity, "id", "")),
+            "title": f"{getattr(entity, 'source_type', '?')} --[{getattr(entity, 'relationship_type', '?')}]--> {getattr(entity, 'target_type', '?')}",
+            "snippet": str(getattr(entity, "metadata", {})),
+            "score": 0.0,
+            "data": {},
+        }
@@ -0,0 +1,168 @@
+"""GraphRAG plugin routes — relationship CRUD and BFS graph traversal."""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.db import get_db
+from app.deps import get_current_user, require_permission
+from app.plugins.builtins.graph_rag.models import EntityRelationship
+from app.plugins.builtins.graph_rag.schemas import (
+    RelationshipCreate,
+    TraverseRequest,
+)
+from app.plugins.builtins.graph_rag.services import (
+    create_relationship,
+    delete_relationship,
+    traverse_graph,
+)
+
+router = APIRouter(prefix="/api/v1/graph", tags=["graph-rag"])
+
+
+@router.post("/relationships", status_code=status.HTTP_201_CREATED, dependencies=[Depends(require_permission("graph:write"))])
+async def create_relationship_route(
+    body: RelationshipCreate,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Create a new relationship between two entities."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    user_id = uuid.UUID(current_user["user_id"])
+    source_id = _parse_uuid(body.source_id, "source_id")
+    target_id = _parse_uuid(body.target_id, "target_id")
+
+    result = await create_relationship(
+        db=db,
+        tenant_id=tenant_id,
+        source_type=body.source_type,
+        source_id=source_id,
+        target_type=body.target_type,
+        target_id=target_id,
+        relationship_type=body.relationship_type,
+        metadata=body.metadata,
+        owner_id=user_id,
+    )
+
+    if "error" in result:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail={"detail": result["error"], "code": result.get("code", "duplicate")},
+        )
+
+    return result
+
+
+@router.get("/relationships", dependencies=[Depends(require_permission("graph:read"))])
+async def list_relationships(
+    source_type: str | None = Query(None, description="Filter by source entity type"),
+    source_id: str | None = Query(None, description="Filter by source entity UUID"),
+    target_type: str | None = Query(None, description="Filter by target entity type"),
+    target_id: str | None = Query(None, description="Filter by target entity UUID"),
+    relationship_type: str | None = Query(None, description="Filter by relationship type"),
+    page: int = Query(1, ge=1),
+    page_size: int = Query(50, ge=1, le=200),
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """List relationships with optional filters."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+
+    base = select(EntityRelationship).where(
+        EntityRelationship.tenant_id == tenant_id,
+        EntityRelationship.deleted_at.is_(None),
+    )
+
+    if source_type:
+        base = base.where(EntityRelationship.source_type == source_type)
+    if source_id:
+        base = base.where(EntityRelationship.source_id == _parse_uuid(source_id, "source_id"))
+    if target_type:
+        base = base.where(EntityRelationship.target_type == target_type)
+    if target_id:
+        base = base.where(EntityRelationship.target_id == _parse_uuid(target_id, "target_id"))
+    if relationship_type:
+        base = base.where(EntityRelationship.relationship_type == relationship_type)
+
+    # Count total
+    count_q = select(func.count()).select_from(base.subquery())
+    total_result = await db.execute(count_q)
+    total = total_result.scalar_one()
+
+    # Paginated query
+    offset = (page - 1) * page_size
+    stmt = base.order_by(EntityRelationship.created_at.desc()).offset(offset).limit(page_size)
+    result = await db.execute(stmt)
+    relationships = result.scalars().all()
+
+    return {
+        "items": [
+            {
+                "id": str(r.id),
+                "source_type": r.source_type,
+                "source_id": str(r.source_id),
+                "target_type": r.target_type,
+                "target_id": str(r.target_id),
+                "relationship_type": r.relationship_type,
+                "metadata": r.metadata,
+                "owner_id": str(r.owner_id) if r.owner_id else None,
+                "created_at": r.created_at.isoformat() if r.created_at else None,
+            }
+            for r in relationships
+        ],
+        "total": total,
+    }
+
+
+@router.post("/traverse", dependencies=[Depends(require_permission("graph:read"))])
+async def traverse_graph_route(
+    body: TraverseRequest,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """BFS traversal of the knowledge graph from a starting node."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    source_id = _parse_uuid(body.source_id, "source_id")
+
+    result = await traverse_graph(
+        db=db,
+        tenant_id=tenant_id,
+        source_type=body.source_type,
+        source_id=source_id,
+        max_hops=body.max_hops,
+        relationship_types=body.relationship_types,
+    )
+    return result
+
+
+@router.delete("/relationships/{relationship_id}", status_code=status.HTTP_204_NO_CONTENT, dependencies=[Depends(require_permission("graph:write"))])
+async def delete_relationship_route(
+    relationship_id: str,
+    db: AsyncSession = Depends(get_db),
+    current_user: dict = Depends(get_current_user),
+):
+    """Delete a relationship by ID."""
+    tenant_id = uuid.UUID(current_user["tenant_id"])
+    rid = _parse_uuid(relationship_id, "relationship_id")
+
+    success = await delete_relationship(db, tenant_id, rid)
+    if not success:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail={"detail": "Relationship not found", "code": "not_found"},
+        )
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+def _parse_uuid(val: str, field: str) -> uuid.UUID:
+    try:
+        return uuid.UUID(val)
+    except (ValueError, TypeError):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail={"detail": f"Invalid {field}", "code": "invalid_id"},
+        ) from None
@@ -0,0 +1,59 @@
+"""Pydantic schemas for the GraphRAG plugin."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class RelationshipCreate(BaseModel):
+    source_type: str = Field(..., max_length=50, description="Entity type of the source (e.g. 'contact', 'company')")
+    source_id: str = Field(..., description="UUID of the source entity")
+    target_type: str = Field(..., max_length=50, description="Entity type of the target (e.g. 'email', 'task')")
+    target_id: str = Field(..., description="UUID of the target entity")
+    relationship_type: str = Field(..., max_length=50, description="Type of relationship (e.g. 'works_for', 'has_email')")
+    metadata: dict[str, Any] | None = Field(None, description="Arbitrary metadata about the relationship")
+
+
+class RelationshipRead(BaseModel):
+    id: str
+    source_type: str
+    source_id: str
+    target_type: str
+    target_id: str
+    relationship_type: str
+    metadata: dict[str, Any] | None = None
+    owner_id: str | None = None
+    created_at: datetime | None = None
+
+
+class TraverseRequest(BaseModel):
+    source_type: str = Field(..., max_length=50, description="Entity type of the starting node")
+    source_id: str = Field(..., description="UUID of the starting node")
+    max_hops: int = Field(3, ge=1, le=10, description="Maximum traversal depth")
+    relationship_types: list[str] | None = Field(None, description="Optional filter by relationship types")
+
+
+class GraphNode(BaseModel):
+    entity_type: str
+    entity_id: str
+    depth: int
+    path: list[str] = []
+
+
+class GraphEdge(BaseModel):
+    source_type: str
+    source_id: str
+    target_type: str
+    target_id: str
+    relationship_type: str
+    metadata: dict[str, Any] | None = None
+
+
+class TraverseResponse(BaseModel):
+    nodes: list[GraphNode]
+    edges: list[GraphEdge]
+    total_nodes: int
+    total_edges: int
@@ -0,0 +1,226 @@
+"""GraphRAG services — relationship management and BFS graph traversal."""
+
+from __future__ import annotations
+
+import uuid
+from collections import deque
+from typing import Any
+
+from sqlalchemy import select, text as sql_text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.plugins.builtins.graph_rag.models import EntityRelationship
+
+
+async def create_relationship(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    source_type: str,
+    source_id: uuid.UUID,
+    target_type: str,
+    target_id: uuid.UUID,
+    relationship_type: str,
+    metadata: dict[str, Any] | None = None,
+    owner_id: uuid.UUID | None = None,
+) -> dict[str, Any]:
+    """Create a new relationship between two entities.
+
+    Args:
+        db: Database session.
+        tenant_id: Tenant UUID.
+        source_type: Entity type of the source.
+        source_id: UUID of the source entity.
+        target_type: Entity type of the target.
+        target_id: UUID of the target entity.
+        relationship_type: Type of relationship.
+        metadata: Optional metadata dict.
+        owner_id: Optional owner user UUID.
+
+    Returns:
+        Dict with the created relationship data.
+    """
+    # Check for duplicate
+    existing = await db.execute(
+        select(EntityRelationship).where(
+            EntityRelationship.tenant_id == tenant_id,
+            EntityRelationship.source_type == source_type,
+            EntityRelationship.source_id == source_id,
+            EntityRelationship.target_type == target_type,
+            EntityRelationship.target_id == target_id,
+            EntityRelationship.relationship_type == relationship_type,
+            EntityRelationship.deleted_at.is_(None),
+        )
+    )
+    if existing.scalar_one_or_none() is not None:
+        return {"error": "Relationship already exists", "code": "duplicate"}
+
+    rel = EntityRelationship(
+        tenant_id=tenant_id,
+        source_type=source_type,
+        source_id=source_id,
+        target_type=target_type,
+        target_id=target_id,
+        relationship_type=relationship_type,
+        metadata=metadata or {},
+        owner_id=owner_id,
+    )
+    db.add(rel)
+    await db.flush()
+    await db.refresh(rel)
+
+    return {
+        "id": str(rel.id),
+        "source_type": rel.source_type,
+        "source_id": str(rel.source_id),
+        "target_type": rel.target_type,
+        "target_id": str(rel.target_id),
+        "relationship_type": rel.relationship_type,
+        "metadata": rel.metadata,
+        "owner_id": str(rel.owner_id) if rel.owner_id else None,
+        "created_at": rel.created_at.isoformat() if rel.created_at else None,
+    }
+
+
+async def traverse_graph(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    source_type: str,
+    source_id: uuid.UUID,
+    max_hops: int = 3,
+    relationship_types: list[str] | None = None,
+) -> dict[str, Any]:
+    """BFS traversal of the knowledge graph from a starting node.
+
+    Uses Breadth-First Search to find all entities reachable within
+    `max_hops` steps, following directed relationships.
+
+    Args:
+        db: Database session.
+        tenant_id: Tenant UUID.
+        source_type: Entity type of the starting node.
+        source_id: UUID of the starting node.
+        max_hops: Maximum traversal depth (1-10).
+        relationship_types: Optional filter to follow only specific relationship types.
+
+    Returns:
+        Dict with nodes and edges discovered during traversal.
+    """
+    visited: set[tuple[str, str]] = set()
+    nodes: list[dict[str, Any]] = []
+    edges: list[dict[str, Any]] = []
+
+    # BFS queue: (source_type, source_id, depth, path)
+    queue: deque[tuple[str, str, int, list[str]]] = deque()
+    start_key = (source_type, str(source_id))
+    visited.add(start_key)
+    nodes.append({
+        "entity_type": source_type,
+        "entity_id": str(source_id),
+        "depth": 0,
+        "path": [],
+    })
+    queue.append((source_type, str(source_id), 0, []))
+
+    while queue:
+        current_type, current_id, depth, path = queue.popleft()
+
+        if depth >= max_hops:
+            continue
+
+        # Build query for outgoing relationships
+        stmt = select(EntityRelationship).where(
+            EntityRelationship.tenant_id == tenant_id,
+            EntityRelationship.source_type == current_type,
+            EntityRelationship.source_id == uuid.UUID(current_id),
+            EntityRelationship.deleted_at.is_(None),
+        )
+        if relationship_types:
+            stmt = stmt.where(EntityRelationship.relationship_type.in_(relationship_types))
+
+        result = await db.execute(stmt)
+        relationships = result.scalars().all()
+
+        for rel in relationships:
+            target_key = (rel.target_type, str(rel.target_id))
+            new_path = path + [rel.relationship_type]
+
+            edges.append({
+                "source_type": rel.source_type,
+                "source_id": str(rel.source_id),
+                "target_type": rel.target_type,
+                "target_id": str(rel.target_id),
+                "relationship_type": rel.relationship_type,
+                "metadata": rel.metadata,
+            })
+
+            if target_key not in visited:
+                visited.add(target_key)
+                nodes.append({
+                    "entity_type": rel.target_type,
+                    "entity_id": str(rel.target_id),
+                    "depth": depth + 1,
+                    "path": new_path,
+                })
+                queue.append((rel.target_type, str(rel.target_id), depth + 1, new_path))
+
+        # Also traverse incoming relationships (bidirectional graph)
+        stmt_in = select(EntityRelationship).where(
+            EntityRelationship.tenant_id == tenant_id,
+            EntityRelationship.target_type == current_type,
+            EntityRelationship.target_id == uuid.UUID(current_id),
+            EntityRelationship.deleted_at.is_(None),
+        )
+        if relationship_types:
+            stmt_in = stmt_in.where(EntityRelationship.relationship_type.in_(relationship_types))
+
+        result_in = await db.execute(stmt_in)
+        relationships_in = result_in.scalars().all()
+
+        for rel in relationships_in:
+            source_key = (rel.source_type, str(rel.source_id))
+            new_path = path + [f"inverse_{rel.relationship_type}"]
+
+            edges.append({
+                "source_type": rel.source_type,
+                "source_id": str(rel.source_id),
+                "target_type": rel.target_type,
+                "target_id": str(rel.target_id),
+                "relationship_type": rel.relationship_type,
+                "metadata": rel.metadata,
+            })
+
+            if source_key not in visited:
+                visited.add(source_key)
+                nodes.append({
+                    "entity_type": rel.source_type,
+                    "entity_id": str(rel.source_id),
+                    "depth": depth + 1,
+                    "path": new_path,
+                })
+                queue.append((rel.source_type, str(rel.source_id), depth + 1, new_path))
+
+    return {
+        "nodes": nodes,
+        "edges": edges,
+        "total_nodes": len(nodes),
+        "total_edges": len(edges),
+    }
+
+
+async def delete_relationship(
+    db: AsyncSession,
+    tenant_id: uuid.UUID,
+    relationship_id: uuid.UUID,
+) -> bool:
+    """Delete a relationship by ID."""
+    result = await db.execute(
+        select(EntityRelationship).where(
+            EntityRelationship.id == relationship_id,
+            EntityRelationship.tenant_id == tenant_id,
+        )
+    )
+    rel = result.scalar_one_or_none()
+    if rel is None:
+        return False
+    await db.delete(rel)
+    return True