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

basic_memory/schemas/base.py

@@ -11,20 +11,48 @@ Key Concepts:
 4. Everything is stored in both SQLite and markdown files
 """
 
+import os
 import mimetypes
 import re
-from datetime import datetime
+from datetime import datetime, timedelta
 from pathlib import Path
 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.
 
@@ -46,20 +74,71 @@ def to_snake_case(name: str) -> str:
     return s2.lower()
 
 
+def parse_timeframe(timeframe: str) -> datetime:
+    """Parse timeframe with special handling for 'today' and other natural language expressions.
+
+    Enforces a minimum 1-day lookback to handle timezone differences in distributed deployments.
+
+    Args:
+        timeframe: Natural language timeframe like 'today', '1d', '1 week ago', etc.
+
+    Returns:
+        datetime: The parsed datetime for the start of the timeframe, timezone-aware in local system timezone
+                 Always returns at least 1 day ago to handle timezone differences.
+
+    Examples:
+        parse_timeframe('today') -> 2025-06-04 14:50:00-07:00 (1 day ago, not start of today)
+        parse_timeframe('1h') -> 2025-06-04 14:50:00-07:00 (1 day ago, not 1 hour ago)
+        parse_timeframe('1d') -> 2025-06-04 14:50:00-07:00 (24 hours ago with local timezone)
+        parse_timeframe('1 week ago') -> 2025-05-29 14:50:00-07:00 (1 week ago with local timezone)
+    """
+    if timeframe.lower() == "today":
+        # For "today", return 1 day ago to ensure we capture recent activity across timezones
+        # This handles the case where client and server are in different timezones
+        now = datetime.now()
+        one_day_ago = now - timedelta(days=1)
+        return one_day_ago.astimezone()
+    else:
+        # Use dateparser for other formats
+        parsed = parse(timeframe)
+        if not parsed:
+            raise ValueError(f"Could not parse timeframe: {timeframe}")
+
+        # If the parsed datetime is naive, make it timezone-aware in local system timezone
+        if parsed.tzinfo is None:
+            parsed = parsed.astimezone()
+        else:
+            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
+        now = datetime.now().astimezone()
+        one_day_ago = now - timedelta(days=1)
+
+        # If the parsed time is more recent than 1 day ago, use 1 day ago instead
+        if parsed > one_day_ago:
+            return one_day_ago
+        else:
+            return parsed
+
+
 def validate_timeframe(timeframe: str) -> str:
     """Convert human readable timeframes to a duration relative to the current time."""
     if not isinstance(timeframe, str):
         raise ValueError("Timeframe must be a string")
 
-    # Parse relative time expression
-    parsed = parse(timeframe)
-    if not parsed:
-        raise ValueError(f"Could not parse timeframe: {timeframe}")
+    # Preserve special timeframe strings that need custom handling
+    special_timeframes = ["today"]
+    if timeframe.lower() in special_timeframes:
+        return timeframe.lower()
+
+    # Parse relative time expression using our enhanced parser
+    parsed = parse_timeframe(timeframe)
 
     # Convert to duration
-    now = datetime.now()
+    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
@@ -104,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
 ]
 
 
@@ -143,6 +222,7 @@ class Entity(BaseModel):
     """
 
     # private field to override permalink
+    # Use empty string "" as sentinel to indicate permalinks are explicitly disabled
     _permalink: Optional[str] = None
 
     title: str
@@ -156,14 +236,53 @@ class Entity(BaseModel):
         default="text/markdown",
     )
 
+    def __init__(self, **data):
+        data["folder"] = sanitize_for_folder(data.get("folder", ""))
+        super().__init__(**data)
+
+    @property
+    def safe_title(self) -> str:
+        """
+        A sanitized version of the title, which is safe for use on the filesystem. For example,
+        a title of "Coupon Enable/Disable Feature" should create a the file as "Coupon Enable-Disable Feature.md"
+        instead of creating a file named "Disable Feature.md" beneath the "Coupon Enable" directory.
+
+        Replaces POSIX and/or Windows style slashes as well as a few other characters that are not safe for filenames.
+        If kebab_filenames is True, then behavior is consistent with transformation used when generating permalink
+        strings (e.g. "Coupon Enable/Disable Feature" -> "coupon-enable-disable-feature").
+        """
+        fixed_title = sanitize_for_filename(self.title)
+
+        app_config = ConfigManager().config
+        use_kebab_case = app_config.kebab_filenames
+
+        if use_kebab_case:
+            # 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."""
-        return f"{self.folder}/{self.title}.md" if self.folder else f"{self.title}.md"
+        safe_title = self.safe_title
+        if self.content_type == "text/markdown":
+            return (
+                os.path.join(self.folder, f"{safe_title}.md") if self.folder else f"{safe_title}.md"
+            )
+        else:
+            return os.path.join(self.folder, safe_title) if self.folder else safe_title
 
     @property
