basic-memory 0.7.0__py3-none-any.whl → 0.17.4__py3-none-any.whl

basic_memory/project_resolver.py

@@ -0,0 +1,222 @@
+"""Unified project resolution across MCP, API, and CLI.
+
+This module provides a single canonical implementation of project resolution
+logic, eliminating duplicated decision trees across the codebase.
+
+The resolution follows a three-tier hierarchy:
+1. Constrained mode: BASIC_MEMORY_MCP_PROJECT env var (highest priority)
+2. Explicit parameter: Project passed directly to operation
+3. Default project: Used when default_project_mode=true (lowest priority)
+
+In cloud mode, project is required unless discovery mode is explicitly allowed.
+"""
+
+import os
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import Optional
+
+from loguru import logger
+
+
+class ResolutionMode(Enum):
+    """How the project was resolved."""
+
+    CLOUD_EXPLICIT = auto()  # Explicit project in cloud mode
+    CLOUD_DISCOVERY = auto()  # Discovery mode allowed in cloud (no project)
+    ENV_CONSTRAINT = auto()  # BASIC_MEMORY_MCP_PROJECT env var
+    EXPLICIT = auto()  # Explicit project parameter
+    DEFAULT = auto()  # default_project with default_project_mode=true
+    NONE = auto()  # No resolution possible
+
+
+@dataclass(frozen=True)
+class ResolvedProject:
+    """Result of project resolution.
+
+    Attributes:
+        project: The resolved project name, or None if not resolved
+        mode: How the project was resolved
+        reason: Human-readable explanation of resolution
+    """
+
+    project: Optional[str]
+    mode: ResolutionMode
+    reason: str
+
+    @property
+    def is_resolved(self) -> bool:
+        """Whether a project was successfully resolved."""
+        return self.project is not None
+
+    @property
+    def is_discovery_mode(self) -> bool:
+        """Whether we're in discovery mode (no specific project)."""
+        return self.mode == ResolutionMode.CLOUD_DISCOVERY or (
+            self.mode == ResolutionMode.NONE and self.project is None
+        )
+
+
+@dataclass
+class ProjectResolver:
+    """Unified project resolution logic.
+
+    Resolves the effective project given requested project, environment
+    constraints, and configuration settings.
+
+    This is the single canonical implementation of project resolution,
+    used by MCP tools, API routes, and CLI commands.
+
+    Args:
+        cloud_mode: Whether running in cloud mode (project required)
+        default_project_mode: Whether to use default project when not specified
+        default_project: The default project name
+        constrained_project: Optional env-constrained project override
+            (typically from BASIC_MEMORY_MCP_PROJECT)
+    """
+
+    cloud_mode: bool = False
+    default_project_mode: bool = False
+    default_project: Optional[str] = None
+    constrained_project: Optional[str] = None
+
+    @classmethod
+    def from_env(
+        cls,
+        cloud_mode: bool = False,
+        default_project_mode: bool = False,
+        default_project: Optional[str] = None,
+    ) -> "ProjectResolver":
+        """Create resolver with constrained_project from environment.
+
+        Args:
+            cloud_mode: Whether running in cloud mode
+            default_project_mode: Whether to use default project when not specified
+            default_project: The default project name
+
+        Returns:
+            ProjectResolver configured with current environment
+        """
+        constrained = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
+        return cls(
+            cloud_mode=cloud_mode,
+            default_project_mode=default_project_mode,
+            default_project=default_project,
+            constrained_project=constrained,
+        )
+
+    def resolve(
+        self,
+        project: Optional[str] = None,
+        allow_discovery: bool = False,
+    ) -> ResolvedProject:
+        """Resolve project using the three-tier hierarchy.
+
+        Resolution order:
+        1. Cloud mode check (project required unless discovery allowed)
+        2. Constrained project from env var (highest priority in local mode)
+        3. Explicit project parameter
+        4. Default project if default_project_mode=true
+
+        Args:
+            project: Optional explicit project parameter
+            allow_discovery: If True, allows returning None in cloud mode
+                for discovery operations (e.g., recent_activity across projects)
+
+        Returns:
+            ResolvedProject with project name, resolution mode, and reason
+
+        Raises:
+            ValueError: If in cloud mode and no project specified (unless discovery allowed)
+        """
+        # --- Cloud Mode Handling ---
+        # In cloud mode, project is required unless discovery is explicitly allowed
+        if self.cloud_mode:
+            if project:
+                logger.debug(f"Cloud mode: using explicit project '{project}'")
+                return ResolvedProject(
+                    project=project,
+                    mode=ResolutionMode.CLOUD_EXPLICIT,
+                    reason=f"Explicit project in cloud mode: {project}",
+                )
+            elif allow_discovery:
+                logger.debug("Cloud mode: discovery mode allowed, no project required")
+                return ResolvedProject(
+                    project=None,
+                    mode=ResolutionMode.CLOUD_DISCOVERY,
+                    reason="Discovery mode enabled in cloud",
+                )
+            else:
+                raise ValueError("No project specified. Project is required for cloud mode.")
+
+        # --- Local Mode: Three-Tier Hierarchy ---
+
+        # Priority 1: CLI constraint overrides everything
+        if self.constrained_project:
+            logger.debug(f"Using CLI constrained project: {self.constrained_project}")
+            return ResolvedProject(
+                project=self.constrained_project,
+                mode=ResolutionMode.ENV_CONSTRAINT,
+                reason=f"Environment constraint: BASIC_MEMORY_MCP_PROJECT={self.constrained_project}",
+            )
+
+        # Priority 2: Explicit project parameter
+        if project:
+            logger.debug(f"Using explicit project parameter: {project}")
+            return ResolvedProject(
+                project=project,
+                mode=ResolutionMode.EXPLICIT,
+                reason=f"Explicit parameter: {project}",
+            )
+
+        # Priority 3: Default project mode
+        if self.default_project_mode and self.default_project:
+            logger.debug(f"Using default project from config: {self.default_project}")
+            return ResolvedProject(
+                project=self.default_project,
+                mode=ResolutionMode.DEFAULT,
+                reason=f"Default project mode: {self.default_project}",
+            )
+
+        # No resolution possible
+        logger.debug("No project resolution possible")
+        return ResolvedProject(
+            project=None,
+            mode=ResolutionMode.NONE,
+            reason="No project specified and default_project_mode is disabled",
+        )
+
+    def require_project(
+        self,
+        project: Optional[str] = None,
+        error_message: Optional[str] = None,
+    ) -> ResolvedProject:
+        """Resolve project, raising an error if not resolved.
+
+        Convenience method for operations that require a project.
+
+        Args:
+            project: Optional explicit project parameter
+            error_message: Custom error message if project not resolved
+
+        Returns:
+            ResolvedProject (always with a non-None project)
+
+        Raises:
+            ValueError: If project could not be resolved
+        """
+        result = self.resolve(project, allow_discovery=False)
+        if not result.is_resolved:
+            msg = error_message or (
+                "No project specified. Either set 'default_project_mode=true' in config, "
+                "or provide a 'project' argument."
+            )
+            raise ValueError(msg)
+        return result
+
+
+__all__ = [
+    "ProjectResolver",
+    "ResolvedProject",
+    "ResolutionMode",
+]

basic_memory/repository/__init__.py

@@ -1,9 +1,11 @@
 from .entity_repository import EntityRepository
 from .observation_repository import ObservationRepository
+from .project_repository import ProjectRepository
 from .relation_repository import RelationRepository
 
 __all__ = [
     "EntityRepository",
     "ObservationRepository",
+    "ProjectRepository",
     "RelationRepository",
 ]