basic-memory 0.17.1__py3-none-any.whl

basic_memory/schemas/response.py

@@ -0,0 +1,229 @@
+"""Response schemas for knowledge graph operations.
+
+This module defines the response formats for all knowledge graph operations.
+Each response includes complete information about the affected entities,
+including IDs that can be used in subsequent operations.
+
+Key Features:
+1. Every created/updated object gets an ID
+2. Relations are included with their parent entities
+3. Responses include everything needed for next operations
+4. Bulk operations return all affected items
+"""
+
+from datetime import datetime
+from typing import List, Optional, Dict
+
+from pydantic import BaseModel, ConfigDict, Field, AliasPath, AliasChoices
+
+from basic_memory.schemas.base import Relation, Permalink, EntityType, ContentType, Observation
+
+
+class SQLAlchemyModel(BaseModel):
+    """Base class for models that read from SQLAlchemy attributes.
+
+    This base class handles conversion of SQLAlchemy model attributes
+    to Pydantic model fields. All response models extend this to ensure
+    proper handling of database results.
+    """
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class ObservationResponse(Observation, SQLAlchemyModel):
+    """Schema for observation data returned from the service.
+
+    Each observation gets a unique ID that can be used for later
+    reference or deletion.
+
+    Example Response:
+    {
+        "category": "feature",
+        "content": "Added support for async operations",
+        "context": "Initial database design meeting"
+    }
+    """
+
+    permalink: Permalink
+
+
+class RelationResponse(Relation, SQLAlchemyModel):
+    """Response schema for relation operations.
+
+    Extends the base Relation model with a unique ID that can be
+    used for later modification or deletion.
+
+    Example Response:
+    {
+        "from_id": "test/memory_test",
+        "to_id": "component/memory-service",
+        "relation_type": "validates",
+        "context": "Comprehensive test suite"
+    }
+    """
+
+    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,
+    )
+
+
+class EntityResponse(SQLAlchemyModel):
+    """Complete entity data returned from the service.
+
+    This is the most comprehensive entity view, including:
+    1. Basic entity details (id, name, type)
+    2. All observations with their IDs
+    3. All relations with their IDs
+    4. Optional description
+
+    Example Response:
+    {
+        "permalink": "component/memory-service",
+        "file_path": "MemoryService",
+        "entity_type": "component",
+        "entity_metadata": {}
+        "content_type: "text/markdown"
+        "observations": [
+            {
+                "category": "feature",
+                "content": "Uses SQLite storage"
+                "context": "Initial design"
+            },
+            {
+                "category": "feature",
+                "content": "Implements async operations"
+                "context": "Initial design"
+            }
+        ],
+        "relations": [
+            {
+                "from_id": "test/memory-test",
+                "to_id": "component/memory-service",
+                "relation_type": "validates",
+                "context": "Main test suite"
+            }
+        ]
+    }
+    """
+
+    permalink: Optional[Permalink]
+    title: str
+    file_path: str
+    entity_type: EntityType
+    entity_metadata: Optional[Dict] = None
+    checksum: Optional[str] = None
+    content_type: ContentType
+    observations: List[ObservationResponse] = []
+    relations: List[RelationResponse] = []
+    created_at: datetime
+    updated_at: datetime
+
+
+class EntityListResponse(SQLAlchemyModel):
+    """Response for create_entities operation.
+
+    Returns complete information about entities returned from the service,
+    including their permalinks, observations,
+    and any established relations.
+
+    Example Response:
+    {
+        "entities": [
+            {
+                "permalink": "component/search_service",
+                "title": "SearchService",
+                "entity_type": "component",
+                "description": "Knowledge graph search",
+                "observations": [
+                    {
+                        "content": "Implements full-text search"
+                    }
+                ],
+                "relations": []
+            },
+            {
+                "permalink": "document/api_docs",
+                "title": "API_Documentation",
+                "entity_type": "document",
+                "description": "API Reference",
+                "observations": [
+                    {
+                        "content": "Documents REST endpoints"
+                    }
+                ],
+                "relations": []
+            }
+        ]
+    }
+    """
+
+    entities: List[EntityResponse]
+
+
+class SearchNodesResponse(SQLAlchemyModel):
+    """Response for search operation.
+
+    Returns matching entities with their complete information,
+    plus the original query for reference.
+
+    Example Response:
+    {
+        "matches": [
+            {
+                "permalink": "component/memory-service",
+                "title": "MemoryService",
+                "entity_type": "component",
+                "description": "Core service",
+                "observations": [...],
+                "relations": [...]
+            }
+        ],
+        "query": "memory"
+    }
+
+    Note: Each entity in matches includes full details
+    just like EntityResponse.
+    """
+
+    matches: List[EntityResponse]
+    query: str
+
+
+class DeleteEntitiesResponse(SQLAlchemyModel):
+    """Response indicating successful entity deletion.
+
+    A simple boolean response confirming the delete operation
+    completed successfully.
+
+    Example Response:
+    {
+        "deleted": true
+    }
+    """
+
+    deleted: bool

