memgentic-api 0.4.4__py3-none-any.whl

memgentic_api/__init__.py

@@ -0,0 +1,3 @@
+"""Memgentic REST API — search, manage, and stream memories."""
+
+__version__ = "0.1.0"

memgentic_api/auth.py

@@ -0,0 +1,33 @@
+"""Optional API key authentication for local Memgentic instances.
+
+When MEMGENTIC_API_KEY is set in the environment, all API requests must include
+a matching X-API-Key header. When not set, the API is open (local mode).
+"""
+
+from __future__ import annotations
+
+import hmac
+
+from fastapi import HTTPException, Security
+from fastapi.security import APIKeyHeader
+from memgentic.config import settings
+
+_api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
+
+
+async def verify_api_key(
+    api_key: str | None = Security(_api_key_header),
+) -> None:
+    """Verify API key if MEMGENTIC_API_KEY is configured.
+
+    If no API key is configured, all requests are allowed (local mode).
+    If configured, requests must include a matching X-API-Key header.
+    """
+    if not settings.api_key:
+        return  # No API key configured — local open mode
+
+    if not api_key:
+        raise HTTPException(status_code=401, detail="API key required")
+
+    if not hmac.compare_digest(api_key, settings.api_key):
+        raise HTTPException(status_code=401, detail="Invalid API key")

memgentic_api/deps.py

