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

basic_memory/schemas/sync_report.py

@@ -0,0 +1,72 @@
+"""Pydantic schemas for sync report responses."""
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Dict, List, Set
+
+from pydantic import BaseModel, Field
+
+# avoid cirular imports
+if TYPE_CHECKING:  # pragma: no cover
+    from basic_memory.sync.sync_service import SyncReport
+
+
+class SkippedFileResponse(BaseModel):
+    """Information about a file that was skipped due to repeated failures."""
+
+    path: str = Field(description="File path relative to project root")
+    reason: str = Field(description="Error message from last failure")
+    failure_count: int = Field(description="Number of consecutive failures")
+    first_failed: datetime = Field(description="Timestamp of first failure")
+
+    model_config = {"from_attributes": True}
+
+
+class SyncReportResponse(BaseModel):
+    """Report of file changes found compared to database state.
+
+    Used for API responses when scanning or syncing files.
+    """
+
+    new: Set[str] = Field(default_factory=set, description="Files on disk but not in database")
+    modified: Set[str] = Field(default_factory=set, description="Files with different checksums")
+    deleted: Set[str] = Field(default_factory=set, description="Files in database but not on disk")
+    moves: Dict[str, str] = Field(
+        default_factory=dict, description="Files moved (old_path -> new_path)"
+    )
+    checksums: Dict[str, str] = Field(
+        default_factory=dict, description="Current file checksums (path -> checksum)"
+    )
+    skipped_files: List[SkippedFileResponse] = Field(
+        default_factory=list, description="Files skipped due to repeated failures"
+    )
+    total: int = Field(description="Total number of changes")
+
+    @classmethod
+    def from_sync_report(cls, report: "SyncReport") -> "SyncReportResponse":
+        """Convert SyncReport dataclass to Pydantic model.
+
+        Args:
+            report: SyncReport dataclass from sync service
+
+        Returns:
+            SyncReportResponse with same data
+        """
+        return cls(
+            new=report.new,
+            modified=report.modified,
+            deleted=report.deleted,
+            moves=report.moves,
+            checksums=report.checksums,
+            skipped_files=[
+                SkippedFileResponse(
+                    path=skipped.path,
+                    reason=skipped.reason,
+                    failure_count=skipped.failure_count,
+                    first_failed=skipped.first_failed,
+                )
+                for skipped in report.skipped_files
+            ],
+            total=report.total,
+        )
+
+    model_config = {"from_attributes": True}

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")

basic_memory/services/__init__.py

@@ -3,5 +3,6 @@
 from .service import BaseService
 from .file_service import FileService
 from .entity_service import EntityService
+from .project_service import ProjectService
 
-__all__ = ["BaseService", "FileService", "EntityService"]
+__all__ = ["BaseService", "FileService", "EntityService", "ProjectService"]