basic_memory/schemas/search.py

@@ -0,0 +1,117 @@
+"""Search schemas for Basic Memory.
+
+The search system supports three primary modes:
+1. Exact permalink lookup
+2. Pattern matching with *
+3. Full-text search across content
+"""
+
+from typing import Optional, List, Union
+from datetime import datetime
+from enum import Enum
+from pydantic import BaseModel, field_validator
+
+from basic_memory.schemas.base import Permalink
+
+
+class SearchItemType(str, Enum):
+    """Types of searchable items."""
+
+    ENTITY = "entity"
+    OBSERVATION = "observation"
+    RELATION = "relation"
+
+
+class SearchQuery(BaseModel):
+    """Search query parameters.
+
+    Use ONE of these primary search modes:
+    - permalink: Exact permalink match
+    - permalink_match: Path pattern with *
+    - text: Full-text search of title/content (supports boolean operators: AND, OR, NOT)
+
+    Optionally filter results by:
+    - types: Limit to specific item types
+    - entity_types: Limit to specific entity types
+    - after_date: Only items after date
+
+    Boolean search examples:
+    - "python AND flask" - Find items with both terms
+    - "python OR django" - Find items with either term
+    - "python NOT django" - Find items with python but not django
+    - "(python OR flask) AND web" - Use parentheses for grouping
+    """
+
+    # Primary search modes (use ONE of these)
+    permalink: Optional[str] = None  # Exact permalink match
+    permalink_match: Optional[str] = None  # Glob permalink match
+    text: Optional[str] = None  # Full-text search (now supports boolean operators)
+    title: Optional[str] = None  # title only search
+
+    # Optional filters
+    types: Optional[List[str]] = None  # Filter by type
+    entity_types: Optional[List[SearchItemType]] = None  # Filter by entity type
+    after_date: Optional[Union[datetime, str]] = None  # Time-based filter
+
+    @field_validator("after_date")
+    @classmethod
+    def validate_date(cls, v: Optional[Union[datetime, str]]) -> Optional[str]:
+        """Convert datetime to ISO format if needed."""
+        if isinstance(v, datetime):
+            return v.isoformat()
+        return v
+
+    def no_criteria(self) -> bool:
+        return (
+            self.permalink is None
+            and self.permalink_match is None
+            and self.title is None
+            and self.text is None
+            and self.after_date is None
+            and self.types is None
+            and self.entity_types is None
+        )
+
+    def has_boolean_operators(self) -> bool:
+        """Check if the text query contains boolean operators (AND, OR, NOT)."""
+        if not self.text:  # pragma: no cover
+            return False
+
+        # Check for common boolean operators with correct word boundaries
+        # to avoid matching substrings like "GRAND" containing "AND"
+        boolean_patterns = [" AND ", " OR ", " NOT ", "(", ")"]
+        text = f" {self.text} "  # Add spaces to ensure we match word boundaries
+        return any(pattern in text for pattern in boolean_patterns)
+
+
+class SearchResult(BaseModel):
+    """Search result with score and metadata."""
+
+    title: str
+    type: SearchItemType
+    score: float
+    entity: Optional[Permalink] = None
+    permalink: Optional[str]
+    content: Optional[str] = None
+    file_path: str
+
+    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
+    to_entity: Optional[Permalink] = None  # For relations
+    relation_type: Optional[str] = None  # For relations
+
+
+class SearchResponse(BaseModel):
+    """Wrapper for search results."""
+
+    results: List[SearchResult]
+    current_page: int
+    page_size: int

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:
+    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,129 @@
+"""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.
+    """
+
+    entity_id: int = Field(..., description="Numeric entity ID (primary 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["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 ID as the primary field.
+
+    This response format emphasizes the entity ID as the primary identifier,
+    with all other fields (permalink, file_path) as secondary metadata.
+    """
+
+    # ID first - this is the primary identifier in v2
+    id: int = Field(..., description="Numeric entity ID (primary 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.
+    """
+
+    project_id: int = Field(..., description="Numeric project ID (primary 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["id", "name", "permalink"] = Field(
+        ..., description="How the identifier was resolved"
+    )

basic_memory/schemas/v2/resource.py

@@ -0,0 +1,46 @@
+"""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="Entity ID of the resource")
+    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

@@ -0,0 +1,8 @@
+"""Services package."""
+
+from .service import BaseService
+from .file_service import FileService
+from .entity_service import EntityService
+from .project_service import ProjectService
+
+__all__ = ["BaseService", "FileService", "EntityService", "ProjectService"]