tribalmemory 0.1.0__py3-none-any.whl

tribalmemory/server/models.py

@@ -0,0 +1,206 @@
+"""Pydantic models for HTTP API request/response."""
+
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class SourceType(str, Enum):
+    """Memory source types."""
+    USER_EXPLICIT = "user_explicit"
+    AUTO_CAPTURE = "auto_capture"
+    CORRECTION = "correction"
+    CROSS_INSTANCE = "cross_instance"
+    LEGACY = "legacy"
+    UNKNOWN = "unknown"
+
+
+# =============================================================================
+# Request Models
+# =============================================================================
+
+class RememberRequest(BaseModel):
+    """Request to store a new memory."""
+    content: str = Field(..., description="The memory content to store")
+    source_type: SourceType = Field(
+        default=SourceType.AUTO_CAPTURE,
+        description="How this memory was captured"
+    )
+    context: Optional[str] = Field(
+        default=None,
+        description="Additional context about the capture"
+    )
+    tags: Optional[list[str]] = Field(
+        default=None,
+        description="Tags for categorization and filtering"
+    )
+    skip_dedup: bool = Field(
+        default=False,
+        description="If True, store even if similar memory exists"
+    )
+
+
+class RecallRequest(BaseModel):
+    """Request to recall memories."""
+    query: str = Field(..., description="Natural language search query")
+    limit: int = Field(default=5, ge=1, le=50, description="Maximum results")
+    min_relevance: float = Field(
+        default=0.3,
+        ge=0.0,
+        le=1.0,
+        description="Minimum similarity score"
+    )
+    tags: Optional[list[str]] = Field(
+        default=None,
+        description="Filter by tags"
+    )
+
+
+class CorrectRequest(BaseModel):
+    """Request to correct an existing memory."""
+    original_id: str = Field(..., description="ID of memory to correct")
+    corrected_content: str = Field(..., description="Corrected information")
+    context: Optional[str] = Field(
+        default=None,
+        description="Context about the correction"
+    )
+
+
+# =============================================================================
+# Response Models
+# =============================================================================
+
+class MemoryEntryResponse(BaseModel):
+    """A single memory entry."""
+    id: str
+    content: str
+    source_instance: str
+    source_type: SourceType
+    created_at: datetime
+    updated_at: datetime
+    tags: list[str]
+    context: Optional[str]
+    confidence: float
+    supersedes: Optional[str]
+
+    model_config = {"from_attributes": True}
+
+
+class StoreResponse(BaseModel):
+    """Response from storing a memory."""
+    success: bool
+    memory_id: Optional[str] = None
+    duplicate_of: Optional[str] = None
+    error: Optional[str] = None
+
+
+class RecallResultResponse(BaseModel):
+    """A single recall result with score."""
+    memory: MemoryEntryResponse
+    similarity_score: float
+    retrieval_time_ms: float
+
+
+class RecallResponse(BaseModel):
+    """Response from recalling memories."""
+    results: list[RecallResultResponse]
+    query: str
+    total_time_ms: float
+    error: Optional[str] = None
+
+
+class HealthResponse(BaseModel):
+    """Health check response."""
+    status: str = "ok"
+    instance_id: str
+    memory_count: int
+    version: str = "0.1.0"
+
+
+class StatsResponse(BaseModel):
+    """Memory statistics response."""
+    total_memories: int
+    by_source_type: dict[str, int]
+    by_tag: dict[str, int]
+    instance_id: str
+
+
+class ErrorResponse(BaseModel):
+    """Error response."""
+    error: str
+    detail: Optional[str] = None
+
+
+class ForgetResponse(BaseModel):
+    """Response from forgetting a memory."""
+    success: bool
+    memory_id: str
+
+
+class ShutdownResponse(BaseModel):
+    """Response from shutdown request."""
+    status: str
+
+
+# =============================================================================
+# Import/Export Models (Issue #7)
+# =============================================================================
+
+class ExportRequest(BaseModel):
+    """Request to export memories."""
+    tags: Optional[list[str]] = Field(
+        default=None,
+        description="Filter: only memories matching any of these tags",
+    )
+    date_from: Optional[str] = Field(
+        default=None,
+        description="Filter: ISO 8601 datetime lower bound (created_at)",
+    )
+    date_to: Optional[str] = Field(
+        default=None,
+        description="Filter: ISO 8601 datetime upper bound (created_at)",
+    )
+
+
+class ExportResponse(BaseModel):
+    """Response containing the exported bundle."""
+    success: bool
+    memory_count: int = 0
+    bundle: Optional[dict] = None
+    error: Optional[str] = None
+
+
+class ImportRequest(BaseModel):
+    """Request to import memories from a bundle."""
+    bundle: dict = Field(
+        ..., description="Portable bundle (manifest + entries)",
+    )
+    conflict_resolution: str = Field(
+        default="skip",
+        description="Conflict strategy: skip | overwrite | merge",
+    )
+    embedding_strategy: str = Field(
+        default="auto",
+        description="Embedding strategy: auto | keep | drop",
+    )
+    dry_run: bool = Field(
+        default=False,
+        description="Preview changes without writing",
+    )
+
+
+class ImportResponse(BaseModel):
+    """Response from import operation."""
+    success: bool
+    total: int = 0
+    imported: int = 0
+    skipped: int = 0
+    overwritten: int = 0
+    errors: int = 0
+    needs_reembedding: bool = False
+    dry_run: bool = False
+    duration_ms: float = 0.0
+    error_details: list[str] = Field(default_factory=list)
+    error: Optional[str] = None

