basic-memory 0.0.0__py3-none-any.whl

basic_memory/schemas/base.py

@@ -0,0 +1,216 @@
+"""Core pydantic models for basic-memory entities, observations, and relations.
+
+This module defines the foundational data structures for the knowledge graph system.
+The graph consists of entities (nodes) connected by relations (edges), where each
+entity can have multiple observations (facts) attached to it.
+
+Key Concepts:
+1. Entities are nodes storing factual observations
+2. Relations are directed edges between entities using active voice verbs
+3. Observations are atomic facts/notes about an entity
+4. Everything is stored in both SQLite and markdown files
+"""
+
+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 basic_memory.utils import generate_permalink
+
+
+def to_snake_case(name: str) -> str:
+    """Convert a string to snake_case.
+
+    Examples:
+        BasicMemory -> basic_memory
+        Memory Service -> memory_service
+        memory-service -> memory_service
+        Memory_Service -> memory_service
+    """
+    name = name.strip()
+
+    # Replace spaces and hyphens and . with underscores
+    s1 = re.sub(r"[\s\-\\.]", "_", name)
+
+    # Insert underscore between camelCase
+    s2 = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s1)
+
+    # Convert to lowercase
+    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):
+        raise ValueError("Timeframe must be a string")
+
+    # Parse relative time expression
+    parsed = parse(timeframe)
+    if not parsed:
+        raise ValueError(f"Could not parse timeframe: {timeframe}")
+
+    # Convert to duration
+    now = datetime.now()
+    if parsed > now:
+        raise ValueError("Timeframe cannot be in the future")
+
+    # Could format the duration back to our standard format
+    days = (now - parsed).days
+
+    # Could enforce reasonable limits
+    if days > 365:
+        raise ValueError("Timeframe should be <= 1 year")
+
+    return f"{days}d"
+
+
+TimeFrame = Annotated[
+    str,
+    BeforeValidator(validate_timeframe)
+]
+
+PathId = Annotated[str, BeforeValidator(validate_path_format)]
+"""Unique identifier in format '{path}/{normalized_name}'."""
+
+
+EntityType = Annotated[str, BeforeValidator(to_snake_case), MinLen(1), MaxLen(200)]
+"""Classification of entity (e.g., 'person', 'project', 'concept'). """
+
+ALLOWED_CONTENT_TYPES = {
+    "text/markdown",
+    "text/plain",
+    "application/pdf",
+    "image/jpeg",
+    "image/png",
+    "image/svg+xml",
+}
+
+ContentType = Annotated[
+    str,
+    BeforeValidator(str.lower),
+    Field(pattern=r"^[\w\-\+\.]+/[\w\-\+\.]+$"),
+    Field(json_schema_extra={"examples": list(ALLOWED_CONTENT_TYPES)}),
+]
+
+
+RelationType = Annotated[str, MinLen(1), MaxLen(200)]
+"""Type of relationship between entities. Always use active voice present tense."""
+
+ObservationStr = Annotated[
+    str,
+    BeforeValidator(str.strip),  # Clean whitespace
+    MinLen(1),  # Ensure non-empty after stripping
+    MaxLen(1000),  # Keep reasonable length
+]
+
+class Observation(BaseModel):
+    """A single observation with category, content, and optional context."""
+
+    category: ObservationCategory
+    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.
+
+    Relations are directed connections stored in active voice (e.g., "created", "depends_on").
+    The from_permalink represents the source or actor entity, while to_permalink represents the target
+    or recipient entity.
+    """
+
+    from_id: PathId
+    to_id: PathId
+    relation_type: RelationType
+    context: Optional[str] = None
+
+
+class Entity(BaseModel):
+    """Represents a node in our knowledge graph - could be a person, project, concept, etc.
+
+    Each entity has:
+    - A file path (e.g., "people/jane-doe.md")
+    - An entity type (for classification)
+    - A list of observations (facts/notes about the entity)
+    - Optional relations to other entities
+    - Optional description for high-level overview
+    """
+
+    title: str
+    content: Optional[str] = None
+    folder: str
+    entity_type: EntityType = "note"
+    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"
+    )
+
+    @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:
+        """Get the path ID in format {snake_case_title}."""
+        return 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)
+            if not path.exists():
+                return None
+            mime_type, _ = mimetypes.guess_type(path.name)
+            entity.content_type = mime_type or "text/plain"
+
+        return entity

basic_memory/schemas/delete.py

@@ -0,0 +1,38 @@
+"""Delete operation schemas for the knowledge graph.
+
+This module defines the request schemas for removing entities, relations,
+and observations from the knowledge graph. Each operation has specific
+implications and safety considerations.
+
+Deletion Hierarchy:
+1. Entity deletion removes the entity and all its relations
+2. Relation deletion only removes the connection between entities
+3. Observation deletion preserves entity and relations
+
+Key Considerations:
+- All deletions are permanent
+- Entity deletions cascade to relations
+- Files are removed along with entities
+- Operations are atomic - they fully succeed or fail
+"""
+
+from typing import List, Annotated
+
+from annotated_types import MinLen
+from pydantic import BaseModel
+
+from basic_memory.schemas.base import Relation, Observation, PathId
+
+
+class DeleteEntitiesRequest(BaseModel):
+    """Delete one or more entities from the knowledge graph.
+
+    This operation:
+    1. Removes the entity from the database
+    2. Deletes all observations attached to the entity
+    3. Removes all relations where the entity is source or target
+    4. Deletes the corresponding markdown file
+    """
+
+    permalinks: Annotated[List[PathId], MinLen(1)]
+

basic_memory/schemas/discovery.py

@@ -0,0 +1,25 @@
+"""Schemas for knowledge discovery and analytics endpoints."""
+
+from typing import List, Optional
+from pydantic import BaseModel, Field
+
+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")

basic_memory/schemas/memory.py

@@ -0,0 +1,111 @@
+"""Schemas for memory context."""
+
+from datetime import datetime
+from typing import Dict, List, Any, Optional, Annotated
+
+import pydantic
+from annotated_types import MinLen, MaxLen
+from pydantic import BaseModel, field_validator, Field, BeforeValidator, TypeAdapter, AnyUrl
+
+from basic_memory.schemas.search import SearchItemType
+
+
+def normalize_memory_url(url: str) -> str:
+    """Normalize a MemoryUrl string.
+
+    Args:
+        url: A path like "specs/search" or "memory://specs/search"
+
+    Returns:
+        Normalized URL starting with memory://
+
+    Examples:
+        >>> normalize_memory_url("specs/search")
+        'memory://specs/search'
+        >>> normalize_memory_url("memory://specs/search")
+        'memory://specs/search'
+    """
+    clean_path = url.removeprefix("memory://")
+    return f"memory://{clean_path}"
+
+
+MemoryUrl = Annotated[
+    str,
+    BeforeValidator(str.strip),  # Clean whitespace
+    MinLen(1),       
+    MaxLen(2028),   
+]
+
+memory_url = TypeAdapter(MemoryUrl) 
+
+def memory_url_path(url: memory_url) -> str:
+    """
+    Returns the uri for a url value by removing the prefix "memory://" from a given MemoryUrl.
+
+    This function processes a given MemoryUrl by removing the "memory://"
+    prefix and returns the resulting string. If the provided url does not 
+    begin with "memory://", the function will simply return the input url 
+    unchanged.
+
+    :param url: A MemoryUrl object representing the URL with a "memory://" prefix.
+    :type url: MemoryUrl
+    :return: A string representing the URL with the "memory://" prefix removed.
+    :rtype: str
+    """
+    return url.removeprefix("memory://")
+
+
+
+class EntitySummary(BaseModel):
+    """Simplified entity representation."""
+
+    permalink: str
+    title: str
+    file_path: str
+    created_at: datetime
+
+
+class RelationSummary(BaseModel):
+    """Simplified relation representation."""
+
+    permalink: str
+    type: str
+    from_id: str
+    to_id: Optional[str] = None
+
+
+class ObservationSummary(BaseModel):
+    """Simplified observation representation."""
+
+    permalink: str
+    category: str
+    content: str
+
+
+class MemoryMetadata(BaseModel):
+    """Simplified response metadata."""
+
+    uri: Optional[str] = None
+    types: Optional[List[SearchItemType]] = None
+    depth: int
+    timeframe: str
+    generated_at: datetime
+    total_results: int
+    total_relations: int
+
+
+class GraphContext(BaseModel):
+    """Complete context response."""
+
+    # Direct matches
+    primary_results: List[EntitySummary | RelationSummary | ObservationSummary] = Field(
+        description="results directly matching URI"
+    )
+
+    # Related entities
+    related_results: List[EntitySummary | RelationSummary | ObservationSummary] = Field(
+        description="related results"
+    )
+
+    # Context metadata
+    metadata: MemoryMetadata

basic_memory/schemas/request.py

@@ -0,0 +1,77 @@
+"""Request schemas for interacting with the knowledge graph."""
+
+from typing import List, Optional, Annotated, Dict, Any
+from annotated_types import MaxLen, MinLen
+
+from pydantic import BaseModel
+
+from basic_memory.schemas.base import (
+    Observation,
+    Entity,
+    Relation,
+    PathId,
+    ObservationCategory,
+    EntityType,
+)
+
+
+
+
+
+class SearchNodesRequest(BaseModel):
+    """Search for entities in the knowledge graph.
+
+    The search looks across multiple fields:
+    - Entity title
+    - Entity types
+    - summary
+    - file content
+    - Observations
+
+    Features:
+    - Case-insensitive matching
+    - Partial word matches
+    - Returns full entity objects with relations
+    - Includes all matching entities
+    - If a category is specified, only entities with that category are returned
+
+    Example Queries:
+    - "memory" - Find entities related to memory systems
+    - "SQLite" - Find database-related components
+    - "test" - Find test-related entities
+    - "implementation" - Find concrete implementations
+    - "service" - Find service components
+
+    Note: Currently uses SQL ILIKE for matching. Wildcard (*) searches
+    and full-text search capabilities are planned for future versions.
+    """
+
+    query: Annotated[str, MinLen(1), MaxLen(200)]
+    category: Optional[ObservationCategory] = None
+
+
+class GetEntitiesRequest(BaseModel):
+    """Retrieve specific entities by their IDs.
+
+    Used to load complete entity details including all observations
+    and relations. Particularly useful for following relations
+    discovered through search.
+    """
+
+    permalinks: Annotated[List[PathId], MinLen(1)]
+
+
+class CreateRelationsRequest(BaseModel):
+    relations: List[Relation]
+
+
+## update
+
+# TODO remove UpdateEntityRequest
+class UpdateEntityRequest(BaseModel):
+    """Request to update an existing entity."""
+
+    title: Optional[str] = None
+    entity_type: Optional[EntityType] = None
+    content: Optional[str] = None
+    entity_metadata: Optional[Dict[str, Any]] = None

basic_memory/schemas/response.py

@@ -0,0 +1,220 @@
+"""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 typing import List, Optional, Dict
+
+from pydantic import BaseModel, ConfigDict, Field, AliasPath, AliasChoices
+
+from basic_memory.schemas.base import Relation, PathId, 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"
+    }
+    """
+
+
+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"
+    }
+    """
+
+    from_id: PathId = 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[PathId] = Field(
+        # 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[PathId] = 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: PathId
+    title: str
+    file_path: str
+    entity_type: EntityType
+    entity_metadata: Optional[Dict] = None
+    content_type: ContentType
+    observations: List[ObservationResponse] = []
+    relations: List[RelationResponse] = []
+
+
+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