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

basic_memory/schemas/project_info.py

@@ -0,0 +1,211 @@
+"""Schema for project info response."""
+
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+
+from pydantic import Field, BaseModel
+
+from basic_memory.utils import generate_permalink
+
+
+class ProjectStatistics(BaseModel):
+    """Statistics about the current project."""
+
+    # Basic counts
+    total_entities: int = Field(description="Total number of entities in the knowledge base")
+    total_observations: int = Field(description="Total number of observations across all entities")
+    total_relations: int = Field(description="Total number of relations between entities")
+    total_unresolved_relations: int = Field(
+        description="Number of relations with unresolved targets"
+    )
+
+    # Entity counts by type
+    entity_types: Dict[str, int] = Field(
+        description="Count of entities by type (e.g., note, conversation)"
+    )
+
+    # Observation counts by category
+    observation_categories: Dict[str, int] = Field(
+        description="Count of observations by category (e.g., tech, decision)"
+    )
+
+    # Relation counts by type
+    relation_types: Dict[str, int] = Field(
+        description="Count of relations by type (e.g., implements, relates_to)"
+    )
+
+    # Graph metrics
+    most_connected_entities: List[Dict[str, Any]] = Field(
+        description="Entities with the most relations, including their titles and permalinks"
+    )
+    isolated_entities: int = Field(description="Number of entities with no relations")
+
+
+class ActivityMetrics(BaseModel):
+    """Activity metrics for the current project."""
+
+    # Recent activity
+    recently_created: List[Dict[str, Any]] = Field(
+        description="Recently created entities with timestamps"
+    )
+    recently_updated: List[Dict[str, Any]] = Field(
+        description="Recently updated entities with timestamps"
+    )
+
+    # Growth over time (last 6 months)
+    monthly_growth: Dict[str, Dict[str, int]] = Field(
+        description="Monthly growth statistics for entities, observations, and relations"
+    )
+
+
+class SystemStatus(BaseModel):
+    """System status information."""
+
+    # Version information
+    version: str = Field(description="Basic Memory version")
+
+    # Database status
+    database_path: str = Field(description="Path to the SQLite database")
+    database_size: str = Field(description="Size of the database in human-readable format")
+
+    # Watch service status
+    watch_status: Optional[Dict[str, Any]] = Field(
+        default=None, description="Watch service status information (if running)"
+    )
+
+    # System information
+    timestamp: datetime = Field(description="Timestamp when the information was collected")
+
+
+class ProjectInfoResponse(BaseModel):
+    """Response for the project_info tool."""
+
+    # Project configuration
+    project_name: str = Field(description="Name of the current project")
+    project_path: str = Field(description="Path to the current project files")
+    available_projects: Dict[str, Dict[str, Any]] = Field(
+        description="Map of configured project names to detailed project information"
+    )
+    default_project: str = Field(description="Name of the default project")
+
+    # Statistics
+    statistics: ProjectStatistics = Field(description="Statistics about the knowledge base")
+
+    # Activity metrics
+    activity: ActivityMetrics = Field(description="Activity and growth metrics")
+
+    # System status
+    system: SystemStatus = Field(description="System and service status information")
+
+
+class ProjectInfoRequest(BaseModel):
+    """Request model for switching projects."""
+
+    name: str = Field(..., description="Name of the project to switch to")
+    path: str = Field(..., description="Path to the project directory")
+    set_default: bool = Field(..., description="Set the project as the default")
+
+
+class WatchEvent(BaseModel):
+    timestamp: datetime
+    path: str
+    action: str  # new, delete, etc
+    status: str  # success, error
+    checksum: Optional[str]
+    error: Optional[str] = None
+
+
+class WatchServiceState(BaseModel):
+    # Service status
+    running: bool = False
+    start_time: datetime = datetime.now()  # Use directly with Pydantic model
+    pid: int = os.getpid()  # Use directly with Pydantic model
+
+    # Stats
+    error_count: int = 0
+    last_error: Optional[datetime] = None
+    last_scan: Optional[datetime] = None
+
+    # File counts
+    synced_files: int = 0
+
+    # Recent activity
+    recent_events: List[WatchEvent] = []  # Use directly with Pydantic model
+
+    def add_event(
+        self,
+        path: str,
+        action: str,
+        status: str,
+        checksum: Optional[str] = None,
+        error: Optional[str] = None,
+    ) -> WatchEvent:  # pragma: no cover
+        event = WatchEvent(
+            timestamp=datetime.now(),
+            path=path,
+            action=action,
+            status=status,
+            checksum=checksum,
+            error=error,
+        )
+        self.recent_events.insert(0, event)
+        self.recent_events = self.recent_events[:100]  # Keep last 100
+        return event
+
+    def record_error(self, error: str):  # pragma: no cover
+        self.error_count += 1
+        self.add_event(path="", action="sync", status="error", error=error)
+        self.last_error = datetime.now()
+
+
+class ProjectWatchStatus(BaseModel):
+    """Project with its watch status."""
+
+    name: str = Field(..., description="Name of the project")
+    path: str = Field(..., description="Path to the project")
+    watch_status: Optional[WatchServiceState] = Field(
+        None, description="Watch status information for the project"
+    )
+
+
+class ProjectItem(BaseModel):
+    """Simple representation of a project."""
+
+    name: str
+    path: str
+    is_default: bool = False
+
+    @property
+    def permalink(self) -> str:  # pragma: no cover
+        return generate_permalink(self.name)
+
+    @property
+    def home(self) -> Path:  # pragma: no cover
+        return Path(self.path).expanduser()
+
+    @property
+    def project_url(self) -> str:  # pragma: no cover
+        return f"/{generate_permalink(self.name)}"
+
+
+class ProjectList(BaseModel):
+    """Response model for listing projects."""
+
+    projects: List[ProjectItem]
+    default_project: str
+
+
+class ProjectStatusResponse(BaseModel):
+    """Response model for switching projects."""
+
+    message: str = Field(..., description="Status message about the project switch")
+    status: str = Field(..., description="Status of the switch (success or error)")
+    default: bool = Field(..., description="True if the project was set as the default")
+    old_project: Optional[ProjectItem] = Field(
+        None, description="Information about the project being switched from"
+    )
+    new_project: Optional[ProjectItem] = Field(
+        None, description="Information about the project being switched to"
+    )