-    def permalink(self) -> Permalink:
+    def permalink(self) -> Optional[Permalink]:
         """Get a url friendly path}."""
+        # Empty string is a sentinel value indicating permalinks are disabled
+        if self._permalink == "":
+            return None
         return self._permalink or generate_permalink(self.file_path)
 
     @model_validator(mode="after")

basic_memory/schemas/cloud.py

@@ -0,0 +1,50 @@
+"""Schemas for cloud-related API responses."""
+
+from pydantic import BaseModel, Field
+
+
+class TenantMountInfo(BaseModel):
+    """Response from /tenant/mount/info endpoint."""
+
+    tenant_id: str = Field(..., description="Unique identifier for the tenant")
+    bucket_name: str = Field(..., description="S3 bucket name for the tenant")
+
+
+class MountCredentials(BaseModel):
+    """Response from /tenant/mount/credentials endpoint."""
+
+    access_key: str = Field(..., description="S3 access key for mount")
+    secret_key: str = Field(..., description="S3 secret key for mount")
+
+
+class CloudProject(BaseModel):
+    """Representation of a cloud project."""
+
+    name: str = Field(..., description="Project name")
+    path: str = Field(..., description="Project path on cloud")
+
+
+class CloudProjectList(BaseModel):
+    """Response from /proxy/projects/projects endpoint."""
+
+    projects: list[CloudProject] = Field(default_factory=list, description="List of cloud projects")
+
+
+class CloudProjectCreateRequest(BaseModel):
+    """Request to create a new cloud project."""
+
+    name: str = Field(..., description="Project name")
+    path: str = Field(..., description="Project path (permalink)")
+    set_default: bool = Field(default=False, description="Set as default project")
+
+
+class CloudProjectCreateResponse(BaseModel):
+    """Response from creating a cloud project."""
+
+    message: str = Field(..., description="Status message about the project creation")
+    status: str = Field(..., description="Status of the creation (success or error)")
+    default: bool = Field(..., description="True if the project was set as the default")
+    old_project: dict | None = Field(None, description="Information about the previous project")
+    new_project: dict | None = Field(
+        None, description="Information about the newly created project"
+    )

basic_memory/schemas/directory.py

@@ -0,0 +1,31 @@
+"""Schemas for directory tree operations."""
+
+from datetime import datetime
+from typing import List, Optional, Literal
+
+from pydantic import BaseModel
+
+
+class DirectoryNode(BaseModel):
+    """Directory node in file system."""
+
+    name: str
+    file_path: Optional[str] = None  # Original path without leading slash (matches DB)
+    directory_path: str  # Path with leading slash for directory navigation
+    type: Literal["directory", "file"]
+    children: List["DirectoryNode"] = []  # Default to empty list
+    title: Optional[str] = None
+    permalink: Optional[str] = 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
+
+    @property
+    def has_children(self) -> bool:
+        return bool(self.children)
+
+
+# Support for recursive model
+DirectoryNode.model_rebuild()

basic_memory/schemas/importer.py

@@ -0,0 +1,35 @@
+"""Schemas for import services."""
+
+from typing import Dict, Optional
+
+from pydantic import BaseModel
+
+
+class ImportResult(BaseModel):
+    """Common import result schema."""
+
+    import_count: Dict[str, int]
+    success: bool
+    error_message: Optional[str] = None
+
+
+class ChatImportResult(ImportResult):
+    """Result schema for chat imports."""
+
+    conversations: int = 0
+    messages: int = 0
+
+
+class ProjectImportResult(ImportResult):
+    """Result schema for project imports."""
+
+    documents: int = 0
+    prompts: int = 0
+
+
+class EntityImportResult(ImportResult):
+    """Result schema for entity imports."""
+
+    entities: int = 0
+    relations: int = 0
+    skipped_entities: int = 0

basic_memory/schemas/memory.py

@@ -1,16 +1,53 @@
 """Schemas for memory context."""
 
 from datetime import datetime
