basic-memory 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

basic_memory/repository/entity_repository.py

@@ -1,8 +1,8 @@
 """Repository for managing entities in the knowledge graph."""
 
-from typing import List, Optional, Sequence
+from pathlib import Path
+from typing import List, Optional, Sequence, Union
 
-from sqlalchemy import select, or_, asc
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 from sqlalchemy.orm import selectinload
 from sqlalchemy.orm.interfaces import LoaderOption
@@ -12,109 +12,57 @@ from basic_memory.repository.repository import Repository
 
 
 class EntityRepository(Repository[Entity]):
-    """Repository for Entity model."""
+    """Repository for Entity model.
+
+    Note: All file paths are stored as strings in the database. Convert Path objects
+    to strings before passing to repository methods.
+    """
 
     def __init__(self, session_maker: async_sessionmaker[AsyncSession]):
         """Initialize with session maker."""
         super().__init__(session_maker, Entity)
 
     async def get_by_permalink(self, permalink: str) -> Optional[Entity]:
-        """Get entity by permalink."""
+        """Get entity by permalink.
+
+        Args:
+            permalink: Unique identifier for the entity
+        """
         query = self.select().where(Entity.permalink == permalink).options(*self.get_load_options())
         return await self.find_one(query)
 
     async def get_by_title(self, title: str) -> Optional[Entity]:
-        """Get entity by title."""
-        query = self.select().where(Entity.title == title).options(*self.get_load_options())
-        return await self.find_one(query)
+        """Get entity by title.
 
-    async def get_by_file_path(self, file_path: str) -> Optional[Entity]:
-        """Get entity by file_path."""
-        query = self.select().where(Entity.file_path == file_path).options(*self.get_load_options())
+        Args:
+            title: Title of the entity to find
+        """
+        query = self.select().where(Entity.title == title).options(*self.get_load_options())
         return await self.find_one(query)
 
-    async def list_entities(
-        self,
-        entity_type: Optional[str] = None,
-        sort_by: Optional[str] = "updated_at",
-        include_related: bool = False,
-    ) -> Sequence[Entity]:
-        """List all entities, optionally filtered by type and sorted."""
-        query = self.select()
-
-        # Always load base relations
-        query = query.options(*self.get_load_options())
-
-        # Apply filters
-        if entity_type:
-            # When include_related is True, get both:
-            # 1. Entities of the requested type
-            # 2. Entities that have relations with entities of the requested type
-            if include_related:
-                query = query.where(
-                    or_(
-                        Entity.entity_type == entity_type,
-                        Entity.outgoing_relations.any(
-                            Relation.to_entity.has(entity_type=entity_type)
-                        ),
-                        Entity.incoming_relations.any(
-                            Relation.from_entity.has(entity_type=entity_type)
-                        ),
-                    )
-                )
-            else:
-                query = query.where(Entity.entity_type == entity_type)
-
-        # Apply sorting
-        if sort_by:
-            sort_field = getattr(Entity, sort_by, Entity.updated_at)
-            query = query.order_by(asc(sort_field))
-
-        result = await self.execute_query(query)
-        return list(result.scalars().all())
-
-    async def get_entity_types(self) -> List[str]:
-        """Get list of distinct entity types."""
-        query = select(Entity.entity_type).distinct()
-
-        result = await self.execute_query(query, use_query_options=False)
-        return list(result.scalars().all())
-
-    async def search(self, query_str: str) -> List[Entity]:
-        """
-        Search for entities.
+    async def get_by_file_path(self, file_path: Union[Path, str]) -> Optional[Entity]:
+        """Get entity by file_path.
 
-        Searches across:
-        - Entity names
-        - Entity types
-        - Entity descriptions
-        - Associated Observations content
+        Args:
+            file_path: Path to the entity file (will be converted to string internally)
         """
-        search_term = f"%{query_str}%"
         query = (
             self.select()
-            .where(
-                or_(
-                    Entity.title.ilike(search_term),
-                    Entity.entity_type.ilike(search_term),
-                    Entity.summary.ilike(search_term),
-                    Entity.observations.any(Observation.content.ilike(search_term)),
-                )
-            )
+            .where(Entity.file_path == str(file_path))
             .options(*self.get_load_options())
         )
-        result = await self.execute_query(query)
-        return list(result.scalars().all())
+        return await self.find_one(query)
 
-    async def delete_entities_by_doc_id(self, doc_id: int) -> bool:
-        """Delete all entities associated with a document."""
-        return await self.delete_by_fields(doc_id=doc_id)
+    async def delete_by_file_path(self, file_path: Union[Path, str]) -> bool:
+        """Delete entity with the provided file_path.
 