@@ -0,0 +1,42 @@
+"""FastAPI dependency injection for Memgentic stores and services."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Depends, Request
+from memgentic.processing.embedder import Embedder
+from memgentic.processing.pipeline import IngestionPipeline
+from memgentic.storage.metadata import MetadataStore
+from memgentic.storage.vectors import VectorStore
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+
+limiter = Limiter(key_func=get_remote_address)
+
+
+def get_metadata_store(request: Request) -> MetadataStore:
+    """Get the shared MetadataStore from app state."""
+    return request.app.state.metadata_store
+
+
+def get_vector_store(request: Request) -> VectorStore:
+    """Get the shared VectorStore from app state."""
+    return request.app.state.vector_store
+
+
+def get_embedder(request: Request) -> Embedder:
+    """Get the shared Embedder from app state."""
+    return request.app.state.embedder
+
+
+def get_pipeline(request: Request) -> IngestionPipeline:
+    """Get the shared IngestionPipeline from app state."""
+    return request.app.state.pipeline
+
+
+# Type aliases for cleaner route signatures
+MetadataStoreDep = Annotated[MetadataStore, Depends(get_metadata_store)]
+VectorStoreDep = Annotated[VectorStore, Depends(get_vector_store)]
+EmbedderDep = Annotated[Embedder, Depends(get_embedder)]
+PipelineDep = Annotated[IngestionPipeline, Depends(get_pipeline)]

memgentic_api/main.py

@@ -0,0 +1,291 @@
+"""Memgentic REST API — FastAPI application with lifespan management."""
+
+from __future__ import annotations
+
+import hashlib
+from contextlib import asynccontextmanager
+from email.utils import formatdate, parsedate_to_datetime
+
+import structlog
+from fastapi import Depends, FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from memgentic.config import settings
+from slowapi import _rate_limit_exceeded_handler
+from slowapi.errors import RateLimitExceeded
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import Response
+
+from memgentic_api.auth import verify_api_key
+from memgentic_api.deps import limiter
+from memgentic_api.routes import (
+    collections,
+    graph,
+    import_export,
+    ingestion,
+    memories,
+    skills,
+    sources,
+    stats,
+    uploads,
+    websocket,
+)
+
+logger = structlog.get_logger()
+
+
+class SecurityHeadersMiddleware(BaseHTTPMiddleware):
+    """Add security headers to all responses."""
+
+    async def dispatch(self, request, call_next):
+        response = await call_next(request)
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["X-XSS-Protection"] = "1; mode=block"
+        response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+        response.headers["Content-Security-Policy"] = (
+            "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; "
+            "img-src 'self' data:; connect-src 'self' ws: wss:"
+        )
+        response.headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains"
+        response.headers["Permissions-Policy"] = "camera=(), microphone=(), geolocation=()"
+        return response
+
+
+class RequestSizeLimitMiddleware(BaseHTTPMiddleware):
+    """Reject requests with bodies larger than MAX_BODY_SIZE."""
+
+    MAX_BODY_SIZE = 10 * 1024 * 1024  # 10MB
+
+    async def dispatch(self, request, call_next):
+        if request.headers.get("content-length"):
+            content_length = int(request.headers["content-length"])
+            if content_length > self.MAX_BODY_SIZE:
+                return JSONResponse(
+                    status_code=413,
+                    content={"detail": "Request body too large"},
+                )
+        return await call_next(request)
+
+
+# Path patterns for Cache-Control max-age values
+_STATS_PATHS = ("/api/v1/stats", "/api/v1/metrics", "/api/v1/sources", "/api/v1/health/detailed")
+_LIST_PATHS = ("/api/v1/memories",)
+
+
+class CachingHeadersMiddleware(BaseHTTPMiddleware):
+    """Add ETag, Cache-Control, and Last-Modified headers to GET responses.
+
+    Also handles conditional requests: If-None-Match (ETag) and If-Modified-Since.
+    Returns 304 Not Modified when the content has not changed.
+    """
+
+    async def dispatch(self, request, call_next):
+        # Only apply caching to GET requests
+        if request.method != "GET":
+            return await call_next(request)
+
+        # Skip WebSocket upgrade requests
+        if request.headers.get("upgrade", "").lower() == "websocket":
+            return await call_next(request)
+
+        response = await call_next(request)
+
+        # Only cache successful JSON responses
+        if response.status_code != 200:
+            return response
+
+        # Read body for ETag computation
+        body_chunks: list[bytes] = []
+        async for chunk in response.body_iterator:
+            body_chunks.append(chunk if isinstance(chunk, bytes) else chunk.encode())
+        body = b"".join(body_chunks)
+
+        # Generate ETag from content hash
+        etag = '"' + hashlib.md5(body).hexdigest() + '"'  # noqa: S324
+
+        # Check If-None-Match
+        if_none_match = request.headers.get("if-none-match")
+        if if_none_match and if_none_match == etag:
+            return Response(status_code=304, headers={"ETag": etag})
+
+        # Determine Cache-Control max-age based on path
+        path = request.url.path
+        if any(path.startswith(p) for p in _STATS_PATHS):
+            max_age = 300
+        elif any(path.startswith(p) for p in _LIST_PATHS):
+            max_age = 60
+        else:
+            max_age = 60  # Default for other GET endpoints
+
+        # Build new response with caching headers
+        new_response = Response(
+            content=body,
+            status_code=response.status_code,
+            media_type=response.media_type,
+        )
+        # Copy original headers
+        for key, value in response.headers.items():
+            if key.lower() not in ("content-length", "content-encoding", "transfer-encoding"):
+                new_response.headers[key] = value
+
+        new_response.headers["ETag"] = etag
+        new_response.headers["Cache-Control"] = f"private, max-age={max_age}"
+        new_response.headers["Last-Modified"] = formatdate(usegmt=True)
+
+        # Check If-Modified-Since
+        if_modified_since = request.headers.get("if-modified-since")
+        if if_modified_since:
+            try:
+                since_dt = parsedate_to_datetime(if_modified_since)
+                # For simplicity, compare against "now" — content was just generated
+                # A 304 is only returned when the ETag matches (above)
+                _ = since_dt  # placeholder for future last-modified tracking
+            except (TypeError, ValueError):
+                pass
+
+        return new_response
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Initialize stores on startup, close on shutdown."""
+    from memgentic.processing.embedder import Embedder
+    from memgentic.processing.pipeline import IngestionPipeline
+    from memgentic.storage.metadata import MetadataStore
+    from memgentic.storage.vectors import VectorStore
+
+    metadata_store = MetadataStore(settings.sqlite_path)
+    vector_store = VectorStore(settings)
+    embedder = Embedder(settings)
+
+    # Optional: intelligence package for LLM client and knowledge graph
+    llm_client = None
+    graph = None
+    try:
+        from memgentic.processing.llm import LLMClient
+
+        llm_client = LLMClient(settings)
+    except ImportError:
+        pass
+
+    try:
+        from memgentic.graph.knowledge import create_knowledge_graph
+
+        graph = create_knowledge_graph(settings.graph_path)
+        await graph.load()
+        logger.info("api.intelligence_loaded", graph_nodes=graph.node_count)
+    except ImportError:
+        logger.info(
+            "api.no_intelligence",
+            msg="Intelligence extras not installed. Graph and advanced search unavailable.",
+        )
+
+    pipeline = IngestionPipeline(
+        settings,
+        metadata_store,
+        vector_store,
+        embedder,
+        llm_client=llm_client,
+        graph=graph,
+    )
+
+    await metadata_store.initialize()
+    await vector_store.initialize()
+
+    app.state.metadata_store = metadata_store
+    app.state.vector_store = vector_store
+    app.state.embedder = embedder
+    app.state.pipeline = pipeline
+    app.state.graph = graph
+
+    logger.info("api.startup", storage=settings.storage_backend.value)
+
+    yield
+
+    if graph:
+        await graph.save()
+    await embedder.close()
+    await metadata_store.close()
+    await vector_store.close()
+    logger.info("api.shutdown")
+
+
+app = FastAPI(
+    title="Memgentic API",
+    description="Universal AI Memory Layer — search, manage, and stream memories",
+    version="0.1.0",
+    lifespan=lifespan,
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+app.state.limiter = limiter
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+# Security middlewares — order matters (Starlette processes outermost first)
+# 1. Security headers on all responses
+app.add_middleware(SecurityHeadersMiddleware)
+
+# 2. CORS — allow dashboard and local dev
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:3000", "http://localhost:3001", "https://app.memgentic.dev"],
+    allow_credentials=True,
+    allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+    allow_headers=["Content-Type", "Authorization", "X-API-Key", "If-None-Match"],
+)
+
+# 3. Request size limit — reject oversized payloads early
+app.add_middleware(RequestSizeLimitMiddleware)
+
+# 4. HTTP caching headers (ETag, Cache-Control) for GET endpoints
+app.add_middleware(CachingHeadersMiddleware)
+
+# Mount routers — all require API key when MEMGENTIC_API_KEY is set
+_auth = [Depends(verify_api_key)]
+app.include_router(memories.router, prefix="/api/v1", tags=["memories"], dependencies=_auth)
+app.include_router(sources.router, prefix="/api/v1", tags=["sources"], dependencies=_auth)
+app.include_router(stats.router, prefix="/api/v1", tags=["stats"], dependencies=_auth)
+app.include_router(
+    import_export.router, prefix="/api/v1", tags=["import/export"], dependencies=_auth
+)
+app.include_router(graph.router, prefix="/api/v1", tags=["graph"], dependencies=_auth)
+app.include_router(collections.router, prefix="/api/v1", tags=["collections"], dependencies=_auth)
+app.include_router(uploads.router, prefix="/api/v1", tags=["uploads"], dependencies=_auth)
+app.include_router(skills.router, prefix="/api/v1", tags=["skills"], dependencies=_auth)
+app.include_router(ingestion.router, prefix="/api/v1", tags=["ingestion"], dependencies=_auth)
+
+# WebSocket — no auth dependency (clients authenticate via initial message if needed)
+app.include_router(websocket.router, prefix="/api/v1", tags=["websocket"])
+
+
+@app.get("/api/v1/health", tags=["health"])
+async def health_check():
+    """Health check endpoint — verifies storage connectivity."""
+    checks: dict[str, str] = {}
+
+    # Check SQLite
+    try:
+        metadata = app.state.metadata_store
+        await metadata.get_total_count()
+        checks["sqlite"] = "ok"
+    except Exception:
+        checks["sqlite"] = "error"
+
+    # Check vector store
+    try:
+        vectors = app.state.vector_store
+        await vectors.get_collection_info()
+        checks["vectors"] = "ok"
+    except Exception:
+        checks["vectors"] = "error"
+
+    overall = "ok" if all(v == "ok" for v in checks.values()) else "degraded"
+
+    return {
+        "status": overall,
+        "version": "0.1.0",
+        "storage_backend": settings.storage_backend.value,
+        "checks": checks,
+    }

