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

basic_memory/runtime.py

@@ -0,0 +1,61 @@
+"""Runtime mode resolution for Basic Memory.
+
+This module centralizes runtime mode detection, ensuring cloud/local/test
+determination happens in one place rather than scattered across modules.
+
+Composition roots (containers) read ConfigManager and use this module
+to resolve the runtime mode, then pass the result downstream.
+"""
+
+from enum import Enum, auto
+
+
+class RuntimeMode(Enum):
+    """Runtime modes for Basic Memory."""
+
+    LOCAL = auto()  # Local standalone mode (default)
+    CLOUD = auto()  # Cloud mode with remote sync
+    TEST = auto()  # Test environment
+
+    @property
+    def is_cloud(self) -> bool:
+        return self == RuntimeMode.CLOUD
+
+    @property
+    def is_local(self) -> bool:
+        return self == RuntimeMode.LOCAL
+
+    @property
+    def is_test(self) -> bool:
+        return self == RuntimeMode.TEST
+
+
+def resolve_runtime_mode(
+    cloud_mode_enabled: bool,
+    is_test_env: bool,
+) -> RuntimeMode:
+    """Resolve the runtime mode from configuration flags.
+
+    This is the single source of truth for mode resolution.
+    Composition roots call this with config values they've read.
+
+    Args:
+        cloud_mode_enabled: Whether cloud mode is enabled in config
+        is_test_env: Whether running in test environment
+
+    Returns:
+        The resolved RuntimeMode
+    """
+    # Trigger: test environment is detected
+    # Why: tests need special handling (no file sync, isolated DB)
+    # Outcome: returns TEST mode, skipping cloud mode check
+    if is_test_env:
+        return RuntimeMode.TEST
+
+    # Trigger: cloud mode is enabled in config
+    # Why: cloud mode changes auth, sync, and API behavior
+    # Outcome: returns CLOUD mode for remote-first behavior
+    if cloud_mode_enabled:
+        return RuntimeMode.CLOUD
+
+    return RuntimeMode.LOCAL

basic_memory/schemas/base.py

@@ -21,13 +21,38 @@ from typing import List, Optional, Annotated, Dict
 from annotated_types import MinLen, MaxLen
 from dateparser import parse
 
-from pydantic import BaseModel, BeforeValidator, Field, model_validator
+from pydantic import BaseModel, BeforeValidator, Field, model_validator, computed_field
 
 from basic_memory.config import ConfigManager
 from basic_memory.file_utils import sanitize_for_filename, sanitize_for_folder
 from basic_memory.utils import generate_permalink
 
 
