superlocalmemory 3.7.8 → 3.8.1

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

@@ -6,45 +6,117 @@
 
 from __future__ import annotations
 
-from fastapi import APIRouter, HTTPException, Request, Query
+from fastapi import APIRouter, HTTPException, Query, Request
 
-from .helpers import require_engine
+from .helpers import get_active_profile, require_engine
 
 router = APIRouter(prefix="/api/entity", tags=["entity"])
 
 
+def _list_entities_sql(where_sql: str) -> str:
+    """Build the page-first entity query after ``where_sql`` is parameterized."""
+    return f"""
+        WITH page_entities AS MATERIALIZED (
+            SELECT ce.entity_id, ce.profile_id, ce.canonical_name,
+                   ce.entity_type, ce.fact_count, ce.first_seen, ce.last_seen
+            FROM canonical_entities ce
+            WHERE {where_sql}
+            ORDER BY ce.fact_count DESC, ce.entity_id ASC
+            LIMIT ? OFFSET ?
+        ),
+        ranked_profiles AS MATERIALIZED (
+            SELECT ep.*,
+                   ROW_NUMBER() OVER (
+                       PARTITION BY ep.entity_id, ep.profile_id
+                       ORDER BY COALESCE(ep.last_compiled_at, '') DESC,
+                                ep.project_name COLLATE NOCASE ASC,
+                                ep.rowid ASC
+                   ) AS summary_rank
+            FROM entity_profiles ep
+            JOIN page_entities page
+              ON page.entity_id = ep.entity_id
+             AND page.profile_id = ep.profile_id
+            WHERE ep.profile_id = ?
+        )
+        SELECT ce.entity_id, ce.canonical_name, ce.entity_type,
+               ce.fact_count, ce.first_seen, ce.last_seen,
+               ep.knowledge_summary, ep.compiled_truth,
+               ep.compilation_confidence, ep.last_compiled_at
+        FROM page_entities ce
+        LEFT JOIN ranked_profiles ep
+          ON ce.entity_id = ep.entity_id
+         AND ep.profile_id = ce.profile_id
+         AND ep.summary_rank = 1
+        ORDER BY ce.fact_count DESC, ce.entity_id ASC
+    """
+
+
+def _require_read(request: Request, profile: str) -> None:
+    """Authorize entity metadata access for the explicitly requested profile."""
+    from superlocalmemory.access.rbac import Permission
+    from superlocalmemory.server.rbac_enforce import require_permission
+
+    require_permission(request, Permission.READ, profile=profile)
+
+
+def _require_manage(request: Request, profile: str) -> None:
+    """Authorize entity recompilation for the explicitly requested profile."""
+    from superlocalmemory.server.rbac_enforce import require_manage
+
+    require_manage(request, profile=profile)
+
+
 @router.get("/list")
-async def list_entities(
+def list_entities(
     request: Request,
-    profile: str = Query(default="default"),
+    profile: str | None = Query(default=None),
+    entity_type: str | None = Query(default=None, alias="type", max_length=80),
+    search: str | None = Query(default=None, max_length=200),
     limit: int = Query(default=100, ge=1, le=1000),
     offset: int = Query(default=0, ge=0),
 ):
-    """List all entities with basic info (canonical name, type, fact count)."""
+    """List a profile's entities, filtering before count and pagination."""
     engine = require_engine(request)
+    # Default to the ACTIVE profile (request runtime truth), never the literal
+    # "default" — otherwise every profile sees the default profile's entities.
+    profile = profile or get_active_profile()
+    _require_read(request, profile)
 
     import sqlite3
-    import json
     conn = sqlite3.connect(str(engine._config.db_path))
     conn.row_factory = sqlite3.Row
     try:
+        where = ["ce.profile_id = ?"]
+        params: list[object] = [profile]
+        if entity_type and entity_type.lower() != "all":
+            where.append("ce.entity_type = ? COLLATE NOCASE")
+            params.append(entity_type.strip().lower())
+        if search and search.strip():
+            escaped = (search.strip().lower().replace("\\", "\\\\")
+                       .replace("%", "\\%").replace("_", "\\_"))
+            where.append(
+                "(LOWER(ce.canonical_name) LIKE ? ESCAPE '\\' "
+                "OR LOWER(COALESCE(ce.entity_type, 'unknown')) LIKE ? ESCAPE '\\' "
+                "OR EXISTS ("
+                "SELECT 1 FROM entity_profiles eps "
+                "WHERE eps.entity_id = ce.entity_id "
+                "AND eps.profile_id = ce.profile_id "
+                "AND LOWER(COALESCE(eps.knowledge_summary, '')) "
+                "LIKE ? ESCAPE '\\'))"
+            )
+            params.extend([f"%{escaped}%"] * 3)
+        where_sql = " AND ".join(where)
+
         total = conn.execute(
-            "SELECT COUNT(*) FROM canonical_entities WHERE profile_id = ?",
-            (profile,),
+            "SELECT COUNT(*) FROM canonical_entities ce "
+            f"WHERE {where_sql}",
+            params,
         ).fetchone()[0]
 
-        rows = conn.execute("""
-            SELECT ce.entity_id, ce.canonical_name, ce.entity_type,
-                   ce.fact_count, ce.first_seen, ce.last_seen,
-                   ep.knowledge_summary, ep.compiled_truth,
-                   ep.compilation_confidence, ep.last_compiled_at
-            FROM canonical_entities ce
-            LEFT JOIN entity_profiles ep
-              ON ce.entity_id = ep.entity_id AND ep.profile_id = ce.profile_id
-            WHERE ce.profile_id = ?
-            ORDER BY ce.fact_count DESC
-            LIMIT ? OFFSET ?
-        """, (profile, limit, offset)).fetchall()
+        rows = conn.execute(
+            _list_entities_sql(where_sql),
+            [*params, limit, offset, profile],
+        ).fetchall()
 
         entities = []
         for r in rows:
@@ -62,23 +134,31 @@ async def list_entities(
                 "last_compiled_at": r["last_compiled_at"],
             })
 
-        return {"entities": entities, "total": total, "limit": limit, "offset": offset}
+        return {
+            "entities": entities,
+            "total": total,
+            "limit": limit,
+            "offset": offset,
+            "has_more": offset + limit < total,
+        }
     finally:
         conn.close()
 
 
 @router.get("/{entity_name}")
-async def get_entity(
+def get_entity(
     entity_name: str,
     request: Request,
-    profile: str = Query(default="default"),
+    profile: str | None = Query(default=None),
     project: str = Query(default=""),
 ):
     """Get compiled truth + timeline for an entity."""
     engine = require_engine(request)
+    profile = profile or get_active_profile()
+    _require_read(request, profile)
 
-    import sqlite3
     import json
+    import sqlite3
     conn = sqlite3.connect(str(engine._config.db_path))
     conn.row_factory = sqlite3.Row
     try:
@@ -112,14 +192,16 @@ async def get_entity(
 
 
 @router.post("/{entity_name}/recompile")
-async def recompile_entity(
+def recompile_entity(
     entity_name: str,
     request: Request,
-    profile: str = Query(default="default"),
+    profile: str | None = Query(default=None),
     project: str = Query(default=""),
 ):
     """Force immediate recompilation of an entity."""
     engine = require_engine(request)
+    profile = profile or get_active_profile()
+    _require_manage(request, profile)
 
     import sqlite3
     conn = sqlite3.connect(str(engine._config.db_path))

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

@@ -17,7 +17,7 @@ from datetime import datetime, timezone
 from fastapi import APIRouter, HTTPException, Query
 from fastapi.responses import StreamingResponse
 
-from .helpers import DB_PATH
+from .helpers import DB_PATH, get_active_profile
 
 logger = logging.getLogger("superlocalmemory.routes.events")
 router = APIRouter()
@@ -71,6 +71,11 @@ async def event_stream(
 
     import asyncio
 
+    # Scope this stream to the profile active at connect time. The dashboard
+    # opens a fresh stream after a profile switch, so a connection only ever
+    # surfaces ONE profile's events — never another profile's (GDPR).
+    active_profile = get_active_profile()
+
     client_queue = _queue.Queue(maxsize=100)
     with _sse_queues_lock:
         _sse_queues.add(client_queue)
@@ -86,6 +91,7 @@ async def event_stream(
                     bus = EventBus.get_instance(DB_PATH)
                     missed = bus.get_recent_events(
                         since_id=last_event_id, limit=50, event_type=event_type,
+                        profile_id=active_profile,
                     )
                     for evt in missed:
                         data = json.dumps(evt)
@@ -96,7 +102,9 @@ async def event_stream(
             else:
                 try:
                     bus = EventBus.get_instance(DB_PATH)
-                    recent = bus.get_recent_events(limit=1)
+                    recent = bus.get_recent_events(
+                        limit=1, profile_id=active_profile,
+                    )
                     if recent:
                         last_db_id = recent[-1].get('id', 0)
                 except Exception:
@@ -110,6 +118,9 @@ async def event_stream(
                         event = client_queue.get_nowait()
                         if event_type and event.get("event_type") != event_type:
                             continue
+                        # Profile isolation: never forward another profile's event.
+                        if event.get("profile_id", "default") != active_profile:
+                            continue
                         data = json.dumps(event)
                         event_id = event.get("id", event.get("seq", ""))
                         yield f"id: {event_id}\nevent: {event['event_type']}\ndata: {data}\n\n"
@@ -126,6 +137,7 @@ async def event_stream(
                         bus = EventBus.get_instance(DB_PATH)
                         new_events = bus.get_recent_events(
                             since_id=last_db_id, limit=10, event_type=event_type,
+                            profile_id=active_profile,
                         )
                         for evt in new_events:
                             data = json.dumps(evt)
@@ -162,13 +174,16 @@ async def get_events(
         return {"events": [], "count": 0, "message": "Event Bus not available"}
     try:
         bus = EventBus.get_instance(DB_PATH)
+        active_profile = get_active_profile()
         events = bus.get_recent_events(
             since_id=since_id, limit=limit, event_type=event_type,
+            profile_id=active_profile,
         )
-        stats = bus.get_event_stats()
+        stats = bus.get_event_stats(profile_id=active_profile)
         return {"events": events, "count": len(events), "stats": stats}
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Event retrieval error: {str(e)}")
+    except Exception:
+        logger.exception("events route error")
+        raise HTTPException(status_code=500, detail="Event retrieval error")
 
 
 @router.get("/api/events/stats")
@@ -178,6 +193,7 @@ async def get_event_stats():
         return {"total_events": 0, "message": "Event Bus not available"}
     try:
         bus = EventBus.get_instance(DB_PATH)
-        return bus.get_event_stats()
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Event stats error: {str(e)}")
+        return bus.get_event_stats(profile_id=get_active_profile())
+    except Exception:
+        logger.exception("events route error")
+        raise HTTPException(status_code=500, detail="Event stats error")

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

@@ -8,46 +8,89 @@ Routes: /api/evolution/status, /api/evolution/enable, /api/evolution/run
 """
 
 import logging
-from pathlib import Path
+from types import SimpleNamespace
+from typing import Optional
 
-from fastapi import APIRouter
+from fastapi import APIRouter, Request
+from pydantic import BaseModel
 
-from .helpers import get_active_profile, MEMORY_DIR
+from superlocalmemory.server.config_file import read_config, update_config
+
+from .helpers import MEMORY_DIR, get_active_profile
 
 logger = logging.getLogger("superlocalmemory.routes.evolution")
 router = APIRouter()
 
 
+def _require_read(request: Request) -> None:
+    """Guard evolution telemetry with READ on the active profile."""
+    from superlocalmemory.access.rbac import Permission
+    from superlocalmemory.server.rbac_enforce import require_permission
+
+    require_permission(request, Permission.READ, profile=get_active_profile())
+
+
+def _require_manage(request: Request) -> None:
+    """Guard evolution mutations with the same RBAC boundary as v3 settings."""
+    from superlocalmemory.server.rbac_enforce import require_manage
+
+    require_manage(request)
+
+
+def _read_evolution_config() -> dict:
+    """Read one process-safe evolution config snapshot."""
+    return dict(read_config(MEMORY_DIR / "config.json").get("evolution", {}))
+
+
+def _update_evolution_config(update) -> dict:
+    """Atomically update evolution without losing other config sections."""
+    config_path = MEMORY_DIR / "config.json"
+
+    def mutate(cfg: dict) -> None:
+        evolution = cfg.setdefault("evolution", {})
+        update(evolution)
+
+    cfg = update_config(config_path, mutate)
+    return dict(cfg.get("evolution", {}))
+
+
+def _enable_evolution(config: dict) -> None:
+    config["enabled"] = True
+    config.setdefault("backend", "auto")
+
+
 @router.get("/api/evolution/status")
-async def evolution_status():
+def evolution_status(request: Request):
     """Get evolution engine status, backend, and recent history."""
+    _require_read(request)
     try:
-        import json as _json
-        from superlocalmemory.evolution.skill_evolver import detect_backend
         from superlocalmemory.evolution.evolution_store import EvolutionStore
+        from superlocalmemory.evolution.skill_evolver import detect_backend
 
-        # Read config directly from config.json (SLMConfig.load doesn't serialize evolution)
-        config_path = MEMORY_DIR / "config.json"
-        evo_cfg = {}
-        if config_path.exists():
-            with open(config_path) as f:
-                cfg = _json.load(f)
-            evo_cfg = cfg.get("evolution", {})
-
+        evo_cfg = _read_evolution_config()
         enabled = evo_cfg.get("enabled", False)
-        backend = detect_backend() if enabled else "none"
+        backend_setting = evo_cfg.get("backend", "auto")
+        backend = (
+            detect_backend() if enabled and backend_setting == "auto"
+            else backend_setting if enabled
+            else "none"
+        )
         db_path = str(MEMORY_DIR / "memory.db")
 
+        profile_id = get_active_profile()
         store = EvolutionStore(db_path)
-        stats = store.get_stats()
-        recent = store.get_recent(limit=10)
+        stats = store.get_stats(profile_id)
+        recent = store.get_recent(profile_id, limit=10)
 
         return {
             "enabled": enabled,
             "backend": backend,
             "config": {
-                "backend_setting": evo_cfg.get("backend", "auto"),
+                "backend_setting": backend_setting,
                 "max_per_cycle": evo_cfg.get("max_evolutions_per_cycle", 3),
+                "mutation_model": evo_cfg.get("mutation_model", ""),
+                "verify_model": evo_cfg.get("verify_model", ""),
+                "confirm_model": evo_cfg.get("confirm_model", ""),
             },
             "stats": {
                 "total": stats.get("total", 0),
@@ -70,83 +113,158 @@ async def evolution_status():
                 for r in recent
             ],
         }
-    except Exception as e:
-        logger.debug("evolution_status error: %s", e)
-        return {"enabled": False, "backend": "none", "error": str(e)}
+    except Exception:
+        logger.exception("evolution_status error")
+        return {"enabled": False, "backend": "none", "error": "Internal server error"}
 
 
 @router.post("/api/evolution/enable")
-async def evolution_enable():
-    """Enable skill evolution engine. Writes directly to config.json."""
+def evolution_enable(request: Request):
+    """Enable evolution without replacing the user's selected backend."""
+    _require_manage(request)
     try:
-        import json as _json
-
-        config_path = MEMORY_DIR / "config.json"
-        cfg = {}
-        if config_path.exists():
-            with open(config_path) as f:
-                cfg = _json.load(f)
+        evolution = _update_evolution_config(_enable_evolution)
+        return {
+            "ok": True,
+            "message": f"Evolution enabled with {evolution['backend']} backend.",
+        }
+    except Exception:
+        logger.exception("evolution_enable error")
+        return {"ok": False, "error": "Internal server error"}
 
-        if "evolution" not in cfg:
-            cfg["evolution"] = {}
-        cfg["evolution"]["enabled"] = True
-        cfg["evolution"]["backend"] = "auto"
 
-        with open(config_path, "w") as f:
-            _json.dump(cfg, f, indent=2)
+@router.post("/api/evolution/disable")
+def evolution_disable(request: Request):
+    """Disable skill evolution engine.  Mirrors /api/evolution/enable."""
+    _require_manage(request)
+    try:
+        _update_evolution_config(lambda cfg: cfg.update({"enabled": False}))
 
-        return {"ok": True, "message": "Evolution enabled. Will use auto-detected backend."}
-    except Exception as e:
-        logger.error("evolution_enable error: %s", e)
-        return {"ok": False, "error": str(e)}
+        return {"ok": True, "message": "Evolution disabled."}
+    except Exception:
+        logger.exception("evolution_disable error")
+        return {"ok": False, "error": "Internal server error"}
 
 
 @router.post("/api/evolution/run")
-async def evolution_run():
+def evolution_run(request: Request):
     """Manually trigger an evolution cycle."""
+    _require_manage(request)
     try:
-        import json as _json
         from superlocalmemory.evolution.skill_evolver import SkillEvolver
 
-        config_path = MEMORY_DIR / "config.json"
-        evo_cfg = {}
-        if config_path.exists():
-            with open(config_path) as f:
-                evo_cfg = _json.load(f).get("evolution", {})
-
+        evo_cfg = _read_evolution_config()
         if not evo_cfg.get("enabled", False):
             return {"ok": False, "error": "Evolution is disabled. Enable first."}
 
         profile = get_active_profile()
         db_path = str(MEMORY_DIR / "memory.db")
 
-        # Build a minimal config object for the evolver
-        class _EvoCfg:
-            enabled = True
-            backend = evo_cfg.get("backend", "auto")
-            max_evolutions_per_cycle = evo_cfg.get("max_evolutions_per_cycle", 3)
-        class _Cfg:
-            evolution = _EvoCfg()
-
-        evolver = SkillEvolver(db_path, _Cfg())
+        # Build a minimal config object for the evolver. Must carry the
+        # per-step model fields (v3.7.9) or a dashboard-triggered run would
+        # silently ignore the user's configured models and fall back to the
+        # cheapest defaults.
+        evolution_config = SimpleNamespace(
+            enabled=True,
+            backend=evo_cfg.get("backend", "auto"),
+            max_evolutions_per_cycle=evo_cfg.get("max_evolutions_per_cycle", 3),
+            mutation_model=evo_cfg.get("mutation_model", ""),
+            verify_model=evo_cfg.get("verify_model", ""),
+            confirm_model=evo_cfg.get("confirm_model", ""),
+        )
+        evolver = SkillEvolver(
+            db_path, SimpleNamespace(evolution=evolution_config)
+        )
         result = evolver.run_consolidation_cycle(profile)
 
         return {"ok": True, **result}
-    except Exception as e:
-        logger.error("evolution_run error: %s", e)
-        return {"ok": False, "error": str(e)}
+    except Exception:
+        logger.exception("evolution_run error")
+        return {"ok": False, "error": "Internal server error"}
+
+
+class EvolutionConfigUpdate(BaseModel):
+    enabled: Optional[bool] = None
+    backend: Optional[str] = None
+    max_evolutions_per_cycle: Optional[int] = None
+    mutation_model: Optional[str] = None
+    verify_model: Optional[str] = None
+    confirm_model: Optional[str] = None
+
+
+@router.post("/api/evolution/config")
+def evolution_config(request: Request, body: EvolutionConfigUpdate):
+    """Update evolution config from the dashboard (v3.7.9).
+
+    Validates model + backend values against the same allow-list the CLI uses
+    (``slm config set evolution.*``) and persists to config.json atomically.
+    Only fields provided in the body are changed.
+    """
+    _require_manage(request)
+    try:
+        from superlocalmemory.evolution.model_selection import _MODEL_ALIASES
+
+        accepted_models = set(_MODEL_ALIASES) | {"", "auto"}
+        accepted_backends = {"auto", "claude", "ollama", "anthropic", "openai"}
+
+        for field in ("mutation_model", "verify_model", "confirm_model"):
+            val = getattr(body, field)
+            if val is not None and val not in accepted_models:
+                allowed = ", ".join(["auto", *sorted(_MODEL_ALIASES)])
+                return {"ok": False, "error": f"{field} must be one of: {allowed}"}
+        if body.backend is not None and body.backend not in accepted_backends:
+            return {
+                "ok": False,
+                "error": f"backend must be one of: {', '.join(sorted(accepted_backends))}",
+            }
+        if (body.max_evolutions_per_cycle is not None
+                and not 0 < body.max_evolutions_per_cycle <= 50):
+            return {"ok": False, "error": "max_evolutions_per_cycle must be 1..50"}
+
+        def _apply(evo: dict) -> None:
+            for field in (
+                "enabled",
+                "backend",
+                "max_evolutions_per_cycle",
+                "mutation_model",
+                "verify_model",
+                "confirm_model",
+            ):
+                value = getattr(body, field)
+                if value is None:
+                    continue
+                if field.endswith("_model") and value == "auto":
+                    value = ""
+                evo[field] = value
+
+        evo = _update_evolution_config(_apply)
+
+        return {"ok": True, "config": {
+            "enabled": evo.get("enabled", False),
+            "backend": evo.get("backend", "auto"),
+            "max_evolutions_per_cycle": evo.get("max_evolutions_per_cycle", 3),
+            "mutation_model": evo.get("mutation_model", ""),
+            "verify_model": evo.get("verify_model", ""),
+            "confirm_model": evo.get("confirm_model", ""),
+        }}
+    except Exception:
+        logger.exception("evolution_config error")
+        return {"ok": False, "error": "Internal server error"}
 
 
 @router.get("/api/evolution/lineage")
-async def evolution_lineage(skill_name: str = ""):
+def evolution_lineage(request: Request, skill_name: str = ""):
     """Get evolution lineage for a skill or all skills.
 
     Returns lineage records and a tree structure grouped by root skill.
     """
+    _require_read(request)
+    conn = None
     try:
         import sqlite3 as _sqlite3
 
         db_path = str(MEMORY_DIR / "memory.db")
+        profile_id = get_active_profile()
         conn = _sqlite3.connect(db_path, timeout=10)
         conn.row_factory = _sqlite3.Row
 
@@ -156,9 +274,9 @@ async def evolution_lineage(skill_name: str = ""):
                 "trigger_type, generation, status, mutation_summary, "
                 "blind_verified, created_at, completed_at "
                 "FROM skill_evolution_log "
-                "WHERE skill_name = ? OR parent_skill_id = ? "
+                "WHERE profile_id = ? AND (skill_name = ? OR parent_skill_id = ?) "
                 "ORDER BY created_at ASC",
-                (skill_name, skill_name),
+                (profile_id, skill_name, skill_name),
             ).fetchall()
         else:
             rows = conn.execute(
@@ -166,11 +284,11 @@ async def evolution_lineage(skill_name: str = ""):
                 "trigger_type, generation, status, mutation_summary, "
                 "blind_verified, created_at, completed_at "
                 "FROM skill_evolution_log "
+                "WHERE profile_id = ? "
                 "ORDER BY created_at DESC LIMIT 100",
+                (profile_id,),
             ).fetchall()
 
-        conn.close()
-
         lineage = [
             {
                 "id": dict(r)["id"],
@@ -208,6 +326,9 @@ async def evolution_lineage(skill_name: str = ""):
             "lineage_count": len(lineage),
             "tree": tree,
         }
-    except Exception as e:
-        logger.debug("evolution_lineage error: %s", e)
-        return {"lineage": [], "lineage_count": 0, "tree": {}, "error": str(e)}
+    except Exception:
+        logger.exception("evolution_lineage error")
+        return {"lineage": [], "lineage_count": 0, "tree": {}, "error": "Internal server error"}
+    finally:
+        if conn is not None:
+            conn.close()

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

@@ -342,12 +342,23 @@ def set_active_profile_everywhere(name: str) -> None:
 
 
 def delete_profile_from_db(name: str) -> None:
-    """Delete a profile row from SQLite. ON DELETE CASCADE handles child rows."""
+    """Delete a profile row from SQLite.
+
+    rbac_memberships has no FK to profiles, so CASCADE does not remove role
+    grants — they would otherwise survive deletion and silently re-activate if
+    a profile of the same name is later recreated. Remove them explicitly.
+    """
     if not DB_PATH.exists():
         return
     conn = sqlite3.connect(str(DB_PATH))
     try:
         conn.execute("PRAGMA foreign_keys=ON")
+        # Purge role grants for this workspace (no FK CASCADE covers these).
+        for tbl in ("rbac_memberships",):
+            try:
+                conn.execute(f"DELETE FROM {tbl} WHERE profile_id = ?", (name,))
+            except sqlite3.OperationalError:
+                pass  # table may not exist on older installs
         conn.execute("DELETE FROM profiles WHERE profile_id = ?", (name,))
         conn.commit()
     finally:
@@ -420,6 +431,10 @@ class SearchRequest(BaseModel):
     cluster_id: Optional[int] = None
     date_from: Optional[str] = None
     date_to: Optional[str] = None
+    # T-window: relative span ("7d", "30d", "1y") or explicit range
+    # ("2026-07-01..2026-07-31"). When empty, date_from/date_to (if both set)
+    # are used as the range. Empty + no dates = no time filter.
+    window: Optional[str] = None
 
 
 class ProfileSwitch(BaseModel):