memgentic_api/routes/collections.py

@@ -0,0 +1,242 @@
+"""Collection CRUD and membership endpoints."""
+
+from __future__ import annotations
+
+import structlog
+from fastapi import APIRouter, HTTPException, Query, Request
+from memgentic.config import settings
+from memgentic.events import EventType, MemgenticEvent, event_bus
+from memgentic.models import Collection
+
+from memgentic_api.deps import MetadataStoreDep, limiter
+from memgentic_api.schemas import (
+    AddMemoryToCollectionRequest,
+    CollectionListResponse,
+    CollectionResponse,
+    CreateCollectionRequest,
+    MemoryListResponse,
+    MemoryResponse,
+    SourceResponse,
+    UpdateCollectionRequest,
+)
+
+logger = structlog.get_logger()
+router = APIRouter()
+
+
+def _collection_to_response(collection: Collection, memory_count: int = 0) -> CollectionResponse:
+    """Convert a core Collection model to an API CollectionResponse."""
+    return CollectionResponse(
+        id=collection.id,
+        user_id=collection.user_id,
+        name=collection.name,
+        description=collection.description,
+        color=collection.color,
+        icon=collection.icon,
+        position=collection.position,
+        memory_count=memory_count,
+        created_at=collection.created_at,
+        updated_at=collection.updated_at,
+    )
+
+
+def _memory_to_response(memory) -> MemoryResponse:
+    """Convert a core Memory model to an API MemoryResponse."""
+    return MemoryResponse(
+        id=memory.id,
+        content=memory.content,
+        content_type=memory.content_type.value,
+        platform=memory.source.platform.value,
+        topics=memory.topics,
+        entities=memory.entities,
+        confidence=memory.confidence,
+        status=memory.status.value,
+        created_at=memory.created_at,
+        last_accessed=memory.last_accessed,
+        access_count=memory.access_count,
+        source=SourceResponse(
+            platform=memory.source.platform.value,
+            platform_version=memory.source.platform_version,
+            session_id=memory.source.session_id,
+            session_title=memory.source.session_title,
+            capture_method=memory.source.capture_method.value,
+            original_timestamp=memory.source.original_timestamp,
+            file_path=memory.source.file_path,
+        ),
+        is_pinned=memory.is_pinned,
+        pinned_at=memory.pinned_at,
+    )
+
+
+# --- Collection CRUD ---
+
+
+@router.get("/collections")
+@limiter.limit(lambda: f"{settings.rate_limit_default}/minute")
+async def list_collections(
+    request: Request,
+    metadata_store: MetadataStoreDep,
+) -> CollectionListResponse:
+    """List all collections with memory counts."""
+    collections = await metadata_store.get_collections()
+    responses = []
+    for coll in collections:
+        count = await metadata_store.get_collection_memory_count(coll.id)
+        responses.append(_collection_to_response(coll, memory_count=count))
+    return CollectionListResponse(collections=responses, total=len(responses))
+
+
+@router.post("/collections", status_code=201)
+@limiter.limit(lambda: f"{settings.rate_limit_default}/minute")
+async def create_collection(
+    request: Request,
+    body: CreateCollectionRequest,
+    metadata_store: MetadataStoreDep,
+) -> CollectionResponse:
+    """Create a new collection."""
+    collection = Collection(
+        name=body.name,
+        description=body.description,
+        color=body.color,
+        icon=body.icon,
+    )
+    await metadata_store.create_collection(collection)
+    logger.info("collections.created", id=collection.id, name=collection.name)
+    await event_bus.emit(
+        MemgenticEvent(
+            type=EventType.COLLECTION_CREATED,
+            data={
+                "id": collection.id,
+                "name": collection.name,
+            },
+        )
+    )
+    return _collection_to_response(collection, memory_count=0)
+
+
+@router.patch("/collections/{collection_id}")
+@limiter.limit(lambda: f"{settings.rate_limit_default}/minute")
+async def update_collection(
+    request: Request,
+    collection_id: str,
+    body: UpdateCollectionRequest,
+    metadata_store: MetadataStoreDep,
+) -> CollectionResponse:
+    """Update a collection's metadata."""
+    existing = await metadata_store.get_collection(collection_id)
+    if not existing:
+        raise HTTPException(status_code=404, detail="Collection not found")
+
+    update_data = body.model_dump(exclude_unset=True)
+    if update_data:
+        await metadata_store.update_collection(collection_id, **update_data)
+
+    updated = await metadata_store.get_collection(collection_id)
+    count = await metadata_store.get_collection_memory_count(collection_id)
+    await event_bus.emit(
+        MemgenticEvent(
+            type=EventType.COLLECTION_UPDATED,
+            data={
+                "id": collection_id,
+                "name": updated.name,
+            },
+        )
+    )
+    return _collection_to_response(updated, memory_count=count)
+
+
+@router.delete("/collections/{collection_id}", status_code=204)
+@limiter.limit(lambda: f"{settings.rate_limit_default}/minute")
+async def delete_collection(
+    request: Request,
+    collection_id: str,
+    metadata_store: MetadataStoreDep,
+) -> None:
+    """Delete a collection and its membership links."""
+    existing = await metadata_store.get_collection(collection_id)
+    if not existing:
+        raise HTTPException(status_code=404, detail="Collection not found")
+    await metadata_store.delete_collection(collection_id)
+    logger.info("collections.deleted", id=collection_id)
+    await event_bus.emit(
+        MemgenticEvent(
+            type=EventType.COLLECTION_DELETED,
+            data={"id": collection_id},
+        )
+    )
+
+
+# --- Collection Membership ---
+
+
+@router.get("/collections/{collection_id}/memories")
+@limiter.limit(lambda: f"{settings.rate_limit_default}/minute")
+async def list_collection_memories(
+    request: Request,
+    collection_id: str,
+    metadata_store: MetadataStoreDep,
+    page: int = Query(default=1, ge=1),
+    page_size: int = Query(default=20, ge=1, le=100),
+) -> MemoryListResponse:
+    """List memories in a collection."""
+    existing = await metadata_store.get_collection(collection_id)
+    if not existing:
+        raise HTTPException(status_code=404, detail="Collection not found")
+
+    offset = (page - 1) * page_size
+    memories = await metadata_store.get_collection_memories(
+        collection_id, limit=page_size, offset=offset
+    )
+    total = await metadata_store.get_collection_memory_count(collection_id)
+    return MemoryListResponse(
+        memories=[_memory_to_response(m) for m in memories],
+        total=total,
+        page=page,
+        page_size=page_size,
+    )
+
+
+@router.post("/collections/{collection_id}/memories", status_code=201)
+@limiter.limit(lambda: f"{settings.rate_limit_default}/minute")
+async def add_memory_to_collection(
+    request: Request,
+    collection_id: str,
+    body: AddMemoryToCollectionRequest,
+    metadata_store: MetadataStoreDep,
+) -> dict:
+    """Add a memory to a collection."""
+    existing = await metadata_store.get_collection(collection_id)
+    if not existing:
+        raise HTTPException(status_code=404, detail="Collection not found")
+
+    memory = await metadata_store.get_memory(body.memory_id)
+    if not memory:
+        raise HTTPException(status_code=404, detail="Memory not found")
+
+    await metadata_store.add_memory_to_collection(collection_id, body.memory_id)
+    logger.info(
+        "collections.memory_added",
+        collection_id=collection_id,
+        memory_id=body.memory_id,
+    )
+    return {"status": "added", "collection_id": collection_id, "memory_id": body.memory_id}
+
+
+@router.delete("/collections/{collection_id}/memories/{memory_id}", status_code=204)
+@limiter.limit(lambda: f"{settings.rate_limit_default}/minute")
+async def remove_memory_from_collection(
+    request: Request,
+    collection_id: str,
+    memory_id: str,
+    metadata_store: MetadataStoreDep,
+) -> None:
+    """Remove a memory from a collection."""
+    existing = await metadata_store.get_collection(collection_id)
+    if not existing:
+        raise HTTPException(status_code=404, detail="Collection not found")
+    await metadata_store.remove_memory_from_collection(collection_id, memory_id)
+    logger.info(
+        "collections.memory_removed",
+        collection_id=collection_id,
+        memory_id=memory_id,
+    )

memgentic_api/routes/graph.py

@@ -0,0 +1,50 @@
+"""Knowledge graph endpoints — nodes, edges, and neighbor queries."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from memgentic.config import settings
+
+from memgentic_api.deps import limiter
+
+router = APIRouter()
+
+
+def get_graph(request: Request) -> Any:
+    """Get the shared KnowledgeGraph from app state (requires intelligence extras)."""
+    graph = getattr(request.app.state, "graph", None)
+    if graph is None:
+        raise HTTPException(
+            status_code=501,
+            detail="Knowledge graph requires intelligence extras. "
+            "Install with: pip install mneme-core[intelligence]",
+        )
+    return graph
+
+
+GraphDep = Annotated[Any, Depends(get_graph)]
+
+
+@router.get("/graph")
+@limiter.limit(lambda: f"{settings.rate_limit_default}/minute")
+async def get_graph_data(
+    request: Request,
+    graph: GraphDep,
+    min_weight: int = Query(default=1, ge=1, description="Minimum edge weight to include"),
+) -> dict:
+    """Export full graph (nodes + edges) for dashboard visualization."""
+    return await graph.get_graph_data(min_weight=min_weight)
+
+
+@router.get("/graph/{entity}")
+@limiter.limit(lambda: f"{settings.rate_limit_default}/minute")
+async def get_graph_neighbors(
+    request: Request,
+    entity: str,
+    graph: GraphDep,
+    depth: int = Query(default=2, ge=1, le=5, description="BFS depth"),
+) -> dict:
+    """Get neighbors of an entity up to *depth* hops."""
+    return await graph.query_neighbors(entity, depth=depth)