basic-memory 0.12.3__py3-none-any.whl → 0.13.0b1__py3-none-any.whl

basic_memory/schemas/memory.py

@@ -100,27 +100,41 @@ class MemoryMetadata(BaseModel):
     uri: Optional[str] = None
     types: Optional[List[SearchItemType]] = None
     depth: int
-    timeframe: str
+    timeframe: Optional[str] = None
     generated_at: datetime
-    total_results: int
-    total_relations: int
+    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
 
 
-class GraphContext(BaseModel):
-    """Complete context response."""
+class ContextResult(BaseModel):
+    """Context result containing a primary item with its observations and related items."""
 
-    # Direct matches
-    primary_results: Sequence[EntitySummary | RelationSummary | ObservationSummary] = Field(
-        description="results directly matching URI"
+    primary_result: EntitySummary | RelationSummary | ObservationSummary = Field(
+        description="Primary item"
+    )
+
+    observations: Sequence[ObservationSummary] = Field(
+        description="Observations belonging to this entity", default_factory=list
     )
 
-    # Related entities
     related_results: Sequence[EntitySummary | RelationSummary | ObservationSummary] = Field(
-        description="related results"
+        description="Related items", default_factory=list
+    )
+
+
+class GraphContext(BaseModel):
+    """Complete context response."""
+
+    # 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

basic_memory/schemas/project_info.py

@@ -1,5 +1,6 @@
 """Schema for project info response."""
 
+import os
 from datetime import datetime
 from typing import Dict, List, Optional, Any
 
@@ -75,14 +76,24 @@ class SystemStatus(BaseModel):
     timestamp: datetime = Field(description="Timestamp when the information was collected")
 
 
+class ProjectDetail(BaseModel):
+    """Detailed information about a project."""
+
+    path: str = Field(description="Path to the project directory")
+    active: bool = Field(description="Whether the project is active")
+    id: Optional[int] = Field(description="Database ID of the project if available")
+    is_default: bool = Field(description="Whether this is the default project")
+    permalink: str = Field(description="URL-friendly identifier for the project")
+
+
 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, str] = Field(
-        description="Map of configured project names to paths"
+    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")
 
@@ -94,3 +105,102 @@ class ProjectInfoResponse(BaseModel):
 
     # 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
+
+
+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/search.py

@@ -90,7 +90,7 @@ class SearchResult(BaseModel):
     title: str
     type: SearchItemType
     score: float
-    entity: Optional[Permalink]
+    entity: Optional[Permalink] = None
     permalink: Optional[str]
     content: Optional[str] = None
     file_path: str

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