basic_memory/schemas/prompt.py

@@ -0,0 +1,90 @@
+"""Request and response schemas for prompt-related operations."""
+
+from typing import Optional, List, Any, Dict
+from pydantic import BaseModel, Field
+
+from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.memory import EntitySummary, ObservationSummary, RelationSummary
+
+
+class PromptContextItem(BaseModel):
+    """Container for primary and related results to render in a prompt."""
+
+    primary_results: List[EntitySummary]
+    related_results: List[EntitySummary | ObservationSummary | RelationSummary]
+
+
+class ContinueConversationRequest(BaseModel):
+    """Request for generating a continue conversation prompt.
+
+    Used to provide context for continuing a conversation on a specific topic
+    or with recent activity from a given timeframe.
+    """
+
+    topic: Optional[str] = Field(None, description="Topic or keyword to search for")
+    timeframe: Optional[TimeFrame] = Field(
+        None, description="How far back to look for activity (e.g. '1d', '1 week')"
+    )
+    # Limit depth to max 2 for performance reasons - higher values cause significant slowdown
+    search_items_limit: int = Field(
+        5,
+        description="Maximum number of search results to include in context (max 10)",
+        ge=1,
+        le=10,
+    )
+    depth: int = Field(
+        1,
+        description="How many relationship 'hops' to follow when building context (max 5)",
+        ge=1,
+        le=5,
+    )
+    # Limit related items to prevent overloading the context
+    related_items_limit: int = Field(
+        5, description="Maximum number of related items to include in context (max 10)", ge=1, le=10
+    )
+
+
+class SearchPromptRequest(BaseModel):
+    """Request for generating a search results prompt.
+
+    Used to format search results into a prompt with context and suggestions.
+    """
+
+    query: str = Field(..., description="The search query text")
+    timeframe: Optional[TimeFrame] = Field(
+        None, description="Optional timeframe to limit results (e.g. '1d', '1 week')"
+    )
+
+
+class PromptMetadata(BaseModel):
+    """Metadata about a prompt response.
+
+    Contains statistical information about the prompt generation process
+    and results, useful for debugging and UI display.
+    """
+
+    query: Optional[str] = Field(None, description="The original query or topic")
+    timeframe: Optional[str] = Field(None, description="The timeframe used for filtering")
+    search_count: int = Field(0, description="Number of search results found")
+    context_count: int = Field(0, description="Number of context items retrieved")
+    observation_count: int = Field(0, description="Total number of observations included")
+    relation_count: int = Field(0, description="Total number of relations included")
+    total_items: int = Field(0, description="Total number of all items included in the prompt")
+    search_limit: int = Field(0, description="Maximum search results requested")
+    context_depth: int = Field(0, description="Context depth used")
+    related_limit: int = Field(0, description="Maximum related items requested")
+    generated_at: str = Field(..., description="ISO timestamp when this prompt was generated")
+
+
+class PromptResponse(BaseModel):
+    """Response containing the rendered prompt.
+
+    Includes both the rendered prompt text and the context that was used
+    to render it, for potential client-side use.
+    """
+
+    prompt: str = Field(..., description="The rendered prompt text")
+    context: Dict[str, Any] = Field(..., description="The context used to render the prompt")
+    metadata: PromptMetadata = Field(
+        ..., description="Metadata about the prompt generation process"
+    )

basic_memory/schemas/request.py

@@ -1,9 +1,9 @@
 """Request schemas for interacting with the knowledge graph."""
 
-from typing import List, Optional, Annotated
+from typing import List, Optional, Annotated, Literal
 from annotated_types import MaxLen, MinLen
 
