Skip to content

BrainAPI is a knowledge graph–powered AI memory layer that transforms unstructured data into structured knowledge, enabling intelligent search, recommendations, and contextual memory for AI agents and applications.

6.0 KB
Raw Blame
"""Profile-aware lifecycle operations for BrainAPI brains."""

from __future__ import annotations

from contextlib import contextmanager
from dataclasses import dataclass
import logging
from typing import Any, Iterator, Protocol


logger = logging.getLogger(__name__)


class BrainLifecycleError(RuntimeError):
    """Base class for lifecycle failures safe to map at the API boundary."""


class InvalidBrainIdError(BrainLifecycleError):
    """Raised when a lifecycle target is invalid or reserved."""


class BrainNotFoundError(BrainLifecycleError):
    """Raised when a clear operation targets an unknown brain."""


class BrainLifecycleBusyError(BrainLifecycleError):
    """Raised when another lifecycle operation already owns the brain lock."""


class BrainCleanupError(BrainLifecycleError):
    """Raised after one or more storage backends fail to clear."""

    def __init__(self, brain_id: str, failed_backends: list[str]):
        self.brain_id = brain_id
        self.failed_backends = failed_backends
        super().__init__(
            "Could not clear every storage backend for brain "
            f'"{brain_id}": {", ".join(failed_backends)}'
        )


class DataLifecycleClient(Protocol):
    def get_brain(self, name_key: str) -> Any: ...

    def clear_brain_data(self, brain_id: str) -> Any: ...

    def delete_brain_registry(self, brain_id: str) -> bool: ...


class StorageLifecycleClient(Protocol):
    def clear_brain_data(self, brain_id: str) -> Any: ...


class CacheLifecycleClient(StorageLifecycleClient, Protocol):
    client: Any

    def clear_brain_registry_cache(self, brain_id: str) -> Any: ...


@dataclass(frozen=True)
class BrainLifecycleResult:
    brain_id: str
    operation: str
    existed: bool
    cleared_backends: list[str]

    def as_dict(self) -> dict[str, Any]:
        return {
            "success": True,
            "brain_id": self.brain_id,
            "operation": self.operation,
            "existed": self.existed,
            "cleared_backends": self.cleared_backends,
        }


def validate_brain_id(brain_id: str) -> str:
    normalized = (brain_id or "").strip()
    if (
        not normalized
        or not normalized.isalnum()
        or not normalized[0].isalpha()
    ):
        raise InvalidBrainIdError(
            "brain_id must be alphanumeric and start with a letter"
        )
    if normalized.lower() == "system":
        raise InvalidBrainIdError('brain_id "system" is reserved')
    return normalized


class BrainLifecycleService:
    """Clear or delete one brain across the active storage profile."""

    def __init__(
        self,
        *,
        data_client: DataLifecycleClient,
        graph_client: StorageLifecycleClient,
        vector_client: StorageLifecycleClient,
        cache_client: CacheLifecycleClient,
    ) -> None:
        self._data = data_client
        self._graph = graph_client
        self._vector = vector_client
        self._cache = cache_client

    @contextmanager
    def _lock(self, brain_id: str) -> Iterator[None]:
        redis = getattr(self._cache, "client", None)
        if redis is None or not hasattr(redis, "lock"):
            yield
            return

        lock = redis.lock(
            f"system:brain-lifecycle:{brain_id}",
            timeout=300,
            blocking_timeout=1,
        )
        if not lock.acquire(blocking=True):
            raise BrainLifecycleBusyError(
                f'Another lifecycle operation is running for brain "{brain_id}"'
            )
        try:
            yield
        finally:
            try:
                lock.release()
            except Exception:
                # The lock has a TTL and may already have expired. Cleanup must not
                # turn a successful destructive operation into a false failure.
                pass

    def _clear_backends(self, brain_id: str) -> list[str]:
        backends = (
            ("data", self._data),
            ("graph", self._graph),
            ("vectors", self._vector),
            ("cache", self._cache),
        )
        cleared: list[str] = []
        failed: list[str] = []

        for name, backend in backends:
            try:
                backend.clear_brain_data(brain_id)
                cleared.append(name)
            except Exception:
                logger.exception(
                    "Failed to clear %s backend for brain %s",
                    name,
                    brain_id,
                )
                failed.append(name)

        if failed:
            raise BrainCleanupError(brain_id, failed)
        return cleared

    def clear(self, brain_id: str) -> BrainLifecycleResult:
        brain_id = validate_brain_id(brain_id)
        with self._lock(brain_id):
            if self._data.get_brain(brain_id) is None:
                raise BrainNotFoundError(f'Brain "{brain_id}" was not found')
            cleared = self._clear_backends(brain_id)
        return BrainLifecycleResult(
            brain_id=brain_id,
            operation="clear",
            existed=True,
            cleared_backends=cleared,
        )

    def delete(self, brain_id: str) -> BrainLifecycleResult:
        brain_id = validate_brain_id(brain_id)
        with self._lock(brain_id):
            existed = self._data.get_brain(brain_id) is not None
            cleared = self._clear_backends(brain_id)
            try:
                self._cache.clear_brain_registry_cache(brain_id)
            except Exception:
                logger.exception(
                    "Failed to clear registry cache for brain %s", brain_id
                )
                raise BrainCleanupError(brain_id, ["registry_cache"]) from None
            try:
                self._data.delete_brain_registry(brain_id)
            except Exception:
                logger.exception("Failed to delete registry for brain %s", brain_id)
                raise BrainCleanupError(brain_id, ["registry"]) from None

        return BrainLifecycleResult(
            brain_id=brain_id,
            operation="delete",
            existed=existed,
            cleared_backends=cleared,
        )