-from typing import List, Optional, Annotated, Sequence
+from typing import List, Optional, Annotated, Sequence, Literal, Union, Dict
 
 from annotated_types import MinLen, MaxLen
-from pydantic import BaseModel, Field, BeforeValidator, TypeAdapter
+from pydantic import BaseModel, Field, BeforeValidator, TypeAdapter, field_serializer
 
 from basic_memory.schemas.search import SearchItemType
 
 
-def normalize_memory_url(url: str) -> str:
-    """Normalize a MemoryUrl string.
+def validate_memory_url_path(path: str) -> bool:
+    """Validate that a memory URL path is well-formed.
+
+    Args:
+        path: The path part of a memory URL (without memory:// prefix)
+
+    Returns:
+        True if the path is valid, False otherwise
+
+    Examples:
+        >>> validate_memory_url_path("specs/search")
+        True
+        >>> validate_memory_url_path("memory//test")  # Double slash
+        False
+        >>> validate_memory_url_path("invalid://test")  # Contains protocol
+        False
+    """
+    # Empty paths are not valid
+    if not path or not path.strip():
+        return False
+
+    # Check for invalid protocol schemes within the path first (more specific)
+    if "://" in path:
+        return False
+
+    # Check for double slashes (except at the beginning for absolute paths)
+    if "//" in path:
+        return False
+
+    # Check for invalid characters (excluding * which is used for pattern matching)
+    invalid_chars = {"<", ">", '"', "|", "?"}
+    if any(char in path for char in invalid_chars):
+        return False
+
+    return True
+
+
+def normalize_memory_url(url: str | None) -> str:
+    """Normalize a MemoryUrl string with validation.
 
     Args:
         url: A path like "specs/search" or "memory://specs/search"
@@ -18,19 +55,47 @@ def normalize_memory_url(url: str) -> str:
     Returns:
         Normalized URL starting with memory://
 
+    Raises:
+        ValueError: If the URL path is malformed
+
     Examples:
         >>> normalize_memory_url("specs/search")
         'memory://specs/search'
         >>> normalize_memory_url("memory://specs/search")
         'memory://specs/search'
+        >>> normalize_memory_url("memory//test")
+        Traceback (most recent call last):
+        ...
+        ValueError: Invalid memory URL path: 'memory//test' contains double slashes
     """
+    if not url:
+        raise ValueError("Memory URL cannot be empty")
+
+    # Strip whitespace for consistency
+    url = url.strip()
+
+    if not url:
+        raise ValueError("Memory URL cannot be empty or whitespace")
+
     clean_path = url.removeprefix("memory://")
+
+    # Validate the extracted path
+    if not validate_memory_url_path(clean_path):
+        # Provide specific error messages for common issues
+        if "://" in clean_path:
+            raise ValueError(f"Invalid memory URL path: '{clean_path}' contains protocol scheme")
+        elif "//" in clean_path:
+            raise ValueError(f"Invalid memory URL path: '{clean_path}' contains double slashes")
+        else:
+            raise ValueError(f"Invalid memory URL path: '{clean_path}' contains invalid characters")
+
     return f"memory://{clean_path}"
 
 
 MemoryUrl = Annotated[
     str,
     BeforeValidator(str.strip),  # Clean whitespace
+    BeforeValidator(normalize_memory_url),  # Validate and normalize the URL
     MinLen(1),
     MaxLen(2028),
 ]
@@ -58,30 +123,62 @@ def memory_url_path(url: memory_url) -> str:  # pyright: ignore
 class EntitySummary(BaseModel):
     """Simplified entity representation."""
 
-    type: str = "entity"
-    permalink: str
+    type: Literal["entity"] = "entity"
+    entity_id: int  # Database ID for v2 API consistency
+    permalink: Optional[str]
     title: str
+    content: Optional[str] = None
     file_path: str
-    created_at: datetime
+    created_at: Annotated[
+        datetime, Field(json_schema_extra={"type": "string", "format": "date-time"})
+    ]
+
+    @field_serializer("created_at")
+    def serialize_created_at(self, dt: datetime) -> str:
+        return dt.isoformat()
 
 
 class RelationSummary(BaseModel):
     """Simplified relation representation."""
 
-    type: str = "relation"
+    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_id: str
-    to_id: Optional[str] = None
+    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"})
+    ]
+
+    @field_serializer("created_at")
+    def serialize_created_at(self, dt: datetime) -> str:
+        return dt.isoformat()
 
 
 class ObservationSummary(BaseModel):
     """Simplified observation representation."""
 
-    type: str = "observation"
+    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
     category: str
     content: str
+    created_at: Annotated[
+        datetime, Field(json_schema_extra={"type": "string", "format": "date-time"})
+    ]
+
+    @field_serializer("created_at")
+    def serialize_created_at(self, dt: datetime) -> str:
+        return dt.isoformat()
 
 
 class MemoryMetadata(BaseModel):
@@ -90,27 +187,99 @@ class MemoryMetadata(BaseModel):
     uri: Optional[str] = None
     types: Optional[List[SearchItemType]] = None
     depth: int
-    timeframe: str
-    generated_at: datetime
-    total_results: int
-    total_relations: int
+    timeframe: Optional[str] = None
+    generated_at: Annotated[
+        datetime, Field(json_schema_extra={"type": "string", "format": "date-time"})
+    ]
+    primary_count: Optional[int] = None  # Changed field name
+    related_count: Optional[int] = None  # Changed field name
+    total_results: Optional[int] = None  # For backward compatibility
+    total_relations: Optional[int] = None
+    total_observations: Optional[int] = None
+
+    @field_serializer("generated_at")
+    def serialize_generated_at(self, dt: datetime) -> str:
+        return dt.isoformat()
+
+
+class ContextResult(BaseModel):
+    """Context result containing a primary item with its observations and related items."""
+
+    primary_result: Annotated[
+        Union[EntitySummary, RelationSummary, ObservationSummary],
+        Field(discriminator="type", description="Primary item"),
+    ]
+
+    observations: Sequence[ObservationSummary] = Field(
+        description="Observations belonging to this entity", default_factory=list
+    )
+
+    related_results: Sequence[
+        Annotated[
+            Union[EntitySummary, RelationSummary, ObservationSummary], Field(discriminator="type")
+        ]
+    ] = Field(description="Related items", default_factory=list)
 
 
 class GraphContext(BaseModel):
     """Complete context response."""
 
-    # Direct matches
-    primary_results: Sequence[EntitySummary | RelationSummary | ObservationSummary] = Field(
-        description="results directly matching URI"
-    )
-
-    # Related entities
-    related_results: Sequence[EntitySummary | RelationSummary | ObservationSummary] = Field(
-        description="related results"
+    # hierarchical results
+    results: Sequence[ContextResult] = Field(
+        description="Hierarchical results with related items nested", default_factory=list
     )
 
     # Context metadata
     metadata: MemoryMetadata
 
-    page: int = 1
-    page_size: int = 1
+    page: Optional[int] = None
+    page_size: Optional[int] = None
+
+
+class ActivityStats(BaseModel):
+    """Statistics about activity across all projects."""
+
+    total_projects: int
+    active_projects: int = Field(description="Projects with activity in timeframe")
+    most_active_project: Optional[str] = None
+    total_items: int = Field(description="Total items across all projects")
+    total_entities: int = 0
+    total_relations: int = 0
+    total_observations: int = 0
+
+
+class ProjectActivity(BaseModel):
+    """Activity summary for a single project."""
+
+    project_name: str
+    project_path: str
+    activity: GraphContext = Field(description="The actual activity data for this project")
+    item_count: int = Field(description="Total items in this project's activity")
+    last_activity: Optional[
+        Annotated[datetime, Field(json_schema_extra={"type": "string", "format": "date-time"})]
+    ] = Field(default=None, description="Most recent activity timestamp")
+    active_folders: List[str] = Field(default_factory=list, description="Most active folders")
+
+    @field_serializer("last_activity")
+    def serialize_last_activity(self, dt: Optional[datetime]) -> Optional[str]:
+        return dt.isoformat() if dt else None  # pragma: no cover
+
+
+class ProjectActivitySummary(BaseModel):
+    """Summary of activity across all projects."""
+
+    projects: Dict[str, ProjectActivity] = Field(
+        description="Activity per project, keyed by project name"
+    )
+    summary: ActivityStats
+    timeframe: str = Field(description="The timeframe used for the query")
+    generated_at: Annotated[
+        datetime, Field(json_schema_extra={"type": "string", "format": "date-time"})
+    ]
+    guidance: Optional[str] = Field(
+        default=None, description="Assistant guidance for project selection and session management"
+    )
+
+    @field_serializer("generated_at")
+    def serialize_generated_at(self, dt: datetime) -> str:
+        return dt.isoformat()  # pragma: no cover