tribalmemory/server/routes.py

@@ -0,0 +1,378 @@
+"""API route handlers."""
+
+import time
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, Depends
+
+from ..interfaces import MemorySource, MemoryEntry
+from ..services import TribalMemoryService
+from .models import (
+    RememberRequest,
+    RecallRequest,
+    CorrectRequest,
+    StoreResponse,
+    RecallResponse,
+    RecallResultResponse,
+    MemoryEntryResponse,
+    HealthResponse,
+    StatsResponse,
+    ForgetResponse,
+    ShutdownResponse,
+    SourceType,
+    ExportRequest,
+    ExportResponse,
+    ImportRequest,
+    ImportResponse,
+)
+
+router = APIRouter(prefix="/v1", tags=["memory"])
+
+
+def get_memory_service() -> TribalMemoryService:
+    """Dependency injection for memory service.
+    
+    This is set by the app during startup.
+    """
+    from .app import _memory_service
+    if _memory_service is None:
+        raise HTTPException(status_code=503, detail="Service not initialized")
+    return _memory_service
+
+
+def get_instance_id() -> str:
+    """Get the current instance ID."""
+    from .app import _instance_id
+    return _instance_id or "unknown"
+
+
+def _convert_source_type(source_type: SourceType) -> MemorySource:
+    """Convert API source type to internal enum."""
+    return MemorySource(source_type.value)
+
+
+def _entry_to_response(entry: MemoryEntry) -> MemoryEntryResponse:
+    """Convert internal MemoryEntry to API response."""
+    return MemoryEntryResponse(
+        id=entry.id,
+        content=entry.content,
+        source_instance=entry.source_instance,
+        source_type=SourceType(entry.source_type.value),
+        created_at=entry.created_at,
+        updated_at=entry.updated_at,
+        tags=entry.tags,
+        context=entry.context,
+        confidence=entry.confidence,
+        supersedes=entry.supersedes,
+    )
+
+
+@router.post("/remember", response_model=StoreResponse)
+async def remember(
+    request: RememberRequest,
+    service: TribalMemoryService = Depends(get_memory_service),
+) -> StoreResponse:
+    """Store a new memory."""
+    try:
+        result = await service.remember(
+            content=request.content,
+            source_type=_convert_source_type(request.source_type),
+            context=request.context,
+            tags=request.tags,
+            skip_dedup=request.skip_dedup,
+        )
+
+        return StoreResponse(
+            success=result.success,
+            memory_id=result.memory_id,
+            duplicate_of=result.duplicate_of,
+            error=result.error,
+        )
+    except Exception as e:
+        return StoreResponse(success=False, error=str(e))
+
+
+@router.post("/recall", response_model=RecallResponse)
+async def recall(
+    request: RecallRequest,
+    service: TribalMemoryService = Depends(get_memory_service),
+) -> RecallResponse:
+    """Recall relevant memories for a query."""
+    try:
+        start_time = time.time()
+
+        results = await service.recall(
+            query=request.query,
+            limit=request.limit,
+            min_relevance=request.min_relevance,
+            tags=request.tags,
+        )
+
+        total_time_ms = (time.time() - start_time) * 1000
+
+        return RecallResponse(
+            results=[
+                RecallResultResponse(
+                    memory=_entry_to_response(r.memory),
+                    similarity_score=r.similarity_score,
+                    retrieval_time_ms=r.retrieval_time_ms,
+                )
+                for r in results
+            ],
+            query=request.query,
+            total_time_ms=total_time_ms,
+        )
+    except Exception as e:
+        # Return empty results with error info for consistency with other endpoints
+        return RecallResponse(
+            results=[],
+            query=request.query,
+            total_time_ms=0.0,
+            error=str(e),
+        )
+
+
+@router.post("/correct", response_model=StoreResponse)
+async def correct(
+    request: CorrectRequest,
+    service: TribalMemoryService = Depends(get_memory_service),
+) -> StoreResponse:
+    """Correct an existing memory."""
+    try:
+        result = await service.correct(
+            original_id=request.original_id,
+            corrected_content=request.corrected_content,
+            context=request.context,
+        )
+
+        return StoreResponse(
+            success=result.success,
+            memory_id=result.memory_id,
+            error=result.error,
+        )
+    except Exception as e:
+        return StoreResponse(success=False, error=str(e))
+
+
+@router.delete("/forget/{memory_id}", response_model=ForgetResponse)
+async def forget(
+    memory_id: str,
+    service: TribalMemoryService = Depends(get_memory_service),
+) -> ForgetResponse:
+    """Forget (delete) a specific memory. GDPR-compliant."""
+    try:
+        success = await service.forget(memory_id)
+        return ForgetResponse(success=success, memory_id=memory_id)
+    except Exception as e:
+        return ForgetResponse(success=False, memory_id=memory_id)
+
+
+@router.get("/memory/{memory_id}", response_model=MemoryEntryResponse)
+async def get_memory(
+    memory_id: str,
+    service: TribalMemoryService = Depends(get_memory_service),
+) -> MemoryEntryResponse:
+    """Get a specific memory by ID."""
+    entry = await service.get(memory_id)
+    if entry is None:
+        raise HTTPException(status_code=404, detail=f"Memory {memory_id} not found")
+    return _entry_to_response(entry)
+
+
+@router.get("/health", response_model=HealthResponse)
+async def health(
+    service: TribalMemoryService = Depends(get_memory_service),
+    instance_id: str = Depends(get_instance_id),
+) -> HealthResponse:
+    """Health check endpoint."""
+    try:
+        stats = await service.get_stats()
+        return HealthResponse(
+            status="ok",
+            instance_id=instance_id,
+            memory_count=stats.get("total_memories", 0),
+        )
+    except Exception:
+        return HealthResponse(
+            status="degraded",
+            instance_id=instance_id,
+            memory_count=0,
+        )
+
+
+@router.get("/stats", response_model=StatsResponse)
+async def stats(
+    service: TribalMemoryService = Depends(get_memory_service),
+    instance_id: str = Depends(get_instance_id),
+) -> StatsResponse:
+    """Get memory statistics."""
+    stats_data = await service.get_stats()
+    return StatsResponse(
+        total_memories=stats_data.get("total_memories", 0),
+        by_source_type=stats_data.get("by_source_type", {}),
+        by_tag=stats_data.get("by_tag", {}),
+        instance_id=instance_id,
+    )
+
+
+@router.post("/export", response_model=ExportResponse)
+async def export_memories_route(
+    request: ExportRequest,
+    service: TribalMemoryService = Depends(get_memory_service),
+) -> ExportResponse:
+    """Export memories with optional tag/date filtering."""
+    from ..portability.embedding_metadata import (
+        create_embedding_metadata,
+    )
+    from ..services.import_export import (
+        ExportFilter,
+        export_memories,
+        parse_iso_datetime,
+    )
+
+    # Validate dates
+    parsed_from, err = parse_iso_datetime(
+        request.date_from, "date_from",
+    )
+    if err:
+        return ExportResponse(success=False, error=err)
+    parsed_to, err = parse_iso_datetime(
+        request.date_to, "date_to",
+    )
+    if err:
+        return ExportResponse(success=False, error=err)
+
+    try:
+        emb = service.embedding_service
+        meta = create_embedding_metadata(
+            model_name=getattr(emb, "model", "unknown"),
+            dimensions=getattr(emb, "dimensions", 1536),
+            provider="openai",
+        )
+
+        flt = None
+        if request.tags or parsed_from or parsed_to:
+            flt = ExportFilter(
+                tags=request.tags,
+                date_from=parsed_from,
+                date_to=parsed_to,
+            )
+
+        bundle = await export_memories(
+            store=service.vector_store,
+            embedding_metadata=meta,
+            filters=flt,
+        )
+
+        return ExportResponse(
+            success=True,
+            memory_count=bundle.manifest.memory_count,
+            bundle=bundle.to_dict(),
+        )
+    except Exception as e:
+        return ExportResponse(success=False, error=str(e))
+
+
+@router.post("/import", response_model=ImportResponse)
+async def import_memories_route(
+    request: ImportRequest,
+    service: TribalMemoryService = Depends(get_memory_service),
+) -> ImportResponse:
+    """Import memories from a portable bundle."""
+    from ..portability.embedding_metadata import (
+        PortableBundle,
+        ReembeddingStrategy,
+        create_embedding_metadata,
+    )
+    from ..services.import_export import (
+        ConflictResolution,
+        import_memories,
+        validate_conflict_resolution,
+        validate_embedding_strategy,
+    )
+
+    # Validate enum params
+    err = validate_conflict_resolution(
+        request.conflict_resolution,
+    )
+    if err:
+        return ImportResponse(success=False, error=err)
+    err = validate_embedding_strategy(
+        request.embedding_strategy,
+    )
+    if err:
+        return ImportResponse(success=False, error=err)
+
+    try:
+        bundle = PortableBundle.from_dict(request.bundle)
+    except Exception as e:
+        return ImportResponse(
+            success=False, error=f"Invalid bundle: {e}",
+        )
+
+    emb = service.embedding_service
+    target_meta = create_embedding_metadata(
+        model_name=getattr(emb, "model", "unknown"),
+        dimensions=getattr(emb, "dimensions", 1536),
+        provider="openai",
+    )
+
+    cr_map = {
+        "skip": ConflictResolution.SKIP,
+        "overwrite": ConflictResolution.OVERWRITE,
+        "merge": ConflictResolution.MERGE,
+    }
+    es_map = {
+        "auto": ReembeddingStrategy.AUTO,
+        "keep": ReembeddingStrategy.KEEP,
+        "drop": ReembeddingStrategy.DROP,
+    }
+
+    try:
+        summary = await import_memories(
+            bundle=bundle,
+            store=service.vector_store,
+            target_metadata=target_meta,
+            conflict_resolution=cr_map[
+                request.conflict_resolution
+            ],
+            embedding_strategy=es_map[
+                request.embedding_strategy
+            ],
+            dry_run=request.dry_run,
+        )
+
+        return ImportResponse(
+            success=True,
+            total=summary.total,
+            imported=summary.imported,
+            skipped=summary.skipped,
+            overwritten=summary.overwritten,
+            errors=summary.errors,
+            needs_reembedding=summary.needs_reembedding,
+            dry_run=summary.dry_run,
+            duration_ms=round(summary.duration_ms, 1),
+            error_details=summary.error_details,
+        )
+    except Exception as e:
+        return ImportResponse(success=False, error=str(e))
+
+
+@router.post("/shutdown", response_model=ShutdownResponse)
+async def shutdown() -> ShutdownResponse:
+    """Graceful shutdown endpoint.
+    
+    Security note: This endpoint is localhost-only (bound to 127.0.0.1).
+    It allows local process management without authentication since only
+    processes on the same machine can reach it. For production deployments
+    with network exposure, use systemctl/signals instead of this endpoint.
+    """
+    import asyncio
+    import signal
+    import os
+
+    # Schedule shutdown after response is sent
+    asyncio.get_event_loop().call_later(
+        0.5, lambda: os.kill(os.getpid(), signal.SIGTERM)
+    )
+    return ShutdownResponse(status="shutting_down")