-from pydantic import BaseModel
+from pydantic import BaseModel, field_validator
 
 from basic_memory.schemas.base import (
     Relation,
@@ -51,8 +51,62 @@ class GetEntitiesRequest(BaseModel):
     discovered through search.
     """
 
-    permalinks: Annotated[List[Permalink], MinLen(1)]
+    permalinks: Annotated[List[Permalink], MinLen(1), MaxLen(10)]
 
 
 class CreateRelationsRequest(BaseModel):
     relations: List[Relation]
+
+
+class EditEntityRequest(BaseModel):
+    """Request schema for editing an existing entity's content.
+
+    This allows for targeted edits without requiring the full entity content.
+    Supports various operation types for different editing scenarios.
+    """
+
+    operation: Literal["append", "prepend", "find_replace", "replace_section"]
+    content: str
+    section: Optional[str] = None
+    find_text: Optional[str] = None
+    expected_replacements: int = 1
+
+    @field_validator("section")
+    @classmethod
+    def validate_section_for_replace_section(cls, v, info):
+        """Ensure section is provided for replace_section operation."""
+        if info.data.get("operation") == "replace_section" and not v:
+            raise ValueError("section parameter is required for replace_section operation")
+        return v
+
+    @field_validator("find_text")
+    @classmethod
+    def validate_find_text_for_find_replace(cls, v, info):
+        """Ensure find_text is provided for find_replace operation."""
+        if info.data.get("operation") == "find_replace" and not v:
+            raise ValueError("find_text parameter is required for find_replace operation")
+        return v
+
+
+class MoveEntityRequest(BaseModel):
+    """Request schema for moving an entity to a new file location.
+
+    This allows moving notes to different paths while maintaining project
+    consistency and optionally updating permalinks based on configuration.
+    """
+
+    identifier: Annotated[str, MinLen(1), MaxLen(200)]
+    destination_path: Annotated[str, MinLen(1), MaxLen(500)]
+    project: Optional[str] = None
+
+    @field_validator("destination_path")
+    @classmethod
+    def validate_destination_path(cls, v):
+        """Ensure destination path is relative and valid."""
+        if v.startswith("/"):
+            raise ValueError("destination_path must be relative, not absolute")
+        if ".." in v:
+            raise ValueError("destination_path cannot contain '..' path components")
+        if not v.strip():
+            raise ValueError("destination_path cannot be empty or whitespace only")
+        return v.strip()

basic_memory/schemas/response.py

@@ -11,6 +11,7 @@ Key Features:
 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
@@ -43,6 +44,8 @@ class ObservationResponse(Observation, SQLAlchemyModel):
     }
     """
 
+    permalink: Permalink
+
 
 class RelationResponse(Relation, SQLAlchemyModel):
     """Response schema for relation operations.
@@ -59,6 +62,8 @@ class RelationResponse(Relation, SQLAlchemyModel):
     }
     """
 
+    permalink: Permalink
+
     from_id: Permalink = Field(
         # use the permalink from the associated Entity
         # or the from_id value
@@ -126,14 +131,17 @@ class EntityResponse(SQLAlchemyModel):
     }
     """
 
-    permalink: Permalink
+    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):

basic_memory/schemas/search.py

@@ -11,6 +11,8 @@ 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."""
@@ -26,23 +28,29 @@ class SearchQuery(BaseModel):
     Use ONE of these primary search modes:
     - permalink: Exact permalink match
     - permalink_match: Path pattern with *
-    - text: Full-text search of title/content
+    - 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  # Exact permalink match
-    text: Optional[str] = None  # Full-text search
+    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[SearchItemType]] = None  # Filter by item type
-    entity_types: Optional[List[str]] = None  # Filter by entity type
+    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")
@@ -57,58 +65,48 @@ class SearchQuery(BaseModel):
         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."""
 
-    id: int
+    title: str
     type: SearchItemType
     score: float
-    permalink: str
+    entity: Optional[Permalink] = None
+    permalink: Optional[str]
+    content: Optional[str] = None
     file_path: str
 
     metadata: Optional[dict] = None
 
     # Type-specific fields
-    entity_id: Optional[int] = None  # For observations
     category: Optional[str] = None  # For observations
-    from_id: Optional[int] = None  # For relations
-    to_id: Optional[int] = None  # For relations
+    from_entity: Optional[Permalink] = None  # For relations
+    to_entity: Optional[Permalink] = None  # For relations
     relation_type: Optional[str] = None  # For relations
 
 
-class RelatedResult(BaseModel):
-    type: SearchItemType
-    id: int
-    title: str
-    permalink: str
-    depth: int
-    root_id: int
-    created_at: datetime
-    from_id: Optional[int] = None
-    to_id: Optional[int] = None
-    relation_type: Optional[str] = None
-    category: Optional[str] = None
-    entity_id: Optional[int] = None
-
-
 class SearchResponse(BaseModel):
     """Wrapper for search results."""
 
     results: List[SearchResult]
-
-
-# Schema for future advanced search endpoint
-class AdvancedSearchQuery(BaseModel):
-    """Advanced full-text search with explicit FTS5 syntax."""
-
-    query: str  # Raw FTS5 query (e.g., "foo AND bar")
-    types: Optional[List[SearchItemType]] = None
-    entity_types: Optional[List[str]] = None
-    after_date: Optional[Union[datetime, str]] = None
+    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/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"]