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

basic_memory/schemas/project_info.py

@@ -0,0 +1,213 @@
+"""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."""
+
+    id: int
+    external_id: str  # UUID string for API references (required after migration)
+    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,
@@ -56,3 +56,57 @@ class GetEntitiesRequest(BaseModel):
 
 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

@@ -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):
@@ -131,7 +188,7 @@ class EntityResponse(SQLAlchemyModel):
     }
     """
 
-    permalink: Permalink
+    permalink: Optional[Permalink]
     title: str
     file_path: str
     entity_type: EntityType

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,60 +65,53 @@ 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
 
+    # 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
-    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]
     current_page: int
     page_size: int
-
-
-# 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