tribalmemory/services/__init__.py

@@ -0,0 +1,15 @@
+"""Tribal Memory service implementations."""
+
+from .embeddings import OpenAIEmbeddingService
+from .vector_store import LanceDBVectorStore, InMemoryVectorStore
+from .memory import TribalMemoryService, create_memory_service
+from .deduplication import SemanticDeduplicationService
+
+__all__ = [
+    "OpenAIEmbeddingService",
+    "LanceDBVectorStore",
+    "InMemoryVectorStore",
+    "TribalMemoryService",
+    "create_memory_service",
+    "SemanticDeduplicationService",
+]

tribalmemory/services/deduplication.py

@@ -0,0 +1,115 @@
+"""Semantic Deduplication Service."""
+
+from typing import Optional
+
+from ..interfaces import IDeduplicationService, IVectorStore, IEmbeddingService
+
+
+class SemanticDeduplicationService(IDeduplicationService):
+    """Semantic deduplication using embedding similarity."""
+    
+    def __init__(
+        self,
+        vector_store: IVectorStore,
+        embedding_service: IEmbeddingService,
+        exact_threshold: float = 0.98,
+        near_threshold: float = 0.90,
+    ):
+        self.vector_store = vector_store
+        self.embedding_service = embedding_service
+        self.exact_threshold = exact_threshold
+        self.near_threshold = near_threshold
+    
+    async def is_duplicate(
+        self,
+        content: str,
+        embedding: list[float],
+        threshold: Optional[float] = None
+    ) -> tuple[bool, Optional[str]]:
+        """Check if content is a duplicate.
+        
+        Returns:
+            Tuple of (is_duplicate, duplicate_of_id)
+        """
+        threshold = threshold or self.exact_threshold
+        
+        results = await self.vector_store.recall(
+            embedding,
+            limit=1,
+            min_similarity=threshold
+        )
+        
+        if results and results[0].similarity_score >= threshold:
+            return True, results[0].memory.id
+        
+        return False, None
+    
+    async def find_similar(
+        self,
+        content: str,
+        embedding: list[float],
+        threshold: Optional[float] = None,
+        limit: int = 10,
+    ) -> list[tuple[str, float]]:
+        """Find similar memories.
+        
+        Returns:
+            List of (memory_id, similarity_score) tuples
+        """
+        threshold = threshold or self.near_threshold
+        
+        results = await self.vector_store.recall(
+            embedding,
+            limit=limit,
+            min_similarity=threshold
+        )
+        
+        return [(r.memory.id, r.similarity_score) for r in results]
+    
+    async def get_duplicate_report(
+        self,
+        content: str,
+        embedding: list[float]
+    ) -> dict:
+        """Get detailed duplicate analysis report.
+        
+        Args:
+            content: Text content to analyze.
+            embedding: Pre-computed embedding vector for the content.
+        
+        Returns:
+            Dict with keys:
+                - is_duplicate (bool): True if above exact threshold
+                - is_near_duplicate (bool): True if above near threshold
+                - top_match (dict|None): Best matching memory with id, content preview, similarity
+                - candidates (list): Top 5 similar memories with id, similarity, content_preview
+        """
+        results = await self.vector_store.recall(
+            embedding,
+            limit=5,
+            min_similarity=0.7
+        )
+        
+        if not results:
+            return {
+                "is_duplicate": False,
+                "is_near_duplicate": False,
+                "top_match": None,
+                "candidates": []
+            }
+        
+        top = results[0]
+        
+        return {
+            "is_duplicate": top.similarity_score >= self.exact_threshold,
+            "is_near_duplicate": top.similarity_score >= self.near_threshold,
+            "top_match": {
+                "id": top.memory.id,
+                "content": top.memory.content[:200] + "..." if len(top.memory.content) > 200 else top.memory.content,
+                "similarity": top.similarity_score,
+            },
+            "candidates": [
+                {"id": r.memory.id, "similarity": r.similarity_score, "content_preview": r.memory.content[:100]}
+                for r in results
+            ],
+        }