+def has_valid_file_extension(filename: str) -> bool:
+    """Check if a filename has a valid file extension recognized by mimetypes.
+
+    This is used to determine whether to split the extension when processing
+    titles in kebab_filenames mode. Prevents treating periods in version numbers
+    or decimals as file extensions.
+
+    Args:
+        filename: The filename to check
+
+    Returns:
+        True if the filename has a recognized file extension, False otherwise
+
+    Examples:
+        >>> has_valid_file_extension("document.md")
+        True
+        >>> has_valid_file_extension("Version 2.0.0")
+        False
+        >>> has_valid_file_extension("image.png")
+        True
+    """
+    mime_type, _ = mimetypes.guess_type(filename)
+    return mime_type is not None
+
+
 def to_snake_case(name: str) -> str:
     """Convert a string to snake_case.
 
@@ -83,7 +108,7 @@ def parse_timeframe(timeframe: str) -> datetime:
         if parsed.tzinfo is None:
             parsed = parsed.astimezone()
         else:
-            parsed = parsed
+            parsed = parsed  # pragma: no cover
 
         # Enforce minimum 1-day lookback to handle timezone differences
         # This ensures we don't miss recent activity due to client/server timezone mismatches
@@ -113,7 +138,7 @@ def validate_timeframe(timeframe: str) -> str:
     # Convert to duration
     now = datetime.now().astimezone()
     if parsed > now:
-        raise ValueError("Timeframe cannot be in the future")
+        raise ValueError("Timeframe cannot be in the future")  # pragma: no cover
 
     # Could format the duration back to our standard format
     days = (now - parsed).days
@@ -158,7 +183,7 @@ ObservationStr = Annotated[
     str,
     BeforeValidator(str.strip),  # Clean whitespace
     MinLen(1),  # Ensure non-empty after stripping
-    MaxLen(1000),  # Keep reasonable length
+    # No MaxLen - matches DB Text column which has no length restriction
 ]
 
 
@@ -232,12 +257,17 @@ class Entity(BaseModel):
         use_kebab_case = app_config.kebab_filenames
 
         if use_kebab_case:
-            fixed_title = generate_permalink(file_path=fixed_title, split_extension=False)
+            # Convert to kebab-case: lowercase with hyphens, preserving periods in version numbers
+            # generate_permalink() uses mimetypes to detect real file extensions and only splits
+            # them off, avoiding misinterpreting periods in version numbers as extensions
+            has_extension = has_valid_file_extension(fixed_title)
+            fixed_title = generate_permalink(file_path=fixed_title, split_extension=has_extension)
 
         return fixed_title
 
+    @computed_field
     @property
-    def file_path(self):
+    def file_path(self) -> str:
         """Get the file path for this entity based on its permalink."""
         safe_title = self.safe_title
         if self.content_type == "text/markdown":

basic_memory/schemas/directory.py

@@ -16,7 +16,8 @@ class DirectoryNode(BaseModel):
     children: List["DirectoryNode"] = []  # Default to empty list
     title: Optional[str] = None
     permalink: Optional[str] = None
-    entity_id: Optional[int] = None
+    external_id: Optional[str] = None  # UUID (primary API identifier for v2)
+    entity_id: Optional[int] = None  # Internal numeric ID
     entity_type: Optional[str] = None
     content_type: Optional[str] = None
     updated_at: Optional[datetime] = None

basic_memory/schemas/memory.py

@@ -124,6 +124,7 @@ class EntitySummary(BaseModel):
     """Simplified entity representation."""
 
     type: Literal["entity"] = "entity"
+    entity_id: int  # Database ID for v2 API consistency
     permalink: Optional[str]
     title: str
     content: Optional[str] = None
@@ -141,12 +142,16 @@ class RelationSummary(BaseModel):
     """Simplified relation representation."""
 
     type: Literal["relation"] = "relation"
+    relation_id: int  # Database ID for v2 API consistency
+    entity_id: Optional[int] = None  # ID of the entity this relation belongs to
     title: str
     file_path: str
     permalink: str
     relation_type: str
     from_entity: Optional[str] = None
+    from_entity_id: Optional[int] = None  # ID of source entity
     to_entity: Optional[str] = None
+    to_entity_id: Optional[int] = None  # ID of target entity
     created_at: Annotated[
         datetime, Field(json_schema_extra={"type": "string", "format": "date-time"})
     ]
@@ -160,6 +165,8 @@ class ObservationSummary(BaseModel):
     """Simplified observation representation."""
 
     type: Literal["observation"] = "observation"
+    observation_id: int  # Database ID for v2 API consistency
+    entity_id: Optional[int] = None  # ID of the entity this observation belongs to
     title: str
     file_path: str
     permalink: str
@@ -255,7 +262,7 @@ class ProjectActivity(BaseModel):
 
     @field_serializer("last_activity")
     def serialize_last_activity(self, dt: Optional[datetime]) -> Optional[str]:
-        return dt.isoformat() if dt else None
+        return dt.isoformat() if dt else None  # pragma: no cover
 
 
 class ProjectActivitySummary(BaseModel):
@@ -275,4 +282,4 @@ class ProjectActivitySummary(BaseModel):
 
     @field_serializer("generated_at")
     def serialize_generated_at(self, dt: datetime) -> str:
-        return dt.isoformat()
+        return dt.isoformat()  # pragma: no cover

basic_memory/schemas/project_info.py

@@ -173,6 +173,8 @@ class ProjectWatchStatus(BaseModel):
 class ProjectItem(BaseModel):
     """Simple representation of a project."""
 
+    id: int
+    external_id: str  # UUID string for API references (required after migration)
     name: str
     path: str
     is_default: bool = False

basic_memory/schemas/response.py

@@ -14,7 +14,7 @@ Key Features:
 from datetime import datetime
 from typing import List, Optional, Dict
 
-from pydantic import BaseModel, ConfigDict, Field, AliasPath, AliasChoices
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from basic_memory.schemas.base import Relation, Permalink, EntityType, ContentType, Observation
 
@@ -64,32 +64,89 @@ class RelationResponse(Relation, SQLAlchemyModel):
 
     permalink: Permalink
 
-    from_id: Permalink = Field(
-        # use the permalink from the associated Entity
-        # or the from_id value
-        validation_alias=AliasChoices(
-            AliasPath("from_entity", "permalink"),
-            "from_id",
-        )
-    )
-    to_id: Optional[Permalink] = Field(  # pyright: ignore
-        # use the permalink from the associated Entity
-        # or the to_id value
-        validation_alias=AliasChoices(
-            AliasPath("to_entity", "permalink"),
-            "to_id",
-        ),
-        default=None,
-    )
-    to_name: Optional[Permalink] = Field(
-        # use the permalink from the associated Entity
-        # or the to_id value
-        validation_alias=AliasChoices(
-            AliasPath("to_entity", "title"),
-            "to_name",
-        ),
-        default=None,
-    )
+    # Override base Relation fields to allow Optional values
+    from_id: Optional[Permalink] = Field(default=None)  # pyright: ignore[reportIncompatibleVariableOverride]
+    to_id: Optional[Permalink] = Field(default=None)  # pyright: ignore[reportIncompatibleVariableOverride]
+    to_name: Optional[str] = Field(default=None)
+
+    @model_validator(mode="before")
+    @classmethod
+    def resolve_entity_references(cls, data):
+        """Resolve from_id and to_id from joined entities, falling back to file_path.
+
+        When loading from SQLAlchemy models, the from_entity and to_entity relationships
+        are joined. We extract the permalink from these entities, falling back to
+        file_path when permalink is None.
+
+        We use file_path directly (not converted to permalink format) because if the
+        entity doesn't have a permalink, the system won't be able to find it by a
+        generated one anyway. Using the actual file_path preserves the real identifier.
+        """
+        # Handle dict input (e.g., from API or tests)
+        if isinstance(data, dict):
+            from_entity = data.get("from_entity")
+            to_entity = data.get("to_entity")
+
+            # Resolve from_id: prefer permalink, fall back to file_path
+            if from_entity and isinstance(from_entity, dict):
+                permalink = from_entity.get("permalink")
+                if permalink:
+                    data["from_id"] = permalink
+                elif from_entity.get("file_path"):
+                    data["from_id"] = from_entity["file_path"]
+
+            # Resolve to_id: prefer permalink, fall back to file_path
+            if to_entity and isinstance(to_entity, dict):
+                permalink = to_entity.get("permalink")
+                if permalink:
+                    data["to_id"] = permalink
+                elif to_entity.get("file_path"):
+                    data["to_id"] = to_entity["file_path"]
+
+                # Also resolve to_name from entity title
+                if to_entity.get("title") and not data.get("to_name"):
+                    data["to_name"] = to_entity["title"]
+
+            return data
+
+        # Handle SQLAlchemy model input (from_attributes=True)
+        # Access attributes directly from the ORM model
+        from_entity = getattr(data, "from_entity", None)
+        to_entity = getattr(data, "to_entity", None)
+
+        # Build a dict from the model's attributes
+        result = {}
+
+        # Copy base fields
+        for field in ["permalink", "relation_type", "context", "to_name"]:
+            if hasattr(data, field):
+                result[field] = getattr(data, field)
+
+        # Resolve from_id: prefer permalink, fall back to file_path
+        if from_entity:
+            permalink = getattr(from_entity, "permalink", None)
+            file_path = getattr(from_entity, "file_path", None)
+            if permalink:
+                result["from_id"] = permalink
+            elif file_path:
+                result["from_id"] = file_path
+
+        # Resolve to_id: prefer permalink, fall back to file_path
+        if to_entity:
+            permalink = getattr(to_entity, "permalink", None)
+            file_path = getattr(to_entity, "file_path", None)
+            if permalink:
+                result["to_id"] = permalink
+            elif file_path:
+                result["to_id"] = file_path
+
+            # Also resolve to_name from entity title if not set
+            if not result.get("to_name"):
+                title = getattr(to_entity, "title", None)
+                if title:
+                    result["to_name"] = title
+
+        return result
 
 
 class EntityResponse(SQLAlchemyModel):

basic_memory/schemas/search.py

@@ -97,6 +97,11 @@ class SearchResult(BaseModel):
 
     metadata: Optional[dict] = None
 
+    # IDs for v2 API consistency
+    entity_id: Optional[int] = None  # Entity ID (always present for entities)
+    observation_id: Optional[int] = None  # Observation ID (for observation results)
+    relation_id: Optional[int] = None  # Relation ID (for relation results)
+
     # Type-specific fields
     category: Optional[str] = None  # For observations
     from_entity: Optional[Permalink] = None  # For relations

basic_memory/schemas/sync_report.py

@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING, Dict, List, Set
 from pydantic import BaseModel, Field
 
 # avoid cirular imports
-if TYPE_CHECKING:
+if TYPE_CHECKING:  # pragma: no cover
     from basic_memory.sync.sync_service import SyncReport
 
 

basic_memory/schemas/v2/__init__.py

@@ -0,0 +1,27 @@
+"""V2 API schemas - ID-based entity and project references."""
+
+from basic_memory.schemas.v2.entity import (
+    EntityResolveRequest,
+    EntityResolveResponse,
+    EntityResponseV2,
+    MoveEntityRequestV2,
+    ProjectResolveRequest,
+    ProjectResolveResponse,
+)
+from basic_memory.schemas.v2.resource import (
+    CreateResourceRequest,
+    UpdateResourceRequest,
+    ResourceResponse,
+)
+
+__all__ = [
+    "EntityResolveRequest",
+    "EntityResolveResponse",
+    "EntityResponseV2",
+    "MoveEntityRequestV2",
+    "ProjectResolveRequest",
+    "ProjectResolveResponse",
+    "CreateResourceRequest",
+    "UpdateResourceRequest",
+    "ResourceResponse",
+]

basic_memory/schemas/v2/entity.py

@@ -0,0 +1,133 @@
+"""V2 entity and project schemas with ID-first design."""
+
+from datetime import datetime
+from typing import Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field, ConfigDict
+
+from basic_memory.schemas.response import ObservationResponse, RelationResponse
+
+
+class EntityResolveRequest(BaseModel):
+    """Request to resolve a string identifier to an entity ID.
+
+    Supports resolution of:
+    - Permalinks (e.g., "specs/search")
+    - Titles (e.g., "Search Specification")
+    - File paths (e.g., "specs/search.md")
+    """
+
+    identifier: str = Field(
+        ...,
+        description="Entity identifier to resolve (permalink, title, or file path)",
+        min_length=1,
+        max_length=500,
+    )
+
+
+class EntityResolveResponse(BaseModel):
+    """Response from identifier resolution.
+
+    Returns the entity ID and associated metadata for the resolved entity.
+    """
+
+    external_id: str = Field(..., description="External UUID (primary API identifier)")
+    entity_id: int = Field(..., description="Numeric entity ID (internal identifier)")
+    permalink: Optional[str] = Field(None, description="Entity permalink")
+    file_path: str = Field(..., description="Relative file path")
+    title: str = Field(..., description="Entity title")
+    resolution_method: Literal["external_id", "permalink", "title", "path", "search"] = Field(
+        ..., description="How the identifier was resolved"
+    )
+
+
+class MoveEntityRequestV2(BaseModel):
+    """V2 request schema for moving an entity to a new file location.
+
+    In V2 API, the entity ID is provided in the URL path, so this request
+    only needs the destination path.
+    """
+
+    destination_path: str = Field(
+        ...,
+        description="New file path for the entity (relative to project root)",
+        min_length=1,
+        max_length=500,
+    )
+
+
+class EntityResponseV2(BaseModel):
+    """V2 entity response with external_id as the primary API identifier.
+
+    This response format emphasizes the external_id (UUID) as the primary API identifier,
+    with the numeric id maintained for internal reference.
+    """
+
+    # External UUID first - this is the primary API identifier in v2
+    external_id: str = Field(..., description="External UUID (primary API identifier)")
+    # Internal numeric ID
+    id: int = Field(..., description="Numeric entity ID (internal identifier)")
+
+    # Core entity fields
+    title: str = Field(..., description="Entity title")
+    entity_type: str = Field(..., description="Entity type")
+    content_type: str = Field(default="text/markdown", description="Content MIME type")
+
+    # Secondary identifiers (for compatibility and convenience)
+    permalink: Optional[str] = Field(None, description="Entity permalink (may change)")
+    file_path: str = Field(..., description="Relative file path (may change)")
+
+    # Content and metadata
+    content: Optional[str] = Field(None, description="Entity content")
+    entity_metadata: Optional[Dict] = Field(None, description="Entity metadata")
+
+    # Relationships
+    observations: List[ObservationResponse] = Field(
+        default_factory=list, description="Entity observations"
+    )
+    relations: List[RelationResponse] = Field(default_factory=list, description="Entity relations")
+
+    # Timestamps
+    created_at: datetime = Field(..., description="Creation timestamp")
+    updated_at: datetime = Field(..., description="Last update timestamp")
+
+    # V2-specific metadata
+    api_version: Literal["v2"] = Field(
+        default="v2", description="API version (always 'v2' for this response)"
+    )
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class ProjectResolveRequest(BaseModel):
+    """Request to resolve a project identifier to a project ID.
+
+    Supports resolution of:
+    - Project names (e.g., "my-project")
+    - Permalinks (e.g., "my-project")
+    """
+
+    identifier: str = Field(
+        ...,
+        description="Project identifier to resolve (name or permalink)",
+        min_length=1,
+        max_length=255,
+    )
+
+
+class ProjectResolveResponse(BaseModel):
+    """Response from project identifier resolution.
+
+    Returns the project ID and associated metadata for the resolved project.
+    """
+
+    external_id: str = Field(..., description="External UUID (primary API identifier)")
+    project_id: int = Field(..., description="Numeric project ID (internal identifier)")
+    name: str = Field(..., description="Project name")
+    permalink: str = Field(..., description="Project permalink")
+    path: str = Field(..., description="Project file path")
+    is_active: bool = Field(..., description="Whether the project is active")
+    is_default: bool = Field(..., description="Whether the project is the default")
+    resolution_method: Literal["external_id", "name", "permalink"] = Field(
+        ..., description="How the identifier was resolved"
+    )

basic_memory/schemas/v2/resource.py

@@ -0,0 +1,47 @@
+"""V2 resource schemas for file content operations."""
+
+from pydantic import BaseModel, Field
+
+
+class CreateResourceRequest(BaseModel):
+    """Request to create a new resource file.
+
+    File path is required for new resources since we need to know where
+    to create the file.
+    """
+
+    file_path: str = Field(
+        ...,
+        description="Path to create the file, relative to project root",
+        min_length=1,
+        max_length=500,
+    )
+    content: str = Field(..., description="File content to write")
+
+
+class UpdateResourceRequest(BaseModel):
+    """Request to update an existing resource by entity ID.
+
+    Only content is required - the file path is already known from the entity.
+    Optionally can update the file_path to move the file.
+    """
+
+    content: str = Field(..., description="File content to write")
+    file_path: str | None = Field(
+        None,
+        description="Optional new file path to move the resource",
+        min_length=1,
+        max_length=500,
+    )
+
+
+class ResourceResponse(BaseModel):
+    """Response from resource operations."""
+
+    entity_id: int = Field(..., description="Internal entity ID of the resource")
+    external_id: str = Field(..., description="External UUID of the resource for API references")
+    file_path: str = Field(..., description="File path of the resource")
+    checksum: str = Field(..., description="File content checksum")
+    size: int = Field(..., description="File size in bytes")
+    created_at: float = Field(..., description="Creation timestamp")
+    modified_at: float = Field(..., description="Modification timestamp")