superlocalmemory 2.8.5 → 3.0.0

package/src/superlocalmemory/server/api.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+"""
+SuperLocalMemory V3 - FastAPI API Server
+Provides REST endpoints for memory visualization and exploration.
+Uses V3 MemoryEngine for all operations.
+"""
+
+import json
+import logging
+from pathlib import Path
+from contextlib import asynccontextmanager
+from typing import Optional
+
+from fastapi import FastAPI, HTTPException, Query, Request
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import HTMLResponse
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.middleware.gzip import GZipMiddleware
+from pydantic import BaseModel
+import uvicorn
+
+from superlocalmemory.server.security_middleware import SecurityHeadersMiddleware
+
+logger = logging.getLogger("superlocalmemory.api_server")
+
+# V3 paths
+MEMORY_DIR = Path.home() / ".superlocalmemory"
+DB_PATH = MEMORY_DIR / "memory.db"
+# ui/ is at repo root, 4 levels up from src/superlocalmemory/server/api.py
+UI_DIR = Path(__file__).resolve().parent.parent.parent.parent / "ui"
+
+
+# ============================================================================
+# Request/Response Models
+# ============================================================================
+
+class SearchRequest(BaseModel):
+    query: str
+    limit: int = 10
+    min_score: float = 0.3
+
+
+class MemoryFilter(BaseModel):
+    category: Optional[str] = None
+    project_name: Optional[str] = None
+    cluster_id: Optional[int] = None
+    min_importance: Optional[int] = None
+
+
+# ============================================================================
+# V3 Engine Initialization (lifespan context)
+# ============================================================================
+
+@asynccontextmanager
+async def lifespan(application: FastAPI):
+    """Initialize V3 engine on startup, cleanup on shutdown."""
+    try:
+        from superlocalmemory.core.config import SLMConfig
+        from superlocalmemory.core.engine import MemoryEngine
+
+        config = SLMConfig.load()
+        engine = MemoryEngine(config)
+        engine.initialize()
+        application.state.engine = engine
+        application.state.config = config
+        logger.info("V3 MemoryEngine initialized: mode=%s", config.mode.value)
+    except Exception as exc:
+        logger.warning("V3 engine init failed (API will use fallback): %s", exc)
+        application.state.engine = None
+        application.state.config = None
+
+    yield
+
+    # Cleanup
+    if hasattr(application.state, 'engine') and application.state.engine:
+        application.state.engine.close()
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    application = FastAPI(
+        title="SuperLocalMemory V3 API",
+        description="V3 Memory Engine REST API",
+        version="3.0.0",
+        lifespan=lifespan,
+    )
+
+    # Middleware
+    application.add_middleware(SecurityHeadersMiddleware)
+    application.add_middleware(GZipMiddleware, minimum_size=1000)
+    application.add_middleware(
+        CORSMiddleware,
+        allow_origins=[
+            "http://localhost:8765", "http://127.0.0.1:8765",
+            "http://localhost:8417", "http://127.0.0.1:8417",
+        ],
+        allow_credentials=True,
+        allow_methods=["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
+        allow_headers=["Content-Type", "Authorization", "X-SLM-API-Key"],
+    )
+
+    # Rate limiting (graceful)
+    try:
+        from superlocalmemory.infra.rate_limiter import RateLimiter
+        _write_limiter = RateLimiter(max_requests=30, window_seconds=60)
+        _read_limiter = RateLimiter(max_requests=120, window_seconds=60)
+
+        @application.middleware("http")
+        async def rate_limit_middleware(request, call_next):
+            client_ip = request.client.host if request.client else "unknown"
+            is_write = request.method in ("POST", "PUT", "DELETE", "PATCH")
+            limiter = _write_limiter if is_write else _read_limiter
+            allowed, remaining = limiter.is_allowed(client_ip)
+            if not allowed:
+                from fastapi.responses import JSONResponse
+                return JSONResponse(
+                    status_code=429,
+                    content={"error": "Too many requests."},
+                    headers={"Retry-After": str(limiter.window_seconds)},
+                )
+            response = await call_next(request)
+            response.headers["X-RateLimit-Remaining"] = str(remaining)
+            return response
+    except (ImportError, Exception):
+        pass
+
+    # Auth middleware (graceful)
+    try:
+        from superlocalmemory.infra.auth_middleware import check_api_key
+
+        @application.middleware("http")
+        async def auth_middleware(request, call_next):
+            is_write = request.method in ("POST", "PUT", "DELETE", "PATCH")
+            headers = dict(request.headers)
+            if not check_api_key(headers, is_write=is_write):
+                from fastapi.responses import JSONResponse
+                return JSONResponse(
+                    status_code=401,
+                    content={"error": "Invalid or missing API key."},
+                )
+            response = await call_next(request)
+            return response
+    except (ImportError, Exception):
+        pass
+
+    # Mount static files
+    UI_DIR.mkdir(exist_ok=True)
+    application.mount("/static", StaticFiles(directory=str(UI_DIR)), name="static")
+
+    # ========================================================================
+    # Register Route Modules
+    # ========================================================================
+    from superlocalmemory.server.routes.memories import router as memories_router
+    from superlocalmemory.server.routes.stats import router as stats_router
+    from superlocalmemory.server.routes.profiles import router as profiles_router
+    from superlocalmemory.server.routes.backup import router as backup_router
+    from superlocalmemory.server.routes.data_io import router as data_io_router
+    from superlocalmemory.server.routes.events import router as events_router, register_event_listener
+    from superlocalmemory.server.routes.agents import router as agents_router
+    from superlocalmemory.server.routes.ws import router as ws_router, manager as ws_manager
+    from superlocalmemory.server.routes.v3_api import router as v3_router
+
+    application.include_router(memories_router)
+    application.include_router(stats_router)
+    application.include_router(profiles_router)
+    application.include_router(backup_router)
+    application.include_router(data_io_router)
+    application.include_router(events_router)
+    application.include_router(agents_router)
+    application.include_router(ws_router)
+    application.include_router(v3_router)
+
+    # Graceful optional routers
+    for _module_name in ("learning", "lifecycle", "behavioral", "compliance"):
+        try:
+            _mod = __import__(f"superlocalmemory.server.routes.{_module_name}", fromlist=["router"])
+            application.include_router(_mod.router)
+        except (ImportError, Exception):
+            pass
+
+    # Wire WebSocket manager
+    import superlocalmemory.server.routes.profiles as _profiles_mod
+    import superlocalmemory.server.routes.data_io as _data_io_mod
+    _profiles_mod.ws_manager = ws_manager
+    _data_io_mod.ws_manager = ws_manager
+
+    # ========================================================================
+    # Basic Routes
+    # ========================================================================
+
+    @application.get("/", response_class=HTMLResponse)
+    async def root():
+        """Serve main UI page."""
+        index_path = UI_DIR / "index.html"
+        if not index_path.exists():
+            return (
+                "<html><head><title>SuperLocalMemory V3</title></head>"
+                "<body style='font-family:Arial;padding:40px'>"
+                "<h1>SuperLocalMemory V3 API Server Running</h1>"
+                "<p><a href='/docs'>API Documentation</a></p>"
+                "</body></html>"
+            )
+        return index_path.read_text()
+
+    @application.get("/health")
+    async def health_check():
+        """Health check."""
+        from datetime import datetime
+        engine = application.state.engine
+        return {
+            "status": "healthy",
+            "version": "3.0.0",
+            "engine": "initialized" if engine else "unavailable",
+            "database": "connected" if DB_PATH.exists() else "missing",
+            "timestamp": datetime.now().isoformat(),
+        }
+
+    @application.on_event("startup")
+    async def startup_event():
+        register_event_listener()
+
+    return application
+
+
+app = create_app()
+
+
+# ============================================================================
+# Server Startup
+# ============================================================================
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("SuperLocalMemory V3 - API Server")
+    print("=" * 60)
+    print(f"Database: {DB_PATH}")
+    print(f"UI Directory: {UI_DIR}")
+    print("=" * 60)
+    print("\nStarting server on http://localhost:8000")
+    print("API Documentation: http://localhost:8000/docs")
+    print("\nPress Ctrl+C to stop\n")
+
+    uvicorn.run(
+        app, host="127.0.0.1", port=8000, log_level="info",
+    )

package/src/superlocalmemory/server/routes/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+# SuperLocalMemory V3 - API Routes Package

package/src/superlocalmemory/server/routes/agents.py

@@ -0,0 +1,107 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+"""SuperLocalMemory V3 - Agent Registry + Trust Routes
+ - MIT License
+
+Routes: /api/agents, /api/agents/stats, /api/trust/stats, /api/trust/signals/{agent_id}
+Uses V3 TrustScorer and core.registry.
+"""
+import logging
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, Query, Request
+
+from .helpers import DB_PATH
+
+logger = logging.getLogger("superlocalmemory.routes.agents")
+router = APIRouter()
+
+# Feature flag: V3 trust scorer
+TRUST_AVAILABLE = False
+try:
+    from superlocalmemory.trust.scorer import TrustScorer
+    TRUST_AVAILABLE = True
+except ImportError:
+    pass
+
+REGISTRY_AVAILABLE = False
+try:
+    from superlocalmemory.core.registry import AgentRegistry
+    REGISTRY_AVAILABLE = True
+except ImportError:
+    pass
+
+
+@router.get("/api/agents")
+async def get_agents(
+    request: Request,
+    protocol: Optional[str] = None,
+    limit: int = Query(50, ge=1, le=200),
+):
+    """List registered agents with optional protocol filter."""
+    if not REGISTRY_AVAILABLE:
+        return {"agents": [], "count": 0, "message": "Agent registry not available"}
+    try:
+        engine = getattr(request.app.state, "engine", None)
+        if engine and hasattr(engine, '_db'):
+            registry = AgentRegistry(engine._db)
+            agents = registry.list_agents(protocol=protocol, limit=limit)
+            stats = registry.get_stats()
+            return {"agents": agents, "count": len(agents), "stats": stats}
+        return {"agents": [], "count": 0, "message": "Engine not initialized"}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Agent registry error: {str(e)}")
+
+
+@router.get("/api/agents/stats")
+async def get_agent_stats(request: Request):
+    """Get agent registry statistics."""
+    if not REGISTRY_AVAILABLE:
+        return {"total_agents": 0, "message": "Agent registry not available"}
+    try:
+        engine = getattr(request.app.state, "engine", None)
+        if engine and hasattr(engine, '_db'):
+            registry = AgentRegistry(engine._db)
+            return registry.get_stats()
+        return {"total_agents": 0, "message": "Engine not initialized"}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Agent stats error: {str(e)}")
+
+
+@router.get("/api/trust/stats")
+async def get_trust_stats(request: Request):
+    """Get trust scoring statistics."""
+    if not TRUST_AVAILABLE:
+        return {"total_signals": 0, "message": "Trust scorer not available"}
+    try:
+        engine = getattr(request.app.state, "engine", None)
+        if engine and engine._trust_scorer:
+            scorer = engine._trust_scorer
+            return scorer.get_trust_stats()
+        return {"total_signals": 0, "message": "Trust scorer not initialized"}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Trust stats error: {str(e)}")
+
+
+@router.get("/api/trust/signals/{agent_id}")
+async def get_agent_trust_signals(
+    request: Request, agent_id: str,
+    limit: int = Query(50, ge=1, le=200),
+):
+    """Get trust signal history for a specific agent."""
+    if not TRUST_AVAILABLE:
+        return {"signals": [], "count": 0}
+    try:
+        engine = getattr(request.app.state, "engine", None)
+        if engine and engine._trust_scorer:
+            scorer = engine._trust_scorer
+            signals = scorer.get_signals(agent_id, limit=limit)
+            score = scorer.get_trust_score(agent_id)
+            return {
+                "agent_id": agent_id, "trust_score": score,
+                "signals": signals, "count": len(signals),
+            }
+        return {"agent_id": agent_id, "signals": [], "count": 0}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Trust signals error: {str(e)}")

package/src/superlocalmemory/server/routes/backup.py

@@ -0,0 +1,91 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+"""SuperLocalMemory V3 - Backup Routes
+ - MIT License
+
+Routes: /api/backup/status, /api/backup/create, /api/backup/configure, /api/backup/list
+Uses V3 infra.backup.BackupManager.
+"""
+import logging
+
+from fastapi import APIRouter, HTTPException
+
+from .helpers import BackupConfigRequest, DB_PATH, MEMORY_DIR
+
+logger = logging.getLogger("superlocalmemory.routes.backup")
+router = APIRouter()
+
+# Feature flag
+BACKUP_AVAILABLE = False
+try:
+    from superlocalmemory.infra.backup import BackupManager
+    BACKUP_AVAILABLE = True
+except ImportError:
+    pass
+
+
+def _get_backup_manager() -> "BackupManager":
+    """Get V3 backup manager instance."""
+    return BackupManager(db_path=DB_PATH, base_dir=MEMORY_DIR)
+
+
+@router.get("/api/backup/status")
+async def backup_status():
+    """Get auto-backup system status."""
+    if not BACKUP_AVAILABLE:
+        return {"status": "not_implemented", "message": "Backup module not available"}
+    try:
+        manager = _get_backup_manager()
+        return manager.get_status()
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Backup status error: {str(e)}")
+
+
+@router.post("/api/backup/create")
+async def backup_create():
+    """Create a manual backup immediately."""
+    if not BACKUP_AVAILABLE:
+        return {"success": False, "message": "Backup module not available"}
+    try:
+        manager = _get_backup_manager()
+        filename = manager.create_backup(label='manual')
+        if filename:
+            return {
+                "success": True, "filename": str(filename),
+                "message": f"Backup created: {filename}",
+                "status": manager.get_status(),
+            }
+        return {"success": False, "message": "Backup failed"}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Backup create error: {str(e)}")
+
+
+@router.post("/api/backup/configure")
+async def backup_configure(request: BackupConfigRequest):
+    """Update auto-backup configuration."""
+    if not BACKUP_AVAILABLE:
+        return {"success": False, "message": "Backup module not available"}
+    try:
+        manager = _get_backup_manager()
+        result = manager.configure(
+            interval_hours=request.interval_hours,
+            max_backups=request.max_backups,
+            enabled=request.enabled,
+        )
+        return {"success": True, "message": "Backup configuration updated", "status": result}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Backup configure error: {str(e)}")
+
+
+@router.get("/api/backup/list")
+async def backup_list():
+    """List all available backups."""
+    if not BACKUP_AVAILABLE:
+        return {"backups": [], "count": 0, "message": "Backup module not available"}
+    try:
+        manager = _get_backup_manager()
+        backups = manager.list_backups()
+        return {"backups": backups, "count": len(backups)}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Backup list error: {str(e)}")

package/src/superlocalmemory/server/routes/behavioral.py

@@ -0,0 +1,127 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under the MIT License - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+"""SuperLocalMemory V3 - Behavioral Routes
+ - MIT License
+
+Routes: /api/behavioral/status, /api/behavioral/report-outcome
+Uses V3 learning.behavioral.BehavioralPatternStore and learning.outcomes.OutcomeTracker.
+"""
+import json
+import logging
+
+from fastapi import APIRouter
+
+from .helpers import get_active_profile, MEMORY_DIR
+
+logger = logging.getLogger("superlocalmemory.routes.behavioral")
+router = APIRouter()
+
+LEARNING_DB = MEMORY_DIR / "learning.db"
+
+# Feature detection
+BEHAVIORAL_AVAILABLE = False
+try:
+    from superlocalmemory.learning.behavioral import BehavioralPatternStore
+    from superlocalmemory.learning.outcomes import OutcomeTracker
+    BEHAVIORAL_AVAILABLE = True
+except ImportError:
+    logger.info("V3 behavioral engine not available")
+
+
+@router.get("/api/behavioral/status")
+async def behavioral_status():
+    """Get behavioral learning status for active profile."""
+    if not BEHAVIORAL_AVAILABLE:
+        return {"available": False, "message": "Behavioral engine not available"}
+
+    try:
+        profile = get_active_profile()
+        db_path = str(LEARNING_DB)
+
+        # Outcomes
+        total_outcomes = 0
+        outcome_breakdown = {"success": 0, "failure": 0, "partial": 0}
+        recent_outcomes = []
+        try:
+            tracker = OutcomeTracker(db_path)
+            total_outcomes = tracker.get_outcome_count(profile=profile)
+            outcome_breakdown = tracker.get_outcome_breakdown(profile=profile)
+            recent_outcomes = tracker.get_recent_outcomes(profile=profile, limit=20)
+        except Exception as exc:
+            logger.debug("outcome tracker: %s", exc)
+
+        # Patterns
+        patterns = []
+        cross_project_transfers = 0
+        try:
+            store = BehavioralPatternStore(db_path)
+            patterns = store.get_patterns(profile=profile)
+            cross_project_transfers = store.get_cross_project_count(profile=profile)
+        except Exception as exc:
+            logger.debug("pattern store: %s", exc)
+
+        return {
+            "available": True,
+            "active_profile": profile,
+            "total_outcomes": total_outcomes,
+            "outcome_breakdown": outcome_breakdown,
+            "patterns": patterns,
+            "cross_project_transfers": cross_project_transfers,
+            "recent_outcomes": recent_outcomes,
+        }
+    except Exception as e:
+        logger.error("behavioral_status error: %s", e)
+        return {"available": False, "error": str(e)}
+
+
+@router.post("/api/behavioral/report-outcome")
+async def report_outcome(data: dict):
+    """Record an action outcome for behavioral learning.
+
+    Body: {
+        memory_ids: [str, ...],
+        outcome: "success" | "failure" | "partial",
+        action_type: str (optional),
+        context: str (optional)
+    }
+    """
+    if not BEHAVIORAL_AVAILABLE:
+        return {"success": False, "error": "Behavioral engine not available"}
+
+    memory_ids = data.get('memory_ids')
+    outcome = data.get('outcome')
+    action_type = data.get('action_type', 'other')
+    context_note = data.get('context', '')
+
+    if not memory_ids or not isinstance(memory_ids, list):
+        return {"success": False, "error": "memory_ids must be a non-empty list"}
+
+    valid_outcomes = ("success", "failure", "partial")
+    if outcome not in valid_outcomes:
+        return {"success": False, "error": f"outcome must be one of: {valid_outcomes}"}
+
+    try:
+        profile = get_active_profile()
+        tracker = OutcomeTracker(str(LEARNING_DB))
+
+        context_dict = {"note": context_note} if context_note else {}
+        row_id = tracker.record_outcome(
+            memory_ids=memory_ids,
+            outcome=outcome,
+            action_type=action_type,
+            context=context_dict,
+            project=profile,
+        )
+
+        if row_id is None:
+            return {"success": False, "error": "Failed to record outcome"}
+
+        return {
+            "success": True, "outcome_id": row_id,
+            "active_profile": profile,
+            "message": f"Recorded {outcome} outcome for {len(memory_ids)} memories",
+        }
+    except Exception as e:
+        logger.error("report_outcome error: %s", e)
+        return {"success": False, "error": str(e)}