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

basic_memory/api/routers/resource_router.py

@@ -2,9 +2,10 @@
 
 import tempfile
 from pathlib import Path
+from typing import Annotated
 
-from fastapi import APIRouter, HTTPException, BackgroundTasks
-from fastapi.responses import FileResponse
+from fastapi import APIRouter, HTTPException, BackgroundTasks, Body
+from fastapi.responses import FileResponse, JSONResponse
 from loguru import logger
 
 from basic_memory.deps import (
@@ -13,10 +14,13 @@ from basic_memory.deps import (
     SearchServiceDep,
     EntityServiceDep,
     FileServiceDep,
+    EntityRepositoryDep,
 )
 from basic_memory.repository.search_repository import SearchIndexRow
 from basic_memory.schemas.memory import normalize_memory_url
 from basic_memory.schemas.search import SearchQuery, SearchItemType
+from basic_memory.models.knowledge import Entity as EntityModel
+from datetime import datetime
 
 router = APIRouter(prefix="/resource", tags=["resources"])
 
@@ -94,8 +98,7 @@ async def get_resource_content(
             content = await file_service.read_entity_content(result)
             memory_url = normalize_memory_url(result.permalink)
             modified_date = result.updated_at.isoformat()
-            assert result.checksum
-            checksum = result.checksum[:8]
+            checksum = result.checksum[:8] if result.checksum else ""
 
             # Prepare the delimited content
             response_content = f"--- {memory_url} {modified_date} {checksum}\n"
@@ -122,3 +125,115 @@ def cleanup_temp_file(file_path: str):
         logger.debug(f"Temporary file deleted: {file_path}")
     except Exception as e:  # pragma: no cover
         logger.error(f"Error deleting temporary file {file_path}: {e}")
+
+
+@router.put("/{file_path:path}")
+async def write_resource(
+    config: ProjectConfigDep,
+    file_service: FileServiceDep,
+    entity_repository: EntityRepositoryDep,
+    search_service: SearchServiceDep,
+    file_path: str,
+    content: Annotated[str, Body()],
+) -> JSONResponse:
+    """Write content to a file in the project.
+
+    This endpoint allows writing content directly to a file in the project.
+    Also creates an entity record and indexes the file for search.
+
+    Args:
+        file_path: Path to write to, relative to project root
+        request: Contains the content to write
+
+    Returns:
+        JSON response with file information
+    """
+    try:
+        # Get content from request body
+
+        # Defensive type checking: ensure content is a string
+        # FastAPI should validate this, but if a dict somehow gets through
+        # (e.g., via JSON body parsing), we need to catch it here
+        if isinstance(content, dict):
+            logger.error(
+                f"Error writing resource {file_path}: "
+                f"content is a dict, expected string. Keys: {list(content.keys())}"
+            )
+            raise HTTPException(
+                status_code=400,
+                detail="content must be a string, not a dict. "
+                "Ensure request body is sent as raw string content, not JSON object.",
+            )
+
+        # Ensure it's UTF-8 string content
+        if isinstance(content, bytes):  # pragma: no cover
+            content_str = content.decode("utf-8")
+        else:
+            content_str = str(content)
+
+        # Get full file path
+        full_path = Path(f"{config.home}/{file_path}")
+
+        # Ensure parent directory exists
+        full_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write content to file
+        checksum = await file_service.write_file(full_path, content_str)
+
+        # Get file info
+        file_stats = file_service.file_stats(full_path)
+
+        # Determine file details
+        file_name = Path(file_path).name
+        content_type = file_service.content_type(full_path)
+
+        entity_type = "canvas" if file_path.endswith(".canvas") else "file"
+
+        # Check if entity already exists
+        existing_entity = await entity_repository.get_by_file_path(file_path)
+
+        if existing_entity:
+            # Update existing entity
+            entity = await entity_repository.update(
+                existing_entity.id,
+                {
+                    "title": file_name,
+                    "entity_type": entity_type,
+                    "content_type": content_type,
+                    "file_path": file_path,
+                    "checksum": checksum,
+                    "updated_at": datetime.fromtimestamp(file_stats.st_mtime).astimezone(),
+                },
+            )
+            status_code = 200
+        else:
+            # Create a new entity model
+            entity = EntityModel(
+                title=file_name,
+                entity_type=entity_type,
+                content_type=content_type,
+                file_path=file_path,
+                checksum=checksum,
+                created_at=datetime.fromtimestamp(file_stats.st_ctime).astimezone(),
+                updated_at=datetime.fromtimestamp(file_stats.st_mtime).astimezone(),
+            )
+            entity = await entity_repository.add(entity)
+            status_code = 201
+
+        # Index the file for search
+        await search_service.index_entity(entity)  # pyright: ignore
+
+        # Return success response
+        return JSONResponse(
+            status_code=status_code,
+            content={
+                "file_path": file_path,
+                "checksum": checksum,
+                "size": file_stats.st_size,
+                "created_at": file_stats.st_ctime,
+                "modified_at": file_stats.st_mtime,
+            },
+        )
+    except Exception as e:  # pragma: no cover
+        logger.error(f"Error writing resource {file_path}: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to write resource: {str(e)}")

basic_memory/api/routers/search_router.py

@@ -1,11 +1,10 @@
 """Router for search operations."""
 
-from dataclasses import asdict
-
 from fastapi import APIRouter, BackgroundTasks
 
-from basic_memory.schemas.search import SearchQuery, SearchResult, SearchResponse
-from basic_memory.deps import SearchServiceDep
+from basic_memory.api.routers.utils import to_search_results
+from basic_memory.schemas.search import SearchQuery, SearchResponse
+from basic_memory.deps import SearchServiceDep, EntityServiceDep
 
 router = APIRouter(prefix="/search", tags=["search"])
 
@@ -14,6 +13,7 @@ router = APIRouter(prefix="/search", tags=["search"])
 async def search(
     query: SearchQuery,
     search_service: SearchServiceDep,
+    entity_service: EntityServiceDep,
     page: int = 1,
     page_size: int = 10,
 ):
@@ -21,7 +21,7 @@ async def search(
     limit = page_size
     offset = (page - 1) * page_size
     results = await search_service.search(query, limit=limit, offset=offset)
-    search_results = [SearchResult.model_validate(asdict(r)) for r in results]
+    search_results = await to_search_results(entity_service, results)
     return SearchResponse(
         results=search_results,
         current_page=page,

basic_memory/api/routers/utils.py

@@ -0,0 +1,130 @@
+from typing import Optional, List
+
+from basic_memory.repository import EntityRepository
+from basic_memory.repository.search_repository import SearchIndexRow
+from basic_memory.schemas.memory import (
+    EntitySummary,
+    ObservationSummary,
+    RelationSummary,
+    MemoryMetadata,
+    GraphContext,
+    ContextResult,
+)
+from basic_memory.schemas.search import SearchItemType, SearchResult
+from basic_memory.services import EntityService
+from basic_memory.services.context_service import (
+    ContextResultRow,
+    ContextResult as ServiceContextResult,
+)
+
+
+async def to_graph_context(
+    context_result: ServiceContextResult,
+    entity_repository: EntityRepository,
+    page: Optional[int] = None,
+    page_size: Optional[int] = None,
+):
+    # Helper function to convert items to summaries
+    async def to_summary(item: SearchIndexRow | ContextResultRow):
+        match item.type:
+            case SearchItemType.ENTITY:
+                return EntitySummary(
+                    title=item.title,  # pyright: ignore
+                    permalink=item.permalink,
+                    content=item.content,
+                    file_path=item.file_path,
+                    created_at=item.created_at,
+                )
+            case SearchItemType.OBSERVATION:
+                return ObservationSummary(
+                    title=item.title,  # pyright: ignore
+                    file_path=item.file_path,
+                    category=item.category,  # pyright: ignore
+                    content=item.content,  # pyright: ignore
+                    permalink=item.permalink,  # pyright: ignore
+                    created_at=item.created_at,
+                )
+            case SearchItemType.RELATION:
+                from_entity = await entity_repository.find_by_id(item.from_id)  # pyright: ignore
+                to_entity = await entity_repository.find_by_id(item.to_id) if item.to_id else None
+                return RelationSummary(
+                    title=item.title,  # pyright: ignore
+                    file_path=item.file_path,
+                    permalink=item.permalink,  # pyright: ignore
+                    relation_type=item.relation_type,  # pyright: ignore
+                    from_entity=from_entity.title if from_entity else None,
+                    to_entity=to_entity.title if to_entity else None,
+                    created_at=item.created_at,
+                )
+            case _:  # pragma: no cover
+                raise ValueError(f"Unexpected type: {item.type}")
+
+    # Process the hierarchical results
+    hierarchical_results = []
+    for context_item in context_result.results:
+        # Process primary result
+        primary_result = await to_summary(context_item.primary_result)
+
+        # Process observations
+        observations = []
+        for obs in context_item.observations:
+            observations.append(await to_summary(obs))
+
+        # Process related results
+        related = []
+        for rel in context_item.related_results:
+            related.append(await to_summary(rel))
+
+        # Add to hierarchical results
+        hierarchical_results.append(
+            ContextResult(
+                primary_result=primary_result,
+                observations=observations,
+                related_results=related,
+            )
+        )
+
+    # Create schema metadata from service metadata
+    metadata = MemoryMetadata(
+        uri=context_result.metadata.uri,
+        types=context_result.metadata.types,
+        depth=context_result.metadata.depth,
+        timeframe=context_result.metadata.timeframe,
+        generated_at=context_result.metadata.generated_at,
+        primary_count=context_result.metadata.primary_count,
+        related_count=context_result.metadata.related_count,
+        total_results=context_result.metadata.primary_count + context_result.metadata.related_count,
+        total_relations=context_result.metadata.total_relations,
+        total_observations=context_result.metadata.total_observations,
+    )
+
+    # Return new GraphContext with just hierarchical results
+    return GraphContext(
+        results=hierarchical_results,
+        metadata=metadata,
+        page=page,
+        page_size=page_size,
+    )
+
+
+async def to_search_results(entity_service: EntityService, results: List[SearchIndexRow]):
+    search_results = []
+    for r in results:
+        entities = await entity_service.get_entities_by_id([r.entity_id, r.from_id, r.to_id])  # pyright: ignore
+        search_results.append(
+            SearchResult(
+                title=r.title,  # pyright: ignore
+                type=r.type,  # pyright: ignore
+                permalink=r.permalink,
+                score=r.score,  # pyright: ignore
+                entity=entities[0].permalink if entities else None,
+                content=r.content,
+                file_path=r.file_path,
+                metadata=r.metadata,
+                category=r.category,
+                from_entity=entities[0].permalink if entities else None,
+                to_entity=entities[1].permalink if len(entities) > 1 else None,
+                relation_type=r.relation_type,
+            )
+        )
+    return search_results

basic_memory/api/template_loader.py

@@ -0,0 +1,292 @@
+"""Template loading and rendering utilities for the Basic Memory API.
+
+This module handles the loading and rendering of Handlebars templates from the
+templates directory, providing a consistent interface for all prompt-related
+formatting needs.
+"""
+
+import textwrap
+from typing import Dict, Any, Optional, Callable
+from pathlib import Path
+import json
+import datetime
+
+import pybars
+from loguru import logger
+
+# Get the base path of the templates directory
+TEMPLATES_DIR = Path(__file__).parent.parent / "templates"
+
+
+# Custom helpers for Handlebars
+def _date_helper(this, *args):
+    """Format a date using the given format string."""
+    if len(args) < 1:  # pragma: no cover
+        return ""
+
+    timestamp = args[0]
+    format_str = args[1] if len(args) > 1 else "%Y-%m-%d %H:%M"
+
+    if hasattr(timestamp, "strftime"):
+        result = timestamp.strftime(format_str)
+    elif isinstance(timestamp, str):
+        try:
+            dt = datetime.datetime.fromisoformat(timestamp)
+            result = dt.strftime(format_str)
+        except ValueError:
+            result = timestamp
+    else:
+        result = str(timestamp)  # pragma: no cover
+
+    return pybars.strlist([result])
+
+
+def _default_helper(this, *args):
+    """Return a default value if the given value is None or empty."""
+    if len(args) < 2:  # pragma: no cover
+        return ""
+
+    value = args[0]
+    default_value = args[1]
+
+    result = default_value if value is None or value == "" else value
+    # Use strlist for consistent handling of HTML escaping
+    return pybars.strlist([str(result)])
+
+
+def _capitalize_helper(this, *args):
+    """Capitalize the first letter of a string."""
+    if len(args) < 1:  # pragma: no cover
+        return ""
+
+    text = args[0]
+    if not text or not isinstance(text, str):  # pragma: no cover
+        result = ""
+    else:
+        result = text.capitalize()
+
+    return pybars.strlist([result])
+
+
+def _round_helper(this, *args):
+    """Round a number to the specified number of decimal places."""
+    if len(args) < 1:
+        return ""
+
+    value = args[0]
+    decimal_places = args[1] if len(args) > 1 else 2
+
+    try:
+        result = str(round(float(value), int(decimal_places)))
+    except (ValueError, TypeError):
+        result = str(value)
+
+    return pybars.strlist([result])
+
+
+def _size_helper(this, *args):
+    """Return the size/length of a collection."""
+    if len(args) < 1:
+        return 0
+
+    value = args[0]
+    if value is None:
+        result = "0"
+    elif isinstance(value, (list, tuple, dict, str)):
+        result = str(len(value))  # pragma: no cover
+    else:  # pragma: no cover
+        result = "0"
+
+    return pybars.strlist([result])
+
+
+def _json_helper(this, *args):
+    """Convert a value to a JSON string."""
+    if len(args) < 1:  # pragma: no cover
+        return "{}"
+
+    value = args[0]
+    # For pybars, we need to return a SafeString to prevent HTML escaping
+    result = json.dumps(value)  # pragma: no cover
+    # Safe string implementation to prevent HTML escaping
+    return pybars.strlist([result])
+
+
+def _math_helper(this, *args):
+    """Perform basic math operations."""
+    if len(args) < 3:
+        return pybars.strlist(["Math error: Insufficient arguments"])
+
+    lhs = args[0]
+    operator = args[1]
+    rhs = args[2]
+
+    try:
+        lhs = float(lhs)
+        rhs = float(rhs)
+        if operator == "+":
+            result = str(lhs + rhs)
+        elif operator == "-":
+            result = str(lhs - rhs)
+        elif operator == "*":
+            result = str(lhs * rhs)
+        elif operator == "/":
+            result = str(lhs / rhs)
+        else:
+            result = f"Unsupported operator: {operator}"
+    except (ValueError, TypeError) as e:
+        result = f"Math error: {e}"
+
+    return pybars.strlist([result])
+
+
+def _lt_helper(this, *args):
+    """Check if left hand side is less than right hand side."""
+    if len(args) < 2:
+        return False
+
+    lhs = args[0]
+    rhs = args[1]
+
+    try:
+        return float(lhs) < float(rhs)
+    except (ValueError, TypeError):
+        # Fall back to string comparison for non-numeric values
+        return str(lhs) < str(rhs)
+
+
+def _if_cond_helper(this, options, condition):
+    """Block helper for custom if conditionals."""
+    if condition:
+        return options["fn"](this)
+    elif "inverse" in options:
+        return options["inverse"](this)
+    return ""  # pragma: no cover
+
+
+def _dedent_helper(this, options):
+    """Dedent a block of text to remove common leading whitespace.
+
+    Usage:
+    {{#dedent}}
+        This text will have its
+        common leading whitespace removed
+        while preserving relative indentation.
+    {{/dedent}}
+    """
+    if "fn" not in options:  # pragma: no cover
+        return ""
+
+    # Get the content from the block
+    content = options["fn"](this)
+
+    # Convert to string if it's a strlist
+    if (
+        isinstance(content, list)
+        or hasattr(content, "__iter__")
+        and not isinstance(content, (str, bytes))
+    ):
+        content_str = "".join(str(item) for item in content)  # pragma: no cover
+    else:
+        content_str = str(content)  # pragma: no cover
+
+    # Add trailing and leading newlines to ensure proper dedenting
+    # This is critical for textwrap.dedent to work correctly with mixed content
+    content_str = "\n" + content_str + "\n"
+
+    # Use textwrap to dedent the content and remove the extra newlines we added
+    dedented = textwrap.dedent(content_str)[1:-1]
+
+    # Return as a SafeString to prevent HTML escaping
+    return pybars.strlist([dedented])  # pragma: no cover
+
+
+class TemplateLoader:
+    """Loader for Handlebars templates.
+
+    This class is responsible for loading templates from disk and rendering
+    them with the provided context data.
+    """
+
+    def __init__(self, template_dir: Optional[str] = None):
+        """Initialize the template loader.
+
+        Args:
+            template_dir: Optional custom template directory path
+        """
+        self.template_dir = Path(template_dir) if template_dir else TEMPLATES_DIR
+        self.template_cache: Dict[str, Callable] = {}
+        self.compiler = pybars.Compiler()
+
+        # Set up standard helpers
+        self.helpers = {
+            "date": _date_helper,
+            "default": _default_helper,
+            "capitalize": _capitalize_helper,
+            "round": _round_helper,
+            "size": _size_helper,
+            "json": _json_helper,
+            "math": _math_helper,
+            "lt": _lt_helper,
+            "if_cond": _if_cond_helper,
+            "dedent": _dedent_helper,
+        }
+
+        logger.debug(f"Initialized template loader with directory: {self.template_dir}")
+
+    def get_template(self, template_path: str) -> Callable:
+        """Get a template by path, using cache if available.
+
+        Args:
+            template_path: The path to the template, relative to the templates directory
+
+        Returns:
+            The compiled Handlebars template
+
+        Raises:
+            FileNotFoundError: If the template doesn't exist
+        """
+        if template_path in self.template_cache:
+            return self.template_cache[template_path]
+
+        # Convert from Liquid-style path to Handlebars extension
+        if template_path.endswith(".liquid"):
+            template_path = template_path.replace(".liquid", ".hbs")
+        elif not template_path.endswith(".hbs"):
+            template_path = f"{template_path}.hbs"
+
+        full_path = self.template_dir / template_path
+
+        if not full_path.exists():
+            raise FileNotFoundError(f"Template not found: {full_path}")
+
+        with open(full_path, "r", encoding="utf-8") as f:
+            template_str = f.read()
+
+        template = self.compiler.compile(template_str)
+        self.template_cache[template_path] = template
+
+        logger.debug(f"Loaded template: {template_path}")
+        return template
+
+    async def render(self, template_path: str, context: Dict[str, Any]) -> str:
+        """Render a template with the given context.
+
+        Args:
+            template_path: The path to the template, relative to the templates directory
+            context: The context data to pass to the template
+
+        Returns:
+            The rendered template as a string
+        """
+        template = self.get_template(template_path)
+        return template(context, helpers=self.helpers)
+
+    def clear_cache(self) -> None:
+        """Clear the template cache."""
+        self.template_cache.clear()
+        logger.debug("Template cache cleared")
+
+
+# Global template loader instance
+template_loader = TemplateLoader()

basic_memory/cli/app.py

@@ -1,20 +1,54 @@
-import asyncio
+from typing import Optional
 
 import typer
 
-from basic_memory import db
-from basic_memory.config import config
-from basic_memory.utils import setup_logging
+from basic_memory.config import ConfigManager
 
-setup_logging(log_file=".basic-memory/basic-memory-cli.log", console=False)  # pragma: no cover
 
-asyncio.run(db.run_migrations(config))
+def version_callback(value: bool) -> None:
+    """Show version and exit."""
+    if value:  # pragma: no cover
+        import basic_memory
+
+        typer.echo(f"Basic Memory version: {basic_memory.__version__}")
+        raise typer.Exit()
+
 
 app = typer.Typer(name="basic-memory")
 
-import_app = typer.Typer()
-app.add_typer(import_app, name="import")
+
+@app.callback()
+def app_callback(
+    ctx: typer.Context,
+    version: Optional[bool] = typer.Option(
+        None,
+        "--version",
+        "-v",
+        help="Show version and exit.",
+        callback=version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """Basic Memory - Local-first personal knowledge management."""
+
+    # Run initialization for every command unless --version was specified
+    if not version and ctx.invoked_subcommand is not None:
+        from basic_memory.services.initialization import ensure_initialization
+
+        app_config = ConfigManager().config
+        ensure_initialization(app_config)
 
 
-claude_app = typer.Typer()
+## import
+# Register sub-command groups
+import_app = typer.Typer(help="Import data from various sources")
+app.add_typer(import_app, name="import")
+
+claude_app = typer.Typer(help="Import Conversations from Claude JSON export.")
 import_app.add_typer(claude_app, name="claude")
+
+
+## cloud
+
+cloud_app = typer.Typer(help="Access Basic Memory Cloud")
+app.add_typer(cloud_app, name="cloud")