-    async def delete_by_file_path(self, file_path: str) -> bool:
-        """Delete entity with the provided file_path."""
-        return await self.delete_by_fields(file_path=file_path)
+        Args:
+            file_path: Path to the entity file (will be converted to string internally)
+        """
+        return await self.delete_by_fields(file_path=str(file_path))
 
     def get_load_options(self) -> List[LoaderOption]:
+        """Get SQLAlchemy loader options for eager loading relationships."""
         return [
             selectinload(Entity.observations).selectinload(Observation.entity),
             # Load from_relations and both entities for each relation
@@ -126,8 +74,11 @@ class EntityRepository(Repository[Entity]):
         ]
 
     async def find_by_permalinks(self, permalinks: List[str]) -> Sequence[Entity]:
-        """Find multiple entities by their permalink."""
+        """Find multiple entities by their permalink.
 
+        Args:
+            permalinks: List of permalink strings to find
+        """
         # Handle empty input explicitly
         if not permalinks:
             return []
@@ -139,18 +90,3 @@ class EntityRepository(Repository[Entity]):
 
         result = await self.execute_query(query)
         return list(result.scalars().all())
-
-    async def delete_by_permalinks(self, permalinks: List[str]) -> int:
-        """Delete multiple entities by permalink."""
-
-        # Handle empty input explicitly
-        if not permalinks:
-            return 0
-
-        # Find matching entities
-        entities = await self.find_by_permalinks(permalinks)
-        if not entities:
-            return 0
-
-        # Use existing delete_by_ids
-        return await self.delete_by_ids([entity.id for entity in entities])

basic_memory/repository/relation_repository.py

@@ -40,12 +40,6 @@ class RelationRepository(Repository[Relation]):
         )
         return await self.find_one(query)
 
-    async def find_by_entity(self, from_entity_id: int) -> Sequence[Relation]:
-        """Find all relations from a specific entity."""
-        query = select(Relation).filter(Relation.from_id == from_entity_id)
-        result = await self.execute_query(query)
-        return result.scalars().all()
-
     async def find_by_entities(self, from_id: int, to_id: int) -> Sequence[Relation]:
         """Find all relations between two entities."""
         query = select(Relation).where((Relation.from_id == from_id) & (Relation.to_id == to_id))
@@ -73,6 +67,5 @@ class RelationRepository(Repository[Relation]):
         result = await self.execute_query(query)
         return result.scalars().all()
 
-
     def get_load_options(self) -> List[LoaderOption]:
         return [selectinload(Relation.from_entity), selectinload(Relation.to_entity)]

basic_memory/repository/repository.py

@@ -1,6 +1,5 @@
 """Base repository implementation."""
 
-from datetime import datetime
 from typing import Type, Optional, Any, Sequence, TypeVar, List
 
 from loguru import logger
@@ -98,13 +97,6 @@ class Repository[T: Base]:
             entities = (self.Model,)
         return select(*entities)
 
-    async def refresh(self, instance: T, relationships: list[str] | None = None) -> None:
-        """Refresh instance and optionally specified relationships."""
-        logger.debug(f"Refreshing {self.Model.__name__} instance: {getattr(instance, 'id', None)}")
-        async with db.scoped_session(self.session_maker) as session:
-            await session.refresh(instance, relationships or [])
-            logger.debug(f"Refreshed relationships: {relationships}")
-
     async def find_all(self, skip: int = 0, limit: Optional[int] = 0) -> Sequence[T]:
         """Fetch records from the database with pagination."""
         logger.debug(f"Finding all {self.Model.__name__} (skip={skip}, limit={limit})")
@@ -149,35 +141,6 @@ class Repository[T: Base]:
             logger.debug(f"No {self.Model.__name__} found")
         return entity
 
-    async def find_modified_since(self, since: datetime) -> Sequence[T]:
-        """Find all records modified since the given timestamp.
-
-        This method assumes the model has an updated_at column. Override
-        in subclasses if a different column should be used.
-
-        Args:
-            since: Datetime to search from
-
-        Returns:
-            Sequence of records modified since the timestamp
-        """
-        logger.debug(f"Finding {self.Model.__name__} modified since: {since}")
-
-        if not hasattr(self.Model, "updated_at"):
-            raise AttributeError(f"{self.Model.__name__} does not have updated_at column")
-
-        query = (
-            select(self.Model)
-            .filter(self.Model.updated_at >= since)
-            .options(*self.get_load_options())
-        )
-
-        async with db.scoped_session(self.session_maker) as session:
-            result = await session.execute(query)
-            items = result.scalars().all()
-            logger.debug(f"Found {len(items)} modified {self.Model.__name__} records")
-            return items
-
     async def create(self, data: dict) -> T:
         """Create a new record from a model instance."""
         logger.debug(f"Creating {self.Model.__name__} from entity_data: {data}")
@@ -223,11 +186,11 @@ class Repository[T: Base]:
                     for key, value in entity_data.items():
                         if key in self.valid_columns:
                             setattr(entity, key, value)
-                            
+
                 elif isinstance(entity_data, self.Model):
                     for column in self.Model.__table__.columns.keys():
                         setattr(entity, column, getattr(entity_data, column))
-                        
+
                 await session.flush()  # Make sure changes are flushed
                 await session.refresh(entity)  # Refresh
 

basic_memory/repository/search_repository.py

@@ -21,6 +21,8 @@ class SearchIndexRow:
 
     id: int
     type: str
+    permalink: str
+    file_path: str
     metadata: Optional[dict] = None
 
     # date values
@@ -30,13 +32,9 @@ class SearchIndexRow:
     # assigned in result
     score: Optional[float] = None
 
-    # Common fields
-    permalink: Optional[str] = None
-    file_path: Optional[str] = None
-
     # Type-specific fields
-    title: Optional[int] = None  # entity
-    content: Optional[int] = None  # entity, observation
+    title: Optional[str] = None  # entity
+    content: Optional[str] = None  # entity, observation
     entity_id: Optional[int] = None  # observations
     category: Optional[str] = None  # observations
     from_id: Optional[int] = None  # relations
@@ -70,7 +68,7 @@ class SearchRepository:
 
     async def init_search_index(self):
         """Create or recreate the search index."""
-        
+
         logger.info("Initializing search index")
         async with db.scoped_session(self.session_maker) as session:
             await session.execute(CREATE_SEARCH_INDEX)
@@ -81,8 +79,8 @@ class SearchRepository:
         For FTS5, special characters and phrases need to be quoted to be treated as a single token.
         """
         # List of special characters that need quoting
-        special_chars = ['/', '*', '-', '.', ' ', '(', ')', '[', ']', '"', "'"]
-        
+        special_chars = ["/", "*", "-", ".", " ", "(", ")", "[", "]", '"', "'"]
+
         # Check if term contains any special characters
         if any(c in term for c in special_chars):
             # If the term already contains quotes, escape them
@@ -96,16 +94,16 @@ class SearchRepository:
         permalink: Optional[str] = None,
         permalink_match: Optional[str] = None,
         title: Optional[str] = None,
-        types: List[SearchItemType] = None,
+        types: Optional[List[SearchItemType]] = None,
         after_date: Optional[datetime] = None,
-        entity_types: List[str] = None,
+        entity_types: Optional[List[str]] = None,
         limit: int = 10,
     ) -> List[SearchIndexRow]:
         """Search across all indexed content with fuzzy matching."""
         conditions = []
         params = {}
         order_by_clause = ""
-        
+
         # Handle text search for title and content
         if search_text:
             search_text = self._quote_search_term(search_text.lower().strip())
@@ -127,7 +125,7 @@ class SearchRepository:
         if permalink_match:
             params["permalink"] = self._quote_search_term(permalink_match)
             conditions.append("permalink MATCH :permalink")
-            
+
         # Handle type filter
         if types:
             type_list = ", ".join(f"'{t.value}'" for t in types)
@@ -142,13 +140,13 @@ class SearchRepository:
         if after_date:
             params["after_date"] = after_date
             conditions.append("datetime(created_at) > datetime(:after_date)")
-            
+
             # order by most recent first
             order_by_clause = ", updated_at DESC"
 
         # set limit on search query
         params["limit"] = limit
-        
+
         # Build WHERE clause
         where_clause = " AND ".join(conditions) if conditions else "1=1"
 
@@ -175,7 +173,7 @@ class SearchRepository:
             LIMIT :limit
         """
 
-        #logger.debug(f"Search {sql} params: {params}")
+        # logger.debug(f"Search {sql} params: {params}")
         async with db.scoped_session(self.session_maker) as session:
             result = await session.execute(text(sql), params)
             rows = result.fetchall()
@@ -201,9 +199,9 @@ class SearchRepository:
             for row in rows
         ]
 
-        #for r in results:
+        # for r in results:
         #    logger.debug(f"Search result: type:{r.type} title: {r.title} permalink: {r.permalink} score: {r.score}")
-        
+
         return results
 
     async def index_item(
@@ -250,17 +248,14 @@ class SearchRepository:
     async def execute_query(
         self,
         query: Executable,
-        params: Optional[Dict[str, Any]] = None,
+        params: Dict[str, Any],
     ) -> Result[Any]:
         """Execute a query asynchronously."""
-        #logger.debug(f"Executing query: {query}")
+        # logger.debug(f"Executing query: {query}, params: {params}")
         async with db.scoped_session(self.session_maker) as session:
             start_time = time.perf_counter()
-            if params:
-                result = await session.execute(query, params)
-            else:
-                result = await session.execute(query)
+            result = await session.execute(query, params)
             end_time = time.perf_counter()
             elapsed_time = end_time - start_time
             logger.debug(f"Query executed successfully in {elapsed_time:.2f}s.")
-            return result
+            return result

basic_memory/schemas/__init__.py

@@ -23,7 +23,7 @@ from basic_memory.schemas.delete import (
 from basic_memory.schemas.request import (
     SearchNodesRequest,
     GetEntitiesRequest,
-    CreateRelationsRequest, UpdateEntityRequest,
+    CreateRelationsRequest,
 )
 
 # Response models
@@ -40,7 +40,8 @@ from basic_memory.schemas.response import (
 # Discovery and analytics models
 from basic_memory.schemas.discovery import (
     EntityTypeList,
-    ObservationCategoryList, TypedEntityList,
+    ObservationCategoryList,
+    TypedEntityList,
 )
 
 # For convenient imports, export all models
@@ -55,7 +56,6 @@ __all__ = [
     "SearchNodesRequest",
     "GetEntitiesRequest",
     "CreateRelationsRequest",
-    "UpdateEntityRequest",
     # Responses
     "SQLAlchemyModel",
     "ObservationResponse",
@@ -69,5 +69,5 @@ __all__ = [
     # Discovery and Analytics
     "EntityTypeList",
     "ObservationCategoryList",
-    "TypedEntityList"
+    "TypedEntityList",
 ]

basic_memory/schemas/base.py

@@ -14,14 +14,13 @@ Key Concepts:
 import mimetypes
 import re
 from datetime import datetime
-from enum import Enum
 from pathlib import Path
 from typing import List, Optional, Annotated, Dict
 
 from annotated_types import MinLen, MaxLen
 from dateparser import parse
 
-from pydantic import BaseModel, BeforeValidator, Field, model_validator, ValidationError
+from pydantic import BaseModel, BeforeValidator, Field, model_validator
 
 from basic_memory.utils import generate_permalink
 
@@ -47,44 +46,6 @@ def to_snake_case(name: str) -> str:
     return s2.lower()
 
 
-def validate_path_format(path: str) -> str:
-    """Validate path has the correct format: not empty."""
-    if not path or not isinstance(path, str):
-        raise ValueError("Path must be a non-empty string")
-
-    return path
-
-
-class ObservationCategory(str, Enum):
-    """Categories for structuring observations.
-
-    Categories help organize knowledge and make it easier to find later:
-    - tech: Implementation details and technical notes
-    - design: Architecture decisions and patterns
-    - feature: User-facing capabilities
-    - note: General observations (default)
-    - issue: Problems or concerns
-    - todo: Future work items
-
-    Categories are case-insensitive for easier use.
-    """
-
-    TECH = "tech"
-    DESIGN = "design"
-    FEATURE = "feature"
-    NOTE = "note"
-    ISSUE = "issue"
-    TODO = "todo"
-
-    @classmethod
-    def _missing_(cls, value: str) -> "ObservationCategory":
-        """Handle case-insensitive lookup."""
-        try:
-            return cls(value.lower())
-        except ValueError:
-            return None
-
-
 def validate_timeframe(timeframe: str) -> str:
     """Convert human readable timeframes to a duration relative to the current time."""
     if not isinstance(timeframe, str):
@@ -110,12 +71,9 @@ def validate_timeframe(timeframe: str) -> str:
     return f"{days}d"
 
 
-TimeFrame = Annotated[
-    str,
-    BeforeValidator(validate_timeframe)
-]
+TimeFrame = Annotated[str, BeforeValidator(validate_timeframe)]
 
-PathId = Annotated[str, BeforeValidator(validate_path_format)]
+Permalink = Annotated[str, MinLen(1)]
 """Unique identifier in format '{path}/{normalized_name}'."""
 
 
@@ -149,14 +107,16 @@ ObservationStr = Annotated[
     MaxLen(1000),  # Keep reasonable length
 ]
 
+
 class Observation(BaseModel):
     """A single observation with category, content, and optional context."""
 
-    category: ObservationCategory
+    category: Optional[str] = None
     content: ObservationStr
     tags: Optional[List[str]] = Field(default_factory=list)
     context: Optional[str] = None
 
+
 class Relation(BaseModel):
     """Represents a directed edge between entities in the knowledge graph.
 
@@ -165,8 +125,8 @@ class Relation(BaseModel):
     or recipient entity.
     """
 
-    from_id: PathId
-    to_id: PathId
+    from_id: Permalink
+    to_id: Permalink
     relation_type: RelationType
     context: Optional[str] = None
 
@@ -181,7 +141,7 @@ class Entity(BaseModel):
     - Optional relations to other entities
     - Optional description for high-level overview
     """
-    
+
     # private field to override permalink
     _permalink: Optional[str] = None
 
@@ -192,28 +152,27 @@ class Entity(BaseModel):
     entity_metadata: Optional[Dict] = Field(default=None, description="Optional metadata")
     content_type: ContentType = Field(
         description="MIME type of the content (e.g. text/markdown, image/jpeg)",
-        examples=["text/markdown", "image/jpeg"], default="text/markdown"
+        examples=["text/markdown", "image/jpeg"],
+        default="text/markdown",
     )
 
     @property
     def file_path(self):
         """Get the file path for this entity based on its permalink."""
         return f"{self.folder}/{self.title}.md" if self.folder else f"{self.title}.md"
-    
+
     @property
-    def permalink(self) -> PathId:
+    def permalink(self) -> Permalink:
         """Get a url friendly path}."""
         return self._permalink or generate_permalink(self.file_path)
 
     @model_validator(mode="after")
-    @classmethod
-    def infer_content_type(cls, entity: "Entity") -> Dict | None:
-        """Infer content_type from file_path if not provided."""
-        if not entity.content_type:
-            path = Path(entity.file_path)
+    def infer_content_type(self) -> "Entity":  # pragma: no cover
+        if not self.content_type:
+            path = Path(self.file_path)
             if not path.exists():
-                return None
-            mime_type, _ = mimetypes.guess_type(path.name)
-            entity.content_type = mime_type or "text/plain"
-
-        return entity
+                self.content_type = "text/plain"
+            else:
+                mime_type, _ = mimetypes.guess_type(path.name)
+                self.content_type = mime_type or "text/plain"
+        return self

basic_memory/schemas/delete.py

@@ -21,7 +21,7 @@ from typing import List, Annotated
 from annotated_types import MinLen
 from pydantic import BaseModel
 
-from basic_memory.schemas.base import Relation, Observation, PathId
+from basic_memory.schemas.base import Permalink
 
 
 class DeleteEntitiesRequest(BaseModel):
@@ -34,5 +34,4 @@ class DeleteEntitiesRequest(BaseModel):
     4. Deletes the corresponding markdown file
     """
 
-    permalinks: Annotated[List[PathId], MinLen(1)]
-
+    permalinks: Annotated[List[Permalink], MinLen(1)]

basic_memory/schemas/discovery.py

@@ -8,18 +8,21 @@ from basic_memory.schemas.response import EntityResponse
 
 class EntityTypeList(BaseModel):
     """List of unique entity types in the system."""
+
     types: List[str]
 
 
 class ObservationCategoryList(BaseModel):
     """List of unique observation categories in the system."""
+
     categories: List[str]
 
 
 class TypedEntityList(BaseModel):
     """List of entities of a specific type."""
+
     entity_type: str = Field(..., description="Type of entities in the list")
     entities: List[EntityResponse]
     total: int = Field(..., description="Total number of entities")
     sort_by: Optional[str] = Field(None, description="Field used for sorting")
-    include_related: bool = Field(False, description="Whether related entities are included")
+    include_related: bool = Field(False, description="Whether related entities are included")