amfs-http-server 0.3.3__tar.gz → 0.3.5__tar.gz

{amfs_http_server-0.3.3 → amfs_http_server-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: amfs-http-server
-Version: 0.3.3
+Version: 0.3.5
 Summary: AMFS HTTP/REST API server with SSE support
 License-Expression: Apache-2.0
 Requires-Python: >=3.11

{amfs_http_server-0.3.3 → amfs_http_server-0.3.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "amfs-http-server"
-version = "0.3.3"
+version = "0.3.5"
 description = "AMFS HTTP/REST API server with SSE support"
 requires-python = ">=3.11"
 license = "Apache-2.0"

amfs_http_server-0.3.5/src/amfs_http/openrouter_proxy.py

@@ -0,0 +1,267 @@
+"""Memory-augmenting OpenRouter proxy (OpenAI-compatible chat completions).
+
+This is the "Option C" proxy: a drop-in replacement for the OpenRouter chat
+completions endpoint that (1) retrieves relevant memory for the caller's scope
+and injects it as context, (2) forwards the request to OpenRouter unchanged
+otherwise, and (3) writes salient facts from the exchange back to memory and
+seals a decision trace — all without the client changing anything but the base
+URL.
+
+Design principles:
+- Fail-open: any memory error (retrieval, injection, write-back) must never
+  break the LLM call. On failure we forward the original request untouched.
+- Non-blocking: memory retrieval and write-back are synchronous SDK calls, so
+  they run in a threadpool (``asyncio.to_thread``) to keep the event loop free.
+  Write-back and trace sealing are fire-and-forget background tasks.
+- Streaming: ``stream: true`` is passed through as an SSE byte stream.
+
+Configuration (env):
+- OPENROUTER_API_KEY         upstream key (required to enable the route)
+- OPENROUTER_BASE_URL        default https://openrouter.ai/api/v1
+- AMFS_PROXY_INJECT_LIMIT    max memory facts injected (default 5)
+- AMFS_PROXY_WRITE_BACK      "true" to enable fact write-back (default false)
+- AMFS_PROXY_SAFETY_GATE     "false" to disable the Pro SafetyGate on write-back
+                             (default true; no-op when amfs_safety is absent)
+
+TODO(integration-test): tests/integration/test_openrouter_proxy.py exercises the
+inject/forward/write-back path against a mocked upstream; it is skipped in unit
+CI (requires fastapi TestClient + httpx-mock) and is unvalidated here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+BASE_URL = os.environ.get("OPENROUTER_BASE_URL", "https://openrouter.ai/api/v1").rstrip("/")
+API_KEY = os.environ.get("OPENROUTER_API_KEY", "")
+INJECT_LIMIT = int(os.environ.get("AMFS_PROXY_INJECT_LIMIT", "5"))
+WRITE_BACK = os.environ.get("AMFS_PROXY_WRITE_BACK", "false").lower() == "true"
+# Auto-run the Pro SafetyGate on write-back when available (secret block + PII
+# redact). Disabled explicitly with AMFS_PROXY_SAFETY_GATE=false. Soft/optional:
+# the gate lives in the Pro ``amfs_safety`` package; OSS-only deployments skip it.
+SAFETY_GATE = os.environ.get("AMFS_PROXY_SAFETY_GATE", "true").lower() == "true"
+
+_SAFETY_GATE_CACHE: dict[str, Any] = {}
+
+
+def _gate_value(mem: Any, scope: str, key: str, value: Any) -> tuple[bool, Any]:
+    """Run the optional Pro SafetyGate over a proposed write-back value.
+
+    Returns ``(allowed, value_to_write)`` — the value is redacted when the gate
+    masks sensitive content. Fail-open: any import/build/scan error allows the
+    original value through (the LLM exchange must never be lost to a gate bug).
+    """
+    if not SAFETY_GATE:
+        return True, value
+    try:
+        if "gate" not in _SAFETY_GATE_CACHE:
+            from amfs_safety import SafetyGate  # Pro package, optional
+
+            adapter = getattr(mem, "_adapter", None)
+            _SAFETY_GATE_CACHE["gate"] = SafetyGate(adapter=adapter)
+        gate = _SAFETY_GATE_CACHE["gate"]
+
+        from datetime import datetime, timezone
+
+        from amfs_core.models import MemoryEntry, Provenance
+
+        entry = MemoryEntry(
+            entity_path=scope,
+            key=key,
+            value=value,
+            provenance=Provenance(
+                agent_id="openrouter-proxy",
+                session_id="proxy",
+                written_at=datetime.now(timezone.utc),
+            ),
+            confidence=0.5,
+        )
+        decision = gate.check_write(entry)
+        if not decision.allowed:
+            logger.info("proxy: write-back blocked by SafetyGate (%s)", decision.max_severity)
+            return False, value
+        return True, decision.entry.value
+    except Exception:  # noqa: BLE001 - fail-open
+        logger.debug("proxy: SafetyGate unavailable/failed; allowing write", exc_info=True)
+        return True, value
+
+_MEMORY_HEADER = (
+    "You have access to the following facts from persistent memory. "
+    "Treat them as authoritative context; if none are relevant, ignore them.\n"
+)
+
+
+def is_configured() -> bool:
+    return bool(API_KEY)
+
+
+def _last_user_text(messages: list[dict[str, Any]]) -> str:
+    for msg in reversed(messages):
+        if msg.get("role") == "user":
+            content = msg.get("content")
+            if isinstance(content, str):
+                return content
+            if isinstance(content, list):  # OpenAI content-parts form
+                return " ".join(p.get("text", "") for p in content if isinstance(p, dict))
+    return ""
+
+
+def _retrieve_facts(get_memory: Callable[[], Any], scope: str | None, query: str) -> list[str]:
+    """Best-effort memory retrieval. Returns formatted fact strings (fail-open)."""
+    if not query:
+        return []
+    try:
+        mem = get_memory()
+    except Exception:  # noqa: BLE001
+        logger.debug("proxy: get_memory failed", exc_info=True)
+        return []
+    # Prefer the Pro MultiStrategyRetriever (adaptive RRF + rerank) when the
+    # amfs_retrieval package is installed; otherwise SDK full-text/semantic
+    # search; otherwise list the scope. All fail-open.
+    try:
+        from amfs_http.pro_provider import build_pro_retriever, pro_retrieve_values
+
+        adapter = getattr(mem, "_adapter", None)
+        retriever = build_pro_retriever(adapter)
+        pro_values = pro_retrieve_values(retriever, scope, query, INJECT_LIMIT)
+        if pro_values is not None:
+            return [
+                v if isinstance(v, str) else json.dumps(v, default=str)
+                for v in pro_values
+            ][:INJECT_LIMIT]
+    except Exception:  # noqa: BLE001 - Pro path optional, fall through to OSS
+        logger.debug("proxy: pro retrieval skipped", exc_info=True)
+
+    # Prefer full-text/semantic search; fall back to listing the scope.
+    try:
+        search = getattr(mem, "search", None)
+        if callable(search):
+            results = search(query=query, entity_path=scope, limit=INJECT_LIMIT)
+        else:
+            results = mem._adapter.list(scope)[:INJECT_LIMIT]
+    except Exception:  # noqa: BLE001
+        logger.debug("proxy: memory search failed", exc_info=True)
+        return []
+    facts: list[str] = []
+    for r in results or []:
+        value = getattr(r, "value", None)
+        if value is None and isinstance(r, dict):
+            value = r.get("value")
+        if value is not None:
+            facts.append(value if isinstance(value, str) else json.dumps(value, default=str))
+    return facts[:INJECT_LIMIT]
+
+
+def _inject(messages: list[dict[str, Any]], facts: list[str]) -> list[dict[str, Any]]:
+    if not facts:
+        return messages
+    block = _MEMORY_HEADER + "\n".join(f"- {f}" for f in facts)
+    # Prepend as a system message so it does not overwrite the caller's system prompt.
+    return [{"role": "system", "content": block}, *messages]
+
+
+def _write_back(get_memory: Callable[[], Any], scope: str | None,
+                query: str, answer: str) -> None:
+    """Persist a salient fact from the exchange + seal a trace (best-effort)."""
+    if not WRITE_BACK or not scope or not answer:
+        return
+    try:
+        mem = get_memory()
+        key = f"proxy-exchange-{abs(hash(query)) % 10_000_000}"
+        value = {"q": query[:500], "a": answer[:1500]}
+        allowed, value = _gate_value(mem, scope, key, value)
+        if not allowed:
+            return
+        mem.write(scope, key, value, confidence=0.5)
+        commit = getattr(mem, "commit_outcome", None)
+        if callable(commit):
+            commit("proxy-exchange", "success")
+    except Exception:  # noqa: BLE001
+        logger.debug("proxy: write-back failed", exc_info=True)
+
+
+def mount_openrouter_proxy(app, *, get_memory: Callable[[], Any]) -> None:
+    """Mount POST /api/v1/proxy/chat/completions if OpenRouter is configured."""
+    if not is_configured():
+        logger.info("OpenRouter proxy disabled (OPENROUTER_API_KEY not set)")
+        return
+
+    import httpx
+    from fastapi import Request
+    from fastapi.responses import JSONResponse, StreamingResponse
+
+    client = httpx.AsyncClient(timeout=httpx.Timeout(60.0, connect=10.0))
+
+    def _scope_of(request: Request, body: dict[str, Any]) -> str | None:
+        return (body.get("amfs_scope")
+                or request.headers.get("X-AMFS-Scope")
+                or os.environ.get("AMFS_PROXY_DEFAULT_SCOPE"))
+
+    def _upstream_headers(request: Request) -> dict[str, str]:
+        headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
+        # Pass through OpenRouter attribution headers when present.
+        for h in ("HTTP-Referer", "X-Title"):
+            if h in request.headers:
+                headers[h] = request.headers[h]
+        return headers
+
+    @app.post("/api/v1/proxy/chat/completions")
+    async def proxy_chat_completions(request: Request):
+        raw = await request.body()
+        try:
+            body = json.loads(raw)
+        except Exception:
+            return JSONResponse({"error": "invalid JSON body"}, status_code=400)
+
+        scope = _scope_of(request, body)
+        messages = body.get("messages") or []
+        query = _last_user_text(messages)
+
+        # 1) Retrieve + inject memory (fail-open, off the event loop).
+        try:
+            facts = await asyncio.to_thread(_retrieve_facts, get_memory, scope, query)
+            if facts:
+                body = {**body, "messages": _inject(messages, facts)}
+        except Exception:  # noqa: BLE001
+            logger.debug("proxy: injection skipped", exc_info=True)
+
+        body.pop("amfs_scope", None)
+        url = f"{BASE_URL}/chat/completions"
+        headers = _upstream_headers(request)
+
+        # 2a) Streaming: pass the SSE stream straight through.
+        if body.get("stream"):
+            async def _iter():
+                async with client.stream("POST", url, headers=headers, json=body) as resp:
+                    async for chunk in resp.aiter_raw():
+                        yield chunk
+            # NOTE: write-back on streamed responses requires accumulating the
+            # SSE deltas; deferred (TODO) to keep streaming zero-overhead.
+            return StreamingResponse(_iter(), media_type="text/event-stream")
+
+        # 2b) Non-streaming: forward, then schedule background write-back.
+        try:
+            resp = await client.post(url, headers=headers, json=body)
+        except Exception:  # noqa: BLE001
+            logger.warning("proxy: upstream request failed", exc_info=True)
+            return JSONResponse({"error": "upstream unavailable"}, status_code=502)
+
+        data = resp.json() if resp.content else {}
+        try:
+            answer = data["choices"][0]["message"]["content"]
+        except Exception:  # noqa: BLE001
+            answer = ""
+
+        if WRITE_BACK and answer:
+            asyncio.create_task(
+                asyncio.to_thread(_write_back, get_memory, scope, query, answer))
+
+        return JSONResponse(data, status_code=resp.status_code)
+
+    logger.info("OpenRouter memory proxy mounted → POST /api/v1/proxy/chat/completions")

amfs_http_server-0.3.5/src/amfs_http/pro_provider.py

@@ -0,0 +1,121 @@
+"""Optional Pro retrieval/sealing provider for the OpenRouter proxy.
+
+The OSS proxy retrieves memory with the plain SDK ``search`` (full-text / list).
+When the Pro ``amfs_retrieval`` package is installed, this module upgrades that to
+the ``MultiStrategyRetriever`` (adaptive-weighted RRF + optional cross-encoder
+rerank over a real default embedder), which is what wins the precision/adversarial
+benchmarks. When ``amfs_traces`` is installed and sealing is enabled, write-backs
+can be sealed into a signed ``ImmutableDecisionTrace``.
+
+Everything here is soft/optional and fail-open:
+- OSS-only deployments (no Pro packages) get ``None`` and the proxy falls back to
+  SDK search — no error, no behaviour change.
+- Any construction/among failure degrades to the OSS path.
+
+Env:
+- AMFS_PROXY_PRO_RETRIEVAL   "false" to force the OSS search path (default true)
+- AMFS_PROXY_PRO_RERANK      "false" to skip reranking entirely (default true)
+- AMFS_LLM_RERANK            "true" to use the LLM listwise reranker (Pro tier) —
+                             the lever that reaches >90% adversarial Hit@1. Costs
+                             one LLM call per retrieval, so it is opt-in. Needs
+                             AMFS_LLM_RERANK_BASE_URL/API_KEY (e.g. OpenRouter).
+                             When unset/unavailable, falls back to the offline
+                             cross-encoder.
+
+NOTE(integration-test): the Pro retrieval path requires the amfs-internal packages
+and a populated adapter; it is exercised in the amfs-internal retrieval eval, not
+in OSS unit CI. The unit test here only covers graceful absence + value extraction.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+PRO_RETRIEVAL = os.environ.get("AMFS_PROXY_PRO_RETRIEVAL", "true").lower() == "true"
+PRO_RERANK = os.environ.get("AMFS_PROXY_PRO_RERANK", "true").lower() == "true"
+
+_cache: dict[str, Any] = {}
+
+
+def _build_reranker() -> Any | None:
+    """Build the strongest available reranker.
+
+    Prefers the LLM listwise reranker (Pro tier) when ``AMFS_LLM_RERANK=true`` and
+    an OpenAI-compatible client/key are configured — it resolves confusable facts
+    under adversarial paraphrase and is the lever for top-1 accuracy, at the cost
+    of one LLM call per retrieval. Otherwise falls back to the offline
+    ``CrossEncoderReranker`` (single-digit ms, zero egress). Returns ``None`` only
+    if neither is importable.
+    """
+    try:
+        from amfs_retrieval import LLMReranker
+
+        llm = LLMReranker()  # reads AMFS_LLM_RERANK* env
+        if llm.available:
+            logger.info("pro_provider: LLM listwise reranker enabled for proxy")
+            return llm
+    except Exception:  # noqa: BLE001 - LLM rerank optional
+        logger.debug("pro_provider: LLM reranker unavailable", exc_info=True)
+    try:
+        from amfs_retrieval import CrossEncoderReranker
+
+        return CrossEncoderReranker()
+    except Exception:  # noqa: BLE001 - rerank optional
+        logger.debug("pro_provider: reranker unavailable", exc_info=True)
+        return None
+
+
+def build_pro_retriever(adapter: Any) -> Any | None:
+    """Build a Pro MultiStrategyRetriever over ``adapter``, or None if unavailable.
+
+    Cached on the adapter identity so the embedder/reranker are loaded once.
+    """
+    if not PRO_RETRIEVAL or adapter is None:
+        return None
+    cache_key = f"retriever:{id(adapter)}"
+    if cache_key in _cache:
+        return _cache[cache_key]
+    try:
+        from amfs_retrieval import MultiStrategyRetriever, create_pro_embedder
+
+        reranker = _build_reranker() if PRO_RERANK else None
+
+        retriever = MultiStrategyRetriever(
+            adapter, embedder=create_pro_embedder(), reranker=reranker
+        )
+        _cache[cache_key] = retriever
+        logger.info("pro_provider: Pro MultiStrategyRetriever enabled for proxy")
+        return retriever
+    except Exception:  # noqa: BLE001 - Pro package absent or failed to build
+        logger.debug("pro_provider: Pro retrieval unavailable", exc_info=True)
+        _cache[cache_key] = None
+        return None
+
+
+def _result_value(result: Any) -> Any:
+    """Extract the stored value from a RetrievalResult-like object or dict."""
+    entry = getattr(result, "entry", None)
+    if entry is None and isinstance(result, dict):
+        entry = result.get("entry", result)
+    if isinstance(entry, dict):
+        return entry.get("value")
+    return getattr(entry, "value", None)
+
+
+def pro_retrieve_values(
+    retriever: Any, scope: str | None, query: str, limit: int
+) -> list[Any] | None:
+    """Run Pro retrieval and return raw stored values (fail-open -> None)."""
+    if retriever is None or not query:
+        return None
+    try:
+        results = retriever.retrieve(query, entity_path=scope, limit=limit)
+    except Exception:  # noqa: BLE001
+        logger.debug("pro_provider: retrieve failed", exc_info=True)
+        return None
+    values = [v for v in (_result_value(r) for r in results or []) if v is not None]
+    return values or None

{amfs_http_server-0.3.3 → amfs_http_server-0.3.5}/src/amfs_http/server.py

@@ -35,6 +35,7 @@ from amfs import AgentMemory, MemoryType, OutcomeType
 from amfs.config import load_config_or_default
 from pydantic import BaseModel, Field
 from amfs_core.models import (
+    AgentGroup,
     AMFSConfig,
     DecisionTrace,
     Event,
@@ -217,6 +218,12 @@ try:
 except ImportError:
     pass
 
+try:
+    from amfs_http.openrouter_proxy import mount_openrouter_proxy
+    mount_openrouter_proxy(app, get_memory=_get_memory)
+except Exception:  # noqa: BLE001 - proxy is optional; never block startup
+    logger.debug("OpenRouter proxy not mounted", exc_info=True)
+
 try:
     from amfs_tenant.http_deps import mount_scope_enforcement
     mount_scope_enforcement(app)
@@ -1027,6 +1034,7 @@ def _infer_tags(
 
 @app.put("/api/v1/agents/{agent_id:path}/profile")
 async def update_agent_profile(
+    request: Request,
     agent_id: str,
     body: dict[str, Any],
     _auth: str | None = Depends(verify_api_key),
@@ -1036,6 +1044,10 @@ async def update_agent_profile(
     mem = _get_memory()
     profile = AgentProfile.model_validate(body)
     agent = mem._adapter.update_agent_profile(agent_id, profile)
+    # Link the agent to the API key's owner so it shows on the user's dashboard
+    # immediately — set_identity announces through this endpoint before the
+    # agent has written any memory, so the write-path owner link never fires.
+    _ensure_agent_owner(request, agent_id, mem.namespace)
     return json.loads(json.dumps(agent.model_dump(mode="json"), default=str))
 
 
@@ -1694,6 +1706,18 @@ async def list_agents(
         own = vis.get_user_agents()
         before_own_filter = list(agent_data.keys())
         agent_data = {aid: d for aid, d in agent_data.items() if aid in own}
+        # Include owner-linked agents that have written zero entries (e.g. an
+        # agent that called set_identity over MCP but hasn't written memory
+        # yet). Without this they never appear on the dashboard.
+        for aid in own:
+            if aid not in agent_data:
+                agent_data[aid] = {
+                    "agent_id": aid,
+                    "entries_written": 0,
+                    "entities_touched": set(),
+                    "last_active": None,
+                    "first_seen": None,
+                }
         logger.warning(
             "[AGENTS] own_filter: before=%s after=%s own_set=%s",
             sorted(before_own_filter), sorted(agent_data.keys()), sorted(own),
@@ -1710,12 +1734,17 @@ async def list_agents(
                     with conn.cursor() as cur:
                         placeholders = ", ".join(["%s"] * len(known_agent_ids))
                         cur.execute(
-                            f"SELECT agent_id, created_at FROM amfs_agents "
+                            f"SELECT agent_id, created_at, last_active_at, profile "
+                            f"FROM amfs_agents "
                             f"WHERE namespace = %s AND agent_id IN ({placeholders})",
                             [adapter._namespace, *known_agent_ids],
                         )
                         for row in cur.fetchall():
-                            agent_registration[row["agent_id"]] = {"created_at": row["created_at"]}
+                            agent_registration[row["agent_id"]] = {
+                                "created_at": row["created_at"],
+                                "last_active_at": row.get("last_active_at"),
+                                "profile": row.get("profile"),
+                            }
         except (ImportError, Exception):
             pass
 
@@ -1736,14 +1765,27 @@ async def list_agents(
         desc_info = agent_descriptions.get(ad["agent_id"], {})
         reg = agent_registration.get(ad["agent_id"], {})
         created = reg.get("created_at") or ad.get("first_seen")
+        # Zero-write agents have no entry-derived activity; fall back to the
+        # registration row (set via set_identity / profile update).
+        last_active = ad["last_active"] or reg.get("last_active_at")
+        description = desc_info.get("description", "")
+        platform = desc_info.get("platform", "")
+        prof = reg.get("profile")
+        if isinstance(prof, dict):
+            if not description:
+                description = prof.get("description", "") or ""
+            if not platform:
+                sm = prof.get("session_metadata")
+                if isinstance(sm, dict):
+                    platform = sm.get("platform", "") or ""
         agents.append({
             "agentId": ad["agent_id"],
             "entriesWritten": ad["entries_written"],
             "entitiesTouched": len(ad["entities_touched"]),
-            "lastActive": ad["last_active"].isoformat() if ad["last_active"] else None,
+            "lastActive": last_active.isoformat() if last_active else None,
             "createdAt": created.isoformat() if created else None,
-            "description": desc_info.get("description", ""),
-            "platform": desc_info.get("platform", ""),
+            "description": description,
+            "platform": platform,
         })
     return {"agents": agents}
 
@@ -2095,6 +2137,17 @@ async def log_timeline_event(
         details=body.details,
         actor_agent_id=body.actor_agent_id,
     )
+    # WRITE events are authoritatively logged by the write handler
+    # (POST /api/v1/entries). HTTP-backed SDK clients ALSO emit a WRITE event
+    # here from their background log path, which produced two identical WRITE
+    # events per write (the "double-write" bug). The server is the single
+    # source of truth for WRITE timeline events, so drop client-originated
+    # ones here. This is version-agnostic: it fixes every client regardless of
+    # which SDK version they run via `uvx`, without waiting on a PyPI release.
+    # We still return a well-formed (but unpersisted) event so clients that
+    # parse the response don't error.
+    if event_type_enum is EventType.WRITE:
+        return event.model_dump(mode="json")
     saved = mem._adapter.log_event(event)
     return saved.model_dump(mode="json")
 
@@ -2128,6 +2181,264 @@ async def upsert_graph_edge_endpoint(
     return {"status": "ok"}
 
 
+# ──────────────────────────────────────────────────────────────────────
+# Agent Groups & Enriched Agents
+# ──────────────────────────────────────────────────────────────────────
+
+
+@app.get("/api/v1/agents/enriched")
+async def list_agents_enriched(
+    _auth: str | None = Depends(verify_api_key),
+) -> dict[str, Any]:
+    """Return enriched agent info with activity histograms."""
+    mem = _get_memory()
+    agents = mem._adapter.list_agents_enriched(namespace=mem.namespace)
+    for agent in agents[:100]:
+        aid = agent.get("agent_id") or agent.get("agentId", "")
+        if aid:
+            agent["activity_histogram"] = mem._adapter.get_agent_activity_histogram(
+                aid, days=7, namespace=mem.namespace,
+            )
+    return {"agents": agents}
+
+
+@app.get("/api/v1/agent-groups")
+async def list_agent_groups(
+    _auth: str | None = Depends(verify_api_key),
+) -> dict[str, Any]:
+    """List all agent groups."""
+    mem = _get_memory()
+    groups = mem._adapter.list_agent_groups(namespace=mem.namespace)
+    return {"groups": [g.model_dump(mode="json") for g in groups]}
+
+
+@app.post("/api/v1/agent-groups", status_code=201)
+async def create_agent_group_endpoint(
+    request: Request,
+    _auth: str | None = Depends(verify_api_key),
+) -> dict[str, Any]:
+    """Create a new agent group."""
+    body = await request.json()
+    name = body.get("name")
+    if not name:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "name is required"},
+        )
+    mem = _get_memory()
+    group = AgentGroup(
+        namespace=mem.namespace,
+        name=name,
+        description=body.get("description", ""),
+        color=body.get("color"),
+        icon=body.get("icon"),
+        position=body.get("position", 0.0),
+        auto_generated=body.get("autoGenerated", False),
+        source_cluster_id=body.get("sourceClusterId"),
+    )
+    created = mem._adapter.create_agent_group(group, namespace=mem.namespace)
+    return created.model_dump(mode="json")
+
+
+@app.put("/api/v1/agent-groups/{group_id}")
+async def update_agent_group_endpoint(
+    group_id: str,
+    request: Request,
+    _auth: str | None = Depends(verify_api_key),
+) -> dict[str, Any]:
+    """Update an existing agent group."""
+    body = await request.json()
+    mem = _get_memory()
+    kwargs: dict[str, Any] = {}
+    for field in ("name", "description", "color", "icon", "position"):
+        if field in body and body[field] is not None:
+            kwargs[field] = body[field]
+    updated = mem._adapter.update_agent_group(
+        group_id, namespace=mem.namespace, **kwargs,
+    )
+    if updated is None:
+        raise HTTPException(status_code=404, detail="Group not found")
+    return updated.model_dump(mode="json")
+
+
+@app.delete("/api/v1/agent-groups/{group_id}")
+async def delete_agent_group_endpoint(
+    group_id: str,
+    _auth: str | None = Depends(verify_api_key),
+) -> dict[str, Any]:
+    """Delete an agent group."""
+    mem = _get_memory()
+    deleted = mem._adapter.delete_agent_group(group_id, namespace=mem.namespace)
+    return {"deleted": deleted}
+
+
+@app.post("/api/v1/agent-groups/{group_id}/members")
+async def add_group_members(
+    group_id: str,
+    request: Request,
+    _auth: str | None = Depends(verify_api_key),
+) -> dict[str, Any]:
+    """Add agents to a group."""
+    body = await request.json()
+    agent_ids = body.get("agent_ids")
+    if not agent_ids or not isinstance(agent_ids, list):
+        return JSONResponse(
+            status_code=400,
+            content={"error": "agent_ids list is required"},
+        )
+    mem = _get_memory()
+    count = mem._adapter.add_agents_to_group(
+        group_id, agent_ids, namespace=mem.namespace,
+    )
+    return {"added": count}
+
+
+@app.delete("/api/v1/agent-groups/{group_id}/members")
+async def remove_group_members(
+    group_id: str,
+    request: Request,
+    _auth: str | None = Depends(verify_api_key),
+) -> dict[str, Any]:
+    """Remove agents from a group."""
+    body = await request.json()
+    agent_ids = body.get("agent_ids")
+    if not agent_ids or not isinstance(agent_ids, list):
+        return JSONResponse(
+            status_code=400,
+            content={"error": "agent_ids list is required"},
+        )
+    mem = _get_memory()
+    count = mem._adapter.remove_agents_from_group(
+        group_id, agent_ids, namespace=mem.namespace,
+    )
+    return {"removed": count}
+
+
+@app.put("/api/v1/agent-groups/reorder")
+async def reorder_agent_groups_endpoint(
+    request: Request,
+    _auth: str | None = Depends(verify_api_key),
+) -> dict[str, Any]:
+    """Reorder agent groups by setting new positions."""
+    body = await request.json()
+    positions = body.get("positions")
+    if not positions or not isinstance(positions, list):
+        return JSONResponse(
+            status_code=400,
+            content={"error": "positions list is required"},
+        )
+    tuples = [(p["group_id"], p["position"]) for p in positions]
+    mem = _get_memory()
+    mem._adapter.reorder_agent_groups(tuples, namespace=mem.namespace)
+    return {"ok": True}
+
+
+@app.get("/api/v1/agent-groups/suggestions")
+async def agent_group_suggestions(
+    _auth: str | None = Depends(verify_api_key),
+) -> dict[str, Any]:
+    """Return cluster-based group suggestions, excluding dismissed ones."""
+    from amfs_core.models import DigestType
+
+    mem = _get_memory()
+    adapter = mem._adapter
+    digest = adapter.get_digest(
+        DigestType.AGENT_CLUSTERS,
+        f"account:{mem.namespace}",
+        namespace=mem.namespace,
+    )
+    if not digest:
+        return {"suggestions": []}
+
+    try:
+        dismissed = set(adapter.list_dismissed_cluster_ids(mem.namespace))
+    except Exception:
+        dismissed = set()
+
+    clusters = digest.summary.get("clusters", [])
+    suggestions = [c for c in clusters if c.get("cluster_id") not in dismissed]
+    return {"suggestions": suggestions}
+
+
+@app.post("/api/v1/agent-groups/suggestions/{cluster_id}/accept", status_code=201)
+async def accept_cluster_suggestion(
+    cluster_id: str,
+    _auth: str | None = Depends(verify_api_key),
+) -> dict[str, Any]:
+    """Accept a cluster suggestion — create a group from it."""
+    from amfs_core.models import DigestType
+
+    mem = _get_memory()
+    adapter = mem._adapter
+    digest = adapter.get_digest(
+        DigestType.AGENT_CLUSTERS,
+        f"account:{mem.namespace}",
+        namespace=mem.namespace,
+    )
+    if not digest:
+        raise HTTPException(status_code=404, detail="No cluster digest found")
+
+    clusters = digest.summary.get("clusters", [])
+    cluster = next((c for c in clusters if c.get("cluster_id") == cluster_id), None)
+    if cluster is None:
+        raise HTTPException(status_code=404, detail="Cluster not found")
+
+    group = AgentGroup(
+        namespace=mem.namespace,
+        name=cluster.get("suggested_name", cluster_id),
+        description=cluster.get("rationale", ""),
+        auto_generated=True,
+        source_cluster_id=cluster_id,
+    )
+    created = adapter.create_agent_group(group, namespace=mem.namespace)
+
+    agent_ids = cluster.get("agents", [])
+    if agent_ids:
+        adapter.add_agents_to_group(created.id, agent_ids, namespace=mem.namespace)
+
+    return created.model_dump(mode="json")
+
+
+@app.post("/api/v1/agent-groups/suggestions/{cluster_id}/dismiss")
+async def dismiss_cluster_suggestion_endpoint(
+    cluster_id: str,
+    _auth: str | None = Depends(verify_api_key),
+) -> dict[str, Any]:
+    """Dismiss a cluster suggestion so it no longer appears."""
+    mem = _get_memory()
+    mem._adapter.dismiss_cluster_suggestion(cluster_id, mem.namespace)
+    return {"dismissed": True}
+
+
+@app.post("/api/v1/agent-groups/recompute")
+async def recompute_clusters(
+    _auth: str | None = Depends(verify_api_key),
+) -> dict[str, Any]:
+    """Trigger recomputation of agent clusters."""
+    try:
+        from amfs_cortex.compiler import DigestCompiler
+        from amfs_postgres.adapter import PostgresAdapter
+
+        mem = _get_memory()
+        adapter = mem._adapter
+        if not isinstance(adapter, PostgresAdapter):
+            return JSONResponse(
+                status_code=400,
+                content={"error": "Cluster recomputation requires Postgres adapter"},
+            )
+        compiler = DigestCompiler(
+            adapter=adapter,
+            namespace=mem.namespace,
+        )
+        compiler.compile(f"cluster:account:{mem.namespace}")
+    except ImportError:
+        return JSONResponse(
+            status_code=400,
+            content={"error": "amfs-cortex package is required for recomputation"},
+        )
+    return {"ok": True}
+
+
 # ──────────────────────────────────────────────────────────────────────
 # Agent Snapshots
 # ──────────────────────────────────────────────────────────────────────