Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

feat(copilot): dream pass (#13243)

Nicholas Tindleb6bcaba8a741
diff --git a/.github/workflows/platform-backend-ci.yml b/.github/workflows/platform-backend-ci.yml
index eb509f3a5b..db05f79b4a 100644
--- a/.github/workflows/platform-backend-ci.yml
+++ b/.github/workflows/platform-backend-ci.yml
@@ -155,6 +155,36 @@ jobs:
--health-timeout 10s
--health-retries 5
--health-start-period 180s
+ # FalkorDB backs the Graphiti knowledge graph the copilot uses for
+ # long-term memory. Mirrors the local compose mapping
+ # (autogpt_platform/docker-compose.platform.yml: ``6380:6379``) so
+ # ``GraphitiConfig`` defaults (``localhost:6380``,
+ # password=``local-dev-password`` from backend/.env.default) work
+ # unchanged. ``REDIS_ARGS=--requirepass <pw>`` is the FalkorDB
+ # image's documented way to set the bearer; mirrors the entrypoint
+ # the compose stack writes. Integration tests in
+ # ``backend/copilot/graphiti/*_integration_test.py`` skip cleanly
+ # via the ``falkordb_available`` fixture when the port isn't open
+ # (e.g. on a contributor's laptop) — this service makes the port
+ # available in CI so the integration suite actually runs.
+ # ``redis-cli`` ships inside the FalkorDB image; the healthcheck
+ # passes ``-a`` so AUTH succeeds rather than the daemon rejecting
+ # an unauthenticated PING.
+ # Pinned to a concrete release (unlike the local compose ``:latest``)
+ # so an upstream FalkorDB push can't start failing CI on unrelated
+ # PRs; bump deliberately alongside the compose stack.
+ falkordb:
+ image: falkordb/falkordb:v4.18.9
+ ports:
+ - 6380:6379
+ env:
+ REDIS_ARGS: "--requirepass local-dev-password"
+ options: >-
+ --health-cmd "redis-cli -a local-dev-password ping || exit 1"
+ --health-interval 10s
+ --health-timeout 5s
+ --health-retries 10
+ --health-start-period 10s
steps:
- name: Checkout repository
diff --git a/autogpt_platform/backend/.env.default b/autogpt_platform/backend/.env.default
index eae42c4ab1..237f030554 100644
--- a/autogpt_platform/backend/.env.default
+++ b/autogpt_platform/backend/.env.default
@@ -91,8 +91,19 @@ CHAT_USE_LOCAL=false
# Graphiti Temporal Knowledge Graph Memory
# Rollout controlled by LaunchDarkly flag "graphiti-memory"
-# LLM key falls back to CHAT_API_KEY (AutoPilot), then OPEN_ROUTER_API_KEY.
-# Embedder key falls back to CHAT_OPENAI_API_KEY (AutoPilot), then OPENAI_API_KEY.
+# LLM key falls back to CHAT_API_KEY (AutoPilot), then OPEN_ROUTER_API_KEY,
+# then (under CHAT_USE_LOCAL=true) the chat-config api_key + base_url.
+# Embedder key falls back to CHAT_OPENAI_API_KEY (AutoPilot), then
+# OPENAI_API_KEY, then (local) the chat-config api_key.
+#
+# Under CHAT_USE_LOCAL=true these defaults are auto-rewritten to local-
+# friendly Ollama slugs by GraphitiConfig._apply_local_graphiti_models:
+# GRAPHITI_LLM_MODEL=hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M (same as chat)
+# GRAPHITI_RERANKER_MODEL=hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M
+# GRAPHITI_EMBEDDER_MODEL=nomic-embed-text (needs ollama pull)
+# Set GRAPHITI_*_MODEL to a non-cloud slug to bypass the auto-rewrite
+# (your custom value passes through untouched). See
+# docs/platform/copilot-local-llm.md#dream-pass-and-memory.
GRAPHITI_FALKORDB_HOST=localhost
GRAPHITI_FALKORDB_PORT=6380
GRAPHITI_FALKORDB_PASSWORD=local-dev-password
diff --git a/autogpt_platform/backend/backend/api/features/admin/memory_admin_routes.py b/autogpt_platform/backend/backend/api/features/admin/memory_admin_routes.py
new file mode 100644
index 0000000000..2591333fe4
--- /dev/null
+++ b/autogpt_platform/backend/backend/api/features/admin/memory_admin_routes.py
@@ -0,0 +1,1036 @@
+"""Admin-only inspector + on-demand rebuild for Graphiti memory.
+
+Powers the admin memory-visualizer page in the frontend (Task #10).
+All routes are gated by ``requires_admin_user`` so non-admin callers
+get a 403 before any FalkorDB query runs.
+
+Initially scoped to "admin views their OWN memory" — every route
+accepts ``user_id="me"`` and resolves to the caller's user id via
+``get_user_id`` (which also honours the existing admin-impersonation
+``X-Act-As-User-Id`` header for cross-user inspection).
+"""
+
+import logging
+import uuid as _uuid
+from datetime import datetime
+from typing import Annotated, Any, Literal
+
+from autogpt_libs.auth import get_user_id, requires_admin_user
+from autogpt_libs.auth.jwt_utils import get_jwt_payload
+from fastapi import APIRouter, Depends, HTTPException, Path, Query, Request, Security
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
+from redis.exceptions import ResponseError
+
+from backend.copilot.dream.job_status import (
+ JobKind,
+ JobState,
+ JobStatus,
+ mark_errored,
+ read_status,
+ write_initial_status,
+)
+from backend.copilot.dream.nightly_batch import NightlyBatchResult
+from backend.copilot.dream.ratification import RatificationResult
+from backend.copilot.dream.schemas import DreamPassResult
+from backend.copilot.graphiti.client import derive_group_id
+from backend.copilot.graphiti.config import graphiti_config
+from backend.copilot.graphiti.falkordb_driver import AutoGPTFalkorDriver
+from backend.util.clients import get_scheduler_client
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(
+ prefix="/admin/memory",
+ tags=["admin", "memory"],
+ dependencies=[Security(requires_admin_user)],
+)
+
+
+# ---------------------------------------------------------------------------
+# Response models
+# ---------------------------------------------------------------------------
+
+
+class MemoryOverview(BaseModel):
+ """Counts surfaced in the visualizer's header strip."""
+
+ user_id: str
+ group_id: str
+ entities: int
+ episodes: int
+ relates_to_edges: int
+ mentions_edges: int
+ communities: int
+
+
+class EntitySummary(BaseModel):
+ uuid: str
+ name: str
+ summary: str | None = None
+
+
+class EntityListResponse(BaseModel):
+ user_id: str
+ items: list[EntitySummary]
+
+
+class FactSummary(BaseModel):
+ uuid: str
+ source: str
+ target: str
+ name: str | None = None
+ fact: str | None = None
+ status: str | None = None
+ scope: str | None = None
+ confidence: float | None = None
+ created_at: str | None = None
+ expired_at: str | None = None
+
+
+class FactListResponse(BaseModel):
+ user_id: str
+ items: list[FactSummary]
+
+
+class CommunitySummary(BaseModel):
+ uuid: str
+ name: str | None = None
+ summary: str | None = None
+ member_count: int = 0
+
+
+class CommunityListResponse(BaseModel):
+ user_id: str
+ items: list[CommunitySummary]
+
+
+class GraphNode(BaseModel):
+ """A node in the visualizer graph payload.
+
+ ``label`` is the primary FalkorDB label (Entity / Episodic /
+ Community); ``type`` (if present) is the more-specific custom
+ entity type from ``MemoryFact``-typed extraction (Person /
+ Organization / Project / Concept / Preference / Rule). The frontend
+ uses ``type`` for color-coding when present, falls back to ``label``.
+ """
+
+ uuid: str
+ label: str
+ type: str | None = None
+ name: str | None = None
+ summary: str | None = None
+
+
+class GraphEdge(BaseModel):
+ """An edge in the visualizer graph payload."""
+
+ uuid: str
+ label: str # RELATES_TO | MENTIONS | HAS_MEMBER
+ source: str # source node uuid
+ target: str # target node uuid
+ name: str | None = None # extracted relation name (e.g. "works_on")
+ fact: str | None = None
+ status: str | None = None
+ scope: str | None = None
+
+
+class GraphResponse(BaseModel):
+ user_id: str
+ group_id: str
+ nodes: list[GraphNode]
+ edges: list[GraphEdge]
+ truncated: bool = Field(
+ default=False,
+ description=(
+ "True when the result was capped by ``node_limit`` / ``edge_limit``. "
+ "Frontend should surface this so the user knows they're not "
+ "seeing the full graph."
+ ),
+ )
+
+
+class RebuildResult(BaseModel):
+ """Typed envelope around ``rebuild_communities_for_user``'s return dict.
+
+ Lives here (admin routes) rather than in ``copilot/graphiti/communities.py``
+ because the dict-returning rebuild function predates the admin-API
+ typing pass. Hoisting it to ``communities.py`` (and changing the
+ function signature) is a follow-up cleanup.
+ """
+
+ user_id: str
+ started_at: str | None = None
+ communities_built: Any = None
+ elapsed_seconds: float | None = None
+ error: str | None = None
+ skipped: bool = False
+ skip_reason: str | None = None
+ activity: dict[str, Any] | None = None
+ forced: bool = False
+ execution_path: str | None = None
+ """``"flex"`` when the rebuild ran on OpenAI's flex service tier,
+ ``"sync"`` for the default. ``None`` when the rebuild was skipped
+ before a client was constructed."""
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_user_id(user_id: str, caller_id: str) -> str:
+ """``"me"`` resolves to the calling admin's own id."""
+ return caller_id if user_id == "me" else user_id
+
+
+def _audit_cross_user_access(
+ *,
+ request: Request,
+ caller_id: str,
+ target_id: str,
+ jwt_payload: dict,
+) -> None:
+ """Log admin reads/writes against another user's memory.
+
+ ``get_user_id`` only audits impersonation via ``X-Act-As-User-Id``;
+ these routes accept the target user id directly in the path, so we
+ log here to keep an audit trail for PII access (entity names, fact
+ text) and destructive ops (community rebuild).
+ """
+ if target_id == caller_id:
+ return
+ caller_email = jwt_payload.get("email") or jwt_payload.get("user_metadata", {}).get(
+ "email", ""
+ )
+ logger.info(
+ f"Admin memory access: {caller_id} ({caller_email}) "
+ f"acting on user {target_id} for {request.method} {request.url}"
+ )
+
+
+async def _mark_schedule_failed(kind: JobKind, job_id: str, exc: Exception) -> None:
+ """Best-effort: flip a just-queued JobStatus to errored when the
+ scheduler hand-off failed, so a poller doesn't wait on a job that
+ will never run."""
+ try:
+ await mark_errored(
+ kind=kind,
+ job_id=job_id,
+ error=f"scheduling failed: {type(exc).__name__}: {exc}",
+ )
+ except Exception:
+ logger.warning(
+ "Failed to mark %s job %s errored after schedule failure",
+ kind,
+ job_id[:12],
+ )
+
+
+def _open_driver(group_id: str) -> AutoGPTFalkorDriver:
+ """Read-only driver — bypasses the full Graphiti client construction.
+
+ The visualizer's read paths only need Cypher; we avoid the
+ ~1s LLM-client + cross-encoder setup cost for what should be
+ snappy dashboard calls.
+
+ ``build_indices=False`` suppresses graphiti-core's per-init
+ fire-and-forget indexing task. For a user whose graph the admin
+ is inspecting, the indices are already in place from the
+ long-lived chat-write client; firing the index-creation task per
+ short-lived admin request creates a race with the route's own
+ queries and produces "Buffer is closed" log spam.
+ """
+ return AutoGPTFalkorDriver(
+ host=graphiti_config.falkordb_host,
+ port=graphiti_config.falkordb_port,
+ password=graphiti_config.falkordb_password or None,
+ database=group_id,
+ build_indices=False,
+ )
+
+
+_MISSING_GRAPH_MARKERS = ("no such graph", "does not exist", "invalid graph")
+
+
+def _is_missing_graph_error(exc: BaseException) -> bool:
+ """FalkorDB returns ``ResponseError`` with a graph-not-found message
+ when querying a database the user has never populated."""
+ if not isinstance(exc, ResponseError):
+ return False
+ msg = str(exc).lower()
+ return any(marker in msg for marker in _MISSING_GRAPH_MARKERS)
+
+
+async def _count(driver, query: str) -> int:
+ """Run a ``RETURN count(...) AS c`` query; return 0 on empty.
+
+ Swallows only the "no graph yet" case — the user just hasn't used
+ memory. Other Cypher errors (typos, schema issues) propagate so
+ they're visible to admins rather than silently zeroed.
+ """
+ try:
+ rows, _, _ = await driver.execute_query(query)
+ return int(rows[0]["c"]) if rows else 0
+ except ResponseError as exc:
+ if _is_missing_graph_error(exc):
+ return 0
+ raise
+
+
+# ---------------------------------------------------------------------------
+# Routes
+# ---------------------------------------------------------------------------
+
+
[email protected]("/{user_id}/overview", response_model=MemoryOverview)
+async def get_memory_overview(
+ request: Request,
+ user_id: Annotated[str, Path(description="User id or 'me'")],
+ caller_id: Annotated[str, Depends(get_user_id)],
+ jwt_payload: Annotated[dict, Security(get_jwt_payload)],
+) -> MemoryOverview:
+ target = _resolve_user_id(user_id, caller_id)
+ _audit_cross_user_access(
+ request=request,
+ caller_id=caller_id,
+ target_id=target,
+ jwt_payload=jwt_payload,
+ )
+ try:
+ group_id = derive_group_id(target)
+ except ValueError as exc:
+ raise HTTPException(status_code=400, detail=str(exc))
+
+ driver = _open_driver(group_id)
+ try:
+ entities = await _count(driver, "MATCH (n:Entity) RETURN count(n) AS c")
+ episodes = await _count(driver, "MATCH (n:Episodic) RETURN count(n) AS c")
+ relates = await _count(
+ driver, "MATCH ()-[e:RELATES_TO]->() RETURN count(e) AS c"
+ )
+ mentions = await _count(
+ driver, "MATCH ()-[e:MENTIONS]->() RETURN count(e) AS c"
+ )
+ communities = await _count(driver, "MATCH (n:Community) RETURN count(n) AS c")
+ finally:
+ await driver.close()
+
+ return MemoryOverview(
+ user_id=target,
+ group_id=group_id,
+ entities=entities,
+ episodes=episodes,
+ relates_to_edges=relates,
+ mentions_edges=mentions,
+ communities=communities,
+ )
+
+
[email protected]("/{user_id}/entities", response_model=EntityListResponse)
+async def list_entities(
+ request: Request,
+ user_id: Annotated[str, Path(description="User id or 'me'")],
+ caller_id: Annotated[str, Depends(get_user_id)],
+ jwt_payload: Annotated[dict, Security(get_jwt_payload)],
+ limit: Annotated[int, Query(ge=1, le=10000)] = 1000,
+) -> EntityListResponse:
+ target = _resolve_user_id(user_id, caller_id)
+ _audit_cross_user_access(
+ request=request,
+ caller_id=caller_id,
+ target_id=target,
+ jwt_payload=jwt_payload,
+ )
+ try:
+ group_id = derive_group_id(target)
+ except ValueError as exc:
+ raise HTTPException(status_code=400, detail=str(exc))
+
+ driver = _open_driver(group_id)
+ try:
+ result = await driver.execute_query(
+ """
+ MATCH (n:Entity {group_id: $g})
+ RETURN n.uuid AS uuid, n.name AS name, n.summary AS summary
+ ORDER BY n.name
+ LIMIT $limit
+ """,
+ g=group_id,
+ limit=limit,
+ )
+ rows = result[0] if result else []
+ except ResponseError as exc:
+ if not _is_missing_graph_error(exc):
+ raise
+ rows = []
+ finally:
+ await driver.close()
+
+ items = [
+ EntitySummary(
+ uuid=str(r.get("uuid", "")),
+ name=str(r.get("name") or ""),
+ summary=r.get("summary"),
+ )
+ for r in rows
+ ]
+ return EntityListResponse(user_id=target, items=items)
+
+
[email protected]("/{user_id}/facts", response_model=FactListResponse)
+async def list_facts(
+ request: Request,
+ user_id: Annotated[str, Path(description="User id or 'me'")],
+ caller_id: Annotated[str, Depends(get_user_id)],
+ jwt_payload: Annotated[dict, Security(get_jwt_payload)],
+ limit: Annotated[int, Query(ge=1, le=10000)] = 1000,
+ status: Annotated[
+ Literal["active", "superseded", "contradicted", "any"], Query()
+ ] = "any",
+ scope: Annotated[str | None, Query()] = None,
+) -> FactListResponse:
+ target = _resolve_user_id(user_id, caller_id)
+ _audit_cross_user_access(
+ request=request,
+ caller_id=caller_id,
+ target_id=target,
+ jwt_payload=jwt_payload,
+ )
+ try:
+ group_id = derive_group_id(target)
+ except ValueError as exc:
+ raise HTTPException(status_code=400, detail=str(exc))
+
+ # Build optional filters
+ where_clauses = ["e.group_id = $g"]
+ params: dict[str, Any] = {"g": group_id, "limit": limit}
+ if status != "any":
+ where_clauses.append("e.status = $status")
+ params["status"] = status
+ if scope:
+ where_clauses.append("e.scope = $scope")
+ params["scope"] = scope
+ where = " AND ".join(where_clauses)
+
+ driver = _open_driver(group_id)
+ try:
+ result = await driver.execute_query(
+ f"""
+ MATCH (src:Entity)-[e:RELATES_TO]->(tgt:Entity)
+ WHERE {where}
+ RETURN e.uuid AS uuid,
+ src.name AS source,
+ tgt.name AS target,
+ e.name AS name,
+ e.fact AS fact,
+ e.status AS status,
+ e.scope AS scope,
+ e.confidence AS confidence,
+ toString(e.created_at) AS created_at,
+ toString(e.expired_at) AS expired_at
+ ORDER BY e.created_at DESC
+ LIMIT $limit
+ """,
+ **params,
+ )
+ rows = result[0] if result else []
+ except ResponseError as exc:
+ if not _is_missing_graph_error(exc):
+ raise
+ rows = []
+ finally:
+ await driver.close()
+
+ items = [
+ FactSummary(
+ uuid=str(r.get("uuid", "")),
+ source=str(r.get("source") or ""),
+ target=str(r.get("target") or ""),
+ name=r.get("name"),
+ fact=r.get("fact"),
+ status=r.get("status"),
+ scope=r.get("scope"),
+ confidence=r.get("confidence"),
+ created_at=r.get("created_at"),
+ expired_at=r.get("expired_at"),
+ )
+ for r in rows
+ ]
+ return FactListResponse(user_id=target, items=items)
+
+
[email protected]("/{user_id}/communities", response_model=CommunityListResponse)
+async def list_communities(
+ request: Request,
+ user_id: Annotated[str, Path(description="User id or 'me'")],
+ caller_id: Annotated[str, Depends(get_user_id)],
+ jwt_payload: Annotated[dict, Security(get_jwt_payload)],
+ limit: Annotated[int, Query(ge=1, le=2000)] = 500,
+) -> CommunityListResponse:
+ target = _resolve_user_id(user_id, caller_id)
+ _audit_cross_user_access(
+ request=request,
+ caller_id=caller_id,
+ target_id=target,
+ jwt_payload=jwt_payload,
+ )
+ try:
+ group_id = derive_group_id(target)
+ except ValueError as exc:
+ raise HTTPException(status_code=400, detail=str(exc))
+
+ driver = _open_driver(group_id)
+ try:
+ # Graphiti stores membership as (Community)-[HAS_MEMBER]->(Entity); match
+ # in that direction so member_count and the size sort are correct.
+ result = await driver.execute_query(
+ """
+ MATCH (c:Community {group_id: $g})
+ OPTIONAL MATCH (c)-[:HAS_MEMBER]->(m:Entity)
+ WITH c, count(m) AS member_count
+ RETURN c.uuid AS uuid,
+ c.name AS name,
+ c.summary AS summary,
+ member_count
+ ORDER BY member_count DESC, c.name
+ LIMIT $limit
+ """,
+ g=group_id,
+ limit=limit,
+ )
+ rows = result[0] if result else []
+ except ResponseError as exc:
+ if not _is_missing_graph_error(exc):
+ raise
+ rows = []
+ finally:
+ await driver.close()
+
+ items = [
+ CommunitySummary(
+ uuid=str(r.get("uuid", "")),
+ name=r.get("name"),
+ summary=r.get("summary"),
+ member_count=int(r.get("member_count") or 0),
+ )
+ for r in rows
+ ]
+ return CommunityListResponse(user_id=target, items=items)
+
+
[email protected]("/{user_id}/graph", response_model=GraphResponse)
+async def get_graph(
+ request: Request,
+ user_id: Annotated[str, Path(description="User id or 'me'")],
+ caller_id: Annotated[str, Depends(get_user_id)],
+ jwt_payload: Annotated[dict, Security(get_jwt_payload)],
+ node_limit: Annotated[int, Query(ge=1, le=20000)] = 5000,
+ edge_limit: Annotated[int, Query(ge=1, le=50000)] = 10000,
+ include_episodes: Annotated[bool, Query()] = False,
+ include_communities: Annotated[bool, Query()] = True,
+) -> GraphResponse:
+ """Single-shot graph payload for the visualizer canvas.
+
+ Returns nodes + edges in one round-trip so the frontend can hand
+ the whole thing to a force-directed layout without N+1 fetches.
+
+ Defaults to entities + communities (the "what does my memory know
+ about" view). ``include_episodes=True`` adds the temporal
+ :Episodic nodes — useful for debugging extraction but noisy for the
+ typical inspector view.
+ """
+ target = _resolve_user_id(user_id, caller_id)
+ _audit_cross_user_access(
+ request=request,
+ caller_id=caller_id,
+ target_id=target,
+ jwt_payload=jwt_payload,
+ )
+ try:
+ group_id = derive_group_id(target)
+ except ValueError as exc:
+ raise HTTPException(status_code=400, detail=str(exc))
+
+ # Build the labels-of-interest list for the node queries — one
+ # Cypher per label so the label can travel through the result row
+ # without an extra ``labels(n)`` call per row.
+ labels: list[str] = ["Entity"]
+ if include_episodes:
+ labels.append("Episodic")
+ if include_communities:
+ labels.append("Community")
+
+ driver = _open_driver(group_id)
+ nodes: list[GraphNode] = []
+ edges: list[GraphEdge] = []
+ truncated = False
+
+ try:
+ # Nodes — one query per label so we can carry the label through
+ # without an expensive labels() function call per row.
+ for label in labels:
+ result = await driver.execute_query(
+ f"""
+ MATCH (n:{label} {{group_id: $g}})
+ RETURN n.uuid AS uuid,
+ n.name AS name,
+ n.summary AS summary,
+ labels(n) AS all_labels
+ LIMIT $limit
+ """,
+ g=group_id,
+ limit=node_limit,
+ )
+ rows = result[0] if result else []
+ for r in rows:
+ # Custom entity types (Person, Organization, etc.) appear
+ # alongside the base "Entity" label. Pick the first
+ # non-base label as the "type".
+ all_labels = r.get("all_labels") or []
+ custom_type: str | None = None
+ for lbl in all_labels:
+ if lbl not in {"Entity", "Episodic", "Community", "Node"}:
+ custom_type = lbl
+ break
+ nodes.append(
+ GraphNode(
+ uuid=str(r.get("uuid", "")),
+ label=label,
+ type=custom_type,
+ name=r.get("name"),
+ summary=r.get("summary"),
+ )
+ )
+ if len(nodes) >= node_limit:
+ truncated = True
+ break
+ if truncated:
+ break
+
+ # Build a set of fetched node uuids so we can filter edges
+ # to nodes the frontend can actually render (avoids edges
+ # dangling into pages of the graph we didn't fetch).
+ node_uuids = {n.uuid for n in nodes}
+
+ # Edges — RELATES_TO is the meaty signal; MENTIONS is provenance;
+ # HAS_MEMBER ties entities to communities (only meaningful when
+ # include_communities=True).
+ edge_types = ["RELATES_TO"]
+ if include_communities:
+ edge_types.append("HAS_MEMBER")
+ if include_episodes:
+ edge_types.append("MENTIONS")
+ edge_label_filter = "|".join(edge_types)
+
+ result = await driver.execute_query(
+ f"""
+ MATCH (src)-[e:{edge_label_filter} {{group_id: $g}}]->(tgt)
+ RETURN e.uuid AS uuid,
+ type(e) AS label,
+ src.uuid AS source,
+ tgt.uuid AS target,
+ e.name AS name,
+ e.fact AS fact,
+ e.status AS status,
+ e.scope AS scope
+ LIMIT $limit
+ """,
+ g=group_id,
+ limit=edge_limit,
+ )
+ rows = result[0] if result else []
+ for r in rows:
+ src = str(r.get("source", ""))
+ tgt = str(r.get("target", ""))
+ # Drop edges pointing outside the fetched node set — keeps
+ # the rendered graph well-formed when truncation cuts in.
+ if src not in node_uuids or tgt not in node_uuids:
+ continue
+ edges.append(
+ GraphEdge(
+ uuid=str(r.get("uuid", "")),
+ label=str(r.get("label", "RELATES_TO")),
+ source=src,
+ target=tgt,
+ name=r.get("name"),
+ fact=r.get("fact"),
+ status=r.get("status"),
+ scope=r.get("scope"),
+ )
+ )
+ if len(edges) >= edge_limit:
+ truncated = True
+ break
+ except ResponseError as exc:
+ # Missing graph (new user) — return an empty payload rather than
+ # 500; the frontend renders the empty state. Any other FalkorDB
+ # error (Cypher typo, schema mismatch) propagates instead of
+ # being hidden behind an empty graph.
+ if not _is_missing_graph_error(exc):
+ raise
+ finally:
+ await driver.close()
+
+ return GraphResponse(
+ user_id=target,
+ group_id=group_id,
+ nodes=nodes,
+ edges=edges,
+ truncated=truncated,
+ )
+
+
+class JobTriggerResponse(BaseModel):
+ """202 response from a fire-and-forget admin trigger.
+
+ Frontend captures ``job_id`` and polls ``GET .../{job_id}`` for
+ progress. ``state`` is always ``"queued"`` at this point — the
+ scheduler picks the job up within sub-second and flips it to
+ ``running``.
+ """
+
+ job_id: str
+ user_id: str
+ kind: JobKind
+ state: JobState
+ started_at: datetime
+
+
+# Typed JobStatus envelopes per job kind. Each is a concrete
+# parametrization of ``JobStatus[T]`` from
+# ``backend/copilot/dream/job_status.py`` over the work body's result
+# shape. Declaring them as named subclasses (rather than inline
+# ``JobStatus[DreamPassResult]``) gives FastAPI a clean OpenAPI
+# component name (``DreamJobStatus`` instead of
+# ``JobStatus_DreamPassResult_``).
+
+
+class DreamJobStatus(JobStatus[DreamPassResult]):
+ """JobStatus envelope for ``kind="dream_pass"``."""
+
+
+class NightlyJobStatus(JobStatus[NightlyBatchResult]):
+ """JobStatus envelope for ``kind="nightly"``."""
+
+
+class CommunityRebuildJobStatus(JobStatus[RebuildResult]):
+ """JobStatus envelope for ``kind="rebuild"``."""
+
+
+ "/{user_id}/dream",
+ response_model=JobTriggerResponse,
+ status_code=202,
+)
+async def trigger_dream_pass(
+ request: Request,
+ user_id: Annotated[str, Path(description="User id or 'me'")],
+ caller_id: Annotated[str, Depends(get_user_id)],
+ jwt_payload: Annotated[dict, Security(get_jwt_payload)],
+) -> JSONResponse:
+ """Fire a dream pass and return 202 + job_id immediately.
+
+ Frontend polls ``GET /api/admin/memory/{user_id}/dream/{job_id}``
+ for progress. Runs ONLY the dream pass submitter — for the full
+ nightly fan-out use ``POST /{user_id}/nightly``.
+ """
+ target = _resolve_user_id(user_id, caller_id)
+ _audit_cross_user_access(
+ request=request,
+ caller_id=caller_id,
+ target_id=target,
+ jwt_payload=jwt_payload,
+ )
+ try:
+ derive_group_id(target) # validate before kicking off
+ except ValueError as exc:
+ raise HTTPException(status_code=400, detail=str(exc))
+
+ job_id = str(_uuid.uuid4())
+ status = await write_initial_status(
+ kind="dream_pass", job_id=job_id, user_id=target
+ )
+
+ try:
+ await get_scheduler_client().schedule_immediate_dream_pass(
+ user_id=target, job_id=job_id
+ )
+ except Exception as exc:
+ logger.warning(
+ "Failed to schedule dream pass %s for user %s: %s",
+ job_id[:12],
+ target[:12],
+ exc,
+ )
+ await _mark_schedule_failed("dream_pass", job_id, exc)
+ raise HTTPException(
+ status_code=500,
+ detail=f"Dream pass scheduling failed: {type(exc).__name__}: {exc}",
+ )
+
+ payload = JobTriggerResponse(
+ job_id=status.job_id,
+ user_id=status.user_id,
+ kind=status.kind,
+ state=status.state,
+ started_at=status.started_at,
+ )
+ return JSONResponse(status_code=202, content=payload.model_dump(mode="json"))
+
+
+ "/{user_id}/dream/{job_id}",
+ response_model=DreamJobStatus,
+)
+async def get_dream_pass_status(
+ request: Request,
+ user_id: Annotated[str, Path(description="User id or 'me'")],
+ job_id: Annotated[str, Path(description="Job id returned by the POST")],
+ caller_id: Annotated[str, Depends(get_user_id)],
+ jwt_payload: Annotated[dict, Security(get_jwt_payload)],
+) -> DreamJobStatus:
+ """Read the current status of a fire-and-forget dream pass job."""
+ target = _resolve_user_id(user_id, caller_id)
+ _audit_cross_user_access(
+ request=request,
+ caller_id=caller_id,
+ target_id=target,
+ jwt_payload=jwt_payload,
+ )
+ status = await read_status(kind="dream_pass", job_id=job_id)
+ if status is None:
+ raise HTTPException(status_code=404, detail="job not found")
+ if status.user_id != target:
+ raise HTTPException(status_code=403, detail="job belongs to a different user")
+ return DreamJobStatus.model_validate(status.model_dump())
+
+
[email protected]("/{user_id}/ratification", response_model=RatificationResult)
+async def trigger_ratification_pass(
+ request: Request,
+ user_id: Annotated[str, Path(description="User id or 'me'")],
+ caller_id: Annotated[str, Depends(get_user_id)],
+ jwt_payload: Annotated[dict, Security(get_jwt_payload)],
+) -> RatificationResult:
+ """Trigger an on-demand ratification sweep for the user (in isolation).
+
+ Forwards to ``Scheduler.execute_ratification_pass_now``. Runs ONLY
+ the ratification supersession sweep — does NOT run dream pass or
+ community rebuild. Useful for testing ratification behavior
+ without the full nightly fan-out.
+ """
+ target = _resolve_user_id(user_id, caller_id)
+ _audit_cross_user_access(
+ request=request,
+ caller_id=caller_id,
+ target_id=target,
+ jwt_payload=jwt_payload,
+ )
+ try:
+ derive_group_id(target)
+ except ValueError as exc:
+ raise HTTPException(status_code=400, detail=str(exc))
+
+ try:
+ result = await get_scheduler_client().execute_ratification_pass_now(
+ user_id=target
+ )
+ except Exception as exc:
+ logger.warning(
+ "Admin-triggered ratification pass failed for user %s: %s",
+ target[:12],
+ exc,
+ )
+ raise HTTPException(
+ status_code=500,
+ detail=f"Ratification pass failed: {type(exc).__name__}: {exc}",
+ )
+ return RatificationResult.model_validate(result)
+
+
+ "/{user_id}/nightly",
+ response_model=JobTriggerResponse,
+ status_code=202,
+)
+async def trigger_nightly_batch(
+ request: Request,
+ user_id: Annotated[str, Path(description="User id or 'me'")],
+ caller_id: Annotated[str, Depends(get_user_id)],
+ jwt_payload: Annotated[dict, Security(get_jwt_payload)],
+) -> JSONResponse:
+ """Fire the full nightly batch fan-out and return 202 + job_id immediately.
+
+ Frontend polls ``GET /api/admin/memory/{user_id}/nightly/{job_id}``
+ for progress. Same composition as the 03:00 cron — every enabled
+ batch-family submitter runs in sequence sharing one ``nightly_id``
+ for cost-log attribution.
+ """
+ target = _resolve_user_id(user_id, caller_id)
+ _audit_cross_user_access(
+ request=request,
+ caller_id=caller_id,
+ target_id=target,
+ jwt_payload=jwt_payload,
+ )
+ try:
+ derive_group_id(target)
+ except ValueError as exc:
+ raise HTTPException(status_code=400, detail=str(exc))
+
+ job_id = str(_uuid.uuid4())
+ status = await write_initial_status(kind="nightly", job_id=job_id, user_id=target)
+
+ try:
+ await get_scheduler_client().schedule_immediate_nightly_batch(
+ user_id=target, job_id=job_id
+ )
+ except Exception as exc:
+ logger.warning(
+ "Failed to schedule nightly batch %s for user %s: %s",
+ job_id[:12],
+ target[:12],
+ exc,
+ )
+ await _mark_schedule_failed("nightly", job_id, exc)
+ raise HTTPException(
+ status_code=500,
+ detail=f"Nightly batch scheduling failed: {type(exc).__name__}: {exc}",
+ )
+
+ payload = JobTriggerResponse(
+ job_id=status.job_id,
+ user_id=status.user_id,
+ kind=status.kind,
+ state=status.state,
+ started_at=status.started_at,
+ )
+ return JSONResponse(status_code=202, content=payload.model_dump(mode="json"))
+
+
+ "/{user_id}/nightly/{job_id}",
+ response_model=NightlyJobStatus,
+)
+async def get_nightly_batch_status(
+ request: Request,
+ user_id: Annotated[str, Path(description="User id or 'me'")],
+ job_id: Annotated[str, Path(description="Job id returned by the POST")],
+ caller_id: Annotated[str, Depends(get_user_id)],
+ jwt_payload: Annotated[dict, Security(get_jwt_payload)],
+) -> NightlyJobStatus:
+ """Read the current status of a fire-and-forget nightly batch job."""
+ target = _resolve_user_id(user_id, caller_id)
+ _audit_cross_user_access(
+ request=request,
+ caller_id=caller_id,
+ target_id=target,
+ jwt_payload=jwt_payload,
+ )
+ status = await read_status(kind="nightly", job_id=job_id)
+ if status is None:
+ raise HTTPException(status_code=404, detail="job not found")
+ if status.user_id != target:
+ raise HTTPException(status_code=403, detail="job belongs to a different user")
+ return NightlyJobStatus.model_validate(status.model_dump())
+
+
+ "/{user_id}/communities/rebuild",
+ response_model=JobTriggerResponse,
+ status_code=202,
+)
+async def rebuild_communities(
+ request: Request,
+ user_id: Annotated[str, Path(description="User id or 'me'")],
+ caller_id: Annotated[str, Depends(get_user_id)],
+ jwt_payload: Annotated[dict, Security(get_jwt_payload)],
+ force: Annotated[
+ bool,
+ Query(
+ description=(
+ "Reserved — the fire-and-forget wrapper currently always "
+ "honours the activity gate. Kept on the signature so the "
+ "frontend hook doesn't need a contract change when the "
+ "force flag is threaded through to the wrapper."
+ )
+ ),
+ ] = False,
+) -> JSONResponse:
+ """Fire a community rebuild and return 202 + job_id immediately.
+
+ Frontend polls
+ ``GET /api/admin/memory/{user_id}/communities/rebuild/{job_id}``
+ for progress.
+ """
+ _ = force # not yet plumbed through the with_status wrapper
+ target = _resolve_user_id(user_id, caller_id)
+ _audit_cross_user_access(
+ request=request,
+ caller_id=caller_id,
+ target_id=target,
+ jwt_payload=jwt_payload,
+ )
+ try:
+ derive_group_id(target)
+ except ValueError as exc:
+ raise HTTPException(status_code=400, detail=str(exc))
+
+ job_id = str(_uuid.uuid4())
+ status = await write_initial_status(kind="rebuild", job_id=job_id, user_id=target)
+
+ try:
+ await get_scheduler_client().schedule_immediate_community_rebuild(
+ user_id=target, job_id=job_id
+ )
+ except Exception as exc:
+ logger.warning(
+ "Failed to schedule community rebuild %s for user %s: %s",
+ job_id[:12],
+ target[:12],
+ exc,
+ )
+ await _mark_schedule_failed("rebuild", job_id, exc)
+ raise HTTPException(
+ status_code=500,
+ detail=(
+ f"Community rebuild scheduling failed: " f"{type(exc).__name__}: {exc}"
+ ),
+ )
+
+ payload = JobTriggerResponse(
+ job_id=status.job_id,
+ user_id=status.user_id,
+ kind=status.kind,
+ state=status.state,
+ started_at=status.started_at,
+ )
+ return JSONResponse(status_code=202, content=payload.model_dump(mode="json"))
+
+
+ "/{user_id}/communities/rebuild/{job_id}",
+ response_model=CommunityRebuildJobStatus,
+)
+async def get_community_rebuild_status(
+ request: Request,
+ user_id: Annotated[str, Path(description="User id or 'me'")],
+ job_id: Annotated[str, Path(description="Job id returned by the POST")],
+ caller_id: Annotated[str, Depends(get_user_id)],
+ jwt_payload: Annotated[dict, Security(get_jwt_payload)],
+) -> CommunityRebuildJobStatus:
+ """Read the current status of a fire-and-forget community rebuild job."""
+ target = _resolve_user_id(user_id, caller_id)
+ _audit_cross_user_access(
+ request=request,
+ caller_id=caller_id,
+ target_id=target,
+ jwt_payload=jwt_payload,
+ )
+ status = await read_status(kind="rebuild", job_id=job_id)
+ if status is None:
+ raise HTTPException(status_code=404, detail="job not found")
+ if status.user_id != target:
+ raise HTTPException(status_code=403, detail="job belongs to a different user")
+ return CommunityRebuildJobStatus.model_validate(status.model_dump())
diff --git a/autogpt_platform/backend/backend/api/features/admin/memory_admin_routes_test.py b/autogpt_platform/backend/backend/api/features/admin/memory_admin_routes_test.py
new file mode 100644
index 0000000000..2659d52b4a
--- /dev/null
+++ b/autogpt_platform/backend/backend/api/features/admin/memory_admin_routes_test.py
@@ -0,0 +1,382 @@
+"""Tests for the admin memory inspector routes."""
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import fastapi
+import fastapi.testclient
+import pytest
+from autogpt_libs.auth.jwt_utils import get_jwt_payload
+from redis.exceptions import ResponseError
+
+from .memory_admin_routes import router as memory_admin_router
+
+app = fastapi.FastAPI()
+app.include_router(memory_admin_router)
+
+client = fastapi.testclient.TestClient(app)
+
+_MOCK_MODULE = "backend.api.features.admin.memory_admin_routes"
+
+
[email protected](autouse=True)
+def setup_app_admin_auth(mock_jwt_admin):
+ """Admin auth override for all tests in this module."""
+ app.dependency_overrides[get_jwt_payload] = mock_jwt_admin["get_jwt_payload"]
+ yield
+ app.dependency_overrides.clear()
+
+
+def _driver_returning(*query_results) -> AsyncMock:
+ """Build a mocked AutoGPTFalkorDriver whose ``execute_query`` returns
+ each value in turn (one per call)."""
+ driver = AsyncMock()
+ driver.execute_query.side_effect = [(r, None, None) for r in query_results]
+ driver.close = AsyncMock()
+ return driver
+
+
+class TestOverview:
+ def test_returns_counts_for_all_node_types(self) -> None:
+ # Returns one row per count query in order: entities, episodes,
+ # relates_to, mentions, communities.
+ driver = _driver_returning(
+ [{"c": 107}], # entities
+ [{"c": 36}], # episodes
+ [{"c": 104}], # relates_to
+ [{"c": 153}], # mentions
+ [{"c": 30}], # communities
+ )
+ with patch(f"{_MOCK_MODULE}._open_driver", return_value=driver):
+ resp = client.get("/admin/memory/abc/overview")
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["user_id"] == "abc"
+ assert body["group_id"] == "user_abc"
+ assert body["entities"] == 107
+ assert body["episodes"] == 36
+ assert body["relates_to_edges"] == 104
+ assert body["mentions_edges"] == 153
+ assert body["communities"] == 30
+ # Driver must be closed even on success
+ driver.close.assert_awaited_once()
+
+ def test_me_resolves_to_caller_id(self, mock_jwt_admin) -> None:
+ driver = _driver_returning(
+ [{"c": 0}], [{"c": 0}], [{"c": 0}], [{"c": 0}], [{"c": 0}]
+ )
+ with patch(f"{_MOCK_MODULE}._open_driver", return_value=driver):
+ resp = client.get("/admin/memory/me/overview")
+ assert resp.status_code == 200
+ body = resp.json()
+ # 'me' resolved to the caller's admin_user_id from mock_jwt_admin
+ assert body["user_id"] == mock_jwt_admin["user_id"]
+
+ def test_invalid_user_id_returns_400(self) -> None:
+ resp = client.get("/admin/memory/!!!invalid!!!/overview")
+ assert resp.status_code == 400
+
+ def test_missing_graph_returns_zeros(self) -> None:
+ # Simulate the FalkorDB error for a database that doesn't exist yet.
+ driver = AsyncMock()
+ driver.execute_query.side_effect = ResponseError(
+ "Invalid graph operation on empty key"
+ )
+ driver.close = AsyncMock()
+ with patch(f"{_MOCK_MODULE}._open_driver", return_value=driver):
+ resp = client.get("/admin/memory/abc/overview")
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["entities"] == 0
+ assert body["communities"] == 0
+
+ def test_unexpected_cypher_error_propagates(self) -> None:
+ """A Cypher typo / unrelated FalkorDB error must NOT be swallowed
+ as a zero count — admins need to see the failure."""
+ driver = AsyncMock()
+ driver.execute_query.side_effect = ResponseError("syntax error near 'MATHC'")
+ driver.close = AsyncMock()
+ # Surface the underlying exception instead of letting the test
+ # client convert it to a 500 — we want to assert the exact type
+ # propagated past _count.
+ bare_client = fastapi.testclient.TestClient(app, raise_server_exceptions=True)
+ with patch(f"{_MOCK_MODULE}._open_driver", return_value=driver):
+ with pytest.raises(ResponseError, match="MATHC"):
+ bare_client.get("/admin/memory/abc/overview")
+ # Driver must still be closed even when the query blows up.
+ driver.close.assert_awaited_once()
+
+ def test_non_response_error_propagates(self) -> None:
+ """Non-FalkorDB exceptions (e.g. a programming TypeError) must not
+ be silently zeroed."""
+ driver = AsyncMock()
+ driver.execute_query.side_effect = TypeError("bad query param")
+ driver.close = AsyncMock()
+ bare_client = fastapi.testclient.TestClient(app, raise_server_exceptions=True)
+ with patch(f"{_MOCK_MODULE}._open_driver", return_value=driver):
+ with pytest.raises(TypeError, match="bad query param"):
+ bare_client.get("/admin/memory/abc/overview")
+ driver.close.assert_awaited_once()
+
+
+class TestListEntities:
+ def test_returns_entity_summaries(self) -> None:
+ driver = _driver_returning(
+ [
+ {"uuid": "e1", "name": "Alice", "summary": "engineer"},
+ {"uuid": "e2", "name": "Atlas", "summary": None},
+ ]
+ )
+ with patch(f"{_MOCK_MODULE}._open_driver", return_value=driver):
+ resp = client.get("/admin/memory/abc/entities?limit=10")
+ assert resp.status_code == 200
+ items = resp.json()["items"]
+ assert len(items) == 2
+ assert items[0]["name"] == "Alice"
+ assert items[1]["summary"] is None
+
+ def test_limit_above_cap_rejected_with_422(self) -> None:
+ """The entities route caps ``limit`` at 10000 via FastAPI Query
+ validation. Anything beyond gets a 422 — not a 500 from a runaway
+ Cypher LIMIT clause."""
+ resp = client.get("/admin/memory/abc/entities?limit=10001")
+ assert resp.status_code == 422
+
+
+class TestListFacts:
+ def test_default_returns_any_status(self) -> None:
+ driver = _driver_returning(
+ [
+ {
+ "uuid": "e1",
+ "source": "Alice",
+ "target": "Atlas",
+ "name": "works_on",
+ "fact": "Alice works on Atlas",
+ "status": "active",
+ "scope": "real:global",
+ "confidence": 0.9,
+ "created_at": "2026-05-19T10:00:00Z",
+ "expired_at": None,
+ }
+ ]
+ )
+ with patch(f"{_MOCK_MODULE}._open_driver", return_value=driver):
+ resp = client.get("/admin/memory/abc/facts")
+ assert resp.status_code == 200
+ # No status filter applied → query shouldn't include WHERE on status
+ call_query = driver.execute_query.call_args.args[0]
+ assert "e.status = $status" not in call_query
+ assert resp.json()["items"][0]["source"] == "Alice"
+
+ def test_status_filter_passed_to_cypher(self) -> None:
+ driver = _driver_returning([])
+ with patch(f"{_MOCK_MODULE}._open_driver", return_value=driver):
+ resp = client.get(
+ "/admin/memory/abc/facts?status=superseded&scope=project:atlas"
+ )
+ assert resp.status_code == 200
+ kwargs = driver.execute_query.call_args.kwargs
+ assert kwargs["status"] == "superseded"
+ assert kwargs["scope"] == "project:atlas"
+
+ def test_status_must_be_valid_enum(self) -> None:
+ resp = client.get("/admin/memory/abc/facts?status=garbage")
+ assert resp.status_code == 422
+
+
+class TestListCommunities:
+ def test_returns_community_summaries(self) -> None:
+ driver = _driver_returning(
+ [
+ {
+ "uuid": "c1",
+ "name": "Card art",
+ "summary": "MTG card illustrations",
+ "member_count": 7,
+ },
+ {
+ "uuid": "c2",
+ "name": "Engineering",
+ "summary": "Software work",
+ "member_count": 4,
+ },
+ ]
+ )
+ with patch(f"{_MOCK_MODULE}._open_driver", return_value=driver):
+ resp = client.get("/admin/memory/abc/communities?limit=10")
+ assert resp.status_code == 200
+ items = resp.json()["items"]
+ assert len(items) == 2
+ # Member counts come through correctly
+ assert items[0]["member_count"] == 7
+
+
+class TestGraph:
+ def test_missing_graph_returns_empty(self) -> None:
+ driver = AsyncMock()
+ driver.execute_query.side_effect = ResponseError("no such graph")
+ driver.close = AsyncMock()
+ with patch(f"{_MOCK_MODULE}._open_driver", return_value=driver):
+ resp = client.get("/admin/memory/abc/graph")
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["nodes"] == []
+ assert body["edges"] == []
+
+ def test_unexpected_error_propagates(self) -> None:
+ """A non-graph-not-found FalkorDB error must surface, not be
+ hidden behind an empty graph payload."""
+ driver = AsyncMock()
+ driver.execute_query.side_effect = ResponseError("syntax error near 'MATHC'")
+ driver.close = AsyncMock()
+ bare_client = fastapi.testclient.TestClient(app, raise_server_exceptions=True)
+ with patch(f"{_MOCK_MODULE}._open_driver", return_value=driver):
+ with pytest.raises(ResponseError, match="MATHC"):
+ bare_client.get("/admin/memory/abc/graph")
+ driver.close.assert_awaited_once()
+
+
+class TestRebuildCommunitiesPolling:
+ """POST /communities/rebuild is now fire-and-forget.
+
+ It writes a JobStatus row, kicks off the scheduler via
+ ``schedule_immediate_community_rebuild``, and returns 202 +
+ job_id immediately. Frontend polls the GET endpoint to read
+ progress; the work body fires asynchronously on the scheduler
+ thread pool.
+ """
+
+ def test_returns_202_with_job_id(self) -> None:
+ scheduler = MagicMock()
+ scheduler.schedule_immediate_community_rebuild = AsyncMock(
+ return_value={"scheduled": True, "job_id": "x", "kind": "rebuild"}
+ )
+ with patch(
+ f"{_MOCK_MODULE}.get_scheduler_client", return_value=scheduler
+ ), patch(
+ f"{_MOCK_MODULE}.write_initial_status",
+ new=_make_fake_initial_status("rebuild"),
+ ):
+ resp = client.post("/admin/memory/abc/communities/rebuild")
+ assert resp.status_code == 202
+ body = resp.json()
+ assert body["kind"] == "rebuild"
+ assert body["state"] == "queued"
+ assert body["user_id"] == "abc"
+ assert isinstance(body["job_id"], str)
+ scheduler.schedule_immediate_community_rebuild.assert_awaited_once()
+ # The job_id passed to the scheduler must match the one returned.
+ call_kwargs = scheduler.schedule_immediate_community_rebuild.call_args.kwargs
+ assert call_kwargs["job_id"] == body["job_id"]
+ assert call_kwargs["user_id"] == "abc"
+
+ def test_scheduler_failure_marks_errored_and_returns_500(self) -> None:
+ scheduler = MagicMock()
+ scheduler.schedule_immediate_community_rebuild = AsyncMock(
+ side_effect=RuntimeError("scheduler unreachable")
+ )
+ mark_errored = AsyncMock()
+ with patch(
+ f"{_MOCK_MODULE}.get_scheduler_client", return_value=scheduler
+ ), patch(
+ f"{_MOCK_MODULE}.write_initial_status",
+ new=_make_fake_initial_status("rebuild"),
+ ), patch(
+ f"{_MOCK_MODULE}.mark_errored", mark_errored
+ ):
+ resp = client.post("/admin/memory/abc/communities/rebuild")
+ assert resp.status_code == 500
+ assert "scheduler unreachable" in resp.json()["detail"]
+ # The just-queued JobStatus must be flipped to errored, not left
+ # stuck on 'queued' for a job the scheduler never picked up.
+ mark_errored.assert_awaited_once()
+ assert mark_errored.call_args.kwargs["kind"] == "rebuild"
+
+
+class TestTriggerStatusGetEndpoints:
+ """Each trigger has a paired GET that reads the JobStatus row."""
+
+ def test_status_returns_404_for_unknown_job(self) -> None:
+ with patch(f"{_MOCK_MODULE}.read_status", new=AsyncMock(return_value=None)):
+ resp = client.get("/admin/memory/abc/nightly/missing-job-id")
+ assert resp.status_code == 404
+
+ def test_status_returns_403_when_user_mismatches(self) -> None:
+ # A job owned by a different user must not be visible.
+ status = _fake_status_row("nightly", "owned-by-someone-else")
+ with patch(f"{_MOCK_MODULE}.read_status", new=AsyncMock(return_value=status)):
+ resp = client.get("/admin/memory/abc/nightly/job-1")
+ assert resp.status_code == 403
+
+ def test_status_returns_job_row_for_owner(self) -> None:
+ status = _fake_status_row("nightly", "abc")
+ with patch(f"{_MOCK_MODULE}.read_status", new=AsyncMock(return_value=status)):
+ resp = client.get("/admin/memory/abc/nightly/job-1")
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["user_id"] == "abc"
+ assert body["kind"] == "nightly"
+ assert body["state"] == "queued"
+
+ def test_each_kind_has_its_own_status_endpoint(self) -> None:
+ """Pin the URL structure: nightly, dream, communities/rebuild
+ each have a GET .../{job_id} sibling to their POST."""
+ for kind, url in [
+ ("nightly", "/admin/memory/abc/nightly/job-1"),
+ ("dream_pass", "/admin/memory/abc/dream/job-1"),
+ ("rebuild", "/admin/memory/abc/communities/rebuild/job-1"),
+ ]:
+ status = _fake_status_row(kind, "abc")
+ with patch(
+ f"{_MOCK_MODULE}.read_status",
+ new=AsyncMock(return_value=status),
+ ):
+ resp = client.get(url)
+ assert resp.status_code == 200, url
+ assert resp.json()["kind"] == kind
+
+
+def _make_fake_initial_status(kind: str):
+ """A ``write_initial_status`` replacement that returns a fake
+ ``JobStatus`` matching the requested kind + caller's user_id."""
+
+ async def fake(*, kind: str, job_id: str, user_id: str):
+ return _fake_status_row(kind, user_id, job_id=job_id)
+
+ return fake
+
+
+def _fake_status_row(kind: str, user_id: str, job_id: str = "job-1"):
+ from datetime import datetime, timezone
+
+ from backend.copilot.dream.job_status import JobStatus
+
+ now = datetime.now(timezone.utc)
+ return JobStatus(
+ job_id=job_id,
+ user_id=user_id,
+ kind=kind,
+ state="queued",
+ started_at=now,
+ updated_at=now,
+ )
+
+
+class TestAdminGating:
+ """Non-admin callers must get 403 on every route."""
+
+ def test_non_admin_gets_403(self, mock_jwt_user) -> None:
+ # Swap to the non-admin user fixture; the autouse setup_app_admin_auth
+ # fixture restores admin auth (clears overrides) on teardown, so no
+ # manual reset is needed.
+ app.dependency_overrides[get_jwt_payload] = mock_jwt_user["get_jwt_payload"]
+ for path in [
+ "/admin/memory/abc/overview",
+ "/admin/memory/abc/entities",
+ "/admin/memory/abc/facts",
+ "/admin/memory/abc/communities",
+ ]:
+ resp = client.get(path)
+ assert resp.status_code == 403, path
+ resp = client.post("/admin/memory/abc/communities/rebuild")
+ assert resp.status_code == 403
diff --git a/autogpt_platform/backend/backend/api/features/admin/platform_cost_routes.py b/autogpt_platform/backend/backend/api/features/admin/platform_cost_routes.py
index 048c4ae07e..4727453155 100644
--- a/autogpt_platform/backend/backend/api/features/admin/platform_cost_routes.py
+++ b/autogpt_platform/backend/backend/api/features/admin/platform_cost_routes.py
@@ -75,6 +75,21 @@ async def get_cost_logs(
block_name: str | None = Query(None),
tracking_type: str | None = Query(None),
graph_exec_id: str | None = Query(None),
+ execution_path: str | None = Query(
+ None,
+ description=(
+ "Filter on metadata.execution_path (e.g. 'anthropic_batch', "
+ "'sync_baseline', 'flex'). Lets admins narrow rows to a single "
+ "dispatch mode for cost-savings audits."
+ ),
+ ),
+ source: str | None = Query(
+ None,
+ description=(
+ "Filter on metadata.source (e.g. 'dream_pass', 'copilot'). "
+ "Distinguishes background/system spend from interactive."
+ ),
+ ),
):
logger.info("Admin %s fetching platform cost logs", admin_user_id)
logs, total = await get_platform_cost_logs(
@@ -88,6 +103,8 @@ async def get_cost_logs(
block_name=block_name,
tracking_type=tracking_type,
graph_exec_id=graph_exec_id,
+ execution_path=execution_path,
+ source=source,
)
total_pages = (total + page_size - 1) // page_size
return PlatformCostLogsResponse(
@@ -122,6 +139,8 @@ async def export_cost_logs(
block_name: str | None = Query(None),
tracking_type: str | None = Query(None),
graph_exec_id: str | None = Query(None),
+ execution_path: str | None = Query(None),
+ source: str | None = Query(None),
):
logger.info("Admin %s exporting platform cost logs", admin_user_id)
logs, truncated = await get_platform_cost_logs_for_export(
@@ -133,6 +152,8 @@ async def export_cost_logs(
block_name=block_name,
tracking_type=tracking_type,
graph_exec_id=graph_exec_id,
+ execution_path=execution_path,
+ source=source,
)
return PlatformCostExportResponse(
logs=logs,
diff --git a/autogpt_platform/backend/backend/api/rest_api.py b/autogpt_platform/backend/backend/api/rest_api.py
index 9afd323c33..dba0bc8406 100644
--- a/autogpt_platform/backend/backend/api/rest_api.py
+++ b/autogpt_platform/backend/backend/api/rest_api.py
@@ -21,6 +21,7 @@ import backend.api.features.admin.bot_analytics_routes
import backend.api.features.admin.credit_admin_routes
import backend.api.features.admin.diagnostics_admin_routes
import backend.api.features.admin.execution_analytics_routes
+import backend.api.features.admin.memory_admin_routes
import backend.api.features.admin.platform_cost_routes
import backend.api.features.admin.rate_limit_admin_routes
import backend.api.features.admin.store_admin_routes
@@ -378,6 +379,11 @@ app.include_router(
tags=["v2", "admin"],
prefix="/api",
)
+app.include_router(
+ backend.api.features.admin.memory_admin_routes.router,
+ tags=["v2", "admin"],
+ prefix="/api",
+)
app.include_router(
backend.api.features.executions.review.routes.router,
tags=["v2", "executions", "review"],
diff --git a/autogpt_platform/backend/backend/app.py b/autogpt_platform/backend/backend/app.py
index 314d266e8f..68eac98ff7 100644
--- a/autogpt_platform/backend/backend/app.py
+++ b/autogpt_platform/backend/backend/app.py
@@ -42,12 +42,20 @@ def main(**kwargs):
from backend.copilot.executor.manager import CoPilotExecutor
from backend.data.db_manager import DatabaseManager
from backend.executor import ExecutionManager, Scheduler
+ from backend.executor.batch_executor import BatchExecutor
from backend.notifications import NotificationManager
from backend.platform_linking.manager import PlatformLinkingManager
run_processes(
DatabaseManager().set_log_level("warning"),
Scheduler(),
+ # BatchExecutor polls submitted LLM batches (Anthropic today) and
+ # dispatches results to caller-registered namespace handlers.
+ # The dream pass uses it when an anthropic key is configured;
+ # falls back to sync_baseline otherwise. Own subprocess so a
+ # slow Anthropic batch poll never starves the Scheduler's cron
+ # tick.
+ BatchExecutor(),
NotificationManager(),
PlatformLinkingManager(),
WebsocketServer(),
diff --git a/autogpt_platform/backend/backend/blocks/llm.py b/autogpt_platform/backend/backend/blocks/llm.py
index 5bb54e59a9..e5e30e11d6 100644
--- a/autogpt_platform/backend/backend/blocks/llm.py
+++ b/autogpt_platform/backend/backend/blocks/llm.py
@@ -12,13 +12,9 @@ from json import JSONDecodeError
from typing import Any, Iterable, List, Literal, NamedTuple, Optional, cast
import anthropic
-import ollama
import openai
from anthropic.types import ToolParam
-from groq import AsyncGroq
from openai.types.chat import ChatCompletion as OpenAIChatCompletion
-from openai.types.chat import ChatCompletionMessageParam, ChatCompletionToolParam
-from openai.types.shared_params import ResponseFormatJSONObject
from pydantic import BaseModel, SecretStr
from backend.blocks._base import (
@@ -37,17 +33,15 @@ from backend.data.model import (
)
from backend.integrations.providers import ProviderName
from backend.util import json
-from backend.util.clients import OPENROUTER_BASE_URL
+
+# ``ToolCall`` and ``ToolContentBlock`` live in the shared
+# ``util.llm.conversions`` module so every LLM caller (block layer,
+# dream pass, copilot chat) references one canonical type. Re-export
+# them here so existing ``from backend.blocks.llm import
+# ToolContentBlock`` imports keep working.
+from backend.util.llm.conversions import ToolCall, ToolContentBlock
from backend.util.logging import TruncatedLogger
-from backend.util.openai_responses import (
- convert_tools_to_responses_format,
- extract_responses_content,
- extract_responses_reasoning,
- extract_responses_tool_calls,
- extract_responses_usage,
-)
from backend.util.prompt import compress_context, estimate_token_count
-from backend.util.request import validate_url_host
from backend.util.settings import Settings
from backend.util.text import TextFormatter
@@ -738,17 +732,6 @@ for model in LlmModel:
raise ValueError(f"Missing MODEL_METADATA metadata for model: {model}")
-class ToolCall(BaseModel):
- name: str
- arguments: str
-
-
-class ToolContentBlock(BaseModel):
- id: str
- type: str
- function: ToolCall
-
-
class LLMResponse(BaseModel):
raw_response: Any
prompt: List[Any]
@@ -971,379 +954,53 @@ async def _llm_call(
available_tokens = max(context_window - estimated_input_tokens, 0)
max_tokens = max(min(available_tokens, model_max_output, user_max), 1)
- if provider == "openai":
- oai_client = openai.AsyncOpenAI(api_key=credentials.api_key.get_secret_value())
-
- tools_param = convert_tools_to_responses_format(tools) if tools else openai.omit
-
- text_config = openai.omit
- if force_json_output:
- text_config = {"format": {"type": "json_object"}} # type: ignore
-
- response = await oai_client.responses.create(
- model=llm_model.value,
- input=prompt, # type: ignore[arg-type]
- tools=tools_param, # type: ignore[arg-type]
- max_output_tokens=max_tokens,
- parallel_tool_calls=get_parallel_tool_calls_param(
- llm_model, parallel_tool_calls
- ),
- text=text_config, # type: ignore[arg-type]
- store=False,
- timeout=LLM_REQUEST_TIMEOUT_SECONDS,
- )
-
- raw_tool_calls = extract_responses_tool_calls(response)
- tool_calls = (
- [
- ToolContentBlock(
- id=tc["id"],
- type=tc["type"],
- function=ToolCall(
- name=tc["function"]["name"],
- arguments=tc["function"]["arguments"],
- ),
- )
- for tc in raw_tool_calls
- ]
- if raw_tool_calls
- else None
- )
- reasoning = extract_responses_reasoning(response)
- content = extract_responses_content(response)
- prompt_tokens, completion_tokens = extract_responses_usage(response)
-
- return LLMResponse(
- raw_response=response,
- prompt=prompt,
- response=content,
- tool_calls=tool_calls,
- prompt_tokens=prompt_tokens,
- completion_tokens=completion_tokens,
- reasoning=reasoning,
- )
- elif provider == "anthropic":
- an_tools = convert_openai_tool_fmt_to_anthropic(tools)
- # Cache tool definitions alongside the system prompt.
- # Placing cache_control on the last tool caches all tool schemas as a
- # single prefix — reads cost 10% of normal input tokens.
- if isinstance(an_tools, list) and an_tools:
- an_tools[-1] = {**an_tools[-1], "cache_control": {"type": "ephemeral"}}
-
- system_messages = [p["content"] for p in prompt if p["role"] == "system"]
- sysprompt = " ".join(system_messages)
-
- messages = []
- last_role = None
- for p in prompt:
- if p["role"] in ["user", "assistant"]:
- if (
- p["role"] == last_role
- and isinstance(messages[-1]["content"], str)
- and isinstance(p["content"], str)
- ):
- # If the role is the same as the last one, combine the content
- messages[-1]["content"] += p["content"]
- else:
- messages.append({"role": p["role"], "content": p["content"]})
- last_role = p["role"]
-
- client = anthropic.AsyncAnthropic(
- api_key=credentials.api_key.get_secret_value()
- )
- # create_kwargs is built as a plain dict so we can conditionally add
- # the `system` field only when the prompt is non-empty. Anthropic's
- # API rejects empty text blocks (returns HTTP 400), so omitting the
- # field is the correct behaviour for whitespace-only prompts.
- create_kwargs: dict[str, Any] = dict(
- model=llm_model.value,
- messages=messages,
- max_tokens=max_tokens,
- # `an_tools` may be anthropic.NOT_GIVEN when no tools were
- # configured. The SDK treats NOT_GIVEN as a sentinel meaning "omit
- # this field from the serialized request", so passing it here is
- # equivalent to not including the key at all — no `tools` field is
- # sent to the API in that case.
- tools=an_tools,
- timeout=LLM_REQUEST_TIMEOUT_SECONDS,
- )
- if sysprompt.strip():
- # Wrap the system prompt in a single cacheable text block.
- # The guard intentionally omits `system` for whitespace-only
- # prompts — Anthropic rejects empty text blocks with HTTP 400.
- create_kwargs["system"] = [
- {
- "type": "text",
- "text": sysprompt,
- "cache_control": {"type": "ephemeral"},
- }
- ]
- resp = await client.messages.create(**create_kwargs)
-
- if not resp.content:
- raise ValueError("No content returned from Anthropic.")
-
- tool_calls = None
- for content_block in resp.content:
- # Antropic is different to openai, need to iterate through
- # the content blocks to find the tool calls
- if content_block.type == "tool_use":
- if tool_calls is None:
- tool_calls = []
- tool_calls.append(
- ToolContentBlock(
- id=content_block.id,
- type=content_block.type,
- function=ToolCall(
- name=content_block.name,
- arguments=json.dumps(content_block.input),
- ),
- )
- )
-
- if not tool_calls and resp.stop_reason == "tool_use":
- logger.warning(
- f"Tool use stop reason but no tool calls found in content. {resp}"
- )
-
- reasoning = None
- for content_block in resp.content:
- if hasattr(content_block, "type") and content_block.type == "thinking":
- reasoning = content_block.thinking
- break
-
- return LLMResponse(
- raw_response=resp,
- prompt=prompt,
- response=(
- resp.content[0].name
- if isinstance(resp.content[0], anthropic.types.ToolUseBlock)
- else getattr(resp.content[0], "text", "")
- ),
- tool_calls=tool_calls,
- prompt_tokens=resp.usage.input_tokens,
- completion_tokens=resp.usage.output_tokens,
- cache_read_tokens=getattr(resp.usage, "cache_read_input_tokens", None) or 0,
- cache_creation_tokens=getattr(
- resp.usage, "cache_creation_input_tokens", None
- )
- or 0,
- reasoning=reasoning,
- )
- elif provider == "groq":
- if tools:
- raise ValueError("Groq does not support tools.")
-
- client = AsyncGroq(api_key=credentials.api_key.get_secret_value())
- response_format = {"type": "json_object"} if force_json_output else None
- response = await client.chat.completions.create(
- model=llm_model.value,
- messages=prompt, # type: ignore
- response_format=response_format, # type: ignore
- max_tokens=max_tokens,
- timeout=LLM_REQUEST_TIMEOUT_SECONDS,
- )
- if not response.choices:
- raise ValueError("Groq returned empty choices in response")
- return LLMResponse(
- raw_response=response.choices[0].message,
- prompt=prompt,
- response=response.choices[0].message.content or "",
- tool_calls=None,
- prompt_tokens=response.usage.prompt_tokens if response.usage else 0,
- completion_tokens=response.usage.completion_tokens if response.usage else 0,
- reasoning=None,
- )
- elif provider == "ollama":
- if tools:
- raise ValueError("Ollama does not support tools.")
-
- # Validate user-provided Ollama host to prevent SSRF etc.
- await validate_url_host(
- ollama_host, trusted_hostnames=[settings.config.ollama_host]
- )
-
- client = ollama.AsyncClient(
- host=ollama_host, timeout=LLM_REQUEST_TIMEOUT_SECONDS
- )
- sys_messages = [p["content"] for p in prompt if p["role"] == "system"]
- usr_messages = [p["content"] for p in prompt if p["role"] != "system"]
- response = await client.generate(
- model=llm_model.value,
- prompt=f"{sys_messages}\n\n{usr_messages}",
- stream=False,
- options={"num_ctx": max_tokens},
- )
- return LLMResponse(
- raw_response=response.get("response") or "",
- prompt=prompt,
- response=response.get("response") or "",
- tool_calls=None,
- prompt_tokens=response.get("prompt_eval_count") or 0,
- completion_tokens=response.get("eval_count") or 0,
- reasoning=None,
- )
- elif provider == "open_router":
- client = openai.AsyncOpenAI(
- base_url=OPENROUTER_BASE_URL,
- api_key=credentials.api_key.get_secret_value(),
- )
-
- parallel_tool_calls_param = get_parallel_tool_calls_param(
+ # ---- Delegate per-provider HTTP to the shared helper ----------------
+ # All per-provider SDK quirks (Anthropic system-prompt wrapping,
+ # OpenRouter cost extras, AI/ML branded headers, Ollama generate
+ # API, etc.) live in ``backend/util/llm/providers.py`` so the dream
+ # pass, copilot chat, and any future server-side caller route
+ # through one implementation. This wrapper keeps the block-layer
+ # framing on top: ``LlmModel``-aware token budget, retry-on-bad-
+ # shape (caller), ``NodeExecutionStats`` (caller).
+ from backend.util.llm.providers import ProviderResponse, call_provider
+
+ provider_response = await call_provider(
+ provider=cast(Any, provider),
+ model=llm_model.value,
+ api_key=credentials.api_key.get_secret_value(),
+ messages=prompt,
+ max_tokens=max_tokens,
+ tools=tools,
+ force_json_output=force_json_output,
+ parallel_tool_calls=get_parallel_tool_calls_param(
llm_model, parallel_tool_calls
- )
-
- response = await client.chat.completions.create(
- extra_headers={
- "HTTP-Referer": "https://agpt.co",
- "X-Title": "AutoGPT",
- },
- # Ask OpenRouter to include the per-request USD cost on the usage
- # object. Same shape used by simulator.py — keep aligned.
- extra_body={"usage": {"include": True}},
- model=llm_model.value,
- messages=cast(list[ChatCompletionMessageParam], prompt),
- max_tokens=max_tokens,
- tools=(
- cast(list[ChatCompletionToolParam], tools) if tools else openai.omit
- ),
- parallel_tool_calls=parallel_tool_calls_param,
- response_format=(
- ResponseFormatJSONObject(type="json_object")
- if force_json_output
- else openai.omit
- ),
- timeout=LLM_REQUEST_TIMEOUT_SECONDS,
- )
-
- if not response.choices:
- raise ValueError(f"OpenRouter returned empty choices: {response}")
-
- tool_calls = extract_openai_tool_calls(response)
- reasoning = extract_openai_reasoning(response)
-
- return LLMResponse(
- raw_response=response.choices[0].message,
- prompt=prompt,
- response=response.choices[0].message.content or "",
- tool_calls=tool_calls,
- prompt_tokens=response.usage.prompt_tokens if response.usage else 0,
- completion_tokens=response.usage.completion_tokens if response.usage else 0,
- reasoning=reasoning,
- provider_cost=extract_openrouter_cost(response),
- )
- elif provider == "llama_api":
- tools_param = tools if tools else openai.NOT_GIVEN
- client = openai.AsyncOpenAI(
- base_url="https://api.llama.com/compat/v1/",
- api_key=credentials.api_key.get_secret_value(),
- )
-
- parallel_tool_calls_param = get_parallel_tool_calls_param(
- llm_model, parallel_tool_calls
- )
-
- response = await client.chat.completions.create(
- extra_headers={
- "HTTP-Referer": "https://agpt.co",
- "X-Title": "AutoGPT",
- },
- model=llm_model.value,
- messages=prompt, # type: ignore
- max_tokens=max_tokens,
- tools=tools_param, # type: ignore
- parallel_tool_calls=parallel_tool_calls_param,
- timeout=LLM_REQUEST_TIMEOUT_SECONDS,
- )
-
- if not response.choices:
- raise ValueError(f"Llama API returned empty choices: {response}")
-
- tool_calls = extract_openai_tool_calls(response)
- reasoning = extract_openai_reasoning(response)
-
- return LLMResponse(
- raw_response=response.choices[0].message,
- prompt=prompt,
- response=response.choices[0].message.content or "",
- tool_calls=tool_calls,
- prompt_tokens=response.usage.prompt_tokens if response.usage else 0,
- completion_tokens=response.usage.completion_tokens if response.usage else 0,
- reasoning=reasoning,
- )
- elif provider == "aiml_api":
- client = openai.AsyncOpenAI(
- base_url="https://api.aimlapi.com/v2",
- api_key=credentials.api_key.get_secret_value(),
- default_headers={
- "X-Project": "AutoGPT",
- "X-Title": "AutoGPT",
- "HTTP-Referer": "https://github.com/Significant-Gravitas/AutoGPT",
- },
- )
-
- completion = await client.chat.completions.create(
- model=llm_model.value,
- messages=prompt, # type: ignore
- max_tokens=max_tokens,
- timeout=LLM_REQUEST_TIMEOUT_SECONDS,
- )
- if not completion.choices:
- raise ValueError("AI/ML API returned empty choices in response")
-
- return LLMResponse(
- raw_response=completion.choices[0].message,
- prompt=prompt,
- response=completion.choices[0].message.content or "",
- tool_calls=None,
- prompt_tokens=completion.usage.prompt_tokens if completion.usage else 0,
- completion_tokens=(
- completion.usage.completion_tokens if completion.usage else 0
- ),
- reasoning=None,
- )
- elif provider == "v0":
- tools_param = tools if tools else openai.NOT_GIVEN
- client = openai.AsyncOpenAI(
- base_url="https://api.v0.dev/v1",
- api_key=credentials.api_key.get_secret_value(),
- )
-
- response_format = None
- if force_json_output:
- response_format = {"type": "json_object"}
-
- parallel_tool_calls_param = get_parallel_tool_calls_param(
- llm_model, parallel_tool_calls
- )
-
- response = await client.chat.completions.create(
- model=llm_model.value,
- messages=prompt, # type: ignore
- response_format=response_format, # type: ignore
- max_tokens=max_tokens,
- tools=tools_param, # type: ignore
- parallel_tool_calls=parallel_tool_calls_param,
- timeout=LLM_REQUEST_TIMEOUT_SECONDS,
- )
-
- if not response.choices:
- raise ValueError(f"v0 API returned empty choices: {response}")
-
- tool_calls = extract_openai_tool_calls(response)
- reasoning = extract_openai_reasoning(response)
-
- return LLMResponse(
- raw_response=response.choices[0].message,
- prompt=prompt,
- response=response.choices[0].message.content or "",
- tool_calls=tool_calls,
- prompt_tokens=response.usage.prompt_tokens if response.usage else 0,
- completion_tokens=response.usage.completion_tokens if response.usage else 0,
- reasoning=reasoning,
- )
- else:
- raise ValueError(f"Unsupported LLM provider: {provider}")
+ ),
+ ollama_host=ollama_host,
+ timeout_seconds=LLM_REQUEST_TIMEOUT_SECONDS,
+ )
+ # Block layer never opts into batch mode (that lives on the
+ # orchestrator side for the dream pass and any future async
+ # callers). The default ``execution_mode="sync"`` is hardcoded
+ # above, so the helper always returns a ``ProviderResponse`` here.
+ # The isinstance guard narrows the union for the type checker.
+ if not isinstance(provider_response, ProviderResponse):
+ raise RuntimeError(
+ "block-layer _llm_call only supports execution_mode='sync' but "
+ f"call_provider returned {type(provider_response).__name__}"
+ )
+
+ return LLMResponse(
+ raw_response=provider_response.raw_response,
+ prompt=prompt,
+ response=provider_response.content,
+ tool_calls=provider_response.tool_calls,
+ prompt_tokens=provider_response.prompt_tokens,
+ completion_tokens=provider_response.completion_tokens,
+ cache_read_tokens=provider_response.cache_read_tokens,
+ cache_creation_tokens=provider_response.cache_creation_tokens,
+ reasoning=provider_response.reasoning,
+ provider_cost=provider_response.cost_usd,
+ )
class AIBlockBase(Block, ABC):
diff --git a/autogpt_platform/backend/backend/copilot/baseline/service.py b/autogpt_platform/backend/backend/copilot/baseline/service.py
index fac253fd3c..be4b716b49 100644
--- a/autogpt_platform/backend/backend/copilot/baseline/service.py
+++ b/autogpt_platform/backend/backend/copilot/baseline/service.py
@@ -23,6 +23,7 @@ from typing import TYPE_CHECKING, Any, cast
import orjson
from langfuse import propagate_attributes
from openai import APIConnectionError
+from openai import omit as openai_omit
from openai.types import CompletionUsage
from openai.types.chat import ChatCompletionMessageParam, ChatCompletionToolParam
from opentelemetry import trace as otel_trace
@@ -118,6 +119,7 @@ from backend.copilot.transcript import (
from backend.copilot.transcript_builder import TranscriptBuilder
from backend.util import json as util_json
from backend.util.exceptions import NotFoundError
+from backend.util.llm.providers import call_provider_stream
from backend.util.prompt import (
compress_context,
estimate_token_count,
@@ -821,26 +823,33 @@ async def _baseline_llm_caller(
)
if thinking_param:
extra_body.update(thinking_param)
- create_kwargs: dict[str, Any] = {
- "model": state.model,
- "messages": typed_messages,
- "stream": True,
- "extra_body": extra_body,
- }
- # OR-only: Anthropic's compat endpoint 400s on stream_options; OR embeds cost via it.
- if is_openrouter_transport:
- create_kwargs["stream_options"] = {"include_usage": True}
# Direct: Anthropic requires max_tokens > budget_tokens explicitly; OR injects a default.
+ max_tokens_arg: int | Any = openai_omit
if not is_openrouter_transport and "thinking" in extra_body:
model_max = get_max_output_tokens(state.model)
budget = min(config.claude_agent_max_thinking_tokens, model_max - 1)
extra_body["thinking"]["budget_tokens"] = budget
- create_kwargs["max_tokens"] = min(budget + 4096, model_max)
- if extra_headers:
- create_kwargs["extra_headers"] = extra_headers
- if tools:
- create_kwargs["tools"] = cast(list[ChatCompletionToolParam], list(tools))
- response = await client.chat.completions.create(**create_kwargs)
+ max_tokens_arg = min(budget + 4096, model_max)
+ # Route through the shared providers helper so future provider
+ # work (streaming flex tier, new SDK upgrades) propagates here
+ # without a parallel migration. The pre-built ``client`` is
+ # passed through so the module-level Langfuse-wrapped client
+ # keeps its HTTP connection pool warm across turns.
+ response = await call_provider_stream(
+ client=client,
+ model=state.model,
+ messages=cast(list[dict[str, Any]], typed_messages),
+ extra_body=extra_body,
+ extra_headers=extra_headers,
+ # OR-only: Anthropic's compat endpoint 400s on stream_options; OR embeds cost via it.
+ # Local transport (``is_openrouter_transport == False``) also gets
+ # ``None`` so stricter local backends don't 400 on the extension.
+ stream_options=(
+ {"include_usage": True} if is_openrouter_transport else None
+ ),
+ tools=cast(list[dict[str, Any]] | None, list(tools)) if tools else None,
+ max_tokens=max_tokens_arg,
+ )
tool_calls_by_index: dict[int, dict[str, str]] = {}
# Iterate under an inner try/finally so early exits (cancel, tool-call
diff --git a/autogpt_platform/backend/backend/copilot/config.py b/autogpt_platform/backend/backend/copilot/config.py
index 4283d51f18..8e6e4f430f 100644
--- a/autogpt_platform/backend/backend/copilot/config.py
+++ b/autogpt_platform/backend/backend/copilot/config.py
@@ -16,6 +16,7 @@ from pydantic import (
from pydantic_settings import BaseSettings
from backend.util.clients import OPENROUTER_BASE_URL
+from backend.util.llm.providers import ProviderLiteral
logger = logging.getLogger(__name__)
@@ -102,6 +103,25 @@ class TransportProfile(BaseModel):
# ``provider="open_router"`` row from a local Ollama turn would
# falsely show up as OR spend on the admin dashboard.
cost_log_provider: str
+ # Provider literal that any out-of-chat caller (dream pass, graphiti
+ # memory ingest, future scheduled batch jobs) should pass to
+ # ``backend.util.llm.providers.call_provider``. Maps the transport's
+ # OpenAI-compat / direct-Anthropic / OpenRouter / Ollama endpoint
+ # back into the typed ``ProviderLiteral`` ``call_provider`` accepts.
+ # Read by ``backend.copilot.transport_routing`` to build the actual
+ # provider kwargs; kept on the profile so adding a new transport row
+ # automatically tells dream + graphiti where to dispatch.
+ dispatch_provider: ProviderLiteral
+ # Whether OpenAI's ``service_tier="flex"`` flows end-to-end on this
+ # transport. True only for ``openrouter`` today: OpenRouter forwards
+ # ``extra_body.service_tier`` to OpenAI-backed upstreams and gets the
+ # ~50% discount; OpenAI native would also support it but we don't have
+ # a "direct OpenAI" transport. False on subscription / direct_anthropic
+ # (Anthropic has no flex tier — their cost-saver is batch) and on
+ # ``local`` (Ollama silently ignores ``service_tier`` and there's no
+ # discount to chase). Read by graphiti's flex-client builder to fall
+ # back to the sync client when the active transport can't honour it.
+ supports_flex_tier: bool
_TRANSPORT_PROFILES: dict[TransportName, TransportProfile] = {
@@ -112,6 +132,8 @@ _TRANSPORT_PROFILES: dict[TransportName, TransportProfile] = {
api_key_fallback_envs=(),
inherit_fast_model_for_aux=False,
cost_log_provider="anthropic",
+ dispatch_provider="anthropic",
+ supports_flex_tier=False,
),
"openrouter": TransportProfile(
name="openrouter",
@@ -120,6 +142,8 @@ _TRANSPORT_PROFILES: dict[TransportName, TransportProfile] = {
api_key_fallback_envs=("OPEN_ROUTER_API_KEY", "OPENAI_API_KEY"),
inherit_fast_model_for_aux=False,
cost_log_provider="open_router",
+ dispatch_provider="open_router",
+ supports_flex_tier=True,
),
"direct_anthropic": TransportProfile(
name="direct_anthropic",
@@ -128,6 +152,8 @@ _TRANSPORT_PROFILES: dict[TransportName, TransportProfile] = {
api_key_fallback_envs=("OPEN_ROUTER_API_KEY", "OPENAI_API_KEY"),
inherit_fast_model_for_aux=False,
cost_log_provider="anthropic",
+ dispatch_provider="anthropic",
+ supports_flex_tier=False,
),
"local": TransportProfile(
name="local",
@@ -136,6 +162,8 @@ _TRANSPORT_PROFILES: dict[TransportName, TransportProfile] = {
api_key_fallback_envs=(),
inherit_fast_model_for_aux=True,
cost_log_provider="ollama",
+ dispatch_provider="ollama",
+ supports_flex_tier=False,
),
}
diff --git a/autogpt_platform/backend/backend/copilot/config_test.py b/autogpt_platform/backend/backend/copilot/config_test.py
index 627642afcc..dd4987a69c 100644
--- a/autogpt_platform/backend/backend/copilot/config_test.py
+++ b/autogpt_platform/backend/backend/copilot/config_test.py
@@ -431,6 +431,8 @@ class TestTransportProfile:
assert p.api_key_fallback_envs == ()
assert p.inherit_fast_model_for_aux is True
assert p.cost_log_provider == "ollama"
+ assert p.dispatch_provider == "ollama"
+ assert p.supports_flex_tier is False
def test_openrouter_profile_shape(self):
cfg = ChatConfig(
@@ -446,6 +448,8 @@ class TestTransportProfile:
assert "OPENAI_API_KEY" in p.api_key_fallback_envs
assert p.inherit_fast_model_for_aux is False
assert p.cost_log_provider == "open_router"
+ assert p.dispatch_provider == "open_router"
+ assert p.supports_flex_tier is True
def test_subscription_profile_shape(self):
cfg = _make_direct_safe_config(use_claude_code_subscription=True)
@@ -456,6 +460,8 @@ class TestTransportProfile:
assert p.api_key_fallback_envs == ()
assert p.inherit_fast_model_for_aux is False
assert p.cost_log_provider == "anthropic"
+ assert p.dispatch_provider == "anthropic"
+ assert p.supports_flex_tier is False
def test_direct_anthropic_profile_shape(self):
cfg = _make_direct_safe_config(
@@ -466,6 +472,8 @@ class TestTransportProfile:
assert p.supports_sdk is True
assert p.sdk_model_vendor_constraint == "anthropic"
assert p.cost_log_provider == "anthropic"
+ assert p.dispatch_provider == "anthropic"
+ assert p.supports_flex_tier is False
def test_thinking_available_alias_matches_profile(self):
"""``thinking_available`` is a backwards-compat alias used by
diff --git a/autogpt_platform/backend/backend/copilot/dream/__init__.py b/autogpt_platform/backend/backend/copilot/dream/__init__.py
new file mode 100644
index 0000000000..fa1b5eba68
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/__init__.py
@@ -0,0 +1,9 @@
+"""Dream pass — scheduled offline memory consolidation.
+
+Three-phase pipeline (consolidate → recombine → sanitize) that walks a
+user's recent episodes + active facts, proposes new tentative findings,
+demotes stale or contradicted ones, and writes a summary chat session.
+
+Designed to run on a per-user cron in user-local time (default 03:00),
+with an admin-triggered on-demand path for testing.
+"""
diff --git a/autogpt_platform/backend/backend/copilot/dream/apply.py b/autogpt_platform/backend/backend/copilot/dream/apply.py
new file mode 100644
index 0000000000..af858e5225
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/apply.py
@@ -0,0 +1,480 @@
+"""Apply a sanitized ``DreamOperations`` payload to the world.
+
+Three side-effects, in order:
+ 1. Writes (consolidated facts) → ``status='active'`` MemoryEnvelope
+ episodes via ``enqueue_episode``.
+ 2. Proposals (novel findings) → ``status='tentative'`` envelopes.
+ Ratification (P-0.4) will flip these to active or supersede them.
+ 3. Demotions / entity invalidations → ``mark_edges_superseded`` /
+ ``invalidate_entity_direct_neighbors`` against the FalkorDB driver.
+
+A ``ChatSession`` shell (``metadata.kind='dream'`` +
+``metadata.dream_pass_id``) is created up front so the MemoryEnvelope
+provenance can reference its id; the assistant message holding
+``summary_for_user`` is appended LAST, after the ops above, so a partway
+failure leaves an empty dream rather than a narrative with no memory.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid as uuidlib
+from datetime import datetime, timezone
+
+from backend.copilot.graphiti.client import derive_group_id
+from backend.copilot.graphiti.config import graphiti_config
+from backend.copilot.graphiti.falkordb_driver import AutoGPTFalkorDriver
+from backend.copilot.graphiti.ingest import enqueue_episode
+from backend.copilot.graphiti.memory_model import (
+ MemoryEnvelope,
+ MemoryKind,
+ MemoryStatus,
+ SourceKind,
+)
+from backend.copilot.tools.graphiti_forget import (
+ invalidate_entity_direct_neighbors,
+ mark_edges_superseded,
+)
+from backend.util.feature_flag import Flag, is_feature_enabled
+
+from .batch_submit import read_input_bundle
+from .schemas import (
+ ConsolidatedFact,
+ DemotionSummary,
+ DreamDemotion,
+ DreamOperations,
+ DreamOperationsSnapshot,
+ EntityInvalidation,
+ EntityInvalidationSummary,
+ ProposedFinding,
+ WriteSummary,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _provenance(pass_id: str, phase: str) -> str:
+ """Provenance string written into the MemoryEnvelope.
+
+ Format matches Graphiti audit §6.12 / TODO P-1.5 grain — encodes
+ the dream pass id and the phase so ratification can find originating
+ dream-write episodes by prefix-match.
+ """
+ return f"dream:{pass_id}:{phase}:{datetime.now(timezone.utc).isoformat()}"
+
+
+def _episode_name(pass_id: str, phase: str, counter: int) -> str:
+ """Stable, auditable episode name for dream-derived writes."""
+ return f"dream_{pass_id}_{phase}_{counter:03d}"
+
+
+async def _write_consolidated_fact(
+ user_id: str,
+ pass_id: str,
+ counter: int,
+ fact: ConsolidatedFact,
+ session_id: str,
+) -> bool:
+ envelope = MemoryEnvelope(
+ content=fact.content,
+ source_kind=SourceKind.assistant_derived,
+ memory_kind=MemoryKind.fact,
+ status=MemoryStatus.active,
+ confidence=fact.confidence,
+ scope=fact.scope,
+ provenance=_provenance(pass_id, "consolidate"),
+ )
+ return await enqueue_episode(
+ user_id=user_id,
+ session_id=session_id,
+ name=_episode_name(pass_id, "consolidate", counter),
+ episode_body=envelope.model_dump_json(),
+ source_description=(
+ f"dream-pass consolidation; src_episodes="
+ f"{','.join(fact.source_episode_uuids[:5])}"
+ ),
+ is_json=True,
+ )
+
+
+async def _write_proposed_finding(
+ user_id: str,
+ pass_id: str,
+ counter: int,
+ finding: ProposedFinding,
+ session_id: str,
+) -> bool:
+ envelope = MemoryEnvelope(
+ content=finding.content,
+ source_kind=SourceKind.assistant_derived,
+ memory_kind=finding.memory_kind,
+ status=MemoryStatus.tentative,
+ confidence=finding.confidence,
+ scope=finding.scope,
+ provenance=_provenance(pass_id, "recombine"),
+ )
+ description_parts: list[str] = ["dream-pass proposal"]
+ if finding.rationale:
+ description_parts.append(f"rationale={finding.rationale[:240]}")
+ if finding.source_fact_uuids:
+ description_parts.append(f"src_facts={','.join(finding.source_fact_uuids[:5])}")
+ return await enqueue_episode(
+ user_id=user_id,
+ session_id=session_id,
+ name=_episode_name(pass_id, "recombine", counter),
+ episode_body=envelope.model_dump_json(),
+ source_description="; ".join(description_parts),
+ is_json=True,
+ )
+
+
+async def _filter_demotions_to_known_facts(
+ pass_id: str,
+ demotions: list[DreamDemotion],
+ known_fact_uuids: set[str] | None,
+) -> list[DreamDemotion]:
+ """Code-level pre-flight for LLM-proposed demotion targets.
+
+ The sanitize prompt tells the model only ``known_fact_uuids`` are
+ valid demotion targets, but prompt text isn't enforcement — a
+ hallucinated or injected uuid would otherwise reach Cypher and
+ could demote edges the dream pass never fetched. Both the sync
+ orchestrator and the batch callback converge on
+ ``apply_operations``, so this is the one chokepoint that covers
+ both paths.
+
+ The sync path passes ``known_fact_uuids`` from its in-memory
+ ``DreamInput``; the batch path calls ``apply_operations`` without
+ it, so we fall back to the input bundle persisted at submit time.
+ If neither source exists (bundle expired/corrupted, or the Redis
+ read itself fails) we keep the demotions rather than zeroing the
+ pass — the same fail-open posture as the clamp's
+ unknown-fact-count fallback — and log that validation was skipped.
+ The Redis error MUST NOT propagate: by the time apply runs on the
+ batch path the at-most-once apply gate is already claimed, so an
+ exception here would permanently lose the dream (a retry hits the
+ "duplicate" branch and skips apply entirely).
+
+ Entity invalidations are NOT filtered here: the input bundle
+ carries no entity-uuid allowlist (``FactRow.source``/``target``
+ are entity *names*), so there is nothing to validate against.
+ """
+ if not demotions:
+ return demotions
+ if known_fact_uuids is None:
+ try:
+ bundle = await read_input_bundle(pass_id)
+ except Exception as exc:
+ logger.warning(
+ "Dream pass %s: input bundle read failed (%s) — failing open "
+ "and skipping known-fact validation for %d demotion(s)",
+ pass_id,
+ exc,
+ len(demotions),
+ )
+ return demotions
+ if bundle is None:
+ logger.warning(
+ "Dream pass %s: no input bundle available — skipping "
+ "known-fact validation for %d demotion(s)",
+ pass_id,
+ len(demotions),
+ )
+ return demotions
+ known_fact_uuids = bundle.known_fact_uuids
+ kept = [d for d in demotions if d.edge_uuid in known_fact_uuids]
+ dropped = len(demotions) - len(kept)
+ if dropped:
+ logger.warning(
+ "Dream pass %s: dropped %d demotion(s) targeting edge uuids "
+ "outside the pass's known_fact_uuids (prompt-only constraint "
+ "violated by the model)",
+ pass_id,
+ dropped,
+ )
+ return kept
+
+
+async def _apply_demotions(
+ user_id: str,
+ group_id: str,
+ demotions: list[DreamDemotion],
+) -> tuple[int, int, list[DemotionSummary]]:
+ """Run mark_edges_superseded once per (reason, new_status) bucket.
+
+ Returns ``(succeeded_count, failed_count, summaries)`` where each
+ summary records the original DreamDemotion plus whether the
+ underlying Cypher actually touched a row (``applied`` flag).
+ """
+ if not demotions:
+ return 0, 0, []
+
+ # Group by (new_status, reason) so we minimize round-trips.
+ buckets: dict[tuple[str, str], list[str]] = {}
+ for d in demotions:
+ buckets.setdefault((d.new_status, d.reason), []).append(d.edge_uuid)
+
+ driver = AutoGPTFalkorDriver(
+ host=graphiti_config.falkordb_host,
+ port=graphiti_config.falkordb_port,
+ password=graphiti_config.falkordb_password or None,
+ database=group_id,
+ # Indices live with the chat-write client; skip the per-driver
+ # indexing race ("Buffer is closed" spam).
+ build_indices=False,
+ )
+ succeeded = 0
+ failed = 0
+ succeeded_uuids: set[str] = set()
+ try:
+ for (new_status, reason), uuids in buckets.items():
+ ok, bad = await mark_edges_superseded(
+ driver,
+ uuids,
+ reason=reason,
+ new_status=new_status, # type: ignore[arg-type]
+ user_id=user_id,
+ # Defense-in-depth: the driver is already opened against
+ # the per-user database, but the group_id predicate keeps
+ # a future wrong-driver caller from touching another
+ # user's edges.
+ group_id=group_id,
+ )
+ succeeded += len(ok)
+ failed += len(bad)
+ succeeded_uuids.update(ok)
+ finally:
+ await driver.close()
+
+ summaries = [
+ DemotionSummary(
+ edge_uuid=d.edge_uuid,
+ reason=d.reason,
+ new_status=d.new_status,
+ applied=d.edge_uuid in succeeded_uuids,
+ )
+ for d in demotions
+ ]
+ return succeeded, failed, summaries
+
+
+async def _apply_entity_invalidations(
+ group_id: str,
+ invalidations: list[EntityInvalidation],
+) -> tuple[int, list[EntityInvalidationSummary]]:
+ """Single-hop demotion of every :RELATES_TO around each invalidated entity.
+
+ Returns ``(total_edges_touched, summaries)`` — summaries enumerate
+ the per-entity edge uuids so callers can render or audit which
+ edges fell off when an entity was invalidated.
+ """
+ if not invalidations:
+ return 0, []
+ driver = AutoGPTFalkorDriver(
+ host=graphiti_config.falkordb_host,
+ port=graphiti_config.falkordb_port,
+ password=graphiti_config.falkordb_password or None,
+ database=group_id,
+ # Indices live with the chat-write client; skip the per-driver
+ # indexing race ("Buffer is closed" spam).
+ build_indices=False,
+ )
+ total = 0
+ summaries: list[EntityInvalidationSummary] = []
+ try:
+ for inv in invalidations:
+ uuids = await invalidate_entity_direct_neighbors(
+ driver,
+ group_id=group_id,
+ entity_uuid=inv.entity_uuid,
+ reason=inv.reason,
+ )
+ total += len(uuids)
+ summaries.append(
+ EntityInvalidationSummary(
+ entity_uuid=inv.entity_uuid,
+ reason=inv.reason,
+ edges_touched=list(uuids),
+ )
+ )
+ finally:
+ await driver.close()
+ return total, summaries
+
+
+async def _create_dream_session(user_id: str, pass_id: str) -> str:
+ """Create the dream-kind ChatSession shell and return its id.
+
+ Written up front (before the memory ops) because the fact/proposal
+ ``MemoryEnvelope`` provenance references this ``session_id``. The
+ user-facing narrative is written separately, AFTER the ops land
+ (``_write_dream_summary_message``), so a partway failure leaves an
+ empty dream rather than a 'completed' narrative with no memory.
+
+ We use a fresh uuid rather than the pass_id so re-runs of the same
+ pass (admin retries on failure) each produce their own session row.
+ """
+ # Lazy import — avoids circular dependency at module-import time
+ # AND keeps the dream-pass / chat-model coupling explicit. Routing
+ # through ``chat_db()`` means the dream pass (running in the
+ # Scheduler subprocess) auto-uses the DatabaseManager RPC client;
+ # the DatabaseManager process itself uses the direct module.
+ from backend.copilot.model import ChatSessionMetadata
+ from backend.data.db_accessors import chat_db
+
+ session_id = str(uuidlib.uuid4())
+ await chat_db().create_chat_session(
+ session_id=session_id,
+ user_id=user_id,
+ metadata=ChatSessionMetadata(kind="dream", dream_pass_id=pass_id),
+ )
+ return session_id
+
+
+async def _write_dream_summary_message(
+ session_id: str, pass_id: str, summary_for_user: str
+) -> None:
+ """Append the assistant narrative to an already-created dream session.
+
+ Called at the END of ``apply_operations`` so the user-visible summary
+ only appears once the memory ops above have been attempted.
+ """
+ from backend.data.db_accessors import chat_db
+
+ body = summary_for_user.strip() or "Dream pass completed with no narrative output."
+ await chat_db().add_chat_message(
+ session_id=session_id,
+ role="assistant",
+ sequence=0,
+ content=body,
+ metadata={"dream_pass_id": pass_id},
+ )
+
+
+async def apply_operations(
+ user_id: str,
+ pass_id: str,
+ ops: DreamOperations,
+ *,
+ known_fact_uuids: set[str] | None = None,
+) -> dict[str, int | str | DreamOperationsSnapshot]:
+ """Apply a sanitized DreamOperations to Graphiti + Postgres.
+
+ Returns a small stats dict the orchestrator can fold into
+ ``DreamPassResult``. Includes a ``snapshot`` key carrying the
+ detailed ``DreamOperationsSnapshot`` payload for consumers that
+ need per-operation rollups (eval, admin UI, future P9 SSE event).
+
+ ``known_fact_uuids`` is the set of edge uuids the dream pass
+ actually fetched (``DreamInput.known_fact_uuids``); demotions
+ targeting anything outside it are dropped before any Cypher runs
+ (see ``_filter_demotions_to_known_facts``). ``None`` means "look
+ up the persisted input bundle by pass_id" — the batch path's
+ callbacks rely on that fallback.
+
+ Postgres writes route through ``chat_db()`` / equivalent
+ accessors. The dream pass runs in the Scheduler subprocess where
+ Prisma is intentionally NOT locally connected — those accessors
+ auto-route to the DatabaseManager RPC client. We deliberately do
+ NOT call ``platform_db.connect()`` here: setting ``is_connected``
+ True before the local Prisma engine is reachable causes a race
+ with concurrent ``platform_cost_db()`` callers from
+ ``token_tracking._safe_log`` (they'd see ``is_connected=True``,
+ try direct Prisma, hit "All connection attempts failed" while
+ the engine is still booting).
+ """
+ group_id = derive_group_id(user_id)
+
+ # Phase A — create the session shell up front so the MemoryEnvelope
+ # provenance can reference its id. The user-facing narrative summary
+ # is written AFTER the ops (see below), so a partway failure leaves an
+ # empty dream rather than a 'completed' narrative with no memory.
+ session_id = await _create_dream_session(user_id=user_id, pass_id=pass_id)
+
+ written = 0
+ write_summaries: list[WriteSummary] = []
+ for i, fact in enumerate(ops.writes):
+ if await _write_consolidated_fact(
+ user_id, pass_id, i, fact, session_id=session_id
+ ):
+ written += 1
+ write_summaries.append(
+ WriteSummary(
+ content=fact.content,
+ scope=fact.scope,
+ confidence=fact.confidence,
+ status="active",
+ source_episode_uuids=list(fact.source_episode_uuids),
+ )
+ )
+
+ proposed = 0
+ proposal_summaries: list[WriteSummary] = []
+ for i, prop in enumerate(ops.proposals):
+ if await _write_proposed_finding(
+ user_id, pass_id, i, prop, session_id=session_id
+ ):
+ proposed += 1
+ proposal_summaries.append(
+ WriteSummary(
+ content=prop.content,
+ scope=prop.scope,
+ confidence=prop.confidence,
+ status="tentative",
+ source_episode_uuids=list(prop.source_episode_uuids),
+ source_fact_uuids=list(prop.source_fact_uuids),
+ )
+ )
+
+ demotions = await _filter_demotions_to_known_facts(
+ pass_id, ops.demotions, known_fact_uuids
+ )
+ demoted_ok, demoted_fail, demotion_summaries = await _apply_demotions(
+ user_id, group_id, demotions
+ )
+ # Entity invalidation single-hop demotes every edge around the
+ # entity — the most destructive op in the pass — so it stays behind
+ # its own LD flag for staged rollout, independent of the dream pass
+ # being enabled. Truthiness check short-circuits the flag eval when
+ # the model proposed nothing to invalidate.
+ if ops.entity_invalidations and await is_feature_enabled(
+ Flag.DREAM_PASS_INVALIDATE_ENTITY, user_id
+ ):
+ entity_edges_demoted, entity_summaries = await _apply_entity_invalidations(
+ group_id, ops.entity_invalidations
+ )
+ else:
+ entity_edges_demoted, entity_summaries = 0, []
+
+ # Narrative summary last — only surface the user-facing dream story
+ # once the memory ops above have been attempted.
+ await _write_dream_summary_message(session_id, pass_id, ops.summary_for_user)
+
+ logger.info(
+ "Dream pass %s applied for user %s: "
+ "writes=%d proposals=%d demoted=%d (failed=%d) entity_edges=%d",
+ pass_id,
+ user_id[:12],
+ written,
+ proposed,
+ demoted_ok,
+ demoted_fail,
+ entity_edges_demoted,
+ )
+
+ snapshot = DreamOperationsSnapshot(
+ writes=write_summaries,
+ proposals=proposal_summaries,
+ demotions=demotion_summaries,
+ entity_invalidations=entity_summaries,
+ )
+
+ return {
+ "session_id": session_id,
+ "consolidated_count": written,
+ "proposal_count": proposed,
+ "demotion_count": demoted_ok,
+ "demotion_failed_count": demoted_fail,
+ "entity_invalidation_count": entity_edges_demoted,
+ "snapshot": snapshot,
+ }
diff --git a/autogpt_platform/backend/backend/copilot/dream/apply_test.py b/autogpt_platform/backend/backend/copilot/dream/apply_test.py
new file mode 100644
index 0000000000..6a7b120634
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/apply_test.py
@@ -0,0 +1,540 @@
+"""Apply tests — mock the Graphiti/Postgres boundary, verify the right
+calls are produced for each operation type.
+
+These tests do NOT touch FalkorDB or Prisma. apply.py is a pure
+fan-out: it builds MemoryEnvelopes for writes/proposals and delegates
+to ``enqueue_episode`` / ``mark_edges_superseded`` /
+``invalidate_entity_direct_neighbors`` / ``create_chat_session`` /
+``add_chat_message``. Each of those is mocked here.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock
+
+import pytest
+
+from . import apply as apply_mod
+from .fetch import DreamInput
+from .schemas import (
+ ConsolidatedFact,
+ DreamDemotion,
+ DreamOperations,
+ EntityInvalidation,
+ ProposedFinding,
+)
+
+
+def _bundle_with_known_facts(*uuids: str) -> DreamInput:
+ return DreamInput(
+ user_id="u-bundle",
+ group_id="u-bundle",
+ window_start=datetime(2026, 5, 1, tzinfo=timezone.utc),
+ window_end=datetime(2026, 5, 14, tzinfo=timezone.utc),
+ known_fact_uuids=set(uuids),
+ )
+
+
[email protected](autouse=True)
+def _stub_boundaries(mocker):
+ """Wire up the apply.py side-effects with AsyncMocks once per test."""
+ mocker.patch.object(apply_mod, "enqueue_episode", AsyncMock(return_value=True))
+ # The driver constructor + close — apply.py opens a FalkorDB driver for
+ # demotions and entity invalidations. Patch where it's used.
+ driver = mocker.MagicMock()
+ driver.close = AsyncMock(return_value=None)
+ mocker.patch.object(
+ apply_mod, "AutoGPTFalkorDriver", mocker.MagicMock(return_value=driver)
+ )
+ # Helper functions
+ mocker.patch.object(
+ apply_mod,
+ "mark_edges_superseded",
+ AsyncMock(return_value=(["e1"], [])),
+ )
+ mocker.patch.object(
+ apply_mod,
+ "invalidate_entity_direct_neighbors",
+ AsyncMock(return_value=["e1", "e2"]),
+ )
+ # ChatSession + ChatMessage writes — apply.py imports them lazily inside
+ # ``_create_dream_session`` / ``_write_dream_summary_message`` to avoid a
+ # circular import. Patch where the symbol is looked up (copilot.db).
+ mocker.patch(
+ "backend.copilot.db.create_chat_session",
+ AsyncMock(return_value=mocker.MagicMock(session_id="s1")),
+ )
+ mocker.patch("backend.copilot.db.add_chat_message", AsyncMock(return_value=None))
+ # Entity invalidation is gated on DREAM_PASS_INVALIDATE_ENTITY. Default
+ # the flag ON so the existing entity tests exercise the apply path; the
+ # flag-off behavior has its own dedicated test below.
+ mocker.patch.object(apply_mod, "is_feature_enabled", AsyncMock(return_value=True))
+ # No persisted input bundle by default — the demotion pre-flight filter
+ # fails open (keeps all demotions) so tests that don't care about uuid
+ # validation behave as before. Filter tests re-patch with a bundle.
+ mocker.patch.object(apply_mod, "read_input_bundle", AsyncMock(return_value=None))
+ # derive_group_id is deterministic; let it run.
+
+
+async def test_writes_become_active_envelopes():
+ ops = DreamOperations(
+ writes=[
+ ConsolidatedFact(content="A likes B", confidence=0.8, scope="real:global")
+ ],
+ summary_for_user="ok",
+ )
+ stats = await apply_mod.apply_operations(
+ user_id="u-1234567890ab", pass_id="p-abc", ops=ops
+ )
+
+ assert stats["consolidated_count"] == 1
+ assert stats["proposal_count"] == 0
+ apply_mod.enqueue_episode.assert_awaited()
+ call_kwargs = apply_mod.enqueue_episode.await_args.kwargs
+ assert call_kwargs["is_json"] is True
+ assert call_kwargs["name"].startswith("dream_p-abc_consolidate_")
+ # The envelope body should be JSON with status=active source_kind=assistant_derived
+ body = call_kwargs["episode_body"]
+ assert '"status":"active"' in body
+ assert '"source_kind":"assistant_derived"' in body
+
+
+async def test_proposals_become_tentative_envelopes():
+ ops = DreamOperations(
+ proposals=[
+ ProposedFinding(
+ content="A trusts B",
+ confidence=0.6,
+ rationale="implied",
+ source_fact_uuids=["f1"],
+ )
+ ],
+ summary_for_user="ok",
+ )
+ await apply_mod.apply_operations(user_id="u-x", pass_id="p-2", ops=ops)
+ # First call was the consolidate write (there were no writes, so first call IS the proposal)
+ call_kwargs = apply_mod.enqueue_episode.await_args.kwargs
+ assert call_kwargs["name"].startswith("dream_p-2_recombine_")
+ body = call_kwargs["episode_body"]
+ assert '"status":"tentative"' in body
+
+
+async def test_demotions_group_by_status_and_reason():
+ """Bucketed mark_edges_superseded calls — one per (status, reason) pair."""
+ ops = DreamOperations(
+ demotions=[
+ DreamDemotion(edge_uuid="a", reason="stale", new_status="superseded"),
+ DreamDemotion(edge_uuid="b", reason="stale", new_status="superseded"),
+ DreamDemotion(
+ edge_uuid="c", reason="contradicted_by:x", new_status="contradicted"
+ ),
+ ],
+ )
+ await apply_mod.apply_operations(user_id="u-y", pass_id="p-3", ops=ops)
+
+ # Three demotions but only TWO buckets: (superseded, stale) and
+ # (contradicted, contradicted_by:x)
+ assert apply_mod.mark_edges_superseded.await_count == 2
+ bucket_args = [
+ call.args[1] if len(call.args) > 1 else call.kwargs.get("uuids")
+ for call in apply_mod.mark_edges_superseded.await_args_list
+ ]
+ # One bucket has 2 uuids, the other has 1
+ assert sorted(len(b) for b in bucket_args) == [1, 2]
+
+
+async def test_demotions_pass_group_id_to_mark_edges_superseded():
+ """The Cypher group_id predicate (defense-in-depth against a
+ wrong-driver caller) only works if apply.py threads the derived
+ group_id into every mark_edges_superseded call."""
+ ops = DreamOperations(
+ demotions=[DreamDemotion(edge_uuid="a", reason="stale")],
+ )
+ await apply_mod.apply_operations(user_id="u-gid", pass_id="p-gid", ops=ops)
+
+ apply_mod.mark_edges_superseded.assert_awaited_once()
+ # derive_group_id prefixes user ids with "user_"
+ assert apply_mod.mark_edges_superseded.await_args.kwargs["group_id"] == "user_u-gid"
+
+
+async def test_hallucinated_demotion_uuids_dropped_before_cypher():
+ """Sync path: demotions targeting edge uuids outside the pass's
+ known_fact_uuids are a prompt-constraint violation (hallucination or
+ injection) and must never reach mark_edges_superseded."""
+ ops = DreamOperations(
+ demotions=[
+ DreamDemotion(edge_uuid="known-1", reason="stale"),
+ DreamDemotion(edge_uuid="hallucinated", reason="stale"),
+ ],
+ )
+ stats = await apply_mod.apply_operations(
+ user_id="u-filter",
+ pass_id="p-filter",
+ ops=ops,
+ known_fact_uuids={"known-1", "known-2"},
+ )
+
+ apply_mod.mark_edges_superseded.assert_awaited_once()
+ sent_uuids = apply_mod.mark_edges_superseded.await_args.args[1]
+ assert sent_uuids == ["known-1"]
+ # The rejected demotion never reaches the snapshot either
+ assert [d.edge_uuid for d in stats["snapshot"].demotions] == ["known-1"]
+ # The caller supplied the allowlist — no Redis bundle lookup needed
+ apply_mod.read_input_bundle.assert_not_awaited()
+
+
+async def test_batch_path_demotions_validated_against_persisted_bundle(mocker):
+ """Batch path: apply_operations is called without known_fact_uuids
+ (batch_callbacks doesn't have the in-memory DreamInput), so the
+ filter must fall back to the bundle persisted at submit time."""
+ mocker.patch.object(
+ apply_mod,
+ "read_input_bundle",
+ AsyncMock(return_value=_bundle_with_known_facts("known-1")),
+ )
+ ops = DreamOperations(
+ demotions=[
+ DreamDemotion(edge_uuid="known-1", reason="stale"),
+ DreamDemotion(edge_uuid="ghost", reason="stale"),
+ ],
+ )
+ await apply_mod.apply_operations(user_id="u-batch", pass_id="p-batch", ops=ops)
+
+ apply_mod.read_input_bundle.assert_awaited_once_with("p-batch")
+ apply_mod.mark_edges_superseded.assert_awaited_once()
+ assert apply_mod.mark_edges_superseded.await_args.args[1] == ["known-1"]
+
+
+async def test_missing_input_bundle_fails_open_and_keeps_demotions():
+ """When neither the caller nor Redis can supply known_fact_uuids
+ (bundle expired/corrupted), the filter fails open — demotions are
+ kept rather than zeroing the pass, matching the clamp's
+ unknown-fact-count posture. The autouse fixture's
+ read_input_bundle stub returns None."""
+ ops = DreamOperations(
+ demotions=[DreamDemotion(edge_uuid="unverifiable", reason="stale")],
+ )
+ await apply_mod.apply_operations(user_id="u-open", pass_id="p-open", ops=ops)
+
+ apply_mod.mark_edges_superseded.assert_awaited_once()
+ assert apply_mod.mark_edges_superseded.await_args.args[1] == ["unverifiable"]
+
+
+async def test_redis_blip_on_bundle_fallback_fails_open(mocker, caplog):
+ """A Redis error during the input-bundle fallback read must take the
+ same fail-open branch as a missing bundle (keep demotions, WARNING)
+ instead of raising out of apply_operations — on the batch path the
+ at-most-once apply gate is already claimed by the time apply runs,
+ so an exception here permanently loses the dream (a retry hits the
+ "duplicate" branch and skips apply entirely)."""
+ mocker.patch.object(
+ apply_mod,
+ "read_input_bundle",
+ AsyncMock(side_effect=ConnectionError("redis blip")),
+ )
+ ops = DreamOperations(
+ demotions=[DreamDemotion(edge_uuid="unverifiable", reason="stale")],
+ )
+ with caplog.at_level(logging.WARNING, logger=apply_mod.logger.name):
+ stats = await apply_mod.apply_operations(
+ user_id="u-blip", pass_id="p-blip", ops=ops
+ )
+
+ apply_mod.mark_edges_superseded.assert_awaited_once()
+ assert apply_mod.mark_edges_superseded.await_args.args[1] == ["unverifiable"]
+ assert stats["demotion_count"] == 1
+ assert any(
+ "input bundle read failed" in record.getMessage()
+ for record in caplog.records
+ if record.levelno == logging.WARNING
+ )
+
+
+async def test_entity_invalidations_not_filtered_by_known_fact_uuids():
+ """The input bundle carries no entity-uuid allowlist (FactRow
+ source/target are entity names), so entity invalidations are NOT
+ subject to the known-fact pre-flight — they rely on the LD flag +
+ count clamp + single-hop guarantee instead."""
+ ops = DreamOperations(
+ entity_invalidations=[
+ EntityInvalidation(entity_uuid="ent-unlisted", reason="r"),
+ ],
+ )
+ await apply_mod.apply_operations(
+ user_id="u-ent",
+ pass_id="p-ent",
+ ops=ops,
+ known_fact_uuids={"some-fact"},
+ )
+
+ apply_mod.invalidate_entity_direct_neighbors.assert_awaited_once()
+
+
+async def test_entity_invalidation_calls_single_hop_helper():
+ ops = DreamOperations(
+ entity_invalidations=[
+ EntityInvalidation(entity_uuid="ent-x", reason="dead_to_us"),
+ ],
+ )
+ await apply_mod.apply_operations(user_id="u-z", pass_id="p-4", ops=ops)
+
+ apply_mod.invalidate_entity_direct_neighbors.assert_awaited_once()
+ kwargs = apply_mod.invalidate_entity_direct_neighbors.await_args.kwargs
+ assert kwargs["entity_uuid"] == "ent-x"
+ assert kwargs["reason"] == "dead_to_us"
+
+
+async def test_entity_invalidation_skipped_when_flag_off(mocker):
+ """With DREAM_PASS_INVALIDATE_ENTITY off, proposed invalidations are
+ dropped — the destructive single-hop helper must never run and the
+ snapshot reflects zero entity edges touched."""
+ mocker.patch.object(apply_mod, "is_feature_enabled", AsyncMock(return_value=False))
+ ops = DreamOperations(
+ entity_invalidations=[
+ EntityInvalidation(entity_uuid="ent-x", reason="dead_to_us"),
+ ],
+ )
+ stats = await apply_mod.apply_operations(user_id="u-z", pass_id="p-off", ops=ops)
+
+ apply_mod.invalidate_entity_direct_neighbors.assert_not_awaited()
+ assert stats["entity_invalidation_count"] == 0
+ assert stats["snapshot"].entity_invalidations == []
+
+
+async def test_no_op_dream_still_writes_summary_session(mocker):
+ """Empty DreamOperations still creates the dream-kind ChatSession."""
+ from backend.copilot import db as copilot_db
+
+ ops = DreamOperations(summary_for_user="Nothing new today.")
+ stats = await apply_mod.apply_operations(user_id="u-a", pass_id="p-5", ops=ops)
+
+ assert stats["consolidated_count"] == 0
+ assert stats["proposal_count"] == 0
+ assert stats["demotion_count"] == 0
+ # ChatSession + ChatMessage were both created
+ copilot_db.create_chat_session.assert_awaited_once()
+ copilot_db.add_chat_message.assert_awaited_once()
+ msg_kwargs = copilot_db.add_chat_message.await_args.kwargs
+ assert msg_kwargs["role"] == "assistant"
+ assert msg_kwargs["content"] == "Nothing new today."
+
+
+async def test_summary_written_after_memory_ops(mocker):
+ """The user-facing narrative must be written AFTER the memory ops, so a
+ partway failure doesn't leave a 'completed' dream narrative with no
+ memory behind it."""
+ calls: list[str] = []
+
+ async def _track_write(*args, **kwargs):
+ calls.append("write")
+ return True
+
+ async def _track_summary(*args, **kwargs):
+ calls.append("summary")
+
+ mocker.patch.object(
+ apply_mod, "_create_dream_session", new_callable=AsyncMock, return_value="s"
+ )
+ mocker.patch.object(apply_mod, "_write_consolidated_fact", side_effect=_track_write)
+ mocker.patch.object(
+ apply_mod, "_write_dream_summary_message", side_effect=_track_summary
+ )
+ mocker.patch.object(
+ apply_mod, "_apply_demotions", new_callable=AsyncMock, return_value=(0, 0, [])
+ )
+ mocker.patch.object(
+ apply_mod,
+ "_apply_entity_invalidations",
+ new_callable=AsyncMock,
+ return_value=(0, []),
+ )
+
+ await apply_mod.apply_operations(
+ user_id="u-1",
+ pass_id="p-1",
+ ops=DreamOperations(
+ writes=[ConsolidatedFact(content="A likes B", confidence=0.8)],
+ summary_for_user="done",
+ ),
+ )
+
+ assert calls == ["write", "summary"], calls
+
+
+# ---------------------------------------------------------------------------
+# Prisma auto-connect regression (scheduler service starts without an open
+# Prisma connection; apply_operations must open one before any DB writes).
+# ---------------------------------------------------------------------------
+
+
+async def test_apply_operations_never_auto_connects_prisma(mocker):
+ """``apply_operations`` MUST NOT call ``platform_db.connect()``.
+
+ The dream pass runs in the Scheduler subprocess where Prisma is
+ intentionally left disconnected so callers route through
+ ``chat_db()`` / equivalents (which transparently use the
+ DatabaseManager RPC client). Auto-connecting here flips
+ ``is_connected()`` to True before the local Prisma engine is
+ reachable, racing with concurrent ``platform_cost_db()`` callers
+ from ``token_tracking._safe_log`` — they see
+ ``is_connected=True``, try the direct Prisma path, and hit
+ "All connection attempts failed" while the engine is still
+ booting. Regression pin: keep the auto-connect OUT.
+ """
+ from backend.copilot.dream import apply as apply_mod
+ from backend.copilot.dream.schemas import DreamOperations
+
+ mocker.patch.object(
+ apply_mod, "_create_dream_session", new_callable=AsyncMock, return_value="s"
+ )
+ mocker.patch.object(
+ apply_mod, "_write_dream_summary_message", new_callable=AsyncMock
+ )
+ mocker.patch.object(
+ apply_mod, "_apply_demotions", new_callable=AsyncMock, return_value=(0, 0, [])
+ )
+ mocker.patch.object(
+ apply_mod,
+ "_apply_entity_invalidations",
+ new_callable=AsyncMock,
+ return_value=(0, []),
+ )
+
+ # Whatever state Prisma is in, apply_operations must not touch
+ # ``platform_db.connect``. Spy on BOTH states to make the contract
+ # explicit.
+ for is_conn in (False, True):
+ mocker.patch("backend.data.db.is_connected", return_value=is_conn)
+ connect_spy = mocker.patch("backend.data.db.connect", new_callable=AsyncMock)
+
+ await apply_mod.apply_operations(
+ user_id="u-1",
+ pass_id="p-1",
+ ops=DreamOperations(
+ writes=[],
+ proposals=[],
+ demotions=[],
+ entity_invalidations=[],
+ summary_for_user="empty",
+ ),
+ )
+ connect_spy.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# DreamOperationsSnapshot — eval/UI/SSE consumers need per-operation detail.
+# Tested at the apply.py boundary so the contract survives refactors.
+# ---------------------------------------------------------------------------
+
+
+async def test_apply_operations_returns_snapshot_with_per_op_detail(mocker):
+ """The stats dict must include a ``snapshot: DreamOperationsSnapshot``
+ field with one entry per write/proposal and per-demotion detail.
+
+ Consumers (AgentProbe scorers, admin visualizer, future P9 SSE
+ event) read this; counts alone aren't enough."""
+ from backend.copilot.dream.schemas import DreamOperationsSnapshot
+
+ # The autouse fixture stubs mark_edges_superseded to return ["e1"]
+ # in the succeeded list, which doesn't match our test uuid "d1".
+ # Override so d1 lands in the succeeded list.
+ mocker.patch.object(
+ apply_mod,
+ "mark_edges_superseded",
+ AsyncMock(return_value=(["d1"], [])),
+ )
+
+ ops = DreamOperations(
+ writes=[
+ ConsolidatedFact(
+ content="A likes B",
+ confidence=0.8,
+ scope="real:global",
+ source_episode_uuids=["ep-1", "ep-2"],
+ )
+ ],
+ proposals=[
+ ProposedFinding(
+ content="A trusts B",
+ confidence=0.6,
+ rationale="implied",
+ source_fact_uuids=["f1"],
+ )
+ ],
+ demotions=[
+ DreamDemotion(edge_uuid="d1", reason="stale", new_status="superseded"),
+ ],
+ entity_invalidations=[
+ EntityInvalidation(entity_uuid="ent-x", reason="dead_to_us"),
+ ],
+ summary_for_user="ok",
+ )
+ stats = await apply_mod.apply_operations(
+ user_id="u-snap", pass_id="p-snap", ops=ops
+ )
+
+ snap = stats["snapshot"]
+ assert isinstance(snap, DreamOperationsSnapshot)
+ assert len(snap.writes) == 1
+ assert snap.writes[0].content == "A likes B"
+ assert snap.writes[0].status == "active"
+ assert snap.writes[0].source_episode_uuids == ["ep-1", "ep-2"]
+ assert len(snap.proposals) == 1
+ assert snap.proposals[0].status == "tentative"
+ # Proposal provenance must carry BOTH episode + fact source uuids.
+ assert snap.proposals[0].source_fact_uuids == ["f1"]
+ assert len(snap.demotions) == 1
+ assert snap.demotions[0].edge_uuid == "d1"
+ assert snap.demotions[0].new_status == "superseded"
+ assert snap.demotions[0].applied is True
+ assert len(snap.entity_invalidations) == 1
+ assert snap.entity_invalidations[0].entity_uuid == "ent-x"
+ # ``invalidate_entity_direct_neighbors`` returns ["e1","e2"] per fixture stub
+ assert snap.entity_invalidations[0].edges_touched == ["e1", "e2"]
+
+
+async def test_apply_operations_demotion_summary_marks_applied_false_on_miss(mocker):
+ """When mark_edges_superseded returns the uuid in the failed list,
+ the corresponding DemotionSummary records ``applied=False`` so the
+ consumer can render a "stale-uuid skip" without inferring it."""
+ from backend.copilot.dream.schemas import DreamOperationsSnapshot
+
+ # Override the default success stub: this uuid lands in the bad list.
+ mocker.patch.object(
+ apply_mod,
+ "mark_edges_superseded",
+ AsyncMock(return_value=([], ["d-missing"])),
+ )
+ ops = DreamOperations(
+ demotions=[
+ DreamDemotion(
+ edge_uuid="d-missing", reason="stale", new_status="superseded"
+ ),
+ ],
+ )
+ stats = await apply_mod.apply_operations(
+ user_id="u-miss", pass_id="p-miss", ops=ops
+ )
+ snap = stats["snapshot"]
+ assert isinstance(snap, DreamOperationsSnapshot)
+ assert len(snap.demotions) == 1
+ assert snap.demotions[0].edge_uuid == "d-missing"
+ assert snap.demotions[0].applied is False
diff --git a/autogpt_platform/backend/backend/copilot/dream/batch/__init__.py b/autogpt_platform/backend/backend/copilot/dream/batch/__init__.py
new file mode 100644
index 0000000000..6599c39ef5
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/batch/__init__.py
@@ -0,0 +1,19 @@
+"""Batch-API integration for dream passes.
+
+Anthropic and OpenAI both offer a Message Batch API that's 50% cheaper
+than the synchronous endpoint but takes hours instead of seconds. The
+dream pass is exactly the workload that wants this — it runs at 3 AM,
+nobody is waiting on it, and 50% off three Sonnet/Opus calls per user
+per night is meaningful at production scale.
+
+Module layout (per ``dream/p0-spec.md`` §P0.1):
+ * models.py — typed BatchRequest / BatchResult / BatchStatus
+ * provider.py — BatchProvider Protocol + NullBatchProvider
+ * anthropic_provider.py — TODO: real Anthropic AsyncMessageBatch wrapper
+ * openai_provider.py — TODO: real OpenAI client.batches wrapper
+ * factory.py — pick a provider for a given ExecutionPath
+
+Today the dream orchestrator only wires sync_baseline; the
+provider-aware path is staged here so the orchestrator can adopt it
+incrementally without another big refactor.
+"""
diff --git a/autogpt_platform/backend/backend/copilot/dream/batch/anthropic_provider.py b/autogpt_platform/backend/backend/copilot/dream/batch/anthropic_provider.py
new file mode 100644
index 0000000000..e261a092ce
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/batch/anthropic_provider.py
@@ -0,0 +1,60 @@
+"""Anthropic Message Batches adapter — IMPLEMENTATION STUB.
+
+The real adapter wraps ``anthropic.AsyncAnthropic().messages.batches``.
+That client lives behind the ``anthropic`` package; the dream pipeline
+ships with the package as a dependency (used by the SDK chat path)
+so no extra install is needed.
+
+Stub today, real impl in a follow-up PR. Filling this in is mostly
+mechanical:
+
+1. ``submit`` — call ``client.messages.batches.create(requests=[
+ {"custom_id": r.custom_id, "params": {...}} for r in requests])``,
+ map the returned ``Batch`` object onto ``BatchSubmission``.
+2. ``poll`` — call ``client.messages.batches.retrieve(batch_id)``,
+ normalize ``processing_status`` (``in_progress`` /
+ ``canceling`` / ``ended``) onto ``BatchStatus``.
+3. ``download_results`` — call
+ ``client.messages.batches.results(batch_id)``; the body is JSONL
+ with one line per request. Parse each line, extract
+ ``result.message.content`` + ``result.message.usage``, build a
+ ``BatchResult``. ``result.type == "errored"`` → set ``error``.
+
+The Pydantic models in ``models.py`` are deliberately narrower than
+Anthropic's full response shape so the adapter has freedom to drop
+fields we don't use (e.g. ``request_counts``).
+
+The ``cost_usd`` field is computed via ``model_pricing.compute_cost_usd``
+with ``execution_path="anthropic_batch"`` so the 50% discount is
+applied. Anthropic doesn't return a ``cost`` field; computing it
+from tokens against our rate card is the contract.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from .models import BatchRequest, BatchResult, BatchSubmission
+
+
+class AnthropicBatchProvider:
+ """Stub placeholder. See module docstring for the implementation
+ plan. Calling any method raises ``NotImplementedError`` with a
+ pointer to ``p0-spec.md §P0.1``."""
+
+ name = "anthropic"
+
+ async def submit(self, requests: Sequence[BatchRequest]) -> BatchSubmission:
+ raise NotImplementedError(
+ "AnthropicBatchProvider.submit not yet implemented — "
+ "see dream/p0-spec.md §P0.1 and "
+ "dream/batch/anthropic_provider.py module docstring."
+ )
+
+ async def poll(self, submission: BatchSubmission) -> BatchSubmission:
+ raise NotImplementedError("AnthropicBatchProvider.poll not yet implemented.")
+
+ async def download_results(self, submission: BatchSubmission) -> list[BatchResult]:
+ raise NotImplementedError(
+ "AnthropicBatchProvider.download_results not yet implemented."
+ )
diff --git a/autogpt_platform/backend/backend/copilot/dream/batch/batch_test.py b/autogpt_platform/backend/backend/copilot/dream/batch/batch_test.py
new file mode 100644
index 0000000000..4cf40fb329
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/batch/batch_test.py
@@ -0,0 +1,156 @@
+"""Batch scaffolding tests — pins the Protocol shape + factory routing.
+
+Real-provider tests land when the Anthropic / OpenAI adapters are
+filled in (currently NotImplementedError stubs). For now we only
+need to assert:
+ * BatchRequest / BatchResult round-trip via Pydantic.
+ * NullBatchProvider's surface matches the BatchProvider Protocol.
+ * The factory routes to the right provider per ExecutionPath.
+ * Stub providers raise NotImplementedError with a spec pointer
+ (so anyone calling them gets a clear next step).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import pytest
+
+from .anthropic_provider import AnthropicBatchProvider
+from .factory import USE_STUB_BATCH_PROVIDERS, get_batch_provider
+from .models import BatchRequest, BatchResult, BatchStatus, BatchSubmission
+from .openai_provider import OpenAIBatchProvider
+from .provider import BatchProvider, NullBatchProvider
+
+# ---------------------------------------------------------------------------
+# Model round-trips
+# ---------------------------------------------------------------------------
+
+
+def test_batch_request_round_trips_through_pydantic_dump():
+ req = BatchRequest(
+ custom_id="pass-1:consolidate",
+ model="anthropic/claude-sonnet-4.6",
+ messages=[{"role": "user", "content": "hi"}],
+ temperature=0.2,
+ )
+ revived = BatchRequest.model_validate(req.model_dump())
+ assert revived == req
+
+
+def test_batch_result_defaults_cost_to_none_when_provider_silent():
+ """``cost_usd=None`` is the documented "provider didn't return
+ cost" sentinel that the orchestrator's rate-card fallback keys off."""
+ r = BatchResult(custom_id="x", content="{}", model="m")
+ assert r.cost_usd is None
+ assert r.error is None
+
+
+def test_batch_submission_default_status_is_pending():
+ sub = BatchSubmission(
+ provider_batch_id="b1",
+ provider="anthropic",
+ submitted_at=datetime.now(timezone.utc),
+ )
+ assert sub.status == BatchStatus.PENDING
+
+
+# ---------------------------------------------------------------------------
+# NullBatchProvider
+# ---------------------------------------------------------------------------
+
+
+async def test_null_provider_submit_reports_failed_status_with_empty_batch_id():
+ """The Null provider's contract: never succeed, fail in a way the
+ orchestrator can read structurally (no exception)."""
+ provider = NullBatchProvider()
+ sub = await provider.submit([BatchRequest(custom_id="x", model="m")])
+ assert sub.status == BatchStatus.FAILED
+ assert sub.provider_batch_id == ""
+ assert sub.provider == "null"
+
+
+async def test_null_provider_download_returns_empty_list():
+ provider = NullBatchProvider()
+ sub = BatchSubmission(
+ provider_batch_id="",
+ provider="null",
+ submitted_at=datetime.now(timezone.utc),
+ status=BatchStatus.FAILED,
+ )
+ assert await provider.download_results(sub) == []
+
+
+def test_null_provider_satisfies_batch_provider_protocol():
+ """Protocol structural check — keeps the contract honest when
+ we add methods to BatchProvider later."""
+ provider: BatchProvider = NullBatchProvider()
+ assert provider.name == "null"
+
+
+# ---------------------------------------------------------------------------
+# Factory routing
+# ---------------------------------------------------------------------------
+
+
+def test_factory_returns_null_for_sync_baseline():
+ """sync_baseline never uses batch — orchestrator gates upstream,
+ but the factory still has to handle the path without raising."""
+ provider = get_batch_provider("sync_baseline")
+ assert isinstance(provider, NullBatchProvider)
+
+
+def test_use_stub_batch_providers_flag_is_off():
+ """Step 5 of the rollout flipped this off: the orchestrator's
+ Anthropic batch path now goes directly through
+ ``backend/util/llm/providers.call_provider(execution_mode="batch")``.
+ The legacy factory + stub providers are kept around only for
+ callers that still want the Protocol-shaped abstraction (P-0.1
+ callers and the future OpenAI batch path)."""
+ assert USE_STUB_BATCH_PROVIDERS is False
+
+
+def test_factory_returns_anthropic_provider_when_unstubbed():
+ """With the stub flag off the factory hands back the real
+ AnthropicBatchProvider for ``anthropic_batch`` paths. Today this
+ is unused by the orchestrator (which calls ``call_provider``
+ directly) but kept for adapter symmetry once OpenAI batch lands."""
+ provider = get_batch_provider("anthropic_batch")
+ # Specifically NOT NullBatchProvider — the stub-gated test above
+ # would catch a regression flipping the flag back to True.
+ assert not isinstance(provider, NullBatchProvider)
+
+
+def test_factory_returns_openai_provider_when_unstubbed():
+ """Same contract for OpenAI."""
+ provider = get_batch_provider("openai_batch")
+ assert not isinstance(provider, NullBatchProvider)
+
+
+# ---------------------------------------------------------------------------
+# Stub providers raise with a clear next-step pointer
+# ---------------------------------------------------------------------------
+
+
+async def test_anthropic_stub_submit_raises_with_spec_pointer():
+ """Anyone who reaches the stub gets a clear NEXT STEP, not a
+ generic AttributeError or silent no-op."""
+ provider = AnthropicBatchProvider()
+ with pytest.raises(NotImplementedError, match="p0-spec.md §P0.1"):
+ await provider.submit([])
+
+
+async def test_openai_stub_poll_raises_with_clear_message():
+ provider = OpenAIBatchProvider()
+ with pytest.raises(NotImplementedError, match="not yet implemented"):
+ await provider.poll(
+ BatchSubmission(
+ provider_batch_id="b1",
+ provider="openai",
+ submitted_at=datetime.now(timezone.utc),
+ )
+ )
diff --git a/autogpt_platform/backend/backend/copilot/dream/batch/factory.py b/autogpt_platform/backend/backend/copilot/dream/batch/factory.py
new file mode 100644
index 0000000000..3e67df2ac6
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/batch/factory.py
@@ -0,0 +1,64 @@
+"""Pick a BatchProvider for a given ExecutionPath + config state.
+
+Single seam the orchestrator calls when it routes to a batch path.
+Today the AnthropicBatchProvider and OpenAIBatchProvider are stubs;
+this factory always returns the Null provider so the orchestrator's
+batch path short-circuits to sync_baseline cleanly when the stubs
+are detected. As soon as the real adapters land, flip the
+``USE_STUB_BATCH_PROVIDERS`` flag off and the orchestrator picks
+them up automatically.
+
+The factory deliberately does NOT read provider API keys here —
+``resolve_dream_execution_path`` in routing.py already gates on
+``has_anthropic_key`` / ``has_openai_key`` upstream. If we get to
+this factory, the routing decision said "use this batch path"; our
+job is only to hand back a working provider for that path.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from ..routing import ExecutionPath
+from .anthropic_provider import AnthropicBatchProvider
+from .openai_provider import OpenAIBatchProvider
+from .provider import BatchProvider, NullBatchProvider
+
+logger = logging.getLogger(__name__)
+
+
+# The orchestrator's Anthropic batch path now goes directly through
+# ``backend/util/llm/providers.call_provider(execution_mode="batch")``;
+# this factory is preserved only for callers that still want the
+# Protocol-shaped provider abstraction (P-0.1 stub callers, future
+# OpenAI batch path). Flipped to ``False`` as of Step 5 of the
+# plan in ``plans/idempotent-launching-moth.md`` so the orchestrator
+# isn't confused into thinking the providers are stubbed.
+USE_STUB_BATCH_PROVIDERS = False
+
+
+def get_batch_provider(execution_path: ExecutionPath) -> BatchProvider:
+ """Return the BatchProvider for the chosen execution path.
+
+ ``sync_baseline`` always returns the Null provider — sync runs
+ don't use batch at all; the orchestrator gates on the path
+ before calling this. The function still accepts sync_baseline to
+ avoid a special case at the call site.
+ """
+ if execution_path == "sync_baseline":
+ return NullBatchProvider()
+
+ if USE_STUB_BATCH_PROVIDERS:
+ logger.info(
+ "dream batch: execution_path=%s but providers are stubbed; "
+ "returning NullBatchProvider — orchestrator should fall back "
+ "to sync_baseline.",
+ execution_path,
+ )
+ return NullBatchProvider()
+
+ if execution_path == "anthropic_batch":
+ return AnthropicBatchProvider()
+ if execution_path == "openai_batch":
+ return OpenAIBatchProvider()
+ return NullBatchProvider()
diff --git a/autogpt_platform/backend/backend/copilot/dream/batch/models.py b/autogpt_platform/backend/backend/copilot/dream/batch/models.py
new file mode 100644
index 0000000000..7997bbe581
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/batch/models.py
@@ -0,0 +1,102 @@
+"""Provider-agnostic typed shapes for batch dream passes.
+
+Both Anthropic and OpenAI expose a similar API surface:
+ 1. Submit N message-completion requests in one HTTP call.
+ 2. Poll until the batch is processing → ended.
+ 3. Download JSONL results, route per-request by ``custom_id``.
+
+These models normalize that surface so the orchestrator never knows
+which provider it's talking to. Per-provider quirks (Anthropic's
+``ended_at`` vs OpenAI's ``completed_at``, beta header requirements,
+JSONL line format) live in the per-provider adapter.
+
+The schema is intentionally narrower than either provider's full
+API — we only model what the dream pipeline uses, so neither provider
+has to be feature-complete to wire in.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class BatchStatus(str, Enum):
+ """Lifecycle states a submitted batch can be in.
+
+ Both providers have richer status enums (Anthropic adds
+ ``canceling``, ``expired``; OpenAI adds ``finalizing``,
+ ``cancelling``). Normalize to these four because the dream
+ pipeline only cares about "is this done yet" + "should I retry".
+ """
+
+ PENDING = "pending"
+ """Submitted; provider hasn't started processing."""
+ PROCESSING = "processing"
+ """Provider is generating responses."""
+ ENDED = "ended"
+ """Finished — results ready to download."""
+ FAILED = "failed"
+ """Provider returned an unrecoverable error. Surfaces as ``error``."""
+
+
+class BatchRequest(BaseModel):
+ """One LLM call inside a submitted batch.
+
+ ``custom_id`` is opaque to the provider — we use it to route the
+ response back to the correct dream pass + phase. Convention:
+ ``"{pass_id}:{phase}"``. The dream pipeline only ever submits 3
+ requests per pass (one per phase), so collisions are impossible.
+ """
+
+ custom_id: str = Field(description="Routing key the orchestrator uses.")
+ model: str
+ messages: list[dict[str, Any]] = Field(default_factory=list)
+ response_format: dict[str, Any] | None = None
+ max_output_tokens: int = 4096
+ temperature: float = 0.0
+
+
+class BatchResult(BaseModel):
+ """One LLM response inside a downloaded batch result.
+
+ Mirrors ``StructuredCompletion`` from ``dream/llm.py`` but
+ deserialized from a batch JSONL line rather than a real-time
+ completion. The orchestrator hands ``content`` to the same parser
+ that handles sync responses (``_strip_json_code_fence`` +
+ ``_extract_first_json_object``), so phase-2/3 lenient parsing
+ keeps working on batch results.
+ """
+
+ custom_id: str
+ content: str
+ """Raw response body — JSON string ready for the phase parser."""
+ model: str
+ input_tokens: int = 0
+ output_tokens: int = 0
+ cache_read_tokens: int = 0
+ cache_creation_tokens: int = 0
+ cost_usd: float | None = None
+ error: str | None = None
+ """Per-request error (e.g. moderation rejection); does NOT fail
+ the whole batch. Surface so the orchestrator can record it as
+ a phase failure and supersede the dream pass."""
+
+
+class BatchSubmission(BaseModel):
+ """Provider's acknowledgement of a submission.
+
+ ``provider_batch_id`` is what the poller uses to look up status
+ later — Anthropic returns a UUID, OpenAI returns ``"batch_..."``.
+ Both are opaque strings to us.
+ """
+
+ provider_batch_id: str
+ provider: str
+ """``"anthropic"`` | ``"openai"`` — the same string used as the
+ ``provider`` tag on ``PlatformCostLog`` rows."""
+ submitted_at: datetime
+ status: BatchStatus = BatchStatus.PENDING
diff --git a/autogpt_platform/backend/backend/copilot/dream/batch/openai_provider.py b/autogpt_platform/backend/backend/copilot/dream/batch/openai_provider.py
new file mode 100644
index 0000000000..7807b23bae
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/batch/openai_provider.py
@@ -0,0 +1,60 @@
+"""OpenAI Batch API adapter — IMPLEMENTATION STUB.
+
+The real adapter wraps ``openai.AsyncOpenAI().batches`` + ``.files``.
+OpenAI's batch flow is two-step:
+
+1. Upload a JSONL file via ``client.files.create(purpose="batch")``.
+ Each line is one ``ChatCompletion`` request with a ``custom_id``.
+2. Create a batch via ``client.batches.create(input_file_id=...,
+ endpoint="/v1/chat/completions", completion_window="24h")``.
+
+Polling/downloading mirror the Anthropic flow but the JSONL line
+format differs — see https://platform.openai.com/docs/guides/batch.
+
+Stub today, real impl in a follow-up PR. Filling this in is mostly
+mechanical:
+
+1. ``submit`` — write the requests to an in-memory buffer, upload
+ via ``files.create``, then ``batches.create``.
+2. ``poll`` — ``batches.retrieve(batch_id)``; normalize
+ ``status`` (``validating`` / ``in_progress`` / ``finalizing`` /
+ ``completed`` / ``failed``) onto ``BatchStatus``.
+3. ``download_results`` — download ``output_file_id`` via
+ ``files.content(...)``, parse JSONL, extract
+ ``response.body.choices[0].message.content`` +
+ ``response.body.usage``. Track ``error_file_id`` separately for
+ per-request errors.
+
+The ``cost_usd`` field comes from ``model_pricing.compute_cost_usd``
+with ``execution_path="openai_batch"`` (50% discount applied).
+OpenAI's batch responses don't carry a cost field either.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from .models import BatchRequest, BatchResult, BatchSubmission
+
+
+class OpenAIBatchProvider:
+ """Stub placeholder. See module docstring for the implementation
+ plan. Calling any method raises ``NotImplementedError`` with a
+ pointer to ``p0-spec.md §P0.1``."""
+
+ name = "openai"
+
+ async def submit(self, requests: Sequence[BatchRequest]) -> BatchSubmission:
+ raise NotImplementedError(
+ "OpenAIBatchProvider.submit not yet implemented — "
+ "see dream/p0-spec.md §P0.1 and "
+ "dream/batch/openai_provider.py module docstring."
+ )
+
+ async def poll(self, submission: BatchSubmission) -> BatchSubmission:
+ raise NotImplementedError("OpenAIBatchProvider.poll not yet implemented.")
+
+ async def download_results(self, submission: BatchSubmission) -> list[BatchResult]:
+ raise NotImplementedError(
+ "OpenAIBatchProvider.download_results not yet implemented."
+ )
diff --git a/autogpt_platform/backend/backend/copilot/dream/batch/provider.py b/autogpt_platform/backend/backend/copilot/dream/batch/provider.py
new file mode 100644
index 0000000000..a7cc9ba104
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/batch/provider.py
@@ -0,0 +1,84 @@
+"""BatchProvider Protocol + a Null implementation.
+
+Every concrete batch provider (Anthropic, OpenAI) implements this
+Protocol. The Null provider always reports submission failure with a
+documented error so the orchestrator falls back to sync_baseline. The
+dream pipeline can wire BatchProvider in today and pick up
+real-Anthropic / real-OpenAI when those adapters land.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Protocol, Sequence
+
+from .models import BatchRequest, BatchResult, BatchStatus, BatchSubmission
+
+logger = logging.getLogger(__name__)
+
+
+class BatchProvider(Protocol):
+ """What a concrete batch backend (Anthropic / OpenAI) must implement.
+
+ Lifecycle:
+ 1. ``submit(requests)`` → returns a ``BatchSubmission`` whose
+ ``provider_batch_id`` is the lookup key.
+ 2. ``poll(submission)`` → returns the same submission with an
+ updated ``status``. Caller decides when to poll again.
+ 3. ``download_results(submission)`` → returns the per-request
+ responses. Only safe to call when status is ``ENDED``.
+
+ Cancellation, retries, and exponential-backoff polling cadence
+ are the *caller's* responsibility (lives in ``poller.py`` once
+ that module is filled in). The provider only owns the API surface.
+ """
+
+ name: str
+
+ async def submit(self, requests: Sequence[BatchRequest]) -> BatchSubmission: ...
+
+ async def poll(self, submission: BatchSubmission) -> BatchSubmission: ...
+
+ async def download_results(
+ self, submission: BatchSubmission
+ ) -> list[BatchResult]: ...
+
+
+class NullBatchProvider:
+ """Always-fails BatchProvider.
+
+ Returned by ``factory.get_batch_provider`` when neither Anthropic
+ nor OpenAI is configured (no API key, or batch flag off). Surfaces
+ a structured "no batch backend" error so the orchestrator's batch
+ path can short-circuit to sync_baseline cleanly instead of crashing
+ on a missing adapter.
+
+ Submitting against this provider yields a synthetic ``FAILED``
+ submission whose ``provider_batch_id`` is empty; polling and
+ downloading return the same status and an empty result list. The
+ orchestrator should never reach the download step against a Null
+ provider, but defending against it is a one-liner so we do.
+ """
+
+ name = "null"
+
+ async def submit(self, requests: Sequence[BatchRequest]) -> BatchSubmission:
+ logger.info(
+ "NullBatchProvider.submit() called with %d requests — no "
+ "batch backend configured; caller should fall back to "
+ "sync_baseline.",
+ len(requests),
+ )
+ return BatchSubmission(
+ provider_batch_id="",
+ provider=self.name,
+ submitted_at=datetime.now(timezone.utc),
+ status=BatchStatus.FAILED,
+ )
+
+ async def poll(self, submission: BatchSubmission) -> BatchSubmission:
+ return submission
+
+ async def download_results(self, submission: BatchSubmission) -> list[BatchResult]:
+ return []
diff --git a/autogpt_platform/backend/backend/copilot/dream/batch_callbacks.py b/autogpt_platform/backend/backend/copilot/dream/batch_callbacks.py
new file mode 100644
index 0000000000..075f10d60f
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/batch_callbacks.py
@@ -0,0 +1,974 @@
+"""Dream-pass batch result handler — sequential phase chain.
+
+Registered with the BatchExecutor service under namespace
+``"dream_pass"`` at module-import time. When a batch the dream pass
+submitted finishes, the BatchExecutor calls
+``handle_dream_batch_result`` with the per-``custom_id`` result rows
+plus the pending entry's ``payload``.
+
+Dream's three phases are sequentially dependent:
+
+ consolidate → recombine (needs consolidate output)
+ → sanitize (needs both)
+
+That means a phase can only be submitted once the prior phase's
+result lands. The orchestrator kicks off phase 1; this handler chains
+phase 2 from phase 1's result, phase 3 from phase 2's result, then
+runs the apply step + cost log + JobStatus complete when phase 3 lands.
+
+Per-pass state lives in two Redis keys:
+
+ * ``dream:batch:input:{pass_id}`` — the serialized ``DreamInput``
+ (so we can rebuild each phase's prompt without re-fetching from
+ Postgres / FalkorDB) plus the dream lock's ownership token for the
+ compare-and-delete release
+ * ``dream:batch:state:{pass_id}`` — accumulated phase outputs +
+ per-phase token usage so the apply step has everything it needs
+ and the cost log can record all three rows at once
+
+Both are TTL'd to 24h (Anthropic's batch SLA) so a forgotten pass
+naturally falls off the radar. Two SETNX gates (7-day TTL) keep the
+side effects at-most-once across batch re-dispatch:
+``dream:applied:{pass_id}`` for the memory writes and
+``dream:batch:costs_logged:{pass_id}`` for billing.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import ValidationError
+
+from .batch_submit import (
+ PHASE_RESPONSE_MODELS,
+ delete_input_bundle,
+ read_input_bundle,
+ read_lock_token,
+ submit_phase,
+)
+from .billing import record_phase_cost
+from .locks import release_dream_lock
+from .model_pricing import compute_cost_usd
+from .schemas import DreamOperations, DreamOperationsSnapshot, PhaseUsage
+
+if TYPE_CHECKING:
+ from backend.executor.batch_executor import PendingEntry
+ from backend.util.llm.providers import BatchResultRow
+
+logger = logging.getLogger(__name__)
+
+
+NAMESPACE = "dream_pass"
+
+DreamPhase = Literal["consolidate", "recombine", "sanitize"]
+
+NEXT_PHASE: dict[DreamPhase, DreamPhase | None] = {
+ "consolidate": "recombine",
+ "recombine": "sanitize",
+ "sanitize": None, # terminal — apply runs from here
+}
+
+
+# ---------------------------------------------------------------------------
+# State persistence
+# ---------------------------------------------------------------------------
+
+
+def _state_key(pass_id: str) -> str:
+ return f"dream:batch:state:{pass_id}"
+
+
+# 24h matches Anthropic's batch SLA; if no phase has landed in that
+# window the BatchExecutor has already issued a timeout error via
+# ``MAX_BATCH_LIFETIME_SECONDS``.
+STATE_TTL_SECONDS = 24 * 60 * 60
+
+
+async def _read_state(pass_id: str) -> dict[str, dict[str, Any]]:
+ """Per-pass accumulator: phase → {content, usage tokens, error}.
+
+ Returns a ``dict[str, ...]`` rather than ``dict[DreamPhase, ...]``
+ because Redis hash keys are plain strings and we lose the
+ ``Literal`` narrowing the moment we read them back. Callers
+ re-narrow at the boundary (e.g. via ``NEXT_PHASE`` lookups) when
+ they need the phase ordering.
+ """
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ raw = await redis.hgetall(_state_key(pass_id)) # type: ignore[misc]
+ out: dict[str, dict[str, Any]] = {}
+ for phase, body in (raw or {}).items():
+ if isinstance(phase, bytes):
+ phase = phase.decode("utf-8")
+ if isinstance(body, bytes):
+ body = body.decode("utf-8")
+ try:
+ out[phase] = json.loads(body)
+ except Exception:
+ logger.warning("Corrupted state row for pass=%s phase=%s", pass_id, phase)
+ return out
+
+
+async def _write_phase_to_state(
+ *, pass_id: str, phase: DreamPhase, row: "BatchResultRow"
+) -> None:
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ body = json.dumps(
+ {
+ "custom_id": row.custom_id,
+ "content": row.content,
+ "input_tokens": row.input_tokens,
+ "output_tokens": row.output_tokens,
+ "cache_read_tokens": row.cache_read_tokens,
+ "cache_creation_tokens": row.cache_creation_tokens,
+ "error": row.error,
+ }
+ )
+ await redis.hset(_state_key(pass_id), phase, body) # type: ignore[misc]
+ await redis.expire(_state_key(pass_id), STATE_TTL_SECONDS)
+
+
+async def _delete_state(pass_id: str) -> None:
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ await redis.delete(_state_key(pass_id))
+
+
+def _phase_models_from_payload(payload: dict[str, Any]) -> dict[str, str]:
+ """Per-phase model map persisted by ``submit_phase`` — used to chain
+ the next phase and to price each phase with the model it actually
+ used. Empty when absent (current code never omits it)."""
+ raw = payload.get("phase_models")
+ if not isinstance(raw, dict):
+ return {}
+ return {str(k): str(v) for k, v in raw.items()}
+
+
+async def _mark_job_errored_best_effort(job_id: str, error: str) -> None:
+ """Close the admin job row on a dead-end the normal fail path can't
+ reach (malformed payload). Best-effort: status write failures are
+ logged, never raised."""
+ if not job_id:
+ return
+ try:
+ from .job_status import mark_errored
+
+ await mark_errored(kind="dream_pass", job_id=job_id, error=error)
+ except Exception:
+ logger.exception("Failed to mark dead-end job %s errored", job_id[:12])
+
+
+async def _finalize_stuck_duplicate(
+ *, user_id: str, pass_id: str, job_id: str, ops: DreamOperations
+) -> None:
+ """On a duplicate delivery, finalize the job row iff the first
+ delivery crashed between apply and ``mark_complete`` and left it
+ non-terminal. An already-terminal row is left untouched so the
+ first delivery's real apply stats are never overwritten.
+
+ Best-effort: a status read/write failure here must not crash the
+ duplicate tail (lock release + cleanup still need to run)."""
+ if not job_id:
+ return
+ try:
+ from .job_status import mark_complete, read_status
+ from .schemas import DreamPassResult
+
+ existing = await read_status(kind="dream_pass", job_id=job_id)
+ if existing is None or existing.state in ("complete", "errored"):
+ return
+ logger.warning(
+ "Duplicate dispatch found job %s stuck in state=%s — "
+ "finalizing with the clamped op counts",
+ job_id[:12],
+ existing.state,
+ )
+ # The first delivery's per-edge outcomes (and dream session id)
+ # died with it, so the counts here are the clamped *attempted*
+ # ops — annotate the summary so the admin UI doesn't present
+ # them as confirmed apply results.
+ note = (
+ "[finalized after duplicate delivery — counts reflect attempted "
+ "operations; writes landed with the original delivery] "
+ )
+ await mark_complete(
+ kind="dream_pass",
+ job_id=job_id,
+ result=DreamPassResult(
+ user_id=user_id,
+ pass_id=pass_id,
+ execution_path="anthropic_batch",
+ consolidated_count=len(ops.writes),
+ proposal_count=len(ops.proposals),
+ demotion_count=len(ops.demotions),
+ entity_invalidation_count=len(ops.entity_invalidations),
+ summary_for_user=note + (ops.summary_for_user or ""),
+ ),
+ )
+ except Exception:
+ logger.exception("Failed to finalize stuck duplicate for job %s", job_id[:12])
+
+
+async def _best_effort_cleanup(pass_id: str) -> None:
+ """Delete the per-pass state + input bundle without letting a Redis
+ blip propagate. These deletes run AFTER ``mark_complete`` on the
+ success/duplicate tails — an exception here would route through the
+ crash guard to ``_fail_pass`` and rewrite a completed job to errored.
+ Both keys carry 24h TTLs, so a failed delete self-heals."""
+ try:
+ await _delete_state(pass_id)
+ await delete_input_bundle(pass_id)
+ except Exception:
+ logger.exception(
+ "Per-pass cleanup failed for pass=%s — keys will expire via TTL",
+ pass_id,
+ )
+
+
+async def _release_lock(user_id: str, pass_id: str) -> None:
+ """Release the disowned dream lock with the ownership token persisted
+ alongside the input bundle. Must run before ``delete_input_bundle`` —
+ the token rides on that key. A missing token (bundle TTL'd out,
+ malformed payload) leaves the lock for its TTL to clear rather than
+ blind-deleting what may be a newer pass's lock.
+
+ Best-effort like ``release_dream_lock`` itself: a Redis blip on the
+ token read must not propagate — on the success tail it would fire
+ AFTER ``mark_complete`` and the crash guard would rewrite a completed
+ job to errored. Falls back to a token-less release (lock TTL)."""
+ token: str | None = None
+ if pass_id:
+ try:
+ token = await read_lock_token(pass_id)
+ except Exception:
+ logger.exception(
+ "Failed to read dream lock token for pass=%s — "
+ "leaving the lock to its TTL",
+ pass_id,
+ )
+ await release_dream_lock(user_id, token)
+
+
+# ---------------------------------------------------------------------------
+# Handler entry point
+# ---------------------------------------------------------------------------
+
+
+async def handle_dream_batch_result(
+ entry: "PendingEntry", rows: list["BatchResultRow"]
+) -> None:
+ """BatchExecutor entry — called once per finished phase batch.
+
+ Reads the phase label off ``entry.payload``, validates the
+ response shape, persists it to the per-pass accumulator, then
+ decides what to do next:
+
+ * If error → mark JobStatus errored, clean up state + input
+ * If non-terminal phase → submit next phase batch, leave job
+ in ``submitted`` state with updated ``current_phase``
+ * If terminal phase (sanitize) → run apply, log costs for all
+ three phases, mark JobStatus complete, clean up
+ """
+ payload = entry.payload or {}
+ user_id = str(payload.get("user_id") or "")
+ pass_id = str(payload.get("pass_id") or "")
+ job_id = str(payload.get("job_id") or "")
+ phase_models = _phase_models_from_payload(payload)
+ phase = payload.get("phase")
+
+ if not user_id or not pass_id or not phase:
+ logger.warning(
+ "Dream batch handler missing user_id/pass_id/phase — payload=%s",
+ payload,
+ )
+ # Dead-end payload: close the admin job row (it would otherwise sit
+ # queued/submitted until its TTL) and release the disowned lock so
+ # the user isn't locked out until the 24h TTL.
+ await _mark_job_errored_best_effort(
+ job_id, "batch payload missing user_id/pass_id/phase"
+ )
+ if user_id:
+ await _release_lock(user_id, pass_id)
+ return
+
+ if phase not in NEXT_PHASE:
+ logger.warning("Dream batch handler unknown phase=%r", phase)
+ await _mark_job_errored_best_effort(job_id, f"unknown batch phase {phase!r}")
+ await _release_lock(user_id, pass_id)
+ return
+
+ try:
+ await _handle_phase_result(
+ rows=rows,
+ user_id=user_id,
+ pass_id=pass_id,
+ job_id=job_id,
+ phase_models=phase_models,
+ phase=phase,
+ )
+ except Exception:
+ # The batch path disowned the per-user dream lock to this callback,
+ # and BatchExecutor._dispatch swallows handler exceptions — so without
+ # this guard an unexpected error here would strand the user behind the
+ # disowned lock until its extended TTL expired and leave the admin
+ # JobStatus row stuck. Route the crash through _fail_pass (releases the
+ # lock + marks the job errored); if even that fails, release the lock
+ # directly so the user is never blocked on a leaked lock.
+ logger.exception(
+ "Dream batch handler crashed for pass=%s phase=%s", pass_id, phase
+ )
+ try:
+ await _fail_pass(
+ user_id=user_id,
+ pass_id=pass_id,
+ job_id=job_id,
+ phase_models=phase_models,
+ error=f"{phase}: handler crashed",
+ )
+ except Exception:
+ logger.exception("Dream batch _fail_pass also failed for pass=%s", pass_id)
+ try:
+ await _release_lock(user_id, pass_id)
+ except Exception:
+ logger.exception(
+ "Dream batch lock release failed for user=%s", user_id[:12]
+ )
+
+
+async def _handle_phase_result(
+ *,
+ rows: list["BatchResultRow"],
+ user_id: str,
+ pass_id: str,
+ job_id: str,
+ phase_models: dict[str, str],
+ phase: DreamPhase,
+) -> None:
+ """Validate one finished phase batch, then chain to the next phase or
+ finalize.
+
+ Split out from ``handle_dream_batch_result`` so the latter can wrap
+ this in a single crash guard that always releases the disowned dream
+ lock — every early-return below already finalizes via ``_fail_pass``,
+ but an *unexpected* raise (Redis blip, apply bug) must not leak the
+ lock either.
+ """
+ if not rows:
+ logger.warning("Dream batch handler got empty rows for pass=%s", pass_id)
+ await _fail_pass(
+ user_id=user_id,
+ pass_id=pass_id,
+ job_id=job_id,
+ phase_models=phase_models,
+ error=f"{phase}: provider returned no rows",
+ )
+ return
+
+ # Single-request-per-batch today; the first (and only) row is the
+ # phase result. When we group batches in the future the BatchExecutor
+ # will already split by custom_id before calling us.
+ row = rows[0]
+ if row.error:
+ await _write_phase_to_state(pass_id=pass_id, phase=phase, row=row)
+ await _fail_pass(
+ user_id=user_id,
+ pass_id=pass_id,
+ job_id=job_id,
+ phase_models=phase_models,
+ error=f"{phase}: {row.error}",
+ )
+ return
+
+ # Validate the row's content matches the phase's Pydantic schema
+ # BEFORE persisting — corrupted content shouldn't pollute the
+ # accumulator for the next phase to read back.
+ try:
+ PHASE_RESPONSE_MODELS[phase].model_validate(json.loads(row.content))
+ except (json.JSONDecodeError, ValidationError) as exc:
+ await _write_phase_to_state(pass_id=pass_id, phase=phase, row=row)
+ await _fail_pass(
+ user_id=user_id,
+ pass_id=pass_id,
+ job_id=job_id,
+ phase_models=phase_models,
+ error=f"{phase}: invalid output shape — {type(exc).__name__}",
+ )
+ return
+
+ await _write_phase_to_state(pass_id=pass_id, phase=phase, row=row)
+
+ next_phase = NEXT_PHASE[phase]
+ if next_phase is not None:
+ await _chain_next_phase(
+ user_id=user_id,
+ pass_id=pass_id,
+ job_id=job_id,
+ phase_models=phase_models,
+ next_phase=next_phase,
+ )
+ return
+
+ # Terminal phase landed — apply + finalize.
+ await _finalize_complete(
+ user_id=user_id,
+ pass_id=pass_id,
+ job_id=job_id,
+ phase_models=phase_models,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Phase chaining
+# ---------------------------------------------------------------------------
+
+
+async def _chain_next_phase(
+ *,
+ user_id: str,
+ pass_id: str,
+ job_id: str,
+ phase_models: dict[str, str],
+ next_phase: DreamPhase,
+) -> None:
+ """Submit the next phase in the chain.
+
+ Reads the persisted ``DreamInput`` + accumulated prior phase
+ outputs from Redis, builds the next phase's prompt, fires another
+ batch submission. On any failure to submit, marks the JobStatus
+ errored — silent submission failures are unrecoverable.
+ """
+ input_bundle = await read_input_bundle(pass_id)
+ if input_bundle is None:
+ await _fail_pass(
+ user_id=user_id,
+ pass_id=pass_id,
+ job_id=job_id,
+ phase_models=phase_models,
+ error=f"{next_phase}: DreamInput missing from Redis (TTL expired?)",
+ )
+ return
+
+ state = await _read_state(pass_id)
+ consolidated_json = _content_for(state, "consolidate")
+ recombined_json = _content_for(state, "recombine")
+
+ api_key = _anthropic_api_key()
+ if api_key is None:
+ await _fail_pass(
+ user_id=user_id,
+ pass_id=pass_id,
+ job_id=job_id,
+ phase_models=phase_models,
+ error=f"{next_phase}: no Anthropic API key configured",
+ )
+ return
+
+ try:
+ submission = await submit_phase(
+ user_id=user_id,
+ pass_id=pass_id,
+ job_id=job_id,
+ phase=next_phase,
+ phase_models=phase_models,
+ api_key=api_key,
+ input_bundle=input_bundle,
+ consolidated_json=consolidated_json,
+ recombined_json=recombined_json,
+ )
+ except Exception as exc:
+ logger.exception(
+ "Failed to submit %s phase for pass=%s — marking errored",
+ next_phase,
+ pass_id,
+ )
+ await _fail_pass(
+ user_id=user_id,
+ pass_id=pass_id,
+ job_id=job_id,
+ phase_models=phase_models,
+ error=f"{next_phase}: submit failed: {type(exc).__name__}: {exc}",
+ )
+ return
+
+ if job_id:
+ try:
+ from .job_status import update_status_phase
+
+ await update_status_phase(
+ kind="dream_pass",
+ job_id=job_id,
+ state="submitted",
+ current_phase=next_phase,
+ batch_id=submission.provider_batch_id,
+ )
+ except Exception:
+ logger.exception(
+ "Failed to update status for next phase=%s pass=%s",
+ next_phase,
+ pass_id,
+ )
+
+
+def _content_for(state: dict[str, dict[str, Any]], phase: str) -> str | None:
+ row = state.get(phase)
+ if row is None:
+ return None
+ content = row.get("content")
+ return content if isinstance(content, str) else None
+
+
+# ---------------------------------------------------------------------------
+# Terminal handlers
+# ---------------------------------------------------------------------------
+
+
+_APPLIED_GATE_PREFIX = "dream:applied"
+# 7 days — same window as the costs_logged gate; no realistic
+# BatchExecutor re-dispatch (poll backoff caps at 5 min, max lifetime
+# 24h) can outlive it.
+_APPLIED_GATE_TTL_SECONDS = 7 * 24 * 60 * 60
+
+
+async def _claim_apply_gate(pass_id: str) -> Literal["claimed", "duplicate", "error"]:
+ """Atomically claim the per-pass apply gate.
+
+ Returns ``"claimed"`` when this delivery is the first to run
+ ``apply_operations`` for the pass, ``"duplicate"`` on a re-dispatched
+ delivery whose writes already landed, and ``"error"`` when Redis is
+ unavailable and we cannot tell which of the two we are.
+
+ Mirrors ``_claim_costs_logged_gate``: if the BatchExecutor crashes
+ between dispatch and ``remove_pending``, the next poll re-dispatches
+ the same finished batch — and ``apply_operations`` writes every
+ consolidated fact and proposal to the user's graph as fresh episodes,
+ so re-running it duplicates the user's memories. The three states must
+ stay distinct: treating a Redis brown-out as a duplicate would mark
+ the job complete with zero writes, silently dropping the dream.
+ """
+ from backend.data.redis_client import get_redis_async
+
+ try:
+ redis = await get_redis_async()
+ claimed = await redis.set(
+ f"{_APPLIED_GATE_PREFIX}:{pass_id}",
+ "1",
+ nx=True,
+ ex=_APPLIED_GATE_TTL_SECONDS,
+ )
+ return "claimed" if claimed else "duplicate"
+ except Exception:
+ logger.exception(
+ "Failed to claim apply gate for pass=%s — failing pass",
+ pass_id,
+ )
+ return "error"
+
+
+async def _finalize_complete(
+ *, user_id: str, pass_id: str, job_id: str, phase_models: dict[str, str]
+) -> None:
+ """Sanitize phase has landed. Run apply + cost log + complete."""
+ try:
+ from .apply import apply_operations
+ from .orchestrator import _clamp_operations
+ except Exception:
+ logger.exception("Failed to import dream apply for pass=%s", pass_id)
+ await _fail_pass(
+ user_id=user_id,
+ pass_id=pass_id,
+ job_id=job_id,
+ phase_models=phase_models,
+ error="apply: import failed",
+ )
+ return
+
+ state = await _read_state(pass_id)
+ sanitize_row = state.get("sanitize")
+ if sanitize_row is None or not sanitize_row.get("content"):
+ await _fail_pass(
+ user_id=user_id,
+ pass_id=pass_id,
+ job_id=job_id,
+ phase_models=phase_models,
+ error="sanitize: missing terminal phase content",
+ )
+ return
+
+ try:
+ ops = DreamOperations.model_validate(json.loads(sanitize_row["content"]))
+ except (json.JSONDecodeError, ValidationError) as exc:
+ await _fail_pass(
+ user_id=user_id,
+ pass_id=pass_id,
+ job_id=job_id,
+ phase_models=phase_models,
+ error=f"sanitize: shape validation failed: {type(exc).__name__}",
+ )
+ return
+
+ # Enforce the same per-pass operation caps the sync path applies
+ # before writing — the model can over-emit past the prompt's limits.
+ # The 5%-of-active-facts demotion ceiling needs the original fact
+ # count; the persisted input bundle still exists here (deleted only
+ # after apply below). A missing bundle (-1) falls back to the
+ # absolute demotion cap rather than zeroing all demotions.
+ input_bundle = await read_input_bundle(pass_id)
+ active_fact_count = len(input_bundle.facts) if input_bundle is not None else -1
+ # Pass the known-fact allowlist so hallucinated demotion uuids are
+ # filtered BEFORE the cap slice — otherwise they consume cap slots
+ # and displace valid demotions (cap can floor at 1 on small graphs).
+ ops = _clamp_operations(
+ ops,
+ active_fact_count,
+ known_fact_uuids=(
+ input_bundle.known_fact_uuids if input_bundle is not None else None
+ ),
+ )
+
+ # Batch results can re-dispatch (executor crash between dispatch and
+ # ``remove_pending``). Billing below is gated; the memory mutation must
+ # be too. A duplicate delivery skips apply AND mark_complete — the first
+ # delivery already wrote the real stats, and overwriting them with empty
+ # ones would zero the admin-visible counts. A gate error fails the pass:
+ # we cannot tell first-vs-duplicate apart, and "complete with no writes"
+ # would silently drop the dream.
+ gate = await _claim_apply_gate(pass_id)
+ if gate == "error":
+ await _fail_pass(
+ user_id=user_id,
+ pass_id=pass_id,
+ job_id=job_id,
+ phase_models=phase_models,
+ error="apply: gate unavailable (redis) — cannot guarantee at-most-once",
+ )
+ return
+ if gate == "duplicate":
+ logger.info(
+ "Duplicate dispatch for pass=%s — operations already applied; "
+ "preserving the first delivery's job result",
+ pass_id,
+ )
+ # Normally the first delivery wrote the terminal status. If it
+ # crashed between apply and mark_complete, the row is stuck in
+ # 'submitted' — finalize it here WITHOUT clobbering an existing
+ # terminal result (the apply counts are this pass's clamped ops;
+ # the writes themselves landed with the first delivery).
+ await _finalize_stuck_duplicate(
+ user_id=user_id, pass_id=pass_id, job_id=job_id, ops=ops
+ )
+ await _log_all_phase_costs(
+ user_id=user_id, pass_id=pass_id, state=state, phase_models=phase_models
+ )
+ await _release_lock(user_id, pass_id)
+ await _best_effort_cleanup(pass_id)
+ return
+
+ apply_stats: dict[str, int | str | DreamOperationsSnapshot] = {}
+ try:
+ # Thread the demotion allowlist from the bundle already in memory —
+ # letting apply re-read it would do a second Redis GET + full JSON
+ # deserialize and could fail open if the bundle's TTL lapses between
+ # the two reads. None (bundle expired) keeps apply's documented
+ # fail-open fallback.
+ apply_stats = await apply_operations(
+ user_id,
+ pass_id,
+ ops,
+ known_fact_uuids=(
+ input_bundle.known_fact_uuids if input_bundle is not None else None
+ ),
+ )
+ except Exception as exc:
+ logger.exception(
+ "apply_operations crashed for batch pass=%s — marking errored",
+ pass_id,
+ )
+ await _fail_pass(
+ user_id=user_id,
+ pass_id=pass_id,
+ job_id=job_id,
+ phase_models=phase_models,
+ error=f"apply: {type(exc).__name__}: {exc}",
+ )
+ return
+
+ # Per-phase usage log on the success path. Failure paths record the
+ # same usage via ``_fail_pass`` (we incurred those provider tokens
+ # regardless); the Redis dedup gate inside ``_log_all_phase_costs``
+ # keeps it at-most-once across both paths and any batch re-dispatch.
+ await _log_all_phase_costs(
+ user_id=user_id, pass_id=pass_id, state=state, phase_models=phase_models
+ )
+
+ if job_id:
+ try:
+ from .job_status import mark_complete
+ from .schemas import DreamPassResult
+
+ raw_snapshot = apply_stats.get("snapshot")
+ snapshot: DreamOperationsSnapshot | None = None
+ if isinstance(raw_snapshot, DreamOperationsSnapshot):
+ snapshot = raw_snapshot
+ elif isinstance(raw_snapshot, dict):
+ snapshot = DreamOperationsSnapshot.model_validate(raw_snapshot)
+
+ # ``apply_stats`` values are typed as a union that includes
+ # ``DreamOperationsSnapshot``; narrow each count to a plain
+ # ``int`` (with a 0 default) before threading it into the
+ # Pydantic result so pyright doesn't flag the int() cast.
+ def _count(key: str) -> int:
+ value = apply_stats.get(key)
+ if isinstance(value, (int, str)):
+ try:
+ return int(value)
+ except (TypeError, ValueError):
+ return 0
+ return 0
+
+ raw_session_id = apply_stats.get("session_id")
+ session_id = raw_session_id if isinstance(raw_session_id, str) else None
+
+ pass_result = DreamPassResult(
+ user_id=user_id,
+ pass_id=pass_id,
+ execution_path="anthropic_batch",
+ consolidated_count=_count("consolidated_count"),
+ proposal_count=_count("proposal_count"),
+ demotion_count=_count("demotion_count"),
+ entity_invalidation_count=_count("entity_invalidation_count"),
+ dream_session_id=session_id,
+ operations=snapshot,
+ # Carry the user-facing narrative like the sync path does —
+ # without it the Memory Visualizer renders a blank summary for
+ # batch-completed dreams even though the session message exists.
+ summary_for_user=ops.summary_for_user,
+ )
+ await mark_complete(kind="dream_pass", job_id=job_id, result=pass_result)
+ except Exception:
+ logger.exception("Failed to mark dream pass job %s complete", job_id)
+
+ # The batch path disowned the dream lock to this callback; release it now
+ # that the pass has terminated so the next dream for this user can run.
+ await _release_lock(user_id, pass_id)
+ await _best_effort_cleanup(pass_id)
+
+
+async def _fail_pass(
+ *,
+ user_id: str,
+ pass_id: str,
+ job_id: str,
+ phase_models: dict[str, str],
+ error: str,
+) -> None:
+ """Mark JobStatus errored, record usage for any phases that already
+ landed, then clean up per-pass state.
+
+ We incurred the provider tokens for completed phases regardless of
+ whether the whole pass landed, so they're recorded against the
+ user's usage — matching the sync path and the documented contract in
+ ``dream/billing.py``. The idempotency gate inside
+ ``_log_all_phase_costs`` keeps this at-most-once even if the batch
+ re-dispatches.
+ """
+ logger.warning("Dream batch pass=%s failed: %s", pass_id, error)
+ if job_id:
+ try:
+ from .job_status import mark_errored
+
+ await mark_errored(kind="dream_pass", job_id=job_id, error=error)
+ except Exception:
+ logger.exception("Failed to mark dream pass job %s errored", job_id)
+ state = await _read_state(pass_id)
+ if state:
+ await _log_all_phase_costs(
+ user_id=user_id,
+ pass_id=pass_id,
+ state=state,
+ phase_models=phase_models,
+ )
+ # Release the dream lock the batch path disowned to this callback.
+ await _release_lock(user_id, pass_id)
+ await _best_effort_cleanup(pass_id)
+
+
+# ---------------------------------------------------------------------------
+# Cost logging
+# ---------------------------------------------------------------------------
+
+
+_COSTS_LOGGED_PREFIX = "dream:batch:costs_logged"
+# 7 days — long enough that no realistic BatchExecutor re-dispatch
+# (poll backoff caps at 5 min, max lifetime 24h) can slip through and
+# bill twice. Matches the spirit of the Stripe-reconcile gate's TTL.
+_COSTS_LOGGED_TTL_SECONDS = 7 * 24 * 60 * 60
+
+
+async def _claim_costs_logged_gate(pass_id: str) -> bool:
+ """Atomically claim the per-pass cost-charge gate. Returns True
+ when this caller won the race (first time costs_logged is set);
+ False when a prior caller already charged this pass.
+
+ Modelled on ``rate_limit._maybe_reconcile_stripe_tier`` — Redis
+ SETNX with a long TTL is the established convention for "do this
+ side-effect at most once per identifier" in this codebase. The
+ dedup lives at the dream-batch boundary, not inside
+ ``record_cost_usage`` itself (chat legitimately charges every turn).
+ """
+ from backend.data.redis_client import get_redis_async
+
+ try:
+ redis = await get_redis_async()
+ return bool(
+ await redis.set(
+ f"{_COSTS_LOGGED_PREFIX}:{pass_id}",
+ "1",
+ nx=True,
+ ex=_COSTS_LOGGED_TTL_SECONDS,
+ )
+ )
+ except Exception:
+ # Fail closed: if we can't claim the gate, do not charge.
+ # Better to under-bill on a Redis brown-out than risk
+ # double-billing under retry pressure.
+ logger.exception(
+ "Failed to claim costs_logged gate for pass=%s — skipping charge",
+ pass_id,
+ )
+ return False
+
+
+async def _log_all_phase_costs(
+ *,
+ user_id: str,
+ pass_id: str,
+ state: dict[str, dict[str, Any]],
+ phase_models: dict[str, str],
+) -> None:
+ """One PlatformCostLog row per phase, tagged ``anthropic_batch``.
+
+ Idempotent via a Redis SETNX gate keyed on ``pass_id``: if the
+ BatchExecutor crashes between charging and removing the pending
+ batch entry and the next poll re-dispatches the same batch, the
+ gate prevents the second charge. The gate is set BEFORE the loop
+ so a partial failure mid-loop still leaves the user charged for
+ whatever phases landed (matches the documented "partial pass
+ charges for completed phases" semantic in ``dream/billing.py``).
+
+ Cost is computed via ``dream/model_pricing.compute_cost_usd`` —
+ the dream rate card — so the batch path uses the same native-
+ Anthropic token convention (additive cache buckets, not subtracted)
+ as the sync path. The ``execution_path="anthropic_batch"`` arg
+ applies the 50% batch discount there.
+
+ No-ops on per-phase failure — apply already wrote the user-facing
+ memory operations; a cost-log blip shouldn't take that down.
+ """
+ if not await _claim_costs_logged_gate(pass_id):
+ logger.info(
+ "Skipping batch cost log for pass=%s — already charged",
+ pass_id,
+ )
+ return
+
+ for phase, row in state.items():
+ try:
+ if row.get("error"):
+ # Phase errored — don't record usage for a phase that
+ # didn't complete; downstream phases never ran either.
+ continue
+ phase_model = phase_models.get(phase)
+ if not phase_model:
+ logger.warning(
+ "No model recorded for pass=%s phase=%s — skipping cost log",
+ pass_id,
+ phase,
+ )
+ continue
+ input_tokens = int(row.get("input_tokens") or 0)
+ output_tokens = int(row.get("output_tokens") or 0)
+ cache_read_tokens = int(row.get("cache_read_tokens") or 0)
+ cache_creation_tokens = int(row.get("cache_creation_tokens") or 0)
+ cost_usd = compute_cost_usd(
+ model=phase_model,
+ input_tokens=input_tokens,
+ output_tokens=output_tokens,
+ cache_read_tokens=cache_read_tokens,
+ cache_creation_tokens=cache_creation_tokens,
+ execution_path="anthropic_batch",
+ )
+ usage = PhaseUsage(
+ phase=phase, # type: ignore[arg-type]
+ model=phase_model,
+ input_tokens=input_tokens,
+ output_tokens=output_tokens,
+ cache_read_tokens=cache_read_tokens,
+ cache_creation_tokens=cache_creation_tokens,
+ cost_usd=cost_usd,
+ )
+ await record_phase_cost(
+ user_id=user_id,
+ pass_id=pass_id,
+ phase_usage=usage,
+ execution_path="anthropic_batch",
+ )
+ except Exception:
+ logger.exception(
+ "Failed to log batch cost for pass=%s phase=%s", pass_id, phase
+ )
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _anthropic_api_key() -> str | None:
+ """Look up the Anthropic key from the copilot config first, then
+ fall back to the shared settings key.
+
+ Mirrors what ``backend/executor/batch_executor.py::_default_api_key_for``
+ does — callbacks live in their own subprocess so they need to
+ re-resolve the key on their own.
+ """
+ try:
+ from backend.copilot.config import ChatConfig
+
+ cfg = ChatConfig()
+ if cfg.direct_anthropic_api_key:
+ return cfg.direct_anthropic_api_key
+ except Exception:
+ logger.debug("ChatConfig unavailable during dream batch callback")
+ try:
+ from backend.util.settings import Settings
+
+ key = Settings().secrets.anthropic_api_key
+ return key or None
+ except Exception:
+ return None
+
+
+# ---------------------------------------------------------------------------
+# Registration (runs at module import)
+# ---------------------------------------------------------------------------
+
+
+def _register() -> None:
+ try:
+ from backend.executor.batch_executor import register_handler
+
+ register_handler(NAMESPACE, handle_dream_batch_result)
+ except Exception:
+ logger.exception(
+ "Failed to register dream batch handler — "
+ "batch results will not dispatch"
+ )
+
+
+_register()
diff --git a/autogpt_platform/backend/backend/copilot/dream/batch_callbacks_test.py b/autogpt_platform/backend/backend/copilot/dream/batch_callbacks_test.py
new file mode 100644
index 0000000000..8629b453a5
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/batch_callbacks_test.py
@@ -0,0 +1,906 @@
+"""Tests for the dream-pass batch result handler (sequential chain).
+
+Covers the namespace handler that the BatchExecutor invokes when a
+dream batch lands. Dream phases are sequentially dependent so the
+handler chains: phase 1 result → submit phase 2 → phase 2 result →
+submit phase 3 → phase 3 result → apply + mark JobStatus complete.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from backend.copilot.dream.batch_callbacks import handle_dream_batch_result
+from backend.executor.batch_executor import PendingEntry
+from backend.util.llm.providers import BatchResultRow
+
+
+def fake_redis():
+ """In-memory redis fixture matching the BatchExecutor / JobStatus pattern."""
+ store: dict[str, dict[str, str]] = {}
+ string_store: dict[str, str] = {}
+
+ async def fake_hset(key, field, value):
+ store.setdefault(key, {})[field] = value
+ return 1
+
+ async def fake_hgetall(key):
+ return store.get(key, {})
+
+ async def fake_get(key):
+ return string_store.get(key)
+
+ async def fake_set(key, value, ex=None, nx=False):
+ # Mirror redis.set semantics: when ``nx=True`` and the key
+ # already exists, set returns None and leaves the existing
+ # value alone. This is what makes the dedup gate idempotent.
+ if nx and key in string_store:
+ return None
+ string_store[key] = value
+ return True
+
+ async def fake_delete(key):
+ store.pop(key, None)
+ string_store.pop(key, None)
+
+ async def fake_expire(key, ttl):
+ return 1
+
+ async def fake_eval(script, numkeys, key, token):
+ # The only Lua the dream path runs is the lock's single-key
+ # compare-and-delete; mirror its semantics on the string store.
+ if string_store.get(key) == token:
+ string_store.pop(key, None)
+ return 1
+ return 0
+
+ stub = AsyncMock()
+ stub.hset.side_effect = fake_hset
+ stub.hgetall.side_effect = fake_hgetall
+ stub.get.side_effect = fake_get
+ stub.set.side_effect = fake_set
+ stub.expire.side_effect = fake_expire
+ stub.delete.side_effect = fake_delete
+ stub.eval.side_effect = fake_eval
+
+ async def fake_get_redis_async():
+ return stub
+
+ with patch(
+ "backend.data.redis_client.get_redis_async",
+ side_effect=fake_get_redis_async,
+ ):
+ yield stub, store, string_store
+
+
+def _entry(
+ *, pass_id: str = "p1", job_id: str = "j1", phase: str = "consolidate"
+) -> PendingEntry:
+ now = datetime.now(timezone.utc)
+ custom_id = f"{pass_id}:{phase}"
+ return PendingEntry(
+ provider="anthropic",
+ provider_batch_id=f"msgbatch_{phase}",
+ callback_namespace="dream_pass",
+ submitted_at=now,
+ next_poll_at=now,
+ payload={
+ "user_id": "u1",
+ "pass_id": pass_id,
+ "job_id": job_id,
+ "phase": phase,
+ "phase_models": {
+ "consolidate": "claude-sonnet-4-6",
+ "recombine": "claude-opus-4-7",
+ "sanitize": "claude-sonnet-4-6",
+ },
+ "custom_ids": [custom_id],
+ "phase_for_custom_id": {custom_id: phase},
+ },
+ )
+
+
+def _row(*, custom_id: str, content: str, error: str | None = None) -> BatchResultRow:
+ return BatchResultRow(
+ custom_id=custom_id,
+ content=content,
+ input_tokens=10,
+ output_tokens=20,
+ error=error,
+ )
+
+
+# Valid Pydantic content per phase
+_CONSOLIDATE_CONTENT = '{"facts": []}'
+_RECOMBINE_CONTENT = '{"proposals": []}'
+_SANITIZE_CONTENT = (
+ '{"writes": [], "proposals": [], "demotions": [], '
+ '"entity_invalidations": [], "summary_for_user": "ok"}'
+)
+
+
+class TestPhaseChaining:
+ @pytest.mark.asyncio
+ async def test_consolidate_result_submits_recombine_batch(self, fake_redis):
+ """Phase 1 result must trigger phase 2 submission, NOT apply."""
+ # Persist a fake input bundle the chain can read back.
+ from backend.copilot.dream.batch_submit import persist_input_bundle
+ from backend.copilot.dream.fetch import DreamInput
+
+ now = datetime.now(timezone.utc)
+ await persist_input_bundle(
+ "p1",
+ DreamInput(
+ user_id="u1",
+ group_id="user_u1",
+ window_start=now,
+ window_end=now,
+ ),
+ )
+
+ submit_phase = AsyncMock(
+ return_value=MagicMock(provider_batch_id="msgbatch_recombine")
+ )
+ update_status = AsyncMock()
+
+ with patch(
+ "backend.copilot.dream.batch_callbacks.submit_phase", submit_phase
+ ), patch(
+ "backend.copilot.dream.job_status.update_status_phase", update_status
+ ), patch(
+ "backend.copilot.dream.batch_callbacks._anthropic_api_key",
+ return_value="sk-ant-test",
+ ):
+ await handle_dream_batch_result(
+ _entry(phase="consolidate"),
+ [_row(custom_id="p1:consolidate", content=_CONSOLIDATE_CONTENT)],
+ )
+
+ submit_phase.assert_awaited_once()
+ kwargs = submit_phase.call_args.kwargs
+ assert kwargs["phase"] == "recombine"
+ # Phase 2 prompt builder needs phase 1's output
+ assert kwargs["consolidated_json"] == _CONSOLIDATE_CONTENT
+ # JobStatus advanced
+ update_status.assert_awaited_once()
+ update_kwargs = update_status.call_args.kwargs
+ assert update_kwargs["current_phase"] == "recombine"
+
+ @pytest.mark.asyncio
+ async def test_recombine_result_submits_sanitize_batch(self, fake_redis):
+ """Phase 2 result chains to phase 3 with BOTH prior phases' outputs."""
+ from backend.copilot.dream.batch_submit import persist_input_bundle
+ from backend.copilot.dream.fetch import DreamInput
+
+ now = datetime.now(timezone.utc)
+ await persist_input_bundle(
+ "p1",
+ DreamInput(
+ user_id="u1", group_id="user_u1", window_start=now, window_end=now
+ ),
+ )
+
+ # Pre-seed phase 1's output in the per-pass state
+ from backend.copilot.dream.batch_callbacks import _write_phase_to_state
+
+ await _write_phase_to_state(
+ pass_id="p1",
+ phase="consolidate",
+ row=_row(custom_id="p1:consolidate", content=_CONSOLIDATE_CONTENT),
+ )
+
+ submit_phase = AsyncMock(
+ return_value=MagicMock(provider_batch_id="msgbatch_sanitize")
+ )
+ with patch(
+ "backend.copilot.dream.batch_callbacks.submit_phase", submit_phase
+ ), patch(
+ "backend.copilot.dream.batch_callbacks._anthropic_api_key",
+ return_value="sk-ant-test",
+ ), patch(
+ "backend.copilot.dream.job_status.update_status_phase", AsyncMock()
+ ):
+ await handle_dream_batch_result(
+ _entry(phase="recombine"),
+ [_row(custom_id="p1:recombine", content=_RECOMBINE_CONTENT)],
+ )
+
+ kwargs = submit_phase.call_args.kwargs
+ assert kwargs["phase"] == "sanitize"
+ assert kwargs["consolidated_json"] == _CONSOLIDATE_CONTENT
+ assert kwargs["recombined_json"] == _RECOMBINE_CONTENT
+
+ @pytest.mark.asyncio
+ async def test_sanitize_result_runs_apply_marks_complete_logs_costs(
+ self, fake_redis
+ ):
+ """Phase 3 is terminal: apply runs, all three phases logged at
+ anthropic_batch path (50% discount in the rate card), JobStatus
+ flips to complete."""
+ from backend.copilot.dream.batch_callbacks import _write_phase_to_state
+ from backend.copilot.dream.batch_submit import persist_input_bundle
+ from backend.copilot.dream.fetch import DreamInput
+
+ _, _, string_store = fake_redis
+ # The orchestrator holds the dream lock while persisting the bundle;
+ # the bundle captures the lock's ownership token for the callback.
+ string_store["dream:inflight:u1"] = "tok-u1"
+ now = datetime.now(timezone.utc)
+ await persist_input_bundle(
+ "p1",
+ DreamInput(
+ user_id="u1",
+ group_id="user_u1",
+ window_start=now,
+ window_end=now,
+ known_fact_uuids={"fact-1"},
+ ),
+ )
+ await _write_phase_to_state(
+ pass_id="p1",
+ phase="consolidate",
+ row=_row(custom_id="p1:consolidate", content=_CONSOLIDATE_CONTENT),
+ )
+ await _write_phase_to_state(
+ pass_id="p1",
+ phase="recombine",
+ row=_row(custom_id="p1:recombine", content=_RECOMBINE_CONTENT),
+ )
+
+ apply = AsyncMock(return_value={"writes": 0, "snapshot": "..."})
+ mark_complete = AsyncMock()
+ record_cost = AsyncMock()
+ release_lock = AsyncMock()
+ with patch("backend.copilot.dream.apply.apply_operations", apply), patch(
+ "backend.copilot.dream.job_status.mark_complete", mark_complete
+ ), patch(
+ "backend.copilot.dream.batch_callbacks.record_phase_cost", record_cost
+ ), patch(
+ "backend.copilot.dream.batch_callbacks.release_dream_lock", release_lock
+ ):
+ await handle_dream_batch_result(
+ _entry(phase="sanitize"),
+ [_row(custom_id="p1:sanitize", content=_SANITIZE_CONTENT)],
+ )
+
+ apply.assert_awaited_once()
+ # The demotion allowlist is threaded from the bundle already loaded
+ # for the clamp — apply must not re-read the bundle from Redis.
+ assert apply.call_args.kwargs["known_fact_uuids"] == {"fact-1"}
+ mark_complete.assert_awaited_once()
+ # The sanitizer's user-facing narrative must ride on the result so the
+ # Memory Visualizer isn't blank for batch-completed dreams.
+ assert mark_complete.call_args.kwargs["result"].summary_for_user == "ok"
+ # The batch path disowned the dream lock to this callback; the
+ # terminal handler must release it with the ownership token the
+ # input bundle carried — compare-and-delete, never a blind DEL.
+ release_lock.assert_awaited_once_with("u1", "tok-u1")
+ # One cost-log row per phase (consolidate, recombine, sanitize)
+ assert record_cost.await_count == 3
+ for call in record_cost.await_args_list:
+ assert call.kwargs["execution_path"] == "anthropic_batch"
+ # Each phase is priced with ITS OWN model — recombine uses the
+ # advanced (opus) model, not phase 1's standard model.
+ models_by_phase = {
+ call.kwargs["phase_usage"].phase: call.kwargs["phase_usage"].model
+ for call in record_cost.await_args_list
+ }
+ assert models_by_phase["consolidate"] == "claude-sonnet-4-6"
+ assert models_by_phase["recombine"] == "claude-opus-4-7"
+ assert models_by_phase["sanitize"] == "claude-sonnet-4-6"
+
+ @pytest.mark.asyncio
+ async def test_redispatch_after_charge_does_not_double_bill(self, fake_redis):
+ """If the BatchExecutor crashes between charging and
+ ``remove_pending``, the next walk re-dispatches the same batch.
+ The Redis dedup gates must prevent BOTH the second charge and a
+ second ``apply_operations`` run."""
+ from backend.copilot.dream.batch_callbacks import _write_phase_to_state
+ from backend.copilot.dream.batch_submit import persist_input_bundle
+ from backend.copilot.dream.fetch import DreamInput
+
+ now = datetime.now(timezone.utc)
+ await persist_input_bundle(
+ "p1",
+ DreamInput(
+ user_id="u1", group_id="user_u1", window_start=now, window_end=now
+ ),
+ )
+ await _write_phase_to_state(
+ pass_id="p1",
+ phase="consolidate",
+ row=_row(custom_id="p1:consolidate", content=_CONSOLIDATE_CONTENT),
+ )
+ await _write_phase_to_state(
+ pass_id="p1",
+ phase="recombine",
+ row=_row(custom_id="p1:recombine", content=_RECOMBINE_CONTENT),
+ )
+
+ apply = AsyncMock(return_value={"writes": 0, "snapshot": "..."})
+ record_cost = AsyncMock()
+ with patch("backend.copilot.dream.apply.apply_operations", apply), patch(
+ "backend.copilot.dream.job_status.mark_complete", AsyncMock()
+ ), patch(
+ "backend.copilot.dream.batch_callbacks.record_phase_cost", record_cost
+ ):
+ await handle_dream_batch_result(
+ _entry(phase="sanitize"),
+ [_row(custom_id="p1:sanitize", content=_SANITIZE_CONTENT)],
+ )
+ # Simulated re-dispatch: BatchExecutor crashed between
+ # charge + remove_pending, walks the queue again, calls us
+ # a second time with the same batch result.
+ await handle_dream_batch_result(
+ _entry(phase="sanitize"),
+ [_row(custom_id="p1:sanitize", content=_SANITIZE_CONTENT)],
+ )
+
+ # 3 phases charged on the first call, ZERO on the re-dispatch.
+ assert record_cost.await_count == 3
+ # And the memory writes ran exactly once — the apply gate ate the
+ # duplicate delivery.
+ apply.assert_awaited_once()
+
+ @pytest.mark.asyncio
+ async def test_duplicate_batch_dispatch_skips_apply(self, fake_redis):
+ """Executor crash between ``apply_operations`` returning and the
+ state cleanup re-dispatches the sanitize batch with all per-pass
+ state intact. The ``dream:applied:{pass_id}`` SETNX gate must keep
+ apply at-most-once — otherwise every consolidated fact and proposal
+ is written to the user's graph a second time as fresh episodes —
+ while the duplicate skips mark_complete (preserving the first
+ delivery's job result) and still releases the lock + cleans up
+ state."""
+ from backend.copilot.dream.batch_callbacks import _write_phase_to_state
+ from backend.copilot.dream.batch_submit import persist_input_bundle
+ from backend.copilot.dream.fetch import DreamInput
+
+ _, _, string_store = fake_redis
+ string_store["dream:inflight:u1"] = "tok-u1"
+ now = datetime.now(timezone.utc)
+ await persist_input_bundle(
+ "p1",
+ DreamInput(
+ user_id="u1", group_id="user_u1", window_start=now, window_end=now
+ ),
+ )
+ await _write_phase_to_state(
+ pass_id="p1",
+ phase="consolidate",
+ row=_row(custom_id="p1:consolidate", content=_CONSOLIDATE_CONTENT),
+ )
+ await _write_phase_to_state(
+ pass_id="p1",
+ phase="recombine",
+ row=_row(custom_id="p1:recombine", content=_RECOMBINE_CONTENT),
+ )
+
+ apply = AsyncMock(return_value={"writes": 0, "snapshot": "..."})
+ mark_complete = AsyncMock()
+ release_lock = AsyncMock()
+ # Crash-before-cleanup simulation: state + input bundle survive the
+ # first delivery, so the re-dispatch sees a fully populated pass.
+ with patch("backend.copilot.dream.apply.apply_operations", apply), patch(
+ "backend.copilot.dream.job_status.mark_complete", mark_complete
+ ), patch(
+ "backend.copilot.dream.batch_callbacks.record_phase_cost", AsyncMock()
+ ), patch(
+ "backend.copilot.dream.batch_callbacks.release_dream_lock", release_lock
+ ), patch(
+ "backend.copilot.dream.batch_callbacks._delete_state", AsyncMock()
+ ), patch(
+ "backend.copilot.dream.batch_callbacks.delete_input_bundle", AsyncMock()
+ ):
+ await handle_dream_batch_result(
+ _entry(phase="sanitize"),
+ [_row(custom_id="p1:sanitize", content=_SANITIZE_CONTENT)],
+ )
+ # Re-dispatch of the same finished batch.
+ await handle_dream_batch_result(
+ _entry(phase="sanitize"),
+ [_row(custom_id="p1:sanitize", content=_SANITIZE_CONTENT)],
+ )
+
+ apply.assert_awaited_once()
+ # The gate key is what makes the dedup stick across processes.
+ assert "dream:applied:p1" in string_store
+ # Only the first delivery writes the job result — the duplicate
+ # must NOT call mark_complete with empty apply_stats, or it would
+ # zero the real consolidated/proposal/demotion counts and
+ # dream_session_id the first delivery recorded.
+ mark_complete.assert_awaited_once()
+ assert mark_complete.call_args.kwargs["result"].summary_for_user == "ok"
+ # Both deliveries release the lock (token CAS makes the second a
+ # safe no-op) and clean up state.
+ assert release_lock.await_count == 2
+ for call in release_lock.await_args_list:
+ assert call.args == ("u1", "tok-u1")
+
+ @pytest.mark.asyncio
+ async def test_apply_gate_redis_outage_fails_pass_not_silent_success(
+ self, fake_redis
+ ):
+ """A Redis outage while claiming the apply gate means we cannot
+ distinguish first delivery from duplicate. The pass must be marked
+ errored — completing it would report success while no memory was
+ written, silently dropping the dream."""
+ from backend.copilot.dream.batch_callbacks import _write_phase_to_state
+
+ await _write_phase_to_state(
+ pass_id="p1",
+ phase="consolidate",
+ row=_row(custom_id="p1:consolidate", content=_CONSOLIDATE_CONTENT),
+ )
+ await _write_phase_to_state(
+ pass_id="p1",
+ phase="recombine",
+ row=_row(custom_id="p1:recombine", content=_RECOMBINE_CONTENT),
+ )
+
+ apply = AsyncMock()
+ mark_complete = AsyncMock()
+ mark_errored = AsyncMock()
+ gate = AsyncMock(return_value="error")
+ with patch("backend.copilot.dream.apply.apply_operations", apply), patch(
+ "backend.copilot.dream.job_status.mark_complete", mark_complete
+ ), patch("backend.copilot.dream.job_status.mark_errored", mark_errored), patch(
+ "backend.copilot.dream.batch_callbacks._claim_apply_gate", gate
+ ), patch(
+ "backend.copilot.dream.batch_callbacks.record_phase_cost", AsyncMock()
+ ):
+ await handle_dream_batch_result(
+ _entry(phase="sanitize"),
+ [_row(custom_id="p1:sanitize", content=_SANITIZE_CONTENT)],
+ )
+
+ apply.assert_not_awaited()
+ mark_complete.assert_not_awaited()
+ mark_errored.assert_awaited_once()
+ assert "gate unavailable" in mark_errored.call_args.kwargs["error"]
+
+
+class TestErrorPaths:
+ @pytest.mark.asyncio
+ async def test_malformed_payload_marks_job_errored_not_stuck(self, fake_redis):
+ """A payload missing pass_id/phase is a dead end the normal fail
+ path can't reach — the admin row must still go terminal instead of
+ sitting queued/submitted until its TTL."""
+ from backend.copilot.dream.job_status import read_status, write_initial_status
+
+ await write_initial_status(kind="dream_pass", job_id="j-dead", user_id="u1")
+ entry = _entry(phase="consolidate")
+ entry.payload = {"user_id": "u1", "job_id": "j-dead"}
+
+ with patch(
+ "backend.copilot.dream.batch_callbacks.release_dream_lock", AsyncMock()
+ ):
+ await handle_dream_batch_result(entry, [])
+
+ final = await read_status(kind="dream_pass", job_id="j-dead")
+ assert final is not None
+ assert final.state == "errored"
+ assert "missing" in (final.error or "")
+
+ @pytest.mark.asyncio
+ async def test_unknown_phase_marks_job_errored_not_stuck(self, fake_redis):
+ from backend.copilot.dream.job_status import read_status, write_initial_status
+
+ await write_initial_status(kind="dream_pass", job_id="j-odd", user_id="u1")
+ entry = _entry(phase="consolidate")
+ entry.payload = {
+ "user_id": "u1",
+ "pass_id": "p1",
+ "job_id": "j-odd",
+ "phase": "daydream",
+ }
+
+ with patch(
+ "backend.copilot.dream.batch_callbacks.release_dream_lock", AsyncMock()
+ ):
+ await handle_dream_batch_result(entry, [])
+
+ final = await read_status(kind="dream_pass", job_id="j-odd")
+ assert final is not None
+ assert final.state == "errored"
+ assert "unknown batch phase" in (final.error or "")
+
+ @pytest.mark.asyncio
+ async def test_errored_row_short_circuits_to_mark_errored(self, fake_redis):
+ mark_errored = AsyncMock()
+ record_cost = AsyncMock()
+ with patch(
+ "backend.copilot.dream.job_status.mark_errored", mark_errored
+ ), patch(
+ "backend.copilot.dream.batch_callbacks.record_phase_cost", record_cost
+ ):
+ await handle_dream_batch_result(
+ _entry(phase="consolidate"),
+ [
+ _row(
+ custom_id="p1:consolidate",
+ content="",
+ error="content moderation",
+ )
+ ],
+ )
+ mark_errored.assert_awaited_once()
+ assert "content moderation" in mark_errored.call_args.kwargs["error"]
+ # The errored phase itself is not billed.
+ record_cost.assert_not_awaited()
+
+ @pytest.mark.asyncio
+ async def test_invalid_json_marks_errored_does_not_chain(self, fake_redis):
+ """A row whose content is not parseable JSON must NOT chain to
+ the next phase — the next phase's prompt would be built on
+ garbage. Pydantic's default ``model_validate`` is permissive
+ about unknown fields (extra="ignore"), so the failure mode the
+ test pins is invalid-JSON not unknown-field."""
+ submit_phase = AsyncMock()
+ mark_errored = AsyncMock()
+ record_cost = AsyncMock()
+ with patch(
+ "backend.copilot.dream.batch_callbacks.submit_phase", submit_phase
+ ), patch("backend.copilot.dream.job_status.mark_errored", mark_errored), patch(
+ "backend.copilot.dream.batch_callbacks.record_phase_cost", record_cost
+ ):
+ await handle_dream_batch_result(
+ _entry(phase="consolidate"),
+ [
+ _row(
+ custom_id="p1:consolidate",
+ content="this is not JSON at all",
+ )
+ ],
+ )
+ submit_phase.assert_not_awaited()
+ mark_errored.assert_awaited_once()
+ assert "invalid output shape" in mark_errored.call_args.kwargs["error"]
+
+ @pytest.mark.asyncio
+ async def test_apply_crash_marks_errored_still_records_usage(self, fake_redis):
+ """If apply raises, the pass is errored — but the three LLM phases
+ already ran and Anthropic billed us, so their usage is still
+ recorded (matches the sync path + dream/billing.py)."""
+ from backend.copilot.dream.batch_callbacks import _write_phase_to_state
+ from backend.copilot.dream.batch_submit import persist_input_bundle
+ from backend.copilot.dream.fetch import DreamInput
+
+ now = datetime.now(timezone.utc)
+ await persist_input_bundle(
+ "p1",
+ DreamInput(
+ user_id="u1", group_id="user_u1", window_start=now, window_end=now
+ ),
+ )
+ await _write_phase_to_state(
+ pass_id="p1",
+ phase="consolidate",
+ row=_row(custom_id="p1:consolidate", content=_CONSOLIDATE_CONTENT),
+ )
+ await _write_phase_to_state(
+ pass_id="p1",
+ phase="recombine",
+ row=_row(custom_id="p1:recombine", content=_RECOMBINE_CONTENT),
+ )
+
+ apply = AsyncMock(side_effect=RuntimeError("FalkorDB unreachable"))
+ mark_errored = AsyncMock()
+ record_cost = AsyncMock()
+ with patch("backend.copilot.dream.apply.apply_operations", apply), patch(
+ "backend.copilot.dream.job_status.mark_errored", mark_errored
+ ), patch(
+ "backend.copilot.dream.batch_callbacks.record_phase_cost", record_cost
+ ):
+ await handle_dream_batch_result(
+ _entry(phase="sanitize"),
+ [_row(custom_id="p1:sanitize", content=_SANITIZE_CONTENT)],
+ )
+
+ mark_errored.assert_awaited_once()
+ # consolidate + recombine + sanitize all completed and were billed
+ # by Anthropic; apply failing afterward doesn't refund those tokens.
+ assert record_cost.await_count == 3
+
+ @pytest.mark.asyncio
+ async def test_unexpected_crash_releases_disowned_lock(self, fake_redis):
+ """An unexpected raise OUTSIDE the handler's own _fail_pass guards
+ (here phase-chaining blows up) must still release the disowned dream
+ lock and mark the job errored. BatchExecutor._dispatch swallows
+ handler exceptions, so without the crash guard this would strand the
+ user behind the lock until its extended TTL."""
+ from backend.copilot.dream.batch_submit import persist_input_bundle
+ from backend.copilot.dream.fetch import DreamInput
+
+ _, _, string_store = fake_redis
+ string_store["dream:inflight:u1"] = "tok-u1"
+ now = datetime.now(timezone.utc)
+ await persist_input_bundle(
+ "p1",
+ DreamInput(
+ user_id="u1", group_id="user_u1", window_start=now, window_end=now
+ ),
+ )
+
+ chain = AsyncMock(side_effect=RuntimeError("redis exploded mid-chain"))
+ mark_errored = AsyncMock()
+ record_cost = AsyncMock()
+ release_lock = AsyncMock()
+ with patch(
+ "backend.copilot.dream.batch_callbacks._chain_next_phase", chain
+ ), patch("backend.copilot.dream.job_status.mark_errored", mark_errored), patch(
+ "backend.copilot.dream.batch_callbacks.record_phase_cost", record_cost
+ ), patch(
+ "backend.copilot.dream.batch_callbacks.release_dream_lock", release_lock
+ ):
+ # Must not propagate — the crash guard finalizes and swallows.
+ await handle_dream_batch_result(
+ _entry(phase="consolidate"),
+ [_row(custom_id="p1:consolidate", content=_CONSOLIDATE_CONTENT)],
+ )
+
+ mark_errored.assert_awaited_once()
+ assert "handler crashed" in mark_errored.call_args.kwargs["error"]
+ # Released with the ownership token the input bundle carried.
+ release_lock.assert_awaited_once_with("u1", "tok-u1")
+
+
+class TestMalformedPayload:
+ @pytest.mark.asyncio
+ async def test_missing_pass_id_releases_lock_without_token(self, fake_redis):
+ """Malformed payload (missing pass_id) early-returns but, since the
+ user_id is known, still attempts the lock release — with no pass_id
+ there's no persisted token to read, so the release is token-less
+ (release_dream_lock then defers to the lock TTL rather than
+ blind-deleting)."""
+ release = AsyncMock()
+ entry = _entry()
+ entry.payload["pass_id"] = ""
+ with patch("backend.copilot.dream.batch_callbacks.release_dream_lock", release):
+ await handle_dream_batch_result(
+ entry,
+ [_row(custom_id="p1:consolidate", content=_CONSOLIDATE_CONTENT)],
+ )
+ release.assert_awaited_once_with("u1", None)
+
+ @pytest.mark.asyncio
+ async def test_unknown_phase_label_releases_lock_with_persisted_token(
+ self, fake_redis
+ ):
+ """An unknown phase early-returns but must still release the dream
+ lock the orchestrator disowned to this callback — using the token
+ the input bundle carries for this pass."""
+ from backend.copilot.dream.batch_submit import persist_input_bundle
+ from backend.copilot.dream.fetch import DreamInput
+
+ _, _, string_store = fake_redis
+ string_store["dream:inflight:u1"] = "tok-u1"
+ now = datetime.now(timezone.utc)
+ await persist_input_bundle(
+ "p1",
+ DreamInput(
+ user_id="u1", group_id="user_u1", window_start=now, window_end=now
+ ),
+ )
+
+ release = AsyncMock()
+ entry = _entry()
+ entry.payload["phase"] = "some_fake_phase"
+ with patch("backend.copilot.dream.batch_callbacks.release_dream_lock", release):
+ await handle_dream_batch_result(entry, [_row(custom_id="x", content="y")])
+ release.assert_awaited_once_with("u1", "tok-u1")
+
+
+class TestLockTokenWiring:
+ """End-to-end token flow with the real ``release_dream_lock`` — the
+ fake redis implements the single-key compare-and-delete Lua."""
+
+ async def _seed_terminal_pass(self) -> None:
+ from backend.copilot.dream.batch_callbacks import _write_phase_to_state
+ from backend.copilot.dream.batch_submit import persist_input_bundle
+ from backend.copilot.dream.fetch import DreamInput
+
+ now = datetime.now(timezone.utc)
+ await persist_input_bundle(
+ "p1",
+ DreamInput(
+ user_id="u1", group_id="user_u1", window_start=now, window_end=now
+ ),
+ )
+ await _write_phase_to_state(
+ pass_id="p1",
+ phase="consolidate",
+ row=_row(custom_id="p1:consolidate", content=_CONSOLIDATE_CONTENT),
+ )
+ await _write_phase_to_state(
+ pass_id="p1",
+ phase="recombine",
+ row=_row(custom_id="p1:recombine", content=_RECOMBINE_CONTENT),
+ )
+
+ async def _dispatch_sanitize(self) -> None:
+ with patch(
+ "backend.copilot.dream.apply.apply_operations",
+ AsyncMock(return_value={"writes": 0}),
+ ), patch("backend.copilot.dream.job_status.mark_complete", AsyncMock()), patch(
+ "backend.copilot.dream.batch_callbacks.record_phase_cost", AsyncMock()
+ ):
+ await handle_dream_batch_result(
+ _entry(phase="sanitize"),
+ [_row(custom_id="p1:sanitize", content=_SANITIZE_CONTENT)],
+ )
+
+ @pytest.mark.asyncio
+ async def test_terminal_release_deletes_lock_when_token_matches(self, fake_redis):
+ _, _, string_store = fake_redis
+ string_store["dream:inflight:u1"] = "tok-u1"
+ await self._seed_terminal_pass()
+
+ await self._dispatch_sanitize()
+
+ assert "dream:inflight:u1" not in string_store
+
+ @pytest.mark.asyncio
+ async def test_token_read_failure_after_complete_keeps_job_completed(
+ self, fake_redis
+ ):
+ """A Redis blip on the lock-token read in the terminal tail fires
+ AFTER mark_complete already ran. The read must stay best-effort
+ (token=None → lock TTL fallback) — letting it propagate would hit
+ the handler's crash guard, whose _fail_pass rewrites the
+ already-completed job to errored."""
+ _, _, string_store = fake_redis
+ string_store["dream:inflight:u1"] = "tok-u1"
+ await self._seed_terminal_pass()
+
+ mark_complete = AsyncMock()
+ mark_errored = AsyncMock()
+ release_lock = AsyncMock()
+ read_token = AsyncMock(side_effect=ConnectionError("redis blip"))
+ with patch(
+ "backend.copilot.dream.apply.apply_operations",
+ AsyncMock(return_value={"writes": 0}),
+ ), patch(
+ "backend.copilot.dream.job_status.mark_complete", mark_complete
+ ), patch(
+ "backend.copilot.dream.job_status.mark_errored", mark_errored
+ ), patch(
+ "backend.copilot.dream.batch_callbacks.record_phase_cost", AsyncMock()
+ ), patch(
+ "backend.copilot.dream.batch_callbacks.read_lock_token", read_token
+ ), patch(
+ "backend.copilot.dream.batch_callbacks.release_dream_lock", release_lock
+ ):
+ await handle_dream_batch_result(
+ _entry(phase="sanitize"),
+ [_row(custom_id="p1:sanitize", content=_SANITIZE_CONTENT)],
+ )
+
+ mark_complete.assert_awaited_once()
+ mark_errored.assert_not_awaited()
+ # Token read failed → token-less release; release_dream_lock then
+ # defers to the lock TTL rather than blind-deleting.
+ release_lock.assert_awaited_once_with("u1", None)
+
+ @pytest.mark.asyncio
+ async def test_cleanup_failure_after_complete_keeps_job_completed(self, fake_redis):
+ """A Redis blip on the post-mark_complete state/bundle deletes must
+ not route through the crash guard to _fail_pass — both keys carry
+ 24h TTLs, so cleanup is best-effort and the completed job stays
+ completed."""
+ await self._seed_terminal_pass()
+
+ mark_complete = AsyncMock()
+ mark_errored = AsyncMock()
+ delete_state = AsyncMock(side_effect=ConnectionError("redis blip"))
+ with patch(
+ "backend.copilot.dream.apply.apply_operations",
+ AsyncMock(return_value={"writes": 0}),
+ ), patch(
+ "backend.copilot.dream.job_status.mark_complete", mark_complete
+ ), patch(
+ "backend.copilot.dream.job_status.mark_errored", mark_errored
+ ), patch(
+ "backend.copilot.dream.batch_callbacks.record_phase_cost", AsyncMock()
+ ), patch(
+ "backend.copilot.dream.batch_callbacks._delete_state", delete_state
+ ), patch(
+ "backend.copilot.dream.batch_callbacks.release_dream_lock", AsyncMock()
+ ):
+ await handle_dream_batch_result(
+ _entry(phase="sanitize"),
+ [_row(custom_id="p1:sanitize", content=_SANITIZE_CONTENT)],
+ )
+
+ delete_state.assert_awaited_once()
+ mark_complete.assert_awaited_once()
+ mark_errored.assert_not_awaited()
+
+ @pytest.mark.asyncio
+ async def test_duplicate_dispatch_finalizes_job_stuck_before_mark_complete(
+ self, fake_redis
+ ):
+ """First delivery crashed between apply and mark_complete: the gate
+ is claimed but the job row never went terminal. The duplicate must
+ finalize the row (with the clamped op counts) instead of leaving it
+ stuck in 'submitted' until the row TTL."""
+ from backend.copilot.dream.job_status import (
+ read_status,
+ update_status_phase,
+ write_initial_status,
+ )
+
+ _, _, string_store = fake_redis
+ await self._seed_terminal_pass()
+ # Gate already claimed by the crashed first delivery.
+ string_store["dream:applied:p1"] = "1"
+ await write_initial_status(kind="dream_pass", job_id="j1", user_id="u1")
+ await update_status_phase(kind="dream_pass", job_id="j1", state="submitted")
+
+ apply = AsyncMock()
+ with patch("backend.copilot.dream.apply.apply_operations", apply), patch(
+ "backend.copilot.dream.batch_callbacks.record_phase_cost", AsyncMock()
+ ), patch(
+ "backend.copilot.dream.batch_callbacks.release_dream_lock", AsyncMock()
+ ):
+ await handle_dream_batch_result(
+ _entry(phase="sanitize"),
+ [_row(custom_id="p1:sanitize", content=_SANITIZE_CONTENT)],
+ )
+
+ apply.assert_not_awaited()
+ final = await read_status(kind="dream_pass", job_id="j1")
+ assert final is not None
+ assert final.state == "complete"
+ assert final.result is not None
+ # Counts are attempted ops, not confirmed apply results — the
+ # summary must say so.
+ assert final.result["summary_for_user"].endswith("ok")
+ assert "duplicate delivery" in final.result["summary_for_user"]
+
+ @pytest.mark.asyncio
+ async def test_duplicate_dispatch_leaves_terminal_job_untouched(self, fake_redis):
+ """A duplicate against an already-completed row must not rewrite it
+ — the first delivery's real apply stats stay authoritative."""
+ _, _, string_store = fake_redis
+ await self._seed_terminal_pass()
+ string_store["dream:applied:p1"] = "1"
+
+ mark_complete = AsyncMock()
+ read_existing = AsyncMock(return_value=MagicMock(state="complete"))
+ with patch("backend.copilot.dream.apply.apply_operations", AsyncMock()), patch(
+ "backend.copilot.dream.job_status.mark_complete", mark_complete
+ ), patch("backend.copilot.dream.job_status.read_status", read_existing), patch(
+ "backend.copilot.dream.batch_callbacks.record_phase_cost", AsyncMock()
+ ), patch(
+ "backend.copilot.dream.batch_callbacks.release_dream_lock", AsyncMock()
+ ):
+ await handle_dream_batch_result(
+ _entry(phase="sanitize"),
+ [_row(custom_id="p1:sanitize", content=_SANITIZE_CONTENT)],
+ )
+
+ mark_complete.assert_not_awaited()
+
+ @pytest.mark.asyncio
+ async def test_terminal_release_leaves_lock_reacquired_by_newer_pass(
+ self, fake_redis
+ ):
+ """The blocker scenario: this pass's lock expired mid-batch and a
+ NEWER pass re-acquired the key with its own token. The late callback
+ must not delete the new holder's lock — that would let a third
+ concurrent pass start."""
+ _, _, string_store = fake_redis
+ string_store["dream:inflight:u1"] = "tok-u1"
+ await self._seed_terminal_pass()
+ # Simulate expiry + re-acquire by a newer pass between submit and
+ # the (late) terminal callback.
+ string_store["dream:inflight:u1"] = "tok-newer-pass"
+
+ await self._dispatch_sanitize()
+
+ assert string_store["dream:inflight:u1"] == "tok-newer-pass"
diff --git a/autogpt_platform/backend/backend/copilot/dream/batch_submit.py b/autogpt_platform/backend/backend/copilot/dream/batch_submit.py
new file mode 100644
index 0000000000..57458af60c
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/batch_submit.py
@@ -0,0 +1,462 @@
+"""Submit one dream phase to Anthropic batch + enqueue with BatchExecutor.
+
+Both the orchestrator (kicking off phase 1) and the dream
+``batch_callbacks`` (chaining phases 2 → 3 as results arrive) need to
+submit identically: build the per-phase prompt with whatever upstream
+phase outputs we have, force tool_use structured output against the
+phase's Pydantic schema, then enqueue the submission so the
+BatchExecutor polls it. This module owns that flow.
+
+Splitting it out:
+ * Keeps the orchestrator focused on routing / cost accounting and
+ not duplicating Anthropic message-shape construction.
+ * Keeps the callback module focused on lifecycle (which phase
+ landed, what's next, mark complete vs errored) rather than
+ SDK plumbing.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Literal
+
+from pydantic import BaseModel
+
+from backend.executor.batch_executor import (
+ INITIAL_POLL_DELAY_SECONDS,
+ PendingEntry,
+ enqueue_pending,
+)
+from backend.util.llm.providers import (
+ BatchSubmissionRef,
+ ProviderResponse,
+ call_provider,
+ cancel_batch,
+)
+from backend.util.llm.tool_use import force_tool_choice, pydantic_to_anthropic_tool
+
+from .fetch import DreamInput
+from .locks import read_dream_lock_token
+from .prompts import (
+ build_consolidate_prompt,
+ build_recombine_prompt,
+ build_sanitize_prompt,
+)
+from .schemas import ConsolidationOutput, DreamOperations, RecombinationOutput
+
+if TYPE_CHECKING:
+ from backend.copilot.config import ChatConfig
+
+logger = logging.getLogger(__name__)
+
+DreamPhase = Literal["consolidate", "recombine", "sanitize"]
+
+
+# Tool name the model must emit for each phase. Forced ``tool_choice``
+# constrains output to exactly one tool_use block whose ``input`` matches
+# the corresponding Pydantic schema — no JSON-parse-prose failures.
+PHASE_TOOL_NAMES: dict[DreamPhase, str] = {
+ "consolidate": "emit_consolidation",
+ "recombine": "emit_recombination",
+ "sanitize": "emit_dream_operations",
+}
+
+
+PHASE_RESPONSE_MODELS: dict[DreamPhase, type[BaseModel]] = {
+ "consolidate": ConsolidationOutput,
+ "recombine": RecombinationOutput,
+ "sanitize": DreamOperations,
+}
+
+
+# Max output tokens per phase (mirrors the sync orchestrator's values).
+PHASE_MAX_TOKENS: dict[DreamPhase, int] = {
+ "consolidate": 4096,
+ "recombine": 16384,
+ "sanitize": 16384,
+}
+
+
+PHASE_TEMPERATURES: dict[DreamPhase, float] = {
+ "consolidate": 0.2,
+ "recombine": 0.9,
+ "sanitize": 0.0,
+}
+
+
+PHASE_DESCRIPTIONS: dict[DreamPhase, str] = {
+ "consolidate": (
+ "Emit the consolidated facts produced from the user's recent "
+ "episodes + active facts."
+ ),
+ "recombine": (
+ "Emit novel recombination proposals drawn from the " "consolidated facts."
+ ),
+ "sanitize": (
+ "Emit the gated final dream operations (writes / proposals / "
+ "demotions / entity invalidations / summary_for_user)."
+ ),
+}
+
+
+def _to_native_anthropic_model(model: str) -> str:
+ """``anthropic/claude-opus-4.7`` → ``claude-opus-4-7``.
+
+ The batch path always submits to Anthropic's native Batches API
+ (direct key), regardless of the chat transport, so strip the
+ OpenRouter vendor prefix AND convert dots to hyphens — native
+ Anthropic rejects both the prefix and the dot-separated version,
+ and the dream rate card only carries the hyphenated id.
+ """
+ if "/" in model:
+ model = model.split("/", 1)[1]
+ return model.replace(".", "-")
+
+
+def phase_models_for_config(config: "ChatConfig") -> dict[str, str]:
+ """Per-phase model map (native-Anthropic form) for the batch path.
+
+ Mirrors the sync orchestrator's per-phase choice: the standard tier
+ for consolidate/sanitize, the advanced tier (opus + extended
+ thinking) for recombine. Built once at submit and threaded through
+ the batch payload so the model used to *submit* a phase is the exact
+ model used to *price* it — no single-model fan-out across phases.
+ """
+ return {
+ "consolidate": _to_native_anthropic_model(config.fast_standard_model),
+ "recombine": _to_native_anthropic_model(config.fast_advanced_model),
+ "sanitize": _to_native_anthropic_model(config.fast_standard_model),
+ }
+
+
+async def submit_phase(
+ *,
+ user_id: str,
+ pass_id: str,
+ job_id: str,
+ phase: DreamPhase,
+ phase_models: dict[str, str],
+ api_key: str,
+ input_bundle: DreamInput,
+ consolidated_json: str | None = None,
+ recombined_json: str | None = None,
+) -> BatchSubmissionRef:
+ """Submit one dream phase as a single-request Anthropic batch.
+
+ The custom_id encodes ``{pass_id}:{phase}`` so the BatchExecutor's
+ dispatch + dream callbacks can correlate the result back. Returns
+ the ``BatchSubmissionRef`` so the caller can persist the batch_id
+ on the JobStatus row.
+
+ The pending-queue entry's ``payload`` carries everything the
+ callback needs to chain to the next phase: user_id, pass_id,
+ job_id, and the per-phase model map so each phase is submitted —
+ and later priced — with its own model.
+ """
+ model = phase_models[phase]
+ messages = _build_phase_messages(
+ phase=phase,
+ input_bundle=input_bundle,
+ consolidated_json=consolidated_json,
+ recombined_json=recombined_json,
+ )
+ tool_name = PHASE_TOOL_NAMES[phase]
+ tools = [
+ pydantic_to_anthropic_tool(
+ PHASE_RESPONSE_MODELS[phase],
+ tool_name=tool_name,
+ description=PHASE_DESCRIPTIONS[phase],
+ )
+ ]
+ # Anthropic's custom_id must match ``^[a-zA-Z0-9_-]{1,64}$`` —
+ # colons aren't allowed. Underscore separator keeps the
+ # ``pass_id_phase`` structure parseable by the dream callback
+ # while staying within the provider's alphabet.
+ custom_id = f"{pass_id}_{phase}"
+
+ submission = await call_provider(
+ provider="anthropic",
+ model=model,
+ api_key=api_key,
+ messages=messages,
+ max_tokens=PHASE_MAX_TOKENS[phase],
+ temperature=PHASE_TEMPERATURES[phase],
+ tools=tools,
+ tool_choice=force_tool_choice(tool_name),
+ execution_mode="batch",
+ custom_id=custom_id,
+ )
+ if isinstance(submission, ProviderResponse):
+ raise RuntimeError(
+ "submit_phase requested execution_mode='batch' but "
+ "call_provider returned ProviderResponse — Anthropic batch "
+ "may be unsupported for the configured model."
+ )
+
+ entry = PendingEntry(
+ provider="anthropic",
+ provider_batch_id=submission.provider_batch_id,
+ callback_namespace="dream_pass",
+ submitted_at=submission.submitted_at,
+ next_poll_at=submission.submitted_at,
+ poll_delay_seconds=INITIAL_POLL_DELAY_SECONDS,
+ payload={
+ "user_id": user_id,
+ "pass_id": pass_id,
+ "job_id": job_id,
+ "phase": phase,
+ "phase_models": phase_models,
+ "custom_ids": [custom_id],
+ # The phase mapping is what dream_callbacks uses to route
+ # the result row back to a phase label. With one custom_id
+ # per batch we could just look it up by phase, but keeping
+ # the explicit mapping lets us group requests into one
+ # batch in the future without touching the callback.
+ "phase_for_custom_id": {custom_id: phase},
+ },
+ )
+ try:
+ await enqueue_pending(entry)
+ except Exception:
+ # The provider already accepted (and will bill for) this batch, but
+ # the BatchExecutor now has no pending entry to poll it — left as-is
+ # it would run to completion with no callback, orphaning the spend
+ # and stalling the pass. Best-effort cancel the provider batch before
+ # surfacing the failure so the orchestrator releases the lock + marks
+ # the job failed without leaving a paid, un-pollable batch behind.
+ logger.exception(
+ "Dream pass=%s phase=%s: enqueue failed after batch=%s submitted — "
+ "cancelling orphaned provider batch",
+ pass_id,
+ phase,
+ submission.provider_batch_id,
+ )
+ await cancel_batch(
+ provider="anthropic",
+ provider_batch_id=submission.provider_batch_id,
+ api_key=api_key,
+ )
+ raise
+ logger.info(
+ "Dream pass=%s submitted %s batch=%s",
+ pass_id,
+ phase,
+ submission.provider_batch_id,
+ )
+ return submission
+
+
+def _build_phase_messages(
+ *,
+ phase: DreamPhase,
+ input_bundle: DreamInput,
+ consolidated_json: str | None,
+ recombined_json: str | None,
+) -> list[dict[str, str]]:
+ """Build the OpenAI-format message list for one phase.
+
+ Reuses the existing prompt builders so batch and sync paths
+ produce identical inputs — only the transport (batch vs sync)
+ and the structured-output enforcement (tool_use vs response_format)
+ differ.
+ """
+ if phase == "consolidate":
+ return build_consolidate_prompt(input_bundle)
+ if phase == "recombine":
+ if consolidated_json is None:
+ raise ValueError(
+ "recombine phase requires consolidated_json from the "
+ "previous phase's result."
+ )
+ return build_recombine_prompt(input_bundle, consolidated_json)
+ if phase == "sanitize":
+ if consolidated_json is None or recombined_json is None:
+ raise ValueError(
+ "sanitize phase requires both consolidated_json and " "recombined_json."
+ )
+ return build_sanitize_prompt(input_bundle, consolidated_json, recombined_json)
+ raise ValueError(f"Unknown dream phase: {phase}")
+
+
+# ---------------------------------------------------------------------------
+# DreamInput persistence across batch result callbacks
+# ---------------------------------------------------------------------------
+
+
+def input_bundle_key(pass_id: str) -> str:
+ return f"dream:batch:input:{pass_id}"
+
+
+# 24h TTL matches Anthropic's batch SLA — if a batch hasn't completed
+# in 24h we've already timed out via BatchExecutor's
+# ``MAX_BATCH_LIFETIME_SECONDS`` ceiling.
+INPUT_TTL_SECONDS = 24 * 60 * 60
+
+
+async def persist_input_bundle(
+ pass_id: str,
+ input_bundle: DreamInput,
+ *,
+ lock_token: str | None = None,
+) -> None:
+ """Serialize ``DreamInput`` to Redis so callbacks can rebuild prompts.
+
+ DreamInput carries lists of dataclasses; we round-trip through
+ ``json`` rather than pickling so the wire format stays portable +
+ debuggable (`docker exec redis ... HGET ...` works).
+
+ The stored body also carries the dream lock's ownership token
+ (``lock_token``): the orchestrator persists the bundle while it still
+ holds the lock, and the batch callback — hours later, in a different
+ process — needs that token for the compare-and-delete release in
+ ``release_dream_lock``. Riding on this key avoids a second per-pass
+ key and keeps the batch state single-key for cluster mode.
+
+ The orchestrator passes its lock handle's own ``lock_token``
+ explicitly — reading the live lock key here instead could capture a
+ *newer* pass's token (lock expired and was re-acquired between this
+ pass's acquire and the persist), letting this pass's callback release
+ a lock it doesn't own hours later. Only when no token is supplied
+ (eval harness calling the batch path without a lock) do we fall back
+ to the live key.
+ """
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ payload = _input_bundle_to_dict(input_bundle)
+ if lock_token is None:
+ lock_token = await read_dream_lock_token(input_bundle.user_id)
+ if lock_token is not None:
+ payload["lock_token"] = lock_token
+ await redis.set(
+ input_bundle_key(pass_id), json.dumps(payload), ex=INPUT_TTL_SECONDS
+ )
+
+
+async def read_lock_token(pass_id: str) -> str | None:
+ """Dream-lock ownership token persisted alongside the input bundle.
+
+ None when the bundle is gone (TTL expired or already cleaned up), is
+ corrupted, or was written while no lock was held — the caller then
+ leaves the lock to its TTL rather than risking a blind delete of a
+ newer pass's lock.
+ """
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ raw = await redis.get(input_bundle_key(pass_id))
+ if raw is None:
+ return None
+ if isinstance(raw, bytes):
+ raw = raw.decode("utf-8")
+ try:
+ token = json.loads(raw).get("lock_token")
+ except Exception:
+ logger.exception(
+ "Corrupted DreamInput in Redis for pass=%s — no lock token", pass_id
+ )
+ return None
+ return token if isinstance(token, str) else None
+
+
+async def read_input_bundle(pass_id: str) -> DreamInput | None:
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ raw = await redis.get(input_bundle_key(pass_id))
+ if raw is None:
+ return None
+ if isinstance(raw, bytes):
+ raw = raw.decode("utf-8")
+ try:
+ return _dict_to_input_bundle(json.loads(raw))
+ except Exception:
+ logger.exception("Corrupted DreamInput in Redis for pass=%s — bailing", pass_id)
+ return None
+
+
+async def delete_input_bundle(pass_id: str) -> None:
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ await redis.delete(input_bundle_key(pass_id))
+
+
+def _input_bundle_to_dict(input_bundle: DreamInput) -> dict:
+ return {
+ "user_id": input_bundle.user_id,
+ "group_id": input_bundle.group_id,
+ "window_start": input_bundle.window_start.isoformat(),
+ "window_end": input_bundle.window_end.isoformat(),
+ "episodes": [
+ {
+ "uuid": e.uuid,
+ "name": e.name,
+ "content": e.content,
+ "source_description": e.source_description,
+ "valid_at": e.valid_at,
+ "created_at": e.created_at,
+ }
+ for e in input_bundle.episodes
+ ],
+ "facts": [
+ {
+ "uuid": f.uuid,
+ "source": f.source,
+ "target": f.target,
+ "name": f.name,
+ "fact": f.fact,
+ "scope": f.scope,
+ "confidence": f.confidence,
+ "status": f.status,
+ "created_at": f.created_at,
+ }
+ for f in input_bundle.facts
+ ],
+ "recent_sessions": [
+ {
+ "session_id": s.session_id,
+ "title": s.title,
+ "created_at": s.created_at.isoformat() if s.created_at else None,
+ "body": s.body,
+ }
+ for s in input_bundle.recent_sessions
+ ],
+ "known_fact_uuids": list(input_bundle.known_fact_uuids),
+ "known_episode_uuids": list(input_bundle.known_episode_uuids),
+ }
+
+
+def _dict_to_input_bundle(data: dict) -> DreamInput:
+ from .fetch import EpisodeRow, FactRow, SessionRow
+
+ return DreamInput(
+ user_id=data["user_id"],
+ group_id=data["group_id"],
+ window_start=datetime.fromisoformat(data["window_start"]),
+ window_end=datetime.fromisoformat(data["window_end"]),
+ episodes=[EpisodeRow(**e) for e in data.get("episodes") or []],
+ facts=[FactRow(**f) for f in data.get("facts") or []],
+ recent_sessions=[
+ SessionRow(
+ session_id=s["session_id"],
+ title=s.get("title"),
+ created_at=(
+ datetime.fromisoformat(s["created_at"])
+ if s.get("created_at")
+ else None
+ ),
+ body=s.get("body") or "",
+ )
+ for s in data.get("recent_sessions") or []
+ ],
+ known_fact_uuids=set(data.get("known_fact_uuids") or []),
+ known_episode_uuids=set(data.get("known_episode_uuids") or []),
+ )
+
+
+def _dummy_now() -> datetime:
+ """Stub kept for symmetry with Step 4b; never called."""
+ return datetime.now(timezone.utc)
diff --git a/autogpt_platform/backend/backend/copilot/dream/batch_submit_test.py b/autogpt_platform/backend/backend/copilot/dream/batch_submit_test.py
new file mode 100644
index 0000000000..8578717315
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/batch_submit_test.py
@@ -0,0 +1,192 @@
+"""Tests for dream batch submission.
+
+Covers the orphan-prevention guard (a paid provider batch must be
+cancelled when the BatchExecutor enqueue fails afterwards — otherwise it
+runs to completion with no callback to consume it) and the dream-lock
+ownership token riding on the persisted input bundle so the batch
+callback can compare-and-delete the lock hours later.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from backend.copilot.dream.batch_submit import (
+ input_bundle_key,
+ persist_input_bundle,
+ read_input_bundle,
+ read_lock_token,
+ submit_phase,
+)
+from backend.copilot.dream.fetch import DreamInput
+from backend.copilot.dream.locks import DREAM_LOCK_KEY_PREFIX
+from backend.util.llm.providers import BatchSubmissionRef
+
+
+def _bundle() -> DreamInput:
+ now = datetime.now(timezone.utc)
+ return DreamInput(
+ user_id="u1", group_id="user_u1", window_start=now, window_end=now
+ )
+
+
+def fake_redis():
+ """Dict-backed redis stub matching the batch_callbacks_test pattern."""
+ string_store: dict[str, str] = {}
+
+ async def fake_get(key):
+ return string_store.get(key)
+
+ async def fake_set(key, value, ex=None, nx=False):
+ if nx and key in string_store:
+ return None
+ string_store[key] = value
+ return True
+
+ async def fake_delete(key):
+ string_store.pop(key, None)
+
+ stub = AsyncMock()
+ stub.get.side_effect = fake_get
+ stub.set.side_effect = fake_set
+ stub.delete.side_effect = fake_delete
+
+ with patch(
+ "backend.data.redis_client.get_redis_async",
+ AsyncMock(return_value=stub),
+ ):
+ yield stub, string_store
+
+
+async def test_enqueue_failure_cancels_orphaned_batch_and_reraises():
+ submitted = BatchSubmissionRef(
+ provider="anthropic",
+ provider_batch_id="msgbatch_orphan",
+ custom_id="p1_consolidate",
+ submitted_at=datetime.now(timezone.utc),
+ )
+ call = AsyncMock(return_value=submitted)
+ enqueue = AsyncMock(side_effect=RuntimeError("redis down"))
+ cancel = AsyncMock(return_value=True)
+
+ with patch("backend.copilot.dream.batch_submit.call_provider", call), patch(
+ "backend.copilot.dream.batch_submit.enqueue_pending", enqueue
+ ), patch("backend.copilot.dream.batch_submit.cancel_batch", cancel):
+ with pytest.raises(RuntimeError, match="redis down"):
+ await submit_phase(
+ user_id="u1",
+ pass_id="p1",
+ job_id="j1",
+ phase="consolidate",
+ phase_models={"consolidate": "claude-sonnet-4-6"},
+ api_key="sk-test",
+ input_bundle=_bundle(),
+ )
+
+ # The just-submitted, paid batch must be cancelled, not left orphaned.
+ cancel.assert_awaited_once()
+ assert cancel.call_args.kwargs["provider_batch_id"] == "msgbatch_orphan"
+ assert cancel.call_args.kwargs["api_key"] == "sk-test"
+
+
+async def test_successful_enqueue_does_not_cancel():
+ submitted = BatchSubmissionRef(
+ provider="anthropic",
+ provider_batch_id="msgbatch_ok",
+ custom_id="p1_consolidate",
+ submitted_at=datetime.now(timezone.utc),
+ )
+ call = AsyncMock(return_value=submitted)
+ enqueue = AsyncMock(return_value=None)
+ cancel = AsyncMock()
+
+ with patch("backend.copilot.dream.batch_submit.call_provider", call), patch(
+ "backend.copilot.dream.batch_submit.enqueue_pending", enqueue
+ ), patch("backend.copilot.dream.batch_submit.cancel_batch", cancel):
+ ref = await submit_phase(
+ user_id="u1",
+ pass_id="p1",
+ job_id="j1",
+ phase="consolidate",
+ phase_models={"consolidate": "claude-sonnet-4-6"},
+ api_key="sk-test",
+ input_bundle=_bundle(),
+ )
+
+ enqueue.assert_awaited_once()
+ cancel.assert_not_awaited()
+ assert ref.provider_batch_id == "msgbatch_ok"
+
+
+async def test_persist_input_bundle_carries_explicit_lock_token(fake_redis):
+ """The orchestrator persists the bundle while still holding the dream
+ lock and passes its OWN handle token; the bundle must carry it so the
+ batch callback — hours later, in another process — can
+ compare-and-delete."""
+ _, string_store = fake_redis
+ string_store[f"{DREAM_LOCK_KEY_PREFIX}u1"] = "tok-abc"
+
+ await persist_input_bundle("p1", _bundle(), lock_token="tok-abc")
+
+ assert await read_lock_token("p1") == "tok-abc"
+ # The bundle itself still round-trips untouched by the extra field.
+ bundle = await read_input_bundle("p1")
+ assert bundle is not None
+ assert bundle.user_id == "u1"
+
+
+async def test_persist_input_bundle_explicit_token_wins_over_live_key(fake_redis):
+ """If this pass's lock expired and a NEWER pass re-acquired the key
+ before persist runs, the live key holds the newer pass's token. The
+ bundle must store the token the caller actually owns — storing the
+ live value would let this pass's callback compare-and-delete the
+ newer pass's lock hours later."""
+ _, string_store = fake_redis
+ string_store[f"{DREAM_LOCK_KEY_PREFIX}u1"] = "tok-newer-pass"
+
+ await persist_input_bundle("p1", _bundle(), lock_token="tok-ours")
+
+ assert await read_lock_token("p1") == "tok-ours"
+
+
+async def test_persist_input_bundle_falls_back_to_live_key_without_token(fake_redis):
+ """Callers that don't supply a token (eval harness) fall back to
+ reading the live lock key at persist time."""
+ _, string_store = fake_redis
+ string_store[f"{DREAM_LOCK_KEY_PREFIX}u1"] = "tok-live"
+
+ await persist_input_bundle("p1", _bundle())
+
+ assert await read_lock_token("p1") == "tok-live"
+
+
+async def test_persist_input_bundle_omits_token_when_lock_unheld(fake_redis):
+ """No token supplied and no held lock at persist time ⇒ no token
+ stored, and the callback falls back to the lock TTL instead of a
+ blind delete."""
+ await persist_input_bundle("p2", _bundle())
+
+ assert await read_lock_token("p2") is None
+
+
+async def test_read_lock_token_none_when_bundle_expired(fake_redis):
+ assert await read_lock_token("p-gone") is None
+
+
+async def test_read_lock_token_none_when_bundle_corrupted(fake_redis):
+ _, string_store = fake_redis
+ string_store[input_bundle_key("p3")] = "not json {{{"
+
+ assert await read_lock_token("p3") is None
diff --git a/autogpt_platform/backend/backend/copilot/dream/billing.py b/autogpt_platform/backend/backend/copilot/dream/billing.py
new file mode 100644
index 0000000000..1a3a4a687f
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/billing.py
@@ -0,0 +1,207 @@
+"""Dream-pass billing — pre-flight check + per-step cost log.
+
+Dream-pass spend rolls into the user's existing daily/weekly USD budget
+(``backend.copilot.rate_limit``) — there is no dedicated dream-pass
+counter. This module is the seam between the orchestrator and the
+shared billing primitives:
+
+* :func:`check_dream_budget` — pre-flight gate. Called once after the
+ Redis lock is acquired, before phase 1 runs. Refuses the pass when
+ the user is paywalled (``NO_TIER`` + ``ENABLE_PLATFORM_PAYMENT``) or
+ has already exhausted their daily/weekly cap.
+* :func:`record_phase_cost` — per-phase charge. Called after each of
+ consolidate / recombine / sanitize completes, charging the real LLM
+ spend against the user's window and writing a ``PlatformCostLog``
+ row with ``provider`` set to the actual LLM provider (so downstream
+ cost dashboards don't have to back-correlate dream rows to OpenRouter
+ vs Anthropic vs OpenAI).
+
+Per-LLM-call rows (not one row per pass) match the chat convention so
+the existing per-block / per-provider rollups in the admin dashboard
+keep working without dream-specific code paths.
+
+Failure semantics mirror the chat path: a partial pass still charges
+for the phases that completed before the error, because we already
+paid the provider for those tokens.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Literal
+
+from backend.copilot.config import ChatConfig
+from backend.copilot.rate_limit import (
+ RateLimitExceeded,
+ RateLimitUnavailable,
+ check_rate_limit,
+ get_global_rate_limits,
+ is_user_paywalled,
+)
+from backend.copilot.token_tracking import persist_and_record_usage
+from backend.copilot.transport_routing import routing_kwargs_for_chat_transport
+
+from .routing import ExecutionPath
+from .schemas import PhaseUsage
+
+logger = logging.getLogger(__name__)
+
+
+# Provider-locked batch paths — these dispatch through a specific
+# provider's batch API regardless of which chat transport is active,
+# so the cost-log label is fixed at the table level. The
+# ``sync_baseline`` path is NOT in this table because its provider
+# follows the active ``ChatConfig.transport`` (see
+# :func:`_provider_for_execution_path` below).
+_PROVIDER_BY_BATCH_PATH: dict[ExecutionPath, str] = {
+ "anthropic_batch": "anthropic",
+ "openai_batch": "openai",
+}
+
+
+def _provider_for_execution_path(execution_path: ExecutionPath) -> str:
+ """Resolve the ``PlatformCostLog.provider`` label for a phase row.
+
+ Batch paths are pinned to their provider (Anthropic / OpenAI). The
+ sync_baseline path follows the active chat transport — so a
+ local-Ollama install logs ``provider="ollama"``, a subscription
+ or direct-Anthropic install logs ``"anthropic"``, and the cloud
+ OpenRouter default logs ``"open_router"``. Centralizes what was
+ a static ``"sync_baseline" → "open_router"`` mapping that
+ misattributed local + subscription dream rows as OR spend on the
+ admin dashboard.
+ """
+ if execution_path in _PROVIDER_BY_BATCH_PATH:
+ return _PROVIDER_BY_BATCH_PATH[execution_path]
+ return routing_kwargs_for_chat_transport().cost_log_provider
+
+
+DreamBudgetSkipReason = Literal[
+ "insufficient_credits",
+ "rate_limit_unavailable",
+]
+
+
+async def check_dream_budget(
+ user_id: str, config: ChatConfig | None = None
+) -> tuple[bool, DreamBudgetSkipReason | None]:
+ """Pre-flight: is the user allowed to spend on a dream pass right now?
+
+ Returns ``(True, None)`` when the pass may proceed. Returns
+ ``(False, reason)`` when the orchestrator should bail with a
+ skipped result. Background-callable — never raises.
+
+ Reasons:
+ ``"insufficient_credits"`` — user is paywalled (NO_TIER +
+ ``ENABLE_PLATFORM_PAYMENT`` on) OR already over their
+ daily/weekly cap. Treated as a soft skip so the next
+ scheduler tick retries naturally.
+ ``"rate_limit_unavailable"`` — Redis is unreadable. Fail
+ closed: a brown-out must not let dream passes bypass the
+ user's USD cap. Surfaces as ``error`` on the result so the
+ admin endpoint reports it; the scheduler retries next tick.
+ """
+ config = config or ChatConfig()
+
+ try:
+ paywalled = await is_user_paywalled(user_id)
+ except Exception as exc:
+ # Tier lookup failure during a background job — fail closed so
+ # we don't run a paywalled user's dream pass on a transient
+ # Supabase blip. Scheduler will retry next tick.
+ logger.warning(
+ "dream billing: paywall check failed for user=%s: %s", user_id[:8], exc
+ )
+ return False, "rate_limit_unavailable"
+ if paywalled:
+ logger.info("dream billing: skipping paywalled user=%s", user_id[:8])
+ return False, "insufficient_credits"
+
+ try:
+ daily_limit, weekly_limit, _tier = await get_global_rate_limits(
+ user_id,
+ config.daily_cost_limit_microdollars,
+ config.weekly_cost_limit_microdollars,
+ )
+ await check_rate_limit(
+ user_id=user_id,
+ daily_cost_limit=daily_limit,
+ weekly_cost_limit=weekly_limit,
+ skip_daily=True,
+ )
+ except RateLimitExceeded as exc:
+ logger.info(
+ "dream billing: user=%s over %s cap, skipping", user_id[:8], exc.window
+ )
+ return False, "insufficient_credits"
+ except RateLimitUnavailable:
+ logger.warning(
+ "dream billing: rate-limit state unreadable for user=%s; failing closed",
+ user_id[:8],
+ )
+ return False, "rate_limit_unavailable"
+
+ return True, None
+
+
+async def record_phase_cost(
+ *,
+ user_id: str,
+ pass_id: str,
+ phase_usage: PhaseUsage,
+ execution_path: ExecutionPath,
+) -> None:
+ """Charge one phase's spend against the user's window + log a row.
+
+ Writes a ``PlatformCostLog`` row tagged ``provider=<llm_provider>``
+ (not ``provider="dream_pass"``) so existing per-provider dashboards
+ aggregate naturally. The dream-specific shape is carried in
+ ``metadata`` (dream_pass_id, dream_phase, execution_path,
+ discount_applied) and ``block_name=copilot:dream:<phase>`` so the
+ per-block rollup separates dream spend from chat spend.
+
+ ``graph_exec_id`` is set to the ``pass_id`` so each phase row joins
+ back to its parent dream pass — the same join key the future P9
+ inline ``dream.operations`` SSE event will reference.
+
+ No-ops when the phase has no cost (skipped phase / unknown rate
+ card). Matches ``persist_and_record_usage``'s contract: tokens
+ without cost still log but don't charge the rate-limit counter.
+ """
+ if (
+ phase_usage.cost_usd is None
+ and (
+ phase_usage.input_tokens
+ + phase_usage.output_tokens
+ + phase_usage.cache_read_tokens
+ + phase_usage.cache_creation_tokens
+ )
+ == 0
+ ):
+ return
+
+ provider = _provider_for_execution_path(execution_path)
+
+ await persist_and_record_usage(
+ session=None,
+ user_id=user_id,
+ prompt_tokens=phase_usage.input_tokens,
+ completion_tokens=phase_usage.output_tokens,
+ cache_read_tokens=phase_usage.cache_read_tokens,
+ cache_creation_tokens=phase_usage.cache_creation_tokens,
+ log_prefix=f"[dream:{phase_usage.phase}]",
+ cost_usd=phase_usage.cost_usd,
+ model=phase_usage.model,
+ provider=provider,
+ block_name_override=f"copilot:dream:{phase_usage.phase}",
+ graph_exec_id_override=pass_id,
+ extra_metadata={
+ "source": "dream_pass",
+ "dream_pass_id": pass_id,
+ "dream_phase": phase_usage.phase,
+ "execution_path": execution_path,
+ },
+ # Dream is background work — it rolls up under the user's
+ # weekly cap but must not eat the interactive daily budget.
+ skip_daily=True,
+ )
diff --git a/autogpt_platform/backend/backend/copilot/dream/billing_test.py b/autogpt_platform/backend/backend/copilot/dream/billing_test.py
new file mode 100644
index 0000000000..fc24d5531b
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/billing_test.py
@@ -0,0 +1,288 @@
+"""Dream-pass billing tests — pre-flight check + per-phase cost log.
+
+Covers the two billing seams the orchestrator uses:
+ * check_dream_budget — paywall, rate-limit cap, Redis brown-out
+ * record_phase_cost — provider tag mapping, dream metadata,
+ block_name, graph_exec_id correlation, no-op on empty phase
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from backend.copilot.rate_limit import RateLimitExceeded, RateLimitUnavailable
+
+from . import billing as billing_mod
+from .schemas import PhaseUsage
+
+# ---------------------------------------------------------------------------
+# check_dream_budget
+# ---------------------------------------------------------------------------
+
+
+async def test_check_dream_budget_allows_under_cap_user():
+ with patch.object(
+ billing_mod, "is_user_paywalled", new=AsyncMock(return_value=False)
+ ), patch.object(
+ billing_mod,
+ "get_global_rate_limits",
+ new=AsyncMock(return_value=(1_000_000, 5_000_000, None)),
+ ), patch.object(
+ billing_mod, "check_rate_limit", new=AsyncMock(return_value=None)
+ ):
+ ok, reason = await billing_mod.check_dream_budget("u1")
+ assert (ok, reason) == (True, None)
+
+
+async def test_check_dream_budget_skips_paywalled_user_as_insufficient_credits():
+ with patch.object(
+ billing_mod, "is_user_paywalled", new=AsyncMock(return_value=True)
+ ):
+ ok, reason = await billing_mod.check_dream_budget("u1")
+ assert (ok, reason) == (False, "insufficient_credits")
+
+
+async def test_check_dream_budget_skips_when_user_is_over_daily_cap():
+ reset_at = datetime(2026, 5, 22, tzinfo=timezone.utc)
+ with patch.object(
+ billing_mod, "is_user_paywalled", new=AsyncMock(return_value=False)
+ ), patch.object(
+ billing_mod,
+ "get_global_rate_limits",
+ new=AsyncMock(return_value=(0, 0, None)),
+ ), patch.object(
+ billing_mod,
+ "check_rate_limit",
+ new=AsyncMock(side_effect=RateLimitExceeded("daily", reset_at)),
+ ):
+ ok, reason = await billing_mod.check_dream_budget("u1")
+ assert (ok, reason) == (False, "insufficient_credits")
+
+
+async def test_check_dream_budget_fails_closed_on_redis_brownout():
+ """Redis unreadable → orchestrator must NOT bill on it; fail closed."""
+ with patch.object(
+ billing_mod, "is_user_paywalled", new=AsyncMock(return_value=False)
+ ), patch.object(
+ billing_mod,
+ "get_global_rate_limits",
+ new=AsyncMock(return_value=(1_000_000, 5_000_000, None)),
+ ), patch.object(
+ billing_mod,
+ "check_rate_limit",
+ new=AsyncMock(side_effect=RateLimitUnavailable()),
+ ):
+ ok, reason = await billing_mod.check_dream_budget("u1")
+ assert (ok, reason) == (False, "rate_limit_unavailable")
+
+
+async def test_check_dream_budget_fails_closed_when_paywall_lookup_raises():
+ """Background callers can't rely on enforce_payment_paywall's HTTP-503;
+ we treat lookup failure as 'cannot prove eligibility' → skip."""
+ with patch.object(
+ billing_mod,
+ "is_user_paywalled",
+ new=AsyncMock(side_effect=Exception("supabase blip")),
+ ):
+ ok, reason = await billing_mod.check_dream_budget("u1")
+ assert (ok, reason) == (False, "rate_limit_unavailable")
+
+
+# ---------------------------------------------------------------------------
+# record_phase_cost
+# ---------------------------------------------------------------------------
+
+
+def _routing_kwargs(cost_log_provider: str):
+ """Build a ``ProviderRoutingKwargs`` whose ``cost_log_provider``
+ is the only field ``_provider_for_execution_path`` reads on the
+ sync_baseline path. The other fields are placeholders."""
+ from backend.copilot.transport_routing import ProviderRoutingKwargs
+
+ return ProviderRoutingKwargs(
+ provider="open_router",
+ api_key="",
+ base_url=None,
+ supports_flex=False,
+ cost_log_provider=cost_log_provider,
+ )
+
+
+async def test_record_phase_cost_tags_sync_baseline_provider_from_transport():
+ """sync_baseline ``provider`` follows the active chat transport's
+ ``cost_log_provider`` — the cloud OpenRouter case still labels
+ rows as ``open_router`` so existing dashboards stay correct."""
+ spy = AsyncMock()
+ with patch.object(billing_mod, "persist_and_record_usage", new=spy), patch.object(
+ billing_mod,
+ "routing_kwargs_for_chat_transport",
+ return_value=_routing_kwargs("open_router"),
+ ):
+ await billing_mod.record_phase_cost(
+ user_id="u1",
+ pass_id="pass-uuid",
+ phase_usage=PhaseUsage(
+ phase="consolidate",
+ model="anthropic/claude-sonnet-4.6",
+ input_tokens=100,
+ output_tokens=50,
+ cost_usd=0.0025,
+ ),
+ execution_path="sync_baseline",
+ )
+ kwargs = spy.await_args.kwargs
+ assert kwargs["provider"] == "open_router"
+
+
+async def test_record_phase_cost_tags_sync_baseline_provider_ollama_under_local():
+ """Local-transport dream rows must label as ``ollama`` so the
+ admin platform-costs dashboard distinguishes them from OR cloud
+ spend. Previously hard-coded to ``open_router``."""
+ spy = AsyncMock()
+ with patch.object(billing_mod, "persist_and_record_usage", new=spy), patch.object(
+ billing_mod,
+ "routing_kwargs_for_chat_transport",
+ return_value=_routing_kwargs("ollama"),
+ ):
+ await billing_mod.record_phase_cost(
+ user_id="u1",
+ pass_id="p",
+ phase_usage=PhaseUsage(phase="recombine", model="qwen3.5:8b", cost_usd=0.0),
+ execution_path="sync_baseline",
+ )
+ assert spy.await_args.kwargs["provider"] == "ollama"
+
+
+async def test_record_phase_cost_tags_sync_baseline_provider_anthropic_under_subscription():
+ """Subscription / direct_anthropic transports label sync_baseline
+ rows as ``anthropic`` so dream + chat spend roll up together
+ under one provider on the admin dashboard."""
+ spy = AsyncMock()
+ with patch.object(billing_mod, "persist_and_record_usage", new=spy), patch.object(
+ billing_mod,
+ "routing_kwargs_for_chat_transport",
+ return_value=_routing_kwargs("anthropic"),
+ ):
+ await billing_mod.record_phase_cost(
+ user_id="u1",
+ pass_id="p",
+ phase_usage=PhaseUsage(
+ phase="sanitize",
+ model="anthropic/claude-sonnet-4-6",
+ cost_usd=0.0025,
+ ),
+ execution_path="sync_baseline",
+ )
+ assert spy.await_args.kwargs["provider"] == "anthropic"
+
+
+async def test_record_phase_cost_tags_provider_anthropic_for_batch_path():
+ spy = AsyncMock()
+ with patch.object(billing_mod, "persist_and_record_usage", new=spy):
+ await billing_mod.record_phase_cost(
+ user_id="u1",
+ pass_id="p",
+ phase_usage=PhaseUsage(
+ phase="recombine", model="anthropic/claude-opus-4.7", cost_usd=0.01
+ ),
+ execution_path="anthropic_batch",
+ )
+ assert spy.await_args.kwargs["provider"] == "anthropic"
+
+
+async def test_record_phase_cost_tags_provider_openai_for_openai_batch_path():
+ spy = AsyncMock()
+ with patch.object(billing_mod, "persist_and_record_usage", new=spy):
+ await billing_mod.record_phase_cost(
+ user_id="u1",
+ pass_id="p",
+ phase_usage=PhaseUsage(phase="sanitize", model="gpt-5", cost_usd=0.005),
+ execution_path="openai_batch",
+ )
+ assert spy.await_args.kwargs["provider"] == "openai"
+
+
+async def test_record_phase_cost_uses_dream_block_name_and_passes_pass_id_as_graph_exec_id():
+ """Block name must distinguish dream from chat, and pass_id is the
+ correlation key on the row so all 3 phases of one pass join up."""
+ spy = AsyncMock()
+ with patch.object(billing_mod, "persist_and_record_usage", new=spy):
+ await billing_mod.record_phase_cost(
+ user_id="u1",
+ pass_id="pass-uuid-1",
+ phase_usage=PhaseUsage(
+ phase="sanitize", model="m", input_tokens=10, cost_usd=0.001
+ ),
+ execution_path="sync_baseline",
+ )
+ kwargs = spy.await_args.kwargs
+ assert kwargs["block_name_override"] == "copilot:dream:sanitize"
+ assert kwargs["graph_exec_id_override"] == "pass-uuid-1"
+
+
+async def test_record_phase_cost_writes_dream_metadata():
+ """Downstream dashboards key off `source` and `dream_pass_id` —
+ if those drift the cost rollups silently lose dream rows."""
+ spy = AsyncMock()
+ with patch.object(billing_mod, "persist_and_record_usage", new=spy):
+ await billing_mod.record_phase_cost(
+ user_id="u1",
+ pass_id="pass-xyz",
+ phase_usage=PhaseUsage(
+ phase="consolidate", model="m", input_tokens=1, cost_usd=0.001
+ ),
+ execution_path="anthropic_batch",
+ )
+ metadata = spy.await_args.kwargs["extra_metadata"]
+ assert metadata["source"] == "dream_pass"
+ assert metadata["dream_pass_id"] == "pass-xyz"
+ assert metadata["dream_phase"] == "consolidate"
+ assert metadata["execution_path"] == "anthropic_batch"
+
+
+async def test_record_phase_cost_skips_completely_empty_phase():
+ """Zero tokens AND no cost → no billing row, no rate-limit charge.
+ Avoids logging junk rows when a phase short-circuited (e.g. no input
+ to consolidate)."""
+ spy = AsyncMock()
+ with patch.object(billing_mod, "persist_and_record_usage", new=spy):
+ await billing_mod.record_phase_cost(
+ user_id="u1",
+ pass_id="p",
+ phase_usage=PhaseUsage(phase="consolidate", model="m"),
+ execution_path="sync_baseline",
+ )
+ spy.assert_not_called()
+
+
+async def test_record_phase_cost_logs_token_only_phase_even_without_cost():
+ """Phase ran (real tokens) but provider didn't report cost — still
+ log the row for analytics even though rate-limit won't charge."""
+ spy = AsyncMock()
+ with patch.object(billing_mod, "persist_and_record_usage", new=spy):
+ await billing_mod.record_phase_cost(
+ user_id="u1",
+ pass_id="p",
+ phase_usage=PhaseUsage(
+ phase="recombine", model="m", input_tokens=10, output_tokens=5
+ ),
+ execution_path="sync_baseline",
+ )
+ spy.assert_called_once()
diff --git a/autogpt_platform/backend/backend/copilot/dream/fetch.py b/autogpt_platform/backend/backend/copilot/dream/fetch.py
new file mode 100644
index 0000000000..098be3e52d
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/fetch.py
@@ -0,0 +1,307 @@
+"""Gather bounded inputs for a dream pass.
+
+All input lists are clamped per ``dream/p0-spec.md`` §2 — phase 1's
+prompt is the hot path for cost, so we never let it grow unbounded
+even on a power-user with thousands of episodes.
+
+Caps (copied here so they live next to the code that enforces them):
+ * Recent sessions: 10
+ * Recent episodes: 50
+ * Active facts (per scope): 500
+ * Touch window: 14 days
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta, timezone
+
+from pydantic import BaseModel, Field
+
+from backend.copilot.graphiti.client import derive_group_id
+from backend.copilot.graphiti.config import graphiti_config
+from backend.copilot.graphiti.falkordb_driver import AutoGPTFalkorDriver
+from backend.data.db_accessors import chat_db
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_WINDOW_DAYS = 14
+MAX_EPISODES = 50
+MAX_ACTIVE_FACTS = 500
+MAX_RECENT_SESSIONS = 10
+MAX_SESSION_BODY_BYTES = 8 * 1024 # 8 KB per p0-spec.md §2
+
+
+class EpisodeRow(BaseModel):
+ uuid: str
+ name: str | None
+ content: str | None
+ source_description: str | None
+ valid_at: str | None # ISO timestamp
+ created_at: str | None
+
+
+class FactRow(BaseModel):
+ uuid: str
+ source: str | None
+ target: str | None
+ name: str | None
+ fact: str | None
+ scope: str | None
+ confidence: float | None
+ status: str | None
+ created_at: str | None
+
+
+class SessionRow(BaseModel):
+ session_id: str
+ title: str | None
+ created_at: datetime | None
+ body: str # truncated to MAX_SESSION_BODY_BYTES
+
+
+class DreamInput(BaseModel):
+ """The whole gather-step bundle handed to the phase 1 prompt."""
+
+ user_id: str
+ group_id: str
+ window_start: datetime
+ window_end: datetime
+ episodes: list[EpisodeRow] = Field(default_factory=list)
+ facts: list[FactRow] = Field(default_factory=list)
+ recent_sessions: list[SessionRow] = Field(default_factory=list)
+ # Convenience — phase 3 sanitizer needs to know which uuids the dream
+ # is "aware of" so it can reject demotions for unknown edges.
+ known_fact_uuids: set[str] = Field(default_factory=set)
+ known_episode_uuids: set[str] = Field(default_factory=set)
+
+
+def _open_driver(group_id: str) -> AutoGPTFalkorDriver:
+ return AutoGPTFalkorDriver(
+ host=graphiti_config.falkordb_host,
+ port=graphiti_config.falkordb_port,
+ password=graphiti_config.falkordb_password or None,
+ database=group_id,
+ # Indices are built by the long-lived chat-write client when the
+ # user first writes a memory; the dream pass reads from an
+ # already-indexed graph and shouldn't refire the
+ # background-task race that produces "Buffer is closed" spam.
+ build_indices=False,
+ )
+
+
+async def _fetch_recent_episodes(
+ driver: AutoGPTFalkorDriver,
+ group_id: str,
+ window_start: datetime,
+ limit: int,
+) -> list[EpisodeRow]:
+ # FalkorDB does not implement Cypher's ``datetime()`` function, so
+ # we cannot use ``WHERE n.valid_at >= datetime($since)`` here — it
+ # raises ``Unknown function 'datetime'``. The dream window is
+ # already bounded by ``limit`` (default 50 most-recent episodes,
+ # which exceeds typical 14-day activity for any one user). The
+ # ``window_start`` argument is kept for caller bookkeeping but the
+ # Cypher itself just relies on the ORDER BY + LIMIT clamp.
+ _ = window_start
+ try:
+ result = await driver.execute_query(
+ """
+ MATCH (n:Episodic {group_id: $g})
+ RETURN n.uuid AS uuid,
+ n.name AS name,
+ n.content AS content,
+ n.source_description AS source_description,
+ toString(n.valid_at) AS valid_at,
+ toString(n.created_at) AS created_at
+ ORDER BY n.valid_at DESC
+ LIMIT $limit
+ """,
+ g=group_id,
+ limit=limit,
+ )
+ except Exception:
+ logger.warning(
+ "Failed to fetch recent episodes for group %s — treating as empty",
+ group_id[:12],
+ exc_info=True,
+ )
+ return []
+ rows = result[0] if result else []
+ return [
+ EpisodeRow(
+ uuid=str(r.get("uuid", "")),
+ name=r.get("name"),
+ content=r.get("content"),
+ source_description=r.get("source_description"),
+ valid_at=r.get("valid_at"),
+ created_at=r.get("created_at"),
+ )
+ for r in rows
+ ]
+
+
+async def _fetch_active_facts(
+ driver: AutoGPTFalkorDriver,
+ group_id: str,
+ limit: int,
+) -> list[FactRow]:
+ try:
+ result = await driver.execute_query(
+ """
+ MATCH (src:Entity)-[e:RELATES_TO {group_id: $g}]->(tgt:Entity)
+ WHERE (e.status IS NULL OR e.status = 'active')
+ AND (e.expired_at IS NULL)
+ RETURN e.uuid AS uuid,
+ src.name AS source,
+ tgt.name AS target,
+ e.name AS name,
+ e.fact AS fact,
+ e.scope AS scope,
+ e.confidence AS confidence,
+ e.status AS status,
+ toString(e.created_at) AS created_at
+ ORDER BY e.created_at DESC
+ LIMIT $limit
+ """,
+ g=group_id,
+ limit=limit,
+ )
+ except Exception:
+ logger.warning(
+ "Failed to fetch active facts for group %s — treating as empty",
+ group_id[:12],
+ exc_info=True,
+ )
+ return []
+ rows = result[0] if result else []
+ return [
+ FactRow(
+ uuid=str(r.get("uuid", "")),
+ source=r.get("source"),
+ target=r.get("target"),
+ name=r.get("name"),
+ fact=r.get("fact"),
+ scope=r.get("scope"),
+ confidence=r.get("confidence"),
+ status=r.get("status"),
+ created_at=r.get("created_at"),
+ )
+ for r in rows
+ ]
+
+
+async def _fetch_recent_sessions(
+ user_id: str,
+ window_start: datetime,
+ limit: int,
+) -> list[SessionRow]:
+ """Pull the most recent N chat sessions and their first chunk of content.
+
+ Routes through ``chat_db()`` so the dream pass — which runs in the
+ Scheduler subprocess — uses the DatabaseManager RPC when Prisma
+ isn't directly connected, and the in-process Postgres path when
+ it is. Direct ``PrismaChatSession.prisma()`` calls fail with
+ ``ClientNotConnectedError`` in the Scheduler subprocess otherwise.
+
+ We only need a flavour-snapshot of each session, not the full
+ message list — phase 1's prompt cares about *what was discussed
+ recently* as context for consolidation, not about replaying it.
+ The ``window_start`` argument is informational here; the underlying
+ ``get_user_chat_sessions`` orders by most-recent and the ``limit``
+ clamp does the bounding.
+ """
+ _ = window_start
+ try:
+ sessions = await chat_db().get_user_chat_sessions(user_id, limit=limit)
+ except Exception:
+ logger.warning(
+ "Failed to fetch recent sessions for user %s",
+ user_id[:12],
+ exc_info=True,
+ )
+ return []
+
+ out: list[SessionRow] = []
+ for s in sessions:
+ # ``ChatSessionInfo`` exposes ``session_id`` (not ``id``) and
+ # carries no messages (it's a summary). Fetch the body lazily
+ # per-session via the paginated reader so the prompt has
+ # actual content. One round-trip per session is acceptable at
+ # limit=10; a bulk variant can replace this when chat_db
+ # gains one.
+ sid = s.session_id
+ messages: list = []
+ try:
+ paginated = await chat_db().get_chat_messages_paginated(
+ session_id=sid, limit=20, user_id=user_id
+ )
+ if paginated is not None:
+ messages = list(getattr(paginated, "messages", []) or [])
+ except Exception:
+ logger.debug(
+ "Failed to fetch messages for session %s — body left empty",
+ sid[:12],
+ exc_info=True,
+ )
+ body_parts: list[str] = []
+ running_len = 0
+ for m in messages:
+ line = f"{m.role}: {m.content or ''}"
+ running_len += len(line) + 1
+ body_parts.append(line)
+ if running_len >= MAX_SESSION_BODY_BYTES:
+ break
+ body = "\n".join(body_parts)[:MAX_SESSION_BODY_BYTES]
+ out.append(
+ SessionRow(
+ session_id=sid,
+ title=s.title,
+ created_at=getattr(s, "createdAt", None)
+ or getattr(s, "created_at", None),
+ body=body,
+ )
+ )
+ return out
+
+
+async def gather_dream_input(
+ user_id: str,
+ *,
+ window_days: int = DEFAULT_WINDOW_DAYS,
+ max_episodes: int = MAX_EPISODES,
+ max_facts: int = MAX_ACTIVE_FACTS,
+ max_sessions: int = MAX_RECENT_SESSIONS,
+) -> DreamInput:
+ """Build the full bounded input bundle for one dream pass.
+
+ All clamps are enforced here, not in the caller. If any one of
+ the three sources fails (Cypher error, Prisma timeout) the others
+ still proceed — a partial dream is better than no dream.
+ """
+ group_id = derive_group_id(user_id)
+ window_end = datetime.now(timezone.utc)
+ window_start = window_end - timedelta(days=window_days)
+
+ driver = _open_driver(group_id)
+ try:
+ episodes = await _fetch_recent_episodes(
+ driver, group_id, window_start, max_episodes
+ )
+ facts = await _fetch_active_facts(driver, group_id, max_facts)
+ finally:
+ await driver.close()
+
+ sessions = await _fetch_recent_sessions(user_id, window_start, max_sessions)
+
+ return DreamInput(
+ user_id=user_id,
+ group_id=group_id,
+ window_start=window_start,
+ window_end=window_end,
+ episodes=episodes,
+ facts=facts,
+ recent_sessions=sessions,
+ known_fact_uuids={f.uuid for f in facts},
+ known_episode_uuids={e.uuid for e in episodes},
+ )
diff --git a/autogpt_platform/backend/backend/copilot/dream/job_status.py b/autogpt_platform/backend/backend/copilot/dream/job_status.py
new file mode 100644
index 0000000000..87f76a72c2
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/job_status.py
@@ -0,0 +1,310 @@
+"""Redis-backed status registry for fire-and-forget admin jobs.
+
+Admin trigger endpoints used to block synchronously waiting for the
+dream pass / nightly batch / community rebuild to finish — easy
+5-minute httpx ``ReadTimeout`` when an LLM phase legitimately took
+longer than the RPC timeout, plus no way to recover the result if the
+client tab closed mid-run.
+
+The new pattern: admin POST writes an initial :class:`JobStatus` row
+keyed by ``job_id`` (UUID), kicks off the work via APScheduler's
+``add_job(run_date=now)`` and returns 202 immediately. The work body
+calls :func:`update_status_phase` at each phase transition and
+:func:`mark_complete` / :func:`mark_errored` at the end. Admin UI
+polls a GET endpoint that reads the row back. 6-hour TTL bounds
+abandoned rows.
+
+This module is dream-shaped (kinds are ``nightly``, ``dream_pass``,
+``rebuild`` — the three long-running admin triggers we have today),
+but the storage primitive is generic enough to extend to any future
+fire-and-forget admin job.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from typing import Any, Generic, Literal, TypeVar
+
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+# ``JobStatus`` is parametrized by the concrete ``result`` payload type.
+# Each job kind specializes T at the admin-route layer (e.g.
+# ``DreamJobStatus = JobStatus[DreamPassResult]``) so FastAPI emits the
+# full nested OpenAPI schema for the per-kind result without any
+# parallel ``*Response`` shim classes.
+ResultT = TypeVar("ResultT", bound=BaseModel)
+
+
+# Key prefix lives at the dream namespace today because all three job
+# kinds are dream-system-adjacent. If a non-dream caller ever needs
+# this registry, hoist the prefix to ``admin:job:`` then.
+STATUS_KEY_PREFIX = "dream:status"
+
+# 6 hours. Longer than the dream lock TTL (1800s) so results stay
+# visible after the work completes. An admin who triggers a run, walks
+# away, and comes back hours later still sees the result.
+STATUS_TTL_SECONDS = 6 * 60 * 60
+
+
+JobKind = Literal["nightly", "dream_pass", "rebuild"]
+
+JobState = Literal[
+ "queued", # initial state — admin endpoint wrote the row, scheduler hasn't picked it up yet
+ "running", # work body has started; phase transitions update current_phase
+ "submitted", # batch path — work body submitted to provider's batch API and is awaiting result
+ "complete", # terminal: result populated
+ "errored", # terminal: error populated
+]
+
+
+class JobStatus(BaseModel, Generic[ResultT]):
+ """Status row for one fire-and-forget admin job.
+
+ Stored as a JSON-serialized Redis string at
+ ``dream:status:{kind}:{job_id}``. Single ``SET`` per write so there
+ are no read-modify-write races even if multiple workers touch the
+ same job_id concurrently — the last writer wins, but each writer
+ has read the latest state before composing its update via the
+ helpers in this module.
+
+ Generic over ``ResultT`` (the work body's return shape). The Redis
+ layer always reads and writes the row as JSON — the type parameter
+ only kicks in at the read-back seam where ``read_status`` is
+ parameterized by the caller (the admin route knows it expects a
+ ``DreamPassResult``; the polling internals don't need to).
+ """
+
+ job_id: str
+ user_id: str
+ kind: JobKind
+ state: JobState
+ started_at: datetime
+ updated_at: datetime
+ completed_at: datetime | None = None
+ current_phase: str | None = Field(
+ default=None,
+ description=(
+ "Free-form phase label set by the work body. Dream pass uses "
+ "'consolidate' | 'recombine' | 'sanitize' | 'apply'; nightly "
+ "batch reuses those plus 'ratification'; community rebuild "
+ "uses 'leiden' | 'summarize' | 'persist'."
+ ),
+ )
+ # When set, work body submitted to a provider's batch API; the
+ # eventual apply step lives in the batch result handler.
+ batch_id: str | None = None
+ # Populated at terminal state. ``result`` is the work body's return
+ # value typed as ``ResultT``; ``error`` is a short human-readable
+ # error string.
+ result: ResultT | None = None
+ error: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _key(kind: JobKind, job_id: str) -> str:
+ return f"{STATUS_KEY_PREFIX}:{kind}:{job_id}"
+
+
+async def write_initial_status(
+ *, kind: JobKind, job_id: str, user_id: str
+) -> JobStatus[Any]:
+ """Write the first ``state='queued'`` row at admin-trigger time.
+
+ Called from the admin endpoint before it returns 202. The work
+ body is responsible for flipping state to ``running`` when it
+ actually starts. ``result`` is ``None`` at this point — the type
+ parameter is only meaningful once the work body produces a result.
+ """
+ from backend.data.redis_client import get_redis_async
+
+ now = datetime.now(timezone.utc)
+ status: JobStatus[Any] = JobStatus(
+ job_id=job_id,
+ user_id=user_id,
+ kind=kind,
+ state="queued",
+ started_at=now,
+ updated_at=now,
+ )
+ redis = await get_redis_async()
+ await redis.set(
+ _key(kind, job_id),
+ status.model_dump_json(),
+ ex=STATUS_TTL_SECONDS,
+ )
+ return status
+
+
+async def update_status_phase(
+ *,
+ kind: JobKind,
+ job_id: str,
+ state: JobState | None = None,
+ current_phase: str | None = None,
+ batch_id: str | None = None,
+) -> JobStatus[Any] | None:
+ """Update one or more fields on an existing status row.
+
+ Returns the updated status, or ``None`` if the row is missing (TTL
+ expired or wrong job_id). Callers should treat ``None`` as a soft
+ failure — log it and continue rather than raising, since failing
+ to write a status update should never crash the work body itself.
+ """
+ existing = await read_status(kind=kind, job_id=job_id)
+ if existing is None:
+ logger.warning(
+ "Tried to update missing status row kind=%s job_id=%s",
+ kind,
+ job_id[:12],
+ )
+ return None
+
+ update: dict[str, Any] = {"updated_at": datetime.now(timezone.utc)}
+ if state is not None:
+ update["state"] = state
+ if current_phase is not None:
+ update["current_phase"] = current_phase
+ if batch_id is not None:
+ update["batch_id"] = batch_id
+
+ updated = existing.model_copy(update=update)
+ await _persist(updated)
+ return updated
+
+
+async def mark_complete(
+ *, kind: JobKind, job_id: str, result: BaseModel | dict[str, Any]
+) -> JobStatus[Any] | None:
+ """Transition to ``state='complete'`` with the work body's result.
+
+ Accepts either a Pydantic model (preferred — preserves typed
+ fields through JSON serialization) or a plain dict for legacy
+ callers that build the payload by hand.
+
+ Refuses terminal→terminal transitions (symmetric with
+ ``mark_errored``): once a row is complete or errored, its result
+ is authoritative and later writers must not rewrite it.
+ """
+ existing = await read_status(kind=kind, job_id=job_id)
+ if existing is None:
+ logger.warning(
+ "mark_complete: missing status row kind=%s job_id=%s",
+ kind,
+ job_id[:12],
+ )
+ return None
+ if existing.state in ("complete", "errored"):
+ logger.warning(
+ "mark_complete: refusing to overwrite terminal job kind=%s "
+ "job_id=%s state=%s",
+ kind,
+ job_id[:12],
+ existing.state,
+ )
+ return existing
+ serialized = result.model_dump() if isinstance(result, BaseModel) else result
+ now = datetime.now(timezone.utc)
+ updated = existing.model_copy(
+ update={
+ "state": "complete",
+ "updated_at": now,
+ "completed_at": now,
+ "result": serialized,
+ }
+ )
+ await _persist(updated)
+ return updated
+
+
+async def mark_errored(
+ *, kind: JobKind, job_id: str, error: str
+) -> JobStatus[Any] | None:
+ """Transition to ``state='errored'`` with a short error string.
+
+ Refuses to overwrite a job already in ``state='complete'`` — the
+ batch tail runs cleanup after ``mark_complete``, and a transient
+ error routed through the crash guard must not rewrite a completed
+ job (whose writes and billing landed) as errored.
+ """
+ existing = await read_status(kind=kind, job_id=job_id)
+ if existing is None:
+ logger.warning(
+ "mark_errored: missing status row kind=%s job_id=%s",
+ kind,
+ job_id[:12],
+ )
+ return None
+ if existing.state == "complete":
+ logger.warning(
+ "mark_errored: refusing to overwrite completed job kind=%s "
+ "job_id=%s (error was: %s)",
+ kind,
+ job_id[:12],
+ error[:200],
+ )
+ return existing
+ now = datetime.now(timezone.utc)
+ updated = existing.model_copy(
+ update={
+ "state": "errored",
+ "updated_at": now,
+ "completed_at": now,
+ "error": error[:2000], # cap; error strings can be huge stack traces
+ }
+ )
+ await _persist(updated)
+ return updated
+
+
+async def read_status(*, kind: JobKind, job_id: str) -> JobStatus[Any] | None:
+ """Fetch a status row by ``(kind, job_id)``. Returns ``None`` if missing.
+
+ Returns the row with ``result`` as the raw JSON-decoded value
+ (typically a ``dict`` from the work body's ``model_dump()``). Route
+ handlers re-validate the row through their kind-specific
+ ``JobStatus[T]`` subclass (e.g. ``DreamJobStatus``) at response
+ construction time — that walks the dict and types ``result`` per
+ the concrete subclass's parametrization, no extra read helper
+ needed.
+ """
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ raw = await redis.get(_key(kind, job_id))
+ if raw is None:
+ return None
+ if isinstance(raw, bytes):
+ raw = raw.decode("utf-8")
+ try:
+ return JobStatus[Any].model_validate(json.loads(raw))
+ except Exception:
+ logger.exception(
+ "Corrupted job status row at key=%s — treating as missing",
+ _key(kind, job_id),
+ )
+ return None
+
+
+# ---------------------------------------------------------------------------
+# Internals
+# ---------------------------------------------------------------------------
+
+
+async def _persist(status: JobStatus[Any]) -> None:
+ """Serialize + write with TTL. Single SET — no read-modify-write race."""
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ await redis.set(
+ _key(status.kind, status.job_id),
+ status.model_dump_json(),
+ ex=STATUS_TTL_SECONDS,
+ )
diff --git a/autogpt_platform/backend/backend/copilot/dream/job_status_test.py b/autogpt_platform/backend/backend/copilot/dream/job_status_test.py
new file mode 100644
index 0000000000..e73b71c2b9
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/job_status_test.py
@@ -0,0 +1,253 @@
+"""Tests for ``copilot.dream.job_status``."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from backend.copilot.dream.job_status import (
+ STATUS_KEY_PREFIX,
+ STATUS_TTL_SECONDS,
+ JobStatus,
+ mark_complete,
+ mark_errored,
+ read_status,
+ update_status_phase,
+ write_initial_status,
+)
+
+
+def fake_redis():
+ """In-memory dict-backed redis stub for the registry tests."""
+ store: dict[str, str] = {}
+
+ async def fake_set(key, value, ex=None):
+ store[key] = value
+ return True
+
+ async def fake_get(key):
+ return store.get(key)
+
+ redis_stub = AsyncMock()
+ redis_stub.set.side_effect = fake_set
+ redis_stub.get.side_effect = fake_get
+
+ async def fake_get_redis_async():
+ return redis_stub
+
+ with patch(
+ "backend.data.redis_client.get_redis_async",
+ side_effect=fake_get_redis_async,
+ ):
+ yield redis_stub, store
+
+
+class TestWriteInitialStatus:
+ @pytest.mark.asyncio
+ async def test_returns_status_in_queued_state(self, fake_redis):
+ status = await write_initial_status(
+ kind="nightly", job_id="job-1", user_id="user-x"
+ )
+ assert status.state == "queued"
+ assert status.job_id == "job-1"
+ assert status.user_id == "user-x"
+ assert status.kind == "nightly"
+ assert status.started_at == status.updated_at
+ assert status.completed_at is None
+
+ @pytest.mark.asyncio
+ async def test_persists_with_ttl(self, fake_redis):
+ redis, store = fake_redis
+ await write_initial_status(kind="dream_pass", job_id="job-2", user_id="user-y")
+ # Single SET with TTL — no MULTI/HSET dance
+ assert redis.set.await_count == 1
+ kwargs = redis.set.await_args.kwargs
+ assert kwargs["ex"] == STATUS_TTL_SECONDS
+
+ @pytest.mark.asyncio
+ async def test_uses_namespaced_key(self, fake_redis):
+ _, store = fake_redis
+ await write_initial_status(kind="rebuild", job_id="job-3", user_id="user-z")
+ assert f"{STATUS_KEY_PREFIX}:rebuild:job-3" in store
+
+
+class TestUpdateStatusPhase:
+ @pytest.mark.asyncio
+ async def test_updates_state_and_current_phase(self, fake_redis):
+ await write_initial_status(kind="dream_pass", job_id="j1", user_id="u")
+ updated = await update_status_phase(
+ kind="dream_pass",
+ job_id="j1",
+ state="running",
+ current_phase="consolidate",
+ )
+ assert updated is not None
+ assert updated.state == "running"
+ assert updated.current_phase == "consolidate"
+
+ @pytest.mark.asyncio
+ async def test_partial_update_preserves_other_fields(self, fake_redis):
+ """Updating just current_phase shouldn't reset state, batch_id, etc."""
+ await write_initial_status(kind="dream_pass", job_id="j1", user_id="u")
+ await update_status_phase(kind="dream_pass", job_id="j1", state="running")
+ await update_status_phase(
+ kind="dream_pass", job_id="j1", current_phase="recombine"
+ )
+ result = await read_status(kind="dream_pass", job_id="j1")
+ assert result is not None
+ assert result.state == "running" # not overwritten by second update
+ assert result.current_phase == "recombine"
+
+ @pytest.mark.asyncio
+ async def test_advances_updated_at(self, fake_redis):
+ await write_initial_status(kind="dream_pass", job_id="j1", user_id="u")
+ initial = await read_status(kind="dream_pass", job_id="j1")
+ assert initial is not None
+ # Wait a tick — datetime.now resolution on macOS is fine-grained enough
+ import asyncio
+
+ await asyncio.sleep(0.001)
+ updated = await update_status_phase(
+ kind="dream_pass", job_id="j1", current_phase="sanitize"
+ )
+ assert updated is not None
+ assert updated.updated_at > initial.updated_at
+
+ @pytest.mark.asyncio
+ async def test_returns_none_for_missing_row(self, fake_redis):
+ """A missing row is a soft failure — return None, don't raise.
+ Work bodies must not crash because a TTL expired mid-run."""
+ result = await update_status_phase(
+ kind="dream_pass", job_id="never-existed", state="running"
+ )
+ assert result is None
+
+ @pytest.mark.asyncio
+ async def test_sets_batch_id_when_provided(self, fake_redis):
+ await write_initial_status(kind="dream_pass", job_id="j1", user_id="u")
+ updated = await update_status_phase(
+ kind="dream_pass",
+ job_id="j1",
+ state="submitted",
+ batch_id="msgbatch_abc123",
+ )
+ assert updated is not None
+ assert updated.batch_id == "msgbatch_abc123"
+ assert updated.state == "submitted"
+
+
+class TestMarkComplete:
+ @pytest.mark.asyncio
+ async def test_transitions_to_complete_with_result(self, fake_redis):
+ await write_initial_status(kind="nightly", job_id="j1", user_id="u")
+ await update_status_phase(kind="nightly", job_id="j1", state="running")
+ updated = await mark_complete(
+ kind="nightly",
+ job_id="j1",
+ result={"dream": "ran", "ratification": "ran"},
+ )
+ assert updated is not None
+ assert updated.state == "complete"
+ assert updated.completed_at is not None
+ assert updated.result == {"dream": "ran", "ratification": "ran"}
+
+ @pytest.mark.asyncio
+ async def test_returns_none_for_missing_row(self, fake_redis):
+ result = await mark_complete(kind="nightly", job_id="ghost", result={})
+ assert result is None
+
+ @pytest.mark.asyncio
+ async def test_refuses_to_overwrite_errored_job(self, fake_redis):
+ """Terminal→terminal is rejected: a late mark_complete must not
+ rewrite a job that already failed (symmetric with mark_errored's
+ complete guard)."""
+ await write_initial_status(kind="dream_pass", job_id="j1", user_id="u")
+ await mark_errored(kind="dream_pass", job_id="j1", error="boom")
+ result = await mark_complete(kind="dream_pass", job_id="j1", result={"n": 1})
+ assert result is not None
+ assert result.state == "errored"
+ assert result.error == "boom"
+
+
+class TestMarkErrored:
+ @pytest.mark.asyncio
+ async def test_transitions_to_errored_with_short_message(self, fake_redis):
+ await write_initial_status(kind="dream_pass", job_id="j1", user_id="u")
+ updated = await mark_errored(
+ kind="dream_pass", job_id="j1", error="LLM returned non-JSON"
+ )
+ assert updated is not None
+ assert updated.state == "errored"
+ assert updated.error == "LLM returned non-JSON"
+
+ @pytest.mark.asyncio
+ async def test_caps_error_string_at_2000_chars(self, fake_redis):
+ """Stack traces can be huge; cap to keep Redis values reasonable."""
+ await write_initial_status(kind="dream_pass", job_id="j1", user_id="u")
+ huge_error = "x" * 5000
+ updated = await mark_errored(kind="dream_pass", job_id="j1", error=huge_error)
+ assert updated is not None
+ assert updated.error is not None
+ assert len(updated.error) == 2000
+
+ @pytest.mark.asyncio
+ async def test_refuses_to_overwrite_completed_job(self, fake_redis):
+ """A transient error routed through a crash guard after the success
+ tail must not rewrite a completed job (whose writes landed) as
+ errored."""
+ await write_initial_status(kind="dream_pass", job_id="j1", user_id="u")
+ await mark_complete(kind="dream_pass", job_id="j1", result={"n": 1})
+ result = await mark_errored(kind="dream_pass", job_id="j1", error="late blip")
+ assert result is not None
+ assert result.state == "complete"
+ assert result.result == {"n": 1}
+
+
+class TestReadStatus:
+ @pytest.mark.asyncio
+ async def test_returns_none_for_missing_key(self, fake_redis):
+ result = await read_status(kind="nightly", job_id="never-existed")
+ assert result is None
+
+ @pytest.mark.asyncio
+ async def test_roundtrips_through_redis(self, fake_redis):
+ """Pin the JSON serialization shape so a future Pydantic field
+ rename doesn't silently corrupt existing rows."""
+ await write_initial_status(kind="rebuild", job_id="j1", user_id="user-rt")
+ result = await read_status(kind="rebuild", job_id="j1")
+ assert result is not None
+ assert result.user_id == "user-rt"
+ assert result.kind == "rebuild"
+
+ @pytest.mark.asyncio
+ async def test_returns_none_for_corrupted_row(self, fake_redis):
+ """A corrupted row (e.g., missing required fields after a schema
+ change) should be treated as missing rather than crashing the
+ admin GET endpoint."""
+ redis, store = fake_redis
+ store[f"{STATUS_KEY_PREFIX}:nightly:j1"] = (
+ '{"this is": "not a valid JobStatus"}'
+ )
+ result = await read_status(kind="nightly", job_id="j1")
+ assert result is None
+
+
+class TestJobStatusModel:
+ def test_default_terminal_fields_are_none(self):
+ now = datetime.now(timezone.utc)
+ s = JobStatus(
+ job_id="x",
+ user_id="u",
+ kind="nightly",
+ state="queued",
+ started_at=now,
+ updated_at=now,
+ )
+ assert s.completed_at is None
+ assert s.result is None
+ assert s.error is None
+ assert s.batch_id is None
+ assert s.current_phase is None
diff --git a/autogpt_platform/backend/backend/copilot/dream/llm.py b/autogpt_platform/backend/backend/copilot/dream/llm.py
new file mode 100644
index 0000000000..3b35398649
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/llm.py
@@ -0,0 +1,318 @@
+"""Pydantic-typed LLM entry point for the dream pass.
+
+Thin wrapper on top of ``backend/util/llm/providers.call_provider``
+that adds the dream-specific concerns the shared helper deliberately
+doesn't own:
+
+ * **Pydantic schema validation** — converts the LLM's JSON response
+ into a typed instance of ``response_model`` and surfaces a clean
+ ``DreamLLMError`` if the model emits a shape that doesn't fit.
+ * **JSON prose-prefix recovery** — when a model wraps its JSON in
+ chain-of-thought ("Looking at the inputs, I need to ... {...}")
+ we extract the first balanced JSON object/array. The strengthened
+ system prompts in ``prompts.py`` cut down on prose preambles, but
+ this is the parser-level safety net.
+ * **Markdown fence stripping** — ``` ```json ... ``` ``` shows up
+ on some OpenRouter upstreams even with ``force_json_output``.
+ * **CompletionUsage** carrier — the orchestrator rolls these per
+ phase into a ``DreamPassUsage`` for the cost ledger.
+
+Why route through ``routing_kwargs_for_chat_transport()`` instead of
+pinning a provider:
+ * One control surface for every transport — local Ollama,
+ subscription Anthropic, direct Anthropic, and OpenRouter all
+ land at the same call site without per-transport branches here.
+ * ``response_format={"type":"json_object"}`` is supported across
+ OpenAI, OpenRouter, and Ollama (forced JSON works on every
+ transport this dispatcher accepts).
+ * The Anthropic batch path in the orchestrator (see
+ ``plans/idempotent-launching-moth.md`` component E) layers in
+ *below* this wrapper via ``call_provider(execution_mode="batch")``
+ when the transport supports it; this wrapper stays sync-only.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+from backend.copilot.transport_routing import routing_kwargs_for_chat_transport
+from backend.util.llm.providers import (
+ DEFAULT_REQUEST_TIMEOUT_SECONDS,
+ ProviderLiteral,
+ ProviderResponse,
+ call_provider,
+)
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class DreamLLMError(RuntimeError):
+ """Raised when a dream-pass LLM call cannot be parsed into the target schema."""
+
+
+class CompletionUsage(BaseModel):
+ """Token + cost telemetry from a single LLM call.
+
+ Carries the provider-reported cost when present (OpenRouter
+ surfaces ``usage.cost`` when the request asks for ``usage:
+ {"include": True}``); falls back to None when absent. Token counts
+ are always present.
+ """
+
+ model: str
+ input_tokens: int = 0
+ output_tokens: int = 0
+ cache_read_tokens: int = 0
+ cache_creation_tokens: int = 0
+ cost_usd: float | None = None
+
+
+class StructuredCompletion(BaseModel, Generic[T]):
+ """Return value of ``structured_completion``: parsed model + usage."""
+
+ value: T
+ usage: CompletionUsage
+
+
+async def structured_completion(
+ *,
+ model: str,
+ messages: list[dict[str, str]],
+ response_model: type[T],
+ temperature: float = 0.2,
+ max_output_tokens: int = 4096,
+) -> StructuredCompletion[T]:
+ """Call the LLM in JSON mode and parse into ``response_model``.
+
+ Returns a ``StructuredCompletion`` carrying both the parsed value
+ and a ``CompletionUsage`` block so the dream orchestrator can roll
+ token counts + cost up into a ``DreamPassUsage``.
+
+ Raises ``DreamLLMError`` if the response is empty, unparseable, or
+ fails Pydantic validation. Callers should treat that as "this
+ phase failed" — the orchestrator either skips downstream phases
+ or returns a partial result.
+ """
+ routing = routing_kwargs_for_chat_transport()
+ if not routing.api_key and routing.provider != "ollama":
+ raise DreamLLMError(_missing_api_key_message(routing.provider))
+
+ try:
+ response = await call_provider(
+ provider=routing.provider,
+ model=model,
+ api_key=routing.api_key,
+ messages=messages,
+ max_tokens=max_output_tokens,
+ temperature=temperature,
+ force_json_output=True,
+ timeout_seconds=DEFAULT_REQUEST_TIMEOUT_SECONDS,
+ # ``call_provider`` only honors ``ollama_host`` when
+ # ``provider="ollama"``; passing it on cloud transports is
+ # harmless. ``routing.base_url`` is the ``CHAT_BASE_URL``
+ # for local installs (e.g. ``http://localhost:11434/v1``);
+ # strip the OpenAI-compat ``/v1`` suffix because
+ # ``ollama.AsyncClient`` wants the raw host:port.
+ ollama_host=_normalize_ollama_host(routing.base_url),
+ )
+ except DreamLLMError:
+ raise
+ except Exception as exc:
+ raise DreamLLMError(f"LLM call failed: {type(exc).__name__}: {exc}") from exc
+
+ if not isinstance(response, ProviderResponse):
+ # ``call_provider`` only returns a non-ProviderResponse when the
+ # caller passed ``execution_mode="batch"`` (lands later). The
+ # dream's sync wrapper never opts in, so anything else is a bug.
+ raise DreamLLMError(
+ "structured_completion expected a sync ProviderResponse but got a "
+ f"{type(response).__name__} — execution_mode must stay 'sync' here."
+ )
+
+ usage = _usage_from_provider_response(response, model)
+
+ content = (response.content or "").strip()
+ if not content:
+ raise DreamLLMError("LLM returned empty content")
+
+ payload = _parse_json_with_prose_fallback(content)
+
+ try:
+ return StructuredCompletion(
+ value=response_model.model_validate(payload),
+ usage=usage,
+ )
+ except ValidationError as exc:
+ raise DreamLLMError(
+ f"LLM JSON did not match {response_model.__name__}: {exc}"
+ ) from exc
+
+
+def _usage_from_provider_response(
+ response: ProviderResponse, model: str
+) -> CompletionUsage:
+ """Convert a ``ProviderResponse`` into the dream's ``CompletionUsage``."""
+ return CompletionUsage(
+ model=model,
+ input_tokens=response.prompt_tokens,
+ output_tokens=response.completion_tokens,
+ cache_read_tokens=response.cache_read_tokens,
+ cache_creation_tokens=response.cache_creation_tokens,
+ cost_usd=response.cost_usd,
+ )
+
+
+def _parse_json_with_prose_fallback(content: str) -> object:
+ """Parse JSON from a model response, recovering from common preamble bugs.
+
+ Two layers of defense, in order:
+
+ 1. Strip a leading ``` ```json ... ``` ``` markdown fence (some
+ OpenRouter upstreams still emit them even with json_object mode).
+ 2. If ``json.loads`` fails, walk the string looking for the first
+ balanced ``{...}`` / ``[...]`` and re-parse that — handles the
+ "Looking at the inputs, I need to..." prose-prefix case.
+
+ Raises ``DreamLLMError`` if neither layer recovers a parseable
+ document, surfacing the first 200 chars of the offending content so
+ the orchestrator can log enough to debug what the model emitted.
+ """
+ cleaned = _strip_json_code_fence(content)
+ try:
+ return json.loads(cleaned)
+ except json.JSONDecodeError:
+ pass
+
+ extracted = _extract_first_json_object(cleaned)
+ if extracted is None:
+ raise DreamLLMError(
+ f"LLM returned non-JSON content — first 200 chars: {content[:200]}"
+ )
+ try:
+ return json.loads(extracted)
+ except json.JSONDecodeError as exc:
+ raise DreamLLMError(
+ f"LLM returned non-JSON content even after extraction: {exc} — "
+ f"first 200 chars: {content[:200]}"
+ ) from exc
+
+
+def _extract_first_json_object(content: str) -> str | None:
+ """Find the first balanced JSON object or array in ``content``.
+
+ Used as a fallback when the model wraps JSON in chain-of-thought
+ prose ("I'll analyze...\n\n{...}"). Returns ``None`` if no balanced
+ structure can be found. Naive but good enough: we scan for the
+ first ``{`` or ``[``, then walk forward counting braces/brackets
+ while respecting string literals so braces inside strings don't
+ throw off the count.
+ """
+ n = len(content)
+ start = -1
+ for i, ch in enumerate(content):
+ if ch in "{[":
+ start = i
+ break
+ if start == -1:
+ return None
+ open_ch = content[start]
+ close_ch = "}" if open_ch == "{" else "]"
+ depth = 0
+ in_string = False
+ escape = False
+ for i in range(start, n):
+ ch = content[i]
+ if in_string:
+ if escape:
+ escape = False
+ elif ch == "\\":
+ escape = True
+ elif ch == '"':
+ in_string = False
+ continue
+ if ch == '"':
+ in_string = True
+ continue
+ if ch == open_ch:
+ depth += 1
+ elif ch == close_ch:
+ depth -= 1
+ if depth == 0:
+ return content[start : i + 1]
+ return None
+
+
+def _strip_json_code_fence(content: str) -> str:
+ """Strip ```json ...``` or ``` ... ``` fences if the model added them.
+
+ Even with ``response_format={"type":"json_object"}``, some OpenRouter
+ upstreams (notably non-OpenAI models) still wrap output in markdown
+ fences. Strip them defensively so the parser sees pure JSON.
+ """
+ stripped = content.strip()
+ if not stripped.startswith("```"):
+ return content
+ first_newline = stripped.find("\n")
+ if first_newline == -1:
+ return content
+ body = stripped[first_newline + 1 :]
+ if body.endswith("```"):
+ body = body[:-3]
+ return body.strip()
+
+
+def _missing_api_key_message(provider: ProviderLiteral) -> str:
+ """Per-provider friendly error string for the no-API-key case.
+
+ Calls out the env var the operator needs to set + (for subscription)
+ the reason their OAuth token isn't sufficient. Surfaced to the user
+ via the JobStatus ``error`` field in the admin viz so they can
+ self-serve the fix without needing a logs dive.
+ """
+ if provider == "anthropic":
+ return (
+ "Anthropic API key not configured — set ANTHROPIC_API_KEY to "
+ "enable the dream pass under subscription / direct-Anthropic "
+ "mode. The Claude Code OAuth token cannot be used for direct "
+ "Messages API calls (see "
+ "docs/platform/copilot-local-llm.md#subscription-mode-caveat)."
+ )
+ if provider == "open_router":
+ return "OpenRouter API key not configured — set OPEN_ROUTER_API_KEY."
+ return f"No API key configured for dream pass provider={provider!r}."
+
+
+def _normalize_ollama_host(base_url: str | None) -> str:
+ """Turn ``CHAT_BASE_URL`` into the host string ollama.AsyncClient wants.
+
+ ``CHAT_BASE_URL`` for local installs points at the OpenAI-compat
+ surface — e.g. ``http://localhost:11434/v1``. Ollama's native
+ Python client takes the raw host (no ``/v1`` suffix); pass the
+ trailing path through and the client tries to POST to
+ ``/v1/api/generate`` and 404s. Strip path/query/fragment so the
+ client sees ``http://localhost:11434``.
+
+ Returns the platform default (``localhost:11434``) when no
+ ``base_url`` is provided so non-local callers get a sane fallback
+ even though ``call_provider`` ignores ``ollama_host`` outside the
+ ollama branch.
+ """
+ if not base_url:
+ return "localhost:11434"
+ from urllib.parse import urlparse, urlunparse
+
+ parsed = urlparse(base_url)
+ # ``urlparse("localhost:11434")`` mis-reports ``scheme="localhost"``
+ # because the parser treats the colon as a scheme separator when no
+ # ``//`` follows. Only ``http`` / ``https`` are real URL schemes
+ # this caller would emit; anything else means the input was a bare
+ # ``host:port`` — pass it through unchanged.
+ if parsed.scheme not in ("http", "https"):
+ return base_url
+ return urlunparse((parsed.scheme, parsed.netloc, "", "", "", ""))
diff --git a/autogpt_platform/backend/backend/copilot/dream/llm_test.py b/autogpt_platform/backend/backend/copilot/dream/llm_test.py
new file mode 100644
index 0000000000..9e8f38b427
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/llm_test.py
@@ -0,0 +1,390 @@
+"""Regression tests for dream-pass LLM JSON handling.
+
+The structured_completion wrapper requests JSON mode, but some OpenRouter
+upstreams (Claude family, certain Gemini variants) still wrap responses in
+```json ... ``` markdown fences. Without stripping them the dream pass
+aborts on the consolidation step with "Expecting value: line 1 column 1". This file pins
+the fence-stripper that prevents the regression.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from pydantic import BaseModel
+
+from backend.copilot.transport_routing import ProviderRoutingKwargs
+from backend.util.llm.providers import ProviderResponse
+
+from .llm import (
+ DreamLLMError,
+ _extract_first_json_object,
+ _normalize_ollama_host,
+ _strip_json_code_fence,
+ structured_completion,
+)
+
+
+ "raw,expected",
+ [
+ # No fence — content passes through.
+ ('{"a": 1}', '{"a": 1}'),
+ # Fence with ```json tag (most common Claude / Gemini wrap).
+ ('```json\n{"a": 1}\n```', '{"a": 1}'),
+ # Fence without language tag.
+ ('```\n{"a": 1}\n```', '{"a": 1}'),
+ # Trailing whitespace after closing fence.
+ ('```json\n{"a": 1}\n``` ', '{"a": 1}'),
+ # Multiline JSON inside fence — newlines inside the body preserved
+ # by the parser; only the fence delimiters are removed.
+ ('```json\n{\n "a": 1\n}\n```', '{\n "a": 1\n}'),
+ ],
+)
+def test_strip_json_code_fence(raw: str, expected: str):
+ assert _strip_json_code_fence(raw) == expected
+
+
+def test_strip_json_code_fence_leaves_unfenced_content_alone():
+ """A single-line response without fences must be returned verbatim."""
+ raw = '{"facts": [{"content": "test"}]}'
+ assert _strip_json_code_fence(raw) == raw
+
+
+def test_strip_json_code_fence_handles_only_opening_fence():
+ """If the model opened a fence but never closed it, drop the opener anyway
+ so json.loads at least gets a chance to parse the body."""
+ raw = '```json\n{"a": 1}'
+ assert _strip_json_code_fence(raw) == '{"a": 1}'
+
+
+def test_strip_json_code_fence_no_newline_after_opener_returns_raw():
+ """Pathological case — opening fence with no newline before content. We
+ leave it alone so json.loads surfaces the original parse error rather
+ than masking it with a guess."""
+ raw = "```json{}"
+ assert _strip_json_code_fence(raw) == raw
+
+
+ "raw,expected",
+ [
+ # JSON-only — start of string.
+ ('{"a": 1}', '{"a": 1}'),
+ # Prose prefix then JSON object.
+ ('I\'ll analyze the proposals...\n\n{"writes": []}', '{"writes": []}'),
+ # Prose prefix then JSON array.
+ ("Here we go:\n[1, 2, 3]\ntrailing", "[1, 2, 3]"),
+ # Nested braces inside the object — depth counted correctly.
+ (
+ 'Sure thing:\n{"a": {"b": {"c": 1}}, "d": 2}\nThanks!',
+ '{"a": {"b": {"c": 1}}, "d": 2}',
+ ),
+ # Braces inside strings must NOT throw off the depth count.
+ (
+ 'before {"text": "this has } and { inside", "ok": true} after',
+ '{"text": "this has } and { inside", "ok": true}',
+ ),
+ # Escaped quotes inside strings.
+ (
+ 'pre {"a": "\\"quoted\\"", "b": 1} post',
+ '{"a": "\\"quoted\\"", "b": 1}',
+ ),
+ ],
+)
+def test_extract_first_json_object(raw: str, expected: str):
+ assert _extract_first_json_object(raw) == expected
+
+
+def test_extract_first_json_object_returns_none_when_no_object():
+ assert _extract_first_json_object("just some prose without any braces") is None
+
+
+def test_extract_first_json_object_returns_none_when_unbalanced():
+ """An opening brace with no matching close — fallback returns None
+ instead of guessing, so the caller surfaces a real parse error
+ rather than silently truncating."""
+ assert _extract_first_json_object('{"a": "no closer') is None
+
+
+# ---------------------------------------------------------------------------
+# _normalize_ollama_host
+# ---------------------------------------------------------------------------
+
+
+ "base_url,expected",
+ [
+ # OpenAI-compat ``/v1`` suffix is stripped — ollama's native
+ # client wants the raw host.
+ ("http://localhost:11434/v1", "http://localhost:11434"),
+ ("https://ollama.lan:11434/v1/", "https://ollama.lan:11434"),
+ # No path → preserved.
+ ("http://localhost:11434", "http://localhost:11434"),
+ # Bare host:port (no scheme) — pass through unchanged.
+ ("localhost:11434", "localhost:11434"),
+ # Empty/None → fall back to default.
+ ("", "localhost:11434"),
+ (None, "localhost:11434"),
+ ],
+)
+def test_normalize_ollama_host(base_url: str | None, expected: str):
+ assert _normalize_ollama_host(base_url) == expected
+
+
+# ---------------------------------------------------------------------------
+# structured_completion delegation contract
+# ---------------------------------------------------------------------------
+
+
+class _SampleFact(BaseModel):
+ content: str
+ confidence: float
+
+
+class _SampleOutput(BaseModel):
+ facts: list[_SampleFact]
+
+
+def _openrouter_routing(api_key: str = "sk-or-test") -> ProviderRoutingKwargs:
+ return ProviderRoutingKwargs(
+ provider="open_router",
+ api_key=api_key,
+ base_url=None,
+ supports_flex=True,
+ cost_log_provider="open_router",
+ )
+
+
+def _ollama_routing(
+ base_url: str = "http://localhost:11434/v1",
+) -> ProviderRoutingKwargs:
+ return ProviderRoutingKwargs(
+ provider="ollama",
+ api_key="ollama-placeholder",
+ base_url=base_url,
+ supports_flex=False,
+ cost_log_provider="ollama",
+ )
+
+
+def _anthropic_routing(api_key: str = "") -> ProviderRoutingKwargs:
+ return ProviderRoutingKwargs(
+ provider="anthropic",
+ api_key=api_key,
+ base_url=None,
+ supports_flex=False,
+ cost_log_provider="anthropic",
+ )
+
+
+class TestStructuredCompletionDelegation:
+ """Confirms ``structured_completion`` delegates to ``call_provider``
+ with kwargs derived from ``routing_kwargs_for_chat_transport()`` and
+ converts ``ProviderResponse`` → the dream's typed Pydantic +
+ ``CompletionUsage`` shape, regardless of which transport is active."""
+
+ @pytest.mark.asyncio
+ async def test_delegates_to_call_provider_with_openrouter_args(self):
+ fake_response = ProviderResponse(
+ content='{"facts": [{"content": "x", "confidence": 0.9}]}',
+ prompt_tokens=12,
+ completion_tokens=4,
+ cost_usd=0.0042,
+ )
+ call_provider_mock = AsyncMock(return_value=fake_response)
+
+ with patch(
+ "backend.copilot.dream.llm.routing_kwargs_for_chat_transport",
+ return_value=_openrouter_routing(),
+ ), patch("backend.copilot.dream.llm.call_provider", call_provider_mock):
+ result = await structured_completion(
+ model="anthropic/claude-sonnet-4-6",
+ messages=[
+ {"role": "system", "content": "you are helpful"},
+ {"role": "user", "content": "give me a fact"},
+ ],
+ response_model=_SampleOutput,
+ temperature=0.3,
+ max_output_tokens=512,
+ )
+
+ # Result shape is the dream's typed wrapper
+ assert isinstance(result.value, _SampleOutput)
+ assert len(result.value.facts) == 1
+ assert result.value.facts[0].confidence == 0.9
+ # Cost + tokens flow through
+ assert result.usage.cost_usd == 0.0042
+ assert result.usage.input_tokens == 12
+ assert result.usage.output_tokens == 4
+ # Delegation routed to OpenRouter with the right knobs
+ call_provider_mock.assert_awaited_once()
+ kwargs = call_provider_mock.call_args.kwargs
+ assert kwargs["provider"] == "open_router"
+ assert kwargs["api_key"] == "sk-or-test"
+ assert kwargs["model"] == "anthropic/claude-sonnet-4-6"
+ assert kwargs["max_tokens"] == 512
+ assert kwargs["temperature"] == 0.3
+ # JSON-mode must be requested — without it OpenRouter→Claude
+ # falls back to free-form text and our prose parser does extra
+ # work.
+ assert kwargs["force_json_output"] is True
+
+ @pytest.mark.asyncio
+ async def test_routes_to_ollama_under_local_transport(self):
+ """Local transport: dispatch becomes ``provider="ollama"`` with
+ ``ollama_host`` derived from ``CHAT_BASE_URL`` (sans the
+ OpenAI-compat ``/v1`` suffix). Closes the dream-pass-on-local
+ hole identified in the local-AI memory integration."""
+ fake_response = ProviderResponse(
+ content='{"facts": [{"content": "y", "confidence": 0.5}]}',
+ prompt_tokens=8,
+ completion_tokens=3,
+ )
+ call_provider_mock = AsyncMock(return_value=fake_response)
+
+ with patch(
+ "backend.copilot.dream.llm.routing_kwargs_for_chat_transport",
+ return_value=_ollama_routing("http://localhost:11434/v1"),
+ ), patch("backend.copilot.dream.llm.call_provider", call_provider_mock):
+ result = await structured_completion(
+ model="hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M",
+ messages=[{"role": "user", "content": "hi"}],
+ response_model=_SampleOutput,
+ )
+
+ assert isinstance(result.value, _SampleOutput)
+ kwargs = call_provider_mock.call_args.kwargs
+ assert kwargs["provider"] == "ollama"
+ # Empty api_key is fine for ollama; the placeholder ChatConfig
+ # would have set is passed through verbatim.
+ assert kwargs["api_key"] == "ollama-placeholder"
+ # ``/v1`` is the OpenAI-compat suffix; ollama's native client
+ # wants the raw host, so the wrapper strips it.
+ assert kwargs["ollama_host"] == "http://localhost:11434"
+
+ @pytest.mark.asyncio
+ async def test_raises_when_no_openrouter_key(self):
+ with patch(
+ "backend.copilot.dream.llm.routing_kwargs_for_chat_transport",
+ return_value=_openrouter_routing(api_key=""),
+ ):
+ with pytest.raises(DreamLLMError, match="OPEN_ROUTER_API_KEY"):
+ await structured_completion(
+ model="anthropic/claude-sonnet-4-6",
+ messages=[{"role": "user", "content": "hi"}],
+ response_model=_SampleOutput,
+ )
+
+ @pytest.mark.asyncio
+ async def test_raises_with_subscription_hint_when_no_anthropic_key(self):
+ """Subscription mode lands on ``provider="anthropic"`` with an
+ empty api_key (the Claude Code OAuth token can't authenticate
+ against the Messages API per the Feb-2026 Anthropic ToS). The
+ wrapper must surface a friendly error pointing operators at
+ the ``ANTHROPIC_API_KEY`` env var instead of leaking a 401."""
+ with patch(
+ "backend.copilot.dream.llm.routing_kwargs_for_chat_transport",
+ return_value=_anthropic_routing(api_key=""),
+ ):
+ with pytest.raises(DreamLLMError, match="ANTHROPIC_API_KEY") as exc_info:
+ await structured_completion(
+ model="anthropic/claude-sonnet-4-6",
+ messages=[{"role": "user", "content": "hi"}],
+ response_model=_SampleOutput,
+ )
+ # The hint is user-facing self-serve documentation — the anchor must
+ # match the real heading slug in docs/platform/copilot-local-llm.md
+ # ("### Subscription mode caveat").
+ assert "docs/platform/copilot-local-llm.md#subscription-mode-caveat" in str(
+ exc_info.value
+ )
+
+ @pytest.mark.asyncio
+ async def test_empty_content_raises_dream_llm_error(self):
+ fake = ProviderResponse(content="", prompt_tokens=1, completion_tokens=0)
+ with patch(
+ "backend.copilot.dream.llm.routing_kwargs_for_chat_transport",
+ return_value=_openrouter_routing(),
+ ), patch(
+ "backend.copilot.dream.llm.call_provider",
+ new=AsyncMock(return_value=fake),
+ ):
+ with pytest.raises(DreamLLMError, match="empty"):
+ await structured_completion(
+ model="x",
+ messages=[{"role": "user", "content": "hi"}],
+ response_model=_SampleOutput,
+ )
+
+ @pytest.mark.asyncio
+ async def test_invalid_pydantic_shape_raises_dream_llm_error(self):
+ """Pydantic validation lives in this wrapper, not in
+ ``call_provider`` — pin the boundary so a future schema change
+ doesn't accidentally drop validation."""
+ fake = ProviderResponse(
+ content='{"facts": [{"content": 1.0, "confidence": "wrong"}]}',
+ prompt_tokens=1,
+ completion_tokens=1,
+ )
+ with patch(
+ "backend.copilot.dream.llm.routing_kwargs_for_chat_transport",
+ return_value=_openrouter_routing(),
+ ), patch(
+ "backend.copilot.dream.llm.call_provider",
+ new=AsyncMock(return_value=fake),
+ ):
+ with pytest.raises(DreamLLMError, match="did not match"):
+ await structured_completion(
+ model="x",
+ messages=[{"role": "user", "content": "hi"}],
+ response_model=_SampleOutput,
+ )
+
+ @pytest.mark.asyncio
+ async def test_provider_failure_is_wrapped_in_dream_llm_error(self):
+ """``call_provider`` raising must surface as ``DreamLLMError`` so
+ the orchestrator's per-phase failure handler triggers — not as a
+ raw RuntimeError that crashes the pass."""
+ with patch(
+ "backend.copilot.dream.llm.routing_kwargs_for_chat_transport",
+ return_value=_openrouter_routing(),
+ ), patch(
+ "backend.copilot.dream.llm.call_provider",
+ new=AsyncMock(side_effect=RuntimeError("upstream 502")),
+ ):
+ with pytest.raises(DreamLLMError, match="upstream 502"):
+ await structured_completion(
+ model="x",
+ messages=[{"role": "user", "content": "hi"}],
+ response_model=_SampleOutput,
+ )
+
+ @pytest.mark.asyncio
+ async def test_recovers_from_prose_prefixed_json(self):
+ """Even when the strengthened system prompts hold, occasional
+ model outputs still slip prose before the JSON. The wrapper's
+ balanced-brace fallback should recover so the phase doesn't
+ fail unnecessarily."""
+ fake = ProviderResponse(
+ content=(
+ "Looking at the inputs, I need to ...\n\n"
+ '{"facts": [{"content": "recovered", "confidence": 1.0}]}'
+ ),
+ prompt_tokens=10,
+ completion_tokens=20,
+ )
+ with patch(
+ "backend.copilot.dream.llm.routing_kwargs_for_chat_transport",
+ return_value=_openrouter_routing(),
+ ), patch(
+ "backend.copilot.dream.llm.call_provider",
+ new=AsyncMock(return_value=fake),
+ ):
+ result = await structured_completion(
+ model="x",
+ messages=[{"role": "user", "content": "hi"}],
+ response_model=_SampleOutput,
+ )
+ assert result.value.facts[0].content == "recovered"
diff --git a/autogpt_platform/backend/backend/copilot/dream/locks.py b/autogpt_platform/backend/backend/copilot/dream/locks.py
new file mode 100644
index 0000000000..1297492f67
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/locks.py
@@ -0,0 +1,240 @@
+"""Redis SETNX advisory lock for the dream pass.
+
+One in-flight dream per user at a time. Bails if the lock is already
+held — the caller surfaces that as ``skipped=True`` in
+``DreamPassResult`` so the admin UI can render "another dream is
+already running" rather than failing.
+
+The lock value is a per-acquire ownership token (uuid4); every release
+is a single-key Lua compare-and-delete on that token and every TTL
+extend is a single-key Lua compare-and-extend. A blind delete (or a
+blind ``SET XX``) is NOT safe: if a pass outlives its TTL (slow sync
+pass, or a batch callback landing inside the thin margin between the
+batch lifetime and ``BATCH_LOCK_TTL_SECONDS``), the key may already
+belong to a *newer* pass — deleting or overwriting it would break that
+pass's ownership and let a third concurrent pass start. Prod Redis runs
+in cluster mode, so everything here stays single-key: SET NX plus
+single-key Lua scripts, no multi-key scripts and no cross-key
+transactions.
+
+TTL is transport-aware per ``dream/p0-spec.md`` §13:
+ * Cloud (OpenRouter / Anthropic direct): 1800 s (30 min)
+ * Local (Ollama / vLLM / LM Studio): 7200 s (2 hr)
+The longer local TTL accommodates CPU-only inference timelines for
+the three-phase pipeline.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from contextlib import asynccontextmanager
+from typing import Any, cast
+
+logger = logging.getLogger(__name__)
+
+DREAM_LOCK_KEY_PREFIX = "dream:inflight:"
+
+# Default TTLs. Callers can override per-transport when local.
+DEFAULT_LOCK_TTL_SECONDS = 1800
+LOCAL_LOCK_TTL_SECONDS = 7200
+
+# Batch path: the dream pass is async and stays in flight up to the
+# BatchExecutor's MAX_BATCH_LIFETIME_SECONDS (24h). The lock must outlive the
+# whole batch so apply — which runs hours later in the callback — is still
+# covered by "one dream per user". The batch callback releases it on
+# terminal/failure; this TTL is only the crash backstop, kept > 24h so the
+# lock can't expire before the executor times the batch out.
+BATCH_LOCK_TTL_SECONDS = 24 * 60 * 60 + 600
+
+# Compare-and-delete: only the holder whose token still matches the stored
+# value may delete the key. Single-key Lua routes on Redis Cluster.
+_UNLOCK_SCRIPT = (
+ 'if redis.call("get", KEYS[1]) == ARGV[1] then '
+ 'return redis.call("del", KEYS[1]) else return 0 end'
+)
+
+# Compare-and-extend: only the holder whose token still matches the stored
+# value may stretch the TTL. Same single-key Lua pattern as
+# ``_UNLOCK_SCRIPT`` — a blind ``SET XX`` would overwrite a *newer* pass's
+# token (and TTL) when our lock expired and was re-acquired mid-pass.
+_EXTEND_SCRIPT = (
+ 'if redis.call("get", KEYS[1]) == ARGV[1] then '
+ 'return redis.call("expire", KEYS[1], ARGV[2]) else return 0 end'
+)
+
+
+def _lock_key(user_id: str) -> str:
+ return f"{DREAM_LOCK_KEY_PREFIX}{user_id}"
+
+
+class DreamLockHeld(Exception):
+ """Raised when another process is already running a dream for this user."""
+
+ def __init__(self, user_id: str) -> None:
+ super().__init__(f"Dream pass already in flight for user {user_id[:12]}")
+ self.user_id = user_id
+
+
+class DreamLockHandle:
+ """Yielded by ``dream_lock``. Lets the async batch path hand lock
+ ownership to the callback chain: ``extend`` stretches the TTL to the
+ batch lifetime and ``disown`` stops the context manager from releasing on
+ exit, so the lock survives until ``release_dream_lock`` runs in the batch
+ callback (or the TTL expires).
+
+ ``token`` is the ownership value stored at the lock key. Release is a
+ compare-and-delete on it, so the batch path persists the token alongside
+ its per-pass state (the input bundle) for the callback to read back hours
+ later."""
+
+ def __init__(self, redis, key: str, user_id: str, token: str) -> None:
+ self._redis = redis
+ self._key = key
+ self.user_id = user_id
+ self.token = token
+ self.release_on_exit = True
+
+ def disown(self) -> None:
+ self.release_on_exit = False
+
+ async def extend(self, ttl_seconds: int) -> None:
+ """Stretch the lock TTL only while the key still holds our token.
+
+ Single-key Lua compare-and-extend (mirrors ``_UNLOCK_SCRIPT``): a
+ blind ``SET XX`` succeeds against ANY existing value, so if our
+ lock expired and a newer pass re-acquired the key, it would
+ hijack that pass's token and stretch its TTL. The compare also
+ refuses to recreate an expired key — an expired lock is never
+ resurrected — and returns 0 so we can log that ownership was
+ lost.
+ """
+ # ``cast`` because redis-py's stubs type ``eval`` as a bare
+ # ``str`` — same workaround as the release paths below.
+ extended = await cast(
+ "Any",
+ self._redis.eval(
+ _EXTEND_SCRIPT, 1, self._key, self.token, str(ttl_seconds)
+ ),
+ )
+ if not extended:
+ logger.warning(
+ "Dream lock for user %s expired before extend — "
+ "not resurrecting it; another pass may already own the key",
+ self.user_id[:12],
+ )
+
+
+@asynccontextmanager
+async def dream_lock(user_id: str, ttl_seconds: int = DEFAULT_LOCK_TTL_SECONDS):
+ """Acquire a per-user advisory lock for the dream pass.
+
+ Raises ``DreamLockHeld`` if another process holds the lock.
+ The lock is released on context exit via compare-and-delete on this
+ acquire's ownership token — a late exit can't delete a newer pass's
+ lock. On crash the TTL provides a fallback release after
+ ``ttl_seconds``.
+ """
+ # Lazy import so this module is cheap to import in tests that mock redis.
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ key = _lock_key(user_id)
+ token = str(uuid.uuid4())
+
+ acquired = await redis.set(key, token, nx=True, ex=ttl_seconds)
+ if not acquired:
+ raise DreamLockHeld(user_id)
+
+ logger.info("Acquired dream lock for user %s (ttl=%ds)", user_id[:12], ttl_seconds)
+ handle = DreamLockHandle(redis, key, user_id, token)
+ try:
+ yield handle
+ finally:
+ if not handle.release_on_exit:
+ # Disowned by the batch path — the callback (or the TTL) owns
+ # release now, so the lock spans the async batch lifetime.
+ logger.info("Dream lock for user %s handed to batch callback", user_id[:12])
+ else:
+ try:
+ # ``cast`` because redis-py's stubs type ``eval`` as a bare
+ # ``str`` — same workaround as ``data/redis_helpers.py``.
+ deleted = await cast("Any", redis.eval(_UNLOCK_SCRIPT, 1, key, token))
+ if deleted:
+ logger.debug("Released dream lock for user %s", user_id[:12])
+ else:
+ logger.warning(
+ "Dream lock for user %s no longer held our token at "
+ "release — expired and re-acquired by another pass; "
+ "leaving the new holder's lock alone",
+ user_id[:12],
+ )
+ except Exception:
+ # If release fails, the TTL will eventually clear the lock.
+ logger.warning(
+ "Failed to release dream lock for user %s — TTL %ds will clear",
+ user_id[:12],
+ ttl_seconds,
+ exc_info=True,
+ )
+
+
+async def read_dream_lock_token(user_id: str) -> str | None:
+ """Current holder's ownership token, or None when no lock is held.
+
+ The batch path calls this while still holding the lock (at input-bundle
+ persist time) to capture its own token; the batch callback — running
+ hours later in a different process — passes it back to
+ ``release_dream_lock`` for the compare-and-delete.
+ """
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ raw = await redis.get(_lock_key(user_id))
+ if raw is None:
+ return None
+ if isinstance(raw, bytes):
+ return raw.decode("utf-8")
+ return str(raw)
+
+
+async def release_dream_lock(user_id: str, token: str | None) -> None:
+ """Release a disowned dream lock (batch path) once the pass terminates.
+
+ Compare-and-delete on ``token``: a blind delete is NOT safe here — the
+ callback can land close to (or after) the lock's TTL, by which point the
+ key may already belong to a newer pass, and deleting it would let a
+ third concurrent pass start. When the token is unknown (per-pass state
+ expired or corrupted) the key is left for its TTL to clear: the batch
+ lock outlives the input bundle's 24h TTL by only ~10 min, so a short
+ extra lockout beats releasing someone else's lock. A failed delete
+ likewise falls back to the TTL.
+ """
+ if token is None:
+ logger.warning(
+ "No ownership token for disowned dream lock of user %s — "
+ "leaving it for the TTL to clear",
+ user_id[:12],
+ )
+ return
+ from backend.data.redis_client import get_redis_async
+
+ try:
+ redis = await get_redis_async()
+ deleted = await cast(
+ "Any", redis.eval(_UNLOCK_SCRIPT, 1, _lock_key(user_id), token)
+ )
+ if deleted:
+ logger.debug("Released disowned dream lock for user %s", user_id[:12])
+ else:
+ logger.warning(
+ "Disowned dream lock for user %s no longer held our token — "
+ "expired and re-acquired; leaving the new holder's lock alone",
+ user_id[:12],
+ )
+ except Exception:
+ logger.warning(
+ "Failed to release disowned dream lock for user %s — TTL will clear",
+ user_id[:12],
+ exc_info=True,
+ )
diff --git a/autogpt_platform/backend/backend/copilot/dream/locks_test.py b/autogpt_platform/backend/backend/copilot/dream/locks_test.py
new file mode 100644
index 0000000000..11f7b76a9c
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/locks_test.py
@@ -0,0 +1,260 @@
+"""Redis SETNX lock for the dream pass — token-owned compare-and-delete."""
+
+from __future__ import annotations
+
+import uuid
+from unittest.mock import AsyncMock
+
+import pytest
+
+from .locks import (
+ BATCH_LOCK_TTL_SECONDS,
+ DEFAULT_LOCK_TTL_SECONDS,
+ DreamLockHeld,
+ dream_lock,
+ read_dream_lock_token,
+ release_dream_lock,
+)
+
+
+def _redis_mock(**overrides) -> AsyncMock:
+ redis = AsyncMock()
+ redis.set = AsyncMock(return_value=True)
+ redis.eval = AsyncMock(return_value=1)
+ redis.delete = AsyncMock(return_value=1)
+ for name, value in overrides.items():
+ setattr(redis, name, value)
+ return redis
+
+
+def _patch_redis(mocker, redis: AsyncMock) -> None:
+ mocker.patch(
+ "backend.data.redis_client.get_redis_async",
+ AsyncMock(return_value=redis),
+ )
+
+
+async def test_dream_lock_stores_uuid_token_and_releases_via_compare_and_delete(
+ mocker,
+):
+ redis = _redis_mock()
+ _patch_redis(mocker, redis)
+
+ async with dream_lock("user-a", ttl_seconds=DEFAULT_LOCK_TTL_SECONDS) as handle:
+ token = handle.token
+
+ # Acquire: SETNX with a uuid4 ownership token as the value, not "1".
+ redis.set.assert_awaited_once()
+ args, kwargs = redis.set.call_args
+ assert args[0] == "dream:inflight:user-a"
+ assert args[1] == token
+ assert uuid.UUID(token) # parseable uuid, unique per acquire
+ assert kwargs == {"nx": True, "ex": DEFAULT_LOCK_TTL_SECONDS}
+ # Release: single-key Lua compare-and-delete on OUR token — never a
+ # blind DEL that could take out a newer pass's lock.
+ redis.eval.assert_awaited_once()
+ eval_args = redis.eval.call_args.args
+ assert eval_args[1] == 1 # single key — routes on Redis Cluster
+ assert eval_args[2] == "dream:inflight:user-a"
+ assert eval_args[3] == token
+ redis.delete.assert_not_awaited()
+
+
+async def test_dream_lock_raises_when_already_held(mocker):
+ redis = _redis_mock(set=AsyncMock(return_value=False)) # SETNX lost
+ _patch_redis(mocker, redis)
+
+ with pytest.raises(DreamLockHeld):
+ async with dream_lock("user-b"):
+ pytest.fail("should not enter the body when lock is held")
+
+ # And critically: we don't try to delete a key that wasn't ours.
+ redis.eval.assert_not_awaited()
+ redis.delete.assert_not_awaited()
+
+
+async def test_dream_lock_swallows_release_failure(mocker, caplog):
+ redis = _redis_mock(eval=AsyncMock(side_effect=Exception("redis down")))
+ _patch_redis(mocker, redis)
+
+ # The TTL is the fallback release, so a release failure must not
+ # propagate up to the orchestrator.
+ async with dream_lock("user-c"):
+ pass
+
+ assert "Failed to release dream lock" in caplog.text
+
+
+async def test_release_on_exit_skips_delete_when_token_mismatch(mocker, caplog):
+ """A late exit (pass outlived its TTL, key re-acquired by a newer pass)
+ must leave the new holder's lock alone — the Lua compare returns 0."""
+ redis = _redis_mock(eval=AsyncMock(return_value=0))
+ _patch_redis(mocker, redis)
+
+ async with dream_lock("user-d"):
+ pass
+
+ redis.eval.assert_awaited_once()
+ redis.delete.assert_not_awaited()
+ assert "no longer held our token" in caplog.text
+
+
+async def test_dream_lock_disown_skips_release_and_extends_ttl(mocker):
+ """The batch path extends the TTL to the batch window and disowns the
+ lock, so the context manager must NOT delete it on exit — the batch
+ callback (or the TTL) owns release."""
+ redis = _redis_mock()
+ _patch_redis(mocker, redis)
+
+ async with dream_lock("user-e") as handle:
+ await handle.extend(BATCH_LOCK_TTL_SECONDS)
+ handle.disown()
+
+ # extend is a single-key Lua compare-and-extend on OUR token — never a
+ # blind SET XX that could overwrite a newer pass's token, and never a
+ # plain SET that would resurrect an expired lock.
+ redis.set.assert_awaited_once() # the acquire only
+ redis.eval.assert_awaited_once() # the extend; disown skips the unlock
+ eval_args = redis.eval.call_args.args
+ assert 'redis.call("expire"' in eval_args[0]
+ assert eval_args[1] == 1 # single key — routes on Redis Cluster
+ assert eval_args[2] == "dream:inflight:user-e"
+ assert eval_args[3] == handle.token
+ assert eval_args[4] == str(BATCH_LOCK_TTL_SECONDS)
+ redis.delete.assert_not_awaited()
+
+
+async def test_extend_warns_when_lock_already_expired(mocker, caplog):
+ """The compare-and-extend returns 0 when the key expired — extend must
+ surface that (ownership is lost) instead of silently recreating the
+ lock."""
+ redis = _redis_mock(eval=AsyncMock(return_value=0))
+ _patch_redis(mocker, redis)
+
+ async with dream_lock("user-f") as handle:
+ await handle.extend(BATCH_LOCK_TTL_SECONDS)
+ handle.disown()
+
+ assert "expired before extend" in caplog.text
+
+
+async def test_extend_leaves_lock_reacquired_by_newer_pass_untouched(mocker, caplog):
+ """Our lock expired mid-pass and a NEWER pass re-acquired the key with
+ its own token. extend must leave that token AND its TTL alone — the old
+ SET XX would have clobbered both, locking the user out for the batch
+ window under a hijacked token."""
+ key = "dream:inflight:user-m"
+ store: dict[str, str] = {}
+ ttls: dict[str, int] = {}
+
+ async def fake_set(k, value, nx=False, ex=None):
+ if nx and k in store:
+ return None
+ store[k] = value
+ if ex is not None:
+ ttls[k] = ex
+ return True
+
+ async def fake_eval(script, numkeys, k, *argv):
+ if store.get(k) != argv[0]:
+ return 0
+ if 'redis.call("expire"' in script:
+ ttls[k] = int(argv[1])
+ return 1
+ store.pop(k, None)
+ return 1
+
+ redis = _redis_mock(
+ set=AsyncMock(side_effect=fake_set),
+ eval=AsyncMock(side_effect=fake_eval),
+ )
+ _patch_redis(mocker, redis)
+
+ async with dream_lock("user-m") as handle:
+ # Simulate expiry + re-acquire by a newer pass before our extend.
+ store[key] = "tok-newer-pass"
+ ttls[key] = DEFAULT_LOCK_TTL_SECONDS
+ await handle.extend(BATCH_LOCK_TTL_SECONDS)
+ handle.disown()
+
+ assert store[key] == "tok-newer-pass" # token not clobbered
+ assert ttls[key] == DEFAULT_LOCK_TTL_SECONDS # TTL not stretched
+ assert "expired before extend" in caplog.text
+
+
+async def test_release_dream_lock_compare_and_deletes_with_token(mocker):
+ redis = _redis_mock()
+ _patch_redis(mocker, redis)
+
+ await release_dream_lock("user-g", "tok-g")
+
+ redis.eval.assert_awaited_once()
+ eval_args = redis.eval.call_args.args
+ assert eval_args[1] == 1
+ assert eval_args[2] == "dream:inflight:user-g"
+ assert eval_args[3] == "tok-g"
+ redis.delete.assert_not_awaited()
+
+
+async def test_release_skips_delete_when_token_mismatch(mocker, caplog):
+ """A batch callback landing after the lock expired and was re-acquired
+ must not release the new holder's lock — the compare fails and the key
+ is left alone."""
+ redis = _redis_mock(eval=AsyncMock(return_value=0))
+ _patch_redis(mocker, redis)
+
+ await release_dream_lock("user-h", "stale-token")
+
+ redis.eval.assert_awaited_once()
+ redis.delete.assert_not_awaited()
+ assert "no longer held our token" in caplog.text
+
+
+async def test_release_without_token_leaves_lock_for_ttl(mocker, caplog):
+ """When the token is unknown (input bundle TTL'd out / corrupted) the
+ release must not blind-delete — the TTL clears the key instead."""
+ redis = _redis_mock()
+ _patch_redis(mocker, redis)
+
+ await release_dream_lock("user-i", None)
+
+ redis.eval.assert_not_awaited()
+ redis.delete.assert_not_awaited()
+ assert "leaving it for the TTL" in caplog.text
+
+
+async def test_release_dream_lock_swallows_redis_failure(mocker, caplog):
+ redis = _redis_mock(eval=AsyncMock(side_effect=Exception("redis down")))
+ _patch_redis(mocker, redis)
+
+ await release_dream_lock("user-j", "tok-j")
+
+ assert "Failed to release disowned dream lock" in caplog.text
+
+
+async def test_read_dream_lock_token_decodes_current_holder(mocker):
+ redis = _redis_mock(get=AsyncMock(return_value=b"tok-bytes"))
+ _patch_redis(mocker, redis)
+
+ assert await read_dream_lock_token("user-k") == "tok-bytes"
+ redis.get.assert_awaited_once_with("dream:inflight:user-k")
+
+
+async def test_read_dream_lock_token_none_when_unheld(mocker):
+ redis = _redis_mock(get=AsyncMock(return_value=None))
+ _patch_redis(mocker, redis)
+
+ assert await read_dream_lock_token("user-l") is None
diff --git a/autogpt_platform/backend/backend/copilot/dream/model_pricing.py b/autogpt_platform/backend/backend/copilot/dream/model_pricing.py
new file mode 100644
index 0000000000..23365826ab
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/model_pricing.py
@@ -0,0 +1,156 @@
+"""Per-model USD pricing for dream-pass cost calculation.
+
+Used as a fallback when the provider doesn't include a real cost on
+``usage.cost`` (direct OpenAI / Anthropic APIs) or when computing the
+batch-discounted equivalent. Rates are USD per 1M tokens.
+
+The hard-coded table is intentionally narrow — only the models the
+dream pass actually calls today. Adding a model requires updating this
+file; we'd rather fail loud on an unknown model than silently bill at
+zero. The OpenRouter path bypasses this entirely because OpenRouter
+already returns the real spot price as ``usage.cost``.
+
+When the Anthropic + OpenAI direct batch paths land (P0.1), the
+``batch_discount`` factor in ``ExecutionPathDiscount`` is multiplied
+into the computed cost so the savings flow through to the user via the
+shared cost ledger.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Literal
+
+from pydantic.dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ModelRate:
+ """Rate card for one model.
+
+ All four token classes priced separately. ``None`` for a class
+ means the model doesn't support it (e.g. no prompt cache).
+ """
+
+ input_per_mtok: float
+ output_per_mtok: float
+ cache_read_per_mtok: float | None = None
+ cache_write_per_mtok: float | None = None
+
+
+# Rate card. Last updated 2026-05. Source: provider pricing pages.
+# Keep alphabetized by provider, then by model.
+_RATES: dict[str, ModelRate] = {
+ # ---- Anthropic ----
+ # Claude Opus 4.7
+ "claude-opus-4-7": ModelRate(
+ input_per_mtok=15.0,
+ output_per_mtok=75.0,
+ cache_read_per_mtok=1.5,
+ cache_write_per_mtok=18.75,
+ ),
+ "anthropic/claude-opus-4.7": ModelRate(
+ input_per_mtok=15.0,
+ output_per_mtok=75.0,
+ cache_read_per_mtok=1.5,
+ cache_write_per_mtok=18.75,
+ ),
+ # Claude Sonnet 4.6
+ "claude-sonnet-4-6": ModelRate(
+ input_per_mtok=3.0,
+ output_per_mtok=15.0,
+ cache_read_per_mtok=0.3,
+ cache_write_per_mtok=3.75,
+ ),
+ "anthropic/claude-sonnet-4.6": ModelRate(
+ input_per_mtok=3.0,
+ output_per_mtok=15.0,
+ cache_read_per_mtok=0.3,
+ cache_write_per_mtok=3.75,
+ ),
+ # Claude Haiku 4.5
+ "claude-haiku-4-5-20251001": ModelRate(
+ input_per_mtok=1.0,
+ output_per_mtok=5.0,
+ cache_read_per_mtok=0.1,
+ cache_write_per_mtok=1.25,
+ ),
+ # ---- OpenAI ----
+ "gpt-5": ModelRate(input_per_mtok=10.0, output_per_mtok=30.0),
+ "gpt-4o": ModelRate(
+ input_per_mtok=2.5,
+ output_per_mtok=10.0,
+ cache_read_per_mtok=1.25,
+ ),
+}
+
+
+ExecutionPath = Literal["sync_baseline", "anthropic_batch", "openai_batch"]
+
+
+# Both Anthropic and OpenAI batch APIs offer a 50% discount on the
+# normal rate for asynchronous batch processing. We pass that savings
+# through to the user — recorded in the cost ledger so the discount is
+# auditable.
+_BATCH_DISCOUNTS: dict[ExecutionPath, float] = {
+ "sync_baseline": 0.0,
+ "anthropic_batch": 0.5,
+ "openai_batch": 0.5,
+}
+
+
+def execution_path_discount(path: ExecutionPath) -> float:
+ """Discount factor in [0.0, 1.0] applied to the base rate.
+
+ Returns 0.5 for batch (50% off), 0.0 for sync_baseline.
+ """
+ return _BATCH_DISCOUNTS.get(path, 0.0)
+
+
+def compute_cost_usd(
+ *,
+ model: str,
+ input_tokens: int,
+ output_tokens: int,
+ cache_read_tokens: int = 0,
+ cache_creation_tokens: int = 0,
+ execution_path: ExecutionPath = "sync_baseline",
+) -> float | None:
+ """Compute USD cost for a single LLM call from the rate card.
+
+ Returns None when the model isn't in the rate card — caller should
+ log a warning and treat the cost as unknown rather than silently
+ bill at zero. When the provider already supplied a real cost on
+ ``usage.cost`` the caller should prefer that value over this
+ fallback; this function is the synthetic estimate when no spot
+ price is available.
+
+ ``execution_path`` discount is applied at the very end so the
+ return value is the *final* user-facing cost, not the pre-discount
+ base.
+ """
+ rate = _RATES.get(model) or _RATES.get(model.lower())
+ if rate is None:
+ logger.warning(
+ "dream model_pricing: no rate card for model %r — cost unknown", model
+ )
+ return None
+
+ input_cost = (input_tokens / 1_000_000.0) * rate.input_per_mtok
+ output_cost = (output_tokens / 1_000_000.0) * rate.output_per_mtok
+
+ cache_read_cost = 0.0
+ if cache_read_tokens and rate.cache_read_per_mtok is not None:
+ cache_read_cost = (cache_read_tokens / 1_000_000.0) * rate.cache_read_per_mtok
+
+ cache_write_cost = 0.0
+ if cache_creation_tokens and rate.cache_write_per_mtok is not None:
+ cache_write_cost = (
+ cache_creation_tokens / 1_000_000.0
+ ) * rate.cache_write_per_mtok
+
+ base = input_cost + output_cost + cache_read_cost + cache_write_cost
+ discount = execution_path_discount(execution_path)
+ return base * (1.0 - discount)
diff --git a/autogpt_platform/backend/backend/copilot/dream/model_pricing_test.py b/autogpt_platform/backend/backend/copilot/dream/model_pricing_test.py
new file mode 100644
index 0000000000..9fce66cad8
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/model_pricing_test.py
@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import pytest
+
+from .model_pricing import ModelRate, compute_cost_usd, execution_path_discount
+
+
+def test_unknown_model_returns_none():
+ """Unknown model → None so callers can flag the cost as unknown
+ rather than silently bill at zero."""
+ assert (
+ compute_cost_usd(
+ model="totally-fake-model-xyz", input_tokens=100, output_tokens=50
+ )
+ is None
+ )
+
+
+def test_known_model_basic_math():
+ """Sonnet 4.6: $3/M input + $15/M output. Spot check arithmetic."""
+ cost = compute_cost_usd(
+ model="claude-sonnet-4-6", input_tokens=1_000_000, output_tokens=1_000_000
+ )
+ assert cost == pytest.approx(3.0 + 15.0)
+
+
+def test_cache_tokens_priced_separately():
+ """Cache reads + cache writes use their own per-Mtok rates."""
+ # Sonnet 4.6 cache_read=$0.30/M, cache_write=$3.75/M
+ cost = compute_cost_usd(
+ model="claude-sonnet-4-6",
+ input_tokens=0,
+ output_tokens=0,
+ cache_read_tokens=1_000_000,
+ cache_creation_tokens=1_000_000,
+ )
+ assert cost == pytest.approx(0.30 + 3.75)
+
+
+ "path,expected_discount",
+ [
+ ("sync_baseline", 0.0),
+ ("anthropic_batch", 0.5),
+ ("openai_batch", 0.5),
+ ],
+)
+def test_execution_path_discount(path, expected_discount):
+ assert execution_path_discount(path) == expected_discount
+
+
+def test_batch_discount_applied_to_final_cost():
+ """Batch path multiplies the rate-card cost by (1 - 0.5) = 0.5."""
+ sync = compute_cost_usd(
+ model="claude-sonnet-4-6",
+ input_tokens=1_000_000,
+ output_tokens=1_000_000,
+ execution_path="sync_baseline",
+ )
+ batch = compute_cost_usd(
+ model="claude-sonnet-4-6",
+ input_tokens=1_000_000,
+ output_tokens=1_000_000,
+ execution_path="anthropic_batch",
+ )
+ assert sync == pytest.approx(18.0)
+ assert batch == pytest.approx(9.0)
+ assert batch == pytest.approx(sync * 0.5)
+
+
+def test_model_with_no_cache_pricing_ignores_cache_tokens():
+ """gpt-5 has no cache_*_per_mtok — cache tokens contribute zero."""
+ cost = compute_cost_usd(
+ model="gpt-5",
+ input_tokens=0,
+ output_tokens=0,
+ cache_read_tokens=1_000_000,
+ cache_creation_tokens=1_000_000,
+ )
+ assert cost == pytest.approx(0.0)
+
+
+def test_modelrate_is_frozen():
+ """ModelRate is frozen so a typo in calling code can't mutate the
+ shared rate card by accident."""
+ rate = ModelRate(input_per_mtok=1.0, output_per_mtok=2.0)
+ with pytest.raises(Exception):
+ rate.input_per_mtok = 99.0 # type: ignore[misc]
+
+
+def test_model_lookup_is_case_insensitive():
+ """We don't want a registry miss because a caller passes the model
+ name with the wrong case."""
+ a = compute_cost_usd(model="claude-sonnet-4-6", input_tokens=100, output_tokens=100)
+ b = compute_cost_usd(model="CLAUDE-SONNET-4-6", input_tokens=100, output_tokens=100)
+ assert a is not None and b is not None
+ assert a == pytest.approx(b)
diff --git a/autogpt_platform/backend/backend/copilot/dream/nightly_batch.py b/autogpt_platform/backend/backend/copilot/dream/nightly_batch.py
new file mode 100644
index 0000000000..520469398c
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/nightly_batch.py
@@ -0,0 +1,224 @@
+"""Nightly batch-submit cron body — fans out per-user batch-family work.
+
+One per-user APScheduler cron (``dream_nightly_batch_{user_id}``)
+fires at user-local 03:00 daily and calls :func:`run_nightly_batch_submit`.
+The function sequentially invokes each enabled "batch-family"
+submitter:
+
+ * Dream pass (P0.2) — consolidate / recombine / sanitize / apply
+ * Ratification supersession sweep (P0.4) — clean up tentatives that
+ aged past the grace period without earning a warm-context hit
+ * Future P2 dedup / P3 self-model refresh / P4 scenario pre-warm /
+ P11 threat rehearsal land as additional submitters here
+
+Each submitter is fast to ENQUEUE (seconds) but may take up to ~1h to
+COMPLETE when running against a real batch provider (Anthropic /
+OpenAI batch API). The submitters fire in sequence at cron time; their
+batch results land asynchronously via the separate
+``copilot_batch_executor`` poller service that dispatches by
+``custom_id`` to per-stage apply handlers.
+
+Until the real batch providers land (currently scaffolded with
+``NotImplementedError`` stubs in ``dream/batch/``), the dream pass
+runs end-to-end via ``execute_dream_pass`` (sync_baseline path —
+30s LLM thinking + seconds-long apply). The function shape is the
+same either way.
+
+Concurrency model (per ``dream/p0-spec.md`` §5 and the architecture
+plan): LLM-thinking phases stay concurrent with user writes (they're
+read-only against the user's graph); only the apply / writeback step
+of each submitter briefly acquires the per-user lock and queues user
+writes for the seconds it holds.
+
+One pre-flight billing check runs at the top so a single
+``nightly_id`` correlates all per-submitter cost log rows for this
+pass.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid as uuidlib
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from .billing import check_dream_budget
+from .ratification import RatificationResult, run_ratification_pass
+from .schemas import DreamPassResult
+
+logger = logging.getLogger(__name__)
+
+
+class NightlyBatchResult(BaseModel):
+ """Structured outcome of one nightly-batch-submit pass.
+
+ Surfaced via the scheduler wrapper + admin endpoint so we can
+ audit "what fired tonight for this user" without scraping logs.
+ """
+
+ user_id: str
+ nightly_id: str = Field(
+ description=(
+ "UUID correlating every per-submitter cost-log row for "
+ "this pass. The dream pass and ratification supersession "
+ "sweep all share this id."
+ )
+ )
+ started_at: datetime
+ completed_at: datetime | None = None
+ elapsed_seconds: float | None = None
+
+ # Per-submitter results. ``None`` means the submitter was skipped
+ # (flag off, no input, etc.). Each Pydantic model gets its own
+ # field rather than a generic dict so consumers (admin viz,
+ # AgentProbe scorers) don't have to dispatch on runtime type.
+ dream: DreamPassResult | None = None
+ ratification: RatificationResult | None = None
+
+ # True when the dream submitter took a provider batch path: the
+ # submit pass only ENQUEUED phase 1, and the dream's apply step
+ # lands asynchronously via the BatchExecutor's dream callbacks up
+ # to ~24h later (correlated by ``dream.pass_id``). The fan-out
+ # itself is complete — this envelope is the terminal record of the
+ # SUBMIT pass, so consumers must not read the dream counts as
+ # final when this flag is set.
+ dream_in_flight: bool = False
+
+ # Top-level outcome.
+ skipped: bool = False
+ skip_reason: str | None = None
+ error: str | None = None
+
+
+async def run_nightly_batch_submit(user_id: str) -> NightlyBatchResult:
+ """Fan out per-user nightly batch-family submissions, in order.
+
+ Today the order is dream-pass → ratification-supersession-sweep.
+ Future additions land as new sequential calls between these two
+ (e.g. P2 dedup goes before dream so the dream pass operates on a
+ deduped fact set; P11 threat rehearsal goes after ratification).
+
+ Returns immediately after the last submitter returns. In
+ sync_baseline mode that's ~30s+ (each submitter inlines its
+ apply); in real-batch mode it's ~seconds (each submitter just
+ enqueues to the provider's batch API).
+
+ Never raises — top-level failures are captured in
+ ``NightlyBatchResult.error`` so the scheduler wrapper can log
+ without retry-storming the cron.
+ """
+ nightly_id = str(uuidlib.uuid4())
+ started_at = datetime.now(timezone.utc)
+
+ # One pre-flight billing check for the whole pass. Per-submitter
+ # cost logs (written by each submitter's own `record_phase_cost`
+ # calls) all reference the same ``nightly_id`` via the
+ # ``dream_pass_id`` field on PlatformCostLog rows. This means a
+ # paywalled / over-budget user costs us one LD lookup + one
+ # Redis read for the night, not one per submitter.
+ budget_ok, budget_skip = await check_dream_budget(user_id)
+ if not budget_ok:
+ completed_at = datetime.now(timezone.utc)
+ elapsed = (completed_at - started_at).total_seconds()
+ if budget_skip == "rate_limit_unavailable":
+ return NightlyBatchResult(
+ user_id=user_id,
+ nightly_id=nightly_id,
+ started_at=started_at,
+ completed_at=completed_at,
+ elapsed_seconds=elapsed,
+ error=f"billing: {budget_skip}",
+ )
+ return NightlyBatchResult(
+ user_id=user_id,
+ nightly_id=nightly_id,
+ started_at=started_at,
+ completed_at=completed_at,
+ elapsed_seconds=elapsed,
+ skipped=True,
+ skip_reason=budget_skip or "insufficient_credits",
+ )
+
+ result = NightlyBatchResult(
+ user_id=user_id, nightly_id=nightly_id, started_at=started_at
+ )
+
+ # Dream pass submitter. Per-submitter failure stays isolated —
+ # a crashed dream pass doesn't block the ratification sweep
+ # (ratification operates on already-written tentatives from
+ # previous passes, not tonight's failed one).
+ try:
+ from .orchestrator import execute_dream_pass
+
+ result.dream = await execute_dream_pass(user_id)
+ if result.dream.error:
+ logger.warning(
+ "Nightly batch %s: dream submitter errored for user %s: %s",
+ nightly_id,
+ user_id[:12],
+ result.dream.error,
+ )
+ elif (
+ not result.dream.skipped and result.dream.execution_path != "sync_baseline"
+ ):
+ result.dream_in_flight = True
+ except Exception as exc:
+ logger.exception(
+ "Nightly batch %s: dream submitter crashed for user %s",
+ nightly_id,
+ user_id[:12],
+ )
+ # Capture but continue to the next submitter — sweep is
+ # independent.
+ result.error = f"dream: {exc}"
+
+ # Ratification supersession sweep. With the sync hit-hook landed
+ # (see ``ratification_hits.try_ratify_on_hit``), the nightly
+ # sweep primarily handles supersession of unratified tentatives
+ # past their grace period — promotions happen inline at
+ # retrieval-hit time.
+ try:
+ result.ratification = await run_ratification_pass(user_id)
+ if result.ratification.error:
+ logger.warning(
+ "Nightly batch %s: ratification sweep errored for user %s: %s",
+ nightly_id,
+ user_id[:12],
+ result.ratification.error,
+ )
+ except Exception as exc:
+ logger.exception(
+ "Nightly batch %s: ratification sweep crashed for user %s",
+ nightly_id,
+ user_id[:12],
+ )
+ # Append rather than overwrite so a dream failure plus a
+ # ratification failure both surface.
+ prev = result.error or ""
+ result.error = (prev + " | " if prev else "") + f"ratification: {exc}"
+
+ completed_at = datetime.now(timezone.utc)
+ result.completed_at = completed_at
+ result.elapsed_seconds = (completed_at - started_at).total_seconds()
+ logger.info(
+ "Nightly batch %s done for user %s in %.1fs: dream=%s ratification=%s",
+ nightly_id,
+ user_id[:12],
+ result.elapsed_seconds,
+ _summary(result.dream),
+ _summary(result.ratification),
+ )
+ return result
+
+
+def _summary(submitter_result: Any) -> str:
+ """One-word summary of a submitter's outcome for the nightly log line."""
+ if submitter_result is None:
+ return "skipped"
+ if getattr(submitter_result, "error", None):
+ return "errored"
+ if getattr(submitter_result, "skipped", False):
+ return "no-input"
+ return "ran"
diff --git a/autogpt_platform/backend/backend/copilot/dream/nightly_batch_test.py b/autogpt_platform/backend/backend/copilot/dream/nightly_batch_test.py
new file mode 100644
index 0000000000..68a485d3f4
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/nightly_batch_test.py
@@ -0,0 +1,312 @@
+"""Nightly batch submitter tests.
+
+Contracts pinned here:
+
+ 1. **One pre-flight billing check** for the whole pass — paywalled
+ or over-cap users skip the entire fan-out before any submitter
+ runs.
+ 2. **Per-submitter failure isolation** — a crashed dream submitter
+ still lets the ratification sweep run; both errors surface in
+ ``NightlyBatchResult.error``.
+ 3. **Sequential ordering** — dream first, then ratification.
+ 4. **Result shape** — ``NightlyBatchResult`` carries per-submitter
+ Pydantic models (not generic dicts) so admin viz + AgentProbe
+ can read them without runtime type dispatch.
+ 5. **``nightly_id`` correlation** — every submitter call shares
+ the same id so per-LLM-call cost log rows join back to one pass.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Literal
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from backend.copilot.dream.ratification import RatificationResult
+from backend.copilot.dream.schemas import DreamPassResult
+
+from . import nightly_batch
+from .nightly_batch import run_nightly_batch_submit
+
+
+def _dream_result(
+ *,
+ error: str | None = None,
+ skipped: bool = False,
+ execution_path: Literal[
+ "sync_baseline", "anthropic_batch", "openai_batch"
+ ] = "sync_baseline",
+) -> DreamPassResult:
+ return DreamPassResult(
+ user_id="u",
+ pass_id="dream-1",
+ execution_path=execution_path,
+ started_at=datetime.now(timezone.utc),
+ completed_at=datetime.now(timezone.utc),
+ elapsed_seconds=0.5,
+ error=error,
+ skipped=skipped,
+ skip_reason="no_input" if skipped else None,
+ consolidated_count=2 if not (error or skipped) else 0,
+ proposal_count=1 if not (error or skipped) else 0,
+ )
+
+
+def _ratification_result(
+ *, error: str | None = None, ratified: int = 0, superseded: int = 0
+) -> RatificationResult:
+ now = datetime.now(timezone.utc)
+ return RatificationResult(
+ user_id="u",
+ started_at=now,
+ completed_at=now,
+ examined_count=ratified + superseded,
+ ratified_count=ratified,
+ superseded_count=superseded,
+ per_edge_errors=[],
+ error=error,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Pre-flight billing
+# ---------------------------------------------------------------------------
+
+
+async def test_paywalled_user_skips_entire_fanout_no_submitters_run():
+ """One pre-flight billing check — paywalled user costs us one LD
+ lookup + one Redis read for the night, not one per submitter."""
+ dream_spy = AsyncMock()
+ rat_spy = AsyncMock()
+ with patch.object(
+ nightly_batch,
+ "check_dream_budget",
+ new=AsyncMock(return_value=(False, "insufficient_credits")),
+ ), patch(
+ "backend.copilot.dream.orchestrator.execute_dream_pass", new=dream_spy
+ ), patch.object(
+ nightly_batch, "run_ratification_pass", new=rat_spy
+ ):
+ result = await run_nightly_batch_submit("u")
+
+ assert result.skipped is True
+ assert result.skip_reason == "insufficient_credits"
+ dream_spy.assert_not_called()
+ rat_spy.assert_not_called()
+
+
+async def test_redis_brownout_during_budget_check_surfaces_as_error_not_skipped():
+ """Rate-limit-unavailable → orchestrator fails closed; surfaces as
+ error (so the cron retries next tick), NOT skipped."""
+ with patch.object(
+ nightly_batch,
+ "check_dream_budget",
+ new=AsyncMock(return_value=(False, "rate_limit_unavailable")),
+ ):
+ result = await run_nightly_batch_submit("u")
+
+ assert result.skipped is False
+ assert result.error is not None
+ assert "rate_limit_unavailable" in result.error
+
+
+# ---------------------------------------------------------------------------
+# Happy path — both submitters run
+# ---------------------------------------------------------------------------
+
+
+async def test_happy_path_runs_dream_then_ratification_sharing_nightly_id():
+ dream_spy = AsyncMock(return_value=_dream_result())
+ rat_spy = AsyncMock(return_value=_ratification_result(ratified=3, superseded=1))
+ with patch.object(
+ nightly_batch,
+ "check_dream_budget",
+ new=AsyncMock(return_value=(True, None)),
+ ), patch(
+ "backend.copilot.dream.orchestrator.execute_dream_pass", new=dream_spy
+ ), patch.object(
+ nightly_batch, "run_ratification_pass", new=rat_spy
+ ):
+ result = await run_nightly_batch_submit("u")
+
+ assert result.skipped is False
+ assert result.error is None
+ assert result.dream_in_flight is False
+ assert result.dream is not None
+ assert result.dream.consolidated_count == 2
+ assert result.ratification is not None
+ assert result.ratification.ratified_count == 3
+ assert result.ratification.superseded_count == 1
+ # All submitters consult the same nightly_id implicitly via the
+ # NightlyBatchResult — assertion is shape, not collation, since
+ # the cost log layer reads it through PlatformCostLog metadata.
+ assert result.nightly_id # uuid set
+
+
+async def test_submitters_called_in_documented_order_dream_then_ratification():
+ """Order matters for future stages (e.g. P2 dedup before dream,
+ P4 pre-warm after). Pin the order so future re-orderings are
+ intentional."""
+ call_order: list[str] = []
+ dream_spy = AsyncMock(
+ side_effect=lambda *_a, **_kw: call_order.append("dream") or _dream_result()
+ )
+ rat_spy = AsyncMock(
+ side_effect=lambda *_a, **_kw: call_order.append("rat")
+ or _ratification_result()
+ )
+ with patch.object(
+ nightly_batch,
+ "check_dream_budget",
+ new=AsyncMock(return_value=(True, None)),
+ ), patch(
+ "backend.copilot.dream.orchestrator.execute_dream_pass", new=dream_spy
+ ), patch.object(
+ nightly_batch, "run_ratification_pass", new=rat_spy
+ ):
+ await run_nightly_batch_submit("u")
+
+ assert call_order == ["dream", "rat"]
+
+
+# ---------------------------------------------------------------------------
+# Per-submitter failure isolation
+# ---------------------------------------------------------------------------
+
+
+async def test_dream_crash_still_lets_ratification_sweep_run():
+ """A crashed dream submitter must not block the ratification
+ sweep — they operate on disjoint tentative-edge populations."""
+ rat_spy = AsyncMock(return_value=_ratification_result(superseded=2))
+ with patch.object(
+ nightly_batch,
+ "check_dream_budget",
+ new=AsyncMock(return_value=(True, None)),
+ ), patch(
+ "backend.copilot.dream.orchestrator.execute_dream_pass",
+ new=AsyncMock(side_effect=RuntimeError("dream boom")),
+ ), patch.object(
+ nightly_batch, "run_ratification_pass", new=rat_spy
+ ):
+ result = await run_nightly_batch_submit("u")
+
+ assert result.error is not None
+ assert "dream" in result.error
+ assert "dream boom" in result.error
+ # Ratification still ran.
+ assert result.ratification is not None
+ assert result.ratification.superseded_count == 2
+
+
+async def test_both_submitters_failing_concatenates_errors():
+ """Both submitters can fail independently; both errors surface."""
+ with patch.object(
+ nightly_batch,
+ "check_dream_budget",
+ new=AsyncMock(return_value=(True, None)),
+ ), patch(
+ "backend.copilot.dream.orchestrator.execute_dream_pass",
+ new=AsyncMock(side_effect=RuntimeError("dream boom")),
+ ), patch.object(
+ nightly_batch,
+ "run_ratification_pass",
+ new=AsyncMock(side_effect=RuntimeError("rat boom")),
+ ):
+ result = await run_nightly_batch_submit("u")
+
+ assert result.error is not None
+ assert "dream" in result.error
+ assert "ratification" in result.error
+
+
+async def test_dream_internal_error_propagates_via_result_dream_error_not_top_level():
+ """A dream pass that returns ``DreamPassResult(error=...)``
+ (internal failure caught by orchestrator) does NOT set
+ ``NightlyBatchResult.error`` — it surfaces in ``.dream.error``
+ so the cron-wrapper log line can distinguish 'submitter crashed
+ in nightly batch glue' from 'submitter ran and reported failure'."""
+ dream_spy = AsyncMock(return_value=_dream_result(error="phase 1 LLM down"))
+ rat_spy = AsyncMock(return_value=_ratification_result())
+ with patch.object(
+ nightly_batch,
+ "check_dream_budget",
+ new=AsyncMock(return_value=(True, None)),
+ ), patch(
+ "backend.copilot.dream.orchestrator.execute_dream_pass", new=dream_spy
+ ), patch.object(
+ nightly_batch, "run_ratification_pass", new=rat_spy
+ ):
+ result = await run_nightly_batch_submit("u")
+
+ # Top-level error stays None — submitter reported its own error.
+ # The admin ``*_with_status`` wrapper folds sub-result errors into
+ # the JobStatus row at status-write time.
+ assert result.error is None
+ assert result.dream is not None
+ assert result.dream.error == "phase 1 LLM down"
+ # Ratification still ran.
+ assert result.ratification is not None
+
+
+# ---------------------------------------------------------------------------
+# Async batch-path handoff
+# ---------------------------------------------------------------------------
+
+
+async def test_batch_path_dream_sets_dream_in_flight():
+ """A dream submitter that took a provider batch path only ENQUEUED
+ its pass — ``dream_in_flight`` flags that the apply step lands
+ asynchronously via the BatchExecutor, so envelope consumers (the
+ admin wrapper marks the row complete with this envelope) don't
+ read the dream counts as final."""
+ dream_spy = AsyncMock(return_value=_dream_result(execution_path="anthropic_batch"))
+ rat_spy = AsyncMock(return_value=_ratification_result())
+ with patch.object(
+ nightly_batch,
+ "check_dream_budget",
+ new=AsyncMock(return_value=(True, None)),
+ ), patch(
+ "backend.copilot.dream.orchestrator.execute_dream_pass", new=dream_spy
+ ), patch.object(
+ nightly_batch, "run_ratification_pass", new=rat_spy
+ ):
+ result = await run_nightly_batch_submit("u")
+
+ assert result.dream_in_flight is True
+ assert result.error is None
+
+
+async def test_skipped_or_errored_batch_path_dream_is_not_in_flight():
+ """A batch-path dream that was SKIPPED (lock held, no input) or
+ returned an error result has nothing pending with the provider —
+ the in-flight flag must stay unset."""
+ for dream in (
+ _dream_result(execution_path="anthropic_batch", skipped=True),
+ _dream_result(execution_path="anthropic_batch", error="submit failed"),
+ ):
+ with patch.object(
+ nightly_batch,
+ "check_dream_budget",
+ new=AsyncMock(return_value=(True, None)),
+ ), patch(
+ "backend.copilot.dream.orchestrator.execute_dream_pass",
+ new=AsyncMock(return_value=dream),
+ ), patch.object(
+ nightly_batch,
+ "run_ratification_pass",
+ new=AsyncMock(return_value=_ratification_result()),
+ ):
+ result = await run_nightly_batch_submit("u")
+
+ assert result.dream_in_flight is False
diff --git a/autogpt_platform/backend/backend/copilot/dream/orchestrator.py b/autogpt_platform/backend/backend/copilot/dream/orchestrator.py
new file mode 100644
index 0000000000..ec39f171e3
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/orchestrator.py
@@ -0,0 +1,658 @@
+"""Three-phase dream-pass orchestrator (sync_baseline path).
+
+Walks a user's recent memory window through the consolidate → recombine
+→ sanitize pipeline, then applies the sanitizer's ``DreamOperations``
+to Graphiti + Postgres.
+
+Slice 1 of P-0 deliberately bypasses Anthropic batch — every phase
+calls the OpenRouter-fronted OpenAI-compat client. The batch path
+slots in below this layer (`routing.py` returns ``"batch"``) in a
+future PR.
+
+The orchestrator never raises out — every failure becomes a
+``DreamPassResult`` with ``error`` set, so the admin trigger always
+gets a structured response back.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid as uuidlib
+from datetime import datetime, timezone
+
+from backend.copilot.config import ChatConfig
+from backend.util.feature_flag import Flag, is_feature_enabled
+
+from .apply import apply_operations
+from .billing import check_dream_budget, record_phase_cost
+from .fetch import DreamInput, gather_dream_input
+from .llm import (
+ CompletionUsage,
+ DreamLLMError,
+ StructuredCompletion,
+ structured_completion,
+)
+from .locks import (
+ BATCH_LOCK_TTL_SECONDS,
+ DEFAULT_LOCK_TTL_SECONDS,
+ LOCAL_LOCK_TTL_SECONDS,
+ DreamLockHandle,
+ DreamLockHeld,
+ dream_lock,
+)
+from .model_pricing import compute_cost_usd, execution_path_discount
+from .prompts import (
+ MAX_DEMOTIONS_PER_PASS,
+ MAX_PROPOSALS_PER_PASS,
+ MAX_WRITES_PER_PASS,
+ build_consolidate_prompt,
+ build_recombine_prompt,
+ build_sanitize_prompt,
+)
+from .routing import ExecutionPath, resolve_dream_execution_path
+from .schemas import (
+ ConsolidationOutput,
+ DreamOperations,
+ DreamOperationsSnapshot,
+ DreamPassResult,
+ DreamPassUsage,
+ PhaseUsage,
+ RecombinationOutput,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# Per-step temperature + max output token budgets. Spec ref:
+# ``dream/p0-spec.md`` §2. Named by what the step does rather than its
+# position; the consolidation→recombination→sanitization order is
+# enforced by the call graph below.
+CONSOLIDATE_TEMP = 0.2
+RECOMBINE_TEMP = 0.9
+SANITIZE_TEMP = 0.0
+CONSOLIDATE_MAX_TOKENS = 4096
+# Recombine + sanitize emit list-heavy JSON (up to 30 writes + 20
+# proposals + 10 demotions, each with uuid arrays). At 8192 the
+# response truncates mid-array and the JSON-balanced-brace extractor
+# returns None, failing the whole phase. 16384 covers worst-case +
+# headroom; cost impact is bounded by the per-phase caps anyway.
+RECOMBINE_MAX_TOKENS = 16384
+SANITIZE_MAX_TOKENS = 16384
+
+# Entity invalidation is the most destructive op the sanitizer can emit:
+# each one single-hop demotes EVERY :RELATES_TO edge on the entity, so a
+# hub entity multiplies the blast radius far past the demotion caps. We
+# cap the *count* of invalidations per pass here; the per-entity edge
+# blast radius is bounded by the ``DREAM_PASS_INVALIDATE_ENTITY`` LD flag
+# (staged rollout, off by default) plus the single-hop-only guarantee in
+# ``invalidate_entity_direct_neighbors`` (no multi-hop propagation).
+# Deliberately NOT degree-aware — fetching entity degrees is async graph
+# work that doesn't belong in this sync clamp.
+MAX_ENTITY_INVALIDATIONS_PER_PASS = 2
+
+
+def _resolve_lock_ttl(transport_is_local: bool) -> int:
+ return LOCAL_LOCK_TTL_SECONDS if transport_is_local else DEFAULT_LOCK_TTL_SECONDS
+
+
+def _clamp_operations(
+ ops: DreamOperations,
+ active_fact_count: int,
+ known_fact_uuids: set[str] | None = None,
+) -> DreamOperations:
+ """Hard-trim oversized phase 3 outputs.
+
+ Phase 3's prompt asks for these caps but the model can still
+ over-emit. The orchestrator enforces them in code so apply.py
+ never writes more than the policy allows.
+
+ Demotions carry a second ceiling — 5% of the active fact set — so a
+ single pass can never wipe a meaningful fraction of a user's memory
+ even if the absolute ``MAX_DEMOTIONS_PER_PASS`` cap would allow it.
+ The 5% ceiling floors at 1 when there is at least one active fact:
+ small graphs (< 20 facts) would otherwise round to a cap of 0 and
+ never get even a single contradicted fact demoted.
+ ``active_fact_count < 0`` means the count is unknown (the batch path
+ lost its persisted input bundle); fall back to the absolute cap only
+ rather than silently dropping every demotion.
+
+ When ``known_fact_uuids`` is provided, demotions targeting uuids
+ outside it are dropped BEFORE the cap slice — otherwise a
+ hallucinated uuid at the head of the model's list consumes a cap
+ slot (the entire budget on a floor-of-1 small graph) and displaces
+ a valid demotion that apply.py would have accepted. ``None`` skips
+ the pre-filter; apply.py's idempotent known-uuid filter remains the
+ security chokepoint either way.
+
+ Entity invalidations are count-capped at
+ ``MAX_ENTITY_INVALIDATIONS_PER_PASS``; see the constant's comment
+ for why the per-entity edge blast radius is bounded elsewhere (LD
+ flag + single-hop guarantee), not here.
+ """
+ demotions = ops.demotions
+ if known_fact_uuids is not None:
+ demotions = [d for d in demotions if d.edge_uuid in known_fact_uuids]
+ dropped = len(ops.demotions) - len(demotions)
+ if dropped:
+ logger.warning(
+ "Dream clamp: dropped %d demotion(s) targeting edge uuids "
+ "outside known_fact_uuids before applying the demotion cap",
+ dropped,
+ )
+ demotion_cap = MAX_DEMOTIONS_PER_PASS
+ if active_fact_count == 0:
+ demotion_cap = 0
+ elif active_fact_count > 0:
+ demotion_cap = min(MAX_DEMOTIONS_PER_PASS, max(1, active_fact_count * 5 // 100))
+ return DreamOperations(
+ writes=ops.writes[:MAX_WRITES_PER_PASS],
+ proposals=ops.proposals[:MAX_PROPOSALS_PER_PASS],
+ demotions=demotions[:demotion_cap],
+ entity_invalidations=ops.entity_invalidations[
+ :MAX_ENTITY_INVALIDATIONS_PER_PASS
+ ],
+ summary_for_user=ops.summary_for_user,
+ )
+
+
+async def _run_consolidate(
+ config: ChatConfig, input_bundle: DreamInput
+) -> StructuredCompletion[ConsolidationOutput]:
+ """First step: merge near-duplicate recent facts into canonical statements."""
+ messages = build_consolidate_prompt(input_bundle)
+ return await structured_completion(
+ model=config.fast_standard_model,
+ messages=messages,
+ response_model=ConsolidationOutput,
+ temperature=CONSOLIDATE_TEMP,
+ max_output_tokens=CONSOLIDATE_MAX_TOKENS,
+ )
+
+
+async def _run_recombine(
+ config: ChatConfig,
+ input_bundle: DreamInput,
+ consolidated: ConsolidationOutput,
+) -> StructuredCompletion[RecombinationOutput]:
+ """Second step: propose novel connections + weak-link findings."""
+ messages = build_recombine_prompt(input_bundle, consolidated.model_dump_json())
+ return await structured_completion(
+ model=config.fast_advanced_model,
+ messages=messages,
+ response_model=RecombinationOutput,
+ temperature=RECOMBINE_TEMP,
+ max_output_tokens=RECOMBINE_MAX_TOKENS,
+ )
+
+
+async def _run_sanitize(
+ config: ChatConfig,
+ input_bundle: DreamInput,
+ consolidated: ConsolidationOutput,
+ recombined: RecombinationOutput,
+) -> StructuredCompletion[DreamOperations]:
+ """Third step: gate writes/proposals/demotions before apply.py runs."""
+ messages = build_sanitize_prompt(
+ input_bundle,
+ consolidated.model_dump_json(),
+ recombined.model_dump_json(),
+ )
+ return await structured_completion(
+ model=config.fast_standard_model,
+ messages=messages,
+ response_model=DreamOperations,
+ temperature=SANITIZE_TEMP,
+ max_output_tokens=SANITIZE_MAX_TOKENS,
+ )
+
+
+def _phase_usage_from_completion(
+ phase: str, completion_usage: CompletionUsage, execution_path: ExecutionPath
+) -> PhaseUsage:
+ """Build a ``PhaseUsage`` from a raw ``CompletionUsage``, computing
+ cost from the rate card when the provider didn't supply one.
+
+ Provider-supplied cost (OpenRouter ``usage.cost``) wins when
+ present; otherwise we fall back to ``model_pricing.compute_cost_usd``.
+ Either way the execution-path discount has been applied: OpenRouter
+ spot prices are already post-discount (they ARE the rate we paid),
+ and the rate-card fallback explicitly multiplies the discount in.
+ """
+ cost = completion_usage.cost_usd
+ if cost is None:
+ cost = compute_cost_usd(
+ model=completion_usage.model,
+ input_tokens=completion_usage.input_tokens,
+ output_tokens=completion_usage.output_tokens,
+ cache_read_tokens=completion_usage.cache_read_tokens,
+ cache_creation_tokens=completion_usage.cache_creation_tokens,
+ execution_path=execution_path,
+ )
+ return PhaseUsage(
+ phase=phase, # type: ignore[arg-type]
+ model=completion_usage.model,
+ input_tokens=completion_usage.input_tokens,
+ output_tokens=completion_usage.output_tokens,
+ cache_read_tokens=completion_usage.cache_read_tokens,
+ cache_creation_tokens=completion_usage.cache_creation_tokens,
+ cost_usd=cost,
+ )
+
+
+def _aggregate_usage(
+ phases: list[PhaseUsage], execution_path: ExecutionPath
+) -> DreamPassUsage:
+ """Roll up per-phase usage into a ``DreamPassUsage``.
+
+ ``total_cost_usd`` is None when any single phase had unknown cost
+ so we never silently bill at a partial figure.
+ """
+ total_cost: float | None = 0.0
+ for p in phases:
+ if p.cost_usd is None:
+ total_cost = None
+ break
+ total_cost += p.cost_usd
+ return DreamPassUsage(
+ phases=phases,
+ total_input_tokens=sum(p.input_tokens for p in phases),
+ total_output_tokens=sum(p.output_tokens for p in phases),
+ total_cache_read_tokens=sum(p.cache_read_tokens for p in phases),
+ total_cache_creation_tokens=sum(p.cache_creation_tokens for p in phases),
+ total_cost_usd=total_cost,
+ discount_applied=execution_path_discount(execution_path),
+ )
+
+
+async def _execute_dream_pass_async(
+ user_id: str,
+ *,
+ transport_is_local: bool = False,
+ config: ChatConfig | None = None,
+ status_id: str | None = None,
+) -> DreamPassResult:
+ config = config or ChatConfig()
+ pass_id = str(uuidlib.uuid4())
+ started_at = datetime.now(timezone.utc)
+ monotonic_start = asyncio.get_event_loop().time()
+
+ has_anthropic_key = bool(config.direct_anthropic_api_key)
+ # Step 5: the async Anthropic batch path is gated by the
+ # ``DREAM_PASS_BATCH_ENABLED`` LD flag AND a direct Anthropic key (the
+ # native Batch API can't be reached via OpenRouter/subscription, so the
+ # key is a hard requirement). When the flag is off, dreams run on the
+ # synchronous baseline regardless of key presence — the flag lets the
+ # batch path ship dark and roll out per-cohort. When on, phase 1 submits
+ # via call_provider(execution_mode="batch"); the BatchExecutor polls and
+ # dream's batch_callbacks chain phases 2 → 3 + apply when results land
+ # (~50% off the rate card, see model_pricing.execution_path_discount).
+ #
+ # ``transport_name`` short-circuits to sync_baseline for transports that
+ # can't honour a batch path (local backends have no batch API;
+ # subscription mode shouldn't dual-bill the user's Anthropic key when the
+ # chat layer is on Claude Code OAuth).
+ batch_enabled = await is_feature_enabled(Flag.DREAM_PASS_BATCH_ENABLED, user_id)
+ execution_path: ExecutionPath = resolve_dream_execution_path(
+ has_anthropic_key=has_anthropic_key,
+ batch_processing_enabled=batch_enabled,
+ transport_name=config.transport.name,
+ )
+
+ ttl = _resolve_lock_ttl(transport_is_local)
+ try:
+ async with dream_lock(user_id, ttl_seconds=ttl) as dream_lock_handle:
+ # Pre-flight billing check. Runs inside the lock so a
+ # paywalled user doesn't burn the slot for an eligible
+ # concurrent pass on a shared FalkorDB.
+ budget_ok, budget_skip = await check_dream_budget(user_id, config=config)
+ if not budget_ok:
+ if budget_skip == "rate_limit_unavailable":
+ return _failure_result(
+ user_id,
+ pass_id,
+ started_at,
+ monotonic_start,
+ execution_path,
+ f"billing: {budget_skip}",
+ )
+ return DreamPassResult(
+ user_id=user_id,
+ pass_id=pass_id,
+ started_at=started_at,
+ completed_at=datetime.now(timezone.utc),
+ elapsed_seconds=(asyncio.get_event_loop().time() - monotonic_start),
+ execution_path=execution_path,
+ skipped=True,
+ skip_reason=budget_skip or "insufficient_credits",
+ )
+
+ input_bundle = await gather_dream_input(user_id)
+
+ if not input_bundle.episodes and not input_bundle.facts:
+ # Nothing to consolidate — early-return as skipped so the
+ # admin UI can render "nothing to dream about yet".
+ return DreamPassResult(
+ user_id=user_id,
+ pass_id=pass_id,
+ started_at=started_at,
+ completed_at=datetime.now(timezone.utc),
+ elapsed_seconds=(asyncio.get_event_loop().time() - monotonic_start),
+ execution_path=execution_path,
+ skipped=True,
+ skip_reason="no_input",
+ )
+
+ # ---- Anthropic batch path -----------------------------------
+ #
+ # When routing picks ``anthropic_batch`` we persist the
+ # input bundle, submit phase 1 to Anthropic's Messages
+ # Batches API with forced tool_use structured output, and
+ # return ``status="submitted"`` immediately. The BatchExecutor
+ # polls; dream's batch_callbacks chain phases 2 → 3 + apply
+ # when each phase result lands. Total latency is provider-
+ # driven (typically <30min, hard cap 24h via
+ # BatchExecutor.MAX_BATCH_LIFETIME_SECONDS); the user sees
+ # JobStatus.current_phase advance through consolidate →
+ # recombine → sanitize → complete.
+ if execution_path == "anthropic_batch":
+ return await _submit_dream_pass_batch(
+ user_id=user_id,
+ pass_id=pass_id,
+ started_at=started_at,
+ monotonic_start=monotonic_start,
+ execution_path=execution_path,
+ config=config,
+ input_bundle=input_bundle,
+ status_id=status_id,
+ dream_lock_handle=dream_lock_handle,
+ )
+
+ step_usages: list[PhaseUsage] = []
+
+ try:
+ consolidate_completion = await _run_consolidate(config, input_bundle)
+ except DreamLLMError as exc:
+ return _failure_result(
+ user_id,
+ pass_id,
+ started_at,
+ monotonic_start,
+ execution_path,
+ f"consolidate: {exc}",
+ usage=_aggregate_usage(step_usages, execution_path),
+ )
+ step_usages.append(
+ _phase_usage_from_completion(
+ "consolidate", consolidate_completion.usage, execution_path
+ )
+ )
+ await record_phase_cost(
+ user_id=user_id,
+ pass_id=pass_id,
+ phase_usage=step_usages[-1],
+ execution_path=execution_path,
+ )
+ consolidated = consolidate_completion.value
+
+ try:
+ recombine_completion = await _run_recombine(
+ config, input_bundle, consolidated
+ )
+ except DreamLLMError as exc:
+ return _failure_result(
+ user_id,
+ pass_id,
+ started_at,
+ monotonic_start,
+ execution_path,
+ f"recombine: {exc}",
+ usage=_aggregate_usage(step_usages, execution_path),
+ )
+ step_usages.append(
+ _phase_usage_from_completion(
+ "recombine", recombine_completion.usage, execution_path
+ )
+ )
+ await record_phase_cost(
+ user_id=user_id,
+ pass_id=pass_id,
+ phase_usage=step_usages[-1],
+ execution_path=execution_path,
+ )
+ recombined = recombine_completion.value
+
+ try:
+ sanitize_completion = await _run_sanitize(
+ config, input_bundle, consolidated, recombined
+ )
+ except DreamLLMError as exc:
+ return _failure_result(
+ user_id,
+ pass_id,
+ started_at,
+ monotonic_start,
+ execution_path,
+ f"sanitize: {exc}",
+ usage=_aggregate_usage(step_usages, execution_path),
+ )
+ step_usages.append(
+ _phase_usage_from_completion(
+ "sanitize", sanitize_completion.usage, execution_path
+ )
+ )
+ await record_phase_cost(
+ user_id=user_id,
+ pass_id=pass_id,
+ phase_usage=step_usages[-1],
+ execution_path=execution_path,
+ )
+ sanitized = sanitize_completion.value
+
+ ops = _clamp_operations(
+ sanitized,
+ len(input_bundle.facts),
+ known_fact_uuids=input_bundle.known_fact_uuids,
+ )
+ apply_stats = await apply_operations(
+ user_id,
+ pass_id,
+ ops,
+ known_fact_uuids=input_bundle.known_fact_uuids,
+ )
+
+ completed_at = datetime.now(timezone.utc)
+ snapshot = apply_stats.get("snapshot")
+
+ def _as_int(key: str) -> int:
+ v = apply_stats.get(key, 0)
+ return int(v) if isinstance(v, (int, str)) and v else 0
+
+ return DreamPassResult(
+ user_id=user_id,
+ pass_id=pass_id,
+ started_at=started_at,
+ completed_at=completed_at,
+ elapsed_seconds=(asyncio.get_event_loop().time() - monotonic_start),
+ execution_path=execution_path,
+ consolidated_count=_as_int("consolidated_count"),
+ proposal_count=_as_int("proposal_count"),
+ demotion_count=_as_int("demotion_count"),
+ entity_invalidation_count=_as_int("entity_invalidation_count"),
+ summary_for_user=ops.summary_for_user,
+ dream_session_id=str(apply_stats.get("session_id") or ""),
+ operations=(
+ snapshot if isinstance(snapshot, DreamOperationsSnapshot) else None
+ ),
+ usage=_aggregate_usage(step_usages, execution_path),
+ )
+
+ except DreamLockHeld:
+ return DreamPassResult(
+ user_id=user_id,
+ pass_id=pass_id,
+ started_at=started_at,
+ completed_at=datetime.now(timezone.utc),
+ elapsed_seconds=(asyncio.get_event_loop().time() - monotonic_start),
+ execution_path=execution_path,
+ skipped=True,
+ skip_reason="lock_held",
+ )
+ except Exception as exc: # pragma: no cover — last-resort guard
+ logger.exception("Dream pass crashed for user %s: %s", user_id[:12], exc)
+ return _failure_result(
+ user_id,
+ pass_id,
+ started_at,
+ monotonic_start,
+ execution_path,
+ str(exc),
+ )
+
+
+def _failure_result(
+ user_id: str,
+ pass_id: str,
+ started_at: datetime,
+ monotonic_start: float,
+ execution_path: ExecutionPath,
+ error: str,
+ usage: DreamPassUsage | None = None,
+) -> DreamPassResult:
+ """Build a failure ``DreamPassResult`` that still carries usage for
+ the phases that completed before the error — billing has to charge
+ for tokens we already paid for, even on partial failure."""
+ return DreamPassResult(
+ user_id=user_id,
+ pass_id=pass_id,
+ started_at=started_at,
+ completed_at=datetime.now(timezone.utc),
+ elapsed_seconds=asyncio.get_event_loop().time() - monotonic_start,
+ execution_path=execution_path,
+ error=error,
+ usage=usage,
+ )
+
+
+async def execute_dream_pass(
+ user_id: str, *, status_id: str | None = None
+) -> DreamPassResult:
+ """Public async entry point used by the scheduler + admin trigger.
+
+ ``status_id`` is the optional JobStatus row id when the caller is
+ the polling admin trigger (Step 2). The orchestrator threads it
+ into the batch path so the BatchExecutor callbacks can update the
+ user-visible status row as each phase lands. AgentProbe + other
+ sync callers pass ``None`` and never hit the batch path.
+ """
+ return await _execute_dream_pass_async(user_id, status_id=status_id)
+
+
+async def _submit_dream_pass_batch(
+ *,
+ user_id: str,
+ pass_id: str,
+ started_at: datetime,
+ monotonic_start: float,
+ execution_path: ExecutionPath,
+ config: ChatConfig,
+ input_bundle: DreamInput,
+ status_id: str | None,
+ dream_lock_handle: DreamLockHandle,
+) -> DreamPassResult:
+ """Submit phase 1 of the dream pass via Anthropic batch + return.
+
+ The orchestrator hands control to the BatchExecutor here: phase 1
+ (consolidate) is enqueued; phases 2 (recombine) and 3 (sanitize)
+ fire from dream's batch_callbacks as each prior phase's result
+ lands. Apply + cost log + JobStatus complete run when sanitize
+ lands. This function only does the kickoff.
+
+ The job_id link to JobStatus comes from the scheduler's
+ ``execute_dream_pass_with_status`` wrapper (Step 2). When the
+ orchestrator is invoked outside that path (e.g. AgentProbe eval),
+ ``job_id`` is empty and the callback skips the JobStatus updates —
+ apply still runs, cost still logs.
+ """
+ from .batch_submit import (
+ persist_input_bundle,
+ phase_models_for_config,
+ submit_phase,
+ )
+
+ api_key = config.direct_anthropic_api_key
+ if not api_key:
+ # Shouldn't happen — routing.py only picks anthropic_batch when
+ # the key is present. Guard for type-narrowing + future safety.
+ return _failure_result(
+ user_id,
+ pass_id,
+ started_at,
+ monotonic_start,
+ execution_path,
+ "anthropic_batch: no Anthropic API key (routing bug)",
+ )
+
+ # Persist DreamInput so the per-phase callbacks can rebuild the
+ # next phase's prompt without re-fetching from Postgres + FalkorDB.
+ try:
+ await persist_input_bundle(
+ pass_id, input_bundle, lock_token=dream_lock_handle.token
+ )
+ except Exception as exc:
+ return _failure_result(
+ user_id,
+ pass_id,
+ started_at,
+ monotonic_start,
+ execution_path,
+ f"anthropic_batch: input persist failed: {exc}",
+ )
+
+ # ``status_id`` ties the per-phase callback updates back to the
+ # JobStatus row the admin trigger created. Empty string when no
+ # caller wired it (AgentProbe eval, ad-hoc invocation) — the
+ # callback skips status writes in that case but apply still runs.
+ try:
+ submission = await submit_phase(
+ user_id=user_id,
+ pass_id=pass_id,
+ job_id=status_id or "",
+ phase="consolidate",
+ phase_models=phase_models_for_config(config),
+ api_key=api_key,
+ input_bundle=input_bundle,
+ )
+ except Exception as exc:
+ return _failure_result(
+ user_id,
+ pass_id,
+ started_at,
+ monotonic_start,
+ execution_path,
+ f"anthropic_batch: phase 1 submit failed: {exc}",
+ )
+
+ completed_at = datetime.now(timezone.utc)
+ logger.info(
+ "Dream pass %s submitted via Anthropic batch=%s (phase=consolidate)",
+ pass_id,
+ submission.provider_batch_id,
+ )
+ # Phase 1 is enqueued — hand the dream lock to the batch callback so it
+ # spans the full async lifetime (apply runs hours later). Extend the TTL
+ # to the batch window first; the callback releases it on terminal/failure.
+ await dream_lock_handle.extend(BATCH_LOCK_TTL_SECONDS)
+ dream_lock_handle.disown()
+ return DreamPassResult(
+ user_id=user_id,
+ pass_id=pass_id,
+ started_at=started_at,
+ completed_at=completed_at,
+ elapsed_seconds=asyncio.get_event_loop().time() - monotonic_start,
+ execution_path=execution_path,
+ skipped=False,
+ # The pass is async-pending — no usage / ops / session_id yet.
+ # The BatchExecutor + dream callbacks deliver those when phase
+ # 3 lands and apply runs.
+ )
diff --git a/autogpt_platform/backend/backend/copilot/dream/orchestrator_test.py b/autogpt_platform/backend/backend/copilot/dream/orchestrator_test.py
new file mode 100644
index 0000000000..6c38a9ac09
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/orchestrator_test.py
@@ -0,0 +1,700 @@
+"""Orchestrator three-phase tests with the LLM + Graphiti calls mocked.
+
+The orchestrator is the integration seam — these tests exercise the
+phase-to-phase plumbing without actually hitting OpenRouter or
+FalkorDB. apply + fetch get their own integration tests; this file is
+the unit-level safety net for the control-flow.
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from . import orchestrator as orchestrator_mod
+from .fetch import DreamInput, EpisodeRow, FactRow
+from .llm import CompletionUsage, DreamLLMError, StructuredCompletion
+from .schemas import (
+ ConsolidatedFact,
+ ConsolidationOutput,
+ DreamDemotion,
+ DreamOperations,
+ EntityInvalidation,
+ ProposedFinding,
+ RecombinationOutput,
+)
+
+
+def _wrap(value, model: str = "test-model") -> StructuredCompletion:
+ """Wrap a phase output in StructuredCompletion with zeroed usage.
+
+ Tests that don't care about token bookkeeping use this so they can
+ keep the side_effect list short. Tests that exercise the usage
+ pipeline build their own ``CompletionUsage`` with real numbers.
+ """
+ return StructuredCompletion(value=value, usage=CompletionUsage(model=model))
+
+
[email protected](autouse=True)
+def force_sync_baseline(mocker):
+ """Pin the orchestrator to the sync_baseline path for every test
+ in this file.
+
+ Step 5 of the plan routes dream pass to the Anthropic batch path
+ when an Anthropic key is configured; these tests mock
+ ``structured_completion`` directly to exercise the sync three-phase
+ flow, so we have to override the routing decision to keep them
+ valid. The batch path has its own dedicated test coverage in
+ ``batch_callbacks_test.py``.
+ """
+ mocker.patch.object(
+ orchestrator_mod,
+ "resolve_dream_execution_path",
+ return_value="sync_baseline",
+ )
+
+
+def _build_input(*, episodes=1, facts=1) -> DreamInput:
+ return DreamInput(
+ user_id="u",
+ group_id="g",
+ window_start=datetime(2026, 5, 1, tzinfo=timezone.utc),
+ window_end=datetime(2026, 5, 14, tzinfo=timezone.utc),
+ episodes=[
+ EpisodeRow(
+ uuid=f"e{i}",
+ name=None,
+ content="hello",
+ source_description=None,
+ valid_at=None,
+ created_at=None,
+ )
+ for i in range(episodes)
+ ],
+ facts=[
+ FactRow(
+ uuid=f"f{i}",
+ source="A",
+ target="B",
+ name="likes",
+ fact="A likes B",
+ scope="real:global",
+ confidence=0.7,
+ status="active",
+ created_at=None,
+ )
+ for i in range(facts)
+ ],
+ recent_sessions=[],
+ known_fact_uuids={f"f{i}" for i in range(facts)},
+ known_episode_uuids={f"e{i}" for i in range(episodes)},
+ )
+
+
+@asynccontextmanager
+async def _noop_lock(*args, **kwargs):
+ yield
+
+
[email protected](autouse=True)
+def _stub_lock(mocker):
+ """Always-acquired lock; tests that exercise the lock-held branch
+ re-patch to a function that raises DreamLockHeld."""
+ mocker.patch.object(orchestrator_mod, "dream_lock", _noop_lock)
+
+
[email protected](autouse=True)
+def _stub_billing(mocker):
+ """Default-allow billing so happy-path tests don't have to plumb
+ Redis/Supabase. Tests that exercise the budget-skip path re-patch
+ ``check_dream_budget`` with a (False, reason) AsyncMock.
+
+ ``record_phase_cost`` is a no-op fire-and-forget here; the billing
+ seam itself has dedicated coverage in ``billing_test.py``."""
+ mocker.patch.object(
+ orchestrator_mod, "check_dream_budget", AsyncMock(return_value=(True, None))
+ )
+ mocker.patch.object(orchestrator_mod, "record_phase_cost", AsyncMock())
+
+
[email protected](autouse=True)
+def _stub_batch_flag(mocker):
+ """Default the batch-path LD flag off so tests stay on sync + hermetic
+ (no LaunchDarkly calls). The wiring test re-patches to assert flag flow."""
+ mocker.patch.object(
+ orchestrator_mod, "is_feature_enabled", AsyncMock(return_value=False)
+ )
+
+
+async def test_empty_input_returns_skipped(mocker):
+ """No episodes AND no facts ⇒ skipped, no LLM calls."""
+ mocker.patch.object(
+ orchestrator_mod,
+ "gather_dream_input",
+ AsyncMock(return_value=_build_input(episodes=0, facts=0)),
+ )
+ structured = mocker.patch.object(
+ orchestrator_mod,
+ "structured_completion",
+ AsyncMock(),
+ )
+ apply_mock = mocker.patch.object(orchestrator_mod, "apply_operations", AsyncMock())
+
+ result = await orchestrator_mod.execute_dream_pass("u")
+
+ assert result.skipped is True
+ assert result.skip_reason == "no_input"
+ structured.assert_not_called()
+ apply_mock.assert_not_awaited()
+
+
[email protected]("flag_on", [True, False])
+async def test_batch_path_gated_by_flag_not_key(mocker, flag_on):
+ """The Anthropic batch path is gated by DREAM_PASS_BATCH_ENABLED — the
+ flag value (not mere direct-key presence) is what flows to routing's
+ ``batch_processing_enabled``, so the batch path can ship dark."""
+ resolve = mocker.patch.object(
+ orchestrator_mod,
+ "resolve_dream_execution_path",
+ return_value="sync_baseline",
+ )
+ flag = mocker.patch.object(
+ orchestrator_mod,
+ "is_feature_enabled",
+ AsyncMock(return_value=flag_on),
+ )
+ mocker.patch.object(
+ orchestrator_mod,
+ "gather_dream_input",
+ AsyncMock(return_value=_build_input(episodes=0, facts=0)),
+ )
+
+ await orchestrator_mod.execute_dream_pass("u")
+
+ flag.assert_awaited_once()
+ assert flag.await_args.args[0] is orchestrator_mod.Flag.DREAM_PASS_BATCH_ENABLED
+ assert resolve.call_args.kwargs["batch_processing_enabled"] is flag_on
+
+
+async def test_happy_path_runs_three_steps_and_applies(mocker):
+ mocker.patch.object(
+ orchestrator_mod,
+ "gather_dream_input",
+ AsyncMock(return_value=_build_input()),
+ )
+
+ consolidated = ConsolidationOutput(
+ facts=[ConsolidatedFact(content="A likes B", confidence=0.8)]
+ )
+ recombined = RecombinationOutput(
+ proposals=[
+ ProposedFinding(
+ content="A probably trusts B",
+ confidence=0.6,
+ rationale="implied by A likes B",
+ )
+ ]
+ )
+ sanitized = DreamOperations(
+ writes=consolidated.facts,
+ proposals=recombined.proposals,
+ demotions=[],
+ entity_invalidations=[],
+ summary_for_user="Dream consolidated 1 fact.",
+ )
+ mocker.patch.object(
+ orchestrator_mod,
+ "structured_completion",
+ AsyncMock(
+ side_effect=[_wrap(consolidated), _wrap(recombined), _wrap(sanitized)]
+ ),
+ )
+ apply_mock = mocker.patch.object(
+ orchestrator_mod,
+ "apply_operations",
+ AsyncMock(
+ return_value={
+ "session_id": "s1",
+ "consolidated_count": 1,
+ "proposal_count": 1,
+ "demotion_count": 0,
+ "demotion_failed_count": 0,
+ "entity_invalidation_count": 0,
+ }
+ ),
+ )
+
+ result = await orchestrator_mod.execute_dream_pass("u")
+
+ assert result.error is None
+ assert result.skipped is False
+ assert result.consolidated_count == 1
+ assert result.proposal_count == 1
+ assert result.summary_for_user == "Dream consolidated 1 fact."
+ assert result.dream_session_id == "s1"
+ apply_mock.assert_awaited_once()
+
+
+async def test_consolidate_llm_failure_surfaces_error_and_skips_apply(mocker):
+ """A failure in the consolidation step must surface as
+ ``error="consolidate: ..."`` and never trigger apply_operations."""
+ mocker.patch.object(
+ orchestrator_mod,
+ "gather_dream_input",
+ AsyncMock(return_value=_build_input()),
+ )
+ mocker.patch.object(
+ orchestrator_mod,
+ "structured_completion",
+ AsyncMock(side_effect=DreamLLMError("boom")),
+ )
+ apply_mock = mocker.patch.object(orchestrator_mod, "apply_operations", AsyncMock())
+
+ result = await orchestrator_mod.execute_dream_pass("u")
+
+ assert result.error is not None
+ assert result.error.startswith("consolidate:")
+ apply_mock.assert_not_awaited()
+
+
+async def test_clamps_oversized_sanitizer_output(mocker):
+ """The sanitizer model can over-emit; orchestrator must enforce caps."""
+ # 1000 active facts -> 5% ceiling (50) sits above MAX_DEMOTIONS_PER_PASS,
+ # so the absolute cap is the binding one for this assertion.
+ mocker.patch.object(
+ orchestrator_mod,
+ "gather_dream_input",
+ AsyncMock(return_value=_build_input(facts=1000)),
+ )
+ consolidated = ConsolidationOutput(facts=[])
+ recombined = RecombinationOutput(proposals=[])
+
+ # Build a sanitizer output that blows past every cap. Demotions
+ # target real known fact uuids (f0..f99) so the clamp's known-uuid
+ # pre-filter keeps them all and the cap is what binds.
+ huge_sanitized = DreamOperations(
+ writes=[ConsolidatedFact(content=f"w{i}", confidence=0.5) for i in range(100)],
+ proposals=[
+ ProposedFinding(
+ content=f"p{i}",
+ confidence=0.5,
+ rationale="r",
+ )
+ for i in range(100)
+ ],
+ demotions=[DreamDemotion(edge_uuid=f"f{i}", reason="r") for i in range(100)],
+ summary_for_user="ok",
+ )
+
+ mocker.patch.object(
+ orchestrator_mod,
+ "structured_completion",
+ AsyncMock(
+ side_effect=[_wrap(consolidated), _wrap(recombined), _wrap(huge_sanitized)]
+ ),
+ )
+
+ captured: dict[str, DreamOperations] = {}
+
+ async def fake_apply(user_id, pass_id, ops, *, known_fact_uuids=None):
+ captured["ops"] = ops
+ return {
+ "session_id": "s",
+ "consolidated_count": len(ops.writes),
+ "proposal_count": len(ops.proposals),
+ "demotion_count": len(ops.demotions),
+ "demotion_failed_count": 0,
+ "entity_invalidation_count": 0,
+ }
+
+ mocker.patch.object(orchestrator_mod, "apply_operations", fake_apply)
+
+ await orchestrator_mod.execute_dream_pass("u")
+
+ assert captured["ops"] is not None
+ from .prompts import (
+ MAX_DEMOTIONS_PER_PASS,
+ MAX_PROPOSALS_PER_PASS,
+ MAX_WRITES_PER_PASS,
+ )
+
+ assert len(captured["ops"].writes) == MAX_WRITES_PER_PASS
+ assert len(captured["ops"].proposals) == MAX_PROPOSALS_PER_PASS
+ assert len(captured["ops"].demotions) == MAX_DEMOTIONS_PER_PASS
+
+
+async def test_demotions_capped_at_five_percent_of_active_facts(mocker):
+ """A small active-fact set caps demotions below the absolute limit so
+ one pass can't wipe a meaningful fraction of memory: 5% of 100 = 5,
+ well under MAX_DEMOTIONS_PER_PASS (10)."""
+ mocker.patch.object(
+ orchestrator_mod,
+ "gather_dream_input",
+ AsyncMock(return_value=_build_input(facts=100)),
+ )
+ mocker.patch.object(
+ orchestrator_mod,
+ "structured_completion",
+ AsyncMock(
+ side_effect=[
+ _wrap(ConsolidationOutput(facts=[])),
+ _wrap(RecombinationOutput(proposals=[])),
+ _wrap(
+ DreamOperations(
+ # Known fact uuids (f0..f49) so the clamp's
+ # pre-filter keeps them and the 5% cap binds.
+ demotions=[
+ DreamDemotion(edge_uuid=f"f{i}", reason="r")
+ for i in range(50)
+ ],
+ summary_for_user="ok",
+ )
+ ),
+ ]
+ ),
+ )
+
+ captured: dict[str, DreamOperations] = {}
+
+ async def fake_apply(user_id, pass_id, ops, *, known_fact_uuids=None):
+ captured["ops"] = ops
+ return {
+ "session_id": "s",
+ "consolidated_count": 0,
+ "proposal_count": 0,
+ "demotion_count": len(ops.demotions),
+ "demotion_failed_count": 0,
+ "entity_invalidation_count": 0,
+ }
+
+ mocker.patch.object(orchestrator_mod, "apply_operations", fake_apply)
+
+ await orchestrator_mod.execute_dream_pass("u")
+
+ assert len(captured["ops"].demotions) == 5
+
+
+def test_clamp_operations_demotion_cap_rules():
+ """Unit-level coverage of the demotion ceiling: min(absolute, 5%), with
+ an unknown count (-1) falling back to the absolute cap."""
+ from .prompts import MAX_DEMOTIONS_PER_PASS
+
+ ops = DreamOperations(
+ demotions=[DreamDemotion(edge_uuid=f"e{i}", reason="r") for i in range(50)],
+ )
+ # 5% of 100 = 5 (below the absolute cap)
+ assert len(orchestrator_mod._clamp_operations(ops, 100).demotions) == 5
+ # 5% of 1000 = 50, so the absolute cap binds
+ assert (
+ len(orchestrator_mod._clamp_operations(ops, 1000).demotions)
+ == MAX_DEMOTIONS_PER_PASS
+ )
+ # Unknown active-fact count -> absolute cap only, never zero
+ assert (
+ len(orchestrator_mod._clamp_operations(ops, -1).demotions)
+ == MAX_DEMOTIONS_PER_PASS
+ )
+
+
+def test_clamp_operations_small_graph_demotion_cap_floors_at_one():
+ """A small graph (< 20 active facts, where 5% rounds to 0) still gets
+ a demotion budget of 1 — early-stage users must be able to demote a
+ contradicted fact. Zero active facts means zero demotion budget:
+ there is nothing legitimate to demote."""
+ ops = DreamOperations(
+ demotions=[DreamDemotion(edge_uuid=f"e{i}", reason="r") for i in range(50)],
+ )
+ assert len(orchestrator_mod._clamp_operations(ops, 10).demotions) == 1
+ assert len(orchestrator_mod._clamp_operations(ops, 1).demotions) == 1
+ assert len(orchestrator_mod._clamp_operations(ops, 19).demotions) == 1
+ # 20 facts crosses the 5% threshold back to the proportional cap
+ assert len(orchestrator_mod._clamp_operations(ops, 20).demotions) == 1
+ assert len(orchestrator_mod._clamp_operations(ops, 40).demotions) == 2
+ # No active facts at all -> no demotion budget
+ assert len(orchestrator_mod._clamp_operations(ops, 0).demotions) == 0
+
+
+def test_hallucinated_uuid_does_not_consume_cap_slot():
+ """On a small graph the demotion cap floors at 1 — a hallucinated
+ edge uuid at the head of the model's list must not eat that single
+ slot and displace the valid demotion behind it. The clamp filters
+ against known_fact_uuids BEFORE slicing to the cap."""
+ ops = DreamOperations(
+ demotions=[
+ DreamDemotion(edge_uuid="hallucinated", reason="r"),
+ DreamDemotion(edge_uuid="f0", reason="r"),
+ ],
+ )
+ clamped = orchestrator_mod._clamp_operations(ops, 10, known_fact_uuids={"f0"})
+ assert [d.edge_uuid for d in clamped.demotions] == ["f0"]
+
+ # Without the allowlist the clamp can't pre-filter — the cap slices
+ # the raw list and apply.py's filter remains the only defense.
+ unfiltered = orchestrator_mod._clamp_operations(ops, 10)
+ assert [d.edge_uuid for d in unfiltered.demotions] == ["hallucinated"]
+
+
+async def test_sync_path_filters_hallucinated_demotion_before_cap(mocker):
+ """End-to-end on the sync path: 10 active facts → demotion cap 1; the
+ sanitizer leads with a hallucinated uuid but the valid demotion (f0)
+ is the one that survives clamping and reaches apply."""
+ mocker.patch.object(
+ orchestrator_mod,
+ "gather_dream_input",
+ AsyncMock(return_value=_build_input(facts=10)),
+ )
+ mocker.patch.object(
+ orchestrator_mod,
+ "structured_completion",
+ AsyncMock(
+ side_effect=[
+ _wrap(ConsolidationOutput(facts=[])),
+ _wrap(RecombinationOutput(proposals=[])),
+ _wrap(
+ DreamOperations(
+ demotions=[
+ DreamDemotion(edge_uuid="hallucinated", reason="r"),
+ DreamDemotion(edge_uuid="f0", reason="r"),
+ ],
+ summary_for_user="ok",
+ )
+ ),
+ ]
+ ),
+ )
+
+ captured: dict[str, DreamOperations] = {}
+
+ async def fake_apply(user_id, pass_id, ops, *, known_fact_uuids=None):
+ captured["ops"] = ops
+ return {
+ "session_id": "s",
+ "consolidated_count": 0,
+ "proposal_count": 0,
+ "demotion_count": len(ops.demotions),
+ "demotion_failed_count": 0,
+ "entity_invalidation_count": 0,
+ }
+
+ mocker.patch.object(orchestrator_mod, "apply_operations", fake_apply)
+
+ await orchestrator_mod.execute_dream_pass("u")
+
+ assert [d.edge_uuid for d in captured["ops"].demotions] == ["f0"]
+
+
+def test_clamp_operations_caps_entity_invalidations():
+ """Entity invalidations are the highest-blast-radius op (each one
+ demotes every edge on the entity), so the clamp must bound their
+ count at MAX_ENTITY_INVALIDATIONS_PER_PASS — they used to pass
+ through entirely uncapped."""
+ ops = DreamOperations(
+ entity_invalidations=[
+ EntityInvalidation(entity_uuid=f"ent{i}", reason="r") for i in range(25)
+ ],
+ )
+ clamped = orchestrator_mod._clamp_operations(ops, 100)
+ assert (
+ len(clamped.entity_invalidations)
+ == orchestrator_mod.MAX_ENTITY_INVALIDATIONS_PER_PASS
+ )
+ # The first N proposed invalidations survive, in order
+ assert [e.entity_uuid for e in clamped.entity_invalidations] == [
+ "ent0",
+ "ent1",
+ ]
+
+
+async def test_sync_path_passes_known_fact_uuids_to_apply(mocker):
+ """The sync orchestrator must thread the input bundle's
+ known_fact_uuids into apply_operations so the demotion pre-flight
+ filter (apply.py) can reject hallucinated edge uuids."""
+ input_bundle = _build_input(facts=3)
+ mocker.patch.object(
+ orchestrator_mod,
+ "gather_dream_input",
+ AsyncMock(return_value=input_bundle),
+ )
+ mocker.patch.object(
+ orchestrator_mod,
+ "structured_completion",
+ AsyncMock(
+ side_effect=[
+ _wrap(ConsolidationOutput(facts=[])),
+ _wrap(RecombinationOutput(proposals=[])),
+ _wrap(DreamOperations(summary_for_user="ok")),
+ ]
+ ),
+ )
+ apply_mock = mocker.patch.object(
+ orchestrator_mod,
+ "apply_operations",
+ AsyncMock(
+ return_value={
+ "session_id": "s",
+ "consolidated_count": 0,
+ "proposal_count": 0,
+ "demotion_count": 0,
+ "demotion_failed_count": 0,
+ "entity_invalidation_count": 0,
+ }
+ ),
+ )
+
+ await orchestrator_mod.execute_dream_pass("u")
+
+ apply_mock.assert_awaited_once()
+ assert (
+ apply_mock.await_args.kwargs["known_fact_uuids"]
+ == input_bundle.known_fact_uuids
+ )
+
+
+async def test_lock_held_returns_skipped_lock_held(mocker):
+ from .locks import DreamLockHeld
+
+ @asynccontextmanager
+ async def busy_lock(*args, **kwargs):
+ raise DreamLockHeld(args[0] if args else "?")
+ yield # pragma: no cover
+
+ mocker.patch.object(orchestrator_mod, "dream_lock", busy_lock)
+ fetch_mock = mocker.patch.object(
+ orchestrator_mod, "gather_dream_input", AsyncMock()
+ )
+
+ result = await orchestrator_mod.execute_dream_pass("u")
+
+ assert result.skipped is True
+ assert result.skip_reason == "lock_held"
+ fetch_mock.assert_not_awaited()
+
+
+async def test_budget_skip_returns_insufficient_credits_without_running_phases(mocker):
+ """Pre-flight rate-limit cap exceeded → skipped, no LLM calls, no apply."""
+ mocker.patch.object(
+ orchestrator_mod,
+ "check_dream_budget",
+ AsyncMock(return_value=(False, "insufficient_credits")),
+ )
+ structured = mocker.patch.object(
+ orchestrator_mod, "structured_completion", AsyncMock()
+ )
+ apply_mock = mocker.patch.object(orchestrator_mod, "apply_operations", AsyncMock())
+ fetch_mock = mocker.patch.object(
+ orchestrator_mod, "gather_dream_input", AsyncMock()
+ )
+
+ result = await orchestrator_mod.execute_dream_pass("u")
+
+ assert result.skipped is True
+ assert result.skip_reason == "insufficient_credits"
+ structured.assert_not_called()
+ apply_mock.assert_not_awaited()
+ fetch_mock.assert_not_awaited()
+
+
+async def test_budget_check_failing_closed_surfaces_as_error(mocker):
+ """Redis brown-out during pre-flight → error, NOT skipped, so the
+ admin endpoint surfaces it and the scheduler retries next tick."""
+ mocker.patch.object(
+ orchestrator_mod,
+ "check_dream_budget",
+ AsyncMock(return_value=(False, "rate_limit_unavailable")),
+ )
+ apply_mock = mocker.patch.object(orchestrator_mod, "apply_operations", AsyncMock())
+
+ result = await orchestrator_mod.execute_dream_pass("u")
+
+ assert result.error is not None
+ assert "rate_limit_unavailable" in result.error
+ assert result.skipped is False
+ apply_mock.assert_not_awaited()
+
+
+async def test_each_completed_phase_charges_once(mocker):
+ """One billing row per LLM call — verifies the chat convention
+ (per-call rows) is preserved end-to-end in the orchestrator."""
+ mocker.patch.object(
+ orchestrator_mod,
+ "gather_dream_input",
+ AsyncMock(return_value=_build_input()),
+ )
+ consolidated = ConsolidationOutput(facts=[])
+ recombined = RecombinationOutput(proposals=[])
+ sanitized = DreamOperations()
+ mocker.patch.object(
+ orchestrator_mod,
+ "structured_completion",
+ AsyncMock(
+ side_effect=[_wrap(consolidated), _wrap(recombined), _wrap(sanitized)]
+ ),
+ )
+ mocker.patch.object(
+ orchestrator_mod,
+ "apply_operations",
+ AsyncMock(
+ return_value={
+ "session_id": "s",
+ "consolidated_count": 0,
+ "proposal_count": 0,
+ "demotion_count": 0,
+ "demotion_failed_count": 0,
+ "entity_invalidation_count": 0,
+ }
+ ),
+ )
+ charge_spy = AsyncMock()
+ mocker.patch.object(orchestrator_mod, "record_phase_cost", charge_spy)
+
+ await orchestrator_mod.execute_dream_pass("u")
+
+ assert charge_spy.await_count == 3
+ phases_charged = [c.kwargs["phase_usage"].phase for c in charge_spy.await_args_list]
+ assert phases_charged == ["consolidate", "recombine", "sanitize"]
+
+
+async def test_partial_failure_still_charges_completed_phases(mocker):
+ """If recombine errors after consolidate succeeded, we must still
+ bill for the consolidate tokens — we already paid the provider."""
+ mocker.patch.object(
+ orchestrator_mod,
+ "gather_dream_input",
+ AsyncMock(return_value=_build_input()),
+ )
+ consolidated = ConsolidationOutput(facts=[])
+ mocker.patch.object(
+ orchestrator_mod,
+ "structured_completion",
+ AsyncMock(side_effect=[_wrap(consolidated), DreamLLMError("recombine boom")]),
+ )
+ apply_mock = mocker.patch.object(orchestrator_mod, "apply_operations", AsyncMock())
+ charge_spy = AsyncMock()
+ mocker.patch.object(orchestrator_mod, "record_phase_cost", charge_spy)
+
+ result = await orchestrator_mod.execute_dream_pass("u")
+
+ assert result.error is not None
+ assert result.error.startswith("recombine:")
+ assert charge_spy.await_count == 1 # consolidate charged, recombine never ran
+ assert charge_spy.await_args.kwargs["phase_usage"].phase == "consolidate"
+ apply_mock.assert_not_awaited()
+
+
+_ = MagicMock # keep import for editor convenience; not directly used
diff --git a/autogpt_platform/backend/backend/copilot/dream/prompts.py b/autogpt_platform/backend/backend/copilot/dream/prompts.py
new file mode 100644
index 0000000000..e13d13f21e
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/prompts.py
@@ -0,0 +1,280 @@
+"""Prompt builders for the three-phase dream pipeline.
+
+Slice-1 ships hardcoded prompts. Once Langfuse seeds land, swap the
+body of each ``build_*`` for a Langfuse fetch with these strings as
+the local fallback.
+
+Phase 1 — Consolidation (Sonnet, temp 0.2, structured JSON output)
+Phase 2 — Recombination (Opus, temp 0.9, structured JSON output)
+Phase 3 — Sanitize + Gate (Sonnet, temp 0.0, structured JSON output)
+
+Each prompt asks the model to emit JSON matching the corresponding
+Pydantic schema in ``schemas.py``. We rely on ``response_format=
+{"type": "json_object"}`` plus post-validation, which works against
+both OpenAI and OpenRouter without provider-specific shenanigans.
+"""
+
+from __future__ import annotations
+
+import json
+
+from .fetch import DreamInput
+from .staleness import identify_stale_candidates
+
+# Hard cap shared across phases — phase 3 must reject demotion lists
+# longer than this regardless of what phase 1/2 produced. Mirrors the
+# guardrail in ``dream/p0-spec.md`` §2.
+MAX_DEMOTIONS_PER_PASS = 10
+MAX_PROPOSALS_PER_PASS = 20
+MAX_WRITES_PER_PASS = 30
+
+
+def _format_episodes(input_bundle: DreamInput, max_chars_per_episode: int = 500) -> str:
+ if not input_bundle.episodes:
+ return "(no recent episodes in window)"
+ lines: list[str] = []
+ for e in input_bundle.episodes:
+ body = (e.content or "")[:max_chars_per_episode]
+ lines.append(f"- uuid={e.uuid} valid_at={e.valid_at}\n {body}".rstrip())
+ return "\n".join(lines)
+
+
+def _format_facts(input_bundle: DreamInput) -> str:
+ if not input_bundle.facts:
+ return "(no active facts)"
+ by_scope: dict[str, list[str]] = {}
+ for f in input_bundle.facts:
+ scope = f.scope or "real:global"
+ bucket = by_scope.setdefault(scope, [])
+ bucket.append(
+ f" - uuid={f.uuid} confidence={f.confidence} "
+ f"{(f.source or '?')} —[{f.name or '?'}]→ {(f.target or '?')}: "
+ f"{(f.fact or '').strip()}"
+ )
+ parts: list[str] = []
+ for scope, bucket in sorted(by_scope.items()):
+ parts.append(f"[scope={scope}]")
+ parts.extend(bucket)
+ return "\n".join(parts)
+
+
+def _format_sessions(input_bundle: DreamInput) -> str:
+ if not input_bundle.recent_sessions:
+ return "(no recent sessions)"
+ parts: list[str] = []
+ for s in input_bundle.recent_sessions:
+ title = s.title or "(untitled)"
+ parts.append(f"--- session {s.session_id} — {title} ---\n{s.body}".rstrip())
+ return "\n\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Consolidation step — merge near-duplicate recent facts into canonical form.
+# ---------------------------------------------------------------------------
+
+
+CONSOLIDATE_SYSTEM = (
+ "OUTPUT FORMAT — MANDATORY:\n"
+ "Your entire response MUST be a single valid JSON object and "
+ "NOTHING ELSE. The first character of your response MUST be `{`. "
+ "Do NOT preface with prose like 'Looking at the inputs...'. "
+ "Do NOT wrap the JSON in markdown code fences. Do NOT use "
+ "markdown formatting anywhere (no **bold**, no numbered lists, "
+ "no headings). Do NOT explain your reasoning before or after "
+ "the JSON. If you need to think, do it silently — only the JSON "
+ "is returned.\n\n"
+ "ROLE:\n"
+ "You are the consolidation step of a sleep-time memory pass for an "
+ "AI assistant. Your job is to look at the user's recent episodes "
+ "and active facts and emit a small set of *consolidated* statements "
+ "that merge near-duplicates into a canonical form.\n\n"
+ "RULES:\n"
+ " * Do not invent new information that isn't present in the inputs.\n"
+ " * Prefer the longer, more specific phrasing when merging duplicates.\n"
+ " * Group by scope — never merge a fact in 'project:foo' with one in "
+ "'real:global'.\n"
+ " * Carry forward the source episode uuids exactly. Never make uuids up.\n"
+ " * Confidence is your own — 0.0 means 'I am unsure', 1.0 means "
+ "'this is restated verbatim across multiple sources'.\n"
+ f" * Output AT MOST {MAX_WRITES_PER_PASS} consolidated facts. Better "
+ "to consolidate hard than to flood the recombination step.\n\n"
+ "JSON SCHEMA (your response MUST match this shape):\n"
+ '{ "facts": [ { "content": str, "scope": str, "confidence": float, '
+ '"source_episode_uuids": [str, ...] } ] }\n\n'
+ 'If you have nothing to emit, return `{"facts": []}` — still JSON, '
+ "still starting with `{`."
+)
+
+
+def build_consolidate_prompt(input_bundle: DreamInput) -> list[dict[str, str]]:
+ user_body = (
+ "## Recent episodes (within window)\n"
+ + _format_episodes(input_bundle)
+ + "\n\n## Active facts\n"
+ + _format_facts(input_bundle)
+ + "\n\n## Recent sessions (for context only — do not extract facts from these)\n"
+ + _format_sessions(input_bundle)
+ + "\n\nReturn ONLY the JSON object. Begin your response with `{`."
+ )
+ return [
+ {"role": "system", "content": CONSOLIDATE_SYSTEM},
+ {"role": "user", "content": user_body},
+ ]
+
+
+# ---------------------------------------------------------------------------
+# Recombination step — propose novel connections + weak-link findings.
+# ---------------------------------------------------------------------------
+
+
+RECOMBINE_SYSTEM = (
+ "OUTPUT FORMAT — MANDATORY:\n"
+ "Your entire response MUST be a single valid JSON object and "
+ "NOTHING ELSE. The first character of your response MUST be `{`. "
+ "Do NOT preface with prose. Do NOT wrap the JSON in markdown "
+ "code fences. Do NOT use markdown formatting anywhere. Do NOT "
+ "explain reasoning before or after the JSON. Empty result is "
+ '`{"proposals": []}`.\n\n'
+ "ROLE:\n"
+ "You are the recombination step of a sleep-time memory pass. The "
+ "previous step consolidated the user's recent facts. Your job is to "
+ "look for *novel connections* — weak-link findings, implications "
+ "across scopes, useful rules the user has implicitly demonstrated.\n\n"
+ "RULES:\n"
+ " * Every proposal must cite at least one source_fact_uuid or "
+ "source_episode_uuid from the consolidation step's input. Proposals "
+ "with no citation will be rejected by the sanitizer.\n"
+ " * Stay in scope — proposed findings live in the same scope as "
+ "their evidence.\n"
+ ' * Do not propose first-person-as-user statements ("I think X"). '
+ "All proposals must describe the user's world, not the assistant's.\n"
+ f" * Output AT MOST {MAX_PROPOSALS_PER_PASS} proposals. Quality > quantity.\n"
+ " * Confidence here is your own self-rating of how likely the "
+ "proposed finding is to be useful to the user.\n"
+ ' * ``memory_kind`` MUST be one of: "finding", "rule", '
+ '"preference", "plan". Do NOT invent new values (e.g. '
+ '"inferred_fact", "recommendation", "insight") — those '
+ "proposals are silently dropped.\n\n"
+ "JSON SCHEMA (your response MUST match this shape):\n"
+ '{ "proposals": [ { "content": str, "scope": str, "memory_kind": str, '
+ '"confidence": float, "rationale": str, "source_episode_uuids": [str, ...], '
+ '"source_fact_uuids": [str, ...] } ] }'
+)
+
+
+def build_recombine_prompt(
+ input_bundle: DreamInput, consolidated_json: str
+) -> list[dict[str, str]]:
+ user_body = (
+ "## Consolidated facts (from the consolidation step)\n"
+ + consolidated_json
+ + "\n\n## Active facts (for reference)\n"
+ + _format_facts(input_bundle)
+ + "\n\n## Recent episodes (for reference)\n"
+ + _format_episodes(input_bundle, max_chars_per_episode=300)
+ + "\n\nReturn ONLY the JSON object. Begin your response with `{`."
+ )
+ return [
+ {"role": "system", "content": RECOMBINE_SYSTEM},
+ {"role": "user", "content": user_body},
+ ]
+
+
+# ---------------------------------------------------------------------------
+# Sanitization step — decide what lands as a write and what gets demoted.
+# ---------------------------------------------------------------------------
+
+
+SANITIZE_SYSTEM = (
+ "OUTPUT FORMAT — MANDATORY:\n"
+ "Your entire response MUST be a single valid JSON object and "
+ "NOTHING ELSE. The first character of your response MUST be `{`. "
+ "Do NOT preface with prose. Do NOT wrap the JSON in markdown "
+ "code fences. Do NOT use markdown formatting anywhere. Do NOT "
+ "explain reasoning before or after the JSON. An empty result is "
+ 'still JSON: `{"writes": [], "proposals": [], "demotions": [], '
+ '"entity_invalidations": [], "summary_for_user": ""}`.\n\n'
+ "ROLE:\n"
+ "You are the sanitizer step of a sleep-time memory pass. You receive "
+ "the consolidated facts and the recombination proposals; you decide "
+ "what actually lands in memory and what gets demoted.\n\n"
+ "RULES (HARD — outputs that violate these will be dropped):\n"
+ f" * AT MOST {MAX_WRITES_PER_PASS} writes.\n"
+ f" * AT MOST {MAX_PROPOSALS_PER_PASS} proposals.\n"
+ f" * AT MOST {MAX_DEMOTIONS_PER_PASS} demotions per pass. Demotions "
+ "are surgical — only demote a fact when (a) a consolidated fact or "
+ "recombination proposal directly contradicts it, (b) it appears in "
+ "the stale-fact candidates list below AND general knowledge tells "
+ "you it has gone stale, or (c) the user has clearly retracted it.\n"
+ " * STALE-FACT GUARDRAIL: the candidates list flags facts whose "
+ "phrasing suggests they go stale fast (pricing, leadership, "
+ "model versions, 'best'/'current'/'latest' claims). It is NOT a "
+ "demote-on-sight list — stable facts can match the heuristics by "
+ "coincidence (e.g. 'user's birthday is March 5' is dated but not "
+ "stale). For each candidate, demote only when general knowledge or "
+ "a phase-1 consolidated fact contradicts it. When in doubt, "
+ "preserve.\n"
+ " * Demotion edge_uuids MUST exist in the provided list of known "
+ "fact uuids. Do not invent uuids.\n"
+ " * Entity invalidations require an entity_uuid present in the "
+ "active-facts source/target set. Single-hop demotion only.\n"
+ " * Reject any proposal that has zero source citations.\n"
+ " * Reject any proposal whose content starts with first-person "
+ '("I think", "I believe", "In my opinion") — those are not user '
+ "memories.\n"
+ " * Write a short ``summary_for_user`` (1-3 sentences) describing "
+ "what the pass found.\n\n"
+ "JSON SCHEMA (your response MUST match this DreamOperations shape):\n"
+ '{ "writes": [ConsolidatedFact...], "proposals": [ProposedFinding...], '
+ '"demotions": [{"edge_uuid": str, "reason": str, '
+ '"new_status": "superseded"|"contradicted"} ...], '
+ '"entity_invalidations": [{"entity_uuid": str, "reason": str} ...], '
+ '"summary_for_user": str }'
+)
+
+
+def _format_stale_candidates(input_bundle: DreamInput) -> str:
+ """Render the staleness-heuristic candidate list for the sanitize prompt.
+
+ ``identify_stale_candidates`` returns ``(fact, score)`` ordered by
+ descending score so the most-suspect candidates render first when
+ the prompt is near its budget. Use the explicit demotion reason
+ string ``"stale_fact"`` so apply.py's audit trail matches the
+ spec's reason enumeration.
+ """
+ candidates = identify_stale_candidates(input_bundle.facts)
+ if not candidates:
+ return "(no stale-fact candidates flagged this pass)"
+ lines: list[str] = []
+ for fact, score in candidates:
+ lines.append(
+ f"- uuid={fact.uuid} score={score:.2f} "
+ f"created_at={fact.created_at or '?'}: "
+ f"{(fact.fact or '').strip()}"
+ )
+ return "\n".join(lines)
+
+
+def build_sanitize_prompt(
+ input_bundle: DreamInput,
+ consolidated_json: str,
+ recombined_json: str,
+) -> list[dict[str, str]]:
+ known_fact_uuids = sorted(input_bundle.known_fact_uuids)
+ user_body = (
+ "## Consolidated facts (from the consolidation step)\n"
+ + consolidated_json
+ + "\n\n## Recombination proposals (from the recombination step)\n"
+ + recombined_json
+ + "\n\n## Known fact uuids (only these are valid demotion targets)\n"
+ + json.dumps(known_fact_uuids)
+ + "\n\n## Stale-fact candidates (heuristic flags — verify before demoting)\n"
+ + _format_stale_candidates(input_bundle)
+ + "\n\n## Active facts (for context when deciding demotions)\n"
+ + _format_facts(input_bundle)
+ + "\n\nReturn ONLY the JSON object. Begin your response with `{`."
+ )
+ return [
+ {"role": "system", "content": SANITIZE_SYSTEM},
+ {"role": "user", "content": user_body},
+ ]
diff --git a/autogpt_platform/backend/backend/copilot/dream/prompts_test.py b/autogpt_platform/backend/backend/copilot/dream/prompts_test.py
new file mode 100644
index 0000000000..c756e39157
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/prompts_test.py
@@ -0,0 +1,210 @@
+"""Prompt builder smoke tests.
+
+These ensure the three-phase prompt builders produce well-formed
+``[system, user]`` message lists with the right per-phase content
+shape — no LLM call.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from .fetch import DreamInput, EpisodeRow, FactRow, SessionRow
+from .prompts import (
+ MAX_DEMOTIONS_PER_PASS,
+ MAX_PROPOSALS_PER_PASS,
+ MAX_WRITES_PER_PASS,
+ build_consolidate_prompt,
+ build_recombine_prompt,
+ build_sanitize_prompt,
+)
+
+
+def _build_bundle() -> DreamInput:
+ return DreamInput(
+ user_id="u-1",
+ group_id="g-1",
+ window_start=datetime(2026, 5, 1, tzinfo=timezone.utc),
+ window_end=datetime(2026, 5, 14, tzinfo=timezone.utc),
+ episodes=[
+ EpisodeRow(
+ uuid="ep-1",
+ name="conversation",
+ content="User: I love Belgian chocolate",
+ source_description="msg",
+ valid_at="2026-05-10",
+ created_at="2026-05-10",
+ ),
+ ],
+ facts=[
+ FactRow(
+ uuid="f-1",
+ source="Nick",
+ target="Belgian chocolate",
+ name="loves",
+ fact="Nick loves Belgian chocolate",
+ scope="real:global",
+ confidence=0.9,
+ status="active",
+ created_at="2026-05-10",
+ ),
+ FactRow(
+ uuid="f-2",
+ source="Nick",
+ target="ProjectX",
+ name="works_on",
+ fact="Nick works on ProjectX",
+ scope="project:x",
+ confidence=0.8,
+ status="active",
+ created_at="2026-05-10",
+ ),
+ ],
+ recent_sessions=[
+ SessionRow(
+ session_id="s-1",
+ title="Chat about food",
+ created_at=datetime(2026, 5, 10, tzinfo=timezone.utc),
+ body="user: I love Belgian chocolate\nassistant: noted",
+ ),
+ ],
+ known_fact_uuids={"f-1", "f-2"},
+ known_episode_uuids={"ep-1"},
+ )
+
+
+def test_consolidate_prompt_has_system_and_user_messages():
+ msgs = build_consolidate_prompt(_build_bundle())
+ assert [m["role"] for m in msgs] == ["system", "user"]
+ user_body = msgs[1]["content"]
+ # The input bundle's episode body, facts, and session content should all
+ # appear so the model has everything to consolidate from.
+ assert "ep-1" in user_body
+ assert "f-1" in user_body
+ assert "Belgian chocolate" in user_body
+ # Per-scope grouping in the facts section
+ assert "[scope=real:global]" in user_body
+ assert "[scope=project:x]" in user_body
+
+
+def test_recombine_prompt_includes_consolidated_output_and_active_facts():
+ bundle = _build_bundle()
+ consolidated_json = '{"facts": [{"content": "consolidated"}]}'
+ msgs = build_recombine_prompt(bundle, consolidated_json)
+ assert msgs[0]["role"] == "system"
+ assert "recombination" in msgs[0]["content"].lower()
+ assert consolidated_json in msgs[1]["content"]
+ assert "f-1" in msgs[1]["content"]
+
+
+def test_sanitize_prompt_includes_known_fact_uuids_for_demotion_guard():
+ """Sanitizer prompt MUST contain the allowlist so the sanitizer can
+ reject invented uuids in demotions. Regression guard: if this drops
+ out of the prompt, the runaway-demotion bug per p0-spec §3 comes back."""
+ bundle = _build_bundle()
+ msgs = build_sanitize_prompt(bundle, '{"facts": []}', '{"proposals": []}')
+ assert msgs[0]["role"] == "system"
+ user_body = msgs[1]["content"]
+ # Both known fact uuids surfaced as the demotion allowlist
+ assert "f-1" in user_body
+ assert "f-2" in user_body
+ # Hard caps mentioned in the system prompt (so the model can self-trim)
+ sys = msgs[0]["content"]
+ assert str(MAX_DEMOTIONS_PER_PASS) in sys
+ assert str(MAX_PROPOSALS_PER_PASS) in sys
+ assert str(MAX_WRITES_PER_PASS) in sys
+
+
+def test_sanitize_prompt_surfaces_stale_fact_candidates():
+ """The staleness heuristics flag candidates for the sanitizer to
+ judge. If this section drops out of the prompt, P0.3a fails
+ silently — the sanitizer would never see the candidates and
+ couldn't issue stale-fact demotions even when warranted."""
+ bundle = DreamInput(
+ user_id="u-1",
+ group_id="g-1",
+ window_start=datetime(2026, 5, 1, tzinfo=timezone.utc),
+ window_end=datetime(2026, 5, 14, tzinfo=timezone.utc),
+ facts=[
+ # Stale candidate — fires the version + recency heuristics.
+ FactRow(
+ uuid="stale-1",
+ source=None,
+ target=None,
+ name=None,
+ fact="GPT-4 is the best LLM available",
+ scope="real:global",
+ confidence=0.8,
+ status="active",
+ created_at="2024-01-01T00:00:00Z",
+ ),
+ # Stable fact — fires no heuristics.
+ FactRow(
+ uuid="stable-1",
+ source=None,
+ target=None,
+ name=None,
+ fact="user's birthday is March 5",
+ scope="real:global",
+ confidence=0.9,
+ status="active",
+ created_at="2024-01-01T00:00:00Z",
+ ),
+ ],
+ known_fact_uuids={"stale-1", "stable-1"},
+ )
+ msgs = build_sanitize_prompt(bundle, "{}", "{}")
+ user_body = msgs[1]["content"]
+ assert "Stale-fact candidates" in user_body
+ assert "uuid=stale-1" in user_body
+ # Guardrail: the stable fact must NOT appear as a candidate
+ assert (
+ "uuid=stable-1"
+ not in user_body.split("Stale-fact candidates")[1].split("Active facts")[0]
+ )
+
+
+def test_sanitize_prompt_emits_no_stale_candidates_placeholder_when_clean():
+ """Clean fact set → placeholder text, not a missing section. The
+ sanitizer's prompt structure must be stable across runs."""
+ bundle = DreamInput(
+ user_id="u",
+ group_id="g",
+ window_start=datetime(2026, 5, 1, tzinfo=timezone.utc),
+ window_end=datetime(2026, 5, 14, tzinfo=timezone.utc),
+ facts=[
+ FactRow(
+ uuid="stable",
+ source=None,
+ target=None,
+ name=None,
+ fact="user prefers dark mode",
+ scope="real:global",
+ confidence=0.9,
+ status="active",
+ created_at=None,
+ ),
+ ],
+ known_fact_uuids={"stable"},
+ )
+ msgs = build_sanitize_prompt(bundle, "{}", "{}")
+ assert "(no stale-fact candidates flagged this pass)" in msgs[1]["content"]
+
+
+def test_prompts_tolerate_empty_inputs():
+ """A bundle with no episodes / facts / sessions still produces valid
+ prompts — the model should answer with an empty list."""
+ bundle = DreamInput(
+ user_id="u",
+ group_id="g",
+ window_start=datetime.now(timezone.utc),
+ window_end=datetime.now(timezone.utc),
+ )
+ consolidate_msgs = build_consolidate_prompt(bundle)
+ recombine_msgs = build_recombine_prompt(bundle, "{}")
+ sanitize_msgs = build_sanitize_prompt(bundle, "{}", "{}")
+ assert len(consolidate_msgs) == 2
+ assert len(recombine_msgs) == 2
+ assert len(sanitize_msgs) == 2
+ assert "(no recent episodes in window)" in consolidate_msgs[1]["content"]
+ assert "(no active facts)" in consolidate_msgs[1]["content"]
diff --git a/autogpt_platform/backend/backend/copilot/dream/ratification.py b/autogpt_platform/backend/backend/copilot/dream/ratification.py
new file mode 100644
index 0000000000..98675fe824
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/ratification.py
@@ -0,0 +1,361 @@
+"""Ratification loop for ``status='tentative'`` dream proposals (P-0.4).
+
+A tentative MemoryFact edge written by ``apply.py`` is on probation:
+either warm-context retrieval proves it useful within a grace period
+(at which point we promote it to ``status='active'``), or the grace
+period elapses with zero hits and the edge is superseded with
+``reason='unratified'``.
+
+This module owns the pass logic itself. The Redis hit tracker lives
+in ``ratification_hits.py`` so this file stays focused on the
+promote-vs-supersede dispatch and fits the file-length budget.
+
+Per ``dream/p0-spec.md`` §5. The metric ``dream_ratification_rate``
+(P0.4d) is out of scope for this module — counts are logged at INFO
+and surfaced via ``RatificationResult`` for the scheduler wrapper.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from backend.copilot.graphiti.client import derive_group_id
+from backend.copilot.graphiti.config import graphiti_config
+from backend.copilot.graphiti.falkordb_driver import AutoGPTFalkorDriver
+from backend.copilot.tools.graphiti_forget import mark_edges_superseded
+
+from .ratification_hits import (
+ HIT_TRACKER_KEY_PREFIX,
+ RATIFICATION_GRACE_PERIOD,
+ get_hit_count,
+ parse_created_at,
+ record_memory_hit,
+)
+
+logger = logging.getLogger(__name__)
+
+# Re-export so callers (scheduler wrapper, warm-context retrieval, the
+# nightly batch fan-out) only have to know one module name.
+__all__ = (
+ "HIT_TRACKER_KEY_PREFIX",
+ "RATIFICATION_GRACE_PERIOD",
+ "RatificationResult",
+ "record_memory_hit",
+ "run_ratification_pass",
+ "try_ratify_on_hit",
+)
+
+
+class RatificationResult(BaseModel):
+ """Structured outcome of a single ratification pass.
+
+ Surfaced via the scheduler wrapper so admin / future metrics can
+ read promotion vs. supersession counts without re-scanning Graphiti.
+ """
+
+ user_id: str
+ started_at: datetime
+ completed_at: datetime | None = None
+ examined_count: int = 0
+ ratified_count: int = 0
+ superseded_count: int = 0
+ error: str | None = None
+ skipped: bool = False
+ skip_reason: str | None = None
+ per_edge_errors: list[str] = Field(default_factory=list)
+
+
+async def run_ratification_pass(user_id: str) -> RatificationResult:
+ """Promote or supersede every ``status='tentative'`` edge for one user.
+
+ Defensive in two ways:
+ * Catastrophic failure (invalid user, no graph, Redis down) is
+ captured in ``RatificationResult.error`` rather than raised so
+ the scheduler wrapper logs cleanly instead of crashing the job.
+ * Per-edge failure is captured in ``per_edge_errors`` so one bad
+ edge can't poison the rest of the pass.
+ """
+ started_at = datetime.now(timezone.utc)
+ result = RatificationResult(user_id=user_id, started_at=started_at)
+
+ try:
+ group_id = derive_group_id(user_id)
+ except ValueError as exc:
+ result.error = f"invalid_user_id: {exc}"
+ result.completed_at = datetime.now(timezone.utc)
+ logger.warning(
+ "Ratification skipped — invalid user_id %s: %s", user_id[:12], exc
+ )
+ return result
+
+ driver = AutoGPTFalkorDriver(
+ host=graphiti_config.falkordb_host,
+ port=graphiti_config.falkordb_port,
+ password=graphiti_config.falkordb_password or None,
+ database=group_id,
+ # Indices live with the chat-write client; skip the
+ # background-task race that produces "Buffer is closed" spam.
+ build_indices=False,
+ )
+ try:
+ try:
+ tentatives = await _list_tentative_edges(driver)
+ except Exception as exc:
+ result.error = f"list_tentative_edges_failed: {exc}"
+ result.completed_at = datetime.now(timezone.utc)
+ logger.warning(
+ "Ratification list failed for user %s",
+ user_id[:12],
+ exc_info=True,
+ )
+ return result
+
+ result.examined_count = len(tentatives)
+ if not tentatives:
+ result.completed_at = datetime.now(timezone.utc)
+ logger.info(
+ "Ratification no-op for user %s — no tentative edges",
+ user_id[:12],
+ )
+ return result
+
+ now = datetime.now(timezone.utc)
+ for edge in tentatives:
+ try:
+ await _process_edge(
+ user_id=user_id,
+ driver=driver,
+ edge=edge,
+ now=now,
+ result=result,
+ )
+ except Exception as exc:
+ # Per-edge defense: capture and continue so the pass
+ # finishes for the rest of the user's tentatives.
+ result.per_edge_errors.append(
+ f"{edge.get('uuid', '?')}: {type(exc).__name__}: {exc}"
+ )
+ logger.warning(
+ "Ratification per-edge failure for user %s edge %s",
+ user_id[:12],
+ edge.get("uuid", "?"),
+ exc_info=True,
+ )
+ finally:
+ await driver.close()
+
+ result.completed_at = datetime.now(timezone.utc)
+ logger.info(
+ "Ratification complete for user %s: examined=%d ratified=%d superseded=%d errors=%d",
+ user_id[:12],
+ result.examined_count,
+ result.ratified_count,
+ result.superseded_count,
+ len(result.per_edge_errors),
+ )
+ return result
+
+
+# ---------------------------------------------------------------------------
+# Internals
+# ---------------------------------------------------------------------------
+
+
+async def _process_edge(
+ *,
+ user_id: str,
+ driver: AutoGPTFalkorDriver,
+ edge: dict[str, Any],
+ now: datetime,
+ result: RatificationResult,
+) -> None:
+ """Promote, supersede, or leave alone one tentative edge.
+
+ Decision table (spec §5):
+ * hits >= 1 → promote to ``status='active'``
+ * hits == 0 and past grace → supersede with ``reason='unratified'``
+ * hits == 0 within grace → no-op (still earning its keep)
+ """
+ edge_uuid = edge.get("uuid")
+ if not edge_uuid:
+ result.per_edge_errors.append("missing_uuid")
+ return
+
+ hits = await _get_hit_count(user_id, edge_uuid)
+
+ if hits >= 1:
+ promoted = await _promote_edge(driver, edge_uuid)
+ if promoted:
+ result.ratified_count += 1
+ return
+
+ created_at = parse_created_at(edge.get("created_at"))
+ if created_at is None:
+ # Edge without a created_at — be safe and leave it alone rather
+ # than supersede something we can't date.
+ result.per_edge_errors.append(f"{edge_uuid}: missing_created_at")
+ return
+
+ if now - created_at <= RATIFICATION_GRACE_PERIOD:
+ return
+
+ succeeded, _failed = await mark_edges_superseded(
+ driver,
+ [edge_uuid],
+ reason="unratified",
+ new_status="superseded",
+ user_id=user_id,
+ )
+ if succeeded:
+ result.superseded_count += 1
+
+
+async def _list_tentative_edges(
+ driver: AutoGPTFalkorDriver,
+) -> list[dict[str, Any]]:
+ """Return ``status='tentative'`` edges with their uuid and created_at.
+
+ Excludes edges that are already retracted (``expired_at IS NOT NULL``)
+ so an edge demoted by a parallel operation isn't ratified back to life.
+ """
+ query = """
+ MATCH ()-[e:RELATES_TO]->()
+ WHERE e.status = 'tentative' AND e.expired_at IS NULL
+ RETURN e.uuid AS uuid, e.created_at AS created_at
+ """
+ result = await driver.execute_query(query)
+ records = result[0] if result else []
+ return [{"uuid": r["uuid"], "created_at": r["created_at"]} for r in records]
+
+
+async def _promote_edge(driver: AutoGPTFalkorDriver, edge_uuid: str) -> bool:
+ """Flip a tentative edge to ``status='active'`` with a ratified_at stamp.
+
+ Returns True iff Cypher actually touched a row. Sub-10ms per spec §5.
+
+ The ratified_at timestamp is generated in Python because FalkorDB
+ does not implement Cypher's no-arg ``datetime()`` function.
+ """
+ query = """
+ MATCH ()-[e:RELATES_TO {uuid: $uuid}]->()
+ SET e.status = 'active', e.ratified_at = $now
+ RETURN e.uuid AS uuid
+ """
+ result = await driver.execute_query(
+ query, uuid=edge_uuid, now=datetime.now(timezone.utc).isoformat()
+ )
+ records = result[0] if result else []
+ return bool(records)
+
+
+async def try_ratify_on_hit(user_id: str, edge_uuids: list[str]) -> int:
+ """Record warm-context hits and promote any tentative edges inline.
+
+ Called from warm-context retrieval (``graphiti/context.py``) once
+ per turn with the list of edge uuids that landed in the user's
+ context. For each uuid we:
+
+ 1. Bump the ``mem:hits:{user_id}:{edge_uuid}`` Redis counter
+ (so the nightly ratification sweep also sees the hit and
+ agrees on promotion if Cypher fails here).
+ 2. Issue a targeted Cypher ``SET status='active'`` filtered by
+ ``status='tentative' AND expired_at IS NULL`` — already-active
+ and already-retracted edges are no-ops via the WHERE clause.
+
+ Returns the count of edges this call actually promoted. The
+ function is **safe to fire-and-forget** from the retrieval path:
+ failures are caught and logged, never raised; the user's chat
+ turn is never blocked on this.
+
+ Per the architecture plan, this is the sync hit-time half of P0.4
+ ratification. The nightly batch's ratification sweep still owns
+ grace-period supersession; with this hook landing, the sweep
+ rarely promotes (most tentatives get hit at least once within a
+ day) and primarily cleans up the truly-unused.
+ """
+ if not edge_uuids:
+ return 0
+ if not user_id:
+ return 0
+
+ # Step 1: bump hit counters (Redis, best-effort, swallows errors).
+ # Done before the Cypher promotion so the counter survives even
+ # when the promotion path fails.
+ for uuid in edge_uuids:
+ await record_memory_hit(user_id, uuid)
+
+ # Step 2: targeted Cypher promotion. We open our own driver here
+ # because callers are warm-context retrieval call sites that have
+ # a higher-level graphiti client but no raw driver — and we want
+ # the brief write-lock semantics to be local to this function.
+ try:
+ group_id = derive_group_id(user_id)
+ except ValueError as exc:
+ logger.debug("try_ratify_on_hit: invalid user_id %s: %s", user_id[:12], exc)
+ return 0
+
+ promoted_count = 0
+ driver = AutoGPTFalkorDriver(
+ host=graphiti_config.falkordb_host,
+ port=graphiti_config.falkordb_port,
+ password=graphiti_config.falkordb_password or None,
+ database=group_id,
+ # Indices live with the chat-write client; skip the
+ # background-task race that produces "Buffer is closed" spam.
+ build_indices=False,
+ )
+ try:
+ for uuid in edge_uuids:
+ try:
+ if await _promote_if_tentative(driver, uuid):
+ promoted_count += 1
+ except Exception:
+ # Per-edge: log + continue. One bad uuid mustn't poison
+ # the rest of the retrieved set.
+ logger.debug(
+ "try_ratify_on_hit: Cypher failed for user %s edge %s",
+ user_id[:12],
+ uuid,
+ exc_info=True,
+ )
+ finally:
+ await driver.close()
+
+ if promoted_count:
+ logger.info(
+ "Ratification hit-hook promoted %d edge(s) for user %s",
+ promoted_count,
+ user_id[:12],
+ )
+ return promoted_count
+
+
+async def _promote_if_tentative(driver: AutoGPTFalkorDriver, edge_uuid: str) -> bool:
+ """``_promote_edge`` with a ``status='tentative'`` guard.
+
+ Distinct from ``_promote_edge`` because the hit-hook fires on
+ EVERY retrieved edge, including already-active ones — we don't
+ want to overwrite an active edge's ``ratified_at`` with a fresh
+ timestamp on every retrieval. The guard makes the call idempotent.
+ """
+ query = """
+ MATCH ()-[e:RELATES_TO {uuid: $uuid}]->()
+ WHERE e.status = 'tentative' AND e.expired_at IS NULL
+ SET e.status = 'active', e.ratified_at = $now
+ RETURN e.uuid AS uuid
+ """
+ result = await driver.execute_query(
+ query, uuid=edge_uuid, now=datetime.now(timezone.utc).isoformat()
+ )
+ records = result[0] if result else []
+ return bool(records)
+
+
+# Local indirection so tests can mock ``_get_hit_count`` on this module
+# rather than the helper module (matches the poison-pill test pattern).
+async def _get_hit_count(user_id: str, edge_uuid: str) -> int:
+ return await get_hit_count(user_id, edge_uuid)
diff --git a/autogpt_platform/backend/backend/copilot/dream/ratification_hits.py b/autogpt_platform/backend/backend/copilot/dream/ratification_hits.py
new file mode 100644
index 0000000000..a70e55a892
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/ratification_hits.py
@@ -0,0 +1,115 @@
+"""Redis hit tracker for tentative MemoryFact edges.
+
+Owns the ``mem:hits:{user_id}:{edge_uuid}`` key shape and the
+INCR/read paths the ratification pass consults. Kept in its own
+module so ``ratification.py`` stays focused on the pass logic and
+fits the file-length budget.
+
+Wiring note: warm-context retrieval (``graphiti/context.py``) fires
+``ratification.try_ratify_on_hit`` for every retrieved edge, which
+both bumps the counter here (via ``record_memory_hit``) and promotes
+tentative edges inline. The nightly ratification sweep therefore
+rarely promotes — it primarily owns grace-period supersession of
+tentatives that never earned a hit.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Grace period a tentative edge has to earn a warm-context hit before
+# being superseded. Spec §5 mandates 30 days so even low-cadence users
+# get several sessions worth of opportunities to retrieve the memory.
+RATIFICATION_GRACE_PERIOD = timedelta(days=30)
+
+# Redis key prefix for warm-context hit tracking. One key per
+# (user, edge) so we can INCR without contention and let TTL clean up
+# automatically. Format: ``mem:hits:{user_id}:{edge_uuid}``.
+HIT_TRACKER_KEY_PREFIX = "mem:hits"
+
+
+async def record_memory_hit(user_id: str, edge_uuid: str) -> None:
+ """INCR the Redis hit counter for one tentative edge.
+
+ Called from any code path that surfaces a tentative edge to the
+ user (warm-context retrieval, recall tool results, etc.). TTL is
+ refreshed to the full grace period on every hit so a tentative
+ edge that keeps getting used stays in the counter until ratified.
+
+ Failures are swallowed: a missing hit doesn't break chat, and the
+ next call site can record it instead. If Redis is down for a long
+ stretch, the worst case is unhit tentatives get superseded — the
+ spec already treats that as the safe direction.
+ """
+ try:
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ key = hit_key(user_id, edge_uuid)
+ ttl_seconds = int(RATIFICATION_GRACE_PERIOD.total_seconds())
+ # SET with NX + EX seeds the key with TTL, then INCR (which
+ # never touches TTL), then EXPIRE so every hit refreshes the
+ # window to the full grace period. All three are single-key
+ # commands, so this stays cluster-safe.
+ await redis.set(key, 0, nx=True, ex=ttl_seconds)
+ await redis.incr(key)
+ await redis.expire(key, ttl_seconds)
+ except Exception:
+ logger.debug(
+ "record_memory_hit failed for user %s edge %s",
+ user_id[:12],
+ edge_uuid,
+ exc_info=True,
+ )
+
+
+async def get_hit_count(user_id: str, edge_uuid: str) -> int:
+ """Read the Redis hit counter for one edge. Missing key → 0."""
+ try:
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ raw = await redis.get(hit_key(user_id, edge_uuid))
+ if raw is None:
+ return 0
+ if isinstance(raw, bytes):
+ raw = raw.decode("utf-8", errors="ignore")
+ return int(raw)
+ except Exception:
+ # Redis hiccup: treat as zero hits. The edge stays tentative
+ # until the grace period elapses; we never falsely promote.
+ logger.debug(
+ "hit-count read failed for user %s edge %s",
+ user_id[:12],
+ edge_uuid,
+ exc_info=True,
+ )
+ return 0
+
+
+def hit_key(user_id: str, edge_uuid: str) -> str:
+ return f"{HIT_TRACKER_KEY_PREFIX}:{user_id}:{edge_uuid}"
+
+
+def parse_created_at(value: Any) -> datetime | None:
+ """Best-effort coerce FalkorDB's ``created_at`` into an aware datetime.
+
+ FalkorDB returns either a native datetime (Python driver) or a
+ string for some property paths. The ratification clock is in UTC
+ everywhere; naive values are assumed UTC rather than rejected.
+ """
+ if value is None:
+ return None
+ if isinstance(value, datetime):
+ return value if value.tzinfo else value.replace(tzinfo=timezone.utc)
+ if isinstance(value, str):
+ try:
+ parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+ except ValueError:
+ return None
+ return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+ return None
diff --git a/autogpt_platform/backend/backend/copilot/dream/ratification_test.py b/autogpt_platform/backend/backend/copilot/dream/ratification_test.py
new file mode 100644
index 0000000000..83487e5bc9
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/ratification_test.py
@@ -0,0 +1,474 @@
+"""Ratification pass tests — mock Graphiti driver + Redis at the
+boundary, verify each tentative-edge outcome produces the right
+Cypher / mark_edges_superseded call and the right counters.
+
+These tests do NOT touch FalkorDB or a live Redis. ratification.py
+opens an ``AutoGPTFalkorDriver`` for its own Cypher and calls
+``mark_edges_superseded`` for demotions; both are patched at the
+module surface so the dispatch logic can be exercised in isolation.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from . import ratification as ratification_mod
+from .ratification import (
+ RATIFICATION_GRACE_PERIOD,
+ RatificationResult,
+ run_ratification_pass,
+)
+from .ratification_hits import hit_key, record_memory_hit
+
+
+def _make_driver(records_for_list: list[dict], records_for_promote=None):
+ """Build a MagicMock driver whose execute_query returns the rows we want.
+
+ The ratification module issues two Cypher shapes:
+ * the LIST query (status='tentative') → return ``records_for_list``
+ * the PROMOTE query (SET status=active) → return ``records_for_promote``
+
+ We dispatch by inspecting the first arg of execute_query.
+ """
+ driver = MagicMock()
+ driver.close = AsyncMock(return_value=None)
+
+ async def fake_execute(query: str, **kwargs):
+ if "status = 'tentative'" in query:
+ return (list(records_for_list), None, None)
+ if "ratified_at" in query:
+ # Promote query — default to one-row response unless caller said otherwise.
+ rows = (
+ records_for_promote
+ if records_for_promote is not None
+ else [{"uuid": kwargs.get("uuid")}]
+ )
+ return (list(rows), None, None)
+ return ([], None, None)
+
+ driver.execute_query = AsyncMock(side_effect=fake_execute)
+ return driver
+
+
[email protected](autouse=True)
+def _patch_driver_constructor(mocker):
+ """Default to a no-tentative-edges driver; individual tests override."""
+ driver = _make_driver(records_for_list=[])
+ mocker.patch.object(
+ ratification_mod,
+ "AutoGPTFalkorDriver",
+ MagicMock(return_value=driver),
+ )
+ return driver
+
+
+def stub_mark_superseded(mocker):
+ """Stub mark_edges_superseded so we can assert it was (or wasn't) called."""
+ stub = AsyncMock(side_effect=lambda driver, uuids, **kw: (list(uuids), []))
+ mocker.patch.object(ratification_mod, "mark_edges_superseded", stub)
+ return stub
+
+
+def fake_redis(mocker):
+ """Stub the Redis client used by the hit-count read path.
+
+ Tests set ``fake_redis.hits[edge_uuid] = N`` to control the count
+ a given edge sees. Default is zero.
+ """
+
+ class FakeRedis:
+ def __init__(self):
+ self.hits: dict[str, int] = {}
+ self.expire_calls: list[tuple[str, int]] = []
+
+ async def get(self, key: str):
+ # Keys are ``mem:hits:{user_id}:{edge_uuid}`` — split off the uuid.
+ edge_uuid = key.rsplit(":", 1)[-1]
+ value = self.hits.get(edge_uuid, 0)
+ return str(value).encode() if value else None
+
+ async def set(self, key: str, value, **kwargs):
+ return True
+
+ async def incr(self, key: str):
+ edge_uuid = key.rsplit(":", 1)[-1]
+ self.hits[edge_uuid] = self.hits.get(edge_uuid, 0) + 1
+ return self.hits[edge_uuid]
+
+ async def expire(self, key: str, ttl_seconds: int):
+ self.expire_calls.append((key, ttl_seconds))
+ return True
+
+ redis = FakeRedis()
+ mocker.patch(
+ "backend.data.redis_client.get_redis_async",
+ AsyncMock(return_value=redis),
+ )
+ return redis
+
+
+async def test_tentative_edge_with_hits_is_ratified_to_active(
+ mocker, fake_redis, stub_mark_superseded
+):
+ """Hit count >= 1 → flip to active via the promote Cypher; no demotion."""
+ edge = {"uuid": "edge-hot", "created_at": _hours_ago(2)}
+ driver = _make_driver(records_for_list=[edge])
+ mocker.patch.object(
+ ratification_mod, "AutoGPTFalkorDriver", MagicMock(return_value=driver)
+ )
+ fake_redis.hits["edge-hot"] = 3
+
+ result = await run_ratification_pass("u-ratified")
+
+ assert isinstance(result, RatificationResult)
+ assert result.ratified_count == 1
+ assert result.superseded_count == 0
+ assert result.examined_count == 1
+ assert result.error is None
+ # Promote query was issued
+ promote_calls = [
+ call
+ for call in driver.execute_query.await_args_list
+ if "ratified_at" in call.args[0]
+ ]
+ assert len(promote_calls) == 1
+ # ``now`` is bound from Python because FalkorDB doesn't implement
+ # Cypher's no-arg ``datetime()``; assert it's present without
+ # pinning the actual timestamp value.
+ assert promote_calls[0].kwargs["uuid"] == "edge-hot"
+ assert "now" in promote_calls[0].kwargs
+ # And demotion was NOT called
+ stub_mark_superseded.assert_not_awaited()
+
+
+async def test_tentative_edge_without_hits_past_grace_is_superseded_as_unratified(
+ mocker, fake_redis, stub_mark_superseded
+):
+ """Zero hits, edge older than the grace window → mark_edges_superseded(reason='unratified')."""
+ edge = {
+ "uuid": "edge-stale",
+ "created_at": _days_ago(RATIFICATION_GRACE_PERIOD.days + 2),
+ }
+ driver = _make_driver(records_for_list=[edge])
+ mocker.patch.object(
+ ratification_mod, "AutoGPTFalkorDriver", MagicMock(return_value=driver)
+ )
+
+ result = await run_ratification_pass("u-stale")
+
+ assert result.superseded_count == 1
+ assert result.ratified_count == 0
+ stub_mark_superseded.assert_awaited_once()
+ call = stub_mark_superseded.await_args
+ assert call.args[1] == ["edge-stale"]
+ assert call.kwargs["reason"] == "unratified"
+ assert call.kwargs["new_status"] == "superseded"
+
+
+async def test_tentative_edge_within_grace_without_hits_is_untouched(
+ mocker, fake_redis, stub_mark_superseded
+):
+ """Zero hits but still inside the grace window → no promote, no demote."""
+ edge = {"uuid": "edge-young", "created_at": _hours_ago(6)}
+ driver = _make_driver(records_for_list=[edge])
+ mocker.patch.object(
+ ratification_mod, "AutoGPTFalkorDriver", MagicMock(return_value=driver)
+ )
+
+ result = await run_ratification_pass("u-young")
+
+ assert result.ratified_count == 0
+ assert result.superseded_count == 0
+ assert result.examined_count == 1
+ stub_mark_superseded.assert_not_awaited()
+ # No promote query was issued either
+ promote_calls = [
+ call
+ for call in driver.execute_query.await_args_list
+ if "ratified_at" in call.args[0]
+ ]
+ assert promote_calls == []
+
+
+def test_grace_period_is_thirty_days_per_spec():
+ """Spec §5: tentative edges get 30 days to earn a hit before they
+ are superseded. Pin the constant so a shorter window (which would
+ silently drop correct memories for low-cadence users) can't sneak
+ back in."""
+ assert RATIFICATION_GRACE_PERIOD == timedelta(days=30)
+
+
+async def test_unhit_edge_just_inside_grace_window_is_untouched(
+ mocker, fake_redis, stub_mark_superseded
+):
+ """Boundary: zero hits with one hour of grace left → still a no-op.
+ Derived from RATIFICATION_GRACE_PERIOD so the boundary moves with
+ the constant rather than re-encoding a day count."""
+ created_at = datetime.now(timezone.utc) - (
+ RATIFICATION_GRACE_PERIOD - timedelta(hours=1)
+ )
+ edge = {"uuid": "edge-near-boundary", "created_at": created_at}
+ driver = _make_driver(records_for_list=[edge])
+ mocker.patch.object(
+ ratification_mod, "AutoGPTFalkorDriver", MagicMock(return_value=driver)
+ )
+
+ result = await run_ratification_pass("u-near-boundary")
+
+ assert result.ratified_count == 0
+ assert result.superseded_count == 0
+ assert result.examined_count == 1
+ stub_mark_superseded.assert_not_awaited()
+
+
+async def test_already_active_edges_are_not_in_scope_of_the_listing_query(
+ mocker, fake_redis, stub_mark_superseded
+):
+ """The list query filters ``status='tentative'`` so active edges are
+ invisible to the pass — no examined, no ratified, no superseded."""
+ # The default fixture returns zero tentative edges. An already-active
+ # edge would not show up in the list query; we model that by leaving
+ # the list empty here.
+ driver = _make_driver(records_for_list=[])
+ mocker.patch.object(
+ ratification_mod, "AutoGPTFalkorDriver", MagicMock(return_value=driver)
+ )
+
+ result = await run_ratification_pass("u-only-active")
+
+ assert result.examined_count == 0
+ assert result.ratified_count == 0
+ assert result.superseded_count == 0
+ stub_mark_superseded.assert_not_awaited()
+
+
+async def test_empty_user_with_no_tentative_edges_returns_zero_counts_no_error(
+ fake_redis, stub_mark_superseded
+):
+ """User with no tentative edges → counts all zero, no error, completed_at set."""
+ result = await run_ratification_pass("u-empty")
+
+ assert result.error is None
+ assert result.examined_count == 0
+ assert result.ratified_count == 0
+ assert result.superseded_count == 0
+ assert result.completed_at is not None
+ stub_mark_superseded.assert_not_awaited()
+
+
+async def test_per_edge_failure_does_not_kill_the_rest_of_the_pass(
+ mocker, fake_redis, stub_mark_superseded
+):
+ """A poison-pill edge raises mid-pass; the others still get processed,
+ and the failure is captured in ``per_edge_errors`` rather than raised."""
+ edges = [
+ {"uuid": "edge-good-hot", "created_at": _hours_ago(2)},
+ {"uuid": "edge-poison", "created_at": _hours_ago(2)},
+ {
+ "uuid": "edge-good-stale",
+ "created_at": _days_ago(RATIFICATION_GRACE_PERIOD.days + 2),
+ },
+ ]
+ driver = _make_driver(records_for_list=edges)
+ mocker.patch.object(
+ ratification_mod, "AutoGPTFalkorDriver", MagicMock(return_value=driver)
+ )
+ fake_redis.hits["edge-good-hot"] = 5
+ # edge-poison: any hit-count read for this edge raises so the
+ # per-edge try/except can catch it without breaking the others.
+ original_get_hit_count = ratification_mod._get_hit_count
+
+ async def hit_count_with_poison(user_id: str, edge_uuid: str) -> int:
+ if edge_uuid == "edge-poison":
+ raise RuntimeError("simulated redis explosion")
+ return await original_get_hit_count(user_id, edge_uuid)
+
+ mocker.patch.object(
+ ratification_mod, "_get_hit_count", side_effect=hit_count_with_poison
+ )
+
+ result = await run_ratification_pass("u-mixed")
+
+ assert result.examined_count == 3
+ # The hot edge got ratified, the stale edge got superseded, the
+ # poison edge contributed to per_edge_errors.
+ assert result.ratified_count == 1
+ assert result.superseded_count == 1
+ assert len(result.per_edge_errors) == 1
+ assert "edge-poison" in result.per_edge_errors[0]
+
+
+# ---------------------------------------------------------------------------
+# record_memory_hit — Redis hit tracker (ratification_hits.py)
+# ---------------------------------------------------------------------------
+
+
+async def test_hit_refreshes_ttl_to_full_grace_period(fake_redis):
+ """Every hit — not just the first — must reset the counter's TTL to
+ the full grace period. Without the EXPIRE after INCR, the TTL set
+ by the initial SET NX EX runs out mid-window and the nightly sweep
+ falsely reads zero hits for an edge that was being used."""
+ grace_seconds = int(RATIFICATION_GRACE_PERIOD.total_seconds())
+
+ await record_memory_hit("u-ttl", "edge-busy")
+ await record_memory_hit("u-ttl", "edge-busy")
+ await record_memory_hit("u-ttl", "edge-busy")
+
+ key = hit_key("u-ttl", "edge-busy")
+ assert fake_redis.expire_calls == [(key, grace_seconds)] * 3
+ assert fake_redis.hits["edge-busy"] == 3
+
+
+async def test_record_memory_hit_swallows_ttl_refresh_failure(fake_redis):
+ """A failing EXPIRE must not propagate to the chat path — the hit
+ itself was still counted, and the next call site refreshes the TTL."""
+
+ async def exploding_expire(key: str, ttl_seconds: int):
+ raise RuntimeError("simulated redis explosion")
+
+ fake_redis.expire = exploding_expire
+
+ await record_memory_hit("u-ttl", "edge-busy")
+
+ assert fake_redis.hits["edge-busy"] == 1
+
+
+# ---------------------------------------------------------------------------
+# try_ratify_on_hit — sync hit-hook fired from warm-context retrieval
+# ---------------------------------------------------------------------------
+
+
+async def test_try_ratify_on_hit_empty_edge_list_returns_zero_without_redis_or_cypher(
+ mocker,
+):
+ """No edges retrieved → no Redis hit recording, no driver opened."""
+ record_spy = mocker.patch.object(
+ ratification_mod, "record_memory_hit", new=AsyncMock()
+ )
+ driver_spy = mocker.patch.object(ratification_mod, "AutoGPTFalkorDriver")
+
+ promoted = await ratification_mod.try_ratify_on_hit("u1", [])
+
+ assert promoted == 0
+ record_spy.assert_not_called()
+ driver_spy.assert_not_called()
+
+
+async def test_try_ratify_on_hit_records_hits_for_every_retrieved_edge(mocker):
+ """Hit counters get bumped for ALL retrieved uuids — the Cypher
+ filter (status='tentative') decides which ones flip; the counter
+ is a separate signal the nightly sweep also reads."""
+ record_spy = AsyncMock()
+ mocker.patch.object(ratification_mod, "record_memory_hit", new=record_spy)
+ # Driver returns no promotions (everything already-active).
+ driver = _make_driver(records_for_list=[], records_for_promote=[])
+ mocker.patch.object(ratification_mod, "AutoGPTFalkorDriver", return_value=driver)
+
+ await ratification_mod.try_ratify_on_hit("u1", ["edge-a", "edge-b", "edge-c"])
+
+ assert record_spy.await_count == 3
+ called_uuids = [c.args[1] for c in record_spy.await_args_list]
+ assert called_uuids == ["edge-a", "edge-b", "edge-c"]
+
+
+async def test_try_ratify_on_hit_returns_count_of_actually_promoted_edges(mocker):
+ """Cypher's WHERE clause filters to status='tentative' only — the
+ returned count is the number that actually flipped, not the
+ number we attempted."""
+ mocker.patch.object(ratification_mod, "record_memory_hit", new=AsyncMock())
+
+ promote_results = iter(
+ [
+ # First uuid promotes (was tentative)
+ [{"uuid": "edge-1"}],
+ # Second uuid: already active, Cypher WHERE filters → no row
+ [],
+ # Third uuid promotes
+ [{"uuid": "edge-3"}],
+ ]
+ )
+
+ driver = MagicMock()
+ driver.close = AsyncMock(return_value=None)
+
+ async def fake_execute(query: str, **kwargs):
+ return (list(next(promote_results)), None, None)
+
+ driver.execute_query = AsyncMock(side_effect=fake_execute)
+ mocker.patch.object(ratification_mod, "AutoGPTFalkorDriver", return_value=driver)
+
+ promoted = await ratification_mod.try_ratify_on_hit(
+ "u1", ["edge-1", "edge-2", "edge-3"]
+ )
+
+ assert promoted == 2
+
+
+async def test_try_ratify_on_hit_swallows_per_edge_cypher_failures(mocker):
+ """One bad Cypher call mustn't poison the rest of the retrieved
+ edges — log + continue."""
+ mocker.patch.object(ratification_mod, "record_memory_hit", new=AsyncMock())
+
+ calls = {"n": 0}
+
+ async def fake_execute(query: str, **kwargs):
+ calls["n"] += 1
+ if kwargs.get("uuid") == "edge-poison":
+ raise RuntimeError("simulated cypher explosion")
+ return ([{"uuid": kwargs.get("uuid")}], None, None)
+
+ driver = MagicMock()
+ driver.close = AsyncMock(return_value=None)
+ driver.execute_query = AsyncMock(side_effect=fake_execute)
+ mocker.patch.object(ratification_mod, "AutoGPTFalkorDriver", return_value=driver)
+
+ promoted = await ratification_mod.try_ratify_on_hit(
+ "u1", ["edge-a", "edge-poison", "edge-c"]
+ )
+
+ # The poison edge errored; the others promoted.
+ assert promoted == 2
+ assert calls["n"] == 3 # all three attempted; one raised
+
+
+async def test_try_ratify_on_hit_empty_user_id_is_noop(mocker):
+ record_spy = mocker.patch.object(
+ ratification_mod, "record_memory_hit", new=AsyncMock()
+ )
+ driver_spy = mocker.patch.object(ratification_mod, "AutoGPTFalkorDriver")
+ promoted = await ratification_mod.try_ratify_on_hit("", ["edge-a"])
+ assert promoted == 0
+ record_spy.assert_not_called()
+ driver_spy.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _hours_ago(n: int) -> datetime:
+ return datetime.now(timezone.utc) - timedelta(hours=n)
+
+
+def _days_ago(n: int) -> datetime:
+ return datetime.now(timezone.utc) - timedelta(days=n)
diff --git a/autogpt_platform/backend/backend/copilot/dream/routing.py b/autogpt_platform/backend/backend/copilot/dream/routing.py
new file mode 100644
index 0000000000..e751e4dcb2
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/routing.py
@@ -0,0 +1,74 @@
+"""Decide which execution path a dream pass runs through.
+
+Per ``dream/p0-spec.md`` §13, the dream pass must work on every
+transport (openrouter / subscription / openai_compat / local). Two
+batch APIs are supported (both Anthropic and OpenAI offer a 50%
+discount); we route to whichever has a direct API key present + the
+batch flag on. Anything else falls back to the synchronous baseline
+path through the existing ``copilot_executor``.
+
+Slice 1 of P-0 ships sync-baseline only. Both batch paths land in
+task #33 (P0.1). This resolver is wired from day one so adding the
+batch executors is just flipping the conditional below.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from backend.copilot.config import TransportName
+
+# Kept in sync with ``model_pricing.ExecutionPath`` so the discount
+# table in model_pricing.py reads our chosen path directly. If you add
+# a new path here, mirror it there.
+ExecutionPath = Literal["sync_baseline", "anthropic_batch", "openai_batch"]
+
+
+# Transports that cannot honour a batch path even when an Anthropic /
+# OpenAI key is configured separately.
+#
+# - ``"local"`` — local backends (Ollama, vLLM, …) don't expose batch
+# endpoints; even if the operator set ``ANTHROPIC_API_KEY`` for some
+# unrelated reason, the dream pass should stay on the local LLM that
+# the rest of the install uses (and that ``CHAT_USE_LOCAL=true``
+# explicitly opted in to).
+# - ``"subscription"`` — the chat layer authenticates via Claude Code
+# OAuth (no API key); dual-billing the user's Anthropic API key for
+# the dream pass would surprise the operator and split the cost-log
+# audit trail across two surfaces. Force sync so dream + chat
+# continue to roll up under the same provider label
+# (``cost_log_provider="anthropic"``).
+_TRANSPORTS_FORCE_SYNC: frozenset[TransportName] = frozenset({"local", "subscription"})
+
+
+def resolve_dream_execution_path(
+ *,
+ has_anthropic_key: bool,
+ has_openai_key: bool = False,
+ batch_processing_enabled: bool = False,
+ transport_name: TransportName | None = None,
+) -> ExecutionPath:
+ """Pick the dream pass execution path.
+
+ Both batch paths require their respective provider API key AND the
+ ``batch_processing_enabled`` flag. Anthropic batch is preferred
+ when both keys are present (better cache pricing for the consolidation
+ + sanitization phases that share context). Falls back to sync_baseline
+ when no batch path is viable — slower and pricier per pass, but
+ works on every transport.
+
+ ``transport_name`` (when provided) takes precedence over the key
+ flags: ``"local"`` and ``"subscription"`` always force
+ ``sync_baseline`` regardless of which API keys happen to be set
+ (see ``_TRANSPORTS_FORCE_SYNC`` above for the rationale).
+ Defaults to ``None`` so callers that don't know their transport
+ still get the historical key-driven behaviour.
+ """
+ if transport_name in _TRANSPORTS_FORCE_SYNC:
+ return "sync_baseline"
+ if batch_processing_enabled:
+ if has_anthropic_key:
+ return "anthropic_batch"
+ if has_openai_key:
+ return "openai_batch"
+ return "sync_baseline"
diff --git a/autogpt_platform/backend/backend/copilot/dream/routing_test.py b/autogpt_platform/backend/backend/copilot/dream/routing_test.py
new file mode 100644
index 0000000000..a1161e5c87
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/routing_test.py
@@ -0,0 +1,82 @@
+"""Execution-path resolver — drives whether a dream goes batch or sync."""
+
+from __future__ import annotations
+
+import pytest
+
+from .routing import resolve_dream_execution_path
+
+
+ "has_anthropic_key,has_openai_key,batch_enabled,expected",
+ [
+ # Both keys + batch on: Anthropic wins (better cache pricing).
+ (True, True, True, "anthropic_batch"),
+ # Anthropic only + batch on: anthropic_batch.
+ (True, False, True, "anthropic_batch"),
+ # OpenAI only + batch on: openai_batch.
+ (False, True, True, "openai_batch"),
+ # Batch flag off — every combination falls back to sync_baseline.
+ (True, True, False, "sync_baseline"),
+ (True, False, False, "sync_baseline"),
+ (False, True, False, "sync_baseline"),
+ (False, False, True, "sync_baseline"),
+ (False, False, False, "sync_baseline"),
+ ],
+)
+def test_routing_branches(has_anthropic_key, has_openai_key, batch_enabled, expected):
+ assert (
+ resolve_dream_execution_path(
+ has_anthropic_key=has_anthropic_key,
+ has_openai_key=has_openai_key,
+ batch_processing_enabled=batch_enabled,
+ )
+ == expected
+ )
+
+
+def test_has_openai_key_defaults_to_false_for_backward_compat():
+ """Callers from before the multi-provider expansion only passed
+ ``has_anthropic_key``. Keep that working by defaulting
+ ``has_openai_key`` to False — they'll still route correctly to
+ anthropic_batch or sync_baseline."""
+ assert (
+ resolve_dream_execution_path(
+ has_anthropic_key=True, batch_processing_enabled=True
+ )
+ == "anthropic_batch"
+ )
+
+
[email protected]("transport_name", ["local", "subscription"])
+def test_local_and_subscription_transports_force_sync_baseline(transport_name):
+ """Local installs have no batch endpoint; subscription users
+ shouldn't dual-bill an unrelated ``ANTHROPIC_API_KEY`` for the
+ dream pass when the chat layer is on Claude Code OAuth.
+
+ Both transports veto the batch path even when
+ ``batch_processing_enabled=True`` and ``has_anthropic_key=True``."""
+ assert (
+ resolve_dream_execution_path(
+ has_anthropic_key=True,
+ has_openai_key=True,
+ batch_processing_enabled=True,
+ transport_name=transport_name,
+ )
+ == "sync_baseline"
+ )
+
+
[email protected]("transport_name", ["openrouter", "direct_anthropic", None])
+def test_batch_eligible_transports_unaffected(transport_name):
+ """openrouter / direct_anthropic / ``None`` (no override) preserve
+ the historical key-driven behaviour — the new ``transport_name``
+ gate only fires for ``local`` and ``subscription``."""
+ assert (
+ resolve_dream_execution_path(
+ has_anthropic_key=True,
+ batch_processing_enabled=True,
+ transport_name=transport_name,
+ )
+ == "anthropic_batch"
+ )
diff --git a/autogpt_platform/backend/backend/copilot/dream/scheduling.py b/autogpt_platform/backend/backend/copilot/dream/scheduling.py
new file mode 100644
index 0000000000..146a06abc5
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/scheduling.py
@@ -0,0 +1,377 @@
+"""Lazy auto-registration of per-user dream-system schedules.
+
+Two per-user APScheduler cron jobs cover the whole dream system through
+P12 (the cross-scope insight cron for P8 will add a third row when it
+builds):
+
+ * ``community_rebuild_{user_id}`` — Sun 04:00 user-local (P-1.7),
+ direct LLM (not batch), activity-gated inside the function.
+ * ``dream_nightly_batch_{user_id}`` — daily 03:00 user-local,
+ submits all nightly-batch-family work (dream pass, ratification
+ supersession sweep, plus future P2 / P3 / P4 / P11 stages).
+
+Both crons share the same registration helper. Adding a future cron
+(P8 cross-scope insight, P9 lucid dream queue if it grows beyond
+nightly batch, etc.) is a single row in :data:`DREAM_SYSTEM_JOBS`.
+
+Three layers of flag gating:
+
+ 1. **Registration helper (this file)** — cheapest gate; LD flag
+ check runs before the Redis CAS-style dedup so a flag-off user
+ never burns an RPC or a Redis key.
+ 2. **Scheduler ``@expose`` body** — defense-in-depth for direct
+ callers (admin endpoint, ad-hoc scripts) that bypass this helper.
+ 3. **Execution wrapper (``execute_*_sync``)** — runtime gate; if the
+ flag flips off after registration, the scheduled job still fires
+ but short-circuits before the body runs.
+
+**Timezone drift handling.** APScheduler binds the cron trigger to
+the timezone at job-creation time — a later ``User.timezone`` change
+silently leaves the cron firing at the old local time. To detect and
+recover from drift, the Redis dedup key stores the timezone the cron
+was registered with (not the literal ``"1"`` it stored historically).
+Every call to :func:`ensure_dream_system_scheduled` compares the
+stored value to the user's current timezone; on mismatch, re-registers
+via ``replace_existing=True``. The eager path (``force_refresh=True``)
+is invoked from the ``User.timezone`` update endpoint; the lazy path
+catches direct-DB / webhook / SSO writes that bypass the API.
+
+Per-job idempotency: each cron has its OWN Redis dedup key. Flipping
+a single flag from off→on after the other cron already registered
+must let the newly-enabled cron in.
+
+Per-job failure isolation: a scheduler RPC failure for one cron
+surfaces in this call's return dict but never blocks the other crons.
+
+Failures are logged at WARN and swallowed; the caller (the graphiti
+ingestion path) must never break because dream-system registration
+failed.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Awaitable, Callable
+
+from pydantic.dataclasses import dataclass
+
+from backend.util.feature_flag import Flag, is_feature_enabled
+
+logger = logging.getLogger(__name__)
+
+
+# Matches the longest cron cadence in the registry (weekly community
+# rebuild) so the lazy drift-detection path re-checks at least once
+# per cron-tick. Going longer leaves a window where Redis says
+# "registered with tz X" but the cron was deleted out-of-band; going
+# shorter wastes scheduler RPC calls when nothing changed.
+REGISTRATION_TTL_SECONDS = 7 * 24 * 3600
+
+
+# A SchedulerClient is the caller's handle to the scheduler service.
+# We don't import the concrete type here to avoid a circular import
+# during the executor's own bootstrap; the helper just calls the
+# named coroutine on whatever the caller hands in.
+SchedulerLike = Any
+
+
+@dataclass(frozen=True)
+class DreamSystemJob:
+ """One row of the dream-system schedule registry.
+
+ The registry is the single source of truth for "what background
+ crons does the dream system run per user". Adding a new cron
+ (e.g. weekly cross-scope insight for P8) means appending a row
+ here; the helper picks it up automatically, the scheduler call
+ gets the right job_id, and the Redis dedup key falls out naturally.
+ """
+
+ name: str
+ """Human-readable, used only for log messages."""
+
+ job_id_prefix: str
+ """Job-id naming convention: ``f"{job_id_prefix}_{user_id}"``.
+ Must match the scheduler ``@expose`` method's own job_id format."""
+
+ registration_key_prefix: str
+ """Redis dedup key prefix. Each cron has its OWN key so flipping
+ a single flag mid-life lets only that cron re-enter the helper —
+ a shared key would block recovery on flag drift."""
+
+ flag: Flag
+ """LD feature flag gate. Evaluated per-user before any other work."""
+
+ skip_reason: str
+ """The ``reason`` string returned in a flag-off skip result. Keyed
+ on the flag value so the helper's return dict is grep-able for
+ "why did this user not get a schedule"."""
+
+ register: Callable[[SchedulerLike, str, str], Awaitable[dict]]
+ """``(client, user_id, user_timezone) -> awaitable[result dict]``.
+ The actual SchedulerClient method that creates the cron job."""
+
+
+def _register_community_rebuild(
+ client: SchedulerLike, user_id: str, user_timezone: str
+) -> Awaitable[dict]:
+ return client.add_community_rebuild_schedule(
+ user_id=user_id, user_timezone=user_timezone
+ )
+
+
+def _register_nightly_batch(
+ client: SchedulerLike, user_id: str, user_timezone: str
+) -> Awaitable[dict]:
+ return client.add_nightly_batch_schedule(
+ user_id=user_id, user_timezone=user_timezone
+ )
+
+
+# The registry. Listed in cron-frequency order (rarest first) so the
+# log trail when a new user lands reads "weekly → daily" — the
+# narrative matches how the schedules build up over time. The future
+# P8 cross-scope cron (weekly, batch) will land between these two.
+DREAM_SYSTEM_JOBS: list[DreamSystemJob] = [
+ DreamSystemJob(
+ name="Community rebuild",
+ job_id_prefix="community_rebuild",
+ registration_key_prefix="community_rebuild_registered",
+ flag=Flag.GRAPHITI_COMMUNITIES_ENABLED,
+ skip_reason="graphiti_communities_disabled",
+ register=_register_community_rebuild,
+ ),
+ DreamSystemJob(
+ name="Dream nightly batch",
+ job_id_prefix="dream_nightly_batch",
+ # NOT shared with the now-removed individual dream/ratification
+ # crons — those keys (``dream_pass_registered``,
+ # ``ratification_pass_registered``) are orphaned by the
+ # consolidation and naturally expire via their 7-day TTL.
+ registration_key_prefix="dream_nightly_batch_registered",
+ # The nightly batch cron carries dream pass + ratification
+ # supersession + future P2/P3/P4/P11 work. All ride the same
+ # master gate; finer-grained flags inside individual submitters
+ # control whether each stage actually runs within the cron.
+ flag=Flag.DREAM_PASS_ENABLED,
+ skip_reason="dream_pass_disabled",
+ register=_register_nightly_batch,
+ ),
+]
+
+
+async def _resolve_user_timezone(user_id: str) -> str | None:
+ """Look up the user's IANA timezone from Postgres.
+
+ Returns ``"UTC"`` only when the answer is authoritative (user
+ missing or timezone genuinely unset) and ``None`` when the lookup
+ itself failed — a transient DB blip is "unknown", not "UTC", and
+ must never silently re-register the user's local-time crons onto
+ UTC.
+
+ Single DB call — cached at the helper level for the duration of
+ one ``ensure_dream_system_scheduled`` invocation so registering
+ multiple crons doesn't take multiple round-trips.
+ """
+ try:
+ from prisma import Prisma # noqa: F401 — ensures registry
+ from prisma.models import User
+
+ from backend.data.model import USER_TIMEZONE_NOT_SET
+
+ user = await User.prisma().find_unique(where={"id": user_id})
+ if user is None:
+ return "UTC"
+ tz = (user.timezone or "").strip()
+ if not tz or tz == USER_TIMEZONE_NOT_SET:
+ return "UTC"
+ return tz
+ except Exception:
+ logger.warning(
+ "Could not resolve timezone for user %s; leaving existing "
+ "dream-system schedules untouched this cycle",
+ user_id[:12],
+ exc_info=True,
+ )
+ return None
+
+
+async def _read_registration_tz(user_id: str, key_prefix: str) -> str | None:
+ """Read the timezone the cron was last registered with.
+
+ Returns:
+ * The stored timezone string when the key exists.
+ * ``None`` when the key is missing OR Redis is unavailable. The
+ caller treats both as "needs registration" — scheduler-side
+ ``replace_existing=True`` makes a redundant call a cheap no-op.
+ """
+ try:
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ key = f"{key_prefix}:{user_id}"
+ stored = await redis.get(key)
+ if stored is None:
+ return None
+ if isinstance(stored, bytes):
+ return stored.decode("utf-8", errors="replace")
+ return str(stored)
+ except Exception:
+ logger.debug(
+ "Redis read failed for %s:%s; treating as not-registered",
+ key_prefix,
+ user_id[:12],
+ exc_info=True,
+ )
+ return None
+
+
+async def _write_registration_tz(
+ user_id: str, key_prefix: str, current_tz: str
+) -> None:
+ """Persist the timezone we just registered the cron with.
+
+ Best-effort — a Redis write failure means the next call will see
+ the key as missing and force a redundant re-register (cheap via
+ ``replace_existing=True``).
+ """
+ try:
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ key = f"{key_prefix}:{user_id}"
+ await redis.set(key, current_tz, ex=REGISTRATION_TTL_SECONDS)
+ except Exception:
+ logger.debug(
+ "Redis write failed for %s:%s; lazy path will re-detect later",
+ key_prefix,
+ user_id[:12],
+ exc_info=True,
+ )
+
+
+async def ensure_dream_system_scheduled(
+ user_id: str, *, force_refresh: bool = False
+) -> dict[str, Any]:
+ """Idempotently register every flag-enabled dream-system cron for a user.
+
+ Fire-and-forget callable from two trigger points:
+
+ * **Lazy path** — called from the graphiti ingestion's
+ ``_ensure_worker`` the first time we see a memory write for a
+ user in this process. Drift-detects timezone changes via the
+ Redis stored value and re-registers when the user's current
+ timezone differs from the stored one.
+ * **Eager path** — called with ``force_refresh=True`` from the
+ ``User.timezone`` update endpoint so a profile change takes
+ effect within a single APScheduler tick instead of waiting for
+ the dedup key's 7-day TTL to expire.
+
+ Walks :data:`DREAM_SYSTEM_JOBS`, gating each entry on its LD flag,
+ then on per-job drift detection, then the actual scheduler RPC.
+ Each step's failure is isolated; a single bad cron never blocks
+ the others.
+
+ Returns a dict keyed by ``job_id_prefix`` so callers can audit
+ "what happened for this user this call":
+
+ * ``None`` — already registered with the current timezone; no
+ RPC made. (Lazy path's happy case.)
+ * ``{"skipped": True, "reason": "<flag>_disabled"}`` — flag off.
+ * ``{"skipped": True, "reason": "timezone_lookup_failed"}`` —
+ timezone resolution failed; the existing cron and stored tz
+ are left untouched until a later call succeeds.
+ * ``{"skipped": True, "reason": "registration_failed"}`` — RPC
+ raised; logged.
+ * Anything else — the scheduler's own result dict (job id,
+ next_run_time, etc.).
+
+ Empty ``user_id`` → ``{}`` (no work, no error).
+ """
+ if not user_id:
+ return {}
+
+ results: dict[str, Any] = {}
+ tz_cached: str | None = None
+ tz_lookup_failed = False
+ client_cached: SchedulerLike | None = None
+
+ for job in DREAM_SYSTEM_JOBS:
+ try:
+ # Layer 1 of gating: the LD flag check. Cheapest of the
+ # three; always run it first.
+ if not await is_feature_enabled(job.flag, user_id):
+ results[job.job_id_prefix] = {
+ "skipped": True,
+ "reason": job.skip_reason,
+ }
+ continue
+
+ # Resolve current timezone once per invocation (single DB
+ # call shared across enabled crons).
+ if tz_cached is None and not tz_lookup_failed:
+ tz_cached = await _resolve_user_timezone(user_id)
+ tz_lookup_failed = tz_cached is None
+
+ if tz_cached is None:
+ # Lookup failed — "unknown" is not "UTC". Re-registering
+ # would silently rebind the user's 03:00-local crons to
+ # UTC; keep the existing cron and stored tz untouched
+ # until a later call resolves the real timezone.
+ results[job.job_id_prefix] = {
+ "skipped": True,
+ "reason": "timezone_lookup_failed",
+ }
+ continue
+
+ # Drift detection (unless caller explicitly forced refresh).
+ if not force_refresh:
+ stored_tz = await _read_registration_tz(
+ user_id, job.registration_key_prefix
+ )
+ if stored_tz == tz_cached:
+ # Same tz, still within TTL → no work.
+ results[job.job_id_prefix] = None
+ continue
+ if stored_tz is not None and stored_tz != tz_cached:
+ logger.info(
+ "Dream-system: timezone drift for user %s job %s "
+ "(stored=%s, current=%s) — re-registering",
+ user_id[:12],
+ job.name,
+ stored_tz,
+ tz_cached,
+ )
+ # else: stored_tz is None → first registration OR
+ # Redis was unavailable. Either way, register.
+
+ # Lazy client handle so a fully-flag-off user never even
+ # constructs the scheduler client.
+ if client_cached is None:
+ from backend.util.clients import get_scheduler_client
+
+ client_cached = get_scheduler_client()
+
+ result = await job.register(client_cached, user_id, tz_cached)
+ await _write_registration_tz(
+ user_id, job.registration_key_prefix, tz_cached
+ )
+ logger.info(
+ "Dream-system: registered %s for user %s (tz=%s)",
+ job.name,
+ user_id[:12],
+ tz_cached,
+ )
+ results[job.job_id_prefix] = result
+ except Exception:
+ logger.warning(
+ "Dream-system: failed to register %s for user %s",
+ job.name,
+ user_id[:12],
+ exc_info=True,
+ )
+ results[job.job_id_prefix] = {
+ "skipped": True,
+ "reason": "registration_failed",
+ }
+
+ return results
diff --git a/autogpt_platform/backend/backend/copilot/dream/scheduling_test.py b/autogpt_platform/backend/backend/copilot/dream/scheduling_test.py
new file mode 100644
index 0000000000..009fd3c3ab
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/scheduling_test.py
@@ -0,0 +1,487 @@
+"""Registry-driven dream-system auto-registration tests.
+
+Contracts pinned here:
+
+ 1. Registry shape — 2 rows (community + nightly batch), distinct
+ dedup keys, distinct flags.
+ 2. Per-job flag gating — flag-off → recorded as skipped with the
+ right reason; scheduler RPC never called.
+ 3. Per-job idempotency — each cron has its own Redis dedup key so
+ flipping one flag mid-life only re-enters that cron.
+ 4. Per-job failure isolation — one cron's scheduler RPC failure
+ doesn't block the other cron.
+ 5. Timezone drift detection — Redis dedup key stores the
+ registered timezone; on mismatch with current timezone, force
+ re-register. ``force_refresh=True`` skips the drift check and
+ always re-registers.
+ 6. Shared per-call caching — timezone resolution happens at most
+ once per invocation.
+ 7. Timezone lookup failure is "unknown", not "UTC" — a transient
+ DB blip must never re-register the user's local-time crons onto
+ UTC; the cycle is skipped and the existing cron left untouched.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from backend.util.feature_flag import Flag
+
+from . import scheduling
+from .scheduling import (
+ DREAM_SYSTEM_JOBS,
+ REGISTRATION_TTL_SECONDS,
+ ensure_dream_system_scheduled,
+)
+
+# Paths used by the helper — patched at the module level since the
+# helper does lazy imports of the scheduler client + Redis client to
+# avoid bootstrap circular imports.
+_PATH_FLAG = "backend.copilot.dream.scheduling.is_feature_enabled"
+_PATH_TZ = "backend.copilot.dream.scheduling._resolve_user_timezone"
+_PATH_READ_TZ = "backend.copilot.dream.scheduling._read_registration_tz"
+_PATH_WRITE_TZ = "backend.copilot.dream.scheduling._write_registration_tz"
+_PATH_CLIENT = "backend.util.clients.get_scheduler_client"
+
+
+def _mock_scheduler_client(*, fail_jobs: tuple[str, ...] = ()) -> MagicMock:
+ """SchedulerClient stub returning a documented dict per call.
+
+ ``fail_jobs`` = tuple of job_id_prefix strings that should raise
+ instead of returning success — for per-job failure isolation tests.
+ """
+ client = MagicMock()
+
+ def _maker(prefix: str):
+ if prefix in fail_jobs:
+ return AsyncMock(side_effect=RuntimeError(f"{prefix} scheduler down"))
+ return AsyncMock(
+ return_value={
+ "id": f"{prefix}_abc",
+ "user_id": "abc",
+ "next_run_time": None,
+ }
+ )
+
+ client.add_community_rebuild_schedule = _maker("community_rebuild")
+ client.add_nightly_batch_schedule = _maker("dream_nightly_batch")
+ return client
+
+
+def _flag_mock(flag_map: dict[Flag, bool]) -> AsyncMock:
+ async def fake(flag: Flag, user_id: str) -> bool:
+ return flag_map.get(flag, False)
+
+ return AsyncMock(side_effect=fake)
+
+
+def _all_flags_on() -> dict[Flag, bool]:
+ return {
+ Flag.GRAPHITI_COMMUNITIES_ENABLED: True,
+ Flag.DREAM_PASS_ENABLED: True,
+ }
+
+
+# ---------------------------------------------------------------------------
+# Registry shape — guard against accidental edits
+# ---------------------------------------------------------------------------
+
+
+def test_registry_contains_two_jobs_in_cron_frequency_order():
+ """Weekly community first, daily nightly batch second — the order
+ matches how schedules build up over time and reads naturally in
+ the log narrative."""
+ prefixes = [j.job_id_prefix for j in DREAM_SYSTEM_JOBS]
+ assert prefixes == ["community_rebuild", "dream_nightly_batch"]
+
+
+def test_each_job_has_distinct_registration_key_prefix():
+ """Per-job dedup keys MUST be distinct — a shared key would block
+ recovery when a flag flips off→on for one cron but not the other."""
+ keys = [j.registration_key_prefix for j in DREAM_SYSTEM_JOBS]
+ assert len(set(keys)) == len(keys)
+
+
+def test_community_and_nightly_batch_have_distinct_flags():
+ """Community rebuild and nightly batch are independent features
+ behind separate LD flags. A user can have one enabled without
+ the other."""
+ community = next(
+ j for j in DREAM_SYSTEM_JOBS if j.job_id_prefix == "community_rebuild"
+ )
+ nightly = next(
+ j for j in DREAM_SYSTEM_JOBS if j.job_id_prefix == "dream_nightly_batch"
+ )
+ assert community.flag == Flag.GRAPHITI_COMMUNITIES_ENABLED
+ assert nightly.flag == Flag.DREAM_PASS_ENABLED
+
+
+# ---------------------------------------------------------------------------
+# Empty / null user_id
+# ---------------------------------------------------------------------------
+
+
+async def test_empty_user_id_returns_empty_dict_without_running():
+ result = await ensure_dream_system_scheduled("")
+ assert result == {}
+
+
+# ---------------------------------------------------------------------------
+# Happy path — both flags on, no existing registration
+# ---------------------------------------------------------------------------
+
+
+async def test_both_crons_register_when_their_flags_are_on():
+ client = _mock_scheduler_client()
+ with patch(_PATH_FLAG, new=_flag_mock(_all_flags_on())), patch(
+ _PATH_TZ, new=AsyncMock(return_value="America/New_York")
+ ), patch(_PATH_READ_TZ, new=AsyncMock(return_value=None)), patch(
+ _PATH_WRITE_TZ, new=AsyncMock()
+ ), patch(
+ _PATH_CLIENT, return_value=client
+ ):
+ result = await ensure_dream_system_scheduled("abc")
+
+ assert result["community_rebuild"]["id"] == "community_rebuild_abc"
+ assert result["dream_nightly_batch"]["id"] == "dream_nightly_batch_abc"
+
+ # Both scheduler calls threaded the same resolved timezone.
+ client.add_community_rebuild_schedule.assert_awaited_once_with(
+ user_id="abc", user_timezone="America/New_York"
+ )
+ client.add_nightly_batch_schedule.assert_awaited_once_with(
+ user_id="abc", user_timezone="America/New_York"
+ )
+
+
+# ---------------------------------------------------------------------------
+# Layer 1 — flag gate
+# ---------------------------------------------------------------------------
+
+
+async def test_community_flag_off_skips_only_community():
+ """One flag off → only that cron is skipped; the other registers."""
+ client = _mock_scheduler_client()
+ flag_map = _all_flags_on()
+ flag_map[Flag.GRAPHITI_COMMUNITIES_ENABLED] = False
+ with patch(_PATH_FLAG, new=_flag_mock(flag_map)), patch(
+ _PATH_TZ, new=AsyncMock(return_value="UTC")
+ ), patch(_PATH_READ_TZ, new=AsyncMock(return_value=None)), patch(
+ _PATH_WRITE_TZ, new=AsyncMock()
+ ), patch(
+ _PATH_CLIENT, return_value=client
+ ):
+ result = await ensure_dream_system_scheduled("abc")
+
+ assert result["community_rebuild"] == {
+ "skipped": True,
+ "reason": "graphiti_communities_disabled",
+ }
+ assert result["dream_nightly_batch"]["id"] == "dream_nightly_batch_abc"
+ client.add_community_rebuild_schedule.assert_not_called()
+
+
+async def test_dream_flag_off_skips_only_nightly_batch():
+ client = _mock_scheduler_client()
+ flag_map = _all_flags_on()
+ flag_map[Flag.DREAM_PASS_ENABLED] = False
+ with patch(_PATH_FLAG, new=_flag_mock(flag_map)), patch(
+ _PATH_TZ, new=AsyncMock(return_value="UTC")
+ ), patch(_PATH_READ_TZ, new=AsyncMock(return_value=None)), patch(
+ _PATH_WRITE_TZ, new=AsyncMock()
+ ), patch(
+ _PATH_CLIENT, return_value=client
+ ):
+ result = await ensure_dream_system_scheduled("abc")
+
+ assert result["community_rebuild"]["id"] == "community_rebuild_abc"
+ assert result["dream_nightly_batch"] == {
+ "skipped": True,
+ "reason": "dream_pass_disabled",
+ }
+ client.add_nightly_batch_schedule.assert_not_called()
+
+
+async def test_all_flags_off_returns_all_skipped_no_rpc_no_tz_lookup():
+ """When nothing is enabled, don't waste a DB lookup for tz or an
+ RPC to the scheduler service."""
+ client = _mock_scheduler_client()
+ tz_mock = AsyncMock(return_value="UTC")
+ with patch(_PATH_FLAG, new=_flag_mock({})), patch(_PATH_TZ, new=tz_mock), patch(
+ _PATH_READ_TZ, new=AsyncMock(return_value=None)
+ ), patch(_PATH_WRITE_TZ, new=AsyncMock()), patch(_PATH_CLIENT, return_value=client):
+ result = await ensure_dream_system_scheduled("abc")
+
+ assert all(r.get("skipped") is True for r in result.values()) # type: ignore[union-attr]
+ tz_mock.assert_not_called()
+ client.add_community_rebuild_schedule.assert_not_called()
+ client.add_nightly_batch_schedule.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# Layer 2 — timezone drift detection (replaces old SETNX-only semantics)
+# ---------------------------------------------------------------------------
+
+
+async def test_no_drift_returns_none_without_rpc():
+ """Cron already registered with the user's current timezone → no
+ work, no RPC."""
+ client = _mock_scheduler_client()
+ with patch(_PATH_FLAG, new=_flag_mock(_all_flags_on())), patch(
+ _PATH_TZ, new=AsyncMock(return_value="America/New_York")
+ ), patch(_PATH_READ_TZ, new=AsyncMock(return_value="America/New_York")), patch(
+ _PATH_WRITE_TZ, new=AsyncMock()
+ ), patch(
+ _PATH_CLIENT, return_value=client
+ ):
+ result = await ensure_dream_system_scheduled("abc")
+
+ assert result["community_rebuild"] is None
+ assert result["dream_nightly_batch"] is None
+ client.add_community_rebuild_schedule.assert_not_called()
+ client.add_nightly_batch_schedule.assert_not_called()
+
+
+async def test_timezone_drift_re_registers_via_replace_existing():
+ """User moved NY → Paris; existing cron is still bound to NY tz.
+ Helper detects the drift via the stored value and re-registers."""
+ client = _mock_scheduler_client()
+ write_spy = AsyncMock()
+ with patch(_PATH_FLAG, new=_flag_mock(_all_flags_on())), patch(
+ _PATH_TZ, new=AsyncMock(return_value="Europe/Paris")
+ ), patch(_PATH_READ_TZ, new=AsyncMock(return_value="America/New_York")), patch(
+ _PATH_WRITE_TZ, new=write_spy
+ ), patch(
+ _PATH_CLIENT, return_value=client
+ ):
+ result = await ensure_dream_system_scheduled("abc")
+
+ # Both crons re-registered with the new tz.
+ client.add_community_rebuild_schedule.assert_awaited_once_with(
+ user_id="abc", user_timezone="Europe/Paris"
+ )
+ client.add_nightly_batch_schedule.assert_awaited_once_with(
+ user_id="abc", user_timezone="Europe/Paris"
+ )
+ # Stored tz updated for both.
+ written_tzs = [call.args[2] for call in write_spy.await_args_list]
+ assert written_tzs == ["Europe/Paris", "Europe/Paris"]
+ assert result["community_rebuild"]["id"] == "community_rebuild_abc"
+ assert result["dream_nightly_batch"]["id"] == "dream_nightly_batch_abc"
+
+
+async def test_force_refresh_skips_drift_check_and_always_re_registers():
+ """``force_refresh=True`` (from the User.timezone update hook)
+ bypasses drift detection and always re-registers."""
+ client = _mock_scheduler_client()
+ read_spy = AsyncMock(return_value="America/New_York")
+ with patch(_PATH_FLAG, new=_flag_mock(_all_flags_on())), patch(
+ _PATH_TZ, new=AsyncMock(return_value="America/New_York")
+ ), patch(_PATH_READ_TZ, new=read_spy), patch(
+ _PATH_WRITE_TZ, new=AsyncMock()
+ ), patch(
+ _PATH_CLIENT, return_value=client
+ ):
+ result = await ensure_dream_system_scheduled("abc", force_refresh=True)
+
+ # Read NEVER consulted when force_refresh=True — saves a Redis
+ # round-trip when the eager hook KNOWS something changed.
+ read_spy.assert_not_called()
+ client.add_community_rebuild_schedule.assert_awaited_once()
+ client.add_nightly_batch_schedule.assert_awaited_once()
+ assert result["community_rebuild"]["id"] == "community_rebuild_abc"
+
+
+async def test_redis_read_failure_treats_as_first_registration():
+ """Redis unavailable → ``_read_registration_tz`` returns None →
+ helper falls through to scheduler RPC. APScheduler's
+ ``replace_existing=True`` is the durable backstop."""
+ client = _mock_scheduler_client()
+ with patch(_PATH_FLAG, new=_flag_mock(_all_flags_on())), patch(
+ _PATH_TZ, new=AsyncMock(return_value="UTC")
+ ), patch(_PATH_READ_TZ, new=AsyncMock(return_value=None)), patch(
+ _PATH_WRITE_TZ, new=AsyncMock()
+ ), patch(
+ _PATH_CLIENT, return_value=client
+ ):
+ result = await ensure_dream_system_scheduled("abc")
+
+ assert result["community_rebuild"]["id"] == "community_rebuild_abc"
+ assert result["dream_nightly_batch"]["id"] == "dream_nightly_batch_abc"
+
+
+# ---------------------------------------------------------------------------
+# Timezone lookup failure — "unknown" must not become "UTC"
+# ---------------------------------------------------------------------------
+
+
+async def test_timezone_lookup_failure_leaves_existing_crons_untouched():
+ """A transient DB failure during tz resolution must NOT be read as
+ 'user is in UTC' — that would re-register the 03:00-local crons
+ onto 03:00 UTC and overwrite the stored tz. Skip the cycle: no
+ scheduler RPC, no Redis write."""
+ client = _mock_scheduler_client()
+ write_spy = AsyncMock()
+ with patch(_PATH_FLAG, new=_flag_mock(_all_flags_on())), patch(
+ _PATH_TZ, new=AsyncMock(return_value=None)
+ ), patch(_PATH_READ_TZ, new=AsyncMock(return_value="America/Chicago")), patch(
+ _PATH_WRITE_TZ, new=write_spy
+ ), patch(
+ _PATH_CLIENT, return_value=client
+ ):
+ result = await ensure_dream_system_scheduled("abc")
+
+ assert result["community_rebuild"] == {
+ "skipped": True,
+ "reason": "timezone_lookup_failed",
+ }
+ assert result["dream_nightly_batch"] == {
+ "skipped": True,
+ "reason": "timezone_lookup_failed",
+ }
+ client.add_community_rebuild_schedule.assert_not_called()
+ client.add_nightly_batch_schedule.assert_not_called()
+ write_spy.assert_not_called()
+
+
+async def test_timezone_lookup_failure_attempted_once_not_per_job():
+ """A failed lookup is cached for the invocation like a successful
+ one — two enabled crons must not trigger a second DB round-trip."""
+ tz_mock = AsyncMock(return_value=None)
+ client = _mock_scheduler_client()
+ with patch(_PATH_FLAG, new=_flag_mock(_all_flags_on())), patch(
+ _PATH_TZ, new=tz_mock
+ ), patch(_PATH_READ_TZ, new=AsyncMock(return_value=None)), patch(
+ _PATH_WRITE_TZ, new=AsyncMock()
+ ), patch(
+ _PATH_CLIENT, return_value=client
+ ):
+ await ensure_dream_system_scheduled("abc")
+
+ tz_mock.assert_awaited_once_with("abc")
+
+
+async def test_force_refresh_with_failed_tz_lookup_still_skips_re_registration():
+ """Even the eager path (timezone-update endpoint) must not
+ re-register onto UTC when it can't read the new timezone back —
+ the lazy drift-detection path recovers once the DB is healthy."""
+ client = _mock_scheduler_client()
+ with patch(_PATH_FLAG, new=_flag_mock(_all_flags_on())), patch(
+ _PATH_TZ, new=AsyncMock(return_value=None)
+ ), patch(_PATH_READ_TZ, new=AsyncMock(return_value=None)), patch(
+ _PATH_WRITE_TZ, new=AsyncMock()
+ ), patch(
+ _PATH_CLIENT, return_value=client
+ ):
+ result = await ensure_dream_system_scheduled("abc", force_refresh=True)
+
+ assert result["community_rebuild"] == {
+ "skipped": True,
+ "reason": "timezone_lookup_failed",
+ }
+ client.add_community_rebuild_schedule.assert_not_called()
+ client.add_nightly_batch_schedule.assert_not_called()
+
+
+async def test_resolve_user_timezone_returns_none_when_db_lookup_fails():
+ """The resolver distinguishes 'lookup failed' (None) from
+ 'genuinely unset' (UTC)."""
+ with patch("prisma.models.User.prisma", side_effect=RuntimeError("db down")):
+ assert await scheduling._resolve_user_timezone("abc") is None
+
+
+async def test_resolve_user_timezone_unset_value_falls_back_to_utc():
+ """A user whose timezone was never set legitimately defaults to
+ UTC — only lookup FAILURES return None."""
+ from backend.data.model import USER_TIMEZONE_NOT_SET
+
+ prisma_stub = MagicMock()
+ prisma_stub.find_unique = AsyncMock(
+ return_value=MagicMock(timezone=USER_TIMEZONE_NOT_SET)
+ )
+ with patch("prisma.models.User.prisma", return_value=prisma_stub):
+ assert await scheduling._resolve_user_timezone("abc") == "UTC"
+
+
+# ---------------------------------------------------------------------------
+# Layer 3 — per-job RPC failure isolation
+# ---------------------------------------------------------------------------
+
+
+async def test_one_cron_rpc_failure_does_not_block_the_other():
+ """Community rebuild scheduler call raises; nightly batch still
+ registers cleanly. Failed cron surfaces as skipped dict, not a
+ propagated exception."""
+ client = _mock_scheduler_client(fail_jobs=("community_rebuild",))
+ with patch(_PATH_FLAG, new=_flag_mock(_all_flags_on())), patch(
+ _PATH_TZ, new=AsyncMock(return_value="UTC")
+ ), patch(_PATH_READ_TZ, new=AsyncMock(return_value=None)), patch(
+ _PATH_WRITE_TZ, new=AsyncMock()
+ ), patch(
+ _PATH_CLIENT, return_value=client
+ ):
+ result = await ensure_dream_system_scheduled("abc")
+
+ assert result["community_rebuild"] == {
+ "skipped": True,
+ "reason": "registration_failed",
+ }
+ assert result["dream_nightly_batch"]["id"] == "dream_nightly_batch_abc"
+
+
+# ---------------------------------------------------------------------------
+# Shared per-call caching
+# ---------------------------------------------------------------------------
+
+
+async def test_timezone_lookup_runs_at_most_once_per_invocation():
+ """Two crons registering must share one Prisma round-trip for the
+ user's timezone."""
+ client = _mock_scheduler_client()
+ tz_mock = AsyncMock(return_value="UTC")
+ with patch(_PATH_FLAG, new=_flag_mock(_all_flags_on())), patch(
+ _PATH_TZ, new=tz_mock
+ ), patch(_PATH_READ_TZ, new=AsyncMock(return_value=None)), patch(
+ _PATH_WRITE_TZ, new=AsyncMock()
+ ), patch(
+ _PATH_CLIENT, return_value=client
+ ):
+ await ensure_dream_system_scheduled("abc")
+
+ tz_mock.assert_awaited_once_with("abc")
+
+
+# ---------------------------------------------------------------------------
+# Module constants — defended against TTL drift
+# ---------------------------------------------------------------------------
+
+
+def test_registration_ttl_matches_longest_cron_cadence():
+ """TTL must be at least as long as the weekly community rebuild
+ cadence so the lazy drift-detection path re-checks at least once
+ per cron-tick."""
+ one_week_seconds = 7 * 24 * 3600
+ assert REGISTRATION_TTL_SECONDS >= one_week_seconds
+
+
+# Suppress "imported but unused" — ``scheduling`` is the module under test;
+# some linters miss the patch() string-target usage.
+_ = scheduling
diff --git a/autogpt_platform/backend/backend/copilot/dream/schemas.py b/autogpt_platform/backend/backend/copilot/dream/schemas.py
new file mode 100644
index 0000000000..7a4d0f63db
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/schemas.py
@@ -0,0 +1,326 @@
+"""Structured outputs for the three-phase dream pipeline.
+
+Each phase returns a typed Pydantic model so the orchestrator can pass
+phase 1's output into phase 2's prompt without freeform JSON parsing.
+The phase 3 sanitizer's output (``DreamOperations``) is what
+``apply.py`` consumes when writing back to Graphiti + Postgres.
+
+Per ``dream/p0-spec.md`` §2 "Schemas (sketch)".
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from backend.copilot.graphiti.memory_model import MemoryKind
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Phase 1 — Consolidation
+# ---------------------------------------------------------------------------
+
+
+class ConsolidatedFact(BaseModel):
+ """A cluster of related facts merged into a single canonical statement.
+
+ Phase 1 output. Provenance always points back to the source episodes
+ so apply.py can record where the consolidation came from.
+ """
+
+ content: str = Field(description="Canonical statement of the consolidated fact.")
+ scope: str = Field(
+ default="real:global",
+ description="Memory scope namespace, e.g. 'real:global' or 'project:foo'.",
+ )
+ confidence: float = Field(
+ ge=0.0,
+ le=1.0,
+ description="Phase 1 model's confidence in the consolidated statement.",
+ )
+ source_episode_uuids: list[str] = Field(
+ default_factory=list,
+ description="UUIDs of the :Episodic nodes the fact was consolidated from.",
+ )
+
+
+class ConsolidationOutput(BaseModel):
+ facts: list[ConsolidatedFact] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Phase 2 — Recombination
+# ---------------------------------------------------------------------------
+
+
+class ProposedFinding(BaseModel):
+ """A novel connection or weak-link discovery from phase 2.
+
+ All proposals land as ``status=tentative`` in apply.py and ride the
+ P-0.4 ratification loop. The ``rationale`` is recorded as part of
+ the episode body so a reviewer (or future audit) can see *why* the
+ dream pass proposed the finding.
+ """
+
+ content: str = Field(description="The proposed finding.")
+ scope: str = Field(
+ default="real:global",
+ description="Memory scope.",
+ )
+ memory_kind: MemoryKind = Field(
+ default=MemoryKind.finding,
+ description="Envelope kind — finding | rule | preference | plan.",
+ )
+ confidence: float = Field(
+ ge=0.0,
+ le=1.0,
+ description="Phase 2 model's self-rated confidence.",
+ )
+ rationale: str = Field(
+ description="Why the dream pass proposes this — recorded for audit.",
+ )
+ source_episode_uuids: list[str] = Field(default_factory=list)
+ source_fact_uuids: list[str] = Field(default_factory=list)
+
+
+class RecombinationOutput(BaseModel):
+ proposals: list[ProposedFinding] = Field(default_factory=list)
+
+ @model_validator(mode="before")
+ @classmethod
+ def _drop_proposals_with_invalid_memory_kind(cls, data: Any) -> Any:
+ """LLMs occasionally invent kinds outside the MemoryKind enum
+ (observed: "inference", "meta"). Drop those proposals rather
+ than failing the whole phase — the surviving valid proposals
+ still get written as tentative findings."""
+ if not isinstance(data, dict):
+ return data
+ raw_proposals = data.get("proposals")
+ if not isinstance(raw_proposals, list):
+ return data
+ valid_kinds = {k.value for k in MemoryKind}
+ kept: list[Any] = []
+ for p in raw_proposals:
+ if isinstance(p, dict):
+ kind = p.get("memory_kind")
+ if kind is not None and kind not in valid_kinds:
+ logger.info(
+ "dream phase_2: dropping proposal with unknown memory_kind=%r",
+ kind,
+ )
+ continue
+ kept.append(p)
+ data["proposals"] = kept
+ return data
+
+
+# ---------------------------------------------------------------------------
+# Phase 3 — Sanitize + Gate (the final DreamOperations)
+# ---------------------------------------------------------------------------
+
+
+class DreamDemotion(BaseModel):
+ """Demote an existing :RELATES_TO edge.
+
+ Sets ``expired_at`` and ``status``; ``invalid_at`` is reserved for
+ contradiction-detector world-changes per Snodgrass bi-temporal
+ semantics (see ``dream/p0-spec.md`` §4 and the audit at §6.13).
+ """
+
+ edge_uuid: str = Field(description="UUID of the :RELATES_TO edge to demote.")
+ reason: str = Field(
+ description=(
+ "Short reason recorded on the edge. Examples: 'stale_fact', "
+ "'contradicted_by:{uuid}', 'entity_invalidated:{uuid}', "
+ "'user_signal', 'unratified', 'web_contradicted:{url}'."
+ ),
+ )
+ new_status: Literal["superseded", "contradicted"] = "superseded"
+
+
+class EntityInvalidation(BaseModel):
+ """Demote every :RELATES_TO edge directly attached to an entity.
+
+ Single-hop only — apply.py calls ``invalidate_entity_direct_neighbors``
+ which clamps to ``[r:RELATES_TO]-(other)``; never expands to
+ neighbors-of-neighbors.
+ """
+
+ entity_uuid: str
+ reason: str
+
+
+class DreamOperations(BaseModel):
+ """Phase 3 output — what apply.py writes back to the world.
+
+ Guardrails enforced by phase 3's prompt and double-checked in
+ apply.py:
+ * ≤ ``max_demotions_per_pass`` demotions per pass (runaway-demotion
+ mitigation per spec §3 / TODO P0.3b).
+ * Scope match enforced — proposals cannot cross scopes.
+ * Empty ``writes`` and ``proposals`` is fine; a pass can be no-op.
+ """
+
+ writes: list[ConsolidatedFact] = Field(
+ default_factory=list,
+ description="Phase 1 consolidated facts that survived the sanitizer.",
+ )
+ proposals: list[ProposedFinding] = Field(
+ default_factory=list,
+ description="Phase 2 proposals that survived the sanitizer.",
+ )
+ demotions: list[DreamDemotion] = Field(default_factory=list)
+ entity_invalidations: list[EntityInvalidation] = Field(default_factory=list)
+ summary_for_user: str = Field(
+ default="",
+ description="Short narrative for the dream-kind ChatSession body.",
+ )
+
+
+# ---------------------------------------------------------------------------
+# DreamPass — what the orchestrator returns to its caller
+# ---------------------------------------------------------------------------
+
+
+class WriteSummary(BaseModel):
+ """One line per envelope written by apply.py.
+
+ Carries the durable Graphiti edge uuid so the eval / admin UI / the
+ future inline chat-stream `dream.operations` event (P9 daydreaming)
+ can render or audit individual operations. ``edge_uuid`` is None
+ when the underlying ``enqueue_episode`` call did not return one
+ (FalkorDB unreachable, etc.) — we still record the attempted write.
+ """
+
+ edge_uuid: str | None = None
+ content: str
+ scope: str = "real:global"
+ confidence: float | None = None
+ status: Literal["active", "tentative"] = "active"
+ source_episode_uuids: list[str] = Field(default_factory=list)
+ source_fact_uuids: list[str] = Field(default_factory=list)
+
+
+class DemotionSummary(BaseModel):
+ """One line per demoted RELATES_TO edge."""
+
+ edge_uuid: str
+ reason: str
+ new_status: Literal["superseded", "contradicted"]
+ applied: bool = True
+ """False when the underlying Cypher reported zero rows touched —
+ typically because the edge uuid was stale by the time apply.py ran."""
+
+
+class EntityInvalidationSummary(BaseModel):
+ """Per-entity invalidation rollup."""
+
+ entity_uuid: str
+ reason: str
+ edges_touched: list[str] = Field(default_factory=list)
+
+
+class DreamOperationsSnapshot(BaseModel):
+ """Detailed per-operation rollup of a single dream pass.
+
+ Shape used by three downstream consumers:
+ 1. The admin memory-visualizer UI (renders the per-edge detail).
+ 2. AgentProbe eval scorers (read via ``rawExchangeKey``).
+ 3. The future chat-stream ``dream.operations`` SSE event (P6 + P9
+ daydreaming, see ``dream/TODO.md``).
+
+ Kept additive on ``DreamPassResult`` so adding fields here doesn't
+ bump the count-only top-level columns existing clients rely on.
+ """
+
+ writes: list[WriteSummary] = Field(default_factory=list)
+ proposals: list[WriteSummary] = Field(default_factory=list)
+ demotions: list[DemotionSummary] = Field(default_factory=list)
+ entity_invalidations: list[EntityInvalidationSummary] = Field(default_factory=list)
+
+
+class PhaseUsage(BaseModel):
+ """Per-phase token + cost telemetry."""
+
+ phase: Literal["consolidate", "recombine", "sanitize"]
+ model: str
+ input_tokens: int = 0
+ output_tokens: int = 0
+ cache_read_tokens: int = 0
+ cache_creation_tokens: int = 0
+ cost_usd: float | None = None
+ """``None`` when the provider didn't return a cost and the model
+ isn't in ``model_pricing.py`` — caller treats as unknown rather
+ than zero. ``0.0`` is legitimate (zero tokens, edge case)."""
+
+
+class DreamPassUsage(BaseModel):
+ """Aggregate usage across all phases of one dream pass.
+
+ Surfaced on ``DreamPassResult.usage`` so eval / admin UI / billing
+ can read tokens + cost without recomputing. Written to
+ ``PlatformCostLog`` from apply.py with ``provider='dream_pass'``;
+ charged against the user's rate-limit window via
+ ``persist_and_record_usage`` so dream-pass spend rolls into the
+ same daily/weekly subscription tier budget as chat-execution
+ overage.
+ """
+
+ phases: list[PhaseUsage] = Field(default_factory=list)
+ total_input_tokens: int = 0
+ total_output_tokens: int = 0
+ total_cache_read_tokens: int = 0
+ total_cache_creation_tokens: int = 0
+ total_cost_usd: float | None = None
+ """Sum of phase cost_usd values; ``None`` if any phase was unknown."""
+ discount_applied: float = 0.0
+ """Execution-path discount factor in [0, 1] — 0.0 for sync_baseline,
+ 0.5 for anthropic_batch / openai_batch. The ``total_cost_usd``
+ above already has this factored in; recorded separately so the
+ cost ledger can audit the savings."""
+
+
+class DreamPassResult(BaseModel):
+ """Return value of ``execute_dream_pass`` and the admin API.
+
+ Mirrors ``RebuildResponse`` from the community-rebuild endpoint so
+ the admin frontend can render both with the same toast logic.
+ """
+
+ user_id: str
+ pass_id: str
+ started_at: datetime | None = None
+ completed_at: datetime | None = None
+ elapsed_seconds: float | None = None
+ execution_path: Literal["sync_baseline", "anthropic_batch", "openai_batch"] = (
+ "sync_baseline"
+ )
+
+ # Per-phase telemetry — null when the phase did not run.
+ consolidated_count: int = 0
+ proposal_count: int = 0
+ demotion_count: int = 0
+ entity_invalidation_count: int = 0
+
+ summary_for_user: str = ""
+ dream_session_id: str | None = None
+
+ # Detailed per-operation rollup. ``None`` when the pass was skipped
+ # or errored before phase 3 produced operations; ``DreamOperationsSnapshot()``
+ # with empty lists when the pass ran but produced no operations.
+ operations: DreamOperationsSnapshot | None = None
+
+ # Token + cost telemetry across all phases that actually ran.
+ # ``None`` for skipped passes (lock_held / no_input / insufficient_credits).
+ # Populated even on partial failures — we still paid for the phases
+ # that ran before the failure.
+ usage: DreamPassUsage | None = None
+
+ # Failure / skip signalling — mirrors RebuildResponse.
+ error: str | None = None
+ skipped: bool = False
+ skip_reason: str | None = None
diff --git a/autogpt_platform/backend/backend/copilot/dream/schemas_test.py b/autogpt_platform/backend/backend/copilot/dream/schemas_test.py
new file mode 100644
index 0000000000..fa951369ae
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/schemas_test.py
@@ -0,0 +1,148 @@
+"""Schema validation — bounds and defaults for the dream output models."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from .schemas import (
+ ConsolidatedFact,
+ DreamDemotion,
+ DreamOperations,
+ DreamPassResult,
+ ProposedFinding,
+)
+
+
+def test_consolidated_fact_confidence_clamped_to_unit_interval():
+ ConsolidatedFact(content="x", confidence=0.0)
+ ConsolidatedFact(content="x", confidence=1.0)
+ with pytest.raises(ValidationError):
+ ConsolidatedFact(content="x", confidence=-0.1)
+ with pytest.raises(ValidationError):
+ ConsolidatedFact(content="x", confidence=1.1)
+
+
+def test_proposed_finding_requires_rationale():
+ # ``rationale`` is required — phase 2 prompt insists on it and
+ # phase 3 sanitizer rejects citations-less proposals; the schema
+ # enforces that the field is present even if "" so callers can't
+ # accidentally drop it.
+ with pytest.raises(ValidationError):
+ ProposedFinding(content="x", confidence=0.5) # type: ignore[call-arg]
+
+
+def test_demotion_status_must_be_one_of_two_values():
+ DreamDemotion(edge_uuid="u", reason="r", new_status="superseded")
+ DreamDemotion(edge_uuid="u", reason="r", new_status="contradicted")
+ with pytest.raises(ValidationError):
+ DreamDemotion(
+ edge_uuid="u", reason="r", new_status="archived" # type: ignore[arg-type]
+ )
+
+
+def test_dream_operations_defaults_to_empty_no_op():
+ ops = DreamOperations()
+ assert ops.writes == []
+ assert ops.proposals == []
+ assert ops.demotions == []
+ assert ops.entity_invalidations == []
+ assert ops.summary_for_user == ""
+
+
+def test_dream_pass_result_skipped_keeps_zero_counts():
+ result = DreamPassResult(
+ user_id="u", pass_id="p", skipped=True, skip_reason="no_input"
+ )
+ assert result.consolidated_count == 0
+ assert result.proposal_count == 0
+ assert result.demotion_count == 0
+ assert result.entity_invalidation_count == 0
+ assert result.execution_path == "sync_baseline"
+
+
+# ---------------------------------------------------------------------------
+# RecombinationOutput lenient parsing
+# ---------------------------------------------------------------------------
+
+
+def test_recombination_output_drops_proposals_with_unknown_memory_kind():
+ """LLMs sometimes invent kinds outside MemoryKind (e.g. 'inference',
+ 'meta'). Those proposals are dropped; valid ones are kept."""
+ from .schemas import ProposedFinding, RecombinationOutput
+
+ payload = {
+ "proposals": [
+ {
+ "content": "valid one",
+ "scope": "real:global",
+ "memory_kind": "finding",
+ "confidence": 0.8,
+ "rationale": "ok",
+ },
+ {
+ "content": "unknown kind",
+ "scope": "real:global",
+ "memory_kind": "inference", # not in enum
+ "confidence": 0.5,
+ "rationale": "should be dropped",
+ },
+ {
+ "content": "another bad kind",
+ "scope": "real:global",
+ "memory_kind": "meta", # not in enum
+ "confidence": 0.5,
+ "rationale": "should be dropped",
+ },
+ ]
+ }
+ out = RecombinationOutput.model_validate(payload)
+ assert len(out.proposals) == 1
+ assert isinstance(out.proposals[0], ProposedFinding)
+ assert out.proposals[0].content == "valid one"
+
+
+def test_recombination_output_keeps_proposals_without_memory_kind():
+ """memory_kind has a default of MemoryKind.finding, so omitting it
+ is fine — proposal must still be kept."""
+ from .schemas import RecombinationOutput
+
+ payload = {
+ "proposals": [
+ {
+ "content": "no kind given",
+ "scope": "real:global",
+ "confidence": 0.7,
+ "rationale": "default kind applies",
+ }
+ ]
+ }
+ out = RecombinationOutput.model_validate(payload)
+ assert len(out.proposals) == 1
+ # default should be MemoryKind.finding
+ assert out.proposals[0].memory_kind.value == "finding"
+
+
+def test_recombination_output_all_invalid_yields_empty_list():
+ """If every proposal has an invalid memory_kind the result is an empty
+ proposals list — phase 3 then has nothing to gate, which is fine."""
+ from .schemas import RecombinationOutput
+
+ payload = {
+ "proposals": [
+ {
+ "content": "a",
+ "memory_kind": "metaphysics",
+ "confidence": 0.5,
+ "rationale": "drop me",
+ },
+ {
+ "content": "b",
+ "memory_kind": "speculation",
+ "confidence": 0.5,
+ "rationale": "drop me too",
+ },
+ ]
+ }
+ out = RecombinationOutput.model_validate(payload)
+ assert out.proposals == []
diff --git a/autogpt_platform/backend/backend/copilot/dream/staleness.py b/autogpt_platform/backend/backend/copilot/dream/staleness.py
new file mode 100644
index 0000000000..b9be11f3ec
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/staleness.py
@@ -0,0 +1,169 @@
+"""Stale-fact deprecation heuristics for the sanitize step.
+
+Surfaces candidate "this fact may no longer be true" rows to the
+sanitize prompt so the LLM can issue a ``DreamDemotion`` when general
+knowledge or the consolidated phase 1 facts contradict the candidate.
+The heuristics here are *non-blocking*: they raise a fact's score, the
+sanitizer makes the final call. Per ``dream/p0-spec.md`` §P0.3a.
+
+Why heuristics + LLM and not heuristics alone:
+ * Stable facts that look stale by heuristic (e.g. "user's birthday
+ is March 5" — contains a "specific date" and is old) must not be
+ demoted. The sanitizer reads phase 1 facts alongside the candidate
+ and rejects the demotion when the world hasn't changed.
+ * The heuristic side is cheap (regex + age math) so we can afford to
+ score every fact in the dream window, not just a sample.
+
+Edge case test fixtures (the 50-fact "stale and wrong" vs "old but
+stable" set) live in ``backend/copilot/eval/`` as part of P0.6 — not
+in this module.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+ from .fetch import FactRow
+
+logger = logging.getLogger(__name__)
+
+
+# A fact at or above this score is surfaced to the sanitize prompt as a
+# demotion candidate. The threshold is conservative — false negatives
+# (a stale fact slipping through) cost one more dream cycle to catch,
+# false positives spam the sanitizer with noise to ignore.
+STALENESS_THRESHOLD = 0.6
+
+
+# Each heuristic adds this much to the score when it fires. Tuned so:
+# * Birthday / preference (age only) → 0.4, stays below threshold.
+# * Old model-version claim (age + version) → 0.8, above.
+# * Current pricing or leadership claim (volatile domain alone) → 0.6,
+# above — these go stale fast even when freshly recorded.
+# * "Latest config" alone (recency keyword only) → 0.3, below — too
+# little signal to demote without context.
+# Threshold is 0.6 so a SINGLE volatile-domain hit is enough; everything
+# else needs at least two corroborating signals.
+_AGE_WEIGHT = 0.4
+_VERSION_WEIGHT = 0.4
+_RECENCY_KEYWORD_WEIGHT = 0.3
+_VOLATILE_DOMAIN_WEIGHT = 0.6
+
+
+# Matches version numbers, year stamps, and named model versions that
+# usually rev within a year. ``\b`` guards keep e.g. "v2" matching a
+# version but skipping the "v2" inside the word "advert2".
+_VERSION_REGEX = re.compile(
+ r"\bv?\d+\.\d+\b" # 1.2, v3.4
+ r"|\b(?:19|20)\d{2}\b" # 1999, 2024
+ r"|\b(?:GPT|gpt|Claude|claude|Gemini|gemini)-?\d+(?:\.\d+)?(?:o)?\b" # GPT-4, Claude 3.5
+ r"|\bgpt-image-\d+\b"
+)
+
+
+# Words signalling that the fact is asserting current truth. These age
+# fast — "X is the latest" was true last month, not now.
+_RECENCY_KEYWORDS = re.compile(
+ r"\b(?:best|current|latest|as of|now|today|recent|trending|leading|top-rated)\b",
+ re.IGNORECASE,
+)
+
+
+# Domains where facts go stale fastest: pricing, leadership, capability
+# claims about specific tools. Stable-fact counterparts (birthdays,
+# preferences) don't trigger these.
+_VOLATILE_DOMAIN = re.compile(
+ r"\b(?:price|costs?|priced?|fee|fees|charge|"
+ r"CEO|founder|head of|chairman|leader|president|director|"
+ r"market share|valuation|revenue|funding|"
+ r"supports?|integrates?|works with|powered by"
+ r")\b",
+ re.IGNORECASE,
+)
+
+
+def score_staleness(fact: "FactRow", *, now: datetime | None = None) -> float:
+ """Return a 0.0–1.0 score; ≥ ``STALENESS_THRESHOLD`` is a candidate.
+
+ Each heuristic adds an independent contribution; the score is
+ clamped at 1.0. Returns 0.0 for facts with empty text — the
+ sanitizer can't do anything with them so flagging is noise.
+
+ A fact with ONLY the age signal stays at 0.5 and does not cross
+ the threshold; a true-but-old preference like "user prefers dark
+ mode" doesn't get demoted just because it's old.
+ """
+ text = fact.fact or ""
+ if not text.strip():
+ return 0.0
+
+ now = now or datetime.now(timezone.utc)
+
+ score = 0.0
+ if _is_old(fact, now):
+ score += _AGE_WEIGHT
+ if _VERSION_REGEX.search(text):
+ score += _VERSION_WEIGHT
+ if _RECENCY_KEYWORDS.search(text):
+ score += _RECENCY_KEYWORD_WEIGHT
+ if _VOLATILE_DOMAIN.search(text):
+ score += _VOLATILE_DOMAIN_WEIGHT
+
+ return min(score, 1.0)
+
+
+def identify_stale_candidates(
+ facts: list["FactRow"], *, now: datetime | None = None
+) -> list[tuple["FactRow", float]]:
+ """Filter to facts at or above the staleness threshold.
+
+ Returns ``(fact, score)`` tuples ordered by descending score so the
+ sanitize prompt can render the most-suspect candidates first when
+ the candidate count exceeds the prompt budget.
+ """
+ candidates: list[tuple[FactRow, float]] = []
+ for fact in facts:
+ score = score_staleness(fact, now=now)
+ if score >= STALENESS_THRESHOLD:
+ candidates.append((fact, score))
+ candidates.sort(key=lambda pair: pair[1], reverse=True)
+ return candidates
+
+
+def _is_old(fact: "FactRow", now: datetime) -> bool:
+ """True when ``fact.created_at`` is more than 90 days in the past.
+
+ Missing or unparseable timestamps return False — we'd rather under-
+ flag a fact than over-flag every legacy edge that lost its
+ ``created_at`` in a migration.
+ """
+ if not fact.created_at:
+ return False
+ parsed = _parse_iso(fact.created_at)
+ if parsed is None:
+ return False
+ if parsed.tzinfo is None:
+ parsed = parsed.replace(tzinfo=timezone.utc)
+ return (now - parsed).days > 90
+
+
+def _parse_iso(raw: str) -> datetime | None:
+ """Best-effort ISO 8601 parse; returns None on any failure.
+
+ Graphiti stores ``created_at`` as a Cypher ``datetime`` which
+ round-trips through ``toString(...)`` as e.g. ``"2026-05-12T09:33Z"``
+ or ``"2026-05-12T09:33:14.123Z"``. Python's ``fromisoformat``
+ accepts both since 3.11.
+ """
+ try:
+ # Cypher's `Z` suffix isn't accepted by fromisoformat on older
+ # Pythons; normalize before parsing.
+ if raw.endswith("Z"):
+ raw = raw[:-1] + "+00:00"
+ return datetime.fromisoformat(raw)
+ except (ValueError, TypeError):
+ return None
diff --git a/autogpt_platform/backend/backend/copilot/dream/staleness_test.py b/autogpt_platform/backend/backend/copilot/dream/staleness_test.py
new file mode 100644
index 0000000000..10a69eb0fd
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/staleness_test.py
@@ -0,0 +1,147 @@
+"""Staleness heuristic tests — the critical guardrail is "stable facts
+must not score above threshold". Stale fact false positives are noise
+for the sanitizer; stable fact false positives delete real memory.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+from .fetch import FactRow
+from .staleness import STALENESS_THRESHOLD, identify_stale_candidates, score_staleness
+
+
+def _now() -> datetime:
+ return datetime(2026, 5, 21, tzinfo=timezone.utc)
+
+
+def _fact(
+ text: str, *, created_days_ago: int = 1, scope: str = "real:global"
+) -> FactRow:
+ created = _now() - timedelta(days=created_days_ago)
+ return FactRow(
+ uuid="f1",
+ source=None,
+ target=None,
+ name=None,
+ fact=text,
+ scope=scope,
+ confidence=0.8,
+ status="active",
+ created_at=created.isoformat().replace("+00:00", "Z"),
+ )
+
+
+def test_empty_fact_text_scores_zero():
+ assert score_staleness(_fact(""), now=_now()) == 0.0
+ assert score_staleness(_fact(" \n"), now=_now()) == 0.0
+
+
+def test_user_birthday_old_but_stable_stays_below_threshold():
+ """The headline edge case from spec §P0.3a — birthdays must not
+ be demoted just because they're old."""
+ fact = _fact("user's birthday is March 5", created_days_ago=400)
+ score = score_staleness(fact, now=_now())
+ assert score < STALENESS_THRESHOLD
+
+
+def test_old_preference_stays_below_threshold():
+ """'user prefers dark mode' — old and a preference — must survive."""
+ fact = _fact("user prefers dark mode in IDEs", created_days_ago=300)
+ score = score_staleness(fact, now=_now())
+ assert score < STALENESS_THRESHOLD
+
+
+def test_old_version_claim_crosses_threshold():
+ """Age + version regex hits both — the canonical "stale and wrong"
+ pattern: "GPT-4 is the best model" 18 months later."""
+ fact = _fact("GPT-4 is the best LLM available", created_days_ago=400)
+ score = score_staleness(fact, now=_now())
+ assert score >= STALENESS_THRESHOLD
+
+
+def test_current_pricing_claim_crosses_threshold():
+ """Pricing facts go stale fast even if the assertion is recent."""
+ fact = _fact("Claude Opus costs $15 per million input tokens")
+ score = score_staleness(fact, now=_now())
+ assert score >= STALENESS_THRESHOLD
+
+
+def test_leadership_claim_crosses_threshold():
+ """Company-leader facts are high churn."""
+ fact = _fact("Sundar Pichai is the CEO of Google")
+ score = score_staleness(fact, now=_now())
+ assert score >= STALENESS_THRESHOLD
+
+
+def test_recency_keyword_alone_does_not_cross_threshold():
+ """A single signal (just "latest") shouldn't trip — needs context."""
+ fact = _fact("This is the latest config", created_days_ago=1)
+ score = score_staleness(fact, now=_now())
+ # 0.4 < 0.6
+ assert score < STALENESS_THRESHOLD
+
+
+def test_age_signal_alone_does_not_cross_threshold():
+ """An old fact about nothing volatile shouldn't get demoted."""
+ fact = _fact("user works on weekends", created_days_ago=400)
+ score = score_staleness(fact, now=_now())
+ assert score < STALENESS_THRESHOLD
+
+
+def test_missing_created_at_does_not_trip_age_signal():
+ """Legacy edges with no created_at must not be flagged as old —
+ a fact whose ONLY potential signal is age scores zero when
+ created_at is missing."""
+ fact = FactRow(
+ uuid="f",
+ source=None,
+ target=None,
+ name=None,
+ fact="user works on weekends",
+ scope="real:global",
+ confidence=0.8,
+ status="active",
+ created_at=None,
+ )
+ score = score_staleness(fact, now=_now())
+ assert score == 0.0
+
+
+ "text",
+ [
+ "Claude 4 supports prompt caching",
+ "GPT-5 has a 1M context window",
+ "Anthropic's latest model is Opus 4.5",
+ "claude-sonnet-4 is currently best for code",
+ ],
+)
+def test_model_version_claims_with_recency_keyword_flagged(text):
+ """Model + version + recency keyword = high-confidence stale candidate."""
+ fact = _fact(text, created_days_ago=200)
+ score = score_staleness(fact, now=_now())
+ assert score >= STALENESS_THRESHOLD
+
+
+def test_identify_stale_candidates_returns_descending_score_order():
+ """Sanitize prompt needs most-suspect first when budget is tight."""
+ facts = [
+ _fact("user's birthday is March 5", created_days_ago=400), # below
+ _fact("GPT-4 is the best LLM", created_days_ago=400), # very high
+ _fact("Claude Opus costs $15/M tokens"), # high
+ ]
+ candidates = identify_stale_candidates(facts, now=_now())
+ assert len(candidates) == 2 # birthday filtered out
+ assert candidates[0][1] >= candidates[1][1]
+
+
+def test_identify_stale_candidates_returns_empty_when_no_candidates():
+ """Stable-only fact set produces an empty candidate list."""
+ facts = [
+ _fact("user prefers dark mode"),
+ _fact("user's birthday is March 5", created_days_ago=400),
+ ]
+ assert identify_stale_candidates(facts, now=_now()) == []
diff --git a/autogpt_platform/backend/backend/copilot/dream/webcheck/__init__.py b/autogpt_platform/backend/backend/copilot/dream/webcheck/__init__.py
new file mode 100644
index 0000000000..25622a11b3
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/webcheck/__init__.py
@@ -0,0 +1 @@
+"""Web-fact-check scaffolding for the dream pass (P0.5)."""
diff --git a/autogpt_platform/backend/backend/copilot/dream/webcheck/orchestrator_hook.py b/autogpt_platform/backend/backend/copilot/dream/webcheck/orchestrator_hook.py
new file mode 100644
index 0000000000..ee49e0f8e1
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/webcheck/orchestrator_hook.py
@@ -0,0 +1,63 @@
+"""Orchestrator hook — verify a batch of stale-fact candidates.
+
+Called from the dream orchestrator before phase 3 sanitization
+issues demotions, so the sanitizer prompt can see "the web also
+contradicts this" / "the web confirms this" alongside the internal
+heuristic score. The actual wiring is follow-up; this module just
+exposes the function shape and the concurrency guarantees the
+orchestrator needs:
+
+* ``enabled=False`` → no-op, returns empty dict.
+* No tool configured → no-op, returns empty dict.
+* Otherwise, all candidates are verified concurrently via
+ ``asyncio.gather``; per-item exceptions are caught and surfaced
+ on the result's ``error`` field so one bad lookup cannot kill
+ the batch.
+
+The return map is keyed by ``fact.uuid`` so the orchestrator can
+join verification results back onto its candidate list without
+re-matching on fact text.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from backend.copilot.dream.fetch import FactRow
+from backend.copilot.dream.webcheck.tool import WebFactCheckResult, WebFactCheckTool
+
+logger = logging.getLogger(__name__)
+
+
+async def verify_stale_candidates(
+ candidates: list[FactRow],
+ *,
+ enabled: bool,
+ tool: WebFactCheckTool | None = None,
+) -> dict[str, WebFactCheckResult]:
+ if not enabled or tool is None or not candidates:
+ return {}
+
+ async def _verify_one(candidate: FactRow) -> tuple[str, WebFactCheckResult]:
+ fact_text = candidate.fact or ""
+ try:
+ result = await tool.verify(fact_text)
+ except Exception as exc:
+ logger.warning(
+ "web_fact_check hook caught exception for uuid=%s: %s",
+ candidate.uuid,
+ exc,
+ )
+ result = WebFactCheckResult(
+ fact_text=fact_text,
+ verified=False,
+ contradicted=False,
+ sources=[],
+ confidence=0.0,
+ error=f"hook_error:{type(exc).__name__}",
+ )
+ return candidate.uuid, result
+
+ pairs = await asyncio.gather(*(_verify_one(c) for c in candidates))
+ return dict(pairs)
diff --git a/autogpt_platform/backend/backend/copilot/dream/webcheck/orchestrator_hook_test.py b/autogpt_platform/backend/backend/copilot/dream/webcheck/orchestrator_hook_test.py
new file mode 100644
index 0000000000..a3906c5157
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/webcheck/orchestrator_hook_test.py
@@ -0,0 +1,118 @@
+"""Tests for the dream orchestrator's web-fact-check hook.
+
+Guards the contract the dream orchestrator depends on:
+
+* disabled or no-tool → cheap no-op, zero backend calls.
+* a single raising backend lookup does not poison the rest of the
+ batch.
+* the returned map is keyed by ``fact.uuid`` so the orchestrator can
+ join results back without re-matching on text.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from backend.copilot.dream.fetch import FactRow
+
+from .orchestrator_hook import verify_stale_candidates
+from .tool import WebFactCheckResult, WebFactCheckTool
+
+
+def _fact(uuid: str, text: str = "some claim") -> FactRow:
+ return FactRow(
+ uuid=uuid,
+ source=None,
+ target=None,
+ name=None,
+ fact=text,
+ scope="real:global",
+ confidence=0.7,
+ status="active",
+ created_at="2026-05-01T00:00:00Z",
+ )
+
+
+class _RecordingBackend:
+ def __init__(self):
+ self.calls: list[str] = []
+
+ async def verify(self, fact_text: str) -> WebFactCheckResult:
+ self.calls.append(fact_text)
+ return WebFactCheckResult(
+ fact_text=fact_text,
+ verified=True,
+ contradicted=False,
+ sources=["https://example.com/ok"],
+ confidence=0.81,
+ )
+
+
+class _MixedBackend:
+ """Raises on the candidate whose fact text starts with 'bad:'."""
+
+ async def verify(self, fact_text: str) -> WebFactCheckResult:
+ if fact_text.startswith("bad:"):
+ raise RuntimeError("simulated lookup failure")
+ return WebFactCheckResult(
+ fact_text=fact_text,
+ verified=True,
+ contradicted=False,
+ sources=["https://example.com/ok"],
+ confidence=0.75,
+ )
+
+
+async def test_disabled_flag_short_circuits_and_skips_tool():
+ backend = _RecordingBackend()
+ tool = WebFactCheckTool(backend=backend)
+
+ result = await verify_stale_candidates(
+ [_fact("u1"), _fact("u2")], enabled=False, tool=tool
+ )
+
+ assert result == {}
+ assert backend.calls == []
+
+
+async def test_missing_tool_returns_empty_dict():
+ result = await verify_stale_candidates([_fact("u1")], enabled=True, tool=None)
+ assert result == {}
+
+
+async def test_mixed_batch_one_raise_other_results_land():
+ tool = WebFactCheckTool(backend=_MixedBackend())
+ candidates = [
+ _fact("good-1", "good: alpha"),
+ _fact("bad-1", "bad: beta"),
+ _fact("good-2", "good: gamma"),
+ ]
+
+ result = await verify_stale_candidates(candidates, enabled=True, tool=tool)
+
+ assert set(result.keys()) == {"good-1", "bad-1", "good-2"}
+ assert result["good-1"].verified is True
+ assert result["good-1"].error is None
+ assert result["good-2"].verified is True
+ assert result["good-2"].error is None
+ # The tool wrapper catches the backend's RuntimeError and surfaces it.
+ assert result["bad-1"].verified is False
+ assert result["bad-1"].error == "backend_error:RuntimeError"
+
+
+async def test_result_map_is_keyed_by_fact_uuid():
+ tool = WebFactCheckTool(backend=_RecordingBackend())
+ candidates = [
+ _fact("uuid-alpha", "alpha claim"),
+ _fact("uuid-beta", "beta claim"),
+ ]
+
+ result = await verify_stale_candidates(candidates, enabled=True, tool=tool)
+
+ assert set(result.keys()) == {"uuid-alpha", "uuid-beta"}
+ assert result["uuid-alpha"].fact_text == "alpha claim"
+ assert result["uuid-beta"].fact_text == "beta claim"
diff --git a/autogpt_platform/backend/backend/copilot/dream/webcheck/tool.py b/autogpt_platform/backend/backend/copilot/dream/webcheck/tool.py
new file mode 100644
index 0000000000..0ba5f9e6d8
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/webcheck/tool.py
@@ -0,0 +1,94 @@
+"""Web-fact-check tool — verifies a stale-fact candidate against the web.
+
+The actual search backend choice (Brave / Tavily / Perplexity / …) is
+deferred to product per ``dream/p0-spec.md`` §P0.5 open item #3, so
+this module ships the *shape* of the tool only:
+
+* :class:`WebFactCheckResult` — what the orchestrator hook receives
+ back per candidate.
+* :class:`SearchBackend` — protocol that any future provider adapter
+ must satisfy. Keeping the surface narrow (one async ``verify``
+ call) means swapping providers is a one-file change.
+* :class:`_NullSearchBackend` — default backend that returns
+ ``error="no_search_backend_configured"`` so the tool is callable
+ end-to-end with no env config.
+* :class:`WebFactCheckTool` — caller-facing wrapper that swallows
+ backend exceptions into the result's ``error`` field; one bad
+ lookup must not abort the dream pass.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Protocol
+
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+
+class WebFactCheckResult(BaseModel):
+ """Per-fact verification result handed back to the dream pipeline."""
+
+ fact_text: str
+ verified: bool = False
+ contradicted: bool = False
+ sources: list[str] = Field(default_factory=list)
+ confidence: float = 0.0
+ error: str | None = None
+
+
+class SearchBackend(Protocol):
+ """Pluggable search backend the tool delegates verification to.
+
+ Returning a populated :class:`WebFactCheckResult` (rather than raw
+ search hits) keeps backend-specific judging logic next to the
+ backend that owns the search API and rate-limit budget.
+ """
+
+ async def verify(self, fact_text: str) -> WebFactCheckResult: ...
+
+
+class _NullSearchBackend:
+ """Default backend used when no provider has been wired in yet."""
+
+ async def verify(self, fact_text: str) -> WebFactCheckResult:
+ return WebFactCheckResult(
+ fact_text=fact_text,
+ verified=False,
+ contradicted=False,
+ sources=[],
+ confidence=0.0,
+ error="no_search_backend_configured",
+ )
+
+
+class WebFactCheckTool:
+ """Caller-facing wrapper around a :class:`SearchBackend`.
+
+ The backend choice is injected so tests and future provider PRs
+ can swap implementations without touching the orchestrator. When
+ no backend is passed, :class:`_NullSearchBackend` is used so the
+ tool stays callable end-to-end in a fresh checkout.
+ """
+
+ def __init__(self, backend: SearchBackend | None = None) -> None:
+ self._backend: SearchBackend = backend or _NullSearchBackend()
+
+ async def verify(self, fact_text: str) -> WebFactCheckResult:
+ try:
+ return await self._backend.verify(fact_text)
+ except Exception as exc:
+ logger.warning(
+ "web_fact_check backend raised for fact=%r: %s",
+ fact_text[:80],
+ exc,
+ )
+ return WebFactCheckResult(
+ fact_text=fact_text,
+ verified=False,
+ contradicted=False,
+ sources=[],
+ confidence=0.0,
+ error=f"backend_error:{type(exc).__name__}",
+ )
diff --git a/autogpt_platform/backend/backend/copilot/dream/webcheck/tool_test.py b/autogpt_platform/backend/backend/copilot/dream/webcheck/tool_test.py
new file mode 100644
index 0000000000..6f15b85145
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream/webcheck/tool_test.py
@@ -0,0 +1,94 @@
+"""Tests for the web-fact-check tool shape.
+
+The actual search backend choice is deferred (see ``dream/p0-spec.md``
+§P0.5 open item #3), so these tests only cover the protocol contract
+the orchestrator will rely on:
+
+* default (no backend) returns the documented null-backend error;
+* the tool propagates a happy-path verified result;
+* backend exceptions become an ``error=...`` field, not a raise.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from .tool import (
+ SearchBackend,
+ WebFactCheckResult,
+ WebFactCheckTool,
+ _NullSearchBackend,
+)
+
+
+class _StubVerifiedBackend:
+ async def verify(self, fact_text: str) -> WebFactCheckResult:
+ return WebFactCheckResult(
+ fact_text=fact_text,
+ verified=True,
+ contradicted=False,
+ sources=["https://example.com/source-a", "https://example.com/source-b"],
+ confidence=0.92,
+ error=None,
+ )
+
+
+class _StubRaisingBackend:
+ async def verify(self, fact_text: str) -> WebFactCheckResult:
+ raise RuntimeError("backend exploded")
+
+
+async def test_null_backend_returns_no_backend_configured_error():
+ backend = _NullSearchBackend()
+ result = await backend.verify("the sky is blue")
+
+ assert isinstance(result, WebFactCheckResult)
+ assert result.fact_text == "the sky is blue"
+ assert result.verified is False
+ assert result.contradicted is False
+ assert result.sources == []
+ assert result.confidence == 0.0
+ assert result.error == "no_search_backend_configured"
+
+
+async def test_tool_with_default_backend_returns_result_shape():
+ tool = WebFactCheckTool()
+
+ result = await tool.verify("Python is a programming language")
+
+ assert isinstance(result, WebFactCheckResult)
+ assert result.fact_text == "Python is a programming language"
+ assert result.error == "no_search_backend_configured"
+
+
+async def test_tool_with_verified_backend_propagates_sources_and_flag():
+ backend: SearchBackend = _StubVerifiedBackend()
+ tool = WebFactCheckTool(backend=backend)
+
+ result = await tool.verify("Earth orbits the Sun")
+
+ assert result.verified is True
+ assert result.contradicted is False
+ assert result.sources == [
+ "https://example.com/source-a",
+ "https://example.com/source-b",
+ ]
+ assert result.confidence == pytest.approx(0.92)
+ assert result.error is None
+
+
+async def test_tool_with_raising_backend_returns_error_not_raise():
+ backend: SearchBackend = _StubRaisingBackend()
+ tool = WebFactCheckTool(backend=backend)
+
+ result = await tool.verify("anything")
+
+ assert result.verified is False
+ assert result.contradicted is False
+ assert result.sources == []
+ assert result.confidence == 0.0
+ assert result.error == "backend_error:RuntimeError"
diff --git a/autogpt_platform/backend/backend/copilot/dream_events.py b/autogpt_platform/backend/backend/copilot/dream_events.py
new file mode 100644
index 0000000000..1622b7358a
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream_events.py
@@ -0,0 +1,100 @@
+"""SSE events emitted when a dream pass produces operations.
+
+Lives in its own module so ``response_model.py`` stays under the 300-line
+target. The event mirrors the ``data-status`` / ``data-cursor`` shape
+already in use by the AI SDK v5 wire protocol — a ``data-<name>`` part
+with an opaque ``data`` payload — so the frontend just needs to recognise
+a new ``part.type`` rather than learn a whole new envelope.
+
+Per ``dream/p0-spec.md`` §11 item #11 and ``dream/TODO.md`` P9 note: the
+emitter helper is provided here but NOT wired into the dream orchestrator
+yet. P6 (surface dreams in chat UI) and P9 (daydreaming) own the wire-in
+so the gating (``mode in {dream, daydream}``) lives next to the
+orchestrator state machine, not duplicated here.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from pydantic import Field
+
+from backend.copilot.dream.schemas import DreamOperationsSnapshot
+from backend.copilot.response_model import ResponseType, StreamBaseResponse
+
+logger = logging.getLogger(__name__)
+
+
+class StreamDreamOperations(StreamBaseResponse):
+ """Structured snapshot of a completed dream pass, surfaced inline on
+ the chat stream so P6 (surface in chat) and P9 (daydreaming) can
+ render a "dream summary" artifact without a separate admin fetch.
+
+ The frontend Vercel AI SDK accumulates this as a
+ ``type="data-dream-operations"`` UIMessage part with the snapshot
+ available under ``part.data.snapshot``. Bookkeeping fields
+ (``dream_pass_id``, ``user_id``) live alongside so a consumer can
+ reconcile against the admin endpoint or AgentProbe scoring without
+ re-querying.
+ """
+
+ type: ResponseType = Field(
+ default=ResponseType.DREAM_OPERATIONS,
+ description="AI SDK v5 data part wire type.",
+ )
+ snapshot: DreamOperationsSnapshot = Field(
+ ..., description="Per-operation rollup produced by phase 3 + apply.py."
+ )
+ dream_pass_id: str = Field(
+ ..., description="Identifier for the dream pass that produced this snapshot."
+ )
+ user_id: str = Field(..., description="Owner of the dream pass.")
+
+ def to_sse(self) -> str:
+ """Emit as an AI SDK v5 ``data-<name>`` part.
+
+ Mirrors ``StreamStatus.to_sse`` — payload nests under ``data`` so
+ the SDK surfaces it on ``message.parts`` as a recognised data
+ part instead of dropping it as unknown.
+ """
+ payload: dict[str, Any] = {
+ "type": self.type.value,
+ "data": {
+ "snapshot": self.snapshot.model_dump(mode="json"),
+ "dream_pass_id": self.dream_pass_id,
+ "user_id": self.user_id,
+ },
+ }
+ return f"data: {json.dumps(payload)}\n\n"
+
+
+# ---------------------------------------------------------------------------
+# Emitter helper
+# ---------------------------------------------------------------------------
+
+
+EmitFn = Callable[[StreamBaseResponse], Awaitable[None]]
+
+
+async def emit_dream_operations_event(
+ emit: EmitFn,
+ snapshot: DreamOperationsSnapshot,
+ dream_pass_id: str,
+ user_id: str,
+) -> None:
+ """Push a :class:`StreamDreamOperations` event onto the active stream.
+
+ The orchestrator / daydream path passes its own ``emit`` closure (the
+ same one baseline / sdk use for ``StreamStatus``) so the event lands
+ on the user's open SSE subscription and gets persisted via the Redis
+ snapshot pipeline alongside every other turn event.
+ """
+ event = StreamDreamOperations(
+ snapshot=snapshot,
+ dream_pass_id=dream_pass_id,
+ user_id=user_id,
+ )
+ await emit(event)
diff --git a/autogpt_platform/backend/backend/copilot/dream_events_test.py b/autogpt_platform/backend/backend/copilot/dream_events_test.py
new file mode 100644
index 0000000000..6a4109879a
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/dream_events_test.py
@@ -0,0 +1,158 @@
+"""Tests for the ``dream.operations`` SSE event variant.
+
+Covers payload shape, the SSE wire format (``data: ... \\n\\n``), and the
+``emit_dream_operations_event`` helper so the future P6 / P9 wire-in just
+has to import the helper and pass an emit closure.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+
+import pytest
+import pytest_asyncio
+
+from backend.copilot.dream.schemas import (
+ DemotionSummary,
+ DreamOperationsSnapshot,
+ EntityInvalidationSummary,
+ WriteSummary,
+)
+from backend.copilot.dream_events import (
+ StreamDreamOperations,
+ emit_dream_operations_event,
+)
+from backend.copilot.response_model import ResponseType, StreamBaseResponse
+
+
+# Override heavy session-scope fixtures from ``backend/conftest.py`` —
+# these tests are pure pydantic / async helper checks and don't need a
+# real backend. Mirrors ``stream_heartbeat_test.py``.
+@pytest_asyncio.fixture(scope="session", loop_scope="session", name="server")
+async def _server_noop() -> None:
+ return None
+
+
+@pytest_asyncio.fixture(
+ scope="session", loop_scope="session", autouse=True, name="graph_cleanup"
+)
+async def _graph_cleanup_noop() -> AsyncIterator[None]:
+ yield
+
+
+def _sample_snapshot() -> DreamOperationsSnapshot:
+ """Build a non-trivial snapshot exercising every field."""
+ return DreamOperationsSnapshot(
+ writes=[
+ WriteSummary(
+ edge_uuid="edge-write-1",
+ content="The user prefers async tasks.",
+ scope="real:global",
+ confidence=0.82,
+ status="active",
+ source_episode_uuids=["ep-1", "ep-2"],
+ ),
+ ],
+ proposals=[
+ WriteSummary(
+ edge_uuid=None,
+ content="User may be open to scheduled dream passes.",
+ status="tentative",
+ ),
+ ],
+ demotions=[
+ DemotionSummary(
+ edge_uuid="edge-demote-1",
+ reason="stale_fact",
+ new_status="superseded",
+ applied=True,
+ ),
+ ],
+ entity_invalidations=[
+ EntityInvalidationSummary(
+ entity_uuid="ent-1",
+ reason="entity_invalidated:ent-1",
+ edges_touched=["edge-demote-1"],
+ ),
+ ],
+ )
+
+
+def test_event_carries_snapshot_pass_id_and_user_id():
+ """Constructed event echoes every supplied identifier and the full
+ snapshot payload (no fields dropped at the pydantic boundary)."""
+ snapshot = _sample_snapshot()
+
+ event = StreamDreamOperations(
+ snapshot=snapshot,
+ dream_pass_id="dp-123",
+ user_id="user-abc",
+ )
+
+ assert event.type is ResponseType.DREAM_OPERATIONS
+ assert event.dream_pass_id == "dp-123"
+ assert event.user_id == "user-abc"
+ assert event.snapshot == snapshot
+
+
+def test_sse_line_uses_ai_sdk_data_part_envelope():
+ """``to_sse`` produces a single ``data: <json>\\n\\n`` line whose
+ type matches the AI SDK v5 ``data-<name>`` convention and whose
+ payload is nested under ``data`` (mirrors ``StreamStatus``)."""
+ snapshot = _sample_snapshot()
+ event = StreamDreamOperations(
+ snapshot=snapshot, dream_pass_id="dp-1", user_id="u-1"
+ )
+
+ line = event.to_sse()
+
+ assert line.startswith("data: ")
+ assert line.endswith("\n\n")
+
+ body = json.loads(line.removeprefix("data: ").rstrip("\n"))
+ assert body["type"] == "data-dream-operations"
+ assert set(body["data"].keys()) == {"snapshot", "dream_pass_id", "user_id"}
+ assert body["data"]["dream_pass_id"] == "dp-1"
+ assert body["data"]["user_id"] == "u-1"
+ # The snapshot payload must round-trip cleanly through the snapshot
+ # pydantic model (no drift in list lengths or field names).
+ rehydrated = DreamOperationsSnapshot.model_validate(body["data"]["snapshot"])
+ assert rehydrated == snapshot
+
+
+def test_event_is_a_stream_base_response_subclass():
+ """The event must be recognised as a ``StreamBaseResponse`` so the
+ existing emit / reconstruction pipeline accepts it without bespoke
+ type handling."""
+ snapshot = _sample_snapshot()
+ event = StreamDreamOperations(
+ snapshot=snapshot, dream_pass_id="dp-1", user_id="u-1"
+ )
+ assert isinstance(event, StreamBaseResponse)
+
+
+async def test_emitter_helper_pushes_one_event_via_emit_closure():
+ """The helper builds the event and pushes it through the caller's
+ ``emit`` closure exactly once — no double-emit, no out-of-order
+ arguments."""
+ received: list[StreamBaseResponse] = []
+
+ async def emit(event: StreamBaseResponse) -> None:
+ received.append(event)
+
+ snapshot = _sample_snapshot()
+ await emit_dream_operations_event(
+ emit=emit,
+ snapshot=snapshot,
+ dream_pass_id="dp-emit",
+ user_id="u-emit",
+ )
+
+ assert len(received) == 1
+ pushed = received[0]
+ assert isinstance(pushed, StreamDreamOperations)
+ assert pushed.dream_pass_id == "dp-emit"
+ assert pushed.user_id == "u-emit"
+ assert pushed.snapshot == snapshot
diff --git a/autogpt_platform/backend/backend/copilot/eval/__init__.py b/autogpt_platform/backend/backend/copilot/eval/__init__.py
new file mode 100644
index 0000000000..bb042bf857
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/eval/__init__.py
@@ -0,0 +1,18 @@
+"""Dream-pass evaluation harness (P0.6).
+
+Snapshots cost / latency / quality metrics against a stable input so we
+can tell whether changes to the dream pipeline (P0.3a stale-fact, P0.4
+ratification, P0.5 web fact-check) are net positive or net regressions.
+
+Architecture: AgentProbe (TS, separate repo at ~/code/agpt/AgentProbe)
+owns the scorers and the runner for retrieval / demotion / dedup /
+procedure. This package provides the Python orchestration shim
+(``dream-eval`` CLI) plus our own metrics for ratification / cost /
+latency that are tightly coupled to the dream-orchestrator shapes.
+
+The shim shells out to ``bun run agentprobe -- ...``, captures the JSON
+output, decorates with platform metadata (graphiti_version, git_sha,
+transport), and writes ``eval/results.json``.
+
+See ``dream/p0-spec.md`` §7 for the spec.
+"""
diff --git a/autogpt_platform/backend/backend/copilot/eval/cost_latency_suite.py b/autogpt_platform/backend/backend/copilot/eval/cost_latency_suite.py
new file mode 100644
index 0000000000..8e676e4da8
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/eval/cost_latency_suite.py
@@ -0,0 +1,103 @@
+"""Cost + latency rollup from a batch of dream passes.
+
+Consumes a list of ``DreamPassResult`` (each one wraps `elapsed_seconds`
+and `usage`) and rolls them into the suite block written to
+``results.json``. Pure data — the caller supplies the passes (synthetic
+in tests, real-API runs in cloud). Keeps the harness composable: the
+runner doesn't care whether the passes came from a live cluster or a
+canned fixture.
+
+Per ``dream/p0-spec.md`` §7 the report shape is::
+
+ {
+ "n": <pass count>,
+ "skipped": <skipped pass count>,
+ "errored": <errored pass count>,
+ "latency": <latency_summary block>,
+ "cost": {
+ "total_usd": <sum of pass total_cost_usd, None if any unknown>,
+ "mean_usd": <mean over passes with known cost>,
+ "total_input_tokens": <sum>,
+ "total_output_tokens": <sum>,
+ "total_cache_read_tokens": <sum>,
+ "total_cache_creation_tokens": <sum>
+ },
+ "by_execution_path": { <path>: <pass count> ... }
+ }
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import Sequence
+
+from pydantic.dataclasses import dataclass
+
+from backend.copilot.dream.schemas import DreamPassResult
+
+from .metrics import latency_summary, mean
+
+
+@dataclass(frozen=True)
+class CostLatencySuiteResult:
+ n: int
+ skipped: int
+ errored: int
+ latency: dict[str, float]
+ cost: dict[str, float | int | None]
+ by_execution_path: dict[str, int]
+
+
+def run_cost_latency_suite(
+ passes: Sequence[DreamPassResult],
+) -> CostLatencySuiteResult:
+ skipped = sum(1 for p in passes if p.skipped)
+ errored = sum(1 for p in passes if p.error is not None)
+
+ # Latency: only count passes that actually ran (skipped passes
+ # short-circuit at the lock or fetch step and would distort p95).
+ elapsed = [
+ float(p.elapsed_seconds)
+ for p in passes
+ if p.elapsed_seconds is not None and not p.skipped
+ ]
+
+ total_input = sum(p.usage.total_input_tokens for p in passes if p.usage)
+ total_output = sum(p.usage.total_output_tokens for p in passes if p.usage)
+ total_cache_read = sum(p.usage.total_cache_read_tokens for p in passes if p.usage)
+ total_cache_creation = sum(
+ p.usage.total_cache_creation_tokens for p in passes if p.usage
+ )
+
+ known_costs = [
+ float(p.usage.total_cost_usd)
+ for p in passes
+ if p.usage and p.usage.total_cost_usd is not None
+ ]
+ # total_usd is None if ANY pass had unknown cost — surfacing the
+ # gap is more useful than reporting a confidently-wrong figure.
+ any_unknown = any(
+ p.usage is None or p.usage.total_cost_usd is None
+ for p in passes
+ if not p.skipped
+ )
+ total_usd: float | None = None if any_unknown else round(sum(known_costs), 6)
+ mean_usd: float | None = round(mean(known_costs), 6) if known_costs else None
+
+ path_counts = Counter(p.execution_path for p in passes if not p.skipped)
+
+ return CostLatencySuiteResult(
+ n=len(passes),
+ skipped=skipped,
+ errored=errored,
+ latency=latency_summary(elapsed),
+ cost={
+ "total_usd": total_usd,
+ "mean_usd": mean_usd,
+ "total_input_tokens": total_input,
+ "total_output_tokens": total_output,
+ "total_cache_read_tokens": total_cache_read,
+ "total_cache_creation_tokens": total_cache_creation,
+ },
+ by_execution_path=dict(path_counts),
+ )
diff --git a/autogpt_platform/backend/backend/copilot/eval/datasets.py b/autogpt_platform/backend/backend/copilot/eval/datasets.py
new file mode 100644
index 0000000000..8bc16236f4
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/eval/datasets.py
@@ -0,0 +1,67 @@
+"""Curated fixtures used by the dream-eval staleness benchmark.
+
+The 12-row split here is the *unit-test sized* version of the 50-fact
+fixture called for in ``dream/p0-spec.md`` §3. Twelve covers every
+heuristic axis (age, version regex, recency keyword, volatile domain)
+plus the headline edge cases (birthday / preference). The full 50-row
+set comes in when the eval harness graduates from unit-of-record to a
+real cloud-benchmark suite; until then, twelve is what we need to
+gate "did P0.3a regress" in CI.
+
+Adding a row:
+ * Real-world looking — phrases the assistant might actually persist.
+ * One reason per row in the docstring of ``expected_stale=True`` —
+ helps future readers understand WHY each fact should be demoted.
+"""
+
+from __future__ import annotations
+
+from pydantic.dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class StalenessFixture:
+ """One labeled fact for the staleness benchmark.
+
+ ``expected_stale`` is the ground-truth label: True means the
+ sanitizer SHOULD demote this fact; False means a healthy P0.3a
+ must preserve it.
+ """
+
+ fact_text: str
+ created_days_ago: int
+ expected_stale: bool
+
+
+# Stable-fact half — must score below threshold. False positives here
+# delete real user memory, so this set is the high-cost side of the
+# precision/recall tradeoff.
+STABLE_FACT_FIXTURES: list[StalenessFixture] = [
+ StalenessFixture("user's birthday is March 5", 400, False),
+ StalenessFixture("user prefers dark mode in IDEs", 300, False),
+ StalenessFixture("user lives in Boston", 250, False),
+ StalenessFixture("user works on weekends", 400, False),
+ StalenessFixture("user is allergic to peanuts", 600, False),
+ StalenessFixture("user's first programming language was Python", 800, False),
+]
+
+
+# Stale-fact half — must score at or above threshold. False negatives
+# leave wrong assertions in memory; the sanitizer's job downstream is
+# to verify before demoting, so the cost of a flag-but-don't-demote
+# is just prompt noise.
+STALE_FACT_FIXTURES: list[StalenessFixture] = [
+ # Age + version regex hit
+ StalenessFixture("GPT-4 is the best LLM available", 400, True),
+ StalenessFixture("Claude 2.0 is the most capable Anthropic model", 500, True),
+ # Volatile domain — pricing / leadership / market claims
+ StalenessFixture("Claude Opus costs $15 per million input tokens", 30, True),
+ StalenessFixture("Sundar Pichai is the CEO of Google", 30, True),
+ StalenessFixture("OpenAI's valuation is $80 billion", 60, True),
+ StalenessFixture("ChatGPT is the leading consumer AI product", 200, True),
+]
+
+
+ALL_STALENESS_FIXTURES: list[StalenessFixture] = (
+ STABLE_FACT_FIXTURES + STALE_FACT_FIXTURES
+)
diff --git a/autogpt_platform/backend/backend/copilot/eval/metrics.py b/autogpt_platform/backend/backend/copilot/eval/metrics.py
new file mode 100644
index 0000000000..7196700a95
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/eval/metrics.py
@@ -0,0 +1,51 @@
+"""Pure stats functions for the dream-eval harness.
+
+No I/O. Tests pin known-answer cases. Suites import these to roll up
+per-run elapsed_seconds / per-pass token counts into the aggregate
+fields written to ``results.json``.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Sequence
+
+
+def percentile(values: Sequence[float], p: float) -> float:
+ """Linear-interpolation percentile, p in [0, 100].
+
+ Returns 0.0 on empty input rather than raising. Used so a freshly
+ seeded run that yields zero passes doesn't crash the report.
+ """
+ if not values:
+ return 0.0
+ if p <= 0:
+ return float(min(values))
+ if p >= 100:
+ return float(max(values))
+ sorted_vals = sorted(values)
+ rank = (p / 100.0) * (len(sorted_vals) - 1)
+ lo = int(math.floor(rank))
+ hi = int(math.ceil(rank))
+ if lo == hi:
+ return float(sorted_vals[lo])
+ frac = rank - lo
+ return float(sorted_vals[lo] + (sorted_vals[hi] - sorted_vals[lo]) * frac)
+
+
+def mean(values: Sequence[float]) -> float:
+ if not values:
+ return 0.0
+ return float(sum(values)) / len(values)
+
+
+def latency_summary(elapsed_seconds: Sequence[float]) -> dict[str, float]:
+ """Stat block matching the ``results.json`` schema in p0-spec §7."""
+ return {
+ "n": len(elapsed_seconds),
+ "mean_seconds": mean(elapsed_seconds),
+ "p50_seconds": percentile(elapsed_seconds, 50),
+ "p95_seconds": percentile(elapsed_seconds, 95),
+ "min_seconds": float(min(elapsed_seconds)) if elapsed_seconds else 0.0,
+ "max_seconds": float(max(elapsed_seconds)) if elapsed_seconds else 0.0,
+ }
diff --git a/autogpt_platform/backend/backend/copilot/eval/metrics_test.py b/autogpt_platform/backend/backend/copilot/eval/metrics_test.py
new file mode 100644
index 0000000000..2fa86555ab
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/eval/metrics_test.py
@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import pytest
+
+from .metrics import latency_summary, mean, percentile
+
+
+def test_percentile_empty_returns_zero():
+ assert percentile([], 50) == 0.0
+
+
+ "p,expected",
+ [
+ (0, 1.0),
+ (50, 3.0),
+ (100, 5.0),
+ # 95th of [1,2,3,4,5]: rank = 0.95 * 4 = 3.8 → 4 + 0.8 * (5-4) = 4.8
+ (95, 4.8),
+ ],
+)
+def test_percentile_linear_interpolation(p: float, expected: float):
+ assert percentile([1.0, 2.0, 3.0, 4.0, 5.0], p) == pytest.approx(expected)
+
+
+def test_percentile_unsorted_input_is_sorted_internally():
+ """Caller can pass values in any order."""
+ assert percentile([5.0, 1.0, 3.0, 2.0, 4.0], 50) == pytest.approx(3.0)
+
+
+def test_mean_empty():
+ assert mean([]) == 0.0
+
+
+def test_mean_basic():
+ assert mean([1.0, 2.0, 3.0]) == pytest.approx(2.0)
+
+
+def test_latency_summary_empty_yields_zeroed_block():
+ """A freshly-seeded eval that produced zero passes shouldn't crash —
+ every numeric field reads 0.0 / 0."""
+ s = latency_summary([])
+ assert s == {
+ "n": 0,
+ "mean_seconds": 0.0,
+ "p50_seconds": 0.0,
+ "p95_seconds": 0.0,
+ "min_seconds": 0.0,
+ "max_seconds": 0.0,
+ }
+
+
+def test_latency_summary_realistic_block():
+ """Spot-check the aggregate fields against a known input."""
+ s = latency_summary([1.0, 2.0, 3.0, 4.0, 100.0])
+ assert s["n"] == 5
+ assert s["mean_seconds"] == pytest.approx(22.0)
+ assert s["p50_seconds"] == pytest.approx(3.0)
+ # 95th of [1,2,3,4,100]: rank=3.8 → 4 + 0.8*(100-4) = 80.8
+ assert s["p95_seconds"] == pytest.approx(80.8)
+ assert s["min_seconds"] == 1.0
+ assert s["max_seconds"] == 100.0
diff --git a/autogpt_platform/backend/backend/copilot/eval/runner.py b/autogpt_platform/backend/backend/copilot/eval/runner.py
new file mode 100644
index 0000000000..57b40172f8
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/eval/runner.py
@@ -0,0 +1,110 @@
+"""Dream-eval harness — single-pass aggregator.
+
+Composes the per-suite runners into one ``DreamEvalResult`` matching
+the schema in ``dream/p0-spec.md`` §7. AgentProbe drives the live
+side (runs N dream passes against a real cluster); this module is
+what AgentProbe POSTs the results to / calls into. Synthetic tests
+exercise the runner without any I/O.
+
+The runner deliberately does NOT spawn dream passes itself. Coupling
+the harness to the orchestrator would force CI to stand up FalkorDB /
+Supabase / Redis for every run. AgentProbe (the user's TS repo) owns
+the live-run side; this module owns the metrics roll-up + report
+shape so both the live runs AND the CI smoke runs use the same
+``results.json`` schema.
+
+Suites available today:
+ * staleness — P0.3a heuristic precision/recall/stability
+ * cost_latency — per-pass tokens + USD + p50/p95 elapsed
+
+Deferred to future tasks (placeholder slots in the result dict):
+ * ratification (P0.4 — needs the ratification scheduler, task #30)
+ * web_fact_check (P0.5 — needs the webcheck module, task #32)
+ * retrieval (warm-context golden query set — future)
+ * demotion (precision/recall against ground-truth demotion labels —
+ needs the full 50-fact fixture).
+
+When a deferred suite gets implemented, add it to ``_run_one_suite``
+and document it in the dict at the call site — no schema migration
+needed (the report is open-ended).
+"""
+
+from __future__ import annotations
+
+import json
+import platform
+from datetime import datetime, timezone
+from typing import Any, Sequence
+
+from pydantic import Field
+from pydantic.dataclasses import dataclass
+from pydantic_core import to_jsonable_python
+
+from backend.copilot.dream.schemas import DreamPassResult
+
+from .cost_latency_suite import run_cost_latency_suite
+from .datasets import ALL_STALENESS_FIXTURES, StalenessFixture
+from .staleness_suite import run_staleness_suite
+
+
+@dataclass(frozen=True)
+class DreamEvalConfig:
+ """What suites + what fixtures one ``run_dream_eval`` call covers.
+
+ Defaults to "all available suites with their default fixtures" so
+ a caller without strong opinions still gets the full report.
+ """
+
+ run_staleness: bool = True
+ run_cost_latency: bool = True
+ staleness_fixtures: Sequence[StalenessFixture] = Field(
+ default_factory=lambda: tuple(ALL_STALENESS_FIXTURES)
+ )
+
+
+@dataclass(frozen=True)
+class DreamEvalResult:
+ run_id: str
+ ts: str
+ python_version: str
+ suites: dict[str, Any]
+
+ def to_json(self, *, indent: int | None = 2) -> str:
+ return json.dumps(to_jsonable_python(self), indent=indent)
+
+
+def run_dream_eval(
+ *,
+ run_id: str,
+ passes: Sequence[DreamPassResult] = (),
+ config: DreamEvalConfig | None = None,
+ now: datetime | None = None,
+) -> DreamEvalResult:
+ """Aggregate suite results for one eval run.
+
+ ``passes`` is the list of dream passes driven externally (by
+ AgentProbe in production, or synthetic ``DreamPassResult`` objects
+ in tests). Empty ``passes`` is fine — the cost/latency suite just
+ reports zeros and the staleness suite runs independently against
+ its fixture.
+
+ ``run_id`` is the AgentProbe scenario id (when called from a live
+ run) or a deterministic test id; carried through to ``results.json``
+ so the report joins back to its source run.
+ """
+ config = config or DreamEvalConfig()
+ now = now or datetime.now(timezone.utc)
+
+ suites: dict[str, Any] = {}
+
+ if config.run_staleness:
+ suites["staleness"] = run_staleness_suite(config.staleness_fixtures, now=now)
+ if config.run_cost_latency:
+ suites["cost_latency"] = run_cost_latency_suite(passes)
+
+ return DreamEvalResult(
+ run_id=run_id,
+ ts=now.isoformat().replace("+00:00", "Z"),
+ python_version=platform.python_version(),
+ suites={k: to_jsonable_python(v) for k, v in suites.items()},
+ )
diff --git a/autogpt_platform/backend/backend/copilot/eval/runner_test.py b/autogpt_platform/backend/backend/copilot/eval/runner_test.py
new file mode 100644
index 0000000000..2a9f4174cc
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/eval/runner_test.py
@@ -0,0 +1,212 @@
+"""Eval runner tests — verify schema + suite invariants.
+
+The critical contract is the report schema (downstream dashboards read
+this JSON) + the staleness suite's stability number (a regression here
+means we're about to delete real user memory).
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+import pytest
+
+from backend.copilot.dream.schemas import DreamPassResult, DreamPassUsage, PhaseUsage
+
+from .datasets import ALL_STALENESS_FIXTURES, STABLE_FACT_FIXTURES, STALE_FACT_FIXTURES
+from .runner import DreamEvalConfig, run_dream_eval
+from .staleness_suite import run_staleness_suite
+
+
+def _now() -> datetime:
+ return datetime(2026, 5, 21, tzinfo=timezone.utc)
+
+
+def _pass(
+ *,
+ elapsed: float,
+ cost: float | None = 0.005,
+ skipped: bool = False,
+ error: str | None = None,
+ path: str = "sync_baseline",
+) -> DreamPassResult:
+ return DreamPassResult(
+ user_id="u",
+ pass_id="p",
+ execution_path=path, # type: ignore[arg-type]
+ elapsed_seconds=elapsed,
+ skipped=skipped,
+ error=error,
+ usage=(
+ DreamPassUsage(
+ phases=[PhaseUsage(phase="consolidate", model="m", cost_usd=cost)],
+ total_cost_usd=cost,
+ )
+ if not skipped
+ else None
+ ),
+ )
+
+
+# ---------------------------------------------------------------------------
+# staleness suite
+# ---------------------------------------------------------------------------
+
+
+def test_staleness_suite_preserves_all_stable_facts_in_fixture():
+ """Stability == 1.0 — every stable fact must stay below threshold.
+ A drop here means false positives are deleting real memory."""
+ result = run_staleness_suite(STABLE_FACT_FIXTURES, now=_now())
+ assert result.stability == 1.0
+ assert result.failures == []
+
+
+def test_staleness_suite_flags_at_least_two_thirds_of_stale_facts():
+ """Recall ≥ 0.67 — the heuristics don't have to catch every stale
+ fact (sanitizer also catches contradictions via consolidated facts)
+ but should catch most. False negatives just cost one more cycle."""
+ result = run_staleness_suite(STALE_FACT_FIXTURES, now=_now())
+ assert result.recall >= 0.67
+
+
+def test_staleness_suite_reports_specific_failures_when_misclassified():
+ """A misclassification surfaces in `failures` with the fact text +
+ score — needed to debug regressions from results.json alone."""
+ from .datasets import StalenessFixture
+
+ bad_fixture = [
+ StalenessFixture("user prefers dark mode", 300, True), # FN — stable
+ ]
+ result = run_staleness_suite(bad_fixture, now=_now())
+ assert len(result.failures) == 1
+ assert "FN" in result.failures[0]
+ assert "user prefers dark mode" in result.failures[0]
+
+
+# ---------------------------------------------------------------------------
+# cost + latency suite
+# ---------------------------------------------------------------------------
+
+
+def test_cost_latency_suite_aggregates_pass_counts_and_path_breakdown():
+ passes = [
+ _pass(elapsed=1.0, path="sync_baseline"),
+ _pass(elapsed=2.0, path="sync_baseline"),
+ _pass(elapsed=3.0, path="anthropic_batch"),
+ _pass(elapsed=0, skipped=True),
+ ]
+ from .cost_latency_suite import run_cost_latency_suite
+
+ result = run_cost_latency_suite(passes)
+ assert result.n == 4
+ assert result.skipped == 1
+ assert result.by_execution_path == {"sync_baseline": 2, "anthropic_batch": 1}
+ assert result.latency["n"] == 3 # skipped excluded
+ assert result.latency["p50_seconds"] == 2.0
+
+
+def test_cost_latency_suite_returns_none_total_when_any_pass_has_unknown_cost():
+ """Surfacing the missing-cost gap is more useful than a wrong total.
+ Downstream billing dashboards read this — silent zero would
+ underreport actual spend."""
+ passes = [
+ _pass(elapsed=1.0, cost=0.01),
+ _pass(elapsed=1.0, cost=None),
+ ]
+ from .cost_latency_suite import run_cost_latency_suite
+
+ result = run_cost_latency_suite(passes)
+ assert result.cost["total_usd"] is None
+
+
+def test_cost_latency_suite_handles_empty_pass_list_without_raising():
+ """Eval scaffolding may run before any real passes exist."""
+ from .cost_latency_suite import run_cost_latency_suite
+
+ result = run_cost_latency_suite([])
+ assert result.n == 0
+ assert result.cost["total_usd"] is None or result.cost["total_usd"] == 0
+ assert result.latency["n"] == 0
+
+
+# ---------------------------------------------------------------------------
+# top-level runner
+# ---------------------------------------------------------------------------
+
+
+def test_runner_emits_full_report_with_both_suites_by_default():
+ """Default config should produce both staleness + cost_latency suites
+ in the report — the schema downstream readers expect."""
+ result = run_dream_eval(
+ run_id="test-run-1",
+ passes=[_pass(elapsed=0.5)],
+ now=_now(),
+ )
+ assert result.run_id == "test-run-1"
+ assert "staleness" in result.suites
+ assert "cost_latency" in result.suites
+ # Round-trip via JSON to confirm the report is serializable
+ parsed = json.loads(result.to_json())
+ assert parsed["suites"]["staleness"]["n"] == len(ALL_STALENESS_FIXTURES)
+ assert parsed["suites"]["cost_latency"]["n"] == 1
+
+
+def test_runner_skips_disabled_suites():
+ """Config flag must actually skip the suite — needed for fast CI runs
+ that only check the cheap stats."""
+ result = run_dream_eval(
+ run_id="r",
+ config=DreamEvalConfig(run_staleness=False, run_cost_latency=True),
+ now=_now(),
+ )
+ assert "staleness" not in result.suites
+ assert "cost_latency" in result.suites
+
+
+def test_runner_report_is_serializable_to_pretty_json():
+ """results.json is consumed by humans + scripts — both need pretty
+ indented JSON that round-trips through json.loads cleanly."""
+ result = run_dream_eval(run_id="r", now=_now())
+ rendered = result.to_json(indent=2)
+ parsed = json.loads(rendered)
+ assert parsed["run_id"] == "r"
+ assert "python_version" in parsed
+ assert "ts" in parsed
+
+
+# ---------------------------------------------------------------------------
+# end-to-end fixture coverage gate
+# ---------------------------------------------------------------------------
+
+
+def test_full_fixture_meets_quality_floor_for_p0_ship():
+ """Gate: P0 cannot ship if the staleness heuristics regress below
+ the quality floor on the full fixture. Stability is the high-cost
+ side — preserve stable facts."""
+ result = run_staleness_suite(ALL_STALENESS_FIXTURES, now=_now())
+ assert result.stability >= 0.85, (
+ f"Stability dropped to {result.stability}; would delete real memory. "
+ f"Failures:\n" + "\n".join(result.failures)
+ )
+ assert result.recall >= 0.67, (
+ f"Recall dropped to {result.recall}; heuristics missing too many "
+ f"stale facts.\nFailures:\n" + "\n".join(result.failures)
+ )
+
+
[email protected]("fixture", ALL_STALENESS_FIXTURES)
+def test_each_fixture_row_classifies_to_its_expected_label(fixture):
+ """Per-row visibility: if one fixture flips, the failing test name
+ tells you exactly which fact regressed."""
+ from backend.copilot.dream.staleness import STALENESS_THRESHOLD, score_staleness
+
+ from .staleness_suite import _fixture_to_fact
+
+ fact = _fixture_to_fact(fixture, _now())
+ score = score_staleness(fact, now=_now())
+ flagged = score >= STALENESS_THRESHOLD
+ assert flagged == fixture.expected_stale, (
+ f"Misclassified: {fixture.fact_text!r} got score={score:.2f}, "
+ f"expected_stale={fixture.expected_stale}"
+ )
diff --git a/autogpt_platform/backend/backend/copilot/eval/staleness_suite.py b/autogpt_platform/backend/backend/copilot/eval/staleness_suite.py
new file mode 100644
index 0000000000..23565c0c8f
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/eval/staleness_suite.py
@@ -0,0 +1,106 @@
+"""Staleness benchmark — measures precision/recall of P0.3a heuristics.
+
+Runs ``score_staleness`` over a labeled fixture, reports:
+ * precision = correctly-flagged stale / total flagged
+ * recall = correctly-flagged stale / total actually stale
+ * stability = preserved stable / total actually stable
+ (= 1 - false positive rate; the high-cost side — false positives
+ here are the "delete real user memory" failure mode)
+
+Stability is the most important number; the harness fails the suite
+when stability dips below 0.85 (8/10 stable facts preserved). False
+negatives (missed stale facts) cost an extra dream cycle to catch;
+false positives delete real memory.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Sequence
+
+from pydantic.dataclasses import dataclass
+
+from backend.copilot.dream.fetch import FactRow
+from backend.copilot.dream.staleness import STALENESS_THRESHOLD, score_staleness
+
+from .datasets import StalenessFixture
+
+
+@dataclass(frozen=True)
+class StalenessSuiteResult:
+ n: int
+ precision: float
+ recall: float
+ stability: float
+ threshold: float
+ failures: list[str]
+ """Human-readable description of each misclassification — surfaces
+ in the JSON ``results.json`` ``suites.staleness.failures`` field so
+ a regression in the heuristics is debuggable from the report alone
+ (no replay needed)."""
+
+
+def _fixture_to_fact(fixture: StalenessFixture, now: datetime) -> FactRow:
+ created = now - timedelta(days=fixture.created_days_ago)
+ return FactRow(
+ uuid=f"fixture-{hash(fixture.fact_text) & 0xFFFFFFFF:08x}",
+ source=None,
+ target=None,
+ name=None,
+ fact=fixture.fact_text,
+ scope="real:global",
+ confidence=0.8,
+ status="active",
+ created_at=created.isoformat().replace("+00:00", "Z"),
+ )
+
+
+def run_staleness_suite(
+ fixtures: Sequence[StalenessFixture], *, now: datetime | None = None
+) -> StalenessSuiteResult:
+ now = now or datetime.now(timezone.utc)
+
+ true_positive = 0 # flagged AND actually stale
+ false_positive = 0 # flagged BUT actually stable
+ true_negative = 0 # not flagged AND actually stable
+ false_negative = 0 # not flagged BUT actually stale
+ failures: list[str] = []
+
+ for fixture in fixtures:
+ fact = _fixture_to_fact(fixture, now)
+ score = score_staleness(fact, now=now)
+ flagged = score >= STALENESS_THRESHOLD
+
+ if flagged and fixture.expected_stale:
+ true_positive += 1
+ elif flagged and not fixture.expected_stale:
+ false_positive += 1
+ failures.append(
+ f"FP score={score:.2f}: {fixture.fact_text!r} "
+ f"(stable fact incorrectly flagged)"
+ )
+ elif not flagged and not fixture.expected_stale:
+ true_negative += 1
+ else:
+ false_negative += 1
+ failures.append(
+ f"FN score={score:.2f}: {fixture.fact_text!r} "
+ f"(stale fact not flagged)"
+ )
+
+ total_flagged = true_positive + false_positive
+ total_stale = true_positive + false_negative
+ total_stable = true_negative + false_positive
+
+ precision = true_positive / total_flagged if total_flagged else 1.0
+ recall = true_positive / total_stale if total_stale else 1.0
+ stability = true_negative / total_stable if total_stable else 1.0
+
+ return StalenessSuiteResult(
+ n=len(fixtures),
+ precision=round(precision, 3),
+ recall=round(recall, 3),
+ stability=round(stability, 3),
+ threshold=STALENESS_THRESHOLD,
+ failures=failures,
+ )
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/backfill_edge_props_integration_test.py b/autogpt_platform/backend/backend/copilot/graphiti/backfill_edge_props_integration_test.py
new file mode 100644
index 0000000000..daa3ab2111
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/graphiti/backfill_edge_props_integration_test.py
@@ -0,0 +1,166 @@
+"""Integration test for the P-1.2 backfill migration.
+
+The migration script
+(``backend/copilot/graphiti/migrations/backfill_edge_props.py``) sets
+default ``status='active'`` on every existing ``:RELATES_TO`` edge that
+lacks the property. This file pins that contract against live FalkorDB:
+
+- Pre-migration edges without ``status`` are updated to ``status='active'``.
+- The migration is idempotent — re-running is a no-op.
+- Edges that already have ``status`` set are not overwritten (e.g. an
+ already-superseded edge stays superseded).
+"""
+
+import pytest
+
+from .migrations.backfill_edge_props import BACKFILL_QUERY, backfill_one_user
+
+
+async def test_backfill_adds_active_status_to_legacy_edges(
+ clean_graph,
+) -> None:
+ """Edges created before P-1.1 have no ``status`` property; backfill
+ sets them to 'active'. Run the query directly against the driver
+ (the higher-level ``backfill_one_user`` walks user_id → group_id,
+ which we sidestep here since the fixture mints its own group_id).
+ """
+ driver, group_id = clean_graph
+
+ await driver.execute_query(
+ """
+ CREATE
+ (a:Entity {uuid: 'a', name: 'Alice', group_id: $gid}),
+ (b:Entity {uuid: 'b', name: 'Atlas', group_id: $gid}),
+ (a)-[:RELATES_TO {uuid: 'legacy-1', group_id: $gid, fact: 'pre-P-1'}]->(b),
+ (a)-[:RELATES_TO {uuid: 'legacy-2', group_id: $gid, fact: 'pre-P-1 too'}]->(b)
+ """,
+ gid=group_id,
+ )
+
+ # Sanity: no edge has status yet.
+ records, _, _ = await driver.execute_query(
+ """
+ MATCH ()-[e:RELATES_TO]->()
+ WHERE e.status IS NULL
+ RETURN count(e) AS n
+ """
+ )
+ assert records[0]["n"] == 2
+
+ records, _, _ = await driver.execute_query(BACKFILL_QUERY)
+ assert records[0]["updated"] == 2
+
+ # Every edge now has status='active'.
+ records, _, _ = await driver.execute_query(
+ """
+ MATCH ()-[e:RELATES_TO]->()
+ RETURN e.status AS status
+ """
+ )
+ assert {r["status"] for r in records} == {"active"}
+
+
+async def test_backfill_is_idempotent(clean_graph) -> None:
+ """Re-running the migration is a no-op."""
+ driver, group_id = clean_graph
+
+ await driver.execute_query(
+ """
+ CREATE
+ (a:Entity {uuid: 'a', group_id: $gid}),
+ (b:Entity {uuid: 'b', group_id: $gid}),
+ (a)-[:RELATES_TO {uuid: 'e1', group_id: $gid, fact: 'fact'}]->(b)
+ """,
+ gid=group_id,
+ )
+
+ records, _, _ = await driver.execute_query(BACKFILL_QUERY)
+ assert records[0]["updated"] == 1
+
+ records, _, _ = await driver.execute_query(BACKFILL_QUERY)
+ assert records[0]["updated"] == 0, "second run must update zero edges"
+
+
+async def test_backfill_does_not_overwrite_existing_status(
+ clean_graph,
+) -> None:
+ """If an edge already has ``status`` set to something other than
+ 'active' (e.g. an edge that was demoted before the backfill ran),
+ the migration must NOT clobber it.
+ """
+ driver, group_id = clean_graph
+
+ await driver.execute_query(
+ """
+ CREATE
+ (a:Entity {uuid: 'a', group_id: $gid}),
+ (b:Entity {uuid: 'b', group_id: $gid}),
+ (a)-[:RELATES_TO {
+ uuid: 'already-superseded',
+ group_id: $gid,
+ fact: 'old fact',
+ status: 'superseded',
+ expiration_reason: 'previous_pass'
+ }]->(b),
+ (a)-[:RELATES_TO {
+ uuid: 'legacy-active',
+ group_id: $gid,
+ fact: 'new fact'
+ }]->(b)
+ """,
+ gid=group_id,
+ )
+
+ records, _, _ = await driver.execute_query(BACKFILL_QUERY)
+ assert records[0]["updated"] == 1, "only the unstatussed edge should be touched"
+
+ # Verify the superseded edge kept its status.
+ records, _, _ = await driver.execute_query(
+ """
+ MATCH ()-[e:RELATES_TO {uuid: 'already-superseded'}]->()
+ RETURN e.status AS status, e.expiration_reason AS reason
+ """
+ )
+ assert records[0]["status"] == "superseded"
+ assert records[0]["reason"] == "previous_pass"
+
+ # And the legacy edge got 'active'.
+ records, _, _ = await driver.execute_query(
+ """
+ MATCH ()-[e:RELATES_TO {uuid: 'legacy-active'}]->()
+ RETURN e.status AS status
+ """
+ )
+ assert records[0]["status"] == "active"
+
+
+async def test_backfill_one_user_skips_missing_graph(
+ falkordb_available, monkeypatch
+) -> None:
+ """``backfill_one_user`` should not raise on a user_id whose
+ FalkorDB database has never been written to (no graph exists yet).
+
+ Returns 0 quietly. The migration is safe to point at every User row
+ in Postgres, including users who have never used memory features.
+
+ Depends on ``falkordb_available`` so the suite is skipped cleanly
+ when no FalkorDB is reachable (matches the other tests in this
+ file, which inherit the skip via ``clean_graph``). Without this,
+ CI runs without docker-compose'd FalkorDB hit a
+ ``ConnectionError: localhost:6380``.
+ """
+ # Construct a user_id whose derived group_id is valid but corresponds
+ # to a database that doesn't exist. derive_group_id will accept any
+ # [a-zA-Z0-9_-] string.
+ nonexistent_user = "no-such-user-in-falkordb"
+
+ updated = await backfill_one_user(nonexistent_user)
+ assert updated == 0
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/client.py b/autogpt_platform/backend/backend/copilot/graphiti/client.py
index 65fcdb3abb..3e9c1f3208 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/client.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/client.py
@@ -121,6 +121,66 @@ def _get_cache() -> TTLCache:
return _get_loop_state().cache
+def _build_llm_config():
+ """Shared ``LLMConfig`` for graphiti's LLM + cross-encoder paths."""
+ from graphiti_core.llm_client import LLMConfig
+
+ return LLMConfig(
+ api_key=graphiti_config.resolve_llm_api_key(),
+ model=graphiti_config.llm_model,
+ small_model=graphiti_config.llm_model, # avoid gpt-4.1-nano dedup hallucination (#760)
+ base_url=graphiti_config.resolve_llm_base_url(),
+ )
+
+
+def _build_graphiti(group_id: str, llm_client):
+ """Construct a ``Graphiti`` instance bound to a per-group FalkorDB.
+
+ Pure factory: no caching. Callers decide whether to memoize.
+ ``llm_client`` lets the caller pick the LLM-tier behavior (sync vs
+ flex) without disturbing the embedder + cross-encoder defaults.
+ """
+ from graphiti_core import Graphiti
+ from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient
+ from graphiti_core.embedder import OpenAIEmbedder, OpenAIEmbedderConfig
+ from graphiti_core.llm_client import LLMConfig
+
+ from .falkordb_driver import AutoGPTFalkorDriver
+
+ embedder_config = OpenAIEmbedderConfig(
+ api_key=graphiti_config.resolve_embedder_api_key(),
+ embedding_model=graphiti_config.embedder_model,
+ base_url=graphiti_config.resolve_embedder_base_url(),
+ )
+ embedder = OpenAIEmbedder(config=embedder_config)
+
+ # P-1.4: cross-encoder reranker for warm-context retrieval.
+ # OpenAIRerankerClient runs concurrent boolean-classifier prompts
+ # (one per candidate edge) and uses log-probabilities to rank.
+ # Cheap because the reranker model defaults to gpt-4.1-nano —
+ # the cost is one batch of small calls per session-start search.
+ reranker_config = LLMConfig(
+ api_key=graphiti_config.resolve_llm_api_key(),
+ model=graphiti_config.reranker_model,
+ base_url=graphiti_config.resolve_llm_base_url(),
+ )
+ cross_encoder = OpenAIRerankerClient(config=reranker_config)
+
+ graph_driver = AutoGPTFalkorDriver(
+ host=graphiti_config.falkordb_host,
+ port=graphiti_config.falkordb_port,
+ password=graphiti_config.falkordb_password or None,
+ database=group_id,
+ )
+ return Graphiti(
+ llm_client=llm_client,
+ embedder=embedder,
+ cross_encoder=cross_encoder,
+ graph_driver=graph_driver,
+ max_coroutines=graphiti_config.semaphore_limit,
+ )
+
+
async def get_graphiti_client(group_id: str):
"""Return a Graphiti client scoped to the given group_id.
@@ -131,11 +191,7 @@ async def get_graphiti_client(group_id: str):
Returns a ``graphiti_core.Graphiti`` instance.
"""
- from graphiti_core import Graphiti
- from graphiti_core.embedder import OpenAIEmbedder, OpenAIEmbedderConfig
- from graphiti_core.llm_client import LLMConfig, OpenAIClient
-
- from .falkordb_driver import AutoGPTFalkorDriver
+ from graphiti_core.llm_client import OpenAIClient
state = _get_loop_state()
cache = state.cache
@@ -144,36 +200,62 @@ async def get_graphiti_client(group_id: str):
if group_id in cache:
return cache[group_id]
- llm_config = LLMConfig(
- api_key=graphiti_config.resolve_llm_api_key(),
- model=graphiti_config.llm_model,
- small_model=graphiti_config.llm_model, # avoid gpt-4.1-nano dedup hallucination (#760)
- base_url=graphiti_config.resolve_llm_base_url(),
- )
- llm_client = OpenAIClient(config=llm_config)
+ llm_client = OpenAIClient(config=_build_llm_config())
+ client = _build_graphiti(group_id, llm_client)
+ cache[group_id] = client
+ return client
- embedder_config = OpenAIEmbedderConfig(
- api_key=graphiti_config.resolve_embedder_api_key(),
- embedding_model=graphiti_config.embedder_model,
- base_url=graphiti_config.resolve_embedder_base_url(),
- )
- embedder = OpenAIEmbedder(config=embedder_config)
- graph_driver = AutoGPTFalkorDriver(
- host=graphiti_config.falkordb_host,
- port=graphiti_config.falkordb_port,
- password=graphiti_config.falkordb_password or None,
- database=group_id,
- )
- client = Graphiti(
- llm_client=llm_client,
- embedder=embedder,
- graph_driver=graph_driver,
- max_coroutines=graphiti_config.semaphore_limit,
+async def make_flex_graphiti_client(group_id: str):
+ """Return a fresh Graphiti client whose LLM calls run on the flex tier.
+
+ NOT cached: nightly community rebuild is the only caller today and
+ runs once a week per user. The returned client owns its own
+ FalkorDB driver — the caller is responsible for closing it via
+ ``close_graphiti_client(...)`` when the rebuild finishes, otherwise
+ the connection lingers until the process exits.
+
+ Transport veto: the OpenAI ``service_tier="flex"`` parameter only
+ delivers the ~50% discount through OpenRouter's pass-through to
+ OpenAI / Google upstreams. Other transports (Anthropic direct,
+ Claude Code subscription, local Ollama / vLLM) either ignore the
+ extra_body kwarg silently or — in the local case — would dispatch
+ via the OpenAI Responses API endpoint (`responses.parse`) which
+ the backend doesn't speak, returning a 404 mid-rebuild. When the
+ active ``TransportProfile.supports_flex_tier`` is ``False`` we
+ swap in the regular cached ``OpenAIClient`` so the rebuild still
+ runs — at full sync price, but it runs.
+ """
+ from backend.copilot.sdk.env import config as chat_cfg
+
+ from .flex_client import FlexOpenAIClient
+
+ if not chat_cfg.transport.supports_flex_tier:
+ from graphiti_core.llm_client import OpenAIClient
+
+ logger.info(
+ "Graphiti community rebuild: flex tier not available on "
+ "transport=%s; falling back to sync OpenAIClient.",
+ chat_cfg.transport.name,
)
+ llm_client = OpenAIClient(config=_build_llm_config())
+ else:
+ llm_client = FlexOpenAIClient(config=_build_llm_config())
+ return _build_graphiti(group_id, llm_client)
- cache[group_id] = client
- return client
+
+async def close_graphiti_client(client) -> None:
+ """Close a Graphiti client's graph driver (best-effort).
+
+ Safe to call on cached or uncached clients. Use after
+ ``make_flex_graphiti_client`` to release the FalkorDB connection.
+ """
+ driver = getattr(client, "graph_driver", None) or getattr(client, "driver", None)
+ if driver and hasattr(driver, "close"):
+ try:
+ await driver.close()
+ except Exception:
+ logger.debug("Failed to close graphiti driver", exc_info=True)
async def evict_client(group_id: str) -> None:
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/client_test.py b/autogpt_platform/backend/backend/copilot/graphiti/client_test.py
index cd7ec17600..cc51039112 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/client_test.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/client_test.py
@@ -1,8 +1,13 @@
"""Tests for Graphiti client management — derive_group_id and evict_client."""
+from unittest.mock import MagicMock
+
import pytest
-from .client import derive_group_id, evict_client
+from backend.copilot.config import ChatConfig
+
+from . import client as client_mod
+from .client import derive_group_id, evict_client, make_flex_graphiti_client
class TestDeriveGroupId:
@@ -36,3 +41,169 @@ class TestEvictClient:
@pytest.mark.asyncio
async def test_evict_nonexistent_group_id_does_not_raise(self) -> None:
await evict_client("no-such-group-id")
+
+
+class TestHyphenInGroupIdRegression:
+ """Regression coverage for upstream Graphiti issue #1483.
+
+ `AutoGPTFalkorDriver.build_fulltext_query` interpolates the group_id
+ into a Redisearch tag filter as ``(@group_id:user_abc-def)``. In
+ Redisearch query syntax ``-`` means NOT — so the literal hyphen
+ inside a UUID-derived group_id is interpreted as a negation, which
+ causes silent search misses on every user whose UUID contains
+ hyphens (i.e. every user).
+
+ Upstream tracking: https://github.com/getzep/graphiti/issues/1483
+
+ The xfail test below documents what we *want* the contract to be.
+ Once upstream resolves the bug — or we mitigate locally by
+ converting hyphens to underscores in ``derive_group_id`` — flip
+ the marker off and the regression suite catches a re-introduction.
+ """
+
+ def test_derive_group_id_preserves_hyphens(self) -> None:
+ """Sanity check: hyphenated UUIDs round-trip through derivation."""
+ uid = "a1b2c3d4-e5f6-7890-1234-567890abcdef"
+ result = derive_group_id(uid)
+ assert result == f"user_{uid}"
+ assert "-" in result
+
+ @pytest.mark.xfail(
+ reason=(
+ "Graphiti #1483: AutoGPTFalkorDriver.build_fulltext_query produces a "
+ "Redisearch tag filter that interprets hyphens in the group_id as NOT. "
+ "Mitigation deferred — either upstream fix or sanitize in derive_group_id."
+ ),
+ strict=False,
+ )
+ def test_build_fulltext_query_escapes_hyphens_in_group_id(self) -> None:
+ from .falkordb_driver import AutoGPTFalkorDriver
+
+ # Instantiate without connecting — we only need build_fulltext_query.
+ driver = AutoGPTFalkorDriver.__new__(AutoGPTFalkorDriver)
+ result = driver.build_fulltext_query(
+ query="alice",
+ group_ids=["user_a1b2c3d4-e5f6-7890-1234-567890abcdef"],
+ )
+
+ # The contract we want: hyphens are escaped (Redisearch backtick
+ # form) or otherwise rendered safe for tag-filter matching.
+ # Today's output is the raw interpolation, which Redisearch treats
+ # as a NOT — hence xfail.
+ # Acceptable forms include backtick-escaped values
+ # (@group_id:`user_…-…`)
+ # or substituting hyphens with underscores in the filter.
+ unsafe_pattern = "user_a1b2c3d4-e5f6-7890" # raw hyphenated form
+ assert unsafe_pattern not in result, (
+ "Hyphenated group_id is interpolated raw into the Redisearch tag "
+ "filter — Redisearch treats `-` as NOT, causing silent search misses."
+ )
+
+
+def _patch_chat_cfg(monkeypatch: pytest.MonkeyPatch, cfg: ChatConfig) -> None:
+ """Swap the ``copilot.sdk.env.config`` singleton for a per-test
+ transport. Mirrors the pattern used by ``transport_routing_test``
+ and ``graphiti.config_test``."""
+ from backend.copilot.sdk import env
+
+ monkeypatch.setattr(env, "config", cfg)
+
+
+class TestMakeFlexGraphitiClient:
+ """The flex client is the seam where transport identity actually
+ matters at runtime — the OpenAI ``service_tier="flex"`` parameter
+ delivers a ~50% discount via OpenRouter's pass-through but blows
+ up against Ollama (no Responses API). Pin the transport gate so a
+ local install doesn't 404 on its weekly community rebuild."""
+
+ @pytest.mark.asyncio
+ async def test_returns_regular_openaiclient_when_flex_unsupported(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """``CHAT_USE_LOCAL=true`` → ``transport.supports_flex_tier``
+ is False → fall back to the cached non-flex client so the
+ rebuild runs at sync price instead of 404-ing."""
+ _patch_chat_cfg(
+ monkeypatch,
+ ChatConfig(
+ use_local=True,
+ api_key="ollama-placeholder",
+ base_url="http://localhost:11434/v1",
+ ),
+ )
+ captured: dict = {}
+
+ def _fake_build_graphiti(group_id: str, llm_client):
+ captured["llm_client"] = llm_client
+ captured["group_id"] = group_id
+ return MagicMock(name="fake-graphiti")
+
+ # Both clients have heavy constructor side effects (network
+ # connection, validator runs); patch them to lightweight
+ # sentinels so we can inspect which one was instantiated.
+ flex_sentinel = MagicMock(name="FlexOpenAIClient")
+ regular_sentinel = MagicMock(name="OpenAIClient")
+ monkeypatch.setattr(client_mod, "_build_graphiti", _fake_build_graphiti)
+ monkeypatch.setattr(
+ client_mod, "_build_llm_config", lambda: MagicMock(name="LLMConfig")
+ )
+
+ # ``make_flex_graphiti_client`` imports both classes lazily;
+ # patch them on their actual modules so the import inside the
+ # function picks up the sentinel.
+ import graphiti_core.llm_client
+
+ from . import flex_client as flex_module
+
+ monkeypatch.setattr(flex_module, "FlexOpenAIClient", flex_sentinel)
+ monkeypatch.setattr(graphiti_core.llm_client, "OpenAIClient", regular_sentinel)
+
+ await make_flex_graphiti_client("user_abc")
+
+ # The regular (non-flex) client was constructed.
+ assert regular_sentinel.called, "expected fallback to regular OpenAIClient"
+ assert (
+ not flex_sentinel.called
+ ), "flex client must not be constructed under local transport"
+ # And the constructed instance was passed into _build_graphiti.
+ assert captured["llm_client"] is regular_sentinel.return_value
+
+ @pytest.mark.asyncio
+ async def test_returns_flex_client_when_transport_supports_flex(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """OpenRouter transport keeps the flex tier — the gate only
+ kicks in for non-flex-capable transports."""
+ _patch_chat_cfg(
+ monkeypatch,
+ ChatConfig(
+ use_openrouter=True,
+ api_key="or-key",
+ base_url="https://openrouter.ai/api/v1",
+ ),
+ )
+ captured: dict = {}
+
+ def _fake_build_graphiti(group_id: str, llm_client):
+ captured["llm_client"] = llm_client
+ return MagicMock(name="fake-graphiti")
+
+ flex_sentinel = MagicMock(name="FlexOpenAIClient")
+ regular_sentinel = MagicMock(name="OpenAIClient")
+ monkeypatch.setattr(client_mod, "_build_graphiti", _fake_build_graphiti)
+ monkeypatch.setattr(
+ client_mod, "_build_llm_config", lambda: MagicMock(name="LLMConfig")
+ )
+
+ import graphiti_core.llm_client
+
+ from . import flex_client as flex_module
+
+ monkeypatch.setattr(flex_module, "FlexOpenAIClient", flex_sentinel)
+ monkeypatch.setattr(graphiti_core.llm_client, "OpenAIClient", regular_sentinel)
+
+ await make_flex_graphiti_client("user_abc")
+
+ assert flex_sentinel.called, "expected FlexOpenAIClient under openrouter"
+ assert not regular_sentinel.called
+ assert captured["llm_client"] is flex_sentinel.return_value
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/communities.py b/autogpt_platform/backend/backend/copilot/graphiti/communities.py
new file mode 100644
index 0000000000..332279ce97
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/graphiti/communities.py
@@ -0,0 +1,438 @@
+"""Graphiti community detection + scheduled rebuilds.
+
+Per the audit (``dream/dreaming-graphiti.md`` §8 item 1), community
+detection is "not free": Leiden / label-propagation over a non-trivial
+graph is ``O(|V| · log|V|)`` plus an LLM summarization call per
+community. The audit's default recommendation was to leave communities
+off in P0 and revisit only if retrieval relevance plateaued.
+
+The user direction for P-1 overrides that default: enable communities
+now, behind a LaunchDarkly flag, run rebuilds during off-peak windows
+to bound cost. The scheduler hook in ``backend/executor/scheduler.py``
+calls into this module.
+
+Operational notes:
+
+- ``Graphiti.build_communities()`` upstream calls ``remove_communities()``
+ first — destroy-and-rebuild — but the multi-episode research found
+ that older Graphiti versions did not. We add a defensive explicit
+ ``MATCH (c:Community {group_id: $group_id}) DETACH DELETE c`` before
+ the rebuild so the behavior is identical across versions.
+
+- The rebuild is per-user. We do **not** support cross-user community
+ detection (cross-user memory is deferred to org-scoped memory; see
+ ``dream/TODO.md`` deferred section).
+
+- Failures are non-fatal. A community rebuild that crashes leaves
+ the graph in a usable state (we either have the previous communities
+ or none); the next scheduled run will retry. Caller is expected to
+ log failures but not halt other scheduled work.
+"""
+
+import logging
+from collections import defaultdict
+from datetime import datetime, timezone
+from typing import Any
+from uuid import uuid4
+
+from backend.data.redis_client import get_redis_async
+
+from .client import (
+ close_graphiti_client,
+ derive_group_id,
+ get_graphiti_client,
+ make_flex_graphiti_client,
+)
+from .config import graphiti_config
+
+logger = logging.getLogger(__name__)
+
+
+# Upstream graphiti-core's ``label_propagation`` has an unbounded
+# ``while True:`` with no convergence guarantee. Synchronous label
+# propagation is known to oscillate on bipartite-ish subgraphs: two
+# nodes can flip labels in lock-step every iteration, forever.
+#
+# Reproduced in dev on a 107-entity / 104-edge graph: ``min_max`` in a
+# tight loop, 100% CPU for 12+ minutes with no progress, sample-trace
+# evidence. See ``dream/dreaming-graphiti.md`` §8 (anti-patterns) and
+# the inline comment in upstream
+# ``graphiti_core/utils/maintenance/community_operations.py`` for the
+# original algorithm.
+#
+# We cap the loop at this many iterations. Real-world label-propagation
+# converges in << 20 iterations; 50 is a generous ceiling. If we hit
+# the cap, we log a warning and return the partial labeling — still a
+# valid clustering (every node has *some* community assignment), just
+# not optimal. Upstream issue to file: add max_iterations parameter.
+MAX_LABEL_PROP_ITERATIONS = 50
+
+
+def _bounded_label_propagation(projection):
+ """Drop-in replacement for graphiti-core's ``label_propagation`` that
+ caps iterations to avoid the synchronous-LP oscillation infinite loop.
+
+ Same algorithm and same tie-breaking semantics as upstream — only
+ the loop is bounded. On convergence the result is identical to the
+ unbounded version.
+ """
+ community_map = {uuid: i for i, uuid in enumerate(projection.keys())}
+ converged = False
+
+ for _ in range(MAX_LABEL_PROP_ITERATIONS):
+ no_change = True
+ new_community_map: dict[str, int] = {}
+
+ for uuid, neighbors in projection.items():
+ curr_community = community_map[uuid]
+
+ community_candidates: dict[int, int] = defaultdict(int)
+ for neighbor in neighbors:
+ community_candidates[
+ community_map[neighbor.node_uuid]
+ ] += neighbor.edge_count
+ community_lst = [
+ (count, community) for community, count in community_candidates.items()
+ ]
+
+ community_lst.sort(reverse=True)
+ candidate_rank, community_candidate = (
+ community_lst[0] if community_lst else (0, -1)
+ )
+ if community_candidate != -1 and candidate_rank > 1:
+ new_community = community_candidate
+ else:
+ new_community = max(community_candidate, curr_community)
+
+ new_community_map[uuid] = new_community
+
+ if new_community != curr_community:
+ no_change = False
+
+ if no_change:
+ converged = True
+ break
+
+ community_map = new_community_map
+
+ if not converged:
+ logger.warning(
+ "label_propagation hit %d-iteration cap without converging on "
+ "projection with %d nodes — returning partial clustering. "
+ "This usually means the graph has a bipartite-ish subgraph "
+ "that causes synchronous LP to oscillate.",
+ MAX_LABEL_PROP_ITERATIONS,
+ len(projection),
+ )
+
+ community_cluster_map: dict[int, list[str]] = defaultdict(list)
+ for uuid, community in community_map.items():
+ community_cluster_map[community].append(uuid)
+ return [cluster for cluster in community_cluster_map.values()]
+
+
+# Monkey-patch upstream at import time. ``get_community_clusters`` in
+# the same module references ``label_propagation`` via module-level
+# name lookup, so swapping the attribute works.
+def _patch_upstream_label_propagation() -> None:
+ try:
+ from graphiti_core.utils.maintenance import community_operations as _ops
+ except ImportError:
+ logger.debug("graphiti_core not importable; skipping label_propagation patch")
+ return
+ if getattr(_ops.label_propagation, "_autogpt_bounded", False):
+ return # idempotent
+ _bounded_label_propagation._autogpt_bounded = True # type: ignore[attr-defined]
+ _ops.label_propagation = _bounded_label_propagation
+ logger.info(
+ "Patched graphiti_core.label_propagation with bounded variant "
+ "(max %d iterations).",
+ MAX_LABEL_PROP_ITERATIONS,
+ )
+
+
+_patch_upstream_label_propagation()
+
+
+async def _activity_since_last_rebuild(
+ driver,
+ group_id: str,
+ min_new_episodes: int,
+) -> tuple[bool, str, dict[str, Any]]:
+ """Decide whether the user's graph has changed enough to justify a rebuild.
+
+ Returns ``(should_rebuild, reason, stats)``. The graph itself is the
+ source of truth — we compare the newest ``:Episodic.created_at`` to
+ the newest ``:Community.created_at`` and additionally require at least
+ ``min_new_episodes`` net-new episodes since the last build.
+
+ No external state to maintain (no Redis key, no Postgres column).
+ Two indexed Cypher queries; sub-millisecond on FalkorDB.
+ """
+ ep_q = """
+ MATCH (n:Episodic {group_id: $g})
+ RETURN max(n.created_at) AS latest, count(n) AS total
+ """
+ co_q = """
+ MATCH (n:Community {group_id: $g})
+ RETURN max(n.created_at) AS latest, count(n) AS total
+ """
+ ep_rows, _, _ = await driver.execute_query(ep_q, g=group_id)
+ co_rows, _, _ = await driver.execute_query(co_q, g=group_id)
+
+ latest_ep = ep_rows[0]["latest"] if ep_rows else None
+ total_ep = ep_rows[0]["total"] if ep_rows else 0
+ latest_co = co_rows[0]["latest"] if co_rows else None
+ total_co = co_rows[0]["total"] if co_rows else 0
+
+ stats: dict[str, Any] = {
+ "episodes_total": total_ep,
+ "communities_total": total_co,
+ "latest_episode_at": str(latest_ep) if latest_ep is not None else None,
+ "latest_community_at": str(latest_co) if latest_co is not None else None,
+ "min_new_episodes_threshold": min_new_episodes,
+ }
+
+ if total_ep == 0:
+ return False, "no_episodes", stats
+
+ if total_co == 0:
+ # First-ever rebuild — go.
+ stats["new_episodes_since_last_rebuild"] = total_ep
+ return True, "first_rebuild", stats
+
+ if latest_ep is None or latest_co is None or latest_ep <= latest_co:
+ stats["new_episodes_since_last_rebuild"] = 0
+ return False, "no_new_episodes_since_last_rebuild", stats
+
+ # Count exactly how many episodes are newer than the latest community
+ # to enforce the activity threshold.
+ count_q = """
+ MATCH (n:Episodic {group_id: $g})
+ WHERE n.created_at > $since
+ RETURN count(n) AS c
+ """
+ rows, _, _ = await driver.execute_query(count_q, g=group_id, since=latest_co)
+ new_count = rows[0]["c"] if rows else 0
+ stats["new_episodes_since_last_rebuild"] = new_count
+
+ if new_count < min_new_episodes:
+ return False, "below_activity_threshold", stats
+
+ return True, "activity_above_threshold", stats
+
+
+# Per-user community-rebuild lock. The rebuild does a destructive
+# ``DETACH DELETE`` + Leiden clustering + per-community LLM summarization;
+# two racing on the same user's graph corrupt each other. Every rebuild
+# caller (weekly cron, admin-immediate, sync debug) funnels through
+# ``rebuild_communities_for_user``, so the guard lives here rather than in
+# any single caller.
+#
+# Cluster-safe by construction: production Redis is an ``AsyncRedisCluster``,
+# so we use only single-key primitives — ``SET key token NX EX`` to acquire
+# and a single-key Lua compare-and-delete to release, both of which route to
+# the slot owner. The random token makes release safe: we delete the key
+# only if we still own it, so a rebuild that overran its TTL can never drop a
+# lock another worker has since taken.
+#
+# The TTL exceeds the scheduler's hard rebuild bound
+# (``SCHEDULER_DREAM_OPERATION_TIMEOUT_SECONDS`` = 1800s; every caller wraps
+# the rebuild in ``run_async(..., timeout=...)``), so the lock cannot expire
+# mid-rebuild and no lease-renewal watchdog is needed — the TTL is purely a
+# crash backstop.
+_REBUILD_LOCK_KEY_PREFIX = "graphiti:community_rebuild_lock:"
+_REBUILD_LOCK_TTL_SECONDS = 1800 + 120
+
+_REBUILD_UNLOCK_SCRIPT = (
+ "if redis.call('get', KEYS[1]) == ARGV[1] then "
+ "return redis.call('del', KEYS[1]) else return 0 end"
+)
+
+
+def _rebuild_lock_key(group_id: str) -> str:
+ return f"{_REBUILD_LOCK_KEY_PREFIX}{group_id}"
+
+
+async def _release_rebuild_lock(redis, key: str, token: str) -> None:
+ """Compare-and-delete: drop the lock only if we still hold this token.
+
+ Single-key Lua so it routes on Redis Cluster. On any redis error the TTL
+ clears the key, so a failed release never wedges the user.
+ """
+ try:
+ await redis.eval(_REBUILD_UNLOCK_SCRIPT, 1, key, token)
+ except Exception:
+ logger.warning(
+ "Failed to release community-rebuild lock %s — TTL will clear it",
+ key,
+ )
+
+
+async def rebuild_communities_for_user(
+ user_id: str, *, force: bool = False
+) -> dict[str, Any]:
+ """Destroy and rebuild ``:Community`` nodes for one user's graph.
+
+ Gated by an activity check (``_activity_since_last_rebuild``) so we
+ only pay LLM-summarization cost when the graph has actually changed
+ by at least ``GraphitiConfig.community_rebuild_min_new_episodes``
+ since the last successful rebuild. Skipping also avoids non-
+ deterministic clustering drift (LP tie-breaks, summary text)
+ on essentially-unchanged graphs.
+
+ Set ``force=True`` to bypass the gate (admin override / debugging).
+
+ Returns a result dict with ``user_id``, ``communities_built``,
+ ``elapsed_seconds``, ``error`` (if any), ``skipped`` (bool), and
+ ``activity`` (the gate's stats). Always returns a dict even on
+ failure so the scheduler can record the outcome.
+ """
+ started_at = datetime.now(timezone.utc)
+ result: dict[str, Any] = {
+ "user_id": user_id,
+ "started_at": started_at.isoformat(),
+ "communities_built": None,
+ "elapsed_seconds": None,
+ "error": None,
+ "skipped": False,
+ "skip_reason": None,
+ "activity": None,
+ "forced": force,
+ "execution_path": None,
+ }
+
+ try:
+ group_id = derive_group_id(user_id)
+ except ValueError as exc:
+ result["error"] = f"invalid_user_id: {exc}"
+ logger.warning("Skipping community rebuild — invalid user_id %s", user_id[:12])
+ return result
+
+ # When the flex flag is on we build a one-shot Graphiti client whose
+ # LLM calls run on OpenAI's flex tier (~50% discount, best-effort
+ # latency). The cached interactive client stays on sync tier so
+ # live ingest dedup remains responsive. The flex client owns its
+ # own FalkorDB driver — close it in finally to avoid leaks.
+ #
+ # Transport veto: ``make_flex_graphiti_client`` silently falls
+ # back to the regular ``OpenAIClient`` when the active transport
+ # can't honour ``service_tier="flex"`` (local Ollama et al.). To
+ # keep the cost-log audit trail honest we record ``execution_path``
+ # against what *actually* dispatched, not what the operator asked
+ # for. Read the same gate the helper reads so the two stay in sync.
+ from backend.copilot.sdk.env import config as chat_cfg
+
+ flex_requested = graphiti_config.community_rebuild_use_flex_tier
+ use_flex = flex_requested and chat_cfg.transport.supports_flex_tier
+ flex_client = None
+
+ # Per-user mutual exclusion — acquired BEFORE the activity gate so a
+ # concurrent rebuild short-circuits instead of racing the DETACH DELETE
+ # below. A contended acquire rides the existing ``skipped`` contract.
+ redis = await get_redis_async()
+ lock_key = _rebuild_lock_key(group_id)
+ lock_token = uuid4().hex
+ if not await redis.set(lock_key, lock_token, nx=True, ex=_REBUILD_LOCK_TTL_SECONDS):
+ result["skipped"] = True
+ result["skip_reason"] = "rebuild already in progress"
+ logger.info(
+ "Community rebuild skipped for user %s — already in progress",
+ user_id[:12],
+ )
+ return result
+
+ try:
+ if use_flex:
+ flex_client = await make_flex_graphiti_client(group_id)
+ client = flex_client
+ result["execution_path"] = "flex"
+ else:
+ client = await get_graphiti_client(group_id)
+ result["execution_path"] = "sync"
+
+ driver = getattr(client, "graph_driver", None) or getattr(
+ client, "driver", None
+ )
+ if driver is None:
+ raise RuntimeError("Graphiti client has no graph_driver")
+
+ # Activity gate — skip when nothing has changed since the last
+ # rebuild. Cheap two-query check; the LLM cost we save is the
+ # whole point of community detection being a scheduled job
+ # rather than an always-run pass.
+ if not force:
+ should_rebuild, reason, stats = await _activity_since_last_rebuild(
+ driver,
+ group_id,
+ min_new_episodes=graphiti_config.community_rebuild_min_new_episodes,
+ )
+ result["activity"] = stats
+ if not should_rebuild:
+ result["skipped"] = True
+ result["skip_reason"] = reason
+ logger.info(
+ "Community rebuild skipped for user %s — %s (stats=%s)",
+ user_id[:12],
+ reason,
+ stats,
+ )
+ return result
+
+ # Defensive: clean up any orphan :Community nodes regardless of
+ # upstream version. Per multi-episode research, modern Graphiti
+ # already does this inside build_communities(), but older
+ # versions did not. Idempotent either way.
+ await driver.execute_query(
+ """
+ MATCH (c:Community {group_id: $group_id})
+ DETACH DELETE c
+ """,
+ group_id=group_id,
+ )
+
+ # Rebuild via Graphiti. The result shape changes between graphiti
+ # versions; we record whatever it returns rather than asserting
+ # a specific shape.
+ summary = await client.build_communities(group_ids=[group_id])
+ result["communities_built"] = _summarize_communities(summary)
+
+ except Exception as exc:
+ result["error"] = f"{type(exc).__name__}: {exc}"
+ logger.warning(
+ "Community rebuild failed for user %s", user_id[:12], exc_info=True
+ )
+
+ finally:
+ if flex_client is not None:
+ await close_graphiti_client(flex_client)
+ ended_at = datetime.now(timezone.utc)
+ result["elapsed_seconds"] = (ended_at - started_at).total_seconds()
+ await _release_rebuild_lock(redis, lock_key, lock_token)
+
+ return result
+
+
+def _summarize_communities(summary: Any) -> Any:
+ """Reduce graphiti-core's build_communities return value to something
+ JSON-loggable.
+
+ Upstream signature is ``tuple[list[CommunityNode], list[CommunityEdge]]``
+ in the version we pin (0.28.2). Older versions returned a bare list of
+ CommunityNode; some return dicts. Cover all three so telemetry stays
+ readable across version bumps.
+ """
+ if summary is None:
+ return None
+ if isinstance(summary, tuple) and len(summary) == 2:
+ nodes, edges = summary
+ return {
+ "nodes": len(nodes) if hasattr(nodes, "__len__") else None,
+ "edges": len(edges) if hasattr(edges, "__len__") else None,
+ }
+ if isinstance(summary, list):
+ return {"count": len(summary)}
+ if isinstance(summary, dict):
+ return summary
+ # Fallback for unknown shapes — best-effort string coercion.
+ return {"raw": str(summary)[:200]}
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/communities_integration_test.py b/autogpt_platform/backend/backend/copilot/graphiti/communities_integration_test.py
new file mode 100644
index 0000000000..0a28346b17
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/graphiti/communities_integration_test.py
@@ -0,0 +1,198 @@
+"""Integration tests for community rebuild (P-1.7) against live FalkorDB.
+
+What this file covers without an LLM key:
+
+- The defensive ``MATCH (c:Community) DETACH DELETE c`` runs *before*
+ graphiti-core's own ``build_communities`` call. Seeded orphan
+ ``:Community`` nodes from a prior version's rebuild are cleaned up.
+- The function returns a structured result dict on every code path
+ (success, expected-failure-without-LLM, invalid user). The scheduler
+ relies on this contract to record outcomes without throwing.
+- The function is per-user-isolated by ``group_id`` — invalidating
+ user A's communities does not affect user B's.
+
+What this file does NOT cover (needs an LLM key — separate
+``requires_llm``-marked tests to add later):
+
+- The actual happy-path "communities are built and summarized after a
+ rebuild" assertion. We can't drive ``client.build_communities``
+ without LLM access; the summarization step is an LLM call per
+ community. Without it, the call typically returns an error dict
+ (which we *do* assert on cleanly below).
+"""
+
+from datetime import datetime, timezone
+from unittest.mock import patch
+
+import pytest
+
+from .communities import rebuild_communities_for_user
+
+
+def _make_user_id(group_id: str) -> str:
+ """Recover the user_id that would derive into ``group_id``.
+
+ ``derive_group_id`` prefixes ``user_``, so strip that to feed the
+ fixture-minted group_id back through the function.
+ """
+ assert group_id.startswith("user_") or group_id.startswith("test_"), group_id
+ return group_id.removeprefix("user_") if group_id.startswith("user_") else group_id
+
+
+async def test_rebuild_returns_structured_result_on_failure(
+ clean_graph,
+) -> None:
+ """Even when the LLM step fails (no key, no network), the function
+ returns an error dict — never raises. The scheduler relies on this
+ so one bad rebuild doesn't starve other scheduled jobs.
+ """
+ driver, group_id = clean_graph
+
+ # Seed a couple entities so the label-propagation step has something
+ # to chew on before the LLM summarization step (which will fail
+ # without a key in CI). FalkorDB doesn't implement Cypher's no-arg
+ # ``datetime()``; generate the timestamp in Python and bind as a
+ # parameter (mirrors the seeded_graph fixture + dream/fetch.py).
+ await driver.execute_query(
+ """
+ CREATE
+ (a:Entity {uuid: 'a', name: 'Alice', group_id: $gid, created_at: $now}),
+ (b:Entity {uuid: 'b', name: 'Bob', group_id: $gid, created_at: $now}),
+ (a)-[:RELATES_TO {uuid: 'e1', group_id: $gid, fact: 'a knows b'}]->(b)
+ """,
+ gid=group_id,
+ now=datetime.now(timezone.utc).isoformat(),
+ )
+
+ user_id = _make_user_id(group_id)
+ # derive_group_id will fail validation if we don't have the user_ prefix,
+ # so we have to point the rebuild at the actual fixture group_id by
+ # patching derive_group_id for this call only.
+ with patch(
+ "backend.copilot.graphiti.communities.derive_group_id",
+ return_value=group_id,
+ ):
+ result = await rebuild_communities_for_user(user_id)
+
+ # Contract: always returns dict with the expected keys.
+ assert set(result.keys()) >= {
+ "user_id",
+ "started_at",
+ "communities_built",
+ "elapsed_seconds",
+ "error",
+ }
+ assert result["user_id"] == user_id
+ assert result["elapsed_seconds"] is not None
+ assert result["elapsed_seconds"] >= 0
+ # Either the LLM step ran (success) or it failed; either way, we
+ # don't raise out of the function.
+
+
+async def test_detach_delete_clears_orphan_community_nodes(
+ clean_graph,
+) -> None:
+ """The defensive ``DETACH DELETE c`` runs against live FalkorDB.
+
+ Seed two orphan ``:Community`` nodes (as if an older graphiti
+ version left them behind), invoke the rebuild, and verify the
+ orphans are gone — regardless of whether the rebuild itself
+ succeeds in summarization.
+ """
+ driver, group_id = clean_graph
+
+ await driver.execute_query(
+ """
+ CREATE
+ (:Community {uuid: 'orphan-1', name: 'old-1', group_id: $gid, summary: 'stale'}),
+ (:Community {uuid: 'orphan-2', name: 'old-2', group_id: $gid, summary: 'stale'})
+ """,
+ gid=group_id,
+ )
+
+ # Sanity: orphans are there to begin with.
+ records, _, _ = await driver.execute_query(
+ "MATCH (c:Community {group_id: $gid}) RETURN c.uuid AS uuid",
+ gid=group_id,
+ )
+ assert {r["uuid"] for r in records} == {"orphan-1", "orphan-2"}
+
+ user_id = _make_user_id(group_id)
+ # ``force=True`` bypasses ``_activity_since_last_rebuild``. Without
+ # the override the rebuild short-circuits on ``no_episodes`` BEFORE
+ # the ``DETACH DELETE c`` step runs (see communities.py:298-326),
+ # and the orphans this test seeds would stay in place — which would
+ # mask the regression the test is supposed to catch.
+ with patch(
+ "backend.copilot.graphiti.communities.derive_group_id",
+ return_value=group_id,
+ ):
+ await rebuild_communities_for_user(user_id, force=True)
+
+ # Orphans must be gone, whether or not the rebuild itself succeeded.
+ records, _, _ = await driver.execute_query(
+ "MATCH (c:Community {group_id: $gid, uuid: 'orphan-1'}) RETURN c.uuid AS uuid",
+ gid=group_id,
+ )
+ assert records == [], "orphan-1 must be DETACH DELETE'd before rebuild starts"
+
+ records, _, _ = await driver.execute_query(
+ "MATCH (c:Community {group_id: $gid, uuid: 'orphan-2'}) RETURN c.uuid AS uuid",
+ gid=group_id,
+ )
+ assert records == [], "orphan-2 must be DETACH DELETE'd before rebuild starts"
+
+
+async def test_rebuild_invalid_user_id_returns_error_dict(clean_graph) -> None:
+ """``derive_group_id`` raises on empty user_id; the function must
+ catch and surface the error in the result dict, not let it propagate.
+ """
+ result = await rebuild_communities_for_user("")
+ assert result["error"] is not None
+ assert "invalid_user_id" in result["error"]
+ assert result["communities_built"] is None
+
+
+async def test_rebuild_does_not_touch_other_users_communities(
+ clean_graph,
+) -> None:
+ """Per-user isolation by ``group_id`` survives the DETACH DELETE.
+
+ Seed orphan ``:Community`` nodes in two different group_ids,
+ invalidate one, verify the other is untouched.
+ """
+ driver, group_id = clean_graph
+ other_group = group_id + "_other"
+
+ await driver.execute_query(
+ """
+ CREATE
+ (:Community {uuid: 'self-1', group_id: $g1, summary: 'self'}),
+ (:Community {uuid: 'other-1', group_id: $g2, summary: 'other'})
+ """,
+ g1=group_id,
+ g2=other_group,
+ )
+
+ user_id = _make_user_id(group_id)
+ with patch(
+ "backend.copilot.graphiti.communities.derive_group_id",
+ return_value=group_id,
+ ):
+ await rebuild_communities_for_user(user_id)
+
+ # other-1 must still be there.
+ records, _, _ = await driver.execute_query(
+ "MATCH (c:Community {uuid: 'other-1'}) RETURN c.group_id AS gid",
+ )
+ assert records == [
+ {"gid": other_group}
+ ], "Other user's :Community node was deleted — group_id scoping regressed"
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/communities_test.py b/autogpt_platform/backend/backend/copilot/graphiti/communities_test.py
new file mode 100644
index 0000000000..d4d439551b
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/graphiti/communities_test.py
@@ -0,0 +1,563 @@
+"""Tests for the per-user community rebuild helper."""
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from .communities import (
+ MAX_LABEL_PROP_ITERATIONS,
+ _activity_since_last_rebuild,
+ _bounded_label_propagation,
+ _patch_upstream_label_propagation,
+ _summarize_communities,
+ rebuild_communities_for_user,
+)
+
+
[email protected](autouse=True)
+def _free_rebuild_lock():
+ """``rebuild_communities_for_user`` acquires a per-user Redis lock before
+ doing any work. Give every test a redis whose lock is free (SET NX → ok,
+ release → ok); the contention test overrides ``set``."""
+ redis = AsyncMock()
+ redis.set = AsyncMock(return_value=True)
+ redis.eval = AsyncMock(return_value=1)
+ with patch(
+ "backend.copilot.graphiti.communities.get_redis_async",
+ new=AsyncMock(return_value=redis),
+ ):
+ yield redis
+
+
+def _neighbor(uuid: str, edge_count: int = 1):
+ """Mimic graphiti's Neighbor namedtuple — only attributes touched by LP."""
+ return SimpleNamespace(node_uuid=uuid, edge_count=edge_count)
+
+
+class TestBoundedLabelPropagation:
+ """Regression coverage for the synchronous-LP infinite-loop fix.
+
+ Upstream graphiti_core.label_propagation has an unbounded ``while True:``
+ that can oscillate forever on bipartite-ish subgraphs (synchronous LP
+ flips labels in lock-step). Our bounded variant caps iterations and
+ returns the current state if the cap is hit. These tests pin the
+ contract.
+ """
+
+ def test_empty_projection_returns_empty(self) -> None:
+ assert _bounded_label_propagation({}) == []
+
+ def test_single_node_no_neighbors(self) -> None:
+ # One node, no neighbors → one cluster of size 1
+ result = _bounded_label_propagation({"a": []})
+ assert result == [["a"]]
+
+ def test_connected_pair_converges(self) -> None:
+ # Two nodes pointing at each other — should converge fast
+ projection = {
+ "a": [_neighbor("b")],
+ "b": [_neighbor("a")],
+ }
+ result = _bounded_label_propagation(projection)
+ # Expect single cluster — both nodes ended up in the same community
+ assert len(result) == 1
+ assert sorted(result[0]) == ["a", "b"]
+
+ def test_two_disjoint_pairs_form_two_clusters(self) -> None:
+ # No edges between {a,b} and {c,d} — should form 2 clusters
+ projection = {
+ "a": [_neighbor("b")],
+ "b": [_neighbor("a")],
+ "c": [_neighbor("d")],
+ "d": [_neighbor("c")],
+ }
+ clusters = sorted([sorted(c) for c in _bounded_label_propagation(projection)])
+ assert clusters == [["a", "b"], ["c", "d"]]
+
+ def test_oscillating_projection_returns_at_cap_with_warning(
+ self, caplog: pytest.LogCaptureFixture
+ ) -> None:
+ """Construct a fixture that genuinely oscillates under synchronous
+ LP, and assert we exit at the cap with a warning rather than
+ spinning forever.
+
+ Two-node swap with edge_count >= 2: each iteration each node's
+ plurality neighbor-community wins (count > 1 → bypasses the
+ tie-break), so they swap labels every step. After step 1
+ a=label(b_orig), b=label(a_orig). After step 2 they swap back.
+ Forever — without the bound.
+ """
+ import logging
+
+ projection = {
+ "a": [_neighbor("b", edge_count=2)],
+ "b": [_neighbor("a", edge_count=2)],
+ }
+
+ caplog.set_level(logging.WARNING, logger="backend.copilot.graphiti.communities")
+ result = _bounded_label_propagation(projection)
+
+ # Must return — not hang — and must produce a valid clustering
+ # (every node assigned somewhere, no node lost).
+ assigned = sorted(node for cluster in result for node in cluster)
+ assert assigned == ["a", "b"]
+
+ # The warning text must mention the cap. Check caplog.text (the
+ # full captured log) because record collection can vary with
+ # pytest-logging configuration; the formatted text is reliable.
+ assert (
+ f"{MAX_LABEL_PROP_ITERATIONS}-iteration cap" in caplog.text
+ ), f"expected cap-warning in caplog.text; got: {caplog.text!r}"
+
+
+class TestUpstreamMonkeyPatch:
+ """The monkey-patch hooks into graphiti_core's module-level
+ ``label_propagation`` symbol so ``get_community_clusters`` picks it
+ up automatically. Pin the contract so a future refactor can't break
+ it silently.
+ """
+
+ def test_upstream_reference_replaced(self) -> None:
+ from graphiti_core.utils.maintenance import community_operations
+
+ # After importing our communities module, upstream's symbol
+ # must point at our bounded variant.
+ assert community_operations.label_propagation is _bounded_label_propagation
+
+ def test_patch_is_idempotent(self) -> None:
+ from graphiti_core.utils.maintenance import community_operations
+
+ # Idempotency sentinel on the function itself
+ assert (
+ getattr(community_operations.label_propagation, "_autogpt_bounded", False)
+ is True
+ )
+
+ # Calling the patch again must be a no-op (must not raise, must
+ # not replace with a fresh function lacking the sentinel)
+ _patch_upstream_label_propagation()
+ _patch_upstream_label_propagation()
+ assert community_operations.label_propagation is _bounded_label_propagation
+
+
+class TestSummarizeCommunities:
+ def test_none_passthrough(self) -> None:
+ assert _summarize_communities(None) is None
+
+ def test_list_returns_count(self) -> None:
+ assert _summarize_communities([1, 2, 3]) == {"count": 3}
+
+ def test_dict_passthrough(self) -> None:
+ assert _summarize_communities({"a": 1}) == {"a": 1}
+
+ def test_unknown_shape_coerces_to_str(self) -> None:
+ result = _summarize_communities(object())
+ assert isinstance(result, dict)
+ assert "raw" in result
+
+
+class TestRebuildCommunitiesForUser:
+ @pytest.mark.asyncio
+ async def test_invalid_user_id_returns_error_dict(self) -> None:
+ result = await rebuild_communities_for_user("")
+ assert result["error"] is not None
+ assert result["communities_built"] is None
+
+ @pytest.mark.asyncio
+ async def test_success_path_calls_detach_delete_then_build(self) -> None:
+ # Mock the Graphiti client + its driver
+ driver = AsyncMock()
+ driver.execute_query.return_value = ([], None, None)
+
+ client = MagicMock()
+ client.graph_driver = driver
+ client.build_communities = AsyncMock(return_value=[{"name": "c1"}])
+
+ # Bypass the activity gate (covered separately in
+ # TestActivitySinceLastRebuild) so this test stays focused on the
+ # DETACH DELETE → build_communities → summarize flow.
+ with (
+ patch(
+ "backend.copilot.graphiti.communities.make_flex_graphiti_client",
+ new=AsyncMock(return_value=client),
+ ),
+ patch(
+ "backend.copilot.graphiti.communities.close_graphiti_client",
+ new=AsyncMock(),
+ ),
+ patch(
+ "backend.copilot.graphiti.communities._activity_since_last_rebuild",
+ new=AsyncMock(return_value=(True, "first_rebuild", {})),
+ ),
+ ):
+ result = await rebuild_communities_for_user(
+ "883cc9da-fe37-4863-839b-acba022bf3ef"
+ )
+
+ assert result["error"] is None
+ assert result["communities_built"] == {"count": 1}
+ assert result["elapsed_seconds"] is not None
+
+ # Defensive DETACH DELETE must run before build_communities
+ cleanup_query = driver.execute_query.call_args.args[0]
+ assert "MATCH (c:Community" in cleanup_query
+ assert "DETACH DELETE c" in cleanup_query
+ client.build_communities.assert_awaited_once()
+
+ @pytest.mark.asyncio
+ async def test_failure_path_returns_error_in_result(self) -> None:
+ driver = AsyncMock()
+ driver.execute_query.return_value = ([], None, None)
+
+ client = MagicMock()
+ client.graph_driver = driver
+ # Stub activity gate as "rebuild needed" so we reach build_communities
+ client.build_communities = AsyncMock(side_effect=RuntimeError("boom"))
+
+ with (
+ patch(
+ "backend.copilot.graphiti.communities.make_flex_graphiti_client",
+ new=AsyncMock(return_value=client),
+ ),
+ patch(
+ "backend.copilot.graphiti.communities.close_graphiti_client",
+ new=AsyncMock(),
+ ),
+ patch(
+ "backend.copilot.graphiti.communities._activity_since_last_rebuild",
+ new=AsyncMock(return_value=(True, "first_rebuild", {})),
+ ),
+ ):
+ result = await rebuild_communities_for_user(
+ "883cc9da-fe37-4863-839b-acba022bf3ef"
+ )
+
+ assert result["error"] is not None
+ assert "RuntimeError" in result["error"]
+ # Always returns elapsed_seconds even on failure
+ assert result["elapsed_seconds"] is not None
+
+ @pytest.mark.asyncio
+ async def test_skips_when_lock_held(self, _free_rebuild_lock) -> None:
+ """A second concurrent rebuild (SET NX fails) returns skipped and
+ never touches the graph — no client, no activity gate, no DETACH."""
+ _free_rebuild_lock.set = AsyncMock(return_value=None)
+
+ with (
+ patch(
+ "backend.copilot.graphiti.communities.make_flex_graphiti_client",
+ new=AsyncMock(),
+ ) as flex,
+ patch(
+ "backend.copilot.graphiti.communities.get_graphiti_client",
+ new=AsyncMock(),
+ ) as plain,
+ patch(
+ "backend.copilot.graphiti.communities._activity_since_last_rebuild",
+ new=AsyncMock(),
+ ) as gate,
+ ):
+ result = await rebuild_communities_for_user(
+ "883cc9da-fe37-4863-839b-acba022bf3ef"
+ )
+
+ assert result["skipped"] is True
+ assert result["skip_reason"] == "rebuild already in progress"
+ # Short-circuited before any work — the held lock is the whole point.
+ gate.assert_not_awaited()
+ flex.assert_not_awaited()
+ plain.assert_not_awaited()
+ # We don't own the lock, so we must NOT release it.
+ _free_rebuild_lock.eval.assert_not_awaited()
+
+ @pytest.mark.asyncio
+ async def test_releases_lock_after_run(self, _free_rebuild_lock) -> None:
+ """A normal run releases via single-key compare-and-delete Lua
+ (cluster-routable) using the same token it acquired with."""
+ driver = AsyncMock()
+ driver.execute_query.return_value = ([], None, None)
+ client = MagicMock()
+ client.graph_driver = driver
+ client.build_communities = AsyncMock(return_value=[{"name": "c1"}])
+
+ with (
+ patch(
+ "backend.copilot.graphiti.communities.make_flex_graphiti_client",
+ new=AsyncMock(return_value=client),
+ ),
+ patch(
+ "backend.copilot.graphiti.communities.close_graphiti_client",
+ new=AsyncMock(),
+ ),
+ patch(
+ "backend.copilot.graphiti.communities._activity_since_last_rebuild",
+ new=AsyncMock(return_value=(True, "first_rebuild", {})),
+ ),
+ ):
+ result = await rebuild_communities_for_user(
+ "883cc9da-fe37-4863-839b-acba022bf3ef"
+ )
+
+ assert result["skipped"] is False
+ # Acquire: single-key SET NX EX with a token value + TTL backstop.
+ set_args, set_kwargs = _free_rebuild_lock.set.call_args
+ assert set_kwargs.get("nx") is True
+ assert set_kwargs.get("ex") == 1800 + 120
+ # Release: single-key Lua compare-and-delete (numkeys=1 → routes on
+ # the cluster) using the same token we acquired with.
+ _free_rebuild_lock.eval.assert_awaited_once()
+ eval_args = _free_rebuild_lock.eval.call_args.args
+ assert eval_args[1] == 1
+ assert eval_args[2].startswith("graphiti:community_rebuild_lock:")
+ assert eval_args[3] == set_args[1]
+
+
+def _ep_query_result(latest: str | None, total: int) -> tuple:
+ """Build an execute_query return tuple shaped like an episode/community count."""
+ rows = [{"latest": latest, "total": total}] if latest is not None or total else []
+ if not rows:
+ rows = [{"latest": None, "total": 0}]
+ return (rows, None, None)
+
+
+class TestActivitySinceLastRebuild:
+ """Gate that decides whether ``rebuild_communities_for_user`` actually
+ pays the LLM-summarization cost or short-circuits as a no-op."""
+
+ @pytest.mark.asyncio
+ async def test_skips_when_no_episodes(self) -> None:
+ driver = AsyncMock()
+ # First query: episodes — empty. Gate should return early.
+ driver.execute_query.side_effect = [
+ _ep_query_result(None, 0), # episodes
+ _ep_query_result(None, 0), # communities
+ ]
+ should, reason, stats = await _activity_since_last_rebuild(
+ driver, "user_x", min_new_episodes=5
+ )
+ assert should is False
+ assert reason == "no_episodes"
+ assert stats["episodes_total"] == 0
+
+ @pytest.mark.asyncio
+ async def test_rebuilds_on_first_run(self) -> None:
+ """Episodes exist but no communities yet — first rebuild always runs."""
+ driver = AsyncMock()
+ driver.execute_query.side_effect = [
+ _ep_query_result("2026-05-20T01:00:00Z", 10), # episodes
+ _ep_query_result(None, 0), # communities
+ ]
+ should, reason, stats = await _activity_since_last_rebuild(
+ driver, "user_x", min_new_episodes=5
+ )
+ assert should is True
+ assert reason == "first_rebuild"
+ assert stats["new_episodes_since_last_rebuild"] == 10
+
+ @pytest.mark.asyncio
+ async def test_skips_when_no_new_episodes_since_last_rebuild(self) -> None:
+ driver = AsyncMock()
+ driver.execute_query.side_effect = [
+ _ep_query_result("2026-05-20T01:00:00Z", 10), # episodes
+ _ep_query_result("2026-05-20T02:00:00Z", 3), # communities — newer
+ ]
+ should, reason, stats = await _activity_since_last_rebuild(
+ driver, "user_x", min_new_episodes=5
+ )
+ assert should is False
+ assert reason == "no_new_episodes_since_last_rebuild"
+ assert stats["new_episodes_since_last_rebuild"] == 0
+
+ @pytest.mark.asyncio
+ async def test_skips_when_new_episodes_below_threshold(self) -> None:
+ driver = AsyncMock()
+ driver.execute_query.side_effect = [
+ _ep_query_result("2026-05-20T03:00:00Z", 13), # episodes
+ _ep_query_result("2026-05-20T02:00:00Z", 3), # communities older
+ ([{"c": 3}], None, None), # count of new episodes — below threshold 5
+ ]
+ should, reason, stats = await _activity_since_last_rebuild(
+ driver, "user_x", min_new_episodes=5
+ )
+ assert should is False
+ assert reason == "below_activity_threshold"
+ assert stats["new_episodes_since_last_rebuild"] == 3
+ assert stats["min_new_episodes_threshold"] == 5
+
+ @pytest.mark.asyncio
+ async def test_rebuilds_when_above_threshold(self) -> None:
+ driver = AsyncMock()
+ driver.execute_query.side_effect = [
+ _ep_query_result("2026-05-20T03:00:00Z", 20), # episodes
+ _ep_query_result("2026-05-20T02:00:00Z", 3), # communities older
+ ([{"c": 8}], None, None), # 8 new episodes >= threshold 5
+ ]
+ should, reason, stats = await _activity_since_last_rebuild(
+ driver, "user_x", min_new_episodes=5
+ )
+ assert should is True
+ assert reason == "activity_above_threshold"
+ assert stats["new_episodes_since_last_rebuild"] == 8
+
+
+class TestRebuildForUserActivityGate:
+ """End-to-end behavior of ``rebuild_communities_for_user`` with the gate."""
+
+ @pytest.mark.asyncio
+ async def test_skip_path_records_reason_and_does_not_call_build(self) -> None:
+ driver = AsyncMock()
+ client = MagicMock()
+ client.graph_driver = driver
+ client.build_communities = AsyncMock()
+
+ with (
+ patch(
+ "backend.copilot.graphiti.communities.make_flex_graphiti_client",
+ new=AsyncMock(return_value=client),
+ ),
+ patch(
+ "backend.copilot.graphiti.communities.close_graphiti_client",
+ new=AsyncMock(),
+ ),
+ patch(
+ "backend.copilot.graphiti.communities._activity_since_last_rebuild",
+ new=AsyncMock(
+ return_value=(False, "below_activity_threshold", {"x": 1})
+ ),
+ ),
+ ):
+ result = await rebuild_communities_for_user(
+ "883cc9da-fe37-4863-839b-acba022bf3ef"
+ )
+
+ assert result["skipped"] is True
+ assert result["skip_reason"] == "below_activity_threshold"
+ assert result["activity"] == {"x": 1}
+ assert result["communities_built"] is None
+ assert result["error"] is None
+ # Critical: build_communities NOT called, no DETACH DELETE issued
+ client.build_communities.assert_not_awaited()
+ driver.execute_query.assert_not_called()
+
+ @pytest.mark.asyncio
+ async def test_force_bypasses_gate(self) -> None:
+ """``force=True`` skips activity check; always rebuilds."""
+ driver = AsyncMock()
+ driver.execute_query.return_value = ([], None, None)
+ client = MagicMock()
+ client.graph_driver = driver
+ client.build_communities = AsyncMock(return_value=[])
+
+ with (
+ patch(
+ "backend.copilot.graphiti.communities.make_flex_graphiti_client",
+ new=AsyncMock(return_value=client),
+ ),
+ patch(
+ "backend.copilot.graphiti.communities.close_graphiti_client",
+ new=AsyncMock(),
+ ),
+ patch(
+ "backend.copilot.graphiti.communities._activity_since_last_rebuild",
+ new=AsyncMock(),
+ ) as mock_gate,
+ ):
+ result = await rebuild_communities_for_user(
+ "883cc9da-fe37-4863-839b-acba022bf3ef", force=True
+ )
+
+ assert result["forced"] is True
+ assert result["skipped"] is False
+ # The activity gate must not be consulted when force=True
+ mock_gate.assert_not_called()
+ # build_communities WAS called
+ client.build_communities.assert_awaited_once()
+
+
+class TestRebuildPathSelection:
+ """Which Graphiti client (flex vs sync) the rebuild actually uses."""
+
+ @pytest.mark.asyncio
+ async def test_uses_flex_client_by_default(self) -> None:
+ driver = AsyncMock()
+ driver.execute_query.return_value = ([], None, None)
+ client = MagicMock()
+ client.graph_driver = driver
+ client.build_communities = AsyncMock(return_value=[])
+
+ flex_factory = AsyncMock(return_value=client)
+ close_mock = AsyncMock()
+ sync_factory = AsyncMock(return_value=client)
+
+ with (
+ patch(
+ "backend.copilot.graphiti.communities.make_flex_graphiti_client",
+ new=flex_factory,
+ ),
+ patch(
+ "backend.copilot.graphiti.communities.close_graphiti_client",
+ new=close_mock,
+ ),
+ patch(
+ "backend.copilot.graphiti.communities.get_graphiti_client",
+ new=sync_factory,
+ ),
+ patch(
+ "backend.copilot.graphiti.communities._activity_since_last_rebuild",
+ new=AsyncMock(return_value=(True, "first_rebuild", {})),
+ ),
+ ):
+ result = await rebuild_communities_for_user(
+ "883cc9da-fe37-4863-839b-acba022bf3ef"
+ )
+
+ assert result["execution_path"] == "flex"
+ flex_factory.assert_awaited_once()
+ sync_factory.assert_not_called()
+ # finally block must release the one-shot driver
+ close_mock.assert_awaited_once()
+
+ @pytest.mark.asyncio
+ async def test_uses_sync_client_when_flex_disabled(self) -> None:
+ driver = AsyncMock()
+ driver.execute_query.return_value = ([], None, None)
+ client = MagicMock()
+ client.graph_driver = driver
+ client.build_communities = AsyncMock(return_value=[])
+
+ flex_factory = AsyncMock(return_value=client)
+ close_mock = AsyncMock()
+ sync_factory = AsyncMock(return_value=client)
+
+ with (
+ patch(
+ "backend.copilot.graphiti.communities.graphiti_config.community_rebuild_use_flex_tier",
+ new=False,
+ ),
+ patch(
+ "backend.copilot.graphiti.communities.make_flex_graphiti_client",
+ new=flex_factory,
+ ),
+ patch(
+ "backend.copilot.graphiti.communities.close_graphiti_client",
+ new=close_mock,
+ ),
+ patch(
+ "backend.copilot.graphiti.communities.get_graphiti_client",
+ new=sync_factory,
+ ),
+ patch(
+ "backend.copilot.graphiti.communities._activity_since_last_rebuild",
+ new=AsyncMock(return_value=(True, "first_rebuild", {})),
+ ),
+ ):
+ result = await rebuild_communities_for_user(
+ "883cc9da-fe37-4863-839b-acba022bf3ef"
+ )
+
+ assert result["execution_path"] == "sync"
+ sync_factory.assert_awaited_once()
+ flex_factory.assert_not_called()
+ # No flex client → no close call
+ close_mock.assert_not_awaited()
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/config.py b/autogpt_platform/backend/backend/copilot/graphiti/config.py
index 08b533b6fc..c9aeb0bf25 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/config.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/config.py
@@ -3,7 +3,7 @@
import os
from pathlib import Path
-from pydantic import Field
+from pydantic import Field, model_validator
from pydantic_settings import (
BaseSettings,
DotEnvSettingsSource,
@@ -16,6 +16,31 @@ from backend.util.clients import OPENROUTER_BASE_URL
_BACKEND_ROOT = Path(__file__).resolve().parents[3]
+# Cloud defaults that ``_apply_local_graphiti_models`` rewrites under
+# local transport. Pinned as module constants so the field defaults and
+# the validator can't drift — same pattern as
+# ``copilot/config.py::_DEFAULT_TITLE_MODEL`` etc.
+_DEFAULT_LLM_MODEL = "gpt-4.1-mini"
+_DEFAULT_RERANKER_MODEL = "gpt-4.1-nano"
+_DEFAULT_EMBEDDER_MODEL = "text-embedding-3-small"
+
+# Local-transport defaults. Mirrors dev's chat-side ``--with-ollama``
+# default (``hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M``, per
+# ``docs/platform/copilot-local-llm.md`` — 4B params, ~3.4GB resident,
+# 256k native context, vetted for OpenAI-shim structured output). The
+# reranker reuses the same model since the prompts are simpler than
+# extraction and pulling a second model for it would double the local
+# install's disk + RAM footprint.
+_LOCAL_LLM_MODEL = "hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M"
+_LOCAL_RERANKER_MODEL = _LOCAL_LLM_MODEL
+# Embedder defaults to Ollama's ``nomic-embed-text`` (~270MB, 768-dim
+# vectors, well-supported by the OpenAI ``/v1/embeddings`` shim).
+# Operators on ``--with-ollama-embeddings`` get this pulled
+# automatically; everyone else needs to ``ollama pull nomic-embed-text``
+# before graphiti ingest starts working — covered in copilot-local-llm.md.
+_LOCAL_EMBEDDER_MODEL = "nomic-embed-text"
+
+
class GraphitiConfig(BaseSettings):
"""Configuration for Graphiti memory integration.
@@ -33,9 +58,13 @@ class GraphitiConfig(BaseSettings):
falkordb_port: int = Field(default=6380)
falkordb_password: str = Field(default="")
- # LLM for entity extraction (used by graphiti-core during ingestion)
+ # LLM for entity extraction (used by graphiti-core during ingestion).
+ # Default is a cloud OpenAI-compat slug. Under ``CHAT_USE_LOCAL=true``
+ # ``_apply_local_graphiti_models`` rewrites this to the same Ollama
+ # default that dev's PR #12993 uses for the chat path so a single
+ # ``ollama pull`` powers both surfaces.
llm_model: str = Field(
- default="gpt-4.1-mini",
+ default=_DEFAULT_LLM_MODEL,
description="Model for entity extraction — must support structured output",
)
llm_base_url: str = Field(
@@ -47,8 +76,9 @@ class GraphitiConfig(BaseSettings):
description="API key for LLM — empty falls back to CHAT_API_KEY, then OPEN_ROUTER_API_KEY",
)
- # Embedder (separate from LLM — embeddings go direct to OpenAI)
- embedder_model: str = Field(default="text-embedding-3-small")
+ # Embedder (separate from LLM — embeddings go direct to OpenAI).
+ # Under local transport rewritten to ``nomic-embed-text`` (Ollama).
+ embedder_model: str = Field(default=_DEFAULT_EMBEDDER_MODEL)
embedder_base_url: str = Field(
default="",
description="Base URL for embedder — empty uses OpenAI direct",
@@ -58,6 +88,42 @@ class GraphitiConfig(BaseSettings):
description="API key for embedder — empty falls back to CHAT_OPENAI_API_KEY, then OPENAI_API_KEY",
)
+ # Cross-encoder reranker (P-1.4) — used by warm-context retrieval to
+ # rerank top edges from BM25 + cosine + BFS. Graphiti's built-in
+ # OpenAIRerankerClient runs concurrent boolean-classifier prompts
+ # against gpt-4.1-nano by default (one prompt per candidate; log-
+ # probabilities decide the score). The audit estimated ~10–15%
+ # precision lift on warm context at the cost of one LLM call per
+ # session start. Defaults match Graphiti's own default so the
+ # reranker can ship with no env config.
+ reranker_model: str = Field(
+ default=_DEFAULT_RERANKER_MODEL,
+ description="Model for the cross-encoder reranker. Cheap, fast classifier prompts.",
+ )
+
+ # Activity-gate threshold for community rebuilds (P-1.7).
+ # ``rebuild_communities_for_user`` skips when there have been fewer
+ # than this many new episodes since the last successful rebuild —
+ # avoids paying the per-community LLM-summarization cost AND avoids
+ # clustering drift on essentially-unchanged graphs (LP tie-breaks
+ # are non-deterministic; summary text varies). Defaults to 5 — a
+ # full week of low-activity (~1 episode/day) is fine to skip; a
+ # power user blasting 20+ memories triggers rebuild within hours.
+ community_rebuild_min_new_episodes: int = Field(
+ default=5,
+ description="Skip community rebuild when fewer than this many new episodes since last rebuild.",
+ )
+
+ # Nightly community rebuild is non-interactive scheduled work — ~50%
+ # cheaper on OpenAI's ``service_tier="flex"`` (worst-case ~15min
+ # queue, typically just a few seconds slower). Interactive ingest
+ # stays on sync tier because the user expects deduped facts ready
+ # for their next turn.
+ community_rebuild_use_flex_tier: bool = Field(
+ default=True,
+ description="Run nightly community rebuilds on OpenAI's flex service tier (~50% discount).",
+ )
+
# Concurrency
semaphore_limit: int = Field(
default=5,
@@ -95,16 +161,60 @@ class GraphitiConfig(BaseSettings):
DotEnvSettingsSource(settings_cls, env_file=_BACKEND_ROOT / ".env.default"),
)
+ def _chat_local_fallback(self) -> tuple[str, str] | None:
+ """Return ``(api_key, base_url)`` when the active chat transport
+ is ``local`` — otherwise ``None``.
+
+ Holy-grail integration with dev's ``TransportProfile`` from
+ PR #12993: under ``CHAT_USE_LOCAL=true``, graphiti's entity
+ extraction + embedder need to hit the same self-hosted backend
+ that the chat layer was pointed at. The cloud-key fallback chain
+ (CHAT_API_KEY → OPEN_ROUTER_API_KEY) returns either nothing or
+ a stray cloud key the operator forgot to unset, which would
+ send a request to the wrong endpoint and 401.
+
+ Lazy-imports ``chat_cfg`` to keep the
+ ``copilot.sdk.env`` ↔ ``util/clients`` import cycle dev
+ already established under control. Returns ``None`` for any
+ non-local transport so the caller falls through to its
+ existing cloud-key chain (cloud users are unaffected).
+ """
+ # Local import: ``copilot.sdk.env`` instantiates a ``ChatConfig``
+ # at import time, and graphiti's config is sometimes imported
+ # at module-collection time (CI, tools) before env is fully
+ # primed. Lazy so the import only fires when a resolver is
+ # actually called.
+ from backend.copilot.sdk.env import config as chat_cfg
+
+ if chat_cfg.transport.name != "local":
+ return None
+ return chat_cfg.api_key or "", chat_cfg.base_url or ""
+
def resolve_llm_api_key(self) -> str:
if self.llm_api_key:
return self.llm_api_key
# Prefer the AutoPilot-dedicated key so memory costs are tracked
# separately from the platform-wide OpenRouter key.
- return os.getenv("CHAT_API_KEY") or os.getenv("OPEN_ROUTER_API_KEY", "")
+ cloud_key = os.getenv("CHAT_API_KEY") or os.getenv("OPEN_ROUTER_API_KEY")
+ if cloud_key:
+ return cloud_key
+ # Last resort: under local transport, inherit the placeholder
+ # key the operator set for the chat path so the Ollama backend
+ # accepts the bearer (any non-empty value).
+ local_fallback = self._chat_local_fallback()
+ if local_fallback is not None:
+ return local_fallback[0]
+ return ""
def resolve_llm_base_url(self) -> str:
if self.llm_base_url:
return self.llm_base_url
+ # Under local transport, point at the same OpenAI-compat
+ # endpoint as the chat layer (e.g. http://localhost:11434/v1).
+ # Cloud transports keep the OpenRouter default.
+ local_fallback = self._chat_local_fallback()
+ if local_fallback is not None and local_fallback[1]:
+ return local_fallback[1]
return OPENROUTER_BASE_URL
def resolve_embedder_api_key(self) -> str:
@@ -112,13 +222,77 @@ class GraphitiConfig(BaseSettings):
return self.embedder_api_key
# Prefer the AutoPilot-dedicated OpenAI key so memory costs are
# tracked separately from the platform-wide OpenAI key.
- return os.getenv("CHAT_OPENAI_API_KEY") or os.getenv("OPENAI_API_KEY", "")
+ cloud_key = os.getenv("CHAT_OPENAI_API_KEY") or os.getenv("OPENAI_API_KEY")
+ if cloud_key:
+ return cloud_key
+ # Last resort: under local transport, inherit the chat placeholder.
+ local_fallback = self._chat_local_fallback()
+ if local_fallback is not None:
+ return local_fallback[0]
+ return ""
def resolve_embedder_base_url(self) -> str | None:
if self.embedder_base_url:
return self.embedder_base_url
+ # Under local transport, embeddings go to the same self-hosted
+ # backend (the operator pulled an embedding model into Ollama
+ # per docs/platform/copilot-local-llm.md). Cloud transports use
+ # the OpenAI SDK default (``None``).
+ local_fallback = self._chat_local_fallback()
+ if local_fallback is not None and local_fallback[1]:
+ return local_fallback[1]
return None # OpenAI SDK default
+ @model_validator(mode="after")
+ def _apply_local_graphiti_models(self) -> "GraphitiConfig":
+ """Rewrite cloud model defaults to local-friendly slugs under
+ ``CHAT_USE_LOCAL=true``.
+
+ Mirror of dev's ``_apply_local_aux_models`` pattern on
+ ``ChatConfig`` (PR #12993). Three slots get rewritten when
+ still at their cloud defaults and the operator hasn't pinned
+ a ``GRAPHITI_*_MODEL`` override:
+
+ - ``llm_model`` (``gpt-4.1-mini``) → ``hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M``
+ (matches dev's chat default — one Ollama pull powers both
+ surfaces; vetted for structured output / tool-calling shape).
+ - ``reranker_model`` (``gpt-4.1-nano``) → same Qwen slug.
+ Reranker prompts are simpler than extraction; reusing the
+ chat model avoids pulling a second model just for reranking.
+ - ``embedder_model`` (``text-embedding-3-small``) →
+ ``nomic-embed-text``. Operators need to ``ollama pull
+ nomic-embed-text`` separately (chat doesn't need it, so the
+ installer's ``--with-ollama`` doesn't cover it today; see
+ docs/platform/copilot-local-llm.md).
+
+ Operator overrides (custom slugs like ``qwen3:8b`` or
+ ``hf.co/...``) pass through untouched — only the literal cloud
+ defaults trigger rewriting. Lazy-imports ``chat_cfg`` to avoid
+ the ``copilot.sdk.env`` ↔ ``util/clients`` cycle dev's PR
+ established.
+ """
+ try:
+ from backend.copilot.sdk.env import config as chat_cfg
+ except Exception:
+ # Defensive: if the chat config fails to import for any
+ # reason (corrupt env vars during test collection, etc.)
+ # keep the cloud defaults rather than crashing graphiti
+ # at import time. Operators on local transport see the
+ # cloud default and a clear 404 from Ollama; everyone
+ # else is unaffected.
+ return self
+
+ if chat_cfg.transport.name != "local":
+ return self
+
+ if self.llm_model == _DEFAULT_LLM_MODEL:
+ object.__setattr__(self, "llm_model", _LOCAL_LLM_MODEL)
+ if self.reranker_model == _DEFAULT_RERANKER_MODEL:
+ object.__setattr__(self, "reranker_model", _LOCAL_RERANKER_MODEL)
+ if self.embedder_model == _DEFAULT_EMBEDDER_MODEL:
+ object.__setattr__(self, "embedder_model", _LOCAL_EMBEDDER_MODEL)
+ return self
+
_graphiti_config: GraphitiConfig | None = None
@@ -157,3 +331,24 @@ async def is_enabled_for_user(user_id: str | None) -> bool:
user_id,
default=False,
)
+
+
+async def is_communities_enabled_for_user(user_id: str | None) -> bool:
+ """Check if per-user community-detection rebuilds are enabled.
+
+ Distinct from ``is_enabled_for_user`` — a user can have Graphiti
+ memory enabled (writes + reads work) without the weekly Leiden
+ rebuild + LLM summarization running on their graph. Gated by
+ ``Flag.GRAPHITI_COMMUNITIES_ENABLED``; defaults False so the cost
+ only lands behind explicit opt-in.
+ """
+ if not user_id:
+ return False
+
+ from backend.util.feature_flag import Flag, is_feature_enabled
+
+ return await is_feature_enabled(
+ Flag.GRAPHITI_COMMUNITIES_ENABLED,
+ user_id,
+ default=False,
+ )
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/config_test.py b/autogpt_platform/backend/backend/copilot/graphiti/config_test.py
index efe36c8586..8c99f549a3 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/config_test.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/config_test.py
@@ -2,6 +2,8 @@ from unittest.mock import AsyncMock, patch
import pytest
+from backend.copilot.config import ChatConfig
+
from .config import GraphitiConfig, is_enabled_for_user
_ENV_VARS_TO_CLEAR = (
@@ -12,6 +14,10 @@ _ENV_VARS_TO_CLEAR = (
"CHAT_OPENAI_API_KEY",
"OPEN_ROUTER_API_KEY",
"OPENAI_API_KEY",
+ "CHAT_USE_LOCAL",
+ "CHAT_USE_OPENROUTER",
+ "CHAT_USE_CLAUDE_CODE_SUBSCRIPTION",
+ "CHAT_BASE_URL",
)
@@ -21,6 +27,25 @@ def _clean_env(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.delenv(var, raising=False)
+def _patch_chat_cfg(monkeypatch: pytest.MonkeyPatch, cfg: ChatConfig) -> None:
+ """Replace the ``copilot.sdk.env.config`` singleton for one test.
+
+ GraphitiConfig resolvers lazy-import ``chat_cfg`` inside
+ ``_chat_local_fallback``; patching the module attribute is the
+ cleanest way to pin a specific transport per test.
+ """
+ from backend.copilot.sdk import env
+
+ monkeypatch.setattr(env, "config", cfg)
+
+
+def _local_chat_cfg(
+ api_key: str = "ollama-placeholder",
+ base_url: str = "http://localhost:11434/v1",
+) -> ChatConfig:
+ return ChatConfig(use_local=True, api_key=api_key, base_url=base_url)
+
+
def test_graphiti_config_reads_backend_env_defaults() -> None:
cfg = GraphitiConfig()
@@ -52,6 +77,28 @@ class TestResolveLlmApiKey:
cfg = GraphitiConfig(llm_api_key="")
assert cfg.resolve_llm_api_key() == ""
+ def test_inherits_chat_api_key_under_local_transport(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """Under ``CHAT_USE_LOCAL=true`` with no graphiti override and
+ no cloud key, the resolver falls through to the chat-config
+ placeholder so the Ollama backend gets a non-empty bearer."""
+ _patch_chat_cfg(monkeypatch, _local_chat_cfg(api_key="ollama-x"))
+ cfg = GraphitiConfig(llm_api_key="")
+ assert cfg.resolve_llm_api_key() == "ollama-x"
+
+ def test_cloud_key_still_wins_over_local_fallback(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """``CHAT_API_KEY`` (the AutoPilot-dedicated cloud key)
+ beats the local fallback — covers the mixed-mode case where
+ an operator switched the chat layer to local but left a
+ cloud key around."""
+ monkeypatch.setenv("CHAT_API_KEY", "autopilot-cloud-key")
+ _patch_chat_cfg(monkeypatch, _local_chat_cfg(api_key="ollama-x"))
+ cfg = GraphitiConfig(llm_api_key="")
+ assert cfg.resolve_llm_api_key() == "autopilot-cloud-key"
+
class TestResolveLlmBaseUrl:
def test_returns_configured_url_when_set(self) -> None:
@@ -63,6 +110,20 @@ class TestResolveLlmBaseUrl:
result = cfg.resolve_llm_base_url()
assert result == "https://openrouter.ai/api/v1"
+ def test_inherits_chat_base_url_under_local_transport(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """Under local transport, graphiti's entity extraction must
+ hit the same Ollama (or vLLM, …) endpoint as the chat layer
+ — not the OpenRouter default. Otherwise the per-turn graphiti
+ ingest 401s against a placeholder key."""
+ _patch_chat_cfg(
+ monkeypatch,
+ _local_chat_cfg(base_url="http://ollama.lan:11434/v1"),
+ )
+ cfg = GraphitiConfig(llm_base_url="")
+ assert cfg.resolve_llm_base_url() == "http://ollama.lan:11434/v1"
+
class TestResolveEmbedderApiKey:
def test_returns_configured_key_when_set(self) -> None:
@@ -88,6 +149,13 @@ class TestResolveEmbedderApiKey:
cfg = GraphitiConfig(embedder_api_key="")
assert cfg.resolve_embedder_api_key() == ""
+ def test_inherits_chat_api_key_under_local_transport(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ _patch_chat_cfg(monkeypatch, _local_chat_cfg(api_key="ollama-y"))
+ cfg = GraphitiConfig(embedder_api_key="")
+ assert cfg.resolve_embedder_api_key() == "ollama-y"
+
class TestResolveEmbedderBaseUrl:
def test_returns_configured_url_when_set(self) -> None:
@@ -98,6 +166,73 @@ class TestResolveEmbedderBaseUrl:
cfg = GraphitiConfig(embedder_base_url="")
assert cfg.resolve_embedder_base_url() is None
+ def test_inherits_chat_base_url_under_local_transport(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """Local transport directs embeddings to the same self-hosted
+ backend. Operators still need to pull an embedding-capable
+ model into Ollama (e.g. ``nomic-embed-text``) — covered in
+ docs/platform/copilot-local-llm.md."""
+ _patch_chat_cfg(
+ monkeypatch,
+ _local_chat_cfg(base_url="http://ollama.lan:11434/v1"),
+ )
+ cfg = GraphitiConfig(embedder_base_url="")
+ assert cfg.resolve_embedder_base_url() == "http://ollama.lan:11434/v1"
+
+
+class TestApplyLocalGraphitiModels:
+ """``_apply_local_graphiti_models`` rewires cloud model defaults
+ to local-friendly slugs under ``CHAT_USE_LOCAL=true`` so a fresh
+ install of AutoGPT + Ollama works end-to-end without setting a
+ ``GRAPHITI_*_MODEL`` env var per slot. Mirrors dev's
+ ``_apply_local_aux_models`` pattern on the chat side."""
+
+ def test_rewrites_cloud_defaults_under_local(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ _patch_chat_cfg(monkeypatch, _local_chat_cfg())
+ cfg = GraphitiConfig()
+ # llm_model: gpt-4.1-mini → Qwen3.5-4B Unsloth GGUF
+ assert cfg.llm_model == "hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M"
+ # reranker reuses the same model (simpler prompts, avoids a
+ # second Ollama pull).
+ assert cfg.reranker_model == "hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M"
+ # embedder: text-embedding-3-small → nomic-embed-text
+ assert cfg.embedder_model == "nomic-embed-text"
+
+ def test_operator_override_passes_through(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """Operators with custom Ollama tags (``qwen3:8b``,
+ ``hf.co/...``) keep their override — the validator only
+ rewrites *literal* cloud defaults."""
+ _patch_chat_cfg(monkeypatch, _local_chat_cfg())
+ monkeypatch.setenv("GRAPHITI_LLM_MODEL", "qwen3:8b")
+ monkeypatch.setenv("GRAPHITI_EMBEDDER_MODEL", "all-minilm")
+ cfg = GraphitiConfig()
+ assert cfg.llm_model == "qwen3:8b"
+ assert cfg.embedder_model == "all-minilm"
+
+ def test_cloud_defaults_preserved_under_cloud_transport(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """OpenRouter / direct-Anthropic transports leave the cloud
+ defaults alone — graphiti's ``gpt-4.1-mini`` stays put for
+ anyone who isn't on a self-hosted backend."""
+ _patch_chat_cfg(
+ monkeypatch,
+ ChatConfig(
+ use_openrouter=True,
+ api_key="or-key",
+ base_url="https://openrouter.ai/api/v1",
+ ),
+ )
+ cfg = GraphitiConfig()
+ assert cfg.llm_model == "gpt-4.1-mini"
+ assert cfg.reranker_model == "gpt-4.1-nano"
+ assert cfg.embedder_model == "text-embedding-3-small"
+
class TestIsEnabledForUser:
@pytest.mark.asyncio
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/conftest.py b/autogpt_platform/backend/backend/copilot/graphiti/conftest.py
new file mode 100644
index 0000000000..586abcb1d1
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/graphiti/conftest.py
@@ -0,0 +1,191 @@
+"""Local conftest for copilot/graphiti tests.
+
+Two responsibilities:
+
+1. **Opt out of the full SpinTestServer.** Mirrors
+ ``backend/copilot/tools/conftest.py`` — these tests don't need
+ postgres + rabbitmq + the platform-wide ``graph_cleanup`` autouse.
+
+2. **Provide FalkorDB integration fixtures.** Tests marked
+ ``@pytest.mark.integration`` use the ``clean_graph`` and
+ ``seeded_graph`` fixtures to talk to a live FalkorDB. The
+ ``falkordb_available`` session fixture skips the integration suite
+ gracefully when FalkorDB is not reachable, so local unit-test runs
+ stay fast.
+
+Run integration tests with the platform docker-compose stack up::
+
+ cd autogpt_platform
+ docker compose up -d falkordb
+ cd backend
+ poetry run pytest -m integration backend/copilot/graphiti
+
+The fixtures connect using ``GraphitiConfig`` defaults
+(``localhost:6380`` host-side) — override with the standard
+``GRAPHITI_FALKORDB_*`` env vars to point at a different host.
+"""
+
+import socket
+import uuid
+from datetime import datetime, timezone
+from typing import AsyncIterator
+
+import pytest
+import pytest_asyncio
+
+from .config import graphiti_config
+from .falkordb_driver import AutoGPTFalkorDriver
+
+
+@pytest_asyncio.fixture(scope="session", loop_scope="session")
+async def server(): # type: ignore[override]
+ """No-op server stub — graphiti tests don't need the full backend."""
+ return None
+
+
+@pytest_asyncio.fixture(scope="session", loop_scope="session", autouse=True)
+async def graph_cleanup(): # type: ignore[override]
+ """No-op graph cleanup stub."""
+ yield
+
+
[email protected](scope="session")
+def falkordb_available() -> bool:
+ """Skip the calling integration suite if FalkorDB is unreachable.
+
+ Resolves host + port from ``GraphitiConfig`` so a developer who has
+ customized the env stays in sync. A 1-second TCP probe is enough to
+ confirm the port is open — Graphiti's own client will surface any
+ deeper protocol mismatch when the test actually runs.
+ """
+ host = graphiti_config.falkordb_host
+ port = graphiti_config.falkordb_port
+ try:
+ with socket.create_connection((host, port), timeout=1.0):
+ pass
+ except OSError as exc:
+ pytest.skip(
+ f"FalkorDB not reachable at {host}:{port} ({exc.__class__.__name__}). "
+ "Bring it up with `docker compose up -d falkordb` from autogpt_platform/, "
+ "or set GRAPHITI_FALKORDB_HOST / GRAPHITI_FALKORDB_PORT to a reachable instance."
+ )
+ return True
+
+
+def _new_test_group_id() -> str:
+ """Mint a unique group_id for the current test.
+
+ The ``test_`` prefix matches the project convention for ephemeral
+ Graphiti databases and is easy to grep / sweep. UUID is truncated
+ to 16 chars to stay well under the 128-char limit enforced by
+ ``derive_group_id``.
+ """
+ return f"test_{uuid.uuid4().hex[:16]}"
+
+
+async def _drop_database(driver: AutoGPTFalkorDriver) -> None:
+ """Best-effort full wipe of the test database via Cypher.
+
+ DETACH DELETE everything covers entities, episodes, communities, and
+ all edges between them. Falls back silently — if the wipe fails on
+ cleanup we don't want to fail the test that already passed.
+ """
+ try:
+ await driver.execute_query("MATCH (n) DETACH DELETE n")
+ except Exception:
+ pass
+
+
+@pytest_asyncio.fixture(loop_scope="function")
+async def clean_graph(
+ falkordb_available: bool,
+) -> AsyncIterator[tuple[AutoGPTFalkorDriver, str]]:
+ """A per-test FalkorDB driver scoped to a fresh group_id.
+
+ Yields ``(driver, group_id)``. After the test, every node + edge in
+ the database is detach-deleted; the database itself is left
+ in place (FalkorDB doesn't expose a "drop database" Cypher and the
+ test FalkorDB is ephemeral anyway).
+
+ Passes ``build_indices=False`` so the driver does NOT spawn the
+ background ``build_indices_and_constraints`` task graphiti-core's
+ ``FalkorDriver.__init__`` fires by default. That task runs many
+ sequential ``CREATE INDEX`` statements that race the test's own
+ queries — the integration tests hang indefinitely on the test
+ runner with ``Connection closed by server`` retries piling up.
+ Indexes are irrelevant to these tests anyway (they assert against
+ Cypher we issue directly), so opting out is harmless. See the
+ ``AutoGPTFalkorDriver`` docstring for the production rationale.
+ """
+ group_id = _new_test_group_id()
+ driver = AutoGPTFalkorDriver(
+ host=graphiti_config.falkordb_host,
+ port=graphiti_config.falkordb_port,
+ password=graphiti_config.falkordb_password or None,
+ database=group_id,
+ build_indices=False,
+ )
+ try:
+ yield driver, group_id
+ finally:
+ await _drop_database(driver)
+ await driver.close()
+
+
+@pytest_asyncio.fixture(loop_scope="function")
+async def seeded_graph(
+ clean_graph: tuple[AutoGPTFalkorDriver, str],
+) -> tuple[AutoGPTFalkorDriver, str]:
+ """A canonical small graph for tests that need preexisting state.
+
+ Three entities, two ``:RELATES_TO`` edges, all with the new edge
+ properties from ``MemoryFact`` already populated so tests that
+ exercise post-P-1 behavior can run without a separate ingestion
+ step. The shape::
+
+ (Alice {uuid:'alice'})-[:RELATES_TO {uuid:'e1', status:'active'}]->(Atlas {uuid:'atlas'})
+ (Bob {uuid:'bob'}) -[:RELATES_TO {uuid:'e2', status:'active'}]->(Atlas {uuid:'atlas'})
+ """
+ driver, group_id = clean_graph
+ # FalkorDB doesn't implement Cypher's no-arg ``datetime()`` function
+ # (it errors with ``Unknown function 'datetime'``). Generate the
+ # timestamp in Python and bind it as a parameter so the seed query
+ # runs cleanly against FalkorDB — same workaround the production
+ # ``dream/fetch.py`` and ``tools/graphiti_forget.py`` use against
+ # the same backend.
+ now_iso = datetime.now(timezone.utc).isoformat()
+ await driver.execute_query(
+ """
+ CREATE
+ (a:Entity {uuid: 'alice', name: 'Alice', group_id: $gid, created_at: $now}),
+ (b:Entity {uuid: 'bob', name: 'Bob', group_id: $gid, created_at: $now}),
+ (t:Entity {uuid: 'atlas', name: 'Atlas', group_id: $gid, created_at: $now}),
+ (a)-[:RELATES_TO {
+ uuid: 'e1',
+ group_id: $gid,
+ fact: 'Alice works on Atlas',
+ name: 'works_on',
+ status: 'active',
+ confidence: 0.9,
+ source_kind: 'user_asserted',
+ scope: 'real:global',
+ provenance: 'session:test#msg:1',
+ created_at: $now
+ }]->(t),
+ (b)-[:RELATES_TO {
+ uuid: 'e2',
+ group_id: $gid,
+ fact: 'Bob works on Atlas',
+ name: 'works_on',
+ status: 'active',
+ confidence: 0.8,
+ source_kind: 'user_asserted',
+ scope: 'real:global',
+ provenance: 'session:test#msg:2',
+ created_at: $now
+ }]->(t)
+ """,
+ gid=group_id,
+ now=now_iso,
+ )
+ return driver, group_id
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/context.py b/autogpt_platform/backend/backend/copilot/graphiti/context.py
index 29d4e95f47..7f47a9fd81 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/context.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/context.py
@@ -47,14 +47,31 @@ async def fetch_warm_context(user_id: str, message: str) -> str | None:
async def _fetch(user_id: str, message: str) -> str | None:
+ # Imported lazily so the module can be imported without graphiti-core
+ # installed (matches the pattern in client.py).
+ from graphiti_core.search.search_config_recipes import (
+ EDGE_HYBRID_SEARCH_CROSS_ENCODER,
+ )
+
group_id = derive_group_id(user_id)
client = await get_graphiti_client(group_id)
- edges, episodes = await asyncio.gather(
- client.search(
+ # P-1.4: warm context is the single most-impactful retrieval per
+ # session — the one place where the cross-encoder rerank earns its
+ # ~10–15% precision lift (per the audit) at the cost of one extra
+ # batch of boolean-classifier prompts. The EDGE_HYBRID_SEARCH_CROSS_ENCODER
+ # recipe combines BM25 + cosine + BFS edge search with cross-encoder
+ # reranking. The recipe defaults ``limit=10``; we override to our
+ # configured ``context_max_facts`` so existing operator tuning still
+ # applies.
+ search_config = EDGE_HYBRID_SEARCH_CROSS_ENCODER.model_copy(
+ update={"limit": graphiti_config.context_max_facts}
+ )
+ edge_results, episodes = await asyncio.gather(
+ client.search_(
query=message,
+ config=search_config,
group_ids=[group_id],
- num_results=graphiti_config.context_max_facts,
),
client.retrieve_episodes(
reference_time=datetime.now(timezone.utc),
@@ -62,6 +79,15 @@ async def _fetch(user_id: str, message: str) -> str | None:
last_n=5,
),
)
+ edges = edge_results.edges if edge_results is not None else []
+
+ # Ratification sync hit-hook (P0.4 layer-2): every retrieved edge
+ # that's currently ``status='tentative'`` gets promoted to
+ # ``active`` inline, and every retrieved edge bumps its
+ # warm-context hit counter. Fire-and-forget so the chat turn
+ # never blocks on Redis or FalkorDB writes.
+ if edges:
+ _spawn_ratification_hits(user_id, edges)
if not edges and not episodes:
return None
@@ -69,6 +95,26 @@ async def _fetch(user_id: str, message: str) -> str | None:
return _format_context(edges, episodes)
+def _spawn_ratification_hits(user_id: str, edges) -> None:
+ """Fire-and-forget the ratification hit-hook for retrieved edges.
+
+ Imports lazily so the dream/ratification module isn't pulled into
+ every retrieval boot path; keeps the cold-start cost zero for
+ users on the rare GRAPHITI_MEMORY=on / DREAM_PASS_ENABLED=off
+ combination.
+ """
+ edge_uuids = [uuid for uuid in (getattr(e, "uuid", None) for e in edges) if uuid]
+ if not edge_uuids:
+ return
+
+ from backend.copilot.dream.ratification import try_ratify_on_hit
+
+ asyncio.create_task(
+ try_ratify_on_hit(user_id, edge_uuids),
+ name=f"ratify-hits-{user_id[:12]}",
+ )
+
+
def _format_context(edges, episodes) -> str | None:
sections: list[str] = []
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/context_test.py b/autogpt_platform/backend/backend/copilot/graphiti/context_test.py
index ce419b11ff..aab44bcfb3 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/context_test.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/context_test.py
@@ -62,13 +62,25 @@ class TestFetchWarmContextGeneralError:
# ---------------------------------------------------------------------------
+def _search_results(edges: list[object]) -> SimpleNamespace:
+ """Stand-in for graphiti_core.search.search_config.SearchResults — only
+ the ``.edges`` attribute is exercised by ``_fetch``."""
+ return SimpleNamespace(edges=edges)
+
+
class TestFetchInternal:
- """Test the internal _fetch function with mocked graphiti client."""
+ """Test the internal _fetch function with mocked graphiti client.
+
+ After P-1.4, ``_fetch`` calls ``client.search_()`` (note trailing
+ underscore) with the ``EDGE_HYBRID_SEARCH_CROSS_ENCODER`` recipe and
+ expects a ``SearchResults`` object whose ``.edges`` attribute carries
+ the candidate list. The mocks below reflect that shape.
+ """
@pytest.mark.asyncio
async def test_returns_none_when_no_edges_or_episodes(self) -> None:
mock_client = AsyncMock()
- mock_client.search.return_value = []
+ mock_client.search_.return_value = _search_results([])
mock_client.retrieve_episodes.return_value = []
with (
@@ -93,7 +105,7 @@ class TestFetchInternal:
invalid_at=None,
)
mock_client = AsyncMock()
- mock_client.search.return_value = [edge]
+ mock_client.search_.return_value = _search_results([edge])
mock_client.retrieve_episodes.return_value = []
with (
@@ -118,7 +130,7 @@ class TestFetchInternal:
created_at="2025-06-01T00:00:00Z",
)
mock_client = AsyncMock()
- mock_client.search.return_value = []
+ mock_client.search_.return_value = _search_results([])
mock_client.retrieve_episodes.return_value = [ep]
with (
@@ -135,6 +147,43 @@ class TestFetchInternal:
assert result is not None
assert "talked about coffee" in result
+ @pytest.mark.asyncio
+ async def test_search_call_uses_cross_encoder_recipe(self) -> None:
+ """P-1.4 contract: warm context must use the cross-encoder recipe.
+
+ Pins both the method (``search_`` not ``search``) and the recipe
+ passed as ``config=``. If a future refactor swaps in a different
+ recipe, this test fires.
+ """
+ mock_client = AsyncMock()
+ mock_client.search_.return_value = _search_results([])
+ mock_client.retrieve_episodes.return_value = []
+
+ with (
+ patch.object(context, "derive_group_id", return_value="user_abc"),
+ patch.object(
+ context,
+ "get_graphiti_client",
+ new_callable=AsyncMock,
+ return_value=mock_client,
+ ),
+ ):
+ await context._fetch("test-user", "hello world")
+
+ mock_client.search_.assert_awaited_once()
+ kwargs = mock_client.search_.await_args.kwargs
+ assert kwargs["query"] == "hello world"
+ assert kwargs["group_ids"] == ["user_abc"]
+ # The config is a copy of EDGE_HYBRID_SEARCH_CROSS_ENCODER with the
+ # limit overridden to context_max_facts. Verify the edge-config
+ # reranker is still ``cross_encoder`` so the contract is locked.
+ from graphiti_core.search.search_config import EdgeReranker
+
+ cfg = kwargs["config"]
+ assert cfg.edge_config is not None
+ assert cfg.edge_config.reranker == EdgeReranker.cross_encoder
+ assert cfg.limit == context.graphiti_config.context_max_facts
+
class TestFormatContextWithContent:
"""Test _format_context with actual edges and episodes."""
@@ -264,3 +313,63 @@ class TestFormatContextEmptyWrapper:
)
result = _format_context(edges=[], episodes=[ep])
assert result is None
+
+
+# ---------------------------------------------------------------------------
+# Ratification sync hit-hook spawned from warm-context retrieval
+# ---------------------------------------------------------------------------
+
+
+class TestRatificationHitHookFiresFireAndForget:
+ """The hit-hook records warm-context hits + promotes tentative
+ edges inline. It must NOT block the retrieval response — the
+ chat turn cares about latency, the promotion can race the next
+ retrieval to apply."""
+
+ def test_spawn_helper_skips_empty_edge_list_no_task_created(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ created_tasks: list[str] = []
+
+ def fake_create_task(coro, name=None):
+ created_tasks.append(name or "")
+ coro.close() # don't actually run the coroutine in test
+ return AsyncMock()
+
+ monkeypatch.setattr(context.asyncio, "create_task", fake_create_task)
+ context._spawn_ratification_hits("user-abc", edges=[])
+ assert created_tasks == []
+
+ def test_spawn_helper_creates_task_with_retrieved_uuids(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """Edges with uuid attrs → fire-and-forget task scheduled with
+ all of their uuids. Edges missing a uuid are filtered out so
+ the hook never passes ``None`` to the ratification module."""
+ captured_calls: list[tuple[str, list[str]]] = []
+
+ async def fake_try_ratify(user_id: str, edge_uuids: list[str]):
+ captured_calls.append((user_id, edge_uuids))
+
+ from backend.copilot.dream import ratification as ratification_mod
+
+ monkeypatch.setattr(ratification_mod, "try_ratify_on_hit", fake_try_ratify)
+
+ # asyncio.create_task needs an event loop — exercise via
+ # run_until_complete instead of an actual task spawn.
+ async def driver():
+ edges = [
+ SimpleNamespace(uuid="edge-a"),
+ SimpleNamespace(uuid="edge-b"),
+ SimpleNamespace(uuid=None), # filtered
+ SimpleNamespace(), # no uuid attr at all → filtered
+ ]
+ context._spawn_ratification_hits("user-xyz", edges=edges)
+ # Yield once so the spawned task runs.
+ await asyncio.sleep(0)
+
+ asyncio.run(driver())
+ assert len(captured_calls) == 1
+ user_id, uuids = captured_calls[0]
+ assert user_id == "user-xyz"
+ assert uuids == ["edge-a", "edge-b"]
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/falkordb_driver.py b/autogpt_platform/backend/backend/copilot/graphiti/falkordb_driver.py
index 670f82a38b..55c2f05e7e 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/falkordb_driver.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/falkordb_driver.py
@@ -4,6 +4,43 @@ from graphiti_core.helpers import validate_group_ids
class AutoGPTFalkorDriver(FalkorDriver):
+ """FalkorDriver subclass with two AutoGPT-specific tweaks.
+
+ 1. ``build_fulltext_query`` adds the per-user ``group_id`` filter so
+ multi-tenant searches don't cross user graphs.
+
+ 2. ``build_indices`` parameter (defaults True for upstream-compatible
+ behaviour) opts out of the fire-and-forget
+ ``build_indices_and_constraints`` background task that
+ graphiti-core's ``FalkorDriver.__init__`` always spawns.
+ That task is fine for long-lived drivers (chat ingest path) but
+ generates "Connection closed by server" / "Buffer is closed" log
+ spam when the driver is created per short-lived request — most
+ notably the admin memory visualizer's per-request driver opens,
+ where the indexing task's sequential CREATE INDEX statements
+ race the route's own queries and the closing of the connection
+ when the route returns. Pass ``build_indices=False`` for
+ read-only paths against an existing user's graph; the indices
+ are already there from the long-lived chat-write client.
+ """
+
+ def __init__(self, *args, build_indices: bool = True, **kwargs):
+ # Stash the flag BEFORE super().__init__ runs because
+ # FalkorDriver.__init__ fires
+ # ``loop.create_task(self.build_indices_and_constraints())``
+ # synchronously; our override below reads this attribute when
+ # the task actually ticks on the loop.
+ self._build_indices_at_init = build_indices
+ super().__init__(*args, **kwargs)
+
+ async def build_indices_and_constraints(self) -> None: # type: ignore[override]
+ if not getattr(self, "_build_indices_at_init", True):
+ # Caller asserted indices already exist (or will be built by
+ # someone else) — skip the multi-CREATE-INDEX race that
+ # produces the log spam.
+ return
+ await super().build_indices_and_constraints()
+
def build_fulltext_query(
self,
query: str,
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/falkordb_driver_test.py b/autogpt_platform/backend/backend/copilot/graphiti/falkordb_driver_test.py
index f6022092c5..eed7e5b60a 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/falkordb_driver_test.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/falkordb_driver_test.py
@@ -1,4 +1,4 @@
-from unittest.mock import MagicMock
+from unittest.mock import AsyncMock, MagicMock, patch
import pytest
@@ -54,3 +54,77 @@ def test_query_without_group_ids_returns_parenthesized_query(
query = driver.build_fulltext_query("Sarah", group_ids=None)
assert query == "(Sarah)"
+
+
+# ---------------------------------------------------------------------------
+# build_indices opt-out — pins the contract that suppresses graphiti-core's
+# per-driver background indexing task on read-only / per-request paths.
+# Regression coverage for the "Buffer is closed" log spam on admin viz loads.
+# ---------------------------------------------------------------------------
+
+
+async def test_build_indices_false_skips_super_call() -> None:
+ """``build_indices=False`` → our override returns early and never
+ delegates to ``FalkorDriver.build_indices_and_constraints``."""
+ with patch(
+ "graphiti_core.driver.falkordb_driver.FalkorDriver.__init__",
+ return_value=None,
+ ), patch(
+ "graphiti_core.driver.falkordb_driver.FalkorDriver.build_indices_and_constraints",
+ new=AsyncMock(),
+ ) as super_build:
+ driver = AutoGPTFalkorDriver(build_indices=False)
+ await driver.build_indices_and_constraints()
+ super_build.assert_not_called()
+
+
+async def test_build_indices_true_delegates_to_super() -> None:
+ """Default ``build_indices=True`` preserves upstream behaviour —
+ the long-lived chat-write client still gets its indices built."""
+ with patch(
+ "graphiti_core.driver.falkordb_driver.FalkorDriver.__init__",
+ return_value=None,
+ ), patch(
+ "graphiti_core.driver.falkordb_driver.FalkorDriver.build_indices_and_constraints",
+ new=AsyncMock(),
+ ) as super_build:
+ driver = AutoGPTFalkorDriver(build_indices=True)
+ await driver.build_indices_and_constraints()
+ super_build.assert_awaited_once()
+
+
+async def test_default_build_indices_is_upstream_compat() -> None:
+ """Omitting the kwarg keeps the upstream-default behaviour so
+ existing call sites (long-lived chat client) don't silently lose
+ their index-build path."""
+ with patch(
+ "graphiti_core.driver.falkordb_driver.FalkorDriver.__init__",
+ return_value=None,
+ ), patch(
+ "graphiti_core.driver.falkordb_driver.FalkorDriver.build_indices_and_constraints",
+ new=AsyncMock(),
+ ) as super_build:
+ driver = AutoGPTFalkorDriver()
+ await driver.build_indices_and_constraints()
+ super_build.assert_awaited_once()
+
+
+async def test_build_indices_false_persists_across_repeated_calls() -> None:
+ """The override doesn't flip after the first call — every invocation
+ against a ``build_indices=False`` driver stays a no-op."""
+ with patch(
+ "graphiti_core.driver.falkordb_driver.FalkorDriver.__init__",
+ return_value=None,
+ ), patch(
+ "graphiti_core.driver.falkordb_driver.FalkorDriver.build_indices_and_constraints",
+ new=AsyncMock(),
+ ) as super_build:
+ driver = AutoGPTFalkorDriver(build_indices=False)
+ await driver.build_indices_and_constraints()
+ await driver.build_indices_and_constraints()
+ await driver.build_indices_and_constraints()
+ super_build.assert_not_called()
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/flex_client.py b/autogpt_platform/backend/backend/copilot/graphiti/flex_client.py
new file mode 100644
index 0000000000..37ebff7755
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/graphiti/flex_client.py
@@ -0,0 +1,100 @@
+"""Graphiti LLM client that runs on OpenAI's flex tier.
+
+Subclasses graphiti-core's ``OpenAIClient`` to inject
+``service_tier="flex"`` on every underlying LLM call. Used by the
+nightly community-rebuild path: ~50% discount, best-effort latency
+(worst-case ~15min queue) — acceptable for scheduled non-interactive
+work, not for live chat ingest.
+
+``service_tier`` rides through ``extra_body`` so the same client works
+against both backends:
+
+- **OpenAI native** picks the param off the request body and routes
+ the call onto the flex queue.
+- **OpenRouter** forwards ``extra_body`` keys to the upstream model,
+ reaching the same flex tier for OpenAI/Google-backed models and
+ silently ignoring it for providers without a flex equivalent.
+
+We intentionally do NOT pass ``service_tier`` as a top-level SDK
+kwarg — the openai-python SDK doesn't expose it as a typed kwarg on
+every release, so ``extra_body`` is the forward-compatible path
+(mirrors what ``backend.util.llm.providers._call_openai_responses``
+does).
+"""
+
+from typing import Any
+
+from graphiti_core.llm_client import OpenAIClient
+from openai.types.chat import ChatCompletionMessageParam
+from pydantic import BaseModel
+
+
+class FlexOpenAIClient(OpenAIClient):
+ """Same as graphiti's ``OpenAIClient`` with ``service_tier`` injected.
+
+ Constructor mirrors ``OpenAIClient`` exactly so it slots into
+ graphiti's ``Graphiti(llm_client=...)`` without surprises.
+ """
+
+ SERVICE_TIER = "flex"
+
+ async def _create_structured_completion(
+ self,
+ model: str,
+ messages: list[ChatCompletionMessageParam],
+ temperature: float | None,
+ max_tokens: int,
+ response_model: type[BaseModel],
+ reasoning: str | None = None,
+ verbosity: str | None = None,
+ ):
+ is_reasoning_model = (
+ model.startswith("gpt-5")
+ or model.startswith("o1")
+ or model.startswith("o3")
+ )
+
+ request_kwargs: dict[str, Any] = {
+ "model": model,
+ "input": messages,
+ "max_output_tokens": max_tokens,
+ "text_format": response_model,
+ "extra_body": {"service_tier": self.SERVICE_TIER},
+ }
+
+ temperature_value = temperature if not is_reasoning_model else None
+ if temperature_value is not None:
+ request_kwargs["temperature"] = temperature_value
+
+ if is_reasoning_model and reasoning is not None:
+ request_kwargs["reasoning"] = {"effort": reasoning}
+
+ if is_reasoning_model and verbosity is not None:
+ request_kwargs["text"] = {"verbosity": verbosity}
+
+ return await self.client.responses.parse(**request_kwargs)
+
+ async def _create_completion(
+ self,
+ model: str,
+ messages: list[ChatCompletionMessageParam],
+ temperature: float | None,
+ max_tokens: int,
+ response_model: type[BaseModel] | None = None,
+ reasoning: str | None = None,
+ verbosity: str | None = None,
+ ):
+ is_reasoning_model = (
+ model.startswith("gpt-5")
+ or model.startswith("o1")
+ or model.startswith("o3")
+ )
+
+ return await self.client.chat.completions.create(
+ model=model,
+ messages=messages,
+ temperature=temperature if not is_reasoning_model else None,
+ max_tokens=max_tokens,
+ response_format={"type": "json_object"},
+ extra_body={"service_tier": self.SERVICE_TIER},
+ )
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/flex_client_test.py b/autogpt_platform/backend/backend/copilot/graphiti/flex_client_test.py
new file mode 100644
index 0000000000..01d0c81d72
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/graphiti/flex_client_test.py
@@ -0,0 +1,94 @@
+"""FlexOpenAIClient injects service_tier=flex on every underlying call."""
+
+from unittest.mock import AsyncMock
+
+import pytest
+from graphiti_core.llm_client import LLMConfig
+from pydantic import BaseModel
+
+from backend.copilot.graphiti.flex_client import FlexOpenAIClient
+
+
+class _DummyResponseModel(BaseModel):
+ answer: str
+
+
+def _make_client_with_stub_openai() -> tuple[FlexOpenAIClient, AsyncMock, AsyncMock]:
+ """Build a FlexOpenAIClient with its OpenAI client SDK swapped for mocks."""
+ config = LLMConfig(api_key="test-key", model="gpt-4.1-mini")
+ client = FlexOpenAIClient(config=config)
+
+ parse_mock = AsyncMock(return_value=object())
+ chat_create_mock = AsyncMock(return_value=object())
+
+ client.client.responses.parse = parse_mock # type: ignore[assignment]
+ client.client.chat.completions.create = chat_create_mock # type: ignore[assignment]
+
+ return client, parse_mock, chat_create_mock
+
+
+async def test_structured_completion_sends_service_tier_in_extra_body():
+ client, parse_mock, _ = _make_client_with_stub_openai()
+
+ await client._create_structured_completion(
+ model="gpt-4.1-mini",
+ messages=[{"role": "user", "content": "hi"}],
+ temperature=0.0,
+ max_tokens=128,
+ response_model=_DummyResponseModel,
+ )
+
+ parse_mock.assert_awaited_once()
+ kwargs = parse_mock.await_args.kwargs
+ assert kwargs["extra_body"] == {"service_tier": "flex"}
+ assert kwargs["text_format"] is _DummyResponseModel
+
+
+async def test_completion_sends_service_tier_in_extra_body():
+ client, _, chat_create_mock = _make_client_with_stub_openai()
+
+ await client._create_completion(
+ model="gpt-4.1-mini",
+ messages=[{"role": "user", "content": "hi"}],
+ temperature=0.0,
+ max_tokens=128,
+ )
+
+ chat_create_mock.assert_awaited_once()
+ kwargs = chat_create_mock.await_args.kwargs
+ assert kwargs["extra_body"] == {"service_tier": "flex"}
+ assert kwargs["response_format"] == {"type": "json_object"}
+
+
+async def test_reasoning_model_skips_temperature_keeps_flex():
+ """gpt-5 family doesn't accept temperature, but still gets the flex tag."""
+ client, parse_mock, chat_create_mock = _make_client_with_stub_openai()
+
+ await client._create_structured_completion(
+ model="gpt-5-thinking",
+ messages=[{"role": "user", "content": "hi"}],
+ temperature=0.5,
+ max_tokens=128,
+ response_model=_DummyResponseModel,
+ reasoning="medium",
+ verbosity="low",
+ )
+
+ parse_kwargs = parse_mock.await_args.kwargs
+ assert "temperature" not in parse_kwargs
+ assert parse_kwargs["reasoning"] == {"effort": "medium"}
+ assert parse_kwargs["text"] == {"verbosity": "low"}
+ assert parse_kwargs["extra_body"] == {"service_tier": "flex"}
+
+ await client._create_completion(
+ model="gpt-5-thinking",
+ messages=[{"role": "user", "content": "hi"}],
+ temperature=0.5,
+ max_tokens=128,
+ )
+ chat_kwargs = chat_create_mock.await_args.kwargs
+ assert chat_kwargs["temperature"] is None
+ assert chat_kwargs["extra_body"] == {"service_tier": "flex"}
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/graphiti_forget_integration_test.py b/autogpt_platform/backend/backend/copilot/graphiti/graphiti_forget_integration_test.py
new file mode 100644
index 0000000000..9b94974ead
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/graphiti/graphiti_forget_integration_test.py
@@ -0,0 +1,247 @@
+"""Integration tests for the P-1.3 demotion helpers, against live FalkorDB.
+
+The unit-test sibling (``backend/copilot/tools/graphiti_forget_test.py``)
+pins the Cypher strings and call signatures via mock drivers; those run
+fast but don't catch Cypher that's syntactically valid yet semantically
+wrong on FalkorDB (different graph engines have slightly different
+behavior around relationship variable scoping, ``MATCH`` semantics with
+property-only patterns, etc.).
+
+This file is the regression net that catches those. For every P-1.3
+behavior, seed a known graph, run the helper, query the resulting
+state via raw Cypher, and assert.
+
+The single most important test in the file is
+``test_invalidate_entity_direct_neighbors_is_single_hop`` — it pins the
+boundary that distinguishes our scoped cascade from the
+runaway-demotion footgun.
+"""
+
+import pytest
+
+from backend.copilot.tools.graphiti_forget import (
+ _retract_edges,
+ _soft_delete_edges,
+ invalidate_entity_direct_neighbors,
+ mark_edges_superseded,
+)
+
+
+async def _select_edge(driver, uuid: str) -> dict | None:
+ """Return the first row of edge properties matching ``uuid`` (or None)."""
+ records, _, _ = await driver.execute_query(
+ """
+ MATCH ()-[e:RELATES_TO {uuid: $uuid}]-()
+ RETURN e.expired_at AS expired_at,
+ e.invalid_at AS invalid_at,
+ e.status AS status,
+ e.expiration_reason AS expiration_reason
+ """,
+ uuid=uuid,
+ )
+ return records[0] if records else None
+
+
+async def test_retract_edges_sets_only_expired_at(seeded_graph) -> None:
+ """Per Snodgrass — system retraction sets expired_at only."""
+ driver, group_id = seeded_graph
+
+ deleted, failed = await _retract_edges(driver, ["e1"], "test-user")
+ assert deleted == ["e1"]
+ assert failed == []
+
+ row = await _select_edge(driver, "e1")
+ assert row is not None
+ assert row["expired_at"] is not None, "_retract_edges must set expired_at"
+ assert row["invalid_at"] is None, (
+ "_retract_edges must NOT set invalid_at — that's the contradiction-detector "
+ "path. Conflating the two breaks the bi-temporal model."
+ )
+
+
+async def test_soft_delete_edges_sets_both(seeded_graph) -> None:
+ """Contradiction-detector path keeps the original both-timestamps behavior."""
+ driver, group_id = seeded_graph
+
+ deleted, _ = await _soft_delete_edges(driver, ["e1"], "test-user")
+ assert deleted == ["e1"]
+
+ row = await _select_edge(driver, "e1")
+ assert row is not None
+ assert row["expired_at"] is not None
+ assert row["invalid_at"] is not None
+
+
+async def test_mark_edges_superseded_writes_status_and_reason(
+ seeded_graph,
+) -> None:
+ """`status` + `expiration_reason` survive on the durable edge for audit."""
+ driver, group_id = seeded_graph
+
+ deleted, failed = await mark_edges_superseded(
+ driver,
+ ["e1"],
+ reason="stale_fact",
+ new_status="superseded",
+ user_id="test-user",
+ )
+ assert deleted == ["e1"]
+ assert failed == []
+
+ row = await _select_edge(driver, "e1")
+ assert row is not None
+ assert row["expired_at"] is not None
+ assert row["status"] == "superseded"
+ assert row["expiration_reason"] == "stale_fact"
+
+
+async def test_mark_edges_superseded_supports_contradicted_status(
+ seeded_graph,
+) -> None:
+ """`contradicted` is the other allowed status — used by P0.5 web fact-check."""
+ driver, group_id = seeded_graph
+
+ await mark_edges_superseded(
+ driver,
+ ["e2"],
+ reason="web_contradicted:https://example.com",
+ new_status="contradicted",
+ user_id="test-user",
+ )
+
+ row = await _select_edge(driver, "e2")
+ assert row is not None
+ assert row["status"] == "contradicted"
+ assert row["expiration_reason"].startswith("web_contradicted:")
+
+
+async def test_invalidate_entity_direct_neighbors_is_single_hop(
+ clean_graph,
+) -> None:
+ """The 3-hop A→B→C→D test — the core P-1.3 / P0.3b guard.
+
+ Build a chain A↔B↔C↔D, invalidate B. Edges directly attached to B
+ (A↔B and B↔C) must be superseded. The remaining edge C↔D — one hop
+ further out — must be **untouched**. The instinct to use
+ ``[r:RELATES_TO*1..N]`` would propagate the cascade and destroy the
+ tangential relationship; the bare ``[r:RELATES_TO]`` pattern in
+ ``invalidate_entity_direct_neighbors`` is the discipline this test
+ pins.
+ """
+ driver, group_id = clean_graph
+
+ await driver.execute_query(
+ """
+ CREATE
+ (a:Entity {uuid: 'A', name: 'A', group_id: $gid}),
+ (b:Entity {uuid: 'B', name: 'B', group_id: $gid}),
+ (c:Entity {uuid: 'C', name: 'C', group_id: $gid}),
+ (d:Entity {uuid: 'D', name: 'D', group_id: $gid}),
+ (a)-[:RELATES_TO {uuid: 'AB', group_id: $gid, fact: 'A-B', status: 'active'}]->(b),
+ (b)-[:RELATES_TO {uuid: 'BC', group_id: $gid, fact: 'B-C', status: 'active'}]->(c),
+ (c)-[:RELATES_TO {uuid: 'CD', group_id: $gid, fact: 'C-D', status: 'active'}]->(d)
+ """,
+ gid=group_id,
+ )
+
+ demoted = await invalidate_entity_direct_neighbors(
+ driver, group_id=group_id, entity_uuid="B", reason="dead_client"
+ )
+
+ assert set(demoted) == {
+ "AB",
+ "BC",
+ }, f"Expected edges directly attached to B (AB, BC) to be demoted; got {demoted}"
+
+ # CD must be untouched — that's the boundary contract.
+ cd = await _select_edge(driver, "CD")
+ assert cd is not None
+ assert cd["expired_at"] is None, (
+ "CD is two hops from B and must NOT be demoted. If this fires, the "
+ "runaway-demotion guard has regressed — most likely someone introduced "
+ "a variable-length pattern (*1..N) into the Cypher."
+ )
+ assert cd["status"] != "superseded"
+
+ # Sanity: AB and BC should be superseded with the right reason.
+ for edge_uuid in ("AB", "BC"):
+ row = await _select_edge(driver, edge_uuid)
+ assert row is not None
+ assert row["expired_at"] is not None
+ assert row["status"] == "superseded"
+ assert row["expiration_reason"] == "dead_client"
+
+
+async def test_invalidate_entity_direct_neighbors_handles_both_edge_directions(
+ clean_graph,
+) -> None:
+ """The query uses an undirected ``-[r:RELATES_TO]-`` pattern so both
+ inbound and outbound edges are caught. Pin that.
+ """
+ driver, group_id = clean_graph
+
+ await driver.execute_query(
+ """
+ CREATE
+ (a:Entity {uuid: 'A', name: 'A', group_id: $gid}),
+ (b:Entity {uuid: 'B', name: 'B', group_id: $gid}),
+ (c:Entity {uuid: 'C', name: 'C', group_id: $gid}),
+ (a)-[:RELATES_TO {uuid: 'AB', group_id: $gid, fact: 'a→b', status: 'active'}]->(b),
+ (c)-[:RELATES_TO {uuid: 'CB', group_id: $gid, fact: 'c→b', status: 'active'}]->(b)
+ """,
+ gid=group_id,
+ )
+
+ demoted = await invalidate_entity_direct_neighbors(
+ driver, group_id=group_id, entity_uuid="B", reason="x"
+ )
+ assert set(demoted) == {"AB", "CB"}
+
+
+async def test_invalidate_entity_does_not_affect_other_users(
+ clean_graph,
+) -> None:
+ """``group_id`` scoping in the MATCH must isolate per-user graphs.
+
+ Build the same entity-uuid in two different group_ids. Invalidate
+ one; the other must be untouched.
+ """
+ driver, group_id = clean_graph
+ other_group = group_id + "_other"
+
+ await driver.execute_query(
+ """
+ CREATE
+ (a:Entity {uuid: 'shared', name: 'Shared', group_id: $g1}),
+ (b:Entity {uuid: 'other', name: 'Other', group_id: $g1}),
+ (a2:Entity {uuid: 'shared', name: 'Shared', group_id: $g2}),
+ (b2:Entity {uuid: 'other', name: 'Other', group_id: $g2}),
+ (a)-[:RELATES_TO {uuid: 'e_self', group_id: $g1, fact: 'self', status: 'active'}]->(b),
+ (a2)-[:RELATES_TO {uuid: 'e_other', group_id: $g2, fact: 'other', status: 'active'}]->(b2)
+ """,
+ g1=group_id,
+ g2=other_group,
+ )
+
+ demoted = await invalidate_entity_direct_neighbors(
+ driver, group_id=group_id, entity_uuid="shared", reason="test"
+ )
+ assert demoted == ["e_self"]
+
+ other_row = await _select_edge(driver, "e_other")
+ assert other_row is not None
+ assert other_row["expired_at"] is None, "other user's edge must not be touched"
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/ingest.py b/autogpt_platform/backend/backend/copilot/graphiti/ingest.py
index 58d086e55c..4d46e6f664 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/ingest.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/ingest.py
@@ -14,6 +14,7 @@ from graphiti_core.nodes import EpisodeType
from .client import derive_group_id, get_graphiti_client
from .memory_model import MemoryEnvelope, MemoryKind, MemoryStatus, SourceKind
+from .types import EDGE_TYPE_MAP, EDGE_TYPES, ENTITY_TYPES
logger = logging.getLogger(__name__)
@@ -50,6 +51,15 @@ def _get_loop_state() -> _LoopIngestState:
# Idle workers are cleaned up after this many seconds of inactivity.
_WORKER_IDLE_TIMEOUT = 60
+# Hard cap on a single episode body accepted by ``enqueue_episode``.
+# Dream-pass writers queue ``MemoryEnvelope.model_dump_json()`` built from
+# unvalidated LLM output, so the only other bound is the indirect
+# whole-response token budget (~64KB). Oversized bodies are rejected (not
+# truncated) — callers already handle the ``False`` return, and a truncated
+# JSON envelope would fail parsing downstream anyway. Mirrors the read-side
+# clamp (``dream/fetch.py:MAX_SESSION_BODY_BYTES``).
+MAX_EPISODE_BODY_BYTES = 64 * 1024
+
CUSTOM_EXTRACTION_INSTRUCTIONS = """
- Do not extract "User", "Assistant", "AI", "System", "CoPilot", or "human" as entity nodes.
- Do not extract software tool names, block names, API endpoint names, or internal system identifiers as entities.
@@ -81,7 +91,16 @@ async def _ingestion_worker(user_id: str, queue: asyncio.Queue) -> None:
try:
group_id = derive_group_id(user_id)
client = await get_graphiti_client(group_id)
- await client.add_episode(**payload)
+ # Pass custom entity + edge types so MemoryEnvelope metadata
+ # (status, confidence, source_kind, scope, provenance) lives
+ # on :RELATES_TO edges and not only inside :Episodic.content.
+ # Single point of wire-in for every caller of this worker.
+ await client.add_episode(
+ **payload,
+ entity_types=ENTITY_TYPES,
+ edge_types=EDGE_TYPES,
+ edge_type_map=EDGE_TYPE_MAP,
+ )
except Exception:
logger.warning(
"Graphiti ingestion failed for user %s",
@@ -215,6 +234,15 @@ async def enqueue_episode(
logger.warning("Invalid user_id for episode ingestion: %s", user_id[:12])
return False
+ body_bytes = len(episode_body.encode("utf-8"))
+ if body_bytes > MAX_EPISODE_BODY_BYTES:
+ logger.warning(
+ f"Episode body for user {user_id[:12]} exceeds size cap "
+ f"({body_bytes} > {MAX_EPISODE_BODY_BYTES} bytes) — "
+ f"rejecting episode {name!r}"
+ )
+ return False
+
queue = await _ensure_worker(user_id)
source = EpisodeType.json if is_json else EpisodeType.text
@@ -246,8 +274,17 @@ async def _ensure_worker(user_id: str) -> asyncio.Queue:
Returns the queue directly so callers don't need to look it up from
the state dict (which avoids a TOCTOU race if the worker times out
and cleans up between this call and the put_nowait).
+
+ Also fires the auto-registration of the user's dream-system
+ schedules (community rebuild + dream pass + ratification pass) the
+ first time we see them in this process — lazy on first memory write,
+ per-job flag-gated, per-job idempotent. See
+ ``copilot/dream/scheduling.py:ensure_dream_system_scheduled``.
+ Fire-and-forget; failures are swallowed inside the helper so
+ ingestion is never affected.
"""
state = _get_loop_state()
+ is_new_user_for_this_process = False
async with state.workers_lock:
if user_id not in state.user_queues:
q: asyncio.Queue = asyncio.Queue(maxsize=100)
@@ -256,7 +293,22 @@ async def _ensure_worker(user_id: str) -> asyncio.Queue:
_ingestion_worker(user_id, q),
name=f"graphiti-ingest-{user_id[:12]}",
)
- return state.user_queues[user_id]
+ is_new_user_for_this_process = True
+ queue = state.user_queues[user_id]
+
+ if is_new_user_for_this_process:
+ # Fire-and-forget; per-job Redis SETNX inside the helper
+ # provides cross-process / cross-restart idempotency. Done
+ # outside the workers_lock so the scheduler RPC can't
+ # deadlock ingestion.
+ from backend.copilot.dream.scheduling import ensure_dream_system_scheduled
+
+ asyncio.create_task(
+ ensure_dream_system_scheduled(user_id),
+ name=f"dream-system-register-{user_id[:12]}",
+ )
+
+ return queue
async def _resolve_user_name(user_id: str) -> str:
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/ingest_test.py b/autogpt_platform/backend/backend/copilot/graphiti/ingest_test.py
index 6cb9c5fbaf..aee025554f 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/ingest_test.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/ingest_test.py
@@ -193,6 +193,77 @@ class TestEnqueueEpisode:
)
assert result is False
+ @pytest.mark.asyncio
+ async def test_enqueue_episode_rejects_oversized_body_without_queueing(
+ self,
+ ) -> None:
+ """A body over MAX_EPISODE_BODY_BYTES is rejected (False) before any
+ worker or queue is touched — degraded dream writes must not reach
+ FalkorDB or the extraction LLM."""
+ with (
+ patch.object(ingest, "derive_group_id", return_value="user_abc"),
+ patch.object(
+ ingest, "_ensure_worker", new_callable=AsyncMock
+ ) as mock_worker,
+ ):
+ q: asyncio.Queue = asyncio.Queue(maxsize=100)
+ mock_worker.return_value = q
+
+ result = await ingest.enqueue_episode(
+ user_id="abc",
+ session_id="sess1",
+ name="runaway_consolidated_fact",
+ episode_body="x" * (ingest.MAX_EPISODE_BODY_BYTES + 1),
+ is_json=True,
+ )
+ assert result is False
+ mock_worker.assert_not_awaited()
+ assert q.empty()
+
+ @pytest.mark.asyncio
+ async def test_enqueue_episode_accepts_body_at_exact_size_cap(self) -> None:
+ with (
+ patch.object(ingest, "derive_group_id", return_value="user_abc"),
+ patch.object(
+ ingest, "_ensure_worker", new_callable=AsyncMock
+ ) as mock_worker,
+ ):
+ q: asyncio.Queue = asyncio.Queue(maxsize=100)
+ mock_worker.return_value = q
+
+ result = await ingest.enqueue_episode(
+ user_id="abc",
+ session_id="sess1",
+ name="cap_sized_ep",
+ episode_body="x" * ingest.MAX_EPISODE_BODY_BYTES,
+ )
+ assert result is True
+ assert not q.empty()
+
+ @pytest.mark.asyncio
+ async def test_enqueue_episode_size_cap_counts_bytes_not_chars(self) -> None:
+ """Multi-byte UTF-8 content is measured in encoded bytes, so a
+ char-count under the cap can still be rejected."""
+ with (
+ patch.object(ingest, "derive_group_id", return_value="user_abc"),
+ patch.object(
+ ingest, "_ensure_worker", new_callable=AsyncMock
+ ) as mock_worker,
+ ):
+ q: asyncio.Queue = asyncio.Queue(maxsize=100)
+ mock_worker.return_value = q
+
+ # "é" encodes to 2 bytes — half the cap in chars, just over in bytes.
+ body = "é" * (ingest.MAX_EPISODE_BODY_BYTES // 2 + 1)
+ result = await ingest.enqueue_episode(
+ user_id="abc",
+ session_id="sess1",
+ name="multibyte_ep",
+ episode_body=body,
+ )
+ assert result is False
+ assert q.empty()
+
@pytest.mark.asyncio
async def test_enqueue_episode_json_mode(self) -> None:
with (
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/migrations/__init__.py b/autogpt_platform/backend/backend/copilot/graphiti/migrations/__init__.py
new file mode 100644
index 0000000000..82806ad9d0
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/graphiti/migrations/__init__.py
@@ -0,0 +1,10 @@
+"""One-off Graphiti / FalkorDB migrations.
+
+Migrations here are Cypher operations on the per-user FalkorDB graphs.
+They are NOT Prisma migrations and do NOT participate in
+``poetry run prisma migrate``. Run each script manually via
+``poetry run python -m backend.copilot.graphiti.migrations.<name>``.
+
+Each migration MUST be idempotent — re-running it on an already-migrated
+database is a no-op.
+"""
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/migrations/backfill_edge_props.py b/autogpt_platform/backend/backend/copilot/graphiti/migrations/backfill_edge_props.py
new file mode 100644
index 0000000000..105aa8c8ba
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/graphiti/migrations/backfill_edge_props.py
@@ -0,0 +1,146 @@
+"""Backfill custom edge properties on existing ``:RELATES_TO`` edges.
+
+Created 2026-05-12 alongside the introduction of custom Graphiti entity
+and edge types (``graphiti/types.py``). Before custom types were wired
+into ``add_episode``, the LLM extractor produced edges with only
+``fact``/``name``/temporal-validity properties. The dream pass and
+ratification loop want to filter edges by ``status`` natively in Cypher,
+which requires the property to exist on every edge.
+
+This script walks every per-user FalkorDB database and sets
+``e.status = 'active'`` on every ``:RELATES_TO`` edge where ``status`` is
+unset. It is idempotent — re-running is a no-op.
+
+Usage:
+
+ poetry run python -m \\
+ backend.copilot.graphiti.migrations.backfill_edge_props
+
+By default it processes every user. Pass ``--user-id <id>`` to backfill
+one user (useful for canary / debugging).
+"""
+
+import argparse
+import asyncio
+import logging
+import sys
+
+from backend.copilot.graphiti.client import derive_group_id
+from backend.copilot.graphiti.config import graphiti_config
+from backend.copilot.graphiti.falkordb_driver import AutoGPTFalkorDriver
+
+logger = logging.getLogger(__name__)
+
+
+BACKFILL_QUERY = """
+MATCH ()-[e:RELATES_TO]->()
+WHERE e.status IS NULL
+SET e.status = 'active'
+RETURN count(e) AS updated
+"""
+
+# Page size for the Postgres User scan. We process users in fixed-size
+# batches ordered by ``id`` so the migration's memory footprint stays
+# constant even when the user base grows to millions of rows.
+USER_BATCH_SIZE = 1000
+
+
+async def backfill_one_user(user_id: str) -> int:
+ """Set default status='active' on edges for one user. Returns count updated."""
+ try:
+ group_id = derive_group_id(user_id)
+ except ValueError:
+ logger.warning(
+ "Skipping user %s — invalid for group_id derivation", user_id[:12]
+ )
+ return 0
+
+ driver = AutoGPTFalkorDriver(
+ host=graphiti_config.falkordb_host,
+ port=graphiti_config.falkordb_port,
+ password=graphiti_config.falkordb_password or None,
+ database=group_id,
+ )
+ try:
+ # ``execute_query`` is typed as ``tuple | None`` upstream; coerce
+ # to an empty tuple so pyright stops complaining about iterating
+ # over a None and the runtime stays single-pass.
+ result = await driver.execute_query(BACKFILL_QUERY)
+ records = result[0] if result else []
+ updated = records[0]["updated"] if records else 0
+ if updated:
+ logger.info("Backfilled %d edges for user %s", updated, user_id[:12])
+ return updated
+ except Exception:
+ # User may have no graph yet (never used memory). Treat as no-op.
+ logger.debug(
+ "No graph found or query failed for user %s", user_id[:12], exc_info=True
+ )
+ return 0
+ finally:
+ await driver.close()
+
+
+async def backfill_all_users() -> tuple[int, int]:
+ """Walk every User row in Postgres and backfill their graph.
+
+ Pages through ``User`` ordered by ``id`` so the migration's memory
+ footprint stays bounded by ``USER_BATCH_SIZE`` regardless of how
+ large the user table grows. Each page is fetched with
+ ``id > last_seen_id`` (keyset / cursor pagination), which is
+ O(log n) per page on the primary-key index — no growing OFFSET cost.
+
+ Returns (users_processed, edges_updated).
+ """
+ from prisma import Prisma
+
+ db = Prisma()
+ await db.connect()
+ total_users = 0
+ total_edges = 0
+ try:
+ last_seen_id: str | None = None
+ while True:
+ where = {"id": {"gt": last_seen_id}} if last_seen_id else {}
+ batch = await db.user.find_many(
+ where=where,
+ order={"id": "asc"},
+ take=USER_BATCH_SIZE,
+ )
+ if not batch:
+ break
+ for user in batch:
+ total_users += 1
+ updated = await backfill_one_user(user.id)
+ total_edges += updated
+ last_seen_id = batch[-1].id
+ if len(batch) < USER_BATCH_SIZE:
+ break
+ finally:
+ await db.disconnect()
+
+ return total_users, total_edges
+
+
+async def main(args: argparse.Namespace) -> int:
+ logging.basicConfig(
+ level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s"
+ )
+
+ if args.user_id:
+ updated = await backfill_one_user(args.user_id)
+ print(f"backfilled {updated} edges for user {args.user_id[:12]}")
+ return 0
+
+ users, edges = await backfill_all_users()
+ print(f"backfilled {edges} edges across {users} users")
+ return 0
+
+
+if __name__ == "__main__":
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument(
+ "--user-id",
+ help="Backfill a single user instead of all users. Useful for canary runs.",
+ )
+ sys.exit(asyncio.run(main(parser.parse_args())))
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/migrations/backfill_edge_props_test.py b/autogpt_platform/backend/backend/copilot/graphiti/migrations/backfill_edge_props_test.py
new file mode 100644
index 0000000000..af6cc9c8b4
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/graphiti/migrations/backfill_edge_props_test.py
@@ -0,0 +1,69 @@
+"""Tests for the backfill migration script — Cypher boundary mocked.
+
+The migration walks every User row and runs one Cypher per group.
+These tests pin its three branches: success, no-graph (FalkorDB raises
+on a missing database), and invalid-group-id.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock
+
+import pytest
+
+from . import backfill_edge_props as mig
+
+
[email protected](autouse=True)
+def _stub_driver(mocker):
+ """Replace AutoGPTFalkorDriver with a MagicMock that returns canned
+ execute_query results."""
+ driver = mocker.MagicMock()
+ driver.close = AsyncMock(return_value=None)
+ mocker.patch.object(
+ mig, "AutoGPTFalkorDriver", mocker.MagicMock(return_value=driver)
+ )
+ return driver
+
+
+async def test_backfill_one_user_counts_updated(_stub_driver):
+ """Happy path — Cypher returns one row with the updated count."""
+ _stub_driver.execute_query = AsyncMock(return_value=([{"updated": 7}], None, None))
+ updated = await mig.backfill_one_user("9aa20a1c-805e-4128-8bb2-c27515140264")
+ assert updated == 7
+ _stub_driver.execute_query.assert_awaited_once_with(mig.BACKFILL_QUERY)
+ _stub_driver.close.assert_awaited_once()
+
+
+async def test_backfill_one_user_no_records_returns_zero(_stub_driver):
+ """Empty result set (no edges needed backfilling)."""
+ _stub_driver.execute_query = AsyncMock(return_value=([], None, None))
+ assert await mig.backfill_one_user("9aa20a1c-805e-4128-8bb2-c27515140264") == 0
+
+
+async def test_backfill_one_user_none_result_returns_zero(_stub_driver):
+ """Driver returns None when the database doesn't exist yet.
+
+ Pyright fix path — the migration handles this gracefully so it
+ doesn't crash on freshly-signed-up users with no Graphiti graph.
+ """
+ _stub_driver.execute_query = AsyncMock(return_value=None)
+ assert await mig.backfill_one_user("9aa20a1c-805e-4128-8bb2-c27515140264") == 0
+
+
+async def test_backfill_one_user_swallows_driver_exception(_stub_driver, caplog):
+ """Missing-graph errors are logged at debug and treated as no-op."""
+ _stub_driver.execute_query = AsyncMock(side_effect=Exception("no such db"))
+ assert await mig.backfill_one_user("9aa20a1c-805e-4128-8bb2-c27515140264") == 0
+
+
+async def test_backfill_one_user_invalid_user_id_short_circuits(_stub_driver):
+ """``derive_group_id`` raises ValueError on garbage input — migration
+ must log and return 0 rather than attempting a query."""
+ assert await mig.backfill_one_user("") == 0
+ _stub_driver.execute_query.assert_not_called()
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/types.py b/autogpt_platform/backend/backend/copilot/graphiti/types.py
new file mode 100644
index 0000000000..32164512f4
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/graphiti/types.py
@@ -0,0 +1,122 @@
+"""Custom Graphiti entity + edge types for the CoPilot memory domain.
+
+Per the integration audit (dream/dreaming-graphiti.md §6.4), passing
+``entity_types`` and ``edge_types`` to ``Graphiti.add_episode()`` so that
+``MemoryEnvelope`` metadata (``status``, ``confidence``, ``source_kind``,
+``scope``, ``provenance``) survives the LLM extraction step and lives on
+the durable ``:RELATES_TO`` edge — not only in the ``:Episodic.content``
+JSON blob, which Cypher cannot filter without parsing.
+
+After this lands, search filters can do ``WHERE e.status = 'active'``
+natively and ratification can flip ``status`` with a single SET.
+"""
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from .memory_model import MemoryStatus, SourceKind
+
+
+class MemoryFact(BaseModel):
+ """Custom Graphiti edge type for :RELATES_TO edges in our domain.
+
+ Carries the structured metadata fields that the LLM extractor would
+ otherwise discard. Each field maps 1:1 to ``MemoryEnvelope`` so that
+ round-trips between the envelope JSON (on the episode) and the edge
+ properties preserve the same shape.
+ """
+
+ status: MemoryStatus = Field(
+ default=MemoryStatus.active,
+ description="Lifecycle state — active, tentative, superseded, contradicted.",
+ )
+ confidence: float | None = Field(
+ default=None,
+ ge=0.0,
+ le=1.0,
+ description="Confidence in [0, 1]; None means unspecified.",
+ )
+ source_kind: SourceKind = Field(
+ default=SourceKind.user_asserted,
+ description="Whether the fact came from the user, the assistant, or a tool observation.",
+ )
+ scope: str = Field(
+ default="real:global",
+ description="Namespace — 'real:global', 'project:<name>', 'book:<title>', 'session:<id>'.",
+ )
+ provenance: str | None = Field(
+ default=None,
+ description="Origin reference — 'session:{id}#msg:{sequence}', tool_call_id, or URL.",
+ )
+ web_verified_at: datetime | None = Field(
+ default=None,
+ description="When (if ever) this fact was verified against external web sources.",
+ )
+ ratified_at: datetime | None = Field(
+ default=None,
+ description="When a tentative fact was promoted to active via the ratification loop.",
+ )
+ expiration_reason: str | None = Field(
+ default=None,
+ description=(
+ "Short reason recorded when a fact is retracted or superseded. Examples: "
+ "'stale_fact', 'contradicted_by:{uuid}', 'entity_invalidated:{uuid}', "
+ "'web_contradicted:{url}', 'user_signal', 'unratified'."
+ ),
+ )
+
+
+# Entity types — kept narrow at v1. Expand only when extraction quality
+# issues prove that a missing type is the cause (per audit §6.3).
+class Person(BaseModel):
+ role: str | None = Field(
+ default=None, description="Role or title at an organization."
+ )
+ email: str | None = Field(default=None, description="Contact email if mentioned.")
+
+
+class Organization(BaseModel):
+ industry: str | None = Field(default=None, description="Industry or sector.")
+
+
+class Project(BaseModel):
+ # Named ``project_status`` (not ``status``) to disambiguate from
+ # ``MemoryFact.status`` (lifecycle of a fact) — different Cypher
+ # namespaces but readers see the same field name with conflicting
+ # types otherwise.
+ project_status: str | None = Field(
+ default=None,
+ description="Project status — active, completed, paused, cancelled.",
+ )
+
+
+class Concept(BaseModel):
+ """Domain concepts that aren't people, organizations, or projects."""
+
+
+class Preference(BaseModel):
+ """User preferences and stated likes/dislikes."""
+
+
+class Rule(BaseModel):
+ """Standing instructions (matches MemoryKind.rule)."""
+
+
+ENTITY_TYPES: dict[str, type[BaseModel]] = {
+ "Person": Person,
+ "Organization": Organization,
+ "Project": Project,
+ "Concept": Concept,
+ "Preference": Preference,
+ "Rule": Rule,
+}
+
+EDGE_TYPES: dict[str, type[BaseModel]] = {"MemoryFact": MemoryFact}
+
+# Allow MemoryFact between any pair of our entity types. Graphiti uses
+# this to constrain edge labels during extraction; allowing all pairs
+# keeps the LLM free to extract any meaningful relationship.
+EDGE_TYPE_MAP: dict[tuple[str, str], list[str]] = {
+ (src, tgt): ["MemoryFact"] for src in ENTITY_TYPES for tgt in ENTITY_TYPES
+}
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/types_integration_test.py b/autogpt_platform/backend/backend/copilot/graphiti/types_integration_test.py
new file mode 100644
index 0000000000..27662f4171
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/graphiti/types_integration_test.py
@@ -0,0 +1,200 @@
+"""Integration tests for the custom edge-type schema (P-1.1).
+
+Validates the schema contract that ``MemoryFact`` declares: when a
+``:RELATES_TO`` edge carries the new properties (``status``,
+``confidence``, ``source_kind``, ``scope``, ``provenance``,
+``web_verified_at``, ``ratified_at``, ``expiration_reason``), all of
+them round-trip cleanly through FalkorDB + the AutoGPTFalkorDriver,
+and Cypher queries can filter on them natively.
+
+What this does NOT test: end-to-end ``add_episode`` calls that exercise
+the LLM-driven entity extractor. That path requires a live LLM key and
+is covered by separate ``requires_llm``-marked tests when those are
+added. The schema-roundtrip test below is enough to catch the audit
+finding that motivated P-1.1 — metadata stranded inside
+``:Episodic.content`` JSON. After this test passes we know the
+properties at least *can* live on the durable edge.
+"""
+
+from datetime import datetime, timezone
+
+import pytest
+
+from .client import derive_group_id
+from .config import graphiti_config
+from .falkordb_driver import AutoGPTFalkorDriver
+
+
+async def test_hyphenated_uuid_group_id_round_trips_through_cypher(
+ falkordb_available: bool,
+) -> None:
+ """P-1.6 regression: derive_group_id intentionally preserves hyphens
+ (UUIDs contain them), and older Graphiti versions mangled hyphens in
+ Cypher property keys (upstream issue #1483). This test pins that a
+ real hyphenated UUID survives a write + read as a ``group_id`` property
+ so we notice immediately if a future driver/version regresses.
+
+ Uses its own driver — the ``clean_graph`` fixture mints hyphen-free
+ test ids on purpose, which would mask the bug we are guarding.
+ """
+ user_id = "3237579d-a31a-4bb8-ab56-d6e8f7cd0244"
+ group_id = derive_group_id(user_id)
+ assert "-" in group_id, "derive_group_id must preserve hyphens for this regression"
+
+ driver = AutoGPTFalkorDriver(
+ host=graphiti_config.falkordb_host,
+ port=graphiti_config.falkordb_port,
+ password=graphiti_config.falkordb_password or None,
+ database=group_id,
+ )
+ try:
+ await driver.execute_query(
+ "CREATE (n:Entity {uuid: 'probe', name: 'Alice', group_id: $gid})",
+ gid=group_id,
+ )
+ records, _, _ = await driver.execute_query(
+ "MATCH (n:Entity {group_id: $gid}) RETURN n.uuid AS uuid, n.group_id AS gid",
+ gid=group_id,
+ )
+ assert len(records) == 1
+ assert records[0]["uuid"] == "probe"
+ assert records[0]["gid"] == group_id
+ finally:
+ try:
+ await driver.execute_query("MATCH (n) DETACH DELETE n")
+ finally:
+ await driver.close()
+
+
+async def test_memory_fact_properties_roundtrip(clean_graph) -> None:
+ """Every MemoryFact property survives a write + read through Cypher."""
+ driver, group_id = clean_graph
+
+ # FalkorDB doesn't implement Cypher's literal-string ``datetime(...)``
+ # constructor (errors with ``Unknown function 'datetime'``). Pass ISO
+ # strings as parameters and write them straight onto the edge — the
+ # property's wire type is irrelevant to this roundtrip test, which
+ # only asserts the value reads back as non-null.
+ await driver.execute_query(
+ """
+ CREATE
+ (a:Entity {uuid: 'a', name: 'Alice', group_id: $gid}),
+ (t:Entity {uuid: 't', name: 'Atlas', group_id: $gid}),
+ (a)-[:RELATES_TO {
+ uuid: 'e1',
+ group_id: $gid,
+ fact: 'Alice works on Atlas',
+ name: 'works_on',
+ status: 'active',
+ confidence: 0.85,
+ source_kind: 'user_asserted',
+ scope: 'real:global',
+ provenance: 'session:abc#msg:42',
+ web_verified_at: $web_verified_at,
+ ratified_at: $ratified_at,
+ expiration_reason: null
+ }]->(t)
+ """,
+ gid=group_id,
+ web_verified_at="2026-05-13T03:00:00Z",
+ ratified_at="2026-05-14T03:00:00Z",
+ )
+
+ records, _, _ = await driver.execute_query(
+ """
+ MATCH ()-[e:RELATES_TO {uuid: 'e1'}]->()
+ RETURN e.status AS status,
+ e.confidence AS confidence,
+ e.source_kind AS source_kind,
+ e.scope AS scope,
+ e.provenance AS provenance,
+ e.web_verified_at AS web_verified_at,
+ e.ratified_at AS ratified_at,
+ e.expiration_reason AS expiration_reason
+ """,
+ )
+
+ assert len(records) == 1
+ row = records[0]
+ assert row["status"] == "active"
+ assert row["confidence"] == pytest.approx(0.85)
+ assert row["source_kind"] == "user_asserted"
+ assert row["scope"] == "real:global"
+ assert row["provenance"] == "session:abc#msg:42"
+ assert row["web_verified_at"] is not None
+ assert row["ratified_at"] is not None
+ assert row["expiration_reason"] is None
+
+
+async def test_status_filter_is_cypher_native(seeded_graph) -> None:
+ """`WHERE e.status = 'active'` is the whole reason for P-1.1.
+
+ Before custom edge types landed, the filter had to parse the
+ `:Episodic.content` JSON blob in Python. After P-1.1, it lives on
+ the edge property and Cypher does the work. This test pins that
+ contract: seed two active edges, demote one, assert the active
+ filter returns exactly one.
+ """
+ driver, group_id = seeded_graph
+
+ # Demote e1. FalkorDB doesn't implement Cypher's no-arg ``datetime()``;
+ # generate the timestamp in Python and bind it as a parameter (same
+ # workaround the seeded_graph fixture, dream/fetch.py, and
+ # tools/graphiti_forget.py use against the same backend).
+ await driver.execute_query(
+ """
+ MATCH ()-[e:RELATES_TO {uuid: 'e1'}]->()
+ SET e.status = 'superseded',
+ e.expired_at = $now,
+ e.expiration_reason = 'integration-test-demotion'
+ """,
+ now=datetime.now(timezone.utc).isoformat(),
+ )
+
+ records, _, _ = await driver.execute_query(
+ """
+ MATCH ()-[e:RELATES_TO {group_id: $gid}]->()
+ WHERE e.status = 'active'
+ RETURN e.uuid AS uuid
+ """,
+ gid=group_id,
+ )
+ surviving = {r["uuid"] for r in records}
+ assert surviving == {"e2"}, f"expected only e2 to remain active, got {surviving}"
+
+
+async def test_scope_filter_is_cypher_native(clean_graph) -> None:
+ """Same shape as status filter, but for ``scope`` — proves the audit's
+ "push scope into edges" recommendation works once custom types are wired.
+ """
+ driver, group_id = clean_graph
+
+ await driver.execute_query(
+ """
+ CREATE
+ (a:Entity {uuid: 'a', name: 'Alice', group_id: $gid}),
+ (b:Entity {uuid: 'b', name: 'Bob', group_id: $gid}),
+ (a)-[:RELATES_TO {uuid: 'g1', group_id: $gid, fact: 'global', scope: 'real:global'}]->(b),
+ (a)-[:RELATES_TO {uuid: 'p1', group_id: $gid, fact: 'project', scope: 'project:atlas'}]->(b),
+ (a)-[:RELATES_TO {uuid: 'p2', group_id: $gid, fact: 'other', scope: 'project:beacon'}]->(b)
+ """,
+ gid=group_id,
+ )
+
+ records, _, _ = await driver.execute_query(
+ """
+ MATCH ()-[e:RELATES_TO {group_id: $gid}]->()
+ WHERE e.scope = 'project:atlas' OR e.scope = 'real:global'
+ RETURN e.uuid AS uuid
+ """,
+ gid=group_id,
+ )
+ assert {r["uuid"] for r in records} == {"g1", "p1"}
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/types_test.py b/autogpt_platform/backend/backend/copilot/graphiti/types_test.py
new file mode 100644
index 0000000000..83b3860cc1
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/graphiti/types_test.py
@@ -0,0 +1,116 @@
+"""Schema-level coverage for the custom Graphiti entity + edge types.
+
+These tests pin the field defaults and constraints so a regression
+on the audit-fix payload (status / confidence / scope / source_kind /
+provenance) is caught locally before it round-trips through Graphiti's
+LLM extraction step and ends up on production :RELATES_TO edges.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+import pytest
+from pydantic import ValidationError
+
+from .memory_model import MemoryStatus, SourceKind
+from .types import (
+ EDGE_TYPE_MAP,
+ EDGE_TYPES,
+ ENTITY_TYPES,
+ MemoryFact,
+ Organization,
+ Person,
+)
+
+
+def test_memoryfact_defaults_match_envelope():
+ """Defaults round-trip into a :RELATES_TO edge without surprises."""
+ fact = MemoryFact()
+ assert fact.status == MemoryStatus.active
+ assert fact.confidence is None
+ assert fact.source_kind == SourceKind.user_asserted
+ assert fact.scope == "real:global"
+ assert fact.provenance is None
+ assert fact.web_verified_at is None
+ assert fact.ratified_at is None
+ assert fact.expiration_reason is None
+
+
+ "value,ok",
+ [(-0.01, False), (0.0, True), (0.5, True), (1.0, True), (1.01, False)],
+)
+def test_memoryfact_confidence_bounds(value, ok):
+ if ok:
+ MemoryFact(confidence=value)
+ else:
+ with pytest.raises(ValidationError):
+ MemoryFact(confidence=value)
+
+
+def test_memoryfact_status_enum_restricted():
+ """Open enum on the envelope side, restricted on the edge side."""
+ MemoryFact(status=MemoryStatus.tentative)
+ with pytest.raises(ValidationError):
+ MemoryFact(status="archived") # type: ignore[arg-type]
+
+
+def test_memoryfact_carries_full_envelope_metadata():
+ """All audit-required fields can be set in one shot."""
+ fact = MemoryFact(
+ status=MemoryStatus.tentative,
+ confidence=0.7,
+ source_kind=SourceKind.assistant_derived,
+ scope="project:foo",
+ provenance="session:s1#msg:42",
+ web_verified_at=datetime(2026, 5, 12, tzinfo=timezone.utc),
+ ratified_at=datetime(2026, 5, 14, tzinfo=timezone.utc),
+ expiration_reason="stale_fact",
+ )
+ dumped = fact.model_dump(mode="json")
+ assert dumped["status"] == "tentative"
+ assert dumped["confidence"] == 0.7
+ assert dumped["source_kind"] == "assistant_derived"
+ assert dumped["scope"] == "project:foo"
+ assert dumped["provenance"] == "session:s1#msg:42"
+ assert dumped["web_verified_at"] == "2026-05-12T00:00:00Z"
+ assert dumped["ratified_at"] == "2026-05-14T00:00:00Z"
+ assert dumped["expiration_reason"] == "stale_fact"
+
+
+def test_entity_types_include_the_six_canonical_kinds():
+ """Audit §6.3 — narrow entity allowlist."""
+ expected = {"Person", "Organization", "Project", "Concept", "Preference", "Rule"}
+ assert expected.issubset(set(ENTITY_TYPES.keys()))
+
+
+def test_edge_types_include_memoryfact():
+ assert "MemoryFact" in EDGE_TYPES
+ assert EDGE_TYPES["MemoryFact"] is MemoryFact
+
+
+def test_edge_type_map_spans_full_cartesian_product():
+ """Every (entity, entity) pair maps to MemoryFact — the audit's
+ 'one edge type, narrow entity vocabulary' shape."""
+ # Six entity types × six entity types = 36 pairs.
+ assert len(EDGE_TYPE_MAP) == len(ENTITY_TYPES) ** 2
+ for src in ENTITY_TYPES:
+ for tgt in ENTITY_TYPES:
+ assert EDGE_TYPE_MAP.get((src, tgt)) == ["MemoryFact"]
+
+
+def test_person_entity_has_optional_role_and_email():
+ p = Person()
+ assert p.role is None
+ assert p.email is None
+ p = Person(role="CEO", email="[email protected]")
+ assert p.role == "CEO"
+ assert p.email == "[email protected]"
+
+
+def test_organization_entity_has_optional_industry():
+ o = Organization()
+ assert o.industry is None
+ o = Organization(industry="aerospace")
+ assert o.industry == "aerospace"
diff --git a/autogpt_platform/backend/backend/copilot/model.py b/autogpt_platform/backend/backend/copilot/model.py
index d2e8fd996d..8836cd008b 100644
--- a/autogpt_platform/backend/backend/copilot/model.py
+++ b/autogpt_platform/backend/backend/copilot/model.py
@@ -72,6 +72,17 @@ class ChatSessionMetadata(BaseModel):
builder_graph_id: str | None = None
source_platform: str | None = None
+ # Session kind — distinguishes regular chats from dream-pass and
+ # daydream artifacts so the frontend can render them differently
+ # (and so analytics / retention rules can filter them out).
+ # Open enum: future kinds (e.g. ``"daydream"``) can land without a
+ # migration; readers must tolerate unknown values.
+ kind: str = "normal"
+
+ # When ``kind == "dream"``, the originating pass id so the session
+ # links back to the orchestrator run that produced it.
+ dream_pass_id: str | None = None
+
class ChatMessage(BaseModel):
id: str | None = None
diff --git a/autogpt_platform/backend/backend/copilot/optimize_blocks_test.py b/autogpt_platform/backend/backend/copilot/optimize_blocks_test.py
index a34fcf998f..8c36563601 100644
--- a/autogpt_platform/backend/backend/copilot/optimize_blocks_test.py
+++ b/autogpt_platform/backend/backend/copilot/optimize_blocks_test.py
@@ -1,6 +1,15 @@
-"""Unit tests for optimize_blocks._optimize_descriptions."""
+"""Unit tests for optimize_blocks._optimize_descriptions.
+
+Tests are written as ``async def`` so ``asyncio_mode="auto"`` (set in
+``pyproject.toml``) wires them through pytest-asyncio's session-scoped
+runner. Previously these tests used a ``_run`` helper around
+``asyncio.get_event_loop().run_until_complete`` — that pattern raises
+``RuntimeError: There is no current event loop in thread 'MainThread'``
+under Python 3.12 when the thread doesn't have a current loop (the
+previous test in the suite can close one and never set a new one). The
+auto-mode runner gives each test its own loop deterministically.
+"""
-import asyncio
from unittest.mock import AsyncMock, MagicMock, patch
from backend.copilot.optimize_blocks import _RATE_LIMIT_DELAY, _optimize_descriptions
@@ -15,23 +24,19 @@ def _make_client_response(text: str) -> MagicMock:
return response
-def _run(coro):
- return asyncio.get_event_loop().run_until_complete(coro)
-
-
class TestOptimizeDescriptions:
"""Tests for _optimize_descriptions async function."""
- def test_returns_empty_when_no_client(self):
+ async def test_returns_empty_when_no_client(self):
with patch(
"backend.copilot.optimize_blocks.get_openai_client", return_value=None
):
- result = _run(
- _optimize_descriptions([{"id": "b1", "name": "B", "description": "d"}])
+ result = await _optimize_descriptions(
+ [{"id": "b1", "name": "B", "description": "d"}]
)
assert result == {}
- def test_success_single_block(self):
+ async def test_success_single_block(self):
client = MagicMock()
client.chat.completions.create = AsyncMock(
return_value=_make_client_response("Short desc.")
@@ -46,12 +51,12 @@ class TestOptimizeDescriptions:
"backend.copilot.optimize_blocks.asyncio.sleep", new_callable=AsyncMock
),
):
- result = _run(_optimize_descriptions(blocks))
+ result = await _optimize_descriptions(blocks)
assert result == {"b1": "Short desc."}
client.chat.completions.create.assert_called_once()
- def test_skips_block_on_exception(self):
+ async def test_skips_block_on_exception(self):
client = MagicMock()
client.chat.completions.create = AsyncMock(side_effect=Exception("API error"))
blocks = [{"id": "b1", "name": "MyBlock", "description": "A block."}]
@@ -64,11 +69,11 @@ class TestOptimizeDescriptions:
"backend.copilot.optimize_blocks.asyncio.sleep", new_callable=AsyncMock
),
):
- result = _run(_optimize_descriptions(blocks))
+ result = await _optimize_descriptions(blocks)
assert result == {}
- def test_sleeps_between_blocks(self):
+ async def test_sleeps_between_blocks(self):
client = MagicMock()
client.chat.completions.create = AsyncMock(
return_value=_make_client_response("desc")
@@ -85,7 +90,7 @@ class TestOptimizeDescriptions:
),
patch("backend.copilot.optimize_blocks.asyncio.sleep", sleep_mock),
):
- _run(_optimize_descriptions(blocks))
+ await _optimize_descriptions(blocks)
assert sleep_mock.call_count == 2
sleep_mock.assert_called_with(_RATE_LIMIT_DELAY)
diff --git a/autogpt_platform/backend/backend/copilot/permissions.py b/autogpt_platform/backend/backend/copilot/permissions.py
index 20b920fdf3..c2dea20c5f 100644
--- a/autogpt_platform/backend/backend/copilot/permissions.py
+++ b/autogpt_platform/backend/backend/copilot/permissions.py
@@ -489,3 +489,35 @@ def apply_tool_permissions(
extra_disallowed = list(set(base_disallowed) | removed)
return filtered_allowed, extra_disallowed
+
+
+# ---------------------------------------------------------------------------
+# Presets
+# ---------------------------------------------------------------------------
+
+# Dream-pass sub-agent capability filter (spec: ``dream/p0-spec.md`` §P0.5).
+#
+# The dream orchestrator runs phases 1/2/3 via direct LLM calls today, but P0.5
+# (web fact-check) and P9 (daydreaming) hand work to a sub-agent that must be
+# strictly capability-bounded: read/write the user's Graphiti memory and
+# fact-check claims against the web — nothing else. No shell, no general web
+# browsing, no file ops, no agent-graph mutation.
+#
+# Stored as a **whitelist** (``tools_exclude=False``) so the universe of
+# permitted tools is explicit and grows only when this preset is edited.
+#
+# ``web_fact_check`` is intentionally listed even though the tool does not yet
+# exist in ``TOOL_REGISTRY`` — it lands in P0.5. Unknown short names are
+# silently dropped by :meth:`CopilotPermissions.effective_allowed_tools` (it
+# intersects with ``all_tools``), so the preset is forward-compatible without
+# needing to be updated when the tool ships.
+DREAM_PERMISSIONS: CopilotPermissions = CopilotPermissions(
+ tools=[
+ "memory_search",
+ "memory_store",
+ "memory_forget_search",
+ "memory_forget_confirm",
+ "web_fact_check",
+ ],
+ tools_exclude=False,
+)
diff --git a/autogpt_platform/backend/backend/copilot/permissions_test.py b/autogpt_platform/backend/backend/copilot/permissions_test.py
index 5df999b4d6..a9153826e3 100644
--- a/autogpt_platform/backend/backend/copilot/permissions_test.py
+++ b/autogpt_platform/backend/backend/copilot/permissions_test.py
@@ -6,6 +6,7 @@ import pytest
from backend.copilot.permissions import (
ALL_TOOL_NAMES,
+ DREAM_PERMISSIONS,
PLATFORM_TOOL_NAMES,
SDK_BUILTIN_TOOL_NAMES,
CopilotPermissions,
@@ -625,3 +626,92 @@ class TestSdkBuiltinToolNames:
assert "run_block" in known
assert "Read" in known
assert "Task" in known
+
+
+# ---------------------------------------------------------------------------
+# DREAM_PERMISSIONS preset (spec: dream/p0-spec.md §P0.5)
+# ---------------------------------------------------------------------------
+
+
+class TestDreamPermissionsPreset:
+ """The dream sub-agent must only touch memory + (future) web fact-check."""
+
+ def test_preset_is_whitelist_not_blacklist(self):
+ # Critical: blacklist semantics would *allow* everything not listed,
+ # which is the opposite of what we want for a restricted sub-agent.
+ assert DREAM_PERMISSIONS.tools_exclude is False
+
+ def test_memory_tools_are_allowed(self):
+ # All four Graphiti-backed memory ops the dream pass needs (read,
+ # write, find-for-forget, confirm-forget).
+ allowed = set(DREAM_PERMISSIONS.tools)
+ assert {
+ "memory_search",
+ "memory_store",
+ "memory_forget_search",
+ "memory_forget_confirm",
+ }.issubset(allowed)
+
+ def test_web_fact_check_is_listed_for_future_p0_5(self):
+ # web_fact_check ships with P0.5; preset is forward-compatible.
+ assert "web_fact_check" in DREAM_PERMISSIONS.tools
+
+ def test_shell_execution_is_blocked(self):
+ # Hard rule: dream sub-agent must never get a shell.
+ effective = DREAM_PERMISSIONS.effective_allowed_tools(ALL_TOOL_NAMES)
+ assert "bash_exec" not in effective
+
+ def test_general_web_browsing_is_blocked(self):
+ # web_fact_check is the *only* permitted web egress; raw fetch/search
+ # and browser tools must stay blocked.
+ effective = DREAM_PERMISSIONS.effective_allowed_tools(ALL_TOOL_NAMES)
+ assert "web_fetch" not in effective
+ assert "web_search" not in effective
+ assert "WebSearch" not in effective # SDK built-in
+ assert "browser_act" not in effective
+ assert "browser_navigate" not in effective
+ assert "browser_screenshot" not in effective
+
+ def test_file_operations_are_blocked(self):
+ # No workspace file ops, no SDK built-in file editing.
+ effective = DREAM_PERMISSIONS.effective_allowed_tools(ALL_TOOL_NAMES)
+ for tool in (
+ "read_workspace_file",
+ "write_workspace_file",
+ "delete_workspace_file",
+ "list_workspace_files",
+ "Read",
+ "Write",
+ "Edit",
+ "Glob",
+ "Grep",
+ ):
+ assert tool not in effective, f"{tool} must be blocked for dream sub-agent"
+
+ def test_agent_graph_mutation_is_blocked(self):
+ # Dream pass reflects on memory; it does not edit or run agents.
+ effective = DREAM_PERMISSIONS.effective_allowed_tools(ALL_TOOL_NAMES)
+ for tool in (
+ "create_agent",
+ "edit_agent",
+ "fix_agent_graph",
+ "run_agent",
+ "run_block",
+ "run_sub_session",
+ "Task",
+ ):
+ assert tool not in effective, f"{tool} must be blocked for dream sub-agent"
+
+ def test_effective_set_matches_whitelist_intersection(self):
+ # Sanity: effective set = whitelist ∩ known universe. web_fact_check
+ # is intentionally absent from the universe until P0.5 lands, so the
+ # effective set today is the four memory tools.
+ effective = DREAM_PERMISSIONS.effective_allowed_tools(ALL_TOOL_NAMES)
+ assert effective == frozenset(
+ {
+ "memory_search",
+ "memory_store",
+ "memory_forget_search",
+ "memory_forget_confirm",
+ }
+ )
diff --git a/autogpt_platform/backend/backend/copilot/rate_limit.py b/autogpt_platform/backend/backend/copilot/rate_limit.py
index a4966aa952..b12b237280 100644
--- a/autogpt_platform/backend/backend/copilot/rate_limit.py
+++ b/autogpt_platform/backend/backend/copilot/rate_limit.py
@@ -657,6 +657,8 @@ async def check_rate_limit(
user_id: str,
daily_cost_limit: int,
weekly_cost_limit: int,
+ *,
+ skip_daily: bool = False,
) -> None:
"""Check if user is within rate limits.
@@ -672,6 +674,11 @@ async def check_rate_limit(
dependency :func:`enforce_payment_paywall`, so this function is
purely about per-window USD usage.
+ ``skip_daily`` skips the daily-cap check; the weekly cap still
+ applies. Used by the dream pass so a user with a busy interactive
+ day still gets their nightly background pass — dream rolls under
+ the weekly account ceiling instead.
+
This is a pre-turn soft check. The authoritative usage counter is updated
by ``record_cost_usage()`` after the turn completes. Under concurrency,
two parallel turns may both pass this check against the same snapshot.
@@ -709,7 +716,7 @@ async def check_rate_limit(
# silently treated 0 as unlimited, which collided with the multiplier-
# collapse semantics of :func:`get_global_rate_limits` and produced
# the autopilot paywall bypass.
- if daily_cost_limit >= 0 and daily_used >= daily_cost_limit:
+ if not skip_daily and daily_cost_limit >= 0 and daily_used >= daily_cost_limit:
raise RateLimitExceeded("daily", _daily_reset_time(now=now))
if weekly_cost_limit >= 0 and weekly_used >= weekly_cost_limit:
@@ -817,6 +824,8 @@ async def increment_daily_reset_count(user_id: str) -> None:
async def record_cost_usage(
user_id: str,
cost_microdollars: int,
+ *,
+ skip_daily: bool = False,
) -> None:
"""Record a user's generation spend against daily and weekly counters.
@@ -830,12 +839,21 @@ async def record_cost_usage(
user_id: The user's ID.
cost_microdollars: Spend to record in microdollars (1 USD = 1_000_000).
Non-positive values are ignored.
+ skip_daily: When True, only the weekly counter is incremented. Used
+ by the dream pass so background work doesn't eat the user's
+ interactive daily budget. Dream still counts toward the weekly
+ cap so a user can't dream-pass their way out of an account-wide
+ spend ceiling.
"""
cost_microdollars = max(0, cost_microdollars)
if cost_microdollars <= 0:
return
- logger.info("Recording copilot spend: %d microdollars", cost_microdollars)
+ logger.info(
+ "Recording copilot spend: %d microdollars (skip_daily=%s)",
+ cost_microdollars,
+ skip_daily,
+ )
now = datetime.now(UTC)
d_key = _daily_key(user_id, now=now)
@@ -848,7 +866,8 @@ async def record_cost_usage(
# MULTI/EXEC is not supported, so each counter gets its own
# single-key transaction. Per-counter INCRBY+EXPIRE atomicity is the
# invariant that matters; the two counters are independent budgets.
- await _incr_counter_atomic(redis, d_key, cost_microdollars, daily_ttl)
+ if not skip_daily:
+ await _incr_counter_atomic(redis, d_key, cost_microdollars, daily_ttl)
await _incr_counter_atomic(redis, w_key, cost_microdollars, weekly_ttl)
except (RedisError, RedisClusterException, ConnectionError, OSError):
logger.warning(
diff --git a/autogpt_platform/backend/backend/copilot/rate_limit_test.py b/autogpt_platform/backend/backend/copilot/rate_limit_test.py
index 19ddb504c5..f21bf5bb11 100644
--- a/autogpt_platform/backend/backend/copilot/rate_limit_test.py
+++ b/autogpt_platform/backend/backend/copilot/rate_limit_test.py
@@ -204,6 +204,41 @@ class TestCheckRateLimit:
)
assert exc_info.value.window == "daily"
+ @pytest.mark.asyncio
+ async def test_skip_daily_bypasses_daily_cap_but_still_checks_weekly(self):
+ """Dream pass calls with ``skip_daily=True``. A user at-or-over
+ their daily cap must still be allowed to run a dream pass, but
+ being over the weekly cap still rejects."""
+ # Daily over-cap, weekly fine → must NOT raise when skipped.
+ mock_redis = AsyncMock()
+ mock_redis.get = AsyncMock(side_effect=["10000", "200"])
+ with patch(
+ "backend.copilot.rate_limit.get_redis_async",
+ return_value=mock_redis,
+ ):
+ await check_rate_limit(
+ _USER,
+ daily_cost_limit=10000,
+ weekly_cost_limit=50000,
+ skip_daily=True,
+ )
+
+ # Weekly over-cap → still rejects even when skip_daily=True.
+ mock_redis = AsyncMock()
+ mock_redis.get = AsyncMock(side_effect=["100", "50000"])
+ with patch(
+ "backend.copilot.rate_limit.get_redis_async",
+ return_value=mock_redis,
+ ):
+ with pytest.raises(RateLimitExceeded) as exc_info:
+ await check_rate_limit(
+ _USER,
+ daily_cost_limit=10000,
+ weekly_cost_limit=50000,
+ skip_daily=True,
+ )
+ assert exc_info.value.window == "weekly"
+
@pytest.mark.asyncio
async def test_raises_when_weekly_limit_exceeded(self):
mock_redis = AsyncMock()
@@ -729,6 +764,26 @@ class TestRecordCostUsage:
assert incrby_calls[0].args[1] == 123_456 # daily
assert incrby_calls[1].args[1] == 123_456 # weekly
+ @pytest.mark.asyncio
+ async def test_skip_daily_increments_weekly_only(self):
+ """Dream pass passes ``skip_daily=True`` so background spend rolls up
+ under the user's weekly cap but doesn't burn their interactive
+ daily budget. Daily INCRBY must NOT fire."""
+ mock_pipe = self._make_pipeline_mock()
+ mock_redis = AsyncMock()
+ mock_redis.pipeline = lambda **_kw: mock_pipe
+
+ with patch(
+ "backend.copilot.rate_limit.get_redis_async",
+ return_value=mock_redis,
+ ):
+ await record_cost_usage(_USER, cost_microdollars=7_777, skip_daily=True)
+
+ # Only one incrby — the weekly one.
+ incrby_calls = mock_pipe.incrby.call_args_list
+ assert len(incrby_calls) == 1
+ assert incrby_calls[0].args[1] == 7_777
+
@pytest.mark.asyncio
async def test_skips_when_cost_is_zero(self):
mock_redis = AsyncMock()
diff --git a/autogpt_platform/backend/backend/copilot/response_model.py b/autogpt_platform/backend/backend/copilot/response_model.py
index f6faa1bd19..a0002c63c1 100644
--- a/autogpt_platform/backend/backend/copilot/response_model.py
+++ b/autogpt_platform/backend/backend/copilot/response_model.py
@@ -54,6 +54,9 @@ class ResponseType(str, Enum):
HEARTBEAT = "heartbeat"
STATUS = "data-status"
CURSOR = "data-cursor"
+ # Dream/daydream pass snapshot — emitted from ``dream_events.py``.
+ # Wired into the orchestrator in P6 (surface dreams) + P9 (daydreaming).
+ DREAM_OPERATIONS = "data-dream-operations"
class StreamBaseResponse(BaseModel):
diff --git a/autogpt_platform/backend/backend/copilot/service.py b/autogpt_platform/backend/backend/copilot/service.py
index 2be390d12a..e8295121e9 100644
--- a/autogpt_platform/backend/backend/copilot/service.py
+++ b/autogpt_platform/backend/backend/copilot/service.py
@@ -25,6 +25,7 @@ from backend.data.understanding import (
format_understanding_for_prompt,
)
from backend.util.exceptions import NotAuthorizedError, NotFoundError
+from backend.util.llm.providers import call_provider_openai_compat_sync
from backend.util.settings import AppEnvironment, Settings
from .anthropic_rate_card import compute_anthropic_cost_usd
@@ -778,7 +779,16 @@ async def _generate_session_title(
# ``anthropic/claude-haiku-4-5`` would 400 without this strip.
title_model = _normalize_title_model_for_aux()
- response = await _get_aux_client().chat.completions.create(
+ # Route through the shared providers helper so future provider
+ # work (flex tier, new SDK upgrades, etc.) propagates here
+ # without a parallel migration. Pass the cached
+ # ``_get_aux_client()`` singleton (a Langfuse-wrapped
+ # AsyncOpenAI) so the title-gen span lands in the same trace
+ # tree as the originating chat turn AND the httpx connection
+ # pool stays warm across calls — building a fresh client per
+ # title would cost a TCP+TLS handshake every session.
+ response = await call_provider_openai_compat_sync(
+ client=_get_aux_client(),
model=title_model,
messages=[
{
@@ -792,7 +802,7 @@ async def _generate_session_title(
{"role": "user", "content": message[:500]}, # Limit input length
],
max_tokens=20,
- extra_body=extra_body,
+ extra_body=extra_body or None,
)
except Exception as e:
logger.warning(f"Failed to generate session title: {e}")
diff --git a/autogpt_platform/backend/backend/copilot/service_unit_test.py b/autogpt_platform/backend/backend/copilot/service_unit_test.py
index 8eb8d48879..9b87bc771b 100644
--- a/autogpt_platform/backend/backend/copilot/service_unit_test.py
+++ b/autogpt_platform/backend/backend/copilot/service_unit_test.py
@@ -516,6 +516,18 @@ class TestGenerateSessionTitle:
"""``_generate_session_title`` returns ``(title, response)`` — the
caller owns both the persist and the cost-record decisions."""
+ @pytest.fixture(autouse=True)
+ def _stub_aux_client(self):
+ """Every title-gen test mocks ``call_provider_openai_compat_sync``,
+ but ``_generate_session_title`` still calls ``_get_aux_client()``
+ before reaching the helper. Stub that out so tests don't try to
+ instantiate a real LangfuseAsyncOpenAI from test-env config."""
+ with patch(
+ "backend.copilot.service._get_aux_client",
+ return_value=MagicMock(name="aux_client_stub"),
+ ):
+ yield
+
@pytest.mark.asyncio
async def test_valid_response_returns_cleaned_title_and_response(self):
# Code strips whitespace, then strips ``"'`` — whitespace inside
@@ -523,11 +535,10 @@ class TestGenerateSessionTitle:
# better than ``MyAgent``). Test keeps the outer quotes + inner
# whitespace distinct so the ordering is pinned.
resp = _build_completion(content='"Clean Me" ')
- client = MagicMock()
- client.chat.completions.create = AsyncMock(return_value=resp)
+ helper = AsyncMock(return_value=resp)
with patch(
- "backend.copilot.service._get_aux_client",
- return_value=client,
+ "backend.copilot.service.call_provider_openai_compat_sync",
+ new=helper,
):
title, response = await _generate_session_title(
"first message", user_id="u", session_id="s"
@@ -540,11 +551,10 @@ class TestGenerateSessionTitle:
"""Titles >50 chars get truncated to 47 + '...'."""
long_title = "A" * 80
resp = _build_completion(content=long_title)
- client = MagicMock()
- client.chat.completions.create = AsyncMock(return_value=resp)
+ helper = AsyncMock(return_value=resp)
with patch(
- "backend.copilot.service._get_aux_client",
- return_value=client,
+ "backend.copilot.service.call_provider_openai_compat_sync",
+ new=helper,
):
title, _ = await _generate_session_title("x", user_id=None)
assert title is not None
@@ -557,11 +567,10 @@ class TestGenerateSessionTitle:
typing) must not raise IndexError. The response is preserved so
the caller can still record the paid-for cost."""
resp = _build_completion(choices=[])
- client = MagicMock()
- client.chat.completions.create = AsyncMock(return_value=resp)
+ helper = AsyncMock(return_value=resp)
with patch(
- "backend.copilot.service._get_aux_client",
- return_value=client,
+ "backend.copilot.service.call_provider_openai_compat_sync",
+ new=helper,
):
title, response = await _generate_session_title("write a sales email")
assert title == "write a sales email"
@@ -573,11 +582,10 @@ class TestGenerateSessionTitle:
but the response still lands on the caller."""
fake_choice = SimpleNamespace(message=None)
fake_response = SimpleNamespace(choices=[fake_choice])
- client = MagicMock()
- client.chat.completions.create = AsyncMock(return_value=fake_response)
+ helper = AsyncMock(return_value=fake_response)
with patch(
- "backend.copilot.service._get_aux_client",
- return_value=client,
+ "backend.copilot.service.call_provider_openai_compat_sync",
+ new=helper,
):
title, response = await _generate_session_title("summarize this document")
assert title == "summarize this document"
@@ -585,16 +593,13 @@ class TestGenerateSessionTitle:
@pytest.mark.asyncio
async def test_llm_call_raises_returns_fallback_title_and_no_response(self):
- """Network / API errors on the create call are swallowed and
- fallback to the first message without crashing the background
- task."""
- client = MagicMock()
- client.chat.completions.create = AsyncMock(
- side_effect=RuntimeError("connection reset")
- )
+ """Network / API errors on the dispatch call are swallowed and
+ the caller gets back the fallback title + a ``None`` response
+ so the background task doesn't crash."""
+ helper = AsyncMock(side_effect=RuntimeError("connection reset"))
with patch(
- "backend.copilot.service._get_aux_client",
- return_value=client,
+ "backend.copilot.service.call_provider_openai_compat_sync",
+ new=helper,
):
title, response = await _generate_session_title("build me an invoice tool")
assert title == "build me an invoice tool"
@@ -629,12 +634,11 @@ class TestGenerateSessionTitle:
real billed cost into the final usage chunk — only when the aux
transport is OR (Anthropic-direct rejects unknown extras)."""
resp = _build_completion(content="Title")
- client = MagicMock()
- client.chat.completions.create = AsyncMock(return_value=resp)
+ helper = AsyncMock(return_value=resp)
with (
patch(
- "backend.copilot.service._get_aux_client",
- return_value=client,
+ "backend.copilot.service.call_provider_openai_compat_sync",
+ new=helper,
),
patch(
"backend.copilot.service.config",
@@ -647,8 +651,8 @@ class TestGenerateSessionTitle:
await _generate_session_title(
"hello world", user_id="user-abc", session_id="sess-abc"
)
- client.chat.completions.create.assert_awaited_once()
- extra_body = client.chat.completions.create.await_args.kwargs["extra_body"]
+ helper.assert_awaited_once()
+ extra_body = helper.await_args.kwargs["extra_body"]
assert extra_body["usage"] == {"include": True}
assert extra_body["user"] == "user-abc"
assert extra_body["session_id"] == "sess-abc"
@@ -660,12 +664,11 @@ class TestGenerateSessionTitle:
``anthropic/`` prefix and dot-separated version stripped before
being sent — Anthropic's OpenAI-compat endpoint rejects both."""
resp = _build_completion(content="Title")
- client = MagicMock()
- client.chat.completions.create = AsyncMock(return_value=resp)
+ helper = AsyncMock(return_value=resp)
with (
patch(
- "backend.copilot.service._get_aux_client",
- return_value=client,
+ "backend.copilot.service.call_provider_openai_compat_sync",
+ new=helper,
),
patch(
"backend.copilot.service.config",
@@ -677,8 +680,8 @@ class TestGenerateSessionTitle:
),
):
await _generate_session_title("hello", user_id=None, session_id=None)
- client.chat.completions.create.assert_awaited_once()
- kwargs = client.chat.completions.create.await_args.kwargs
+ helper.assert_awaited_once()
+ kwargs = helper.await_args.kwargs
assert kwargs["model"] == "claude-haiku-4-5"
@pytest.mark.asyncio
@@ -686,12 +689,11 @@ class TestGenerateSessionTitle:
"""OpenRouter routes by full ``vendor/model`` slug — the
normalization branch must NOT fire for OR-routed aux."""
resp = _build_completion(content="Title")
- client = MagicMock()
- client.chat.completions.create = AsyncMock(return_value=resp)
+ helper = AsyncMock(return_value=resp)
with (
patch(
- "backend.copilot.service._get_aux_client",
- return_value=client,
+ "backend.copilot.service.call_provider_openai_compat_sync",
+ new=helper,
),
patch(
"backend.copilot.service.config",
@@ -703,22 +705,23 @@ class TestGenerateSessionTitle:
),
):
await _generate_session_title("hello", user_id=None, session_id=None)
- client.chat.completions.create.assert_awaited_once()
- kwargs = client.chat.completions.create.await_args.kwargs
+ helper.assert_awaited_once()
+ kwargs = helper.await_args.kwargs
assert kwargs["model"] == "anthropic/claude-haiku-4.5"
@pytest.mark.asyncio
async def test_create_omits_extra_body_when_aux_not_openrouter(self):
"""When aux client is pointed at a non-OR endpoint (e.g.
Anthropic OAI-compat), the OR-specific extras must not be sent
- — Anthropic's compat endpoint 400s on unknown fields."""
+ — Anthropic's compat endpoint 400s on unknown fields. The
+ helper normalizes empty dict to None so the kwarg drops off
+ the final SDK call entirely."""
resp = _build_completion(content="Title")
- client = MagicMock()
- client.chat.completions.create = AsyncMock(return_value=resp)
+ helper = AsyncMock(return_value=resp)
with (
patch(
- "backend.copilot.service._get_aux_client",
- return_value=client,
+ "backend.copilot.service.call_provider_openai_compat_sync",
+ new=helper,
),
patch(
"backend.copilot.service.config",
@@ -731,8 +734,6 @@ class TestGenerateSessionTitle:
await _generate_session_title(
"hello world", user_id="user-abc", session_id="sess-abc"
)
- client.chat.completions.create.assert_awaited_once()
- extra_body = client.chat.completions.create.await_args.kwargs["extra_body"]
- assert "usage" not in extra_body
- assert "user" not in extra_body
- assert "session_id" not in extra_body
+ helper.assert_awaited_once()
+ extra_body = helper.await_args.kwargs.get("extra_body")
+ assert extra_body is None
diff --git a/autogpt_platform/backend/backend/copilot/stream_registry.py b/autogpt_platform/backend/backend/copilot/stream_registry.py
index c79f6ee78b..1a4e13f420 100644
--- a/autogpt_platform/backend/backend/copilot/stream_registry.py
+++ b/autogpt_platform/backend/backend/copilot/stream_registry.py
@@ -38,6 +38,7 @@ from backend.data.redis_helpers import hash_compare_and_set
from .config import ChatConfig
from .constants import STREAM_LOCK_PREFIX
+from .dream_events import StreamDreamOperations
from .executor.utils import COPILOT_CONSUMER_TIMEOUT_SECONDS, get_session_lock_key
from .response_model import (
ResponseType,
@@ -1165,6 +1166,7 @@ def _reconstruct_chunk(chunk_data: dict) -> StreamBaseResponse | None:
ResponseType.USAGE.value: StreamUsage,
ResponseType.HEARTBEAT.value: StreamHeartbeat,
ResponseType.STATUS.value: StreamStatus,
+ ResponseType.DREAM_OPERATIONS.value: StreamDreamOperations,
}
chunk_type = chunk_data.get("type")
diff --git a/autogpt_platform/backend/backend/copilot/token_tracking.py b/autogpt_platform/backend/backend/copilot/token_tracking.py
index 274bfad19c..fb1322f51f 100644
--- a/autogpt_platform/backend/backend/copilot/token_tracking.py
+++ b/autogpt_platform/backend/backend/copilot/token_tracking.py
@@ -119,6 +119,11 @@ async def persist_and_record_usage(
cost_usd: float | str | None = None,
model: str | None = None,
provider: str = "open_router",
+ block_name_override: str | None = None,
+ extra_metadata: dict | None = None,
+ graph_exec_id_override: str | None = None,
+ skip_daily: bool = False,
+ execution_path: str = "sync",
) -> int:
"""Persist token usage to session and record generation cost for rate limiting.
@@ -222,6 +227,7 @@ async def persist_and_record_usage(
await record_cost_usage(
user_id=user_id,
cost_microdollars=cost_microdollars,
+ skip_daily=skip_daily,
)
# Log to PlatformCostLog for admin cost dashboard.
@@ -229,7 +235,11 @@ async def persist_and_record_usage(
# (e.g. fully-cached Anthropic responses where only cache tokens
# accumulate a charge without incrementing total_tokens).
if user_id and (total_tokens > 0 or cost_float is not None):
- session_id = session.session_id if session else None
+ session_id = (
+ graph_exec_id_override
+ if graph_exec_id_override is not None
+ else (session.session_id if session else None)
+ )
if cost_float is not None:
tracking_type = "cost_usd"
@@ -238,12 +248,35 @@ async def persist_and_record_usage(
tracking_type = "tokens"
tracking_amount = total_tokens
+ metadata: dict = {
+ "tracking_type": tracking_type,
+ "tracking_amount": tracking_amount,
+ "cache_read_tokens": cache_read_tokens,
+ "cache_creation_tokens": cache_creation_tokens,
+ "source": "copilot",
+ # Default to ``sync`` so every row gets a non-null tag —
+ # the admin cost-logs Path column previously rendered
+ # "—" for chat rows because nobody set this. Dream and any
+ # future batch/flex caller overrides via ``execution_path``
+ # arg (which lands in the base) or ``extra_metadata`` (which
+ # overrides the base — dream uses this path historically).
+ "execution_path": execution_path,
+ }
+ if extra_metadata:
+ # Caller-supplied keys override base keys (dream pass uses this
+ # to mark source="dream_pass"); base keys it doesn't touch stay.
+ metadata.update(extra_metadata)
+
_schedule_cost_log(
PlatformCostEntry(
user_id=user_id,
graph_exec_id=session_id,
block_id=COPILOT_BLOCK_ID,
- block_name=_copilot_block_name(log_prefix),
+ block_name=(
+ block_name_override
+ if block_name_override is not None
+ else _copilot_block_name(log_prefix)
+ ),
provider=provider,
credential_id=COPILOT_CREDENTIAL_ID,
cost_microdollars=cost_microdollars,
@@ -254,13 +287,7 @@ async def persist_and_record_usage(
model=model,
tracking_type=tracking_type,
tracking_amount=tracking_amount,
- metadata={
- "tracking_type": tracking_type,
- "tracking_amount": tracking_amount,
- "cache_read_tokens": cache_read_tokens,
- "cache_creation_tokens": cache_creation_tokens,
- "source": "copilot",
- },
+ metadata=metadata,
)
)
diff --git a/autogpt_platform/backend/backend/copilot/token_tracking_test.py b/autogpt_platform/backend/backend/copilot/token_tracking_test.py
index ff5957e1f5..6238bce7ab 100644
--- a/autogpt_platform/backend/backend/copilot/token_tracking_test.py
+++ b/autogpt_platform/backend/backend/copilot/token_tracking_test.py
@@ -229,6 +229,31 @@ class TestRateLimitRecording:
mock_record.assert_awaited_once_with(
user_id="user-abc",
cost_microdollars=12_300,
+ skip_daily=False,
+ )
+
+ @pytest.mark.asyncio
+ async def test_skip_daily_flag_propagates_to_record_cost_usage(self):
+ """Dream pass passes ``skip_daily=True`` so background spend doesn't
+ eat the user's interactive daily cap. Threading must reach
+ ``record_cost_usage`` unchanged."""
+ mock_record = AsyncMock()
+ with patch(
+ "backend.copilot.token_tracking.record_cost_usage",
+ new=mock_record,
+ ):
+ await persist_and_record_usage(
+ session=None,
+ user_id="user-abc",
+ prompt_tokens=100,
+ completion_tokens=50,
+ cost_usd=0.0123,
+ skip_daily=True,
+ )
+ mock_record.assert_awaited_once_with(
+ user_id="user-abc",
+ cost_microdollars=12_300,
+ skip_daily=True,
)
@pytest.mark.asyncio
diff --git a/autogpt_platform/backend/backend/copilot/tools/graphiti_forget.py b/autogpt_platform/backend/backend/copilot/tools/graphiti_forget.py
index c3a30a583e..d3196e2693 100644
--- a/autogpt_platform/backend/backend/copilot/tools/graphiti_forget.py
+++ b/autogpt_platform/backend/backend/copilot/tools/graphiti_forget.py
@@ -5,7 +5,8 @@ Step 2 (memory_forget_confirm): delete specific edges by UUID after user confirm
"""
import logging
-from typing import Any
+from datetime import datetime, timezone
+from typing import Any, Literal
from backend.copilot.graphiti._format import extract_fact, extract_temporal_validity
from backend.copilot.graphiti.client import derive_group_id, get_graphiti_client
@@ -20,6 +21,20 @@ from .models import (
ToolResponseBase,
)
+
+def _now_iso() -> str:
+ """Current UTC time as an ISO-8601 string for Cypher parameter binding.
+
+ FalkorDB does not implement Cypher's no-arg ``datetime()`` function
+ (the error is ``Unknown function 'datetime'``), so timestamp values
+ have to be generated in Python and passed as a parameter. ISO
+ strings work for the comparison + ordering we use (lexical sort on
+ ISO-8601 matches chronological sort) and round-trip cleanly through
+ ``toString(...)`` reads we already do.
+ """
+ return datetime.now(timezone.utc).isoformat()
+
+
logger = logging.getLogger(__name__)
@@ -237,8 +252,12 @@ class MemoryForgetConfirmTool(BaseTool):
deleted, failed = await _hard_delete_edges(driver, uuids, user_id)
mode = "permanently deleted"
else:
- deleted, failed = await _soft_delete_edges(driver, uuids, user_id)
- mode = "invalidated"
+ # User-initiated forget is a *system* retraction, not a world
+ # change. Per Snodgrass bi-temporal semantics, only `expired_at`
+ # is set. `_soft_delete_edges` (which also sets `invalid_at`)
+ # is reserved for the contradiction detector.
+ deleted, failed = await _retract_edges(driver, uuids, user_id)
+ mode = "retracted from memory"
return MemoryForgetConfirmResponse(
message=(
@@ -251,16 +270,22 @@ class MemoryForgetConfirmTool(BaseTool):
)
-async def _soft_delete_edges(
+async def _retract_edges(
driver, uuids: list[str], user_id: str
) -> tuple[list[str], list[str]]:
- """Temporal invalidation — mark edges as expired without removing them.
+ """System retraction — set ONLY ``expired_at`` on the edge.
+
+ Per Snodgrass bi-temporal semantics (see ``dream/dreaming-graphiti.md``
+ §6.13), ``expired_at`` is *transaction time* ("we retracted the
+ record") and ``invalid_at`` is *valid time* ("the world changed").
+ User-initiated forget, dream demotion, and entity invalidation are
+ all system retractions and must NOT set ``invalid_at``.
- Sets ``invalid_at`` and ``expired_at`` to now, which excludes them
- from default search results while preserving history.
+ For contradiction detection (the world really did change) use
+ ``_soft_delete_edges`` below, which sets both.
Matches the same edge types as ``_hard_delete_edges`` so that edges of
- any type (RELATES_TO, MENTIONS, HAS_MEMBER) can be soft-deleted.
+ any type (RELATES_TO, MENTIONS, HAS_MEMBER) can be retracted.
"""
deleted = []
failed = []
@@ -269,11 +294,53 @@ async def _soft_delete_edges(
records, _, _ = await driver.execute_query(
"""
MATCH ()-[e:MENTIONS|RELATES_TO|HAS_MEMBER {uuid: $uuid}]->()
- SET e.invalid_at = datetime(),
- e.expired_at = datetime()
+ SET e.expired_at = $now
RETURN e.uuid AS uuid
""",
uuid=uuid,
+ now=_now_iso(),
+ )
+ if records:
+ deleted.append(uuid)
+ else:
+ failed.append(uuid)
+ except Exception:
+ logger.warning(
+ "Failed to retract edge %s for user %s",
+ uuid,
+ user_id[:12],
+ exc_info=True,
+ )
+ failed.append(uuid)
+ return deleted, failed
+
+
+async def _soft_delete_edges(
+ driver, uuids: list[str], user_id: str
+) -> tuple[list[str], list[str]]:
+ """Bi-temporal invalidation — mark edges as both expired AND invalid.
+
+ Reserved for the *contradiction detector*: when new evidence proves
+ a fact ceased being true in the world, set ``invalid_at`` (valid time)
+ in addition to ``expired_at`` (transaction time). User-initiated
+ forget should use ``_retract_edges`` instead; conflating the two
+ breaks the bi-temporal model (audit §6.13).
+
+ Matches RELATES_TO, MENTIONS, HAS_MEMBER edges.
+ """
+ deleted = []
+ failed = []
+ for uuid in uuids:
+ try:
+ records, _, _ = await driver.execute_query(
+ """
+ MATCH ()-[e:MENTIONS|RELATES_TO|HAS_MEMBER {uuid: $uuid}]->()
+ SET e.invalid_at = $now,
+ e.expired_at = $now
+ RETURN e.uuid AS uuid
+ """,
+ uuid=uuid,
+ now=_now_iso(),
)
if records:
deleted.append(uuid)
@@ -290,6 +357,119 @@ async def _soft_delete_edges(
return deleted, failed
+async def mark_edges_superseded(
+ driver,
+ uuids: list[str],
+ reason: str,
+ new_status: Literal["superseded", "contradicted"] = "superseded",
+ user_id: str | None = None,
+ group_id: str | None = None,
+) -> tuple[list[str], list[str]]:
+ """Retract edges AND set the custom audit-trail ``status`` property.
+
+ Intended for the dream pass (P0.3 stale-fact deprecation): retract
+ the edge per ``_retract_edges`` semantics and stamp
+ ``status='superseded'`` (or ``'contradicted'``) plus
+ ``expiration_reason=<reason>`` so the demotion is queryable from
+ search (``WHERE e.status = 'superseded'``).
+
+ ``group_id`` adds defense-in-depth: the driver is normally opened
+ against the per-user FalkorDB database, but when provided the
+ Cypher predicate also requires the edge's ``group_id`` to match so
+ a future caller holding the wrong driver can't touch another
+ user's edges. ``None`` keeps the unscoped match (current
+ ratification behavior).
+
+ Returns ``(succeeded_uuids, failed_uuids)``.
+ """
+ deleted = []
+ failed = []
+ user_log = (user_id or "?")[:12]
+ edge_match = (
+ "MATCH ()-[e:RELATES_TO {uuid: $uuid, group_id: $group_id}]->()"
+ if group_id is not None
+ else "MATCH ()-[e:RELATES_TO {uuid: $uuid}]->()"
+ )
+ query = f"""
+ {edge_match}
+ SET e.expired_at = $now,
+ e.status = $new_status,
+ e.expiration_reason = $reason
+ RETURN e.uuid AS uuid
+ """
+ for uuid in uuids:
+ try:
+ params: dict[str, str] = {
+ "uuid": uuid,
+ "new_status": new_status,
+ "reason": reason,
+ "now": _now_iso(),
+ }
+ if group_id is not None:
+ params["group_id"] = group_id
+ records, _, _ = await driver.execute_query(query, **params)
+ if records:
+ deleted.append(uuid)
+ else:
+ failed.append(uuid)
+ except Exception:
+ logger.warning(
+ "Failed to mark edge %s superseded for user %s",
+ uuid,
+ user_log,
+ exc_info=True,
+ )
+ failed.append(uuid)
+ return deleted, failed
+
+
+async def invalidate_entity_direct_neighbors(
+ driver,
+ group_id: str,
+ entity_uuid: str,
+ reason: str,
+) -> list[str]:
+ """Demote every ``:RELATES_TO`` edge directly attached to an entity.
+
+ **Single-hop only** — does NOT propagate to neighbors-of-neighbors.
+ The instinct to write ``[r:RELATES_TO*1..N]`` is exactly the
+ runaway-demotion bug we are protecting against (P0.3b in the dream
+ spec). Keep the single-hop discipline; ratification (P0.4) re-promotes
+ good facts that get caught in the cascade.
+
+ Returns the list of edge UUIDs that were demoted. ``DISTINCT``
+ matters: the undirected ``-[r]-`` pattern can yield the same edge
+ from both traversal directions, and duplicate uuids inflate the
+ demotion counts reported in ``DreamPassResult`` / the admin UI
+ (the ``SET`` itself is idempotent).
+ """
+ query = """
+ MATCH (e:Entity {uuid: $entity_uuid, group_id: $group_id})
+ MATCH (e)-[r:RELATES_TO]-(other)
+ SET r.expired_at = $now,
+ r.status = 'superseded',
+ r.expiration_reason = $reason
+ RETURN DISTINCT r.uuid AS edge_uuid
+ """
+ try:
+ records, _, _ = await driver.execute_query(
+ query,
+ entity_uuid=entity_uuid,
+ group_id=group_id,
+ reason=reason,
+ now=_now_iso(),
+ )
+ return [r["edge_uuid"] for r in records]
+ except Exception:
+ logger.warning(
+ "Failed to invalidate direct neighbors of entity %s in group %s",
+ entity_uuid,
+ group_id,
+ exc_info=True,
+ )
+ return []
+
+
async def _hard_delete_edges(
driver, uuids: list[str], user_id: str
) -> tuple[list[str], list[str]]:
diff --git a/autogpt_platform/backend/backend/copilot/tools/graphiti_forget_test.py b/autogpt_platform/backend/backend/copilot/tools/graphiti_forget_test.py
index 94bbeb5d4f..3ea13e6960 100644
--- a/autogpt_platform/backend/backend/copilot/tools/graphiti_forget_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/graphiti_forget_test.py
@@ -4,7 +4,13 @@ from unittest.mock import AsyncMock
import pytest
-from backend.copilot.tools.graphiti_forget import _hard_delete_edges, _soft_delete_edges
+from backend.copilot.tools.graphiti_forget import (
+ _hard_delete_edges,
+ _retract_edges,
+ _soft_delete_edges,
+ invalidate_entity_direct_neighbors,
+ mark_edges_superseded,
+)
class TestSoftDeleteOverReportsSuccess:
@@ -75,3 +81,187 @@ class TestHardDeleteBasicFlow:
assert failed == ["nonexistent-uuid"]
# Only the delete query should run — cleanup skipped
assert driver.execute_query.call_count == 1
+
+
+class TestRetractEdgesSnodgrass:
+ """`_retract_edges` is the system-retraction soft delete — must set
+ ONLY `expired_at`, never `invalid_at`. Conflating the two breaks the
+ bi-temporal model (see graphiti audit §6.13)."""
+
+ @pytest.mark.asyncio
+ async def test_retract_sets_only_expired_at(self) -> None:
+ driver = AsyncMock()
+ driver.execute_query.return_value = ([{"uuid": "u1"}], None, None)
+
+ await _retract_edges(driver, ["u1"], "test-user")
+
+ query = driver.execute_query.call_args.args[0]
+ assert "e.expired_at = $now" in query
+ # ``now`` parameter is bound from Python (FalkorDB doesn't
+ # implement Cypher's no-arg ``datetime()``).
+ assert "now" in driver.execute_query.call_args.kwargs
+ # Critical contract: must NOT touch invalid_at
+ assert "invalid_at" not in query
+
+ @pytest.mark.asyncio
+ async def test_retract_reports_failure_on_no_match(self) -> None:
+ driver = AsyncMock()
+ driver.execute_query.return_value = ([], None, None)
+
+ deleted, failed = await _retract_edges(driver, ["missing"], "test-user")
+ assert deleted == []
+ assert failed == ["missing"]
+
+
+class TestSoftDeleteContradictionPath:
+ """`_soft_delete_edges` is reserved for the contradiction detector
+ and MUST still set both expired_at AND invalid_at."""
+
+ @pytest.mark.asyncio
+ async def test_soft_delete_sets_both_timestamps(self) -> None:
+ driver = AsyncMock()
+ driver.execute_query.return_value = ([{"uuid": "u1"}], None, None)
+
+ await _soft_delete_edges(driver, ["u1"], "test-user")
+
+ query = driver.execute_query.call_args.args[0]
+ assert "e.invalid_at = $now" in query
+ assert "e.expired_at = $now" in query
+ # ``now`` parameter is bound from Python (FalkorDB doesn't
+ # implement Cypher's no-arg ``datetime()``).
+ assert "now" in driver.execute_query.call_args.kwargs
+
+
+class TestMarkEdgesSuperseded:
+ @pytest.mark.asyncio
+ async def test_sets_status_and_reason(self) -> None:
+ driver = AsyncMock()
+ driver.execute_query.return_value = ([{"uuid": "u1"}], None, None)
+
+ deleted, failed = await mark_edges_superseded(
+ driver,
+ ["u1"],
+ reason="stale_fact",
+ new_status="superseded",
+ user_id="abc",
+ )
+
+ assert deleted == ["u1"]
+ assert failed == []
+ call_kwargs = driver.execute_query.call_args.kwargs
+ assert call_kwargs["new_status"] == "superseded"
+ assert call_kwargs["reason"] == "stale_fact"
+ query = driver.execute_query.call_args.args[0]
+ assert "e.status = $new_status" in query
+ assert "e.expiration_reason = $reason" in query
+ assert "e.expired_at = $now" in query
+ # ``now`` parameter is bound from Python (FalkorDB doesn't
+ # implement Cypher's no-arg ``datetime()``).
+ assert "now" in driver.execute_query.call_args.kwargs
+
+ @pytest.mark.asyncio
+ async def test_default_status_is_superseded(self) -> None:
+ driver = AsyncMock()
+ driver.execute_query.return_value = ([{"uuid": "u1"}], None, None)
+ await mark_edges_superseded(driver, ["u1"], reason="x")
+ assert driver.execute_query.call_args.kwargs["new_status"] == "superseded"
+
+ @pytest.mark.asyncio
+ async def test_contradicted_status_supported(self) -> None:
+ driver = AsyncMock()
+ driver.execute_query.return_value = ([{"uuid": "u1"}], None, None)
+ await mark_edges_superseded(
+ driver, ["u1"], reason="x", new_status="contradicted"
+ )
+ assert driver.execute_query.call_args.kwargs["new_status"] == "contradicted"
+
+ @pytest.mark.asyncio
+ async def test_group_id_scopes_the_match_predicate(self) -> None:
+ """Defense-in-depth: when the caller supplies group_id, the Cypher
+ MATCH must require it alongside the uuid so a wrong-driver caller
+ can't touch another user's edges."""
+ driver = AsyncMock()
+ driver.execute_query.return_value = ([{"uuid": "u1"}], None, None)
+
+ deleted, failed = await mark_edges_superseded(
+ driver,
+ ["u1"],
+ reason="stale_fact",
+ user_id="abc",
+ group_id="user_abc",
+ )
+
+ assert deleted == ["u1"]
+ assert failed == []
+ query = driver.execute_query.call_args.args[0]
+ assert "{uuid: $uuid, group_id: $group_id}" in query
+ assert driver.execute_query.call_args.kwargs["group_id"] == "user_abc"
+
+ @pytest.mark.asyncio
+ async def test_no_group_id_keeps_unscoped_match_for_ratification(self) -> None:
+ """Omitting group_id preserves the original uuid-only predicate —
+ ratification.py still calls without it (per-group driver), so the
+ param must stay optional and default to no group filter."""
+ driver = AsyncMock()
+ driver.execute_query.return_value = ([{"uuid": "u1"}], None, None)
+
+ await mark_edges_superseded(driver, ["u1"], reason="unratified")
+
+ query = driver.execute_query.call_args.args[0]
+ assert "{uuid: $uuid}" in query
+ assert "group_id" not in query
+ assert "group_id" not in driver.execute_query.call_args.kwargs
+
+
+class TestInvalidateEntityDirectNeighbors:
+ """Single-hop demotion. The instinct to write [r:RELATES_TO*1..N] is
+ exactly the runaway-demotion bug. This test pins single-hop discipline."""
+
+ @pytest.mark.asyncio
+ async def test_single_hop_pattern_in_cypher(self) -> None:
+ driver = AsyncMock()
+ driver.execute_query.return_value = (
+ [{"edge_uuid": "e1"}, {"edge_uuid": "e2"}],
+ None,
+ None,
+ )
+
+ result = await invalidate_entity_direct_neighbors(
+ driver, group_id="user_x", entity_uuid="entity-1", reason="dead_client"
+ )
+
+ assert result == ["e1", "e2"]
+ query = driver.execute_query.call_args.args[0]
+ # MUST be single-hop: bare relationship, no quantifier
+ assert "[r:RELATES_TO]" in query
+ # MUST NOT be multi-hop: variable-length pattern would propagate
+ assert "*1.." not in query
+ assert "*0.." not in query
+ # MUST set status + reason for audit trail
+ assert "r.status = 'superseded'" in query
+ assert "r.expiration_reason = $reason" in query
+
+ @pytest.mark.asyncio
+ async def test_returns_distinct_edge_uuids(self) -> None:
+ """The undirected -[r]- pattern can yield the same edge from both
+ traversal directions; without DISTINCT the duplicate uuids inflate
+ the demotion counts in DreamPassResult / the admin UI."""
+ driver = AsyncMock()
+ driver.execute_query.return_value = ([{"edge_uuid": "e1"}], None, None)
+
+ await invalidate_entity_direct_neighbors(
+ driver, group_id="user_x", entity_uuid="entity-1", reason="dup_check"
+ )
+
+ query = driver.execute_query.call_args.args[0]
+ assert "RETURN DISTINCT r.uuid AS edge_uuid" in query
+
+ @pytest.mark.asyncio
+ async def test_returns_empty_on_error(self) -> None:
+ driver = AsyncMock()
+ driver.execute_query.side_effect = RuntimeError("boom")
+
+ result = await invalidate_entity_direct_neighbors(
+ driver, group_id="user_x", entity_uuid="entity-1", reason="x"
+ )
+ assert result == []
diff --git a/autogpt_platform/backend/backend/copilot/tools/graphiti_store.py b/autogpt_platform/backend/backend/copilot/tools/graphiti_store.py
index 3112820e54..08887d42cb 100644
--- a/autogpt_platform/backend/backend/copilot/tools/graphiti_store.py
+++ b/autogpt_platform/backend/backend/copilot/tools/graphiti_store.py
@@ -4,7 +4,7 @@ import logging
from typing import Any
from backend.copilot.graphiti.config import is_enabled_for_user
-from backend.copilot.graphiti.ingest import enqueue_episode
+from backend.copilot.graphiti.ingest import MAX_EPISODE_BODY_BYTES, enqueue_episode
from backend.copilot.graphiti.memory_model import (
MemoryEnvelope,
MemoryKind,
@@ -214,22 +214,51 @@ class MemoryStoreTool(BaseTool):
except ValueError:
resolved_kind = MemoryKind.fact
+ # Richer provenance grain so the ratification loop can find the
+ # originating message, not just the originating session
+ # (audit §6.12 / §6.15 #6). The latest message in the session
+ # is the user turn that triggered the tool call.
+ latest_seq: int | None = None
+ if session.messages:
+ latest_seq = session.messages[-1].sequence
+ if latest_seq is not None:
+ provenance = f"session:{session.session_id}#msg:{latest_seq}"
+ else:
+ provenance = f"session:{session.session_id}"
+
envelope = MemoryEnvelope(
content=content,
source_kind=resolved_source,
scope=scope,
memory_kind=resolved_kind,
status=MemoryStatus.active,
- provenance=session.session_id,
+ provenance=provenance,
rule=rule_model,
procedure=procedure_model,
)
+ episode_body = envelope.model_dump_json()
+
+ # ``enqueue_episode`` returns False for BOTH the oversized-body
+ # rejection (permanent) and a full queue (transient). Pre-check
+ # the size here so the LLM gets an actionable, non-retryable
+ # message instead of the retryable queue-full one — retrying an
+ # oversized store_memory call can never succeed.
+ if len(episode_body.encode("utf-8")) > MAX_EPISODE_BODY_BYTES:
+ return ErrorResponse(
+ message=(
+ "Memory content is too large to store. Do not retry with "
+ "the same content — split it into smaller, more focused "
+ "memories and store each one separately."
+ ),
+ session_id=session.session_id,
+ )
+
queued = await enqueue_episode(
user_id,
session.session_id,
name=name,
- episode_body=envelope.model_dump_json(),
+ episode_body=episode_body,
source_description=source_description,
is_json=True,
)
diff --git a/autogpt_platform/backend/backend/copilot/tools/graphiti_store_test.py b/autogpt_platform/backend/backend/copilot/tools/graphiti_store_test.py
index 21224d39c0..e222ac92bf 100644
--- a/autogpt_platform/backend/backend/copilot/tools/graphiti_store_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/graphiti_store_test.py
@@ -6,6 +6,7 @@ from unittest.mock import AsyncMock, patch
import pytest
+from backend.copilot.graphiti.ingest import MAX_EPISODE_BODY_BYTES
from backend.copilot.model import ChatSession
from backend.copilot.tools.graphiti_store import MemoryStoreTool
from backend.copilot.tools.models import ErrorResponse, MemoryStoreResponse
@@ -263,7 +264,7 @@ class TestMemoryStoreTool:
assert envelope["memory_kind"] == "rule"
@pytest.mark.asyncio
- async def test_store_queue_full_returns_error(self):
+ async def test_store_queue_full_returns_retryable_error(self):
tool = MemoryStoreTool()
session = _make_session()
@@ -288,6 +289,77 @@ class TestMemoryStoreTool:
assert isinstance(result, ErrorResponse)
assert "queue" in result.message.lower()
+ assert "try again" in result.message.lower()
+
+ @pytest.mark.asyncio
+ async def test_store_oversized_content_returns_split_guidance_without_enqueueing(
+ self,
+ ):
+ """An envelope over the 64KB ingest cap is a permanent rejection.
+ The tool must tell the LLM to split the content — not surface the
+ retryable queue-full message that invites an identical retry —
+ and must never hand the oversized body to the ingest queue."""
+ tool = MemoryStoreTool()
+ session = _make_session()
+
+ mock_enqueue = AsyncMock()
+
+ with (
+ patch(
+ "backend.copilot.tools.graphiti_store.is_enabled_for_user",
+ new_callable=AsyncMock,
+ return_value=True,
+ ),
+ patch(
+ "backend.copilot.tools.graphiti_store.enqueue_episode",
+ mock_enqueue,
+ ),
+ ):
+ result = await tool._execute(
+ user_id="user-1",
+ session=session,
+ name="giant_memory",
+ content="x" * (MAX_EPISODE_BODY_BYTES + 1),
+ )
+
+ assert isinstance(result, ErrorResponse)
+ assert "too large" in result.message.lower()
+ assert "split" in result.message.lower()
+ assert "queue" not in result.message.lower()
+ assert "try again" not in result.message.lower()
+ mock_enqueue.assert_not_awaited()
+
+ @pytest.mark.asyncio
+ async def test_store_size_check_measures_full_envelope_not_just_content(self):
+ """The cap applies to the serialized MemoryEnvelope (what is
+ actually enqueued), so content just under the cap is still
+ rejected once the envelope's metadata pushes it over."""
+ tool = MemoryStoreTool()
+ session = _make_session()
+
+ mock_enqueue = AsyncMock()
+
+ with (
+ patch(
+ "backend.copilot.tools.graphiti_store.is_enabled_for_user",
+ new_callable=AsyncMock,
+ return_value=True,
+ ),
+ patch(
+ "backend.copilot.tools.graphiti_store.enqueue_episode",
+ mock_enqueue,
+ ),
+ ):
+ result = await tool._execute(
+ user_id="user-1",
+ session=session,
+ name="barely_oversized_memory",
+ content="x" * (MAX_EPISODE_BODY_BYTES - 10),
+ )
+
+ assert isinstance(result, ErrorResponse)
+ assert "too large" in result.message.lower()
+ mock_enqueue.assert_not_awaited()
@pytest.mark.asyncio
async def test_store_with_scope(self):
diff --git a/autogpt_platform/backend/backend/copilot/transport_routing.py b/autogpt_platform/backend/backend/copilot/transport_routing.py
new file mode 100644
index 0000000000..9ebe283712
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/transport_routing.py
@@ -0,0 +1,115 @@
+"""Map the active ChatConfig transport to ``call_provider`` kwargs.
+
+Single source of truth for any non-chat caller (dream pass, graphiti
+memory, future scheduled batch jobs) that needs to dispatch an LLM
+call through ``backend.util.llm.providers.call_provider``. Combines
+the *static* identity baked into the active ``TransportProfile``
+(``dispatch_provider``, ``supports_flex_tier``, ``cost_log_provider``)
+with the *runtime* credentials carried by ``ChatConfig`` + ``Settings``
+so call sites don't have to dual-read.
+
+Holy-grail design: the per-transport routing table lives on
+``TransportProfile`` itself; this module just resolves credentials.
+Adding a fifth transport (e.g. ``"vllm"`` or ``"lm_studio"``) means
+"add a row to ``_TRANSPORT_PROFILES``" — no edit here required as
+long as the resolution falls back through ``CHAT_API_KEY`` / Settings.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from pydantic import BaseModel, ConfigDict
+
+from backend.util.llm.providers import ProviderLiteral
+
+logger = logging.getLogger(__name__)
+
+
+class ProviderRoutingKwargs(BaseModel):
+ """Kwargs to pass through to ``call_provider`` for the active transport.
+
+ ``provider`` / ``api_key`` / ``base_url`` map 1:1 to ``call_provider``
+ parameters. ``supports_flex`` and ``cost_log_provider`` are carried
+ along as hints for callers that decide *whether* to ask for flex or
+ what label to write on a ``PlatformCostLog`` row.
+
+ Returned by ``routing_kwargs_for_chat_transport`` — never construct
+ directly; the constructor is plumbing, not an API surface. Frozen
+ Pydantic model per the backend architecture rule
+ (``util/architecture_test.py::test_backend_uses_pydantic_not_dataclasses``).
+ """
+
+ model_config = ConfigDict(frozen=True)
+
+ provider: ProviderLiteral
+ api_key: str
+ base_url: str | None
+ supports_flex: bool
+ cost_log_provider: str
+
+
+def routing_kwargs_for_chat_transport() -> ProviderRoutingKwargs:
+ """Resolve the right ``call_provider`` kwargs for the active transport.
+
+ Reads ``ChatConfig.transport`` (the cached singleton in
+ ``copilot.sdk.env``) for the static identity, then resolves the
+ matching credential field. Lazy imports both ``chat_cfg`` and
+ ``Settings`` to avoid the ``copilot.sdk.env`` ↔ ``util.clients``
+ import cycle dev's PR #12993 already established.
+
+ Runtime credential resolution:
+
+ - ``local`` — Ollama's bearer token is a placeholder (any non-empty
+ string works), so we take it from ``chat_cfg.api_key`` whether
+ the operator set it explicitly or not. ``base_url`` is the
+ ``CHAT_BASE_URL`` value the operator pointed at the local
+ backend (e.g. ``http://localhost:11434/v1``).
+ - ``subscription`` / ``direct_anthropic`` — both dispatch through
+ the Messages API. Subscription users have an OAuth token that
+ can't be used for direct API calls (see
+ ``docs/platform/copilot-local-llm.md`` for the rationale + the
+ Anthropic Feb-2026 ToS update), so they need
+ ``ANTHROPIC_API_KEY`` separately. ``direct_anthropic`` callers
+ may have ``chat.direct_anthropic_api_key`` set independently.
+ - ``openrouter`` — the canonical cloud path. Pulls from
+ ``chat_cfg.api_key`` first (operator may have set it directly),
+ then ``settings.secrets.open_router_api_key`` (platform-wide).
+
+ ``api_key`` may be the empty string when no credential is
+ configured — callers must surface a friendly error before
+ invoking ``call_provider`` (which would otherwise 401 with an
+ opaque message). For ``local`` an empty key is fine (Ollama
+ doesn't validate it).
+ """
+ # Lazy import: ``copilot.sdk.env`` instantiates ``ChatConfig`` at
+ # import time, which runs the full validator chain; importing it at
+ # module scope would force every consumer of this helper into the
+ # same boot path even when they only need the dataclass.
+ from backend.copilot.sdk.env import config as chat_cfg
+ from backend.util.settings import Settings
+
+ settings = Settings()
+ transport = chat_cfg.transport
+
+ if transport.name == "local":
+ api_key = chat_cfg.api_key or ""
+ base_url = chat_cfg.base_url
+ elif transport.name in ("subscription", "direct_anthropic"):
+ api_key = (
+ chat_cfg.direct_anthropic_api_key
+ or settings.secrets.anthropic_api_key
+ or ""
+ )
+ base_url = None
+ else: # "openrouter"
+ api_key = chat_cfg.api_key or settings.secrets.open_router_api_key or ""
+ base_url = None
+
+ return ProviderRoutingKwargs(
+ provider=transport.dispatch_provider,
+ api_key=api_key,
+ base_url=base_url,
+ supports_flex=transport.supports_flex_tier,
+ cost_log_provider=transport.cost_log_provider,
+ )
diff --git a/autogpt_platform/backend/backend/copilot/transport_routing_test.py b/autogpt_platform/backend/backend/copilot/transport_routing_test.py
new file mode 100644
index 0000000000..b7b267d5b4
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/transport_routing_test.py
@@ -0,0 +1,300 @@
+"""Unit tests for ``transport_routing.routing_kwargs_for_chat_transport``.
+
+Each test wires up a fresh ``ChatConfig`` and ``Settings`` and asserts
+that the resolved ``ProviderRoutingKwargs`` matches the active
+``TransportProfile`` row plus the right runtime credential. These
+pin the integration boundary between dev's transport machinery
+(#12993) and our centralized ``util/llm/providers.py::call_provider``,
+so regressions in either side surface immediately.
+"""
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from backend.copilot.config import ChatConfig
+from backend.copilot.transport_routing import (
+ ProviderRoutingKwargs,
+ routing_kwargs_for_chat_transport,
+)
+
+# Same env-cleanup pattern as ``config_test.py`` — leftover ``CHAT_*`` /
+# ``*_API_KEY`` env vars in the developer or CI environment would flip
+# transport resolution and break these tests deterministically.
+_ENV_VARS_TO_CLEAR = (
+ "CHAT_USE_OPENROUTER",
+ "CHAT_USE_CLAUDE_CODE_SUBSCRIPTION",
+ "CHAT_USE_LOCAL",
+ "CHAT_API_KEY",
+ "CHAT_BASE_URL",
+ "CHAT_DIRECT_ANTHROPIC_API_KEY",
+ "OPEN_ROUTER_API_KEY",
+ "OPENAI_API_KEY",
+ "ANTHROPIC_API_KEY",
+)
+
+
[email protected](autouse=True)
+def _clean_env(monkeypatch: pytest.MonkeyPatch) -> None:
+ for var in _ENV_VARS_TO_CLEAR:
+ monkeypatch.delenv(var, raising=False)
+
+
+def _patch_chat_cfg(monkeypatch: pytest.MonkeyPatch, cfg: ChatConfig) -> None:
+ """Swap the module-level ``copilot.sdk.env.config`` for a test config.
+
+ The helper imports ``chat_cfg`` lazily inside
+ ``routing_kwargs_for_chat_transport``, so we patch the singleton
+ directly instead of monkeypatching the function-local name.
+ """
+ from backend.copilot.sdk import env
+
+ monkeypatch.setattr(env, "config", cfg)
+
+
+def _patch_settings(monkeypatch: pytest.MonkeyPatch, **secrets) -> None:
+ """Patch ``backend.util.settings.Settings`` to expose the given secrets.
+
+ Only the fields the helper reads (``anthropic_api_key``,
+ ``open_router_api_key``) need to be set per-test.
+ """
+ from backend.util import settings as settings_mod
+
+ fake_secrets = MagicMock()
+ fake_secrets.anthropic_api_key = secrets.get("anthropic_api_key", "")
+ fake_secrets.open_router_api_key = secrets.get("open_router_api_key", "")
+ fake_settings = MagicMock()
+ fake_settings.secrets = fake_secrets
+ monkeypatch.setattr(settings_mod, "Settings", lambda: fake_settings)
+
+
+class TestLocalTransport:
+ """Local transport routes through Ollama. ``api_key`` and
+ ``base_url`` come from ``chat_cfg`` directly — no fallback to
+ Settings since local has ``api_key_fallback_envs=()``."""
+
+ def test_local_routing_kwargs(self, monkeypatch: pytest.MonkeyPatch):
+ cfg = ChatConfig(
+ use_local=True,
+ api_key="ollama-placeholder",
+ base_url="http://localhost:11434/v1",
+ )
+ _patch_chat_cfg(monkeypatch, cfg)
+ _patch_settings(monkeypatch)
+
+ result = routing_kwargs_for_chat_transport()
+
+ assert result == ProviderRoutingKwargs(
+ provider="ollama",
+ api_key="ollama-placeholder",
+ base_url="http://localhost:11434/v1",
+ supports_flex=False,
+ cost_log_provider="ollama",
+ )
+
+ def test_local_with_empty_api_key_is_still_valid(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ """Ollama doesn't validate the bearer token, so an empty
+ ``api_key`` is acceptable. The helper returns ``""`` and the
+ ``call_provider`` ollama branch ignores it."""
+ # ChatConfig validates that ``CHAT_API_KEY`` is non-empty under
+ # local, so the operator must set *something* — we mimic the
+ # "minimal placeholder" case the docs recommend.
+ cfg = ChatConfig(
+ use_local=True,
+ api_key="x",
+ base_url="http://h:11434/v1",
+ )
+ _patch_chat_cfg(monkeypatch, cfg)
+ _patch_settings(monkeypatch)
+
+ result = routing_kwargs_for_chat_transport()
+ assert result.provider == "ollama"
+ assert result.base_url == "http://h:11434/v1"
+ assert result.supports_flex is False
+
+
+class TestOpenRouterTransport:
+ """OpenRouter is the canonical cloud path. Reads
+ ``settings.secrets.open_router_api_key`` when ``chat_cfg.api_key``
+ is unset; ``base_url`` is left ``None`` so ``call_provider``'s
+ OpenRouter branch uses its baked-in ``OPENROUTER_BASE_URL``."""
+
+ def test_openrouter_with_chat_api_key(self, monkeypatch: pytest.MonkeyPatch):
+ cfg = ChatConfig(
+ use_openrouter=True,
+ api_key="or-key-from-chat-config",
+ base_url="https://openrouter.ai/api/v1",
+ )
+ _patch_chat_cfg(monkeypatch, cfg)
+ _patch_settings(monkeypatch, open_router_api_key="or-key-from-secrets")
+
+ result = routing_kwargs_for_chat_transport()
+ # chat_cfg.api_key wins over secrets.
+ assert result.provider == "open_router"
+ assert result.api_key == "or-key-from-chat-config"
+ assert result.base_url is None
+ assert result.supports_flex is True
+ assert result.cost_log_provider == "open_router"
+
+ def test_openrouter_falls_back_to_secrets(self, monkeypatch: pytest.MonkeyPatch):
+ # OpenRouter requires both api_key and a valid base_url for the
+ # ``openrouter_active`` gate. Use the canonical OR base url so the
+ # transport actually resolves to ``openrouter`` and not
+ # ``direct_anthropic``.
+ cfg = ChatConfig(
+ use_openrouter=True,
+ api_key="or-key",
+ base_url="https://openrouter.ai/api/v1",
+ )
+ _patch_chat_cfg(monkeypatch, cfg)
+ _patch_settings(monkeypatch, open_router_api_key="or-key-from-secrets")
+
+ result = routing_kwargs_for_chat_transport()
+ # ``cfg.api_key`` set to "or-key" wins; demonstrating the
+ # fallback path requires a config that resolves to openrouter
+ # without setting chat_cfg.api_key — which the validator forbids
+ # under the openrouter_active gate. The fallback exists as
+ # belt-and-suspenders for runtime env mutations.
+ assert result.api_key == "or-key"
+
+
+class TestSubscriptionTransport:
+ """Subscription users authenticate the chat path via Claude Code
+ OAuth, but that token can't call the Messages API directly (see
+ Anthropic Feb-2026 ToS). Dream pass needs a separate
+ ``ANTHROPIC_API_KEY`` — the helper surfaces ``""`` when missing
+ so callers can produce a friendly error."""
+
+ def test_subscription_with_anthropic_key_from_settings(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ cfg = ChatConfig(
+ use_claude_code_subscription=True,
+ thinking_standard_model="anthropic/claude-sonnet-4-6",
+ thinking_advanced_model="anthropic/claude-opus-4-7",
+ aux_api_key="or-aux-key",
+ )
+ _patch_chat_cfg(monkeypatch, cfg)
+ _patch_settings(monkeypatch, anthropic_api_key="ant-key-12345")
+
+ result = routing_kwargs_for_chat_transport()
+ assert result.provider == "anthropic"
+ assert result.api_key == "ant-key-12345"
+ assert result.base_url is None
+ assert result.supports_flex is False
+ assert result.cost_log_provider == "anthropic"
+
+ def test_subscription_without_anthropic_key_returns_empty(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ """Friendly-error path — callers (e.g. dream/llm.py) check for
+ empty ``api_key`` and raise with an env-var hint instead of
+ letting ``call_provider`` 401."""
+ cfg = ChatConfig(
+ use_claude_code_subscription=True,
+ thinking_standard_model="anthropic/claude-sonnet-4-6",
+ thinking_advanced_model="anthropic/claude-opus-4-7",
+ aux_api_key="or-aux-key",
+ )
+ _patch_chat_cfg(monkeypatch, cfg)
+ _patch_settings(monkeypatch) # anthropic_api_key="" by default
+
+ result = routing_kwargs_for_chat_transport()
+ assert result.provider == "anthropic"
+ assert result.api_key == ""
+ assert result.cost_log_provider == "anthropic"
+
+ def test_subscription_prefers_direct_anthropic_api_key_field(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ """``chat.direct_anthropic_api_key`` (if the operator set it)
+ wins over the platform-wide ``settings.secrets.anthropic_api_key``."""
+ cfg = ChatConfig(
+ use_claude_code_subscription=True,
+ direct_anthropic_api_key="ant-key-direct-cfg",
+ thinking_standard_model="anthropic/claude-sonnet-4-6",
+ thinking_advanced_model="anthropic/claude-opus-4-7",
+ aux_api_key="or-aux-key",
+ )
+ _patch_chat_cfg(monkeypatch, cfg)
+ _patch_settings(monkeypatch, anthropic_api_key="ant-key-from-secrets")
+
+ result = routing_kwargs_for_chat_transport()
+ assert result.api_key == "ant-key-direct-cfg"
+
+
+class TestDirectAnthropicTransport:
+ """direct_anthropic is the explicit "skip OpenRouter, talk to
+ Anthropic" cloud transport. Same provider as subscription but
+ different transport identity (so cost-log labels match)."""
+
+ def test_direct_anthropic_routing_kwargs(self, monkeypatch: pytest.MonkeyPatch):
+ cfg = ChatConfig(
+ use_openrouter=False,
+ api_key=None,
+ base_url=None,
+ direct_anthropic_api_key="ant-key-direct",
+ thinking_standard_model="anthropic/claude-sonnet-4-6",
+ thinking_advanced_model="anthropic/claude-opus-4-7",
+ aux_api_key="or-aux-key",
+ )
+ _patch_chat_cfg(monkeypatch, cfg)
+ _patch_settings(monkeypatch)
+
+ result = routing_kwargs_for_chat_transport()
+ assert result.provider == "anthropic"
+ assert result.api_key == "ant-key-direct"
+ assert result.base_url is None
+ assert result.supports_flex is False
+ assert result.cost_log_provider == "anthropic"
+
+
+class TestStaticIdentityPropagation:
+ """Sanity tests that the static ``TransportProfile`` fields
+ (``dispatch_provider``, ``supports_flex_tier``,
+ ``cost_log_provider``) flow into the returned dataclass without
+ transformation."""
+
+ @pytest.mark.parametrize(
+ "transport_kwargs, expected_provider, expected_cost, expected_flex",
+ [
+ (
+ dict(
+ use_local=True,
+ api_key="ollama",
+ base_url="http://h:11434/v1",
+ ),
+ "ollama",
+ "ollama",
+ False,
+ ),
+ (
+ dict(
+ use_openrouter=True,
+ api_key="or-key",
+ base_url="https://openrouter.ai/api/v1",
+ ),
+ "open_router",
+ "open_router",
+ True,
+ ),
+ ],
+ )
+ def test_profile_fields_propagate_into_routing_kwargs(
+ self,
+ monkeypatch: pytest.MonkeyPatch,
+ transport_kwargs: dict,
+ expected_provider: str,
+ expected_cost: str,
+ expected_flex: bool,
+ ):
+ cfg = ChatConfig(**transport_kwargs)
+ _patch_chat_cfg(monkeypatch, cfg)
+ _patch_settings(monkeypatch, open_router_api_key="or-secrets-key")
+
+ result = routing_kwargs_for_chat_transport()
+ assert result.provider == expected_provider
+ assert result.cost_log_provider == expected_cost
+ assert result.supports_flex is expected_flex
diff --git a/autogpt_platform/backend/backend/data/platform_cost.py b/autogpt_platform/backend/backend/data/platform_cost.py
index 635dbc1d18..9af1fe754f 100644
--- a/autogpt_platform/backend/backend/data/platform_cost.py
+++ b/autogpt_platform/backend/backend/data/platform_cost.py
@@ -103,6 +103,21 @@ async def log_platform_cost_safe(entry: PlatformCostEntry) -> None:
)
+def _md_str(row: Any, key: str) -> str | None:
+ """Read a string-valued key out of PlatformCostLog.metadata.
+
+ Returns ``None`` when metadata is absent, isn't a dict, or the key
+ is missing/non-string. PlatformCostLog.metadata is a Prisma ``Json``
+ column so it deserializes to whatever the writer put in; we defend
+ against everything but the happy path.
+ """
+ md = getattr(row, "metadata", None)
+ if not isinstance(md, dict):
+ return None
+ val = md.get(key)
+ return val if isinstance(val, str) else None
+
+
def _mask_email(email: str | None) -> str | None:
"""Mask an email address to reduce PII exposure in admin API responses.
@@ -163,6 +178,13 @@ class CostLogRow(BaseModel):
model: str | None = None
cache_read_tokens: int | None = None
cache_creation_tokens: int | None = None
+ # ``execution_path`` and ``source`` ride in the JSON ``metadata``
+ # column on PlatformCostLog. Surfacing them as first-class fields
+ # lets the admin LogsTable render a "BATCH"/"FLEX"/"SYNC" badge and
+ # the filter dropdown narrow rows without admins needing to query
+ # the JSON directly. Empty when the writer didn't tag the row.
+ execution_path: str | None = None
+ source: str | None = None
class CostBucket(BaseModel):
@@ -249,6 +271,97 @@ def _build_prisma_where(
return where
+async def _ids_matching_metadata_filter(
+ *,
+ start: datetime | None,
+ end: datetime | None,
+ provider: str | None,
+ user_id: str | None,
+ model: str | None,
+ block_name: str | None,
+ tracking_type: str | None,
+ graph_exec_id: str | None,
+ execution_path: str | None,
+ source: str | None,
+ limit: int,
+ offset: int,
+) -> tuple[list[str], int]:
+ """Return ``(ids, total)`` matching all filters via raw SQL.
+
+ Prisma Python's typed ``count`` (implemented as
+ ``aggregate { _count }``) and ``find_many`` both reject
+ JSON-path filters on the ``metadata`` JSONB column — the engine
+ surfaces ``Could not find field at
+ aggregatePlatformCostLog.where.metadata.string_equals``. Raw SQL
+ sidesteps the typed-WhereInput validation entirely. The caller
+ hydrates the full row + User join via
+ ``find_many({"id": {"in": ids}})``.
+
+ Only used when ``execution_path`` or ``source`` is set. The
+ happy-path query without metadata filters stays on the typed
+ Prisma helpers for speed + type-safety.
+ """
+ clauses: list[str] = []
+ params: list = []
+
+ def _add(clause_tpl: str, *vals) -> None:
+ # Append values then format the clause with sequential $N
+ # placeholders matching the params order.
+ placeholders = [f"${len(params) + i + 1}" for i in range(len(vals))]
+ for v in vals:
+ params.append(v)
+ clauses.append(clause_tpl.format(*placeholders))
+
+ # Prisma's raw_query serializes ``datetime`` arguments as ISO
+ # strings. PlatformCostLog.createdAt is ``timestamp without time
+ # zone`` (Prisma's default DateTime mapping), so without an
+ # explicit ``::timestamp`` cast on the placeholder, Postgres
+ # rejects the comparison with ``operator does not exist:
+ # timestamp without time zone >= text``. The cast does the same
+ # work the typed Prisma helper does silently.
+ if start is not None:
+ _add('"createdAt" >= {0}::timestamp', start)
+ if end is not None:
+ _add('"createdAt" <= {0}::timestamp', end)
+ if provider:
+ _add("provider = {0}", provider.lower())
+ if user_id:
+ _add('"userId" = {0}', user_id)
+ if model:
+ _add("model = {0}", model)
+ if block_name:
+ # Match _build_prisma_where's case-insensitive blockName filter.
+ _add('LOWER("blockName") = LOWER({0})', block_name)
+ if tracking_type:
+ _add('"trackingType" = {0}', tracking_type)
+ if graph_exec_id:
+ _add('"graphExecId" = {0}', graph_exec_id)
+ if execution_path:
+ _add("metadata->>'execution_path' = {0}", execution_path)
+ if source:
+ _add("metadata->>'source' = {0}", source)
+
+ where_sql = " AND ".join(clauses) if clauses else "TRUE"
+
+ count_rows = await query_raw_with_schema(
+ f'SELECT COUNT(*)::bigint AS c FROM {{schema_prefix}}"PlatformCostLog" '
+ f"WHERE {where_sql}",
+ *params,
+ )
+ total = int(count_rows[0]["c"]) if count_rows else 0
+
+ id_rows = await query_raw_with_schema(
+ f'SELECT id FROM {{schema_prefix}}"PlatformCostLog" '
+ f"WHERE {where_sql} "
+ f'ORDER BY "createdAt" DESC, id DESC '
+ f"LIMIT ${len(params) + 1} OFFSET ${len(params) + 2}",
+ *params,
+ limit,
+ offset,
+ )
+ return [r["id"] for r in id_rows], total
+
+
def _build_raw_where(
start: datetime | None,
end: datetime | None,
@@ -673,25 +786,65 @@ async def get_platform_cost_logs(
block_name: str | None = None,
tracking_type: str | None = None,
graph_exec_id: str | None = None,
+ execution_path: str | None = None,
+ source: str | None = None,
) -> tuple[list[CostLogRow], int]:
if start is None:
start = datetime.now(tz=timezone.utc) - timedelta(days=DEFAULT_DASHBOARD_DAYS)
- where = _build_prisma_where(
- start, end, provider, user_id, model, block_name, tracking_type, graph_exec_id
- )
offset = (page - 1) * page_size
- total, rows = await asyncio.gather(
- PrismaLog.prisma().count(where=where),
- PrismaLog.prisma().find_many(
- where=where,
- include={"User": True},
- order=[{"createdAt": "desc"}, {"id": "desc"}],
- take=page_size,
- skip=offset,
- ),
- )
+ if execution_path or source:
+ # Metadata-filtered path: typed Prisma ``count`` (an aggregate
+ # under the hood) and ``find_many`` both reject JSON-column
+ # filters with ``Could not find field at
+ # aggregatePlatformCostLog.where.metadata.string_equals``.
+ # Use raw SQL to identify the matching IDs + total, then
+ # hydrate via ``find_many({"id": {"in": ids}})`` so the User
+ # join + return-shape match the unfiltered path.
+ ids, total = await _ids_matching_metadata_filter(
+ start=start,
+ end=end,
+ provider=provider,
+ user_id=user_id,
+ model=model,
+ block_name=block_name,
+ tracking_type=tracking_type,
+ graph_exec_id=graph_exec_id,
+ execution_path=execution_path,
+ source=source,
+ limit=page_size,
+ offset=offset,
+ )
+ if ids:
+ rows = await PrismaLog.prisma().find_many(
+ where={"id": {"in": ids}},
+ include={"User": True},
+ order=[{"createdAt": "desc"}, {"id": "desc"}],
+ )
+ else:
+ rows = []
+ else:
+ where = _build_prisma_where(
+ start,
+ end,
+ provider,
+ user_id,
+ model,
+ block_name,
+ tracking_type,
+ graph_exec_id,
+ )
+ total, rows = await asyncio.gather(
+ PrismaLog.prisma().count(where=where),
+ PrismaLog.prisma().find_many(
+ where=where,
+ include={"User": True},
+ order=[{"createdAt": "desc"}, {"id": "desc"}],
+ take=page_size,
+ skip=offset,
+ ),
+ )
logs = [
CostLogRow(
@@ -711,6 +864,8 @@ async def get_platform_cost_logs(
cache_creation_tokens=getattr(r, "cacheCreationTokens", None),
duration=r.duration,
model=r.model,
+ execution_path=_md_str(r, "execution_path"),
+ source=_md_str(r, "source"),
)
for r in rows
]
@@ -868,6 +1023,8 @@ async def get_platform_cost_logs_for_export(
block_name: str | None = None,
tracking_type: str | None = None,
graph_exec_id: str | None = None,
+ execution_path: str | None = None,
+ source: str | None = None,
) -> tuple[list[CostLogRow], bool]:
"""Return all matching rows up to EXPORT_MAX_ROWS.
@@ -877,16 +1034,46 @@ async def get_platform_cost_logs_for_export(
if start is None:
start = datetime.now(tz=timezone.utc) - timedelta(days=DEFAULT_DASHBOARD_DAYS)
- where = _build_prisma_where(
- start, end, provider, user_id, model, block_name, tracking_type, graph_exec_id
- )
-
- rows = await PrismaLog.prisma().find_many(
- where=where,
- include={"User": True},
- order=[{"createdAt": "desc"}, {"id": "desc"}],
- take=EXPORT_MAX_ROWS + 1,
- )
+ if execution_path or source:
+ ids, _ = await _ids_matching_metadata_filter(
+ start=start,
+ end=end,
+ provider=provider,
+ user_id=user_id,
+ model=model,
+ block_name=block_name,
+ tracking_type=tracking_type,
+ graph_exec_id=graph_exec_id,
+ execution_path=execution_path,
+ source=source,
+ limit=EXPORT_MAX_ROWS + 1,
+ offset=0,
+ )
+ if ids:
+ rows = await PrismaLog.prisma().find_many(
+ where={"id": {"in": ids}},
+ include={"User": True},
+ order=[{"createdAt": "desc"}, {"id": "desc"}],
+ )
+ else:
+ rows = []
+ else:
+ where = _build_prisma_where(
+ start,
+ end,
+ provider,
+ user_id,
+ model,
+ block_name,
+ tracking_type,
+ graph_exec_id,
+ )
+ rows = await PrismaLog.prisma().find_many(
+ where=where,
+ include={"User": True},
+ order=[{"createdAt": "desc"}, {"id": "desc"}],
+ take=EXPORT_MAX_ROWS + 1,
+ )
truncated = len(rows) > EXPORT_MAX_ROWS
rows = rows[:EXPORT_MAX_ROWS]
@@ -909,6 +1096,8 @@ async def get_platform_cost_logs_for_export(
cache_creation_tokens=getattr(r, "cacheCreationTokens", None),
duration=r.duration,
model=r.model,
+ execution_path=_md_str(r, "execution_path"),
+ source=_md_str(r, "source"),
)
for r in rows
], truncated
diff --git a/autogpt_platform/backend/backend/data/redis_helpers.py b/autogpt_platform/backend/backend/data/redis_helpers.py
index 3ddad1b675..99fee54a8a 100644
--- a/autogpt_platform/backend/backend/data/redis_helpers.py
+++ b/autogpt_platform/backend/backend/data/redis_helpers.py
@@ -68,6 +68,48 @@ redis.call('EXPIRE', KEYS[2], tonumber(ARGV[5]))
return redis.call('LLEN', KEYS[2])
"""
+# Exactly-once batch-dispatch claim. Used by the BatchExecutor's walk
+# to transition a finished provider batch from ``pending → dispatched``
+# in one indivisible step. Without this, the dispatch path is racy:
+#
+# await _dispatch(entry, rows) # side effects fire here
+# await remove_pending(batch_id) # ← any crash / slow write here
+# # leaves the batch in pending,
+# # next walk re-dispatches.
+#
+# The atomic claim SETs a per-batch tombstone STRING key BEFORE the
+# walker calls _dispatch, so a re-entry will be refused even when the
+# pending hash hasn't been HDEL'd yet. One tombstone key per batch_id
+# (``SET ... NX EX ttl``) means each tombstone self-expires its own
+# TTL after its own dispatch. The previous design — one shared SET
+# whose TTL was re-applied on every claim — never aged members out:
+# as long as one batch dispatched within the window, the whole set
+# lived forever and grew unbounded.
+#
+# Cluster safety: this script touches two keys (pending hash +
+# tombstone), so both MUST share a Redis Cluster hash tag (e.g. both
+# prefixed with ``{llm:batch}:``) to land on the same slot — required
+# for multi-key Lua under cluster mode. The pending hash is a
+# single-slot structure anyway, so colocating the small, self-expiring
+# tombstones on its slot costs nothing and buys full claim+HDEL
+# atomicity (no claimed-but-still-pending window for walkers to skip).
+#
+# Returns 1 when this caller won the claim (proceed with dispatch),
+# 0 when another walker already dispatched (skip silently).
+#
+# KEYS[1] pending hash key
+# KEYS[2] per-batch tombstone key
+# ARGV[1] batch_id (field on the pending hash)
+# ARGV[2] TTL seconds applied to the tombstone key
+_CLAIM_BATCH_DISPATCH_LUA = """
+if redis.call('SET', KEYS[2], '1', 'NX', 'EX', ARGV[2]) then
+ redis.call('HDEL', KEYS[1], ARGV[1])
+ return 1
+end
+return 0
+"""
+
+
# Atomically: sweep stale slots, refresh an existing slot's claim or add
# a new slot iff the pool is under capacity, then set the pool key's TTL.
# Returns 1 when a NEW slot was admitted, 2 when an EXISTING slot's claim
@@ -226,6 +268,59 @@ async def capped_rpush_if_hash_field(
return None if length < 0 else length
+async def claim_batch_dispatch_atomic(
+ redis: AsyncRedisClient,
+ *,
+ pending_key: str,
+ dispatched_key_prefix: str,
+ batch_id: str,
+ ttl_seconds: int,
+) -> bool:
+ """Atomically claim the right to dispatch results for ``batch_id``.
+
+ Used by the BatchExecutor walk loop. The race we're closing:
+
+ await _dispatch(entry, rows) # side effects fire here
+ await remove_pending(batch_id) # gap → re-dispatch on
+ # crash / contention
+
+ The tombstone is one STRING key per batch —
+ ``f"{dispatched_key_prefix}:{batch_id}"`` — set with ``NX EX`` so
+ each tombstone expires individually ``ttl_seconds`` after its own
+ dispatch (a shared set with one refreshed TTL would never age
+ members out and grow unbounded). The Lua script SETs the tombstone
+ and, only when it won, HDELs the pending entry, all in one
+ indivisible step. Returns ``True`` when this caller won the claim
+ (proceed with dispatch), ``False`` when another walker already
+ dispatched (skip silently).
+
+ ``pending_key`` and ``dispatched_key_prefix`` MUST share a Redis
+ Cluster hash tag (e.g. both prefixed with ``"{llm:batch}:"``) so
+ the pending hash and every tombstone land on the same slot —
+ required for multi-key Lua under cluster mode. Same-slot keys keep
+ the claim + HDEL fully atomic, so a crash can never leave a
+ claimed-but-still-pending entry.
+
+ ``ttl_seconds`` should comfortably exceed the longest possible
+ in-flight batch lifetime so stale tombstones cannot let a very
+ late re-poll cause a re-dispatch. 7 days is fine today (Anthropic
+ batch SLA is 24h, max batch lifetime cap is 24h); raise it if the
+ provider window widens.
+ """
+ result = await cast(
+ "Any",
+ redis.eval(
+ _CLAIM_BATCH_DISPATCH_LUA,
+ 2,
+ pending_key,
+ f"{dispatched_key_prefix}:{batch_id}",
+ batch_id,
+ str(ttl_seconds),
+ ),
+ )
+ return bool(int(result))
+
+
class SlotAdmission(IntEnum):
"""Result of :func:`try_acquire_concurrency_slot`.
diff --git a/autogpt_platform/backend/backend/data/redis_helpers_test.py b/autogpt_platform/backend/backend/data/redis_helpers_test.py
index 5410a46195..bfcd69e3ee 100644
--- a/autogpt_platform/backend/backend/data/redis_helpers_test.py
+++ b/autogpt_platform/backend/backend/data/redis_helpers_test.py
@@ -12,6 +12,7 @@ import pytest
from backend.data.redis_helpers import (
capped_rpush,
capped_rpush_if_hash_field,
+ claim_batch_dispatch_atomic,
hash_compare_and_set,
incr_with_ttl,
incr_with_ttl_sync,
@@ -27,6 +28,7 @@ class _Fake:
self.counters: dict[str, int] = {}
self.lists: dict[str, list[str]] = {}
self.hashes: dict[str, dict[str, str]] = {}
+ self.strings: dict[str, str] = {}
self.ttls: dict[str, int] = {}
self.expire_calls: list[tuple[str, int, bool]] = []
@@ -57,7 +59,23 @@ class _Fake:
return len(self.lists.get(key, []))
async def eval(self, script: str, numkeys: int, *args: Any) -> int:
+ # Discriminate by script content — the helpers all use distinct
+ # Lua so we can route on a unique substring per script.
+ if "HDEL" in script:
+ # ``claim_batch_dispatch_atomic`` shape:
+ # KEYS[1]=pending hash, KEYS[2]=per-batch tombstone key,
+ # ARGV[1]=batch_id, ARGV[2]=ttl_seconds
+ pending_key, tombstone_key = args[0], args[1]
+ batch_id, ttl_seconds = args[2], args[3]
+ if tombstone_key in self.strings:
+ return 0
+ self.strings[tombstone_key] = "1"
+ await self.expire(tombstone_key, int(ttl_seconds))
+ self.hashes.setdefault(pending_key, {}).pop(batch_id, None)
+ return 1
+
if numkeys == 2:
+ # ``capped_rpush_if_hash_field`` shape.
hash_key, list_key = args[0], args[1]
field, expected, value, max_len, ttl_seconds = args[2:7]
h = self.hashes.setdefault(hash_key, {})
@@ -68,6 +86,7 @@ class _Fake:
await self.expire(list_key, int(ttl_seconds))
return await self.llen(list_key)
+ # ``hash_compare_and_set`` shape (numkeys == 1).
key, field, expected, new = args[0], args[1], args[2], args[3]
h = self.hashes.setdefault(key, {})
if h.get(field) == expected:
@@ -276,3 +295,131 @@ async def test_hash_cas_no_swap_when_expected_differs() -> None:
)
assert swapped is False
assert r.hashes["meta"]["status"] == "completed"
+
+
+# ── claim_batch_dispatch_atomic ───────────────────────────────────────
+
+
+async def test_claim_batch_dispatch_first_call_wins() -> None:
+ """First call must win, must SET the per-batch tombstone key with
+ its own TTL, and must HDEL the pending entry."""
+ r = _Fake()
+ r.hashes["{llm:batch}:pending"] = {
+ "msgbatch_x": "entry-body",
+ "msgbatch_other": "untouched",
+ }
+
+ claimed = await claim_batch_dispatch_atomic(
+ r, # type: ignore[arg-type]
+ pending_key="{llm:batch}:pending",
+ dispatched_key_prefix="{llm:batch}:dispatched",
+ batch_id="msgbatch_x",
+ ttl_seconds=7 * 24 * 60 * 60,
+ )
+
+ assert claimed is True
+ assert r.strings["{llm:batch}:dispatched:msgbatch_x"] == "1"
+ # Pending entry removed for the claimed batch, others untouched.
+ assert "msgbatch_x" not in r.hashes["{llm:batch}:pending"]
+ assert r.hashes["{llm:batch}:pending"]["msgbatch_other"] == "untouched"
+ assert r.ttls["{llm:batch}:dispatched:msgbatch_x"] == 7 * 24 * 60 * 60
+
+
+async def test_claim_batch_dispatch_second_call_loses() -> None:
+ """A second walker arriving for the same batch_id must be refused
+ even if the pending entry has somehow been re-added — the tombstone
+ is the authoritative source of truth."""
+ r = _Fake()
+ r.hashes["{llm:batch}:pending"] = {"msgbatch_x": "entry-body"}
+
+ first = await claim_batch_dispatch_atomic(
+ r, # type: ignore[arg-type]
+ pending_key="{llm:batch}:pending",
+ dispatched_key_prefix="{llm:batch}:dispatched",
+ batch_id="msgbatch_x",
+ ttl_seconds=60,
+ )
+ # Simulate the pending entry being re-added by a buggy caller —
+ # the tombstone must still refuse the claim.
+ r.hashes["{llm:batch}:pending"]["msgbatch_x"] = "re-added"
+
+ second = await claim_batch_dispatch_atomic(
+ r, # type: ignore[arg-type]
+ pending_key="{llm:batch}:pending",
+ dispatched_key_prefix="{llm:batch}:dispatched",
+ batch_id="msgbatch_x",
+ ttl_seconds=60,
+ )
+
+ assert first is True
+ assert second is False
+ # The re-added pending entry is NOT removed because the claim was
+ # refused; the buggy caller's state survives untouched so an
+ # operator can detect + investigate.
+ assert r.hashes["{llm:batch}:pending"]["msgbatch_x"] == "re-added"
+
+
+async def test_claim_batch_dispatch_distinct_batch_ids_dont_collide() -> None:
+ """Tombstones are per-batch_id keys — claiming batch A must not
+ block a later claim for batch B."""
+ r = _Fake()
+ r.hashes["{llm:batch}:pending"] = {"a": "body-a", "b": "body-b"}
+
+ a = await claim_batch_dispatch_atomic(
+ r, # type: ignore[arg-type]
+ pending_key="{llm:batch}:pending",
+ dispatched_key_prefix="{llm:batch}:dispatched",
+ batch_id="a",
+ ttl_seconds=60,
+ )
+ b = await claim_batch_dispatch_atomic(
+ r, # type: ignore[arg-type]
+ pending_key="{llm:batch}:pending",
+ dispatched_key_prefix="{llm:batch}:dispatched",
+ batch_id="b",
+ ttl_seconds=60,
+ )
+
+ assert a is True
+ assert b is True
+ assert set(r.strings) == {
+ "{llm:batch}:dispatched:a",
+ "{llm:batch}:dispatched:b",
+ }
+ assert r.hashes["{llm:batch}:pending"] == {}
+
+
+async def test_claim_tombstones_age_out_individually() -> None:
+ """Each tombstone key carries its own TTL — a later claim for a
+ different batch must not refresh an earlier tombstone's TTL. (The
+ old shared-set design re-EXPIREd the whole set on every claim, so
+ members never aged out under continuous traffic and the set grew
+ without bound.)"""
+ r = _Fake()
+ r.hashes["{llm:batch}:pending"] = {"a": "body-a", "b": "body-b"}
+
+ await claim_batch_dispatch_atomic(
+ r, # type: ignore[arg-type]
+ pending_key="{llm:batch}:pending",
+ dispatched_key_prefix="{llm:batch}:dispatched",
+ batch_id="a",
+ ttl_seconds=60,
+ )
+ await claim_batch_dispatch_atomic(
+ r, # type: ignore[arg-type]
+ pending_key="{llm:batch}:pending",
+ dispatched_key_prefix="{llm:batch}:dispatched",
+ batch_id="b",
+ ttl_seconds=60,
+ )
+
+ # Exactly one EXPIRE per tombstone, each on its own key — nothing
+ # shared, nothing refreshed by the other batch's claim.
+ assert [key for key, _, _ in r.expire_calls] == [
+ "{llm:batch}:dispatched:a",
+ "{llm:batch}:dispatched:b",
+ ]
diff --git a/autogpt_platform/backend/backend/data/user.py b/autogpt_platform/backend/backend/data/user.py
index b778efa910..6a67af3d87 100644
--- a/autogpt_platform/backend/backend/data/user.py
+++ b/autogpt_platform/backend/backend/data/user.py
@@ -1,3 +1,4 @@
+import asyncio
import base64
import hashlib
import hmac
@@ -499,6 +500,22 @@ async def cleanup_user_managed_credentials(
await cleanup_managed_credentials(user_id, store)
+# Strong refs to fire-and-forget tasks — the event loop only keeps weak
+# references, so an unretained task can be GC'd mid-flight and its
+# exception is never observed. Same pattern as
+# ``backend/copilot/chat_session_embeddings.py``.
+_background_tasks: set[asyncio.Task] = set()
+
+
+def _on_background_task_done(task: asyncio.Task) -> None:
+ _background_tasks.discard(task)
+ if task.cancelled():
+ return
+ exc = task.exception()
+ if exc is not None:
+ logger.warning("Background task %s failed", task.get_name(), exc_info=exc)
+
+
async def update_user_timezone(user_id: str, timezone: str) -> User:
"""Update a user's timezone setting."""
try:
@@ -519,6 +536,30 @@ async def update_user_timezone(user_id: str, timezone: str) -> User:
get_user_by_email.cache_delete(user.email)
get_or_create_user.cache_clear()
+ # Dream-system schedules are bound to the timezone at job-creation
+ # time; without an eager re-register they'd keep firing at the old
+ # local time. Fire-and-forget so this profile update returns
+ # immediately — the helper's lazy drift-detection path (via the
+ # Redis dedup key value) is the durable backstop if this
+ # fails or the user doesn't trigger a memory write within the
+ # 7-day key TTL.
+ try:
+ from backend.copilot.dream.scheduling import ensure_dream_system_scheduled
+
+ task = asyncio.create_task(
+ ensure_dream_system_scheduled(user_id, force_refresh=True),
+ name=f"tz-reregister-{user_id[:12]}",
+ )
+ _background_tasks.add(task)
+ task.add_done_callback(_on_background_task_done)
+ except Exception:
+ logger.warning(
+ "Failed to spawn dream-system re-register after timezone "
+ "update for user %s — lazy drift detection will catch it",
+ user_id[:12],
+ exc_info=True,
+ )
+
return User.from_db(user)
except Exception as e:
raise DatabaseError(f"Failed to update timezone for user {user_id}: {e}") from e
diff --git a/autogpt_platform/backend/backend/data/user_test.py b/autogpt_platform/backend/backend/data/user_test.py
index f2b1829280..b21bbad5f6 100644
--- a/autogpt_platform/backend/backend/data/user_test.py
+++ b/autogpt_platform/backend/backend/data/user_test.py
@@ -1,5 +1,6 @@
"""Unit tests for helpers in backend.data.user."""
+import asyncio
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
@@ -64,3 +65,84 @@ class TestUpdateUserTimezone:
assert "user-1" in str(exc.value)
assert "connection lost" in str(exc.value)
+
+ @pytest.mark.asyncio
+ async def test_eagerly_re_registers_dream_schedules_with_force_refresh(self):
+ """APScheduler cron triggers bind to the timezone at registration
+ time. A profile-page timezone change MUST eagerly re-register
+ the dream-system crons so they fire at the right local time
+ without waiting for the 7-day Redis dedup-key TTL to expire."""
+ from backend.copilot.dream import scheduling as dream_scheduling
+
+ prisma_user = MagicMock(id="user-tz", email="[email protected]")
+ captured: list[tuple[str, bool]] = []
+
+ async def fake_ensure(user_id: str, *, force_refresh: bool = False):
+ captured.append((user_id, force_refresh))
+ return {}
+
+ with (
+ patch.object(user_module, "PrismaUser") as mock_prisma_user,
+ patch.object(user_module.User, "from_db", return_value=MagicMock()),
+ patch.object(user_module.get_user_by_id, "cache_delete"),
+ patch.object(user_module.get_user_by_email, "cache_delete"),
+ patch.object(user_module.get_or_create_user, "cache_clear"),
+ patch.object(
+ dream_scheduling, "ensure_dream_system_scheduled", new=fake_ensure
+ ),
+ ):
+ mock_prisma_user.prisma.return_value.update = AsyncMock(
+ return_value=prisma_user
+ )
+ await update_user_timezone("user-tz", "Europe/Paris")
+ # Yield once so the asyncio.create_task body runs before we
+ # assert it was called.
+ await asyncio.sleep(0)
+
+ assert captured == [("user-tz", True)]
+
+ @pytest.mark.asyncio
+ async def test_re_register_task_is_retained_and_its_failure_logged(self):
+ """The event loop holds only weak refs to tasks — an unretained
+ fire-and-forget re-register can be GC'd mid-flight and its
+ exception never observed. The spawn must keep a strong ref in
+ ``_background_tasks`` until done and log failures via the
+ done-callback instead of dropping them."""
+ from backend.copilot.dream import scheduling as dream_scheduling
+
+ prisma_user = MagicMock(id="user-tz", email="[email protected]")
+
+ async def failing_ensure(user_id: str, *, force_refresh: bool = False):
+ raise RuntimeError("scheduler unreachable")
+
+ with (
+ patch.object(user_module, "PrismaUser") as mock_prisma_user,
+ patch.object(user_module.User, "from_db", return_value=MagicMock()),
+ patch.object(user_module.get_user_by_id, "cache_delete"),
+ patch.object(user_module.get_user_by_email, "cache_delete"),
+ patch.object(user_module.get_or_create_user, "cache_clear"),
+ patch.object(
+ dream_scheduling, "ensure_dream_system_scheduled", new=failing_ensure
+ ),
+ patch.object(user_module.logger, "warning") as warn_mock,
+ ):
+ mock_prisma_user.prisma.return_value.update = AsyncMock(
+ return_value=prisma_user
+ )
+ await update_user_timezone("user-tz", "Europe/Paris")
+
+ spawned = [
+ t
+ for t in user_module._background_tasks
+ if t.get_name() == "tz-reregister-user-tz"
+ ]
+ assert spawned, "task must be strongly referenced until it completes"
+
+ await asyncio.gather(*spawned, return_exceptions=True)
+ # One more tick so the done-callback (scheduled via
+ # call_soon) runs.
+ await asyncio.sleep(0)
+
+ assert not user_module._background_tasks & set(spawned)
+ warn_mock.assert_called_once()
+ assert isinstance(warn_mock.call_args.kwargs["exc_info"], RuntimeError)
diff --git a/autogpt_platform/backend/backend/executor/activity_status_generator.py b/autogpt_platform/backend/backend/executor/activity_status_generator.py
index e7bf88e738..2285e55bdd 100644
--- a/autogpt_platform/backend/backend/executor/activity_status_generator.py
+++ b/autogpt_platform/backend/backend/executor/activity_status_generator.py
@@ -535,7 +535,10 @@ def _persist_activity_status_cost(
model=model_name,
tracking_type=tracking_type,
tracking_amount=tracking_amount,
- metadata={"source": "activity_status_generator"},
+ metadata={
+ "source": "activity_status_generator",
+ "execution_path": "sync",
+ },
),
)
except Exception:
diff --git a/autogpt_platform/backend/backend/executor/activity_status_generator_test.py b/autogpt_platform/backend/backend/executor/activity_status_generator_test.py
index 52c0240d5d..1612ee0cef 100644
--- a/autogpt_platform/backend/backend/executor/activity_status_generator_test.py
+++ b/autogpt_platform/backend/backend/executor/activity_status_generator_test.py
@@ -575,7 +575,14 @@ class TestGenerateActivityStatusForExecution:
assert entry.cost_microdollars == 4200
assert entry.input_tokens == 120
assert entry.output_tokens == 40
- assert entry.metadata == {"source": "activity_status_generator"}
+ # ``execution_path`` was added by dev's TransportProfile rollout
+ # (#12993). For the cloud-baseline test config we exercise here
+ # the activity-status generator routes through the sync OR client,
+ # which the new cost-log labelling tags as ``execution_path=sync``.
+ assert entry.metadata == {
+ "source": "activity_status_generator",
+ "execution_path": "sync",
+ }
@pytest.mark.asyncio
async def test_generate_status_no_cost_no_log(
diff --git a/autogpt_platform/backend/backend/executor/batch_executor.py b/autogpt_platform/backend/backend/executor/batch_executor.py
new file mode 100644
index 0000000000..1162e872aa
--- /dev/null
+++ b/autogpt_platform/backend/backend/executor/batch_executor.py
@@ -0,0 +1,650 @@
+"""Background service that polls submitted LLM batches and dispatches results.
+
+The dream-pass orchestrator (and any future server-side batch caller)
+submits requests to Anthropic / OpenAI batch APIs via
+``backend/util/llm/providers.call_provider(execution_mode="batch")``.
+Submissions return immediately with a ``BatchSubmissionRef``; results
+arrive asynchronously up to ~24h later. This service owns:
+
+ * **Polling**: walks a Redis-backed pending queue with exponential
+ backoff (30s → 60s → 120s → 300s cap). Anthropic's typical
+ completion is <30min so the early-aggressive ramp pays off.
+ * **Dispatch**: when a batch reaches ``ended``, downloads results
+ via ``providers.download_batch_results`` and routes each row to
+ a caller-registered handler keyed on the entry's
+ ``callback_namespace`` (e.g. ``"dream_pass"``). Handlers run the
+ apply step, write cost-log rows, and update whatever JobStatus
+ row the caller cares about.
+
+Lives at the same architectural level as ``Scheduler`` — own process,
+own Redis connection, own service-port for health checks. Subscribing
+to a queue rather than driving submissions itself keeps the contract
+small: callers don't care which subprocess owns the poll loop, just
+that results land via their registered handler.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import threading
+from datetime import datetime, timezone
+from typing import Any, Awaitable, Callable
+
+from pydantic import BaseModel, Field, field_validator
+
+from backend.util.llm.providers import (
+ BatchResultRow,
+ ProviderLiteral,
+ download_batch_results,
+ poll_batch,
+)
+from backend.util.service import AppService, UnhealthyServiceError
+from backend.util.settings import Config
+
+logger = logging.getLogger(__name__)
+
+config = Config()
+
+
+# Redis key for the pending-batches hash. Each field is one
+# ``provider_batch_id``; each value is a JSON-serialized ``PendingEntry``.
+# Both keys share the ``{llm:batch}`` hash tag so they land on the same
+# Redis Cluster slot — required by ``claim_batch_dispatch_atomic``'s
+# multi-key Lua script. Don't add or rename either without also updating
+# the tag on the other.
+PENDING_KEY = "{llm:batch}:pending"
+# Tombstones for batches we've already started dispatching: one STRING
+# key per batch — ``{llm:batch}:dispatched:<batch_id>`` — each with its
+# own 7-day TTL so tombstones self-expire instead of accumulating in a
+# shared set forever. 7 days is the dedup window: longer than any
+# realistic Anthropic in-flight lifetime (24h SLA, our
+# MAX_BATCH_LIFETIME_SECONDS cap is also 24h). The ``{llm:batch}``
+# hash tag keeps every tombstone on the same cluster slot as the
+# pending hash — required by ``claim_batch_dispatch_atomic``'s
+# multi-key Lua script.
+DISPATCHED_KEY_PREFIX = "{llm:batch}:dispatched"
+DISPATCHED_TTL_SECONDS = 7 * 24 * 60 * 60
+
+# 24h hard ceiling — Anthropic's promised SLA. Beyond this we mark the
+# entry failed even if the provider still says ``processing``.
+MAX_BATCH_LIFETIME_SECONDS = 24 * 60 * 60
+
+# Poll cadence (exponential backoff). The BatchExecutor walks the queue
+# every ``WALK_INTERVAL_SECONDS`` but each individual entry is only
+# polled when its ``next_poll_at`` has elapsed.
+WALK_INTERVAL_SECONDS = 10
+INITIAL_POLL_DELAY_SECONDS = 30
+MAX_POLL_DELAY_SECONDS = 300
+
+
+# ---------------------------------------------------------------------------
+# Pending-entry persistence
+# ---------------------------------------------------------------------------
+
+
+class PendingEntry(BaseModel):
+ """One submitted batch we're waiting on.
+
+ ``callback_namespace`` is the dispatcher's primary routing key:
+ ``"dream_pass"`` → ``dream.batch_callbacks.handle``,
+ ``"copilot_chat"`` → (future, copilot chat batch handler), etc.
+ ``payload`` is opaque to the BatchExecutor — the namespace handler
+ knows what shape its callers stored there (typically user_id,
+ pass_id, job_id, phase, ...).
+ """
+
+ provider: ProviderLiteral
+ provider_batch_id: str
+ callback_namespace: str
+ submitted_at: datetime
+ next_poll_at: datetime
+ poll_delay_seconds: int = INITIAL_POLL_DELAY_SECONDS
+ payload: dict[str, Any] = Field(default_factory=dict)
+
+ @field_validator("submitted_at", "next_poll_at")
+ @classmethod
+ def _coerce_naive_to_utc(cls, value: datetime) -> datetime:
+ """Naive datetimes poison the walk: comparing them against an
+ aware ``now`` raises TypeError on every walk, forever, because
+ the bad entry is never removed. Coerce at the model boundary so
+ a careless producer (the queue is an open contract) can't write
+ the poison — and ``_deserialize`` can't re-hydrate it."""
+ if value.tzinfo is None:
+ return value.replace(tzinfo=timezone.utc)
+ return value
+
+
+async def enqueue_pending(entry: PendingEntry) -> None:
+ """Persist a pending batch to the Redis hash.
+
+ Callers invoke this right after their ``call_provider(execution_mode=
+ "batch")`` returns a ``BatchSubmissionRef``. The BatchExecutor's
+ walk picks it up within ``WALK_INTERVAL_SECONDS``.
+ """
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ # redis-py's typed stubs mark hash ops as returning bare values on
+ # AsyncRedisCluster — same workaround used in
+ # ``copilot/stream_registry.py``.
+ await redis.hset( # type: ignore[misc]
+ PENDING_KEY,
+ entry.provider_batch_id,
+ _serialize(entry),
+ )
+
+
+async def list_pending() -> list[PendingEntry]:
+ """Return every pending batch in the queue."""
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ raw = await redis.hgetall(PENDING_KEY) # type: ignore[misc]
+ entries: list[PendingEntry] = []
+ for batch_id, body in (raw or {}).items():
+ try:
+ entries.append(_deserialize(batch_id, body))
+ except Exception:
+ logger.exception(
+ "Corrupted pending-batch row at %s — leaving in place",
+ batch_id,
+ )
+ return entries
+
+
+async def update_pending(entry: PendingEntry) -> None:
+ """Rewrite an existing entry — used to advance ``next_poll_at`` /
+ ``poll_delay_seconds`` after a poll that returned ``processing``."""
+ await enqueue_pending(entry)
+
+
+async def remove_pending(provider_batch_id: str) -> None:
+ """Drop an entry from the queue without dispatching.
+
+ Never used to *bypass* the dispatch claim: ended, failed, and
+ lifetime-timeout all go through ``_claim_dispatch``, which
+ atomically tombstones + HDELs in one Lua script so concurrent
+ walkers (or a crash-replay) can never double-dispatch. The walk
+ loop's only callers are the refused-claim zombie cleanups on the
+ ended, failed, and lifetime-timeout paths — clearing a pending row
+ whose batch already carries a dispatch tombstone.
+ """
+ from backend.data.redis_client import get_redis_async
+
+ redis = await get_redis_async()
+ await redis.hdel(PENDING_KEY, provider_batch_id) # type: ignore[misc]
+
+
+async def _claim_dispatch(provider_batch_id: str) -> bool:
+ """Atomically claim the right to dispatch results for this batch.
+
+ Returns True when the caller won the claim (must dispatch); False
+ when another walker already claimed it (must skip silently — the
+ other walker is responsible for the callback). The Lua script
+ inside :func:`claim_batch_dispatch_atomic` SETs a per-batch
+ tombstone key (``NX EX`` so each one self-expires) + HDELs the
+ pending entry in one indivisible step, closing the race we'd
+ otherwise have between ``_dispatch`` and a separate
+ ``remove_pending``.
+ """
+ from backend.data.redis_client import get_redis_async
+ from backend.data.redis_helpers import claim_batch_dispatch_atomic
+
+ redis = await get_redis_async()
+ return await claim_batch_dispatch_atomic(
+ redis,
+ pending_key=PENDING_KEY,
+ dispatched_key_prefix=DISPATCHED_KEY_PREFIX,
+ batch_id=provider_batch_id,
+ ttl_seconds=DISPATCHED_TTL_SECONDS,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Callback registry
+# ---------------------------------------------------------------------------
+
+
+# A handler takes (entry, result_rows) and returns when apply is done.
+# It is the handler's responsibility to log costs, update any caller-
+# supplied job status, and decide what to do with errored rows.
+BatchResultHandler = Callable[[PendingEntry, list[BatchResultRow]], Awaitable[None]]
+
+_HANDLERS: dict[str, BatchResultHandler] = {}
+
+
+def register_handler(namespace: str, handler: BatchResultHandler) -> None:
+ """Register a result handler for one namespace.
+
+ Called at module-import time from the caller's ``__init__.py``
+ (or from the BatchExecutor's bootstrap). Re-registering a
+ namespace overwrites — last registration wins.
+ """
+ _HANDLERS[namespace] = handler
+
+
+def clear_handlers_for_test() -> None:
+ """Used by tests to reset the registry between cases."""
+ _HANDLERS.clear()
+
+
+# ---------------------------------------------------------------------------
+# Poll loop
+# ---------------------------------------------------------------------------
+
+
+async def walk_once(api_key_for: Callable[[ProviderLiteral], str | None]) -> None:
+ """One walk of the pending queue.
+
+ For each entry whose ``next_poll_at`` has elapsed:
+ * Poll the provider for status.
+ * If ``ended``: download results, dispatch to the namespace
+ handler, remove from queue.
+ * If ``failed``: dispatch an error result, remove from queue.
+ * If ``processing`` / ``pending``: bump ``poll_delay_seconds``
+ (exponential backoff, capped at ``MAX_POLL_DELAY_SECONDS``)
+ and write back.
+ * If past ``MAX_BATCH_LIFETIME_SECONDS``: dispatch a timeout
+ error, remove from queue (claimed atomically, exactly like the
+ ended / failed paths).
+
+ The API key is looked up by provider via the caller-supplied
+ factory so this module doesn't need to know how settings are
+ organized.
+ """
+ now = datetime.now(timezone.utc)
+ entries = await list_pending()
+ for entry in entries:
+ try:
+ await _walk_entry(entry, now=now, api_key_for=api_key_for)
+ except Exception:
+ # One poisoned entry must not starve the rest of the queue:
+ # without this guard an uncaught per-entry error aborts the
+ # walk, and every entry after it in hash order is never
+ # polled again — the bad entry is still pending next walk.
+ logger.exception(
+ "Failed processing pending batch %s — skipping this walk",
+ entry.provider_batch_id,
+ )
+
+
+async def _walk_entry(
+ entry: PendingEntry,
+ *,
+ now: datetime,
+ api_key_for: Callable[[ProviderLiteral], str | None],
+) -> None:
+ """Process a single pending entry — gates, poll, then dispatch."""
+ if (now - entry.submitted_at).total_seconds() > MAX_BATCH_LIFETIME_SECONDS:
+ await _handle_timeout(entry)
+ return
+
+ if entry.next_poll_at > now:
+ return
+
+ if entry.callback_namespace not in _HANDLERS:
+ # Never claim (= tombstone + irrecoverably drop) results we
+ # cannot deliver. An unregistered namespace usually means a
+ # deploy whose callback module failed to import (_bootstrap_
+ # callbacks swallows import errors) — leave the entry pending
+ # with backoff so a fixed deploy can still dispatch it within
+ # the provider's retention window. This can't loop forever:
+ # an entry whose handler never shows up eventually crosses
+ # MAX_BATCH_LIFETIME_SECONDS and the timeout path above claims
+ # + removes it.
+ logger.error(
+ "No handler registered for namespace=%s — leaving batch %s pending",
+ entry.callback_namespace,
+ entry.provider_batch_id,
+ )
+ await _push_back(entry)
+ return
+
+ api_key = api_key_for(entry.provider)
+ if not api_key:
+ logger.warning(
+ "No API key for provider=%s — leaving batch %s in queue",
+ entry.provider,
+ entry.provider_batch_id,
+ )
+ entry.next_poll_at = _next_poll_at(entry.poll_delay_seconds)
+ await update_pending(entry)
+ return
+
+ try:
+ status = await poll_batch(
+ provider=entry.provider,
+ provider_batch_id=entry.provider_batch_id,
+ api_key=api_key,
+ )
+ except Exception as exc:
+ logger.warning(
+ "Poll failed for batch %s: %s — will retry",
+ entry.provider_batch_id,
+ exc,
+ exc_info=True,
+ )
+ await _push_back(entry)
+ return
+
+ if status == "ended":
+ try:
+ rows = await download_batch_results(
+ provider=entry.provider,
+ provider_batch_id=entry.provider_batch_id,
+ api_key=api_key,
+ )
+ except Exception:
+ logger.exception(
+ "Download failed for batch %s — will retry once",
+ entry.provider_batch_id,
+ )
+ await _push_back(entry)
+ return
+ # Atomic claim: only one walker dispatches each batch.
+ # Without this, a slow remove_pending or a crash between
+ # _dispatch and remove_pending re-fires the whole callback
+ # chain (re-submits phases, re-runs apply, etc). The Lua
+ # script tombstones the batch_id and HDELs the pending
+ # entry in one indivisible step.
+ if not await _claim_dispatch(entry.provider_batch_id):
+ logger.info(
+ "Batch %s already dispatched — skipping",
+ entry.provider_batch_id,
+ )
+ # Refused claim = the per-batch tombstone exists, so this
+ # pending row is a zombie (same reasoning as the timeout
+ # path in _handle_timeout). Clear it — left alone it would
+ # be re-polled AND its results re-downloaded on every walk
+ # until the lifetime timeout finally reaps it.
+ await remove_pending(entry.provider_batch_id)
+ return
+ await _dispatch(entry, rows)
+ elif status == "failed":
+ if not await _claim_dispatch(entry.provider_batch_id):
+ # Refused claim = zombie row — clear without dispatching,
+ # same as the ended / timeout paths.
+ await remove_pending(entry.provider_batch_id)
+ return
+ await _dispatch_error(entry, error="provider reported failed")
+ else:
+ await _push_back(entry)
+
+
+async def _handle_timeout(entry: PendingEntry) -> None:
+ """Terminal path for entries past ``MAX_BATCH_LIFETIME_SECONDS``."""
+ logger.warning(
+ "Batch %s for namespace=%s exceeded %ds — dispatching timeout",
+ entry.provider_batch_id,
+ entry.callback_namespace,
+ MAX_BATCH_LIFETIME_SECONDS,
+ )
+ # Claim before dispatching — the same atomic tombstone + HDEL as
+ # the ended / failed paths — so a racing walker or a crash-replay
+ # can never fire the timeout callback twice (the dream handler
+ # releases the user's dream lock on error; a double fire could
+ # delete a NEWER pass's lock acquired after the first release).
+ # This path is also the backstop for entries whose namespace never
+ # got a handler registered: the claim still removes the entry, and
+ # _dispatch_error no-ops when the handler is absent.
+ if not await _claim_dispatch(entry.provider_batch_id):
+ # Refused claim = this batch already dispatched once, so the
+ # pending row is a zombie (e.g. re-enqueued by a buggy
+ # producer). Clear it WITHOUT dispatching — left alone it
+ # would be re-walked until the tombstone expires, after which
+ # the claim would win and fire a week-late duplicate dispatch.
+ await remove_pending(entry.provider_batch_id)
+ return
+ await _dispatch_error(
+ entry,
+ error="exceeded MAX_BATCH_LIFETIME_SECONDS without completion",
+ )
+
+
+async def _push_back(entry: PendingEntry) -> None:
+ """Re-queue *entry* with exponential backoff for a later walk."""
+ entry.poll_delay_seconds = _bump_delay(entry.poll_delay_seconds)
+ entry.next_poll_at = _next_poll_at(entry.poll_delay_seconds)
+ await update_pending(entry)
+
+
+# ---------------------------------------------------------------------------
+# Service
+# ---------------------------------------------------------------------------
+
+
+class BatchExecutor(AppService):
+ """Subprocess service that runs the BatchExecutor's poll loop.
+
+ Lives alongside ``Scheduler``, ``ExecutionManager``, etc. in
+ ``backend/app.py``. The service has no RPC surface today — callers
+ interact via the Redis-backed pending queue, not through methods.
+ Health check just confirms the loop thread is alive.
+ """
+
+ _loop_thread: threading.Thread | None = None
+ _shutdown_event: threading.Event
+
+ @classmethod
+ def get_port(cls) -> int:
+ return config.batch_executor_port
+
+ async def health_check(self) -> str:
+ if self._loop_thread is None or not self._loop_thread.is_alive():
+ raise UnhealthyServiceError("BatchExecutor loop thread is not running")
+ return await super().health_check()
+
+ def run_service(self):
+ from dotenv import load_dotenv
+
+ load_dotenv()
+ self._shutdown_event = threading.Event()
+ # Eagerly import callback modules so their handlers are
+ # registered before the first walk.
+ _bootstrap_callbacks()
+
+ self._loop_thread = threading.Thread(
+ target=self._run_loop,
+ daemon=True,
+ name="BatchExecutorLoop",
+ )
+ self._loop_thread.start()
+ logger.info("BatchExecutor poll loop started")
+ # Hand off to the base class which pumps the shared event loop
+ # so uvicorn's serve() coroutine (submitted from the FastAPI
+ # init thread) can actually bind the RPC port + handle health
+ # checks. Without this the AppService process appears alive
+ # but its port never binds — see Scheduler.run_service tail for
+ # the canonical pattern.
+ super().run_service()
+
+ def cleanup(self):
+ if hasattr(self, "_shutdown_event"):
+ self._shutdown_event.set()
+ super().cleanup()
+
+ def _run_loop(self) -> None:
+ loop = asyncio.new_event_loop()
+ asyncio.set_event_loop(loop)
+ try:
+ loop.run_until_complete(_loop_forever(self._shutdown_event))
+ finally:
+ loop.close()
+
+
+async def _loop_forever(shutdown: threading.Event) -> None:
+ """Walk the queue every ``WALK_INTERVAL_SECONDS`` until shutdown."""
+ while not shutdown.is_set():
+ try:
+ await walk_once(api_key_for=_default_api_key_for)
+ except Exception:
+ logger.exception("BatchExecutor walk failed — continuing")
+ # ``shutdown.wait`` returns True if shutdown was set during the
+ # sleep, letting us bail cleanly.
+ if shutdown.wait(WALK_INTERVAL_SECONDS):
+ break
+
+
+# ---------------------------------------------------------------------------
+# Bootstrap + default API key lookup
+# ---------------------------------------------------------------------------
+
+
+def _bootstrap_callbacks() -> None:
+ """Import every module that registers a batch result handler.
+
+ Lazy-import to avoid pulling dream-pass dependencies into modules
+ that just need the registry types. Each callback module's import
+ side-effect calls ``register_handler`` at module load.
+ """
+ try:
+ from backend.copilot.dream import batch_callbacks # noqa: F401
+ except Exception:
+ logger.exception(
+ "Failed to import dream batch_callbacks — "
+ "dream-namespace results will fail to dispatch"
+ )
+
+
+def _default_api_key_for(provider: ProviderLiteral) -> str | None:
+ """Look up the provider API key from settings / copilot config.
+
+ Anthropic batch is the only path today (Step 4a). When other
+ providers' batch APIs land they get added here.
+ """
+ if provider == "anthropic":
+ # The dream pass uses the copilot config's direct Anthropic key.
+ # Fall back to the shared settings key so other future callers
+ # (block-layer if it ever opts in) still work.
+ try:
+ from backend.copilot.config import ChatConfig
+
+ chat = ChatConfig()
+ if chat.direct_anthropic_api_key:
+ return chat.direct_anthropic_api_key
+ except Exception:
+ logger.debug("ChatConfig unavailable for batch API key lookup")
+ from backend.util.settings import Settings
+
+ return Settings().secrets.anthropic_api_key or None
+ return None
+
+
+# ---------------------------------------------------------------------------
+# Dispatch helpers
+# ---------------------------------------------------------------------------
+
+
+async def _dispatch(entry: PendingEntry, rows: list[BatchResultRow]) -> None:
+ """Route downloaded result rows to the namespace handler."""
+ handler = _HANDLERS.get(entry.callback_namespace)
+ if handler is None:
+ logger.warning(
+ "No handler registered for namespace=%s — batch %s results dropped",
+ entry.callback_namespace,
+ entry.provider_batch_id,
+ )
+ return
+ try:
+ await handler(entry, rows)
+ except Exception:
+ logger.exception(
+ "Handler for namespace=%s failed on batch %s — results NOT retried",
+ entry.callback_namespace,
+ entry.provider_batch_id,
+ )
+
+
+async def _dispatch_error(entry: PendingEntry, *, error: str) -> None:
+ """Dispatch a synthetic error row to the namespace handler.
+
+ Used when the provider itself reports the batch failed (or when we
+ timed out). Each ``custom_id`` the caller registered ends up with
+ an errored ``BatchResultRow`` so the handler can mark every phase
+ of the work failed and the JobStatus row gets a clean terminal state.
+ """
+ handler = _HANDLERS.get(entry.callback_namespace)
+ if handler is None:
+ return
+ try:
+ # Row construction stays inside the guard: ``payload`` is an
+ # open contract, so malformed ``custom_ids`` (wrong types, junk
+ # values) must be logged here rather than escape into the walk.
+ custom_ids: list[str] = entry.payload.get("custom_ids") or []
+ rows = [
+ BatchResultRow(
+ custom_id=cid,
+ content="",
+ input_tokens=0,
+ output_tokens=0,
+ error=error,
+ )
+ for cid in custom_ids
+ ]
+ await handler(entry, rows)
+ except Exception:
+ logger.exception(
+ "Error-path handler for namespace=%s failed on batch %s",
+ entry.callback_namespace,
+ entry.provider_batch_id,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Backoff math
+# ---------------------------------------------------------------------------
+
+
+def _bump_delay(current_seconds: int) -> int:
+ """Exponential backoff capped at ``MAX_POLL_DELAY_SECONDS``."""
+ return min(current_seconds * 2, MAX_POLL_DELAY_SECONDS)
+
+
+def _next_poll_at(delay_seconds: int) -> datetime:
+ return datetime.now(timezone.utc).replace(microsecond=0) + _seconds(delay_seconds)
+
+
+def _seconds(s: int):
+ from datetime import timedelta
+
+ return timedelta(seconds=s)
+
+
+# ---------------------------------------------------------------------------
+# Serialization
+# ---------------------------------------------------------------------------
+
+
+def _serialize(entry: PendingEntry) -> str:
+ return json.dumps(
+ {
+ "provider": entry.provider,
+ "provider_batch_id": entry.provider_batch_id,
+ "callback_namespace": entry.callback_namespace,
+ "submitted_at": entry.submitted_at.isoformat(),
+ "next_poll_at": entry.next_poll_at.isoformat(),
+ "poll_delay_seconds": entry.poll_delay_seconds,
+ "payload": entry.payload,
+ }
+ )
+
+
+def _deserialize(provider_batch_id: str | bytes, body: str | bytes) -> PendingEntry:
+ if isinstance(provider_batch_id, bytes):
+ provider_batch_id = provider_batch_id.decode("utf-8")
+ if isinstance(body, bytes):
+ body = body.decode("utf-8")
+ data = json.loads(body)
+ return PendingEntry(
+ provider=data["provider"],
+ provider_batch_id=data["provider_batch_id"],
+ callback_namespace=data["callback_namespace"],
+ submitted_at=datetime.fromisoformat(data["submitted_at"]),
+ next_poll_at=datetime.fromisoformat(data["next_poll_at"]),
+ poll_delay_seconds=int(
+ data.get("poll_delay_seconds") or INITIAL_POLL_DELAY_SECONDS
+ ),
+ payload=dict(data.get("payload") or {}),
+ )
diff --git a/autogpt_platform/backend/backend/executor/batch_executor_test.py b/autogpt_platform/backend/backend/executor/batch_executor_test.py
new file mode 100644
index 0000000000..3512a58c72
--- /dev/null
+++ b/autogpt_platform/backend/backend/executor/batch_executor_test.py
@@ -0,0 +1,581 @@
+"""Tests for the BatchExecutor poll loop + Redis pending queue."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timedelta, timezone
+from typing import Any
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from backend.executor.batch_executor import (
+ INITIAL_POLL_DELAY_SECONDS,
+ MAX_BATCH_LIFETIME_SECONDS,
+ MAX_POLL_DELAY_SECONDS,
+ PendingEntry,
+ _bump_delay,
+ _dispatch_error,
+ _next_poll_at,
+ clear_handlers_for_test,
+ enqueue_pending,
+ list_pending,
+ register_handler,
+ remove_pending,
+ update_pending,
+ walk_once,
+)
+from backend.util.llm.providers import BatchResultRow
+
+
+def fake_redis():
+ """In-memory hash-backed redis stub.
+
+ Also fakes the Lua ``eval`` path so the BatchExecutor's atomic
+ ``claim_batch_dispatch_atomic`` works under test — the real script
+ SETs a per-batch tombstone key (``NX EX``) + HDELs the pending
+ entry in one indivisible step; the fake replays the same effects.
+ """
+ store: dict[str, dict[str, str]] = {}
+ tombstones: dict[str, str] = {}
+
+ async def fake_hset(key, field, value):
+ store.setdefault(key, {})[field] = value
+ return 1
+
+ async def fake_hgetall(key):
+ return store.get(key, {})
+
+ async def fake_hdel(key, field):
+ if key in store and field in store[key]:
+ del store[key][field]
+ return 1
+ return 0
+
+ async def fake_delete(key):
+ store.pop(key, None)
+
+ async def fake_expire(key, ttl):
+ return 1
+
+ async def fake_eval(script, numkeys, *args):
+ # Only the claim_batch_dispatch_atomic shape is used by the
+ # BatchExecutor today. Branch on content so we don't pretend
+ # to know how to evaluate arbitrary Lua.
+ if "HDEL" in script:
+ pending_key, tombstone_key = args[0], args[1]
+ batch_id = args[2]
+ if tombstone_key in tombstones:
+ return 0
+ tombstones[tombstone_key] = "1"
+ store.setdefault(pending_key, {}).pop(batch_id, None)
+ return 1
+ raise NotImplementedError(f"fake_redis.eval: unknown script: {script!r}")
+
+ stub = AsyncMock()
+ stub.hset.side_effect = fake_hset
+ stub.hgetall.side_effect = fake_hgetall
+ stub.hdel.side_effect = fake_hdel
+ stub.delete.side_effect = fake_delete
+ stub.expire.side_effect = fake_expire
+ stub.eval.side_effect = fake_eval
+
+ async def fake_get_redis_async():
+ return stub
+
+ with patch(
+ "backend.data.redis_client.get_redis_async",
+ side_effect=fake_get_redis_async,
+ ):
+ yield stub, store
+
+
[email protected](autouse=True)
+def reset_handlers():
+ """Reset the in-memory handler registry between tests."""
+ clear_handlers_for_test()
+ yield
+ clear_handlers_for_test()
+
+
+def _entry(
+ *,
+ provider_batch_id: str = "msgbatch_1",
+ namespace: str = "dream_pass",
+ next_poll_at: datetime | None = None,
+ submitted_at: datetime | None = None,
+ delay: int = INITIAL_POLL_DELAY_SECONDS,
+ payload: dict[str, Any] | None = None,
+) -> PendingEntry:
+ now = datetime.now(timezone.utc)
+ return PendingEntry(
+ provider="anthropic",
+ provider_batch_id=provider_batch_id,
+ callback_namespace=namespace,
+ submitted_at=submitted_at or now,
+ next_poll_at=next_poll_at or now,
+ poll_delay_seconds=delay,
+ payload=payload or {"custom_ids": ["passid-1:consolidate"]},
+ )
+
+
+class TestQueueRoundtrip:
+ @pytest.mark.asyncio
+ async def test_enqueue_then_list_returns_entry(self, fake_redis):
+ await enqueue_pending(_entry())
+ entries = await list_pending()
+ assert len(entries) == 1
+ assert entries[0].provider_batch_id == "msgbatch_1"
+ assert entries[0].callback_namespace == "dream_pass"
+
+ @pytest.mark.asyncio
+ async def test_remove_drops_entry(self, fake_redis):
+ await enqueue_pending(_entry())
+ await remove_pending("msgbatch_1")
+ assert await list_pending() == []
+
+ @pytest.mark.asyncio
+ async def test_update_pending_overwrites(self, fake_redis):
+ entry = _entry(delay=30)
+ await enqueue_pending(entry)
+ entry.poll_delay_seconds = 120
+ entry.next_poll_at = datetime.now(timezone.utc) + timedelta(seconds=120)
+ await update_pending(entry)
+ result = (await list_pending())[0]
+ assert result.poll_delay_seconds == 120
+
+ @pytest.mark.asyncio
+ async def test_payload_roundtrips_through_json(self, fake_redis):
+ """Payload is opaque to the executor but must survive
+ serialization — phase mappings and pass_id ride in here."""
+ e = _entry(
+ payload={
+ "user_id": "u",
+ "pass_id": "p",
+ "job_id": "j",
+ "phase_for_custom_id": {"p:consolidate": "consolidate"},
+ }
+ )
+ await enqueue_pending(e)
+ back = (await list_pending())[0]
+ assert back.payload["user_id"] == "u"
+ assert back.payload["phase_for_custom_id"] == {"p:consolidate": "consolidate"}
+
+
+class TestWalkOnceDispatch:
+ @pytest.mark.asyncio
+ async def test_ended_batch_downloads_dispatches_removes(self, fake_redis):
+ seen_rows: list[list[BatchResultRow]] = []
+
+ async def fake_handler(entry, rows):
+ seen_rows.append(list(rows))
+
+ register_handler("dream_pass", fake_handler)
+ await enqueue_pending(_entry())
+
+ fake_row = BatchResultRow(
+ custom_id="passid-1:consolidate",
+ content='{"facts": []}',
+ input_tokens=10,
+ output_tokens=20,
+ )
+ with patch(
+ "backend.executor.batch_executor.poll_batch",
+ new=AsyncMock(return_value="ended"),
+ ), patch(
+ "backend.executor.batch_executor.download_batch_results",
+ new=AsyncMock(return_value=[fake_row]),
+ ):
+ await walk_once(api_key_for=lambda p: "sk-ant-test")
+
+ assert len(seen_rows) == 1
+ assert seen_rows[0][0].custom_id == "passid-1:consolidate"
+ # Entry must be removed after successful dispatch.
+ assert await list_pending() == []
+
+ @pytest.mark.asyncio
+ async def test_redispatch_after_claim_is_skipped_and_zombie_cleared(
+ self, fake_redis
+ ):
+ """Second walk that races on the same provider_batch_id must
+ not re-invoke the namespace handler — the atomic claim is the
+ only thing standing between "BatchExecutor saw the same ended
+ batch twice" and "user's billing/apply/phase-chain side effects
+ re-fire". Regression for the double-sanitize incident in prod.
+ The refused-claim zombie row must also be cleared — left alone
+ it would be re-polled AND re-downloaded every walk until the
+ lifetime timeout reaps it (up to ~24h).
+ """
+ seen_rows: list[list[BatchResultRow]] = []
+
+ async def fake_handler(entry, rows):
+ seen_rows.append(list(rows))
+
+ register_handler("dream_pass", fake_handler)
+ await enqueue_pending(_entry())
+
+ fake_row = BatchResultRow(
+ custom_id="passid-1:consolidate",
+ content='{"facts": []}',
+ input_tokens=1,
+ output_tokens=1,
+ )
+ with patch(
+ "backend.executor.batch_executor.poll_batch",
+ new=AsyncMock(return_value="ended"),
+ ), patch(
+ "backend.executor.batch_executor.download_batch_results",
+ new=AsyncMock(return_value=[fake_row]),
+ ):
+ # First walk: claim wins, handler fires.
+ await walk_once(api_key_for=lambda p: "sk-ant-test")
+ # Simulate a second walk that races (or a crash-recovery
+ # replay) — the same entry is re-added to pending, but the
+ # claim must refuse so the handler doesn't fire again.
+ await enqueue_pending(_entry())
+ await walk_once(api_key_for=lambda p: "sk-ant-test")
+
+ assert (
+ len(seen_rows) == 1
+ ), "handler should fire exactly once even on re-dispatch"
+ # The refused-claim zombie row is removed without dispatching
+ # so subsequent walks don't keep re-polling + re-downloading.
+ assert await list_pending() == []
+
+ @pytest.mark.asyncio
+ async def test_failed_batch_refused_claim_clears_zombie_without_dispatch(
+ self, fake_redis
+ ):
+ """Same zombie cleanup on the failed path: a refused claim
+ proves the batch already dispatched once, so the resurrected
+ pending row is cleared instead of being re-polled every walk
+ until the lifetime timeout."""
+ captured: list[list[BatchResultRow]] = []
+
+ async def fake_handler(entry, rows):
+ captured.append(list(rows))
+
+ register_handler("dream_pass", fake_handler)
+ await enqueue_pending(_entry())
+
+ with patch(
+ "backend.executor.batch_executor.poll_batch",
+ new=AsyncMock(return_value="failed"),
+ ):
+ # First walk: claim wins, synthetic error dispatches once.
+ await walk_once(api_key_for=lambda p: "sk-ant-test")
+ # Crash-replay resurrects the entry; the claim must refuse
+ # and the zombie row must be cleared without dispatching.
+ await enqueue_pending(_entry())
+ await walk_once(api_key_for=lambda p: "sk-ant-test")
+
+ assert len(captured) == 1, "error handler must fire exactly once"
+ assert await list_pending() == []
+
+ @pytest.mark.asyncio
+ async def test_processing_batch_bumps_delay_and_keeps_entry(self, fake_redis):
+ register_handler("dream_pass", AsyncMock())
+ await enqueue_pending(_entry(delay=30))
+ with patch(
+ "backend.executor.batch_executor.poll_batch",
+ new=AsyncMock(return_value="processing"),
+ ):
+ await walk_once(api_key_for=lambda p: "sk-ant-test")
+
+ entries = await list_pending()
+ assert len(entries) == 1
+ # Backoff doubled the delay
+ assert entries[0].poll_delay_seconds == 60
+
+ @pytest.mark.asyncio
+ async def test_failed_batch_dispatches_synthetic_error_and_removes(
+ self, fake_redis
+ ):
+ captured: list[list[BatchResultRow]] = []
+
+ async def fake_handler(entry, rows):
+ captured.append(list(rows))
+
+ register_handler("dream_pass", fake_handler)
+ await enqueue_pending(_entry())
+
+ with patch(
+ "backend.executor.batch_executor.poll_batch",
+ new=AsyncMock(return_value="failed"),
+ ):
+ await walk_once(api_key_for=lambda p: "sk-ant-test")
+
+ assert len(captured) == 1
+ assert captured[0][0].error == "provider reported failed"
+ assert await list_pending() == []
+
+ @pytest.mark.asyncio
+ async def test_skips_entry_whose_next_poll_is_in_future(self, fake_redis):
+ register_handler("dream_pass", AsyncMock())
+ future_time = datetime.now(timezone.utc) + timedelta(seconds=300)
+ await enqueue_pending(_entry(next_poll_at=future_time))
+ poll_mock = AsyncMock(return_value="ended")
+ with patch("backend.executor.batch_executor.poll_batch", poll_mock):
+ await walk_once(api_key_for=lambda p: "sk-ant-test")
+ poll_mock.assert_not_awaited()
+ # Entry still pending, no state change
+ assert len(await list_pending()) == 1
+
+ @pytest.mark.asyncio
+ async def test_expired_entry_dispatches_timeout_and_removes(self, fake_redis):
+ """Entries older than ``MAX_BATCH_LIFETIME_SECONDS`` get a
+ synthetic timeout error so the JobStatus row doesn't sit at
+ ``submitted`` forever even when the provider goes silent."""
+ captured: list[list[BatchResultRow]] = []
+
+ async def fake_handler(entry, rows):
+ captured.append(list(rows))
+
+ register_handler("dream_pass", fake_handler)
+ long_ago = datetime.now(timezone.utc) - timedelta(
+ seconds=MAX_BATCH_LIFETIME_SECONDS + 1
+ )
+ await enqueue_pending(_entry(submitted_at=long_ago))
+
+ poll_mock = AsyncMock()
+ with patch("backend.executor.batch_executor.poll_batch", poll_mock):
+ await walk_once(api_key_for=lambda p: "sk-ant-test")
+
+ poll_mock.assert_not_awaited()
+ assert captured[0][0].error == (
+ "exceeded MAX_BATCH_LIFETIME_SECONDS without completion"
+ )
+ assert await list_pending() == []
+
+ @pytest.mark.asyncio
+ async def test_timeout_dispatch_fires_exactly_once_across_replays(self, fake_redis):
+ """The timeout path must claim atomically before dispatching —
+ a crash-replay (entry re-added after the first dispatch) or a
+ racing second walker must not re-fire the handler. A double
+ fire would release the user's dream lock twice, potentially
+ deleting a NEWER pass's lock acquired after the first release.
+ """
+ captured: list[list[BatchResultRow]] = []
+
+ async def fake_handler(entry, rows):
+ captured.append(list(rows))
+
+ register_handler("dream_pass", fake_handler)
+ long_ago = datetime.now(timezone.utc) - timedelta(
+ seconds=MAX_BATCH_LIFETIME_SECONDS + 1
+ )
+ await enqueue_pending(_entry(submitted_at=long_ago))
+ await walk_once(api_key_for=lambda p: "sk-ant-test")
+ # Crash-replay: the same entry reappears in pending after the
+ # first timeout dispatch already claimed the batch.
+ await enqueue_pending(_entry(submitted_at=long_ago))
+ await walk_once(api_key_for=lambda p: "sk-ant-test")
+
+ assert len(captured) == 1, "timeout handler must fire exactly once"
+ # The replayed zombie row is cleared without dispatching so it
+ # can't be re-walked until the tombstone expires.
+ assert await list_pending() == []
+
+ @pytest.mark.asyncio
+ async def test_no_api_key_leaves_entry_in_queue(self, fake_redis):
+ """When the api_key_for factory returns None (rotation in
+ progress, key removed), we MUST leave the entry alone so the
+ retry catches it after the key is restored."""
+ register_handler("dream_pass", AsyncMock())
+ await enqueue_pending(_entry())
+ poll_mock = AsyncMock()
+ with patch("backend.executor.batch_executor.poll_batch", poll_mock):
+ await walk_once(api_key_for=lambda p: None)
+ poll_mock.assert_not_awaited()
+ # Entry must still be there for the next walk to retry.
+ assert len(await list_pending()) == 1
+
+ @pytest.mark.asyncio
+ async def test_poll_exception_bumps_delay_and_keeps_entry(self, fake_redis):
+ """A transient provider-side failure on poll mustn't lose the
+ entry — back off and try again."""
+ register_handler("dream_pass", AsyncMock())
+ await enqueue_pending(_entry(delay=30))
+ with patch(
+ "backend.executor.batch_executor.poll_batch",
+ new=AsyncMock(side_effect=RuntimeError("upstream 502")),
+ ):
+ await walk_once(api_key_for=lambda p: "sk-ant-test")
+ entries = await list_pending()
+ assert len(entries) == 1
+ assert entries[0].poll_delay_seconds == 60
+
+
+class TestUnknownNamespace:
+ @pytest.mark.asyncio
+ async def test_no_handler_leaves_entry_pending_for_recovery(self, fake_redis):
+ """A batch whose namespace nobody registered for must NOT be
+ claimed + dropped — the tombstone would make the results
+ irrecoverable even though the provider retains them for weeks.
+ Leave the entry pending (with backoff) so a deploy that fixes
+ the handler registration can still dispatch it."""
+ await enqueue_pending(_entry(namespace="orphan_namespace", delay=30))
+ poll_mock = AsyncMock(return_value="ended")
+ download_mock = AsyncMock(return_value=[])
+ with patch(
+ "backend.executor.batch_executor.poll_batch",
+ poll_mock,
+ ), patch(
+ "backend.executor.batch_executor.download_batch_results",
+ download_mock,
+ ):
+ await walk_once(api_key_for=lambda p: "sk-ant-test")
+
+ # We don't even poll: there's nobody to deliver results to.
+ poll_mock.assert_not_awaited()
+ download_mock.assert_not_awaited()
+ entries = await list_pending()
+ assert len(entries) == 1
+ # Backed off, not hot-looping the error every walk.
+ assert entries[0].poll_delay_seconds == 60
+
+ @pytest.mark.asyncio
+ async def test_no_handler_entry_is_reaped_by_lifetime_timeout(self, fake_redis):
+ """Leaving handler-less entries pending can't loop forever:
+ once the entry crosses MAX_BATCH_LIFETIME_SECONDS the timeout
+ path claims + removes it even with no handler registered
+ (_dispatch_error no-ops when the handler is absent)."""
+ long_ago = datetime.now(timezone.utc) - timedelta(
+ seconds=MAX_BATCH_LIFETIME_SECONDS + 1
+ )
+ await enqueue_pending(
+ _entry(namespace="orphan_namespace", submitted_at=long_ago)
+ )
+ await walk_once(api_key_for=lambda p: "sk-ant-test")
+ assert await list_pending() == []
+
+
+class TestWalkCrashGuard:
+ @pytest.mark.asyncio
+ async def test_crash_on_one_entry_does_not_starve_later_entries(self, fake_redis):
+ """An uncaught per-entry error (here: the api-key factory
+ blowing up) must be contained to that entry — entries after it
+ in hash order still get polled and dispatched, and the bad
+ entry stays pending for the next walk instead of aborting the
+ whole queue forever."""
+ dispatched: list[str] = []
+
+ async def fake_handler(entry, rows):
+ dispatched.append(entry.provider_batch_id)
+
+ register_handler("dream_pass", fake_handler)
+ await enqueue_pending(_entry(provider_batch_id="msgbatch_poison"))
+ await enqueue_pending(_entry(provider_batch_id="msgbatch_healthy"))
+
+ calls = {"count": 0}
+
+ def flaky_api_key_for(provider):
+ calls["count"] += 1
+ if calls["count"] == 1:
+ raise RuntimeError("settings backend exploded")
+ return "sk-ant-test"
+
+ fake_row = BatchResultRow(
+ custom_id="passid-1:consolidate",
+ content='{"facts": []}',
+ input_tokens=1,
+ output_tokens=1,
+ )
+ with patch(
+ "backend.executor.batch_executor.poll_batch",
+ new=AsyncMock(return_value="ended"),
+ ), patch(
+ "backend.executor.batch_executor.download_batch_results",
+ new=AsyncMock(return_value=[fake_row]),
+ ):
+ await walk_once(api_key_for=flaky_api_key_for)
+
+ assert dispatched == ["msgbatch_healthy"]
+ # The poisoned entry is untouched, ready for the next walk.
+ remaining = [e.provider_batch_id for e in await list_pending()]
+ assert remaining == ["msgbatch_poison"]
+
+ @pytest.mark.asyncio
+ async def test_naive_submitted_at_in_redis_is_coerced_and_walked(self, fake_redis):
+ """A producer that wrote naive isoformat timestamps must not
+ poison the walk — PendingEntry coerces naive datetimes to UTC
+ on rehydration, so ``now - submitted_at`` can't raise TypeError
+ and brick every entry behind it in hash order."""
+ stub, store = fake_redis
+ naive_iso = (
+ (datetime.now(timezone.utc) - timedelta(seconds=60))
+ .replace(tzinfo=None)
+ .isoformat()
+ )
+ store["{llm:batch}:pending"] = {
+ "msgbatch_naive": json.dumps(
+ {
+ "provider": "anthropic",
+ "provider_batch_id": "msgbatch_naive",
+ "callback_namespace": "dream_pass",
+ "submitted_at": naive_iso,
+ "next_poll_at": naive_iso,
+ "poll_delay_seconds": 30,
+ "payload": {"custom_ids": ["x"]},
+ }
+ )
+ }
+ register_handler("dream_pass", AsyncMock())
+
+ entries = await list_pending()
+ assert entries[0].submitted_at.tzinfo == timezone.utc
+ assert entries[0].next_poll_at.tzinfo == timezone.utc
+
+ with patch(
+ "backend.executor.batch_executor.poll_batch",
+ new=AsyncMock(return_value="processing"),
+ ):
+ await walk_once(api_key_for=lambda p: "sk-ant-test")
+
+ # Walked normally: still pending with the delay backed off.
+ assert (await list_pending())[0].poll_delay_seconds == 60
+
+ def test_naive_datetimes_are_coerced_to_utc_on_construction(self):
+ naive = datetime(2026, 1, 1, 12, 0, 0)
+ entry = PendingEntry(
+ provider="anthropic",
+ provider_batch_id="msgbatch_x",
+ callback_namespace="dream_pass",
+ submitted_at=naive,
+ next_poll_at=naive,
+ )
+ assert entry.submitted_at.tzinfo == timezone.utc
+ assert entry.next_poll_at.tzinfo == timezone.utc
+
+
+class TestDispatchErrorGuard:
+ @pytest.mark.asyncio
+ async def test_malformed_custom_ids_payload_is_contained(self):
+ """``payload`` is an open contract — junk ``custom_ids`` (here
+ an int instead of a list) must be caught inside _dispatch_error
+ rather than escaping after the batch was already claimed."""
+ handler = AsyncMock()
+ register_handler("dream_pass", handler)
+ entry = _entry(payload={"custom_ids": 123})
+
+ await _dispatch_error(entry, error="provider reported failed")
+
+ handler.assert_not_awaited()
+
+
+class TestBackoffMath:
+ def test_bump_delay_doubles_until_cap(self):
+ assert _bump_delay(30) == 60
+ assert _bump_delay(60) == 120
+ assert _bump_delay(120) == 240
+ assert _bump_delay(150) == 300
+ assert _bump_delay(MAX_POLL_DELAY_SECONDS) == MAX_POLL_DELAY_SECONDS
+ # Even way past the cap, stays capped
+ assert _bump_delay(MAX_POLL_DELAY_SECONDS * 10) == MAX_POLL_DELAY_SECONDS
+
+ def test_next_poll_at_is_in_future(self):
+ before = datetime.now(timezone.utc)
+ result = _next_poll_at(60)
+ after = datetime.now(timezone.utc) + timedelta(seconds=60)
+ assert before + timedelta(seconds=59) <= result <= after + timedelta(seconds=1)
diff --git a/autogpt_platform/backend/backend/executor/cost_tracking.py b/autogpt_platform/backend/backend/executor/cost_tracking.py
index 16e64f0215..bacaea5758 100644
--- a/autogpt_platform/backend/backend/executor/cost_tracking.py
+++ b/autogpt_platform/backend/backend/executor/cost_tracking.py
@@ -261,6 +261,14 @@ async def log_system_credential_cost(
meta: dict[str, Any] = {
"tracking_type": tracking_type,
"tracking_amount": tracking_amount,
+ # All block-layer LLM calls go through the sync provider
+ # dispatch today; tagging consistently with the rest of
+ # the platform (copilot chat, dream sync_baseline) so
+ # the admin cost-logs Path column never renders "—".
+ # When the block layer opts into flex/batch in the
+ # future, write the actual mode here.
+ "execution_path": "sync",
+ "source": "block",
}
if credit_cost is not None:
meta["credit_cost"] = credit_cost
diff --git a/autogpt_platform/backend/backend/executor/scheduler.py b/autogpt_platform/backend/backend/executor/scheduler.py
index 592b14e3fc..769865371d 100644
--- a/autogpt_platform/backend/backend/executor/scheduler.py
+++ b/autogpt_platform/backend/backend/executor/scheduler.py
@@ -29,6 +29,7 @@ from sqlalchemy import MetaData, create_engine
from backend.copilot.active_turns import ConcurrentTurnLimitError
from backend.copilot.executor.utils import schedule_turn
+from backend.copilot.graphiti.communities import rebuild_communities_for_user
from backend.copilot.model import create_chat_session, get_chat_session
from backend.copilot.optimize_blocks import optimize_block_descriptions
from backend.data.execution import GraphExecutionWithNodes
@@ -95,6 +96,11 @@ config = Config()
# Timeout constants
SCHEDULER_OPERATION_TIMEOUT_SECONDS = 300 # 5 minutes for scheduler operations
+# Dream / nightly / community-rebuild operations call into OpenRouter
+# with 50K-token prompts and FalkorDB-backed Leiden passes that
+# legitimately take >5 min. Match the dream lock's 30 min TTL so the
+# future resolves before the lock expires under the dream pass.
+SCHEDULER_DREAM_OPERATION_TIMEOUT_SECONDS = 1800
# The Stripe tier sweep pages through every active subscription, so it needs a
# generous ceiling relative to the per-op default.
STRIPE_RECONCILE_TIMEOUT_SECONDS = 1800 # 30 minutes
@@ -420,6 +426,449 @@ def cleanup_expired_files():
run_async(cleanup_expired_files_async())
+def execute_community_rebuild(user_id: str):
+ """Per-user Graphiti community rebuild (P-1.7).
+
+ Sync wrapper around the async ``rebuild_communities_for_user`` so it
+ can run on the APScheduler thread pool. Failures are caught inside
+ the coroutine; this wrapper logs the outcome.
+
+ Runtime flag gate: if ``GRAPHITI_COMMUNITIES_ENABLED`` flipped from
+ on→off after the schedule was registered, this body short-circuits
+ instead of running. Registration-time gating is in
+ ``add_community_rebuild_schedule``; this is the third layer of
+ defense (see ``copilot/dream/scheduling.py`` module docstring).
+ """
+ from backend.copilot.graphiti.config import is_communities_enabled_for_user
+
+ if not run_async(is_communities_enabled_for_user(user_id)):
+ logger.info(
+ "Community rebuild skipped for user %s — flag flipped off post-registration",
+ user_id[:12],
+ )
+ return
+
+ result = run_async(
+ rebuild_communities_for_user(user_id),
+ timeout=SCHEDULER_DREAM_OPERATION_TIMEOUT_SECONDS,
+ )
+ if result.get("error"):
+ logger.warning(
+ "Community rebuild errored for user %s: %s",
+ user_id[:12],
+ result["error"],
+ )
+ else:
+ logger.info(
+ "Community rebuild completed for user %s in %.1fs: %s",
+ user_id[:12],
+ result.get("elapsed_seconds") or 0.0,
+ result.get("communities_built"),
+ )
+
+
+def execute_nightly_batch_sync(user_id: str):
+ """Per-user nightly batch-family fan-out cron body.
+
+ Sync wrapper for APScheduler. The body inside
+ ``run_nightly_batch_submit`` sequentially invokes each enabled
+ submitter (dream pass, ratification supersession sweep, plus
+ future P2 / P3 / P4 / P11 stages). In real-batch mode each
+ submitter enqueues to the provider's batch API and returns in
+ seconds; results land asynchronously via the
+ ``copilot_batch_executor`` poller. In sync_baseline mode (today),
+ each submitter inlines its work and the function takes ~30-60s.
+
+ Runtime flag gate (layer 3 of the 3-layer design): if
+ ``DREAM_PASS_ENABLED`` flipped off after the cron was registered,
+ this body short-circuits before any submitter runs. The
+ consolidation removes the separate dream / ratification crons —
+ both are now submitters inside this single nightly cron.
+
+ Returns the typed ``NightlyBatchResult`` so the admin
+ ``*_with_status`` wrapper can persist it on the JobStatus row.
+ Returns ``None`` only when the runtime flag gate short-circuits
+ before the submitter runs.
+ """
+ from backend.copilot.dream.nightly_batch import (
+ NightlyBatchResult,
+ run_nightly_batch_submit,
+ )
+ from backend.util.feature_flag import Flag, is_feature_enabled
+
+ if not run_async(is_feature_enabled(Flag.DREAM_PASS_ENABLED, user_id)):
+ logger.info(
+ "Nightly batch skipped for user %s — DREAM_PASS_ENABLED flipped off",
+ user_id[:12],
+ )
+ return None
+
+ result: NightlyBatchResult = run_async(
+ run_nightly_batch_submit(user_id),
+ timeout=SCHEDULER_DREAM_OPERATION_TIMEOUT_SECONDS,
+ )
+ if result.error:
+ logger.warning(
+ "Nightly batch errored for user %s (nightly %s): %s",
+ user_id[:12],
+ result.nightly_id,
+ result.error,
+ )
+ elif result.skipped:
+ logger.info(
+ "Nightly batch skipped for user %s (nightly %s): %s",
+ user_id[:12],
+ result.nightly_id,
+ result.skip_reason,
+ )
+ else:
+ dream_writes = result.dream.consolidated_count if result.dream else 0
+ dream_proposals = result.dream.proposal_count if result.dream else 0
+ rat_ratified = result.ratification.ratified_count if result.ratification else 0
+ rat_superseded = (
+ result.ratification.superseded_count if result.ratification else 0
+ )
+ logger.info(
+ "Nightly batch completed for user %s in %.1fs (nightly %s): "
+ "dream_writes=%d dream_proposals=%d ratified=%d superseded=%d",
+ user_id[:12],
+ result.elapsed_seconds or 0.0,
+ result.nightly_id,
+ dream_writes,
+ dream_proposals,
+ rat_ratified,
+ rat_superseded,
+ )
+ return result
+
+
+# ---------------------------------------------------------------------------
+# *_with_status wrappers — used by fire-and-forget admin triggers
+# ---------------------------------------------------------------------------
+#
+# The original ``execute_*_sync`` bodies above are called from cron
+# triggers and return a result that the cron-fired path just logs.
+# The admin trigger pattern (POST returns 202 + job_id, frontend
+# polls) needs each work body to also write status transitions to the
+# Redis-backed JobStatus registry so the frontend can show
+# "Consolidating..." → "Recombining..." → "Complete (3.2 min)".
+#
+# Rather than thread ``job_id`` through every internal call, we wrap
+# the sync bodies with a thin status-recording wrapper. The wrapper
+# uses ``run_async`` to call the async JobStatus helpers from this
+# sync context (same bridge to the shared event loop the existing
+# bodies use).
+#
+# The cron path keeps calling the original ``execute_*_sync`` bodies
+# (no status writes). The admin path goes through these wrappers.
+
+
+def execute_nightly_batch_with_status(user_id: str, job_id: str):
+ """Run the nightly batch and record JobStatus transitions.
+
+ Used by the admin trigger pattern (POST /api/admin/memory/{user}/nightly
+ returns 202 + job_id; this fires asynchronously via
+ ``Scheduler.schedule_immediate_nightly_batch``).
+ """
+ from backend.copilot.dream.job_status import (
+ mark_complete,
+ mark_errored,
+ update_status_phase,
+ )
+
+ try:
+ run_async(
+ update_status_phase(kind="nightly", job_id=job_id, state="running"),
+ timeout=10,
+ )
+ except Exception:
+ # Status update failures must never crash the work body — the
+ # admin frontend will just see the row stuck at "queued" until
+ # mark_complete / mark_errored writes the terminal state.
+ logger.warning(
+ "Failed to mark nightly batch %s as running for user %s",
+ job_id[:12],
+ user_id[:12],
+ exc_info=True,
+ )
+
+ try:
+ result = execute_nightly_batch_sync(user_id)
+ except Exception as exc:
+ logger.exception(
+ "Admin-triggered nightly batch crashed for user %s job %s",
+ user_id[:12],
+ job_id[:12],
+ )
+ try:
+ run_async(
+ mark_errored(
+ kind="nightly",
+ job_id=job_id,
+ error=f"{type(exc).__name__}: {exc}",
+ ),
+ timeout=10,
+ )
+ except Exception:
+ logger.warning(
+ "Failed to record errored status for nightly %s", job_id[:12]
+ )
+ return
+
+ if result is None:
+ # Runtime flag gate short-circuit — record a minimal envelope
+ # so the polling client sees the run completed-as-skipped.
+ from backend.copilot.dream.nightly_batch import NightlyBatchResult
+
+ now = datetime.now(timezone.utc)
+ result = NightlyBatchResult(
+ user_id=user_id,
+ nightly_id="",
+ started_at=now,
+ completed_at=now,
+ elapsed_seconds=0.0,
+ skipped=True,
+ skip_reason="dream_pass_disabled_runtime",
+ )
+
+ # ``run_nightly_batch_submit`` never raises — a submitter CRASH is
+ # captured in ``NightlyBatchResult.error``, while a submitter that
+ # ran but reported its own failure carries it on its sub-result
+ # (``dream.error`` / ``ratification.error``) with the top-level
+ # error left unset. The admin row must read errored for all of
+ # these — otherwise the Memory Visualizer renders a failed dream
+ # as a successful nightly run (same contract as the dream-pass
+ # wrapper below).
+ error_parts = [
+ part
+ for part in (
+ result.error,
+ (
+ f"dream: {result.dream.error}"
+ if result.dream is not None and result.dream.error
+ else None
+ ),
+ (
+ f"ratification: {result.ratification.error}"
+ if result.ratification is not None and result.ratification.error
+ else None
+ ),
+ )
+ if part
+ ]
+ if error_parts:
+ try:
+ run_async(
+ mark_errored(
+ kind="nightly", job_id=job_id, error=" | ".join(error_parts)
+ ),
+ timeout=10,
+ )
+ except Exception:
+ logger.warning(
+ "Failed to mark nightly batch %s errored for user %s",
+ job_id[:12],
+ user_id[:12],
+ exc_info=True,
+ )
+ return
+
+ # The nightly fan-out is complete once every submitter has run —
+ # even when the dream submitter took a provider batch path and only
+ # ENQUEUED its pass (``result.dream_in_flight``). The dream batch
+ # callbacks finalize ``dream_pass`` JobStatus rows only, never this
+ # nightly row, so parking it at 'submitted' would leave it stuck
+ # with nothing ever writing a terminal state until the 6h TTL
+ # reaps it. Close it out as complete; ``dream_in_flight`` on the
+ # persisted envelope tells consumers the dream's apply step is
+ # still landing asynchronously via the BatchExecutor.
+ try:
+ run_async(
+ mark_complete(kind="nightly", job_id=job_id, result=result),
+ timeout=10,
+ )
+ except Exception:
+ logger.warning(
+ "Failed to mark nightly batch %s complete for user %s",
+ job_id[:12],
+ user_id[:12],
+ exc_info=True,
+ )
+
+
+def execute_dream_pass_with_status(user_id: str, job_id: str):
+ """Run the dream pass in isolation and record JobStatus transitions."""
+ from backend.copilot.dream.job_status import (
+ mark_complete,
+ mark_errored,
+ update_status_phase,
+ )
+ from backend.copilot.dream.orchestrator import execute_dream_pass
+
+ try:
+ run_async(
+ update_status_phase(kind="dream_pass", job_id=job_id, state="running"),
+ timeout=10,
+ )
+ except Exception:
+ logger.warning(
+ "Failed to mark dream pass %s as running for user %s",
+ job_id[:12],
+ user_id[:12],
+ exc_info=True,
+ )
+
+ try:
+ result = run_async(
+ execute_dream_pass(user_id, status_id=job_id),
+ timeout=SCHEDULER_DREAM_OPERATION_TIMEOUT_SECONDS,
+ )
+ except Exception as exc:
+ logger.exception(
+ "Admin-triggered dream pass crashed for user %s job %s",
+ user_id[:12],
+ job_id[:12],
+ )
+ try:
+ run_async(
+ mark_errored(
+ kind="dream_pass",
+ job_id=job_id,
+ error=f"{type(exc).__name__}: {exc}",
+ ),
+ timeout=10,
+ )
+ except Exception:
+ logger.warning(
+ "Failed to record errored status for dream pass %s", job_id[:12]
+ )
+ return
+
+ # The Anthropic batch path returns ``DreamPassResult`` as soon as
+ # the first phase submission is queued — the actual apply step
+ # runs in the BatchExecutor's callback chain when phase 3 lands
+ # (anywhere from minutes to ~1h later). In that case the dream
+ # batch_callbacks own the final ``mark_complete`` / ``mark_errored``
+ # transition; this wrapper must NOT close the row out early or
+ # the GET status endpoint will report ``complete`` while the batch
+ # is still processing.
+ if (
+ result.execution_path == "anthropic_batch"
+ and not result.skipped
+ and not result.error
+ ):
+ try:
+ run_async(
+ update_status_phase(
+ kind="dream_pass",
+ job_id=job_id,
+ state="submitted",
+ current_phase="consolidate",
+ ),
+ timeout=10,
+ )
+ except Exception:
+ logger.warning(
+ "Failed to flip dream pass %s to submitted for user %s",
+ job_id[:12],
+ user_id[:12],
+ exc_info=True,
+ )
+ return
+
+ if result.error:
+ # A sync pass that returned an error result must surface as
+ # errored, not complete — otherwise the Memory Visualizer renders
+ # a failed dream as a successful one.
+ try:
+ run_async(
+ mark_errored(kind="dream_pass", job_id=job_id, error=result.error),
+ timeout=10,
+ )
+ except Exception:
+ logger.warning(
+ "Failed to mark dream pass %s errored for user %s",
+ job_id[:12],
+ user_id[:12],
+ exc_info=True,
+ )
+ return
+
+ try:
+ run_async(
+ mark_complete(kind="dream_pass", job_id=job_id, result=result),
+ timeout=10,
+ )
+ except Exception:
+ logger.warning(
+ "Failed to mark dream pass %s complete for user %s",
+ job_id[:12],
+ user_id[:12],
+ exc_info=True,
+ )
+
+
+def execute_community_rebuild_with_status(user_id: str, job_id: str):
+ """Run a community rebuild and record JobStatus transitions."""
+ from backend.copilot.dream.job_status import (
+ mark_complete,
+ mark_errored,
+ update_status_phase,
+ )
+
+ try:
+ run_async(
+ update_status_phase(kind="rebuild", job_id=job_id, state="running"),
+ timeout=10,
+ )
+ except Exception:
+ logger.warning(
+ "Failed to mark community rebuild %s as running for user %s",
+ job_id[:12],
+ user_id[:12],
+ exc_info=True,
+ )
+
+ try:
+ result = run_async(
+ rebuild_communities_for_user(user_id),
+ timeout=SCHEDULER_DREAM_OPERATION_TIMEOUT_SECONDS,
+ )
+ except Exception as exc:
+ logger.exception(
+ "Admin-triggered community rebuild crashed for user %s job %s",
+ user_id[:12],
+ job_id[:12],
+ )
+ try:
+ run_async(
+ mark_errored(
+ kind="rebuild",
+ job_id=job_id,
+ error=f"{type(exc).__name__}: {exc}",
+ ),
+ timeout=10,
+ )
+ except Exception:
+ logger.warning(
+ "Failed to record errored status for rebuild %s", job_id[:12]
+ )
+ return
+
+ try:
+ run_async(
+ mark_complete(kind="rebuild", job_id=job_id, result=result),
+ timeout=10,
+ )
+ except Exception:
+ logger.warning(
+ "Failed to mark community rebuild %s complete for user %s",
+ job_id[:12],
+ user_id[:12],
+ exc_info=True,
+ )
+
+
def cleanup_oauth_tokens():
"""Clean up expired OAuth tokens from the database."""
@@ -1368,6 +1817,287 @@ class Scheduler(AppService):
"""Manually trigger embedding backfill for approved store agents."""
return ensure_embeddings_coverage()
+ # --- Graphiti community detection (P-1.7) ---
+ #
+ # Communities are off-by-default behind LD flag ``GRAPHITI_COMMUNITIES_ENABLED``
+ # at the call sites. The scheduler unconditionally accepts the
+ # registration call; callers gate on the flag. Rebuilds run weekly at
+ # user-local 04:00 Sunday to avoid the Leiden cost spike during active
+ # hours (and to stagger from a future per-user dream pass at 03:00).
+
+ @expose
+ def add_community_rebuild_schedule(
+ self,
+ user_id: str,
+ user_timezone: str = "UTC",
+ ) -> dict:
+ """Register a weekly community rebuild for one user.
+
+ Gated by ``Flag.GRAPHITI_COMMUNITIES_ENABLED`` per-user. When the
+ flag is off the call is a no-op — returns a structured "skipped"
+ dict so callers see the same shape as a successful registration.
+ """
+ from backend.copilot.graphiti.config import is_communities_enabled_for_user
+
+ if not run_async(is_communities_enabled_for_user(user_id)):
+ logger.info(
+ "Community rebuild registration skipped for user %s — "
+ "GRAPHITI_COMMUNITIES_ENABLED flag is off.",
+ user_id[:12],
+ )
+ return {
+ "id": None,
+ "user_id": user_id,
+ "user_timezone": user_timezone,
+ "next_run_time": None,
+ "skipped": True,
+ "reason": "graphiti_communities_disabled",
+ }
+
+ if not user_timezone:
+ user_timezone = "UTC"
+
+ job_id = f"community_rebuild_{user_id}"
+ job = self.scheduler.add_job(
+ execute_community_rebuild,
+ kwargs={"user_id": user_id},
+ trigger=CronTrigger.from_crontab("0 4 * * 0", timezone=user_timezone),
+ id=job_id,
+ name=f"Graphiti community rebuild for {user_id[:12]}",
+ jobstore=Jobstores.EXECUTION.value,
+ replace_existing=True,
+ max_instances=1,
+ )
+ logger.info(
+ "Registered community rebuild job %s for user %s in tz %s",
+ job.id,
+ user_id[:12],
+ user_timezone,
+ )
+ return {
+ "id": job.id,
+ "user_id": user_id,
+ "user_timezone": user_timezone,
+ "next_run_time": (
+ job.next_run_time.isoformat() if job.next_run_time else None
+ ),
+ }
+
+ @expose
+ def delete_community_rebuild_schedule(self, user_id: str) -> bool:
+ """Remove the weekly community rebuild for one user."""
+ job_id = f"community_rebuild_{user_id}"
+ job = self.scheduler.get_job(job_id, jobstore=Jobstores.EXECUTION.value)
+ if not job:
+ return False
+ job.remove()
+ logger.info("Removed community rebuild job for user %s", user_id[:12])
+ return True
+
+ @expose
+ def execute_community_rebuild_pass(self, user_id: str, force: bool = False) -> dict:
+ """Manually trigger a community rebuild for one user (bypasses cron).
+
+ Set ``force=True`` to bypass the activity gate inside
+ ``rebuild_communities_for_user`` — useful for admin debugging
+ when you want to rebuild even on an unchanged graph.
+ """
+ return run_async(
+ rebuild_communities_for_user(user_id, force=force),
+ timeout=SCHEDULER_DREAM_OPERATION_TIMEOUT_SECONDS,
+ )
+
+ # --- Dream nightly batch (P-0.2 + P-0.4 consolidated) ---
+ #
+ # ONE per-user cron at user-local 03:00 fans out all batch-family
+ # work (dream pass, ratification supersession sweep, plus future
+ # P2 / P3 / P4 / P11 submitters). The separate dream-pass and
+ # ratification-pass crons that previously existed are gone — both
+ # are now submitters inside this nightly cron's body.
+ #
+ # In real-batch mode this cron returns in seconds (each submitter
+ # just enqueues to the provider's batch API; results land hours
+ # later via the ``copilot_batch_executor`` poller). In
+ # sync_baseline mode (today, until P0.1 adapter stubs are filled
+ # in) each submitter inlines its work.
+ #
+ # ``execute_ratification_pass_now`` remains as an admin-callable
+ # sync endpoint because ratification is Cypher-only and finishes in
+ # seconds (no batch SLA to amortise). The dream pass + nightly fan-
+ # out moved to fire-and-forget + JobStatus polling — see
+ # ``schedule_immediate_*`` below — so their old sync ``_now``
+ # methods were removed in Step 9 of the providers rollout.
+
+ @expose
+ def add_nightly_batch_schedule(
+ self,
+ user_id: str,
+ user_timezone: str = "UTC",
+ ) -> dict:
+ """Register the nightly batch-family fan-out cron for one user.
+
+ Gated by ``Flag.DREAM_PASS_ENABLED`` per-user. When the flag
+ is off the call is a no-op — returns a structured "skipped"
+ dict matching the shape of a successful registration.
+ Defense-in-depth: the auto-registration helper in
+ ``copilot/dream/scheduling.py`` already gates this, but direct
+ callers (admin endpoint, ad-hoc scripts) bypass that helper.
+ """
+ from backend.util.feature_flag import Flag, is_feature_enabled
+
+ if not run_async(is_feature_enabled(Flag.DREAM_PASS_ENABLED, user_id)):
+ logger.info(
+ "Nightly batch registration skipped for user %s — "
+ "DREAM_PASS_ENABLED flag is off.",
+ user_id[:12],
+ )
+ return {
+ "id": None,
+ "user_id": user_id,
+ "user_timezone": user_timezone,
+ "next_run_time": None,
+ "skipped": True,
+ "reason": "dream_pass_disabled",
+ }
+
+ if not user_timezone:
+ user_timezone = "UTC"
+
+ job_id = f"dream_nightly_batch_{user_id}"
+ job = self.scheduler.add_job(
+ execute_nightly_batch_sync,
+ kwargs={"user_id": user_id},
+ trigger=CronTrigger.from_crontab("0 3 * * *", timezone=user_timezone),
+ id=job_id,
+ name=f"Dream nightly batch for {user_id[:12]}",
+ jobstore=Jobstores.EXECUTION.value,
+ replace_existing=True,
+ max_instances=1,
+ )
+ logger.info(
+ "Registered nightly batch job %s for user %s in tz %s",
+ job.id,
+ user_id[:12],
+ user_timezone,
+ )
+ return {
+ "id": job.id,
+ "user_id": user_id,
+ "user_timezone": user_timezone,
+ "next_run_time": (
+ job.next_run_time.isoformat() if job.next_run_time else None
+ ),
+ }
+
+ @expose
+ def delete_nightly_batch_schedule(self, user_id: str) -> bool:
+ """Remove the nightly batch cron for one user."""
+ job_id = f"dream_nightly_batch_{user_id}"
+ job = self.scheduler.get_job(job_id, jobstore=Jobstores.EXECUTION.value)
+ if not job:
+ return False
+ job.remove()
+ logger.info("Removed nightly batch job for user %s", user_id[:12])
+ return True
+
+ # ---- Fire-and-forget admin triggers (JobStatus-aware) -------------------
+ #
+ # The ``schedule_immediate_*`` methods schedule the matching
+ # ``*_with_status`` wrapper to run on the APScheduler thread pool
+ # at the current time, then return immediately. The admin route
+ # writes the initial ``state="queued"`` row before calling these;
+ # the wrapper writes ``running`` / phase transitions / ``complete``
+ # / ``errored``. The admin frontend polls a GET endpoint to render
+ # progress without holding an HTTP connection open for minutes.
+
+ @expose
+ def schedule_immediate_nightly_batch(self, user_id: str, job_id: str) -> dict:
+ """Schedule a one-shot nightly batch run keyed by ``job_id``.
+
+ The admin endpoint that calls this has already written an
+ initial ``state="queued"`` JobStatus row, so this method just
+ adds the APScheduler job and returns immediately. The wrapper
+ body is responsible for advancing the status row.
+ """
+ import datetime as _dt
+
+ scheduler_job_id = f"adhoc_nightly_{job_id}"
+ self.scheduler.add_job(
+ execute_nightly_batch_with_status,
+ kwargs={"user_id": user_id, "job_id": job_id},
+ trigger="date",
+ run_date=_dt.datetime.now(_dt.timezone.utc),
+ id=scheduler_job_id,
+ jobstore=Jobstores.EXECUTION.value,
+ replace_existing=False,
+ max_instances=1,
+ )
+ logger.info(
+ "Scheduled immediate nightly batch %s for user %s",
+ job_id[:12],
+ user_id[:12],
+ )
+ return {"scheduled": True, "job_id": job_id, "kind": "nightly"}
+
+ @expose
+ def schedule_immediate_dream_pass(self, user_id: str, job_id: str) -> dict:
+ """Schedule a one-shot dream pass run keyed by ``job_id``."""
+ import datetime as _dt
+
+ scheduler_job_id = f"adhoc_dream_{job_id}"
+ self.scheduler.add_job(
+ execute_dream_pass_with_status,
+ kwargs={"user_id": user_id, "job_id": job_id},
+ trigger="date",
+ run_date=_dt.datetime.now(_dt.timezone.utc),
+ id=scheduler_job_id,
+ jobstore=Jobstores.EXECUTION.value,
+ replace_existing=False,
+ max_instances=1,
+ )
+ logger.info(
+ "Scheduled immediate dream pass %s for user %s",
+ job_id[:12],
+ user_id[:12],
+ )
+ return {"scheduled": True, "job_id": job_id, "kind": "dream_pass"}
+
+ @expose
+ def schedule_immediate_community_rebuild(self, user_id: str, job_id: str) -> dict:
+ """Schedule a one-shot community rebuild run keyed by ``job_id``."""
+ import datetime as _dt
+
+ scheduler_job_id = f"adhoc_rebuild_{job_id}"
+ self.scheduler.add_job(
+ execute_community_rebuild_with_status,
+ kwargs={"user_id": user_id, "job_id": job_id},
+ trigger="date",
+ run_date=_dt.datetime.now(_dt.timezone.utc),
+ id=scheduler_job_id,
+ jobstore=Jobstores.EXECUTION.value,
+ replace_existing=False,
+ max_instances=1,
+ )
+ logger.info(
+ "Scheduled immediate community rebuild %s for user %s",
+ job_id[:12],
+ user_id[:12],
+ )
+ return {"scheduled": True, "job_id": job_id, "kind": "rebuild"}
+
+ @expose
+ def execute_ratification_pass_now(self, user_id: str) -> dict:
+ """Run the ratification sweep in isolation (admin debug endpoint).
+
+ Bypasses the nightly batch cron and runs only the ratification
+ supersession sweep. Useful for testing ratification logic
+ without waiting for / running the full nightly fan-out.
+ """
+ from backend.copilot.dream.ratification import run_ratification_pass
+
+ result = run_async(run_ratification_pass(user_id))
+ return result.model_dump(mode="json")
+
class SchedulerClient(AppServiceClient):
@classmethod
@@ -1383,3 +2113,37 @@ class SchedulerClient(AppServiceClient):
)
# Polymorphic list — preferred for new callers; returns both kinds.
get_execution_schedules = endpoint_to_async(Scheduler.get_execution_schedules)
+
+ add_community_rebuild_schedule = endpoint_to_async(
+ Scheduler.add_community_rebuild_schedule
+ )
+ delete_community_rebuild_schedule = endpoint_to_async(
+ Scheduler.delete_community_rebuild_schedule
+ )
+ execute_community_rebuild_pass = endpoint_to_async(
+ Scheduler.execute_community_rebuild_pass
+ )
+
+ add_nightly_batch_schedule = endpoint_to_async(Scheduler.add_nightly_batch_schedule)
+ delete_nightly_batch_schedule = endpoint_to_async(
+ Scheduler.delete_nightly_batch_schedule
+ )
+
+ # Ratification stays synchronous — Cypher-only, finishes in seconds.
+ # The admin viz "Ratification" button still calls this directly.
+ execute_ratification_pass_now = endpoint_to_async(
+ Scheduler.execute_ratification_pass_now
+ )
+
+ # Fire-and-forget admin triggers — the admin route writes an
+ # initial JobStatus row, calls these, and returns 202 immediately.
+ # Frontend polls the JobStatus GET endpoint to render progress.
+ schedule_immediate_nightly_batch = endpoint_to_async(
+ Scheduler.schedule_immediate_nightly_batch
+ )
+ schedule_immediate_dream_pass = endpoint_to_async(
+ Scheduler.schedule_immediate_dream_pass
+ )
+ schedule_immediate_community_rebuild = endpoint_to_async(
+ Scheduler.schedule_immediate_community_rebuild
+ )
diff --git a/autogpt_platform/backend/backend/executor/scheduler_test.py b/autogpt_platform/backend/backend/executor/scheduler_test.py
index 55d7e267cf..724750dacf 100644
--- a/autogpt_platform/backend/backend/executor/scheduler_test.py
+++ b/autogpt_platform/backend/backend/executor/scheduler_test.py
@@ -1,5 +1,6 @@
import uuid
from datetime import datetime, timedelta, timezone
+from unittest.mock import MagicMock, patch
import pytest
import pytz
@@ -7,7 +8,12 @@ from apscheduler.triggers.cron import CronTrigger
from backend.api.model import CreateGraph
from backend.data import db
-from backend.executor.scheduler import _build_trigger, _normalize_cron_day_of_week
+from backend.executor.scheduler import (
+ Jobstores,
+ Scheduler,
+ _build_trigger,
+ _normalize_cron_day_of_week,
+)
from backend.usecases.sample import create_test_graph, create_test_user
from backend.util.clients import get_scheduler_client
from backend.util.test import SpinTestServer
@@ -47,6 +53,434 @@ async def test_agent_schedule(server: SpinTestServer):
assert len(schedules) == 0
+# ---------------------------------------------------------------------------
+# Community rebuild @expose methods — lightweight unit tests
+#
+# Avoid SpinTestServer for these (Postgres + RabbitMQ overhead is overkill
+# for verifying job-args plumbing). Instantiate Scheduler via __new__ so we
+# skip AppService.__init__ side effects, then assign a MagicMock to
+# ``self.scheduler`` (the APScheduler instance) and assert on its add_job /
+# get_job / remove_job calls.
+# ---------------------------------------------------------------------------
+
+
+def _stub_scheduler() -> Scheduler:
+ """Build a Scheduler with all real init skipped — for @expose unit tests."""
+ s = Scheduler.__new__(Scheduler)
+ s.scheduler = MagicMock()
+ return s
+
+
+class TestAddCommunityRebuildSchedule:
+ def test_registers_with_expected_cron_and_jobstore(self) -> None:
+ s = _stub_scheduler()
+ fake_job = MagicMock(id="community_rebuild_abc", next_run_time=None)
+ s.scheduler.add_job.return_value = fake_job
+
+ with patch("backend.executor.scheduler.run_async", return_value=True):
+ result = s.add_community_rebuild_schedule(
+ user_id="abc", user_timezone="America/New_York"
+ )
+
+ s.scheduler.add_job.assert_called_once()
+ kwargs = s.scheduler.add_job.call_args.kwargs
+ # Job id matches the documented per-user convention.
+ assert kwargs["id"] == "community_rebuild_abc"
+ # Single-fire safety + drop-in replace.
+ assert kwargs["max_instances"] == 1
+ assert kwargs["replace_existing"] is True
+ # Lands in the EXECUTION jobstore (Postgres-backed).
+ assert kwargs["jobstore"] == Jobstores.EXECUTION.value
+ # Cron is 04:00 Sunday per spec (P-1.7). Trigger repr is the
+ # most stable surface to assert against without depending on
+ # APScheduler's internal CronTrigger.field accessors.
+ trigger_repr = repr(kwargs["trigger"])
+ assert "hour='4'" in trigger_repr
+ assert "day_of_week='sun'" in trigger_repr or "day_of_week='0'" in trigger_repr
+ # User kwargs are passed through to the job body.
+ assert kwargs["kwargs"] == {"user_id": "abc"}
+
+ # Returned dict surfaces job id and tz.
+ assert result["id"] == "community_rebuild_abc"
+ assert result["user_id"] == "abc"
+ assert result["user_timezone"] == "America/New_York"
+
+ def test_empty_timezone_falls_back_to_utc(self) -> None:
+ s = _stub_scheduler()
+ s.scheduler.add_job.return_value = MagicMock(
+ id="community_rebuild_abc", next_run_time=None
+ )
+ with patch("backend.executor.scheduler.run_async", return_value=True):
+ result = s.add_community_rebuild_schedule(user_id="abc", user_timezone="")
+ assert result["user_timezone"] == "UTC"
+
+ def test_next_run_time_isoformatted_when_present(self) -> None:
+ s = _stub_scheduler()
+ nrt = datetime(2026, 5, 24, 4, 0, tzinfo=timezone.utc)
+ s.scheduler.add_job.return_value = MagicMock(
+ id="community_rebuild_abc", next_run_time=nrt
+ )
+ with patch("backend.executor.scheduler.run_async", return_value=True):
+ result = s.add_community_rebuild_schedule(user_id="abc")
+ assert result["next_run_time"] == nrt.isoformat()
+
+
+class TestDeleteCommunityRebuildSchedule:
+ def test_returns_true_when_job_exists(self) -> None:
+ s = _stub_scheduler()
+ fake_job = MagicMock()
+ s.scheduler.get_job.return_value = fake_job
+ assert s.delete_community_rebuild_schedule("abc") is True
+ # Look up by the canonical job id
+ s.scheduler.get_job.assert_called_once_with(
+ "community_rebuild_abc", jobstore=Jobstores.EXECUTION.value
+ )
+ fake_job.remove.assert_called_once()
+
+ def test_returns_false_when_no_job(self) -> None:
+ s = _stub_scheduler()
+ s.scheduler.get_job.return_value = None
+ assert s.delete_community_rebuild_schedule("abc") is False
+
+
+class TestExecuteCommunityRebuildPass:
+ def test_default_force_false(self) -> None:
+ s = _stub_scheduler()
+ sentinel = {"ok": True}
+ with (
+ patch(
+ "backend.executor.scheduler.run_async", return_value=sentinel
+ ) as run_async_mock,
+ patch(
+ "backend.executor.scheduler.rebuild_communities_for_user"
+ ) as rebuild_mock,
+ ):
+ result = s.execute_community_rebuild_pass(user_id="abc")
+ # We forwarded to rebuild_communities_for_user with force=False default
+ rebuild_mock.assert_called_once_with("abc", force=False)
+ # And ran it through run_async (the sync-over-async bridge)
+ run_async_mock.assert_called_once()
+ assert result == sentinel
+
+ def test_force_propagates_through(self) -> None:
+ s = _stub_scheduler()
+ with (
+ patch("backend.executor.scheduler.run_async", return_value={}),
+ patch(
+ "backend.executor.scheduler.rebuild_communities_for_user"
+ ) as rebuild_mock,
+ ):
+ s.execute_community_rebuild_pass(user_id="abc", force=True)
+ rebuild_mock.assert_called_once_with("abc", force=True)
+
+
+# ---------------------------------------------------------------------------
+# Dream nightly batch @expose methods — registration-time flag gating
+#
+# The dream pass and ratification pass crons were consolidated into a
+# single nightly batch cron. The dream pass + nightly fan-out admin
+# entry points moved to fire-and-forget + JobStatus polling via
+# ``schedule_immediate_*``; only ``execute_ratification_pass_now``
+# remains as a sync @expose method (Cypher-only, finishes in seconds).
+# ---------------------------------------------------------------------------
+
+
+class TestAddNightlyBatchSchedule:
+ def test_flag_on_registers_with_03_00_daily_cron(self) -> None:
+ s = _stub_scheduler()
+ s.scheduler.add_job.return_value = MagicMock(
+ id="dream_nightly_batch_abc", next_run_time=None
+ )
+ with patch("backend.executor.scheduler.run_async", return_value=True):
+ result = s.add_nightly_batch_schedule(
+ user_id="abc", user_timezone="America/New_York"
+ )
+ kwargs = s.scheduler.add_job.call_args.kwargs
+ assert kwargs["id"] == "dream_nightly_batch_abc"
+ assert kwargs["max_instances"] == 1
+ assert kwargs["replace_existing"] is True
+ assert kwargs["jobstore"] == Jobstores.EXECUTION.value
+ trigger_repr = repr(kwargs["trigger"])
+ # Daily 03:00 cron — same as the former dream pass cron, but
+ # carries the consolidated submitter set.
+ assert "hour='3'" in trigger_repr
+ assert result["id"] == "dream_nightly_batch_abc"
+ assert result.get("skipped") is not True
+
+ def test_flag_off_returns_skipped_dict_without_calling_add_job(self) -> None:
+ """Layer 2 of the 3-layer flag gating — direct callers
+ (admin endpoint, ad-hoc scripts) that bypass
+ ``ensure_dream_system_scheduled`` must STILL be refused when
+ the flag is off."""
+ s = _stub_scheduler()
+ with patch("backend.executor.scheduler.run_async", return_value=False):
+ result = s.add_nightly_batch_schedule(user_id="abc")
+ s.scheduler.add_job.assert_not_called()
+ assert result == {
+ "id": None,
+ "user_id": "abc",
+ "user_timezone": "UTC",
+ "next_run_time": None,
+ "skipped": True,
+ "reason": "dream_pass_disabled",
+ }
+
+
+class TestDeleteNightlyBatchSchedule:
+ def test_returns_true_when_job_exists(self) -> None:
+ s = _stub_scheduler()
+ fake_job = MagicMock()
+ s.scheduler.get_job.return_value = fake_job
+ assert s.delete_nightly_batch_schedule("abc") is True
+ s.scheduler.get_job.assert_called_once_with(
+ "dream_nightly_batch_abc", jobstore=Jobstores.EXECUTION.value
+ )
+ fake_job.remove.assert_called_once()
+
+ def test_returns_false_when_no_job(self) -> None:
+ s = _stub_scheduler()
+ s.scheduler.get_job.return_value = None
+ assert s.delete_nightly_batch_schedule("abc") is False
+
+
+# ---------------------------------------------------------------------------
+# Execution-time flag gate for the nightly batch cron (layer 3)
+# ---------------------------------------------------------------------------
+
+
+class TestExecuteNightlyBatchSyncRuntimeGate:
+ def test_flag_off_short_circuits_before_calling_submitter_fanout(self) -> None:
+ """``DREAM_PASS_ENABLED`` flipped off after registration → the
+ cron still fires but never calls ``run_nightly_batch_submit``,
+ so no submitter runs."""
+ from backend.executor.scheduler import execute_nightly_batch_sync
+
+ with (
+ patch(
+ "backend.executor.scheduler.run_async", return_value=False
+ ) as run_async_mock,
+ patch(
+ "backend.copilot.dream.nightly_batch.run_nightly_batch_submit"
+ ) as fanout_mock,
+ ):
+ execute_nightly_batch_sync("abc")
+
+ # Exactly one run_async call (the flag check). The fan-out
+ # function never gets invoked.
+ run_async_mock.assert_called_once()
+ fanout_mock.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# JobStatus transitions for the admin-triggered nightly fan-out wrapper
+# ---------------------------------------------------------------------------
+
+
+def _nightly_result(**overrides):
+ from backend.copilot.dream.nightly_batch import NightlyBatchResult
+
+ defaults = {
+ "user_id": "abc",
+ "nightly_id": "nightly-1",
+ "started_at": datetime.now(timezone.utc),
+ "completed_at": datetime.now(timezone.utc),
+ "elapsed_seconds": 1.0,
+ }
+ defaults.update(overrides)
+ return NightlyBatchResult(**defaults)
+
+
+def _dream_result(**overrides):
+ from backend.copilot.dream.schemas import DreamPassResult
+
+ defaults = {"user_id": "abc", "pass_id": "pass-1"}
+ defaults.update(overrides)
+ return DreamPassResult(**defaults)
+
+
+def _ratification_result(**overrides):
+ from backend.copilot.dream.ratification import RatificationResult
+
+ defaults = {"user_id": "abc", "started_at": datetime.now(timezone.utc)}
+ defaults.update(overrides)
+ return RatificationResult(**defaults)
+
+
+def _run_nightly_wrapper(result):
+ """Invoke the wrapper with the work body + status writers mocked out.
+
+ ``mark_*`` / ``update_status_phase`` are imported inside the wrapper,
+ so patching them at their definition module intercepts the call-time
+ import. ``run_async`` is stubbed so the (mocked, non-coroutine)
+ status writes don't hit an event loop.
+ """
+ from backend.executor.scheduler import execute_nightly_batch_with_status
+
+ with (
+ patch("backend.executor.scheduler.run_async"),
+ patch(
+ "backend.executor.scheduler.execute_nightly_batch_sync",
+ return_value=result,
+ ),
+ patch("backend.copilot.dream.job_status.mark_complete") as complete_mock,
+ patch("backend.copilot.dream.job_status.mark_errored") as errored_mock,
+ patch("backend.copilot.dream.job_status.update_status_phase") as phase_mock,
+ ):
+ execute_nightly_batch_with_status("abc", "job-1")
+ return complete_mock, errored_mock, phase_mock
+
+
+class TestExecuteNightlyBatchWithStatus:
+ def test_clean_sync_result_marks_complete(self) -> None:
+ result = _nightly_result(dream=_dream_result())
+ complete_mock, errored_mock, phase_mock = _run_nightly_wrapper(result)
+
+ complete_mock.assert_called_once_with(
+ kind="nightly", job_id="job-1", result=result
+ )
+ errored_mock.assert_not_called()
+ # Only the initial 'running' transition — never 'submitted'.
+ phase_mock.assert_called_once_with(
+ kind="nightly", job_id="job-1", state="running"
+ )
+
+ def test_error_result_marks_errored_not_complete(self) -> None:
+ """``run_nightly_batch_submit`` never raises — a crashed dream
+ submitter surfaces in ``result.error``. The admin row must read
+ 'errored', not 'complete'."""
+ result = _nightly_result(error="dream: boom")
+ complete_mock, errored_mock, _ = _run_nightly_wrapper(result)
+
+ errored_mock.assert_called_once_with(
+ kind="nightly", job_id="job-1", error="dream: boom"
+ )
+ complete_mock.assert_not_called()
+
+ def test_dream_error_result_marks_errored_not_complete(self) -> None:
+ """A dream submitter that ran but returned an error RESULT
+ (``result.dream.error`` set, top-level error unset) must also
+ surface as errored — otherwise the admin row reads 'complete'
+ for a run whose dream pass entirely failed."""
+ result = _nightly_result(dream=_dream_result(error="phase 1 LLM down"))
+ complete_mock, errored_mock, _ = _run_nightly_wrapper(result)
+
+ errored_mock.assert_called_once_with(
+ kind="nightly", job_id="job-1", error="dream: phase 1 LLM down"
+ )
+ complete_mock.assert_not_called()
+
+ def test_ratification_error_result_marks_errored_not_complete(self) -> None:
+ """Same contract for the ratification sub-result — an error
+ result from the sweep must not be swallowed by mark_complete."""
+ result = _nightly_result(
+ dream=_dream_result(),
+ ratification=_ratification_result(error="graph down"),
+ )
+ complete_mock, errored_mock, _ = _run_nightly_wrapper(result)
+
+ errored_mock.assert_called_once_with(
+ kind="nightly", job_id="job-1", error="ratification: graph down"
+ )
+ complete_mock.assert_not_called()
+
+ def test_crash_and_error_result_errors_are_joined(self) -> None:
+ """A top-level crash capture and a submitter error result can
+ coexist (e.g. dream error result + ratification crash) — both
+ must surface on the errored row."""
+ result = _nightly_result(
+ dream=_dream_result(error="phase 1 LLM down"),
+ error="ratification: boom",
+ )
+ complete_mock, errored_mock, _ = _run_nightly_wrapper(result)
+
+ errored_mock.assert_called_once_with(
+ kind="nightly",
+ job_id="job-1",
+ error="ratification: boom | dream: phase 1 LLM down",
+ )
+ complete_mock.assert_not_called()
+
+ def test_in_flight_anthropic_batch_marks_complete_with_dream_in_flight(
+ self,
+ ) -> None:
+ """With DREAM_PASS_BATCH_ENABLED on, the dream submitter returns
+ as soon as the batch is ENQUEUED. The nightly fan-out is still
+ complete — its dream step handed off to the BatchExecutor, whose
+ callbacks only ever finalize ``dream_pass`` rows, never this
+ nightly row. The row must close out 'complete' (with
+ ``dream_in_flight`` on the persisted envelope as the async
+ marker), NOT park at 'submitted' until the 6h TTL reaps it."""
+ result = _nightly_result(
+ dream=_dream_result(execution_path="anthropic_batch"),
+ dream_in_flight=True,
+ )
+ complete_mock, errored_mock, phase_mock = _run_nightly_wrapper(result)
+
+ complete_mock.assert_called_once_with(
+ kind="nightly", job_id="job-1", result=result
+ )
+ assert result.dream_in_flight is True
+ errored_mock.assert_not_called()
+ # Only the initial 'running' transition — never 'submitted'.
+ phase_mock.assert_called_once_with(
+ kind="nightly", job_id="job-1", state="running"
+ )
+
+ def test_ratification_error_wins_over_in_flight_dream_batch(self) -> None:
+ """A ratification-sweep crash alongside an in-flight dream
+ batch surfaces as errored — error visibility beats the
+ in-flight bookkeeping."""
+ result = _nightly_result(
+ dream=_dream_result(execution_path="anthropic_batch"),
+ dream_in_flight=True,
+ error="ratification: boom",
+ )
+ complete_mock, errored_mock, _ = _run_nightly_wrapper(result)
+
+ errored_mock.assert_called_once_with(
+ kind="nightly", job_id="job-1", error="ratification: boom"
+ )
+ complete_mock.assert_not_called()
+
+ def test_skipped_dream_batch_result_still_marks_complete(self) -> None:
+ """A batch-path dream that was SKIPPED (lock held, no input)
+ has nothing in flight — the nightly row closes out as complete."""
+ result = _nightly_result(
+ dream=_dream_result(
+ execution_path="anthropic_batch",
+ skipped=True,
+ skip_reason="no_input",
+ )
+ )
+ complete_mock, errored_mock, _ = _run_nightly_wrapper(result)
+
+ complete_mock.assert_called_once_with(
+ kind="nightly", job_id="job-1", result=result
+ )
+ errored_mock.assert_not_called()
+
+
+class TestExecuteCommunityRebuildRuntimeGate:
+ def test_flag_off_short_circuits_before_rebuild_runs(self) -> None:
+ from backend.executor.scheduler import execute_community_rebuild
+
+ # First run_async returns False (flag check). If we let the gate
+ # pass, a second call would invoke rebuild_communities_for_user;
+ # asserting that doesn't happen is the contract.
+ with (
+ patch(
+ "backend.executor.scheduler.run_async", return_value=False
+ ) as run_async_mock,
+ patch(
+ "backend.executor.scheduler.rebuild_communities_for_user"
+ ) as rebuild_mock,
+ ):
+ execute_community_rebuild("abc")
+
+ run_async_mock.assert_called_once()
+ rebuild_mock.assert_not_called()
+
+
@pytest.mark.asyncio(loop_scope="session")
async def test_copilot_turn_schedule_one_shot(server: SpinTestServer):
await db.connect()
diff --git a/autogpt_platform/backend/backend/util/architecture_test.py b/autogpt_platform/backend/backend/util/architecture_test.py
index 42dc5c0e42..0a68969098 100644
--- a/autogpt_platform/backend/backend/util/architecture_test.py
+++ b/autogpt_platform/backend/backend/util/architecture_test.py
@@ -90,6 +90,101 @@ def _iter_backend_py_files():
yield path
+# ---------------------------------------------------------------------------
+# Rule: backend code uses pydantic, not stdlib dataclasses
+# ---------------------------------------------------------------------------
+#
+# Motivation: pydantic ``BaseModel`` gives us validation, (de)serialization,
+# and JSON-schema generation for free, and the whole backend relies on that
+# consistency across the API, the executor, and blocks. A plain ``@dataclass``
+# silently bypasses all of it. Shared, framework-agnostic helpers living under
+# a ``lib``/``libs`` directory are exempt. Pydantic dataclasses
+# (``pydantic.dataclasses``) are a different module and are intentionally
+# allowed.
+
+# Path segments whose subtrees are exempt: shared helpers under a `lib`/`libs`
+# folder may use stdlib dataclasses; everything else must not.
+_DATACLASS_EXEMPT_DIR_NAMES = frozenset({"lib", "libs"})
+
+# Pre-existing offenders (present in `dev` as of merge-base 9822fe4b) tracked
+# for future migration to pydantic. Excluded so the rule catches NEW violations
+# without blocking unrelated PRs. Paths are posix-relative to the backend
+# package root. Burn this list down; do not add to it.
+_DATACLASS_KNOWN_OFFENDERS = frozenset(
+ {
+ "api/features/builder/db.py",
+ # ``search/`` siblings to the original ``store/`` offenders — landed
+ # in dev's global-search rollout (#13217) after this allowlist was
+ # last snapshotted. Tracked here so the rule still catches genuinely
+ # new violations; migrate alongside the ``store/`` originals.
+ "api/features/search/content_handlers.py",
+ "api/features/search/hybrid_search.py",
+ "api/features/store/content_handlers.py",
+ "api/features/store/hybrid_search.py",
+ "blocks/codex.py",
+ "blocks/mcp/client.py",
+ "copilot/baseline/service.py",
+ "copilot/bot/adapters/base.py",
+ "copilot/bot/bot_backend.py",
+ "copilot/bot/handler.py",
+ "copilot/sdk/compaction.py",
+ "copilot/sdk/file_ref.py",
+ "copilot/sdk/service.py",
+ "copilot/sdk/service_test.py",
+ "copilot/sdk/session_waiter.py",
+ "copilot/stream_registry.py",
+ # Self-distilled skills registry added by dev's copilot-skills PR
+ # series; predates this allowlist refresh, same migration plan.
+ "copilot/tools/skills.py",
+ "copilot/tools/helpers.py",
+ "copilot/transcript.py",
+ "util/cache.py",
+ "util/prompt.py",
+ "util/sandbox_files.py",
+ "util/tool_call_loop.py",
+ }
+)
+
+
+def _dataclass_imports(path: pathlib.Path) -> list[tuple[int, str]]:
+ """Return (lineno, description) for every stdlib ``dataclasses`` import."""
+ try:
+ tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+ except SyntaxError:
+ return []
+ offenses: list[tuple[int, str]] = []
+ for node in ast.walk(tree):
+ if isinstance(node, ast.Import):
+ for alias in node.names:
+ if alias.name == "dataclasses" or alias.name.startswith("dataclasses."):
+ offenses.append((node.lineno, "imports the `dataclasses` module"))
+ elif isinstance(node, ast.ImportFrom):
+ # `from dataclasses import ...`; `from pydantic.dataclasses import ...`
+ # has a different module and is intentionally allowed.
+ if node.module == "dataclasses":
+ names = ", ".join(alias.name for alias in node.names)
+ offenses.append((node.lineno, f"imports `{names}` from `dataclasses`"))
+ return offenses
+
+
+def test_backend_uses_pydantic_not_dataclasses():
+ offenders: list[str] = []
+ for py in _iter_backend_py_files():
+ rel = py.relative_to(BACKEND_ROOT)
+ if set(rel.parts) & _DATACLASS_EXEMPT_DIR_NAMES:
+ continue
+ if rel.as_posix() in _DATACLASS_KNOWN_OFFENDERS:
+ continue
+ for lineno, reason in _dataclass_imports(py):
+ offenders.append(f" backend/{rel}:{lineno} {reason}")
+
+ assert not offenders, (
+ "Backend code must use a pydantic `BaseModel` instead of stdlib "
+ "`dataclasses` (only shared `lib`/`libs` helpers are exempt). "
+ "Replace these with `pydantic.BaseModel`:\n" + "\n".join(sorted(offenders))
+ )
+
+
def test_known_offenders_use_posix_separators():
"""_KNOWN_OFFENDERS must use forward slashes since the comparison key
is built from pathlib.Path.relative_to() which uses OS-native separators.
@@ -97,10 +192,10 @@ def test_known_offenders_use_posix_separators():
Ensure the key construction normalises to forward slashes.
"""
- for entry in _KNOWN_OFFENDERS:
+ for entry in _KNOWN_OFFENDERS | _DATACLASS_KNOWN_OFFENDERS:
path_part = entry.split()[0]
assert "\\" not in path_part, (
- f"_KNOWN_OFFENDERS entry uses backslash: {entry!r}. "
+ f"known-offenders entry uses backslash: {entry!r}. "
"Use forward slashes — the test should normalise Path separators."
)
diff --git a/autogpt_platform/backend/backend/util/clients.py b/autogpt_platform/backend/backend/util/clients.py
index 0df62fc33f..fe5e763570 100644
--- a/autogpt_platform/backend/backend/util/clients.py
+++ b/autogpt_platform/backend/backend/util/clients.py
@@ -12,6 +12,7 @@ OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
settings = Settings()
if TYPE_CHECKING:
+ from anthropic import AsyncAnthropic
from openai import AsyncOpenAI
from supabase import AClient, Client
@@ -264,6 +265,31 @@ def get_openai_client(*, prefer_openrouter: bool = False) -> "AsyncOpenAI | None
return None
+# ============ Anthropic Client ============ #
+
+
+@cached(ttl_seconds=3600)
+def get_anthropic_client() -> "AsyncAnthropic | None":
+ """Get a process-cached async Anthropic client.
+
+ Reads ``settings.secrets.anthropic_api_key`` (same env var the SDK
+ blocks consume). Returns ``None`` when no key is configured — caller
+ should fall back to OpenRouter-routed Anthropic via
+ ``get_openai_client(prefer_openrouter=True)`` for sync calls, or
+ skip the Anthropic-batch path entirely.
+
+ Used by the dream pass + future batch-mode LLM callers that need
+ direct Anthropic API access (batch API, prompt caching with
+ cache_control, tool-use forced structured output).
+ """
+ from anthropic import AsyncAnthropic
+
+ anthropic_key = settings.secrets.anthropic_api_key
+ if anthropic_key:
+ return AsyncAnthropic(api_key=anthropic_key)
+ return None
+
+
def openrouter_helper_cost_provider() -> str:
"""Cost-log provider for a client from ``get_openai_client(prefer_openrouter=True)``.
diff --git a/autogpt_platform/backend/backend/util/feature_flag.py b/autogpt_platform/backend/backend/util/feature_flag.py
index a49832b4a4..1d0adb40e5 100644
--- a/autogpt_platform/backend/backend/util/feature_flag.py
+++ b/autogpt_platform/backend/backend/util/feature_flag.py
@@ -63,6 +63,78 @@ class Flag(str, Enum):
COPILOT_TIER_WORKSPACE_STORAGE_LIMITS = "copilot-tier-workspace-storage-limits"
COPILOT_TIER_STRIPE_PRICES = "copilot-tier-stripe-prices"
GRAPHITI_MEMORY = "graphiti-memory"
+
+ # Gates the per-user weekly community rebuild registered by
+ # ``add_community_rebuild_schedule``. Off by default; opt-in canary
+ # so the Leiden + LLM-summarization cost doesn't ramp before
+ # retrieval-relevance benefit is measured.
+ GRAPHITI_COMMUNITIES_ENABLED = "graphiti-communities-enabled"
+
+ # --- Dream-system gates (P0) ---
+ #
+ # No "enabled-users list" flag — LD's per-flag targeting natively
+ # cohorts the canary (internal team → 5 → 50 → 500 → 5k), and
+ # ``is_feature_enabled(..., user_id, ...)`` evaluates each user.
+ # The four flags below are the master gate + three per-feature
+ # gates. Helper functions live next to the code that consumes them
+ # (added when each feature lands); these enum entries are
+ # scaffolding so the LD keys can be configured ahead of code.
+
+ # Master gate for the dream pass. When off, no dream-related code
+ # paths fire for the user — no schedule registration, no batch
+ # consumer pickup, no ratification loop. Defaults False; opt-in
+ # only.
+ DREAM_PASS_ENABLED = "dream-pass-enabled"
+
+ # Per-feature gate for the web-fact-check tool (P0.5). The tool
+ # can only DEMOTE memories on contradiction; new web-derived
+ # facts ride the ratification loop as tentative. Off on the
+ # local-LLM transport by default (most local installs lack a
+ # search-API key); cloud opt-in. Independent of
+ # ``DREAM_PASS_ENABLED`` so the dream pass can run without
+ # external network calls when this flag is off.
+ DREAM_PASS_WEB_FACT_CHECK = "dream-pass-web-fact-check"
+
+ # Orchestrator-level kill switch for the web-fact-check hook
+ # introduced alongside the P0.5 scaffolding. Distinct from
+ # ``DREAM_PASS_WEB_FACT_CHECK`` so the hook can be wired into the
+ # orchestrator without auto-running on every dream pass before a
+ # search backend is bound — flip this on per-user once a backend
+ # is configured.
+ DREAM_WEB_FACT_CHECK_ENABLED = "dream-web-fact-check-enabled"
+
+ # Per-feature gate for the cascading-expiry helper
+ # ``invalidate_entity_direct_neighbors`` (P0.3b). When on, the
+ # dream pass may demote every ``:RELATES_TO`` edge directly
+ # attached to a flagged-as-dead entity (e.g. "this client is
+ # gone — expire their associated facts"). Single-hop only —
+ # tangentially-related edges are NOT touched. Off by default for
+ # the first two weeks after launch because this is the highest
+ # blast-radius dream action; a buggy phase-3 sanitizer could
+ # demote too many edges before we catch it. Ratification (P0.4)
+ # is how good edges caught in the cascade get re-promoted.
+ DREAM_PASS_INVALIDATE_ENTITY = "dream-pass-invalidate-entity"
+
+ # Rollout gate for the async Anthropic batch path (P0.1). When on AND a
+ # direct Anthropic API key is configured, the dream pass routes through
+ # Anthropic's Batch API (~50% cheaper, async, up to 24h) and runs its
+ # memory writeback in the batch callback; when off, dreams run on the
+ # synchronous baseline regardless of key presence. A direct key is a hard
+ # requirement — the native Batch API can't be reached via
+ # OpenRouter/subscription — so this flag gates rollout on top of
+ # key-presence, not instead of it. Defaults False so the batch path ships
+ # dark and is enabled per-cohort.
+ DREAM_PASS_BATCH_ENABLED = "dream-pass-batch-enabled"
+
+ # Note: there is intentionally no DREAM_PASS_LOCAL_TRANSPORT
+ # flag. Whether to run on local-LLM transport is a CODE decision
+ # — ``resolve_dream_execution_path()`` in
+ # ``copilot/dream/routing.py`` inspects ``config.transport`` and
+ # picks sync-baseline + phase-collapse + extended lock TTL for
+ # local users. If a user has ``DREAM_PASS_ENABLED`` true, they
+ # get dreams, period — degraded on local, full on cloud. See
+ # ``dream/p0-spec.md`` §13.
+
GENERIC_TRIGGER_AGENTS = "generic-trigger-agents"
# Stripe Product ID for top-up Checkout sessions. When unset (default),
# top_up_intent uses inline product_data (creates ephemeral Stripe products
diff --git a/autogpt_platform/backend/backend/util/llm/__init__.py b/autogpt_platform/backend/backend/util/llm/__init__.py
new file mode 100644
index 0000000000..eedba1a693
--- /dev/null
+++ b/autogpt_platform/backend/backend/util/llm/__init__.py
@@ -0,0 +1,15 @@
+"""Shared LLM dispatch infrastructure.
+
+Owns the per-provider SDK call helper (``providers.call_provider``)
+so that multiple LLM call sites in the backend — the block-layer
+``_llm_call``, the dream-pass ``structured_completion``, the copilot
+chat dispatch, future server-internal callers — route through one
+implementation. Adding a new provider, a new execution mode (batch,
+flex), or new structured-output handling lands once and every caller
+picks it up.
+
+This module is intentionally agnostic to the caller's surrounding
+framework: it doesn't depend on the block layer's ``LlmModel`` enum,
+the executor's ``NodeExecutionStats``, or the dream-pass's Pydantic
+validation. Callers wrap it with their own typed entry points.
+"""
diff --git a/autogpt_platform/backend/backend/util/llm/conversions.py b/autogpt_platform/backend/backend/util/llm/conversions.py
new file mode 100644
index 0000000000..065d09d1d2
--- /dev/null
+++ b/autogpt_platform/backend/backend/util/llm/conversions.py
@@ -0,0 +1,182 @@
+"""Cross-provider format conversion + response extraction helpers.
+
+Lives next to ``providers.call_provider`` so callers don't need to
+pull in the block layer for type conversions. The functions here
+mirror what was historically in ``backend/blocks/llm.py``; after
+Step 3 of the rollout (see plans/idempotent-launching-moth.md),
+``blocks/llm.py`` will import them from this module instead of
+keeping its own copies.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from typing import Any, Iterable
+
+import anthropic
+from anthropic.types import ToolParam
+from openai.types.chat import ChatCompletion as OpenAIChatCompletion
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Cross-call tool-call carrier types
+# ---------------------------------------------------------------------------
+
+
+class ToolCall(BaseModel):
+ """A single tool invocation a model emitted."""
+
+ name: str
+ arguments: str
+
+
+class ToolContentBlock(BaseModel):
+ """A tool-use content block normalized across OpenAI + Anthropic shapes."""
+
+ id: str
+ type: str
+ function: ToolCall
+
+
+# ---------------------------------------------------------------------------
+# OpenAI → Anthropic conversions
+# ---------------------------------------------------------------------------
+
+
+def convert_openai_tool_fmt_to_anthropic(
+ openai_tools: list[dict] | None = None,
+) -> Iterable[ToolParam] | anthropic.NotGiven:
+ """Convert OpenAI tool definitions into Anthropic ``ToolParam`` shape.
+
+ Returns ``anthropic.NOT_GIVEN`` when the caller passed no tools so
+ the SDK omits the field from the serialized request (Anthropic
+ rejects an empty tools array with HTTP 400).
+ """
+ if not openai_tools or len(openai_tools) == 0:
+ return anthropic.NOT_GIVEN
+
+ anthropic_tools: list[ToolParam] = []
+ for tool in openai_tools:
+ # Accept both forms: {"type":"function","function":{...}} (OpenAI
+ # canonical) and {"name":..., "parameters":...} (raw function def).
+ if "function" in tool:
+ function_data = tool["function"]
+ else:
+ function_data = tool
+
+ anthropic_tool: ToolParam = {
+ "name": function_data["name"],
+ "description": function_data.get("description", ""),
+ "input_schema": {
+ "type": "object",
+ "properties": function_data.get("parameters", {}).get("properties", {}),
+ "required": function_data.get("parameters", {}).get("required", []),
+ },
+ }
+ anthropic_tools.append(anthropic_tool)
+
+ return anthropic_tools
+
+
+# ---------------------------------------------------------------------------
+# Response-shape extractors (OpenAI-compatible providers)
+# ---------------------------------------------------------------------------
+
+
+def extract_openrouter_cost(response: OpenAIChatCompletion) -> float | None:
+ """Pull OpenRouter's per-request USD cost off a chat-completion response.
+
+ OpenRouter populates a ``cost`` field on ``usage`` when the request
+ body sets ``usage: {"include": True}``. The OpenAI SDK's typed
+ ``CompletionUsage`` doesn't declare it; pydantic v2 makes it
+ available on ``model_extra``.
+
+ Returns ``None`` for missing, non-finite, or negative values so
+ callers don't accidentally bill at zero or NaN.
+ """
+ usage = response.usage
+ if usage is None:
+ return None
+ extras = usage.model_extra or {}
+ cost = extras.get("cost")
+ if cost is None:
+ return None
+ try:
+ cost_f = float(cost)
+ except (TypeError, ValueError):
+ return None
+ if not math.isfinite(cost_f) or cost_f < 0:
+ return None
+ return cost_f
+
+
+def extract_openai_reasoning(response: Any) -> str | None:
+ """Extract reasoning content from an OpenAI-compatible chat response.
+
+ Searches the conventional locations (response-level, choice-level,
+ message-level) so the same helper works across OpenAI's evolving
+ SDK surface and OpenRouter's normalized response.
+ """
+ if not response.choices:
+ logger.warning("LLM response has empty choices in extract_openai_reasoning")
+ return None
+ choice = response.choices[0]
+ if hasattr(choice, "reasoning") and getattr(choice, "reasoning", None):
+ return str(getattr(choice, "reasoning"))
+ if hasattr(response, "reasoning") and getattr(response, "reasoning", None):
+ return str(getattr(response, "reasoning"))
+ if hasattr(choice.message, "reasoning") and getattr(
+ choice.message, "reasoning", None
+ ):
+ return str(getattr(choice.message, "reasoning"))
+ return None
+
+
+def extract_openai_tool_calls(response: Any) -> list[ToolContentBlock] | None:
+ """Extract tool calls from an OpenAI-compatible chat response."""
+ if not response.choices:
+ logger.warning("LLM response has empty choices in extract_openai_tool_calls")
+ return None
+ if response.choices[0].message.tool_calls:
+ return [
+ ToolContentBlock(
+ id=tool.id,
+ type=tool.type,
+ function=ToolCall(
+ name=tool.function.name,
+ arguments=tool.function.arguments,
+ ),
+ )
+ for tool in response.choices[0].message.tool_calls
+ ]
+ return None
+
+
+# ---------------------------------------------------------------------------
+# Misc utilities
+# ---------------------------------------------------------------------------
+
+
+def sanitize_messages_for_utf8(messages: list[dict]) -> None:
+ """Replace unpaired surrogates in message content in-place.
+
+ httpx encodes the JSON request body to UTF-8; unpaired surrogates
+ (e.g., copy-pasted emojis stored as raw code points) raise
+ ``UnicodeEncodeError`` before the request even leaves the process.
+ Mirrors the historical sanitization in
+ ``backend/blocks/llm.py::_llm_call``.
+ """
+ for msg in messages:
+ content = msg.get("content")
+ if isinstance(content, str):
+ try:
+ content.encode("utf-8")
+ except UnicodeEncodeError:
+ logger.warning("Sanitized unpaired surrogates in LLM prompt content")
+ msg["content"] = content.encode("utf-8", errors="surrogatepass").decode(
+ "utf-8", errors="replace"
+ )
diff --git a/autogpt_platform/backend/backend/util/llm/providers.py b/autogpt_platform/backend/backend/util/llm/providers.py
new file mode 100644
index 0000000000..f8adc416f7
--- /dev/null
+++ b/autogpt_platform/backend/backend/util/llm/providers.py
@@ -0,0 +1,1315 @@
+"""Per-provider LLM call helper — the single seam every caller delegates to.
+
+Owns the raw per-provider SDK call so the block-layer ``_llm_call``,
+the dream-pass ``structured_completion``, and the copilot chat
+dispatch all route through one implementation. Adding a new
+execution mode (``batch``, ``flex``) or a new provider lands once
+and every caller picks it up.
+
+What this module IS responsible for:
+ * Dispatching the call to the correct provider SDK based on
+ ``provider`` argument
+ * Normalizing the per-provider response shape into ``ProviderResponse``
+ * Wrapping the call in a hard timeout
+ * Sanitizing message content for UTF-8 transport
+ * Switching on ``execution_mode`` (``sync`` today, ``batch`` +
+ ``flex`` in later steps)
+
+What this module is NOT responsible for (caller wraps):
+ * ``LlmModel``-aware token-budget computation (caller passes
+ pre-computed ``max_tokens``)
+ * Prompt compression (``compress_context``) — block layer needs it,
+ dream may not
+ * Retry on validation failure (block layer's ``retry`` parameter)
+ * Pydantic ``response_model`` validation (dream's
+ ``structured_completion`` does this on top)
+ * Cost-log writes / rate-limit charging — caller decides which
+ billing path to use, ``ProviderResponse.cost_usd`` just surfaces
+ the number
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import json as json_module
+import logging
+from datetime import datetime, timezone
+from typing import Any, Literal, cast
+
+import anthropic
+import ollama
+import openai
+from openai.types.chat import ChatCompletionMessageParam, ChatCompletionToolParam
+from openai.types.shared_params import ResponseFormatJSONObject
+from pydantic import Field
+from pydantic.dataclasses import dataclass
+
+from backend.util.clients import OPENROUTER_BASE_URL
+from backend.util.llm.conversions import (
+ ToolCall,
+ ToolContentBlock,
+ convert_openai_tool_fmt_to_anthropic,
+ extract_openai_reasoning,
+ extract_openai_tool_calls,
+ extract_openrouter_cost,
+ sanitize_messages_for_utf8,
+)
+from backend.util.openai_responses import (
+ convert_tools_to_responses_format,
+ extract_responses_content,
+ extract_responses_reasoning,
+ extract_responses_tool_calls,
+ extract_responses_usage,
+)
+from backend.util.request import validate_url_host
+from backend.util.settings import Settings
+
+settings = Settings()
+logger = logging.getLogger(__name__)
+
+
+# Hard cap on a single provider HTTP request. Mirrors
+# ``backend/blocks/llm.py::LLM_REQUEST_TIMEOUT_SECONDS``. Healthy
+# non-streaming Messages / Responses calls finish in seconds; anything
+# past 120s is almost certainly a stalled socket and retries-on-timeout
+# would compound into multi-hour worst cases. Batch and flex paths
+# override this where appropriate.
+DEFAULT_REQUEST_TIMEOUT_SECONDS = 120
+
+# Provider names accepted by ``call_provider``. Kept as a string Literal
+# (not an enum) so the helper stays provider-name-agnostic — callers
+# pass whatever string their model metadata reports.
+ProviderLiteral = Literal[
+ "openai",
+ "anthropic",
+ "groq",
+ "ollama",
+ "open_router",
+ "llama_api",
+ "aiml_api",
+ "v0",
+]
+
+ExecutionMode = Literal["sync", "batch", "flex"]
+
+# Providers that accept ``service_tier="flex"``. OpenAI exposes it
+# natively on its Responses API; OpenRouter forwards the param through
+# to OpenAI- and Google-backed models (the only flex-capable upstreams
+# they support). Anthropic + Groq + Ollama + the open-weight gateways
+# have no flex equivalent — callers asking for flex on them get a
+# sync fallback with a log line.
+_FLEX_SUPPORTED_PROVIDERS: set[str] = {"openai", "open_router"}
+
+
+# ---------------------------------------------------------------------------
+# Result + submission carriers
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class ProviderResponse:
+ """Normalized response from any sync-mode provider call.
+
+ Fields with default 0 / None / empty are absent on providers that
+ don't surface them (e.g. Anthropic doesn't return USD cost,
+ Ollama / Groq don't have cache tokens).
+ """
+
+ content: str
+ prompt_tokens: int
+ completion_tokens: int
+ cache_read_tokens: int = 0
+ cache_creation_tokens: int = 0
+ tool_calls: list[ToolContentBlock] | None = None
+ reasoning: str | None = None
+ cost_usd: float | None = None
+ # Provider-native response object for callers that need raw access.
+ # Kept out of repr + pydantic serialization (it's an opaque SDK object).
+ raw_response: Any = Field(default=None, repr=False, exclude=True)
+
+
+@dataclass(slots=True)
+class BatchSubmissionRef:
+ """Handle returned when ``execution_mode='batch'``.
+
+ Apply step happens asynchronously when the batch poller (Step 4)
+ delivers results keyed by ``custom_id``. Callers persist this
+ handle and register a per-``custom_id`` callback with the
+ ``BatchExecutor`` service.
+ """
+
+ provider: ProviderLiteral
+ provider_batch_id: str
+ custom_id: str
+ submitted_at: datetime
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+
+async def call_provider(
+ *,
+ provider: ProviderLiteral,
+ model: str,
+ api_key: str,
+ messages: list[dict],
+ max_tokens: int,
+ temperature: float | None = None,
+ execution_mode: ExecutionMode = "sync",
+ tools: list[dict] | None = None,
+ tool_choice: dict | None = None,
+ force_json_output: bool = False,
+ parallel_tool_calls: bool | openai.Omit = openai.omit,
+ ollama_host: str = "localhost:11434",
+ custom_id: str | None = None,
+ timeout_seconds: float = DEFAULT_REQUEST_TIMEOUT_SECONDS,
+) -> ProviderResponse | BatchSubmissionRef:
+ """Dispatch a single LLM call to the correct provider SDK.
+
+ Sync mode (``execution_mode="sync"``) returns a ``ProviderResponse``
+ with content + token counts + optional cost. Batch mode (Step 4)
+ returns a ``BatchSubmissionRef`` — apply happens later via the
+ batch poller. Flex mode (Step 8) returns a ``ProviderResponse``
+ like sync but with the provider's discounted tier latency.
+
+ Raises ``TimeoutError`` if the call exceeds ``timeout_seconds``
+ (sync mode only; batch submissions are bounded by the provider's
+ own SLA and the poller's own timeout policy).
+ """
+ if execution_mode == "batch":
+ if not custom_id:
+ raise ValueError(
+ "execution_mode='batch' requires a non-empty custom_id "
+ "for result routing once the batch completes."
+ )
+ sanitize_messages_for_utf8(messages)
+ return await _submit_batch_one_request(
+ provider=provider,
+ model=model,
+ api_key=api_key,
+ messages=messages,
+ max_tokens=max_tokens,
+ temperature=temperature,
+ tools=tools,
+ tool_choice=tool_choice,
+ custom_id=custom_id,
+ )
+ # Flex tier is OpenAI's discounted-async-latency tier (~50% off, may
+ # queue for up to 15 min). OpenRouter forwards ``service_tier=flex``
+ # through to the upstream OpenAI/Google model. Other providers have
+ # no flex equivalent — Anthropic's cost-saver is batch (Step 4), not
+ # flex; Groq + the open-weight gateways just don't expose it. For
+ # those we log and fall through to sync so dream/chat callers don't
+ # have to know which providers support what.
+ service_tier: str | None = None
+ if execution_mode == "flex":
+ if provider in _FLEX_SUPPORTED_PROVIDERS:
+ service_tier = "flex"
+ else:
+ logger.warning(
+ "execution_mode='flex' requested for provider=%s which has "
+ "no flex tier; falling through to sync.",
+ provider,
+ )
+
+ sanitize_messages_for_utf8(messages)
+
+ try:
+ return await asyncio.wait_for(
+ _dispatch_sync(
+ provider=provider,
+ model=model,
+ api_key=api_key,
+ messages=messages,
+ max_tokens=max_tokens,
+ temperature=temperature,
+ tools=tools,
+ tool_choice=tool_choice,
+ force_json_output=force_json_output,
+ parallel_tool_calls=parallel_tool_calls,
+ ollama_host=ollama_host,
+ timeout_seconds=timeout_seconds,
+ service_tier=service_tier,
+ ),
+ timeout=timeout_seconds,
+ )
+ except asyncio.TimeoutError as exc:
+ raise TimeoutError(
+ f"LLM request to {provider}/{model} exceeded "
+ f"{timeout_seconds}s and was cancelled."
+ ) from exc
+
+
+# ---------------------------------------------------------------------------
+# Sync dispatch
+# ---------------------------------------------------------------------------
+
+
+async def _dispatch_sync(
+ *,
+ provider: ProviderLiteral,
+ model: str,
+ api_key: str,
+ messages: list[dict],
+ max_tokens: int,
+ temperature: float | None,
+ tools: list[dict] | None,
+ tool_choice: dict | None,
+ force_json_output: bool,
+ parallel_tool_calls: bool | openai.Omit,
+ ollama_host: str,
+ timeout_seconds: float,
+ service_tier: str | None = None,
+) -> ProviderResponse:
+ if provider == "openai":
+ return await _call_openai_responses(
+ model=model,
+ api_key=api_key,
+ messages=messages,
+ max_tokens=max_tokens,
+ temperature=temperature,
+ tools=tools,
+ force_json_output=force_json_output,
+ parallel_tool_calls=parallel_tool_calls,
+ timeout_seconds=timeout_seconds,
+ service_tier=service_tier,
+ )
+ if provider == "anthropic":
+ return await _call_anthropic_messages(
+ model=model,
+ api_key=api_key,
+ messages=messages,
+ max_tokens=max_tokens,
+ temperature=temperature,
+ tools=tools,
+ tool_choice=tool_choice,
+ timeout_seconds=timeout_seconds,
+ )
+ if provider == "groq":
+ return await _call_groq(
+ model=model,
+ api_key=api_key,
+ messages=messages,
+ max_tokens=max_tokens,
+ temperature=temperature,
+ tools=tools,
+ force_json_output=force_json_output,
+ timeout_seconds=timeout_seconds,
+ )
+ if provider == "ollama":
+ return await _call_ollama(
+ model=model,
+ messages=messages,
+ max_tokens=max_tokens,
+ temperature=temperature,
+ tools=tools,
+ force_json_output=force_json_output,
+ ollama_host=ollama_host,
+ timeout_seconds=timeout_seconds,
+ )
+ if provider == "open_router":
+ return await _call_openai_compat(
+ base_url=OPENROUTER_BASE_URL,
+ model=model,
+ api_key=api_key,
+ messages=messages,
+ max_tokens=max_tokens,
+ temperature=temperature,
+ tools=tools,
+ force_json_output=force_json_output,
+ parallel_tool_calls=parallel_tool_calls,
+ timeout_seconds=timeout_seconds,
+ include_openrouter_extras=True,
+ service_tier=service_tier,
+ )
+ if provider == "llama_api":
+ return await _call_openai_compat(
+ base_url="https://api.llama.com/compat/v1/",
+ model=model,
+ api_key=api_key,
+ messages=messages,
+ max_tokens=max_tokens,
+ temperature=temperature,
+ tools=tools,
+ force_json_output=False, # llama_api doesn't honor it
+ parallel_tool_calls=parallel_tool_calls,
+ timeout_seconds=timeout_seconds,
+ include_openrouter_extras=False,
+ extra_headers={"HTTP-Referer": "https://agpt.co", "X-Title": "AutoGPT"},
+ )
+ if provider == "aiml_api":
+ return await _call_openai_compat(
+ base_url="https://api.aimlapi.com/v2",
+ model=model,
+ api_key=api_key,
+ messages=messages,
+ max_tokens=max_tokens,
+ temperature=temperature,
+ tools=None, # AI/ML API path historically passes no tools
+ force_json_output=False,
+ parallel_tool_calls=openai.omit,
+ timeout_seconds=timeout_seconds,
+ include_openrouter_extras=False,
+ default_headers={
+ "X-Project": "AutoGPT",
+ "X-Title": "AutoGPT",
+ "HTTP-Referer": "https://github.com/Significant-Gravitas/AutoGPT",
+ },
+ )
+ if provider == "v0":
+ return await _call_openai_compat(
+ base_url="https://api.v0.dev/v1",
+ model=model,
+ api_key=api_key,
+ messages=messages,
+ max_tokens=max_tokens,
+ temperature=temperature,
+ tools=tools,
+ force_json_output=force_json_output,
+ parallel_tool_calls=parallel_tool_calls,
+ timeout_seconds=timeout_seconds,
+ include_openrouter_extras=False,
+ )
+
+ raise ValueError(f"Unsupported LLM provider: {provider}")
+
+
+# ---------------------------------------------------------------------------
+# OpenAI Responses API (native)
+# ---------------------------------------------------------------------------
+
+
+async def _call_openai_responses(
+ *,
+ model: str,
+ api_key: str,
+ messages: list[dict],
+ max_tokens: int,
+ temperature: float | None,
+ tools: list[dict] | None,
+ force_json_output: bool,
+ parallel_tool_calls: bool | openai.Omit,
+ timeout_seconds: float,
+ service_tier: str | None = None,
+) -> ProviderResponse:
+ client = openai.AsyncOpenAI(api_key=api_key)
+ tools_param = convert_tools_to_responses_format(tools) if tools else openai.omit
+ text_config: Any = openai.omit
+ if force_json_output:
+ text_config = {"format": {"type": "json_object"}}
+
+ # ``service_tier`` lives in ``extra_body`` because OpenAI ships it on
+ # the Responses payload but the openai-python SDK doesn't surface it
+ # as a typed kwarg on every SDK release. ``extra_body`` is the
+ # forward-compatible escape hatch.
+ extra_body: dict[str, Any] = {}
+ if service_tier:
+ extra_body["service_tier"] = service_tier
+
+ response = await client.responses.create(
+ model=model,
+ input=messages, # type: ignore[arg-type]
+ tools=tools_param, # type: ignore[arg-type]
+ max_output_tokens=max_tokens,
+ # Reasoning models (o-series) reject ``temperature`` — same guard
+ # as the Anthropic path: only send the field when the caller set
+ # one, never a default.
+ temperature=temperature if temperature is not None else openai.omit,
+ parallel_tool_calls=parallel_tool_calls,
+ text=text_config, # type: ignore[arg-type]
+ store=False,
+ timeout=timeout_seconds,
+ extra_body=extra_body or openai.omit, # type: ignore[arg-type]
+ )
+
+ raw_tool_calls = extract_responses_tool_calls(response)
+ tool_calls = None
+ if raw_tool_calls:
+ tool_calls = [
+ ToolContentBlock(
+ id=tc["id"],
+ type=tc["type"],
+ function=ToolCall(
+ name=tc["function"]["name"],
+ arguments=tc["function"]["arguments"],
+ ),
+ )
+ for tc in raw_tool_calls
+ ]
+ prompt_tokens, completion_tokens = extract_responses_usage(response)
+
+ return ProviderResponse(
+ content=extract_responses_content(response),
+ prompt_tokens=prompt_tokens,
+ completion_tokens=completion_tokens,
+ tool_calls=tool_calls,
+ reasoning=extract_responses_reasoning(response),
+ raw_response=response,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Anthropic Messages API (native)
+# ---------------------------------------------------------------------------
+
+
+async def _call_anthropic_messages(
+ *,
+ model: str,
+ api_key: str,
+ messages: list[dict],
+ max_tokens: int,
+ temperature: float | None,
+ tools: list[dict] | None,
+ tool_choice: dict | None,
+ timeout_seconds: float,
+) -> ProviderResponse:
+ an_tools = convert_openai_tool_fmt_to_anthropic(tools)
+ # Cache tool definitions alongside the system prompt — placing
+ # cache_control on the last tool caches all tool schemas as a
+ # single prefix; reads cost 10% of normal input tokens.
+ if isinstance(an_tools, list) and an_tools:
+ an_tools[-1] = {**an_tools[-1], "cache_control": {"type": "ephemeral"}}
+
+ system_messages = [p["content"] for p in messages if p["role"] == "system"]
+ sysprompt = " ".join(system_messages)
+
+ anth_messages: list[dict] = []
+ last_role: str | None = None
+ for p in messages:
+ if p["role"] in ["user", "assistant"]:
+ if (
+ p["role"] == last_role
+ and anth_messages
+ and isinstance(anth_messages[-1]["content"], str)
+ and isinstance(p["content"], str)
+ ):
+ anth_messages[-1]["content"] += p["content"]
+ else:
+ anth_messages.append({"role": p["role"], "content": p["content"]})
+ last_role = p["role"]
+
+ client = anthropic.AsyncAnthropic(api_key=api_key)
+ create_kwargs: dict[str, Any] = dict(
+ model=model,
+ messages=anth_messages,
+ max_tokens=max_tokens,
+ tools=an_tools,
+ timeout=timeout_seconds,
+ )
+ if temperature is not None:
+ create_kwargs["temperature"] = temperature
+ if tool_choice is not None:
+ create_kwargs["tool_choice"] = tool_choice
+ if sysprompt.strip():
+ # Anthropic rejects empty text blocks (HTTP 400) — only attach
+ # the system field for non-whitespace prompts.
+ create_kwargs["system"] = [
+ {
+ "type": "text",
+ "text": sysprompt,
+ "cache_control": {"type": "ephemeral"},
+ }
+ ]
+
+ resp = await client.messages.create(**create_kwargs)
+ if not resp.content:
+ raise ValueError("No content returned from Anthropic.")
+
+ tool_calls: list[ToolContentBlock] | None = None
+ for content_block in resp.content:
+ if content_block.type == "tool_use":
+ if tool_calls is None:
+ tool_calls = []
+ tool_calls.append(
+ ToolContentBlock(
+ id=content_block.id,
+ type=content_block.type,
+ function=ToolCall(
+ name=content_block.name,
+ arguments=json_module.dumps(content_block.input),
+ ),
+ )
+ )
+
+ if not tool_calls and resp.stop_reason == "tool_use":
+ logger.warning(
+ "Anthropic returned stop_reason='tool_use' but no tool calls "
+ "were extractable from content."
+ )
+
+ reasoning: str | None = None
+ for content_block in resp.content:
+ if hasattr(content_block, "type") and content_block.type == "thinking":
+ reasoning = content_block.thinking
+ break
+
+ first_block = resp.content[0]
+ content_text = (
+ first_block.name
+ if isinstance(first_block, anthropic.types.ToolUseBlock)
+ else getattr(first_block, "text", "")
+ )
+
+ return ProviderResponse(
+ content=content_text,
+ prompt_tokens=resp.usage.input_tokens,
+ completion_tokens=resp.usage.output_tokens,
+ cache_read_tokens=getattr(resp.usage, "cache_read_input_tokens", None) or 0,
+ cache_creation_tokens=getattr(resp.usage, "cache_creation_input_tokens", None)
+ or 0,
+ tool_calls=tool_calls,
+ reasoning=reasoning,
+ raw_response=resp,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Groq (OpenAI-shaped chat completions, no tools)
+# ---------------------------------------------------------------------------
+
+
+async def _call_groq(
+ *,
+ model: str,
+ api_key: str,
+ messages: list[dict],
+ max_tokens: int,
+ temperature: float | None,
+ tools: list[dict] | None,
+ force_json_output: bool,
+ timeout_seconds: float,
+) -> ProviderResponse:
+ if tools:
+ raise ValueError("Groq does not support tools.")
+
+ from groq import AsyncGroq # local import — heavy SDK
+
+ client = AsyncGroq(api_key=api_key)
+ response_format = {"type": "json_object"} if force_json_output else None
+ create_kwargs: dict[str, Any] = dict(
+ model=model,
+ messages=messages,
+ response_format=response_format,
+ max_tokens=max_tokens,
+ timeout=timeout_seconds,
+ )
+ # Same guard as the Anthropic path — only send ``temperature`` when
+ # the caller set one, so models that reject it never see the field.
+ if temperature is not None:
+ create_kwargs["temperature"] = temperature
+ response = await client.chat.completions.create(**create_kwargs)
+ if not response.choices:
+ raise ValueError("Groq returned empty choices in response")
+ return ProviderResponse(
+ content=response.choices[0].message.content or "",
+ prompt_tokens=response.usage.prompt_tokens if response.usage else 0,
+ completion_tokens=(response.usage.completion_tokens if response.usage else 0),
+ raw_response=response.choices[0].message,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Ollama (local-runner chat API)
+# ---------------------------------------------------------------------------
+
+
+async def _call_ollama(
+ *,
+ model: str,
+ messages: list[dict],
+ max_tokens: int,
+ temperature: float | None,
+ tools: list[dict] | None,
+ force_json_output: bool,
+ ollama_host: str,
+ timeout_seconds: float,
+) -> ProviderResponse:
+ if tools:
+ raise ValueError("Ollama does not support tools.")
+
+ # SSRF guard — the host can be user-supplied (block-layer input
+ # field), so it must match an operator-configured trust list.
+ await validate_url_host(ollama_host, trusted_hostnames=_trusted_ollama_hostnames())
+
+ # ``num_predict`` is Ollama's OUTPUT token cap. ``num_ctx`` (the
+ # input context window) is deliberately left at the model default —
+ # setting it from ``max_tokens`` silently truncated long prompts to
+ # the output budget.
+ options: dict[str, Any] = {"num_predict": max_tokens}
+ if temperature is not None:
+ options["temperature"] = temperature
+
+ client = ollama.AsyncClient(host=ollama_host, timeout=timeout_seconds)
+ response = await client.chat(
+ model=model,
+ messages=messages,
+ stream=False,
+ format="json" if force_json_output else None,
+ options=options,
+ )
+ return ProviderResponse(
+ content=response.message.content or "",
+ prompt_tokens=response.prompt_eval_count or 0,
+ completion_tokens=response.eval_count or 0,
+ raw_response=response,
+ )
+
+
+def _trusted_ollama_hostnames() -> list[str]:
+ """Hosts an Ollama call may target without IP-resolution checks.
+
+ Two operator-set config values can name the local LLM endpoint, and
+ both are equally trusted:
+
+ * ``Config.ollama_host`` — the block layer's Ollama setting.
+ * ``ChatConfig.base_url`` (``CHAT_BASE_URL``) — the copilot chat
+ endpoint, which the dream pass normalizes into ``ollama_host``
+ on the local transport.
+
+ Deriving the allowlist from only the former made every local dream
+ phase fail the SSRF check whenever the two were configured
+ differently (e.g. backend in Docker with
+ ``CHAT_BASE_URL=http://host.docker.internal:11434/v1`` while
+ ``Config.ollama_host`` sat at its ``localhost:11434`` default).
+ """
+ trusted = [settings.config.ollama_host]
+ chat_base_url = _chat_config_base_url()
+ if chat_base_url:
+ trusted.append(chat_base_url)
+ return trusted
+
+
+def _chat_config_base_url() -> str | None:
+ """Read the copilot ``ChatConfig.base_url`` for the Ollama trust list.
+
+ A broken chat config must not take down block-layer Ollama calls —
+ on any failure fall back to the block-layer trust list only. The
+ failure is deliberately NOT memoized (``lru_cache`` doesn't cache
+ exceptions), so a fixed config is picked up on a later dispatch.
+ """
+ try:
+ return _read_chat_config_base_url()
+ except Exception:
+ logger.warning(
+ "Could not read ChatConfig.base_url for the Ollama trusted-host "
+ "list; falling back to Config.ollama_host only.",
+ exc_info=True,
+ )
+ return None
+
+
[email protected]_cache(maxsize=1)
+def _read_chat_config_base_url() -> str | None:
+ """Construct ``ChatConfig`` once and memoize its ``base_url``.
+
+ ``ChatConfig`` is a pydantic-settings class with ``env_file=".env"``,
+ so each construction does synchronous dotenv disk I/O plus the full
+ validator chain (including repeated validator warnings) — per-call
+ construction meant that ran on every Ollama dispatch for a value
+ that only changes with the environment.
+
+ Lazy import: ``backend.copilot.config`` imports this module (for
+ ``ProviderLiteral``), so a top-level import here would be circular.
+ """
+ from backend.copilot.config import ChatConfig
+
+ return ChatConfig().base_url
+
+
+# ---------------------------------------------------------------------------
+# OpenAI-compatible chat completions (OpenRouter, Llama API, AI/ML, v0)
+# ---------------------------------------------------------------------------
+
+
+async def _call_openai_compat(
+ *,
+ base_url: str,
+ model: str,
+ api_key: str,
+ messages: list[dict],
+ max_tokens: int,
+ temperature: float | None,
+ tools: list[dict] | None,
+ force_json_output: bool,
+ parallel_tool_calls: bool | openai.Omit,
+ timeout_seconds: float,
+ include_openrouter_extras: bool,
+ extra_headers: dict[str, str] | None = None,
+ default_headers: dict[str, str] | None = None,
+ service_tier: str | None = None,
+) -> ProviderResponse:
+ client_kwargs: dict[str, Any] = {"base_url": base_url, "api_key": api_key}
+ if default_headers:
+ client_kwargs["default_headers"] = default_headers
+ client = openai.AsyncOpenAI(**client_kwargs)
+
+ call_kwargs: dict[str, Any] = dict(
+ model=model,
+ messages=cast(list[ChatCompletionMessageParam], messages),
+ max_tokens=max_tokens,
+ tools=(cast(list[ChatCompletionToolParam], tools) if tools else openai.omit),
+ parallel_tool_calls=parallel_tool_calls,
+ response_format=(
+ ResponseFormatJSONObject(type="json_object")
+ if force_json_output
+ else openai.omit
+ ),
+ timeout=timeout_seconds,
+ )
+ # Same guard as the Anthropic path — only send ``temperature`` when
+ # the caller set one, so upstreams that reject it (some reasoning
+ # models behind OpenRouter) never see the field.
+ if temperature is not None:
+ call_kwargs["temperature"] = temperature
+ extra_body: dict[str, Any] = {}
+ if include_openrouter_extras:
+ # Ask OpenRouter to surface per-request USD cost on `usage.cost`.
+ # Same shape used by backend/executor/simulator.py — keep aligned.
+ extra_body["usage"] = {"include": True}
+ call_kwargs["extra_headers"] = {
+ "HTTP-Referer": "https://agpt.co",
+ "X-Title": "AutoGPT",
+ }
+ elif extra_headers:
+ call_kwargs["extra_headers"] = extra_headers
+ if service_tier:
+ # OpenRouter forwards ``service_tier`` to OpenAI- and Google-backed
+ # models. Setting it for other upstreams is harmless — OpenRouter
+ # drops unknown params silently rather than failing the request.
+ extra_body["service_tier"] = service_tier
+ if extra_body:
+ call_kwargs["extra_body"] = extra_body
+
+ response = await client.chat.completions.create(**call_kwargs)
+ if not response.choices:
+ raise ValueError(f"{base_url} returned empty choices in response")
+
+ cache_read, cache_creation = _extract_openai_compat_cache_tokens(response)
+
+ return ProviderResponse(
+ content=response.choices[0].message.content or "",
+ prompt_tokens=response.usage.prompt_tokens if response.usage else 0,
+ completion_tokens=(response.usage.completion_tokens if response.usage else 0),
+ cache_read_tokens=cache_read,
+ cache_creation_tokens=cache_creation,
+ tool_calls=extract_openai_tool_calls(response),
+ reasoning=extract_openai_reasoning(response),
+ cost_usd=(
+ extract_openrouter_cost(response) if include_openrouter_extras else None
+ ),
+ raw_response=response.choices[0].message,
+ )
+
+
+def _extract_openai_compat_cache_tokens(response: Any) -> tuple[int, int]:
+ """Extract (cache_read, cache_creation) from an OpenAI-compat usage block.
+
+ Provider quirks this navigates:
+ * Standard OpenAI: ``usage.prompt_tokens_details.cached_tokens``
+ * OpenRouter routing to Anthropic: cache writes surface as
+ ``prompt_tokens_details.model_extra["cache_write_tokens"]``
+ * Anthropic-via-OpenAI-compat (rare): writes under
+ ``cache_creation_input_tokens`` on the same ``model_extra`` blob
+
+ Returns ``(0, 0)`` when no usage object is present so cost
+ computation degrades gracefully on providers that don't return it.
+ """
+ usage = getattr(response, "usage", None)
+ if usage is None:
+ return 0, 0
+ ptd = getattr(usage, "prompt_tokens_details", None)
+ if ptd is None:
+ return 0, 0
+ cache_read = int(getattr(ptd, "cached_tokens", 0) or 0)
+ ptd_extras = getattr(ptd, "model_extra", None) or {}
+ cache_creation = int(
+ ptd_extras.get("cache_write_tokens")
+ or ptd_extras.get("cache_creation_input_tokens")
+ or 0
+ )
+ return cache_read, cache_creation
+
+
+# ---------------------------------------------------------------------------
+# Streaming dispatch (chat baseline)
+# ---------------------------------------------------------------------------
+#
+# The chat baseline path needs the raw provider stream so it can iterate
+# chunks for delta-emitted SSE events, accumulate per-chunk token /
+# cost / cache deltas into its ``_BaselineStreamState``, and react to
+# tool-call partials as they arrive. Returning a normalized
+# ``ProviderResponse`` would collapse those incremental signals — so
+# the streaming entry-point returns the SDK's ``AsyncStream`` object
+# directly. The caller still owns chunk parsing; the helper centralizes
+# client instantiation + the OpenAI-compat ``create_kwargs`` assembly
+# (``extra_body``, ``extra_headers``, ``stream_options``, tools).
+#
+# Client factory injection:
+# The chat layer instantiates ``openai.AsyncOpenAI`` via a
+# Langfuse-wrapped subclass (``langfuse.openai.AsyncOpenAI``) to
+# thread OTel-style spans through every chat turn. To preserve that
+# tracing, callers pass ``client_factory=LangfuseAsyncOpenAI`` (or
+# any subclass with the same constructor) and the helper builds the
+# client from it. Defaults to ``openai.AsyncOpenAI`` so non-traced
+# callers (eval scripts, integration tests) need no extra wiring.
+
+
+# Wider than ``ProviderResponse`` because the caller picks up chunks
+# directly. Typed as ``Any`` to avoid importing the SDK's private
+# stream typevars across the helper boundary — the openai SDK is the
+# source of truth for chunk shape and callers are already openai-shape
+# aware (they came here from a direct SDK call).
+StreamResponse = Any
+
+
+async def call_provider_stream(
+ *,
+ model: str,
+ messages: list[dict],
+ client: openai.AsyncOpenAI | None = None,
+ base_url: str | None = None,
+ api_key: str | None = None,
+ extra_body: dict[str, Any] | None = None,
+ extra_headers: dict[str, str] | None = None,
+ stream_options: dict[str, Any] | None = None,
+ tools: list[dict] | None = None,
+ max_tokens: int | openai.Omit = openai.omit,
+ timeout: float | openai.Omit = openai.omit,
+ client_factory: type[openai.AsyncOpenAI] = openai.AsyncOpenAI,
+) -> StreamResponse:
+ """Open an OpenAI-compatible streaming chat completion and return
+ the raw ``AsyncStream`` for the caller to iterate.
+
+ Used by the chat baseline path. The non-streaming sync helper
+ (``call_provider``) is the right choice for everything else — only
+ consumers that need chunk-level deltas (tool partials, incremental
+ SSE tokens) belong here.
+
+ Either pass a pre-built ``client`` (the chat layer caches its
+ Langfuse-wrapped client at module level) OR pass
+ ``base_url`` + ``api_key`` and the helper builds one via
+ ``client_factory``. The chat layer prefers the pre-built path so
+ TCP connections stay pooled across turns; tests pass a mocked
+ client. Default factory is ``openai.AsyncOpenAI`` — callers
+ needing Langfuse spans pass the wrapped subclass.
+
+ Does NOT wrap the call in ``asyncio.wait_for`` and defaults
+ ``timeout`` to ``openai.omit`` so the SDK / client's own per-request
+ default applies. A streaming chat request can legitimately run
+ minutes (long reasoning, large tool-call payloads) and the
+ streaming protocol already exposes keepalive failures via chunk
+ timeouts; the caller's outer cancel scope is the right place to
+ bound total time. Pass an explicit ``timeout`` only when you
+ really mean per-request inter-chunk read timeout.
+ """
+ sanitize_messages_for_utf8(messages)
+ if client is None:
+ if base_url is None or api_key is None:
+ raise ValueError(
+ "call_provider_stream: pass either `client` or both "
+ "`base_url` and `api_key`."
+ )
+ client = client_factory(base_url=base_url, api_key=api_key)
+ create_kwargs: dict[str, Any] = {
+ "model": model,
+ "messages": cast(list[ChatCompletionMessageParam], messages),
+ "stream": True,
+ }
+ if not isinstance(timeout, openai.Omit):
+ create_kwargs["timeout"] = timeout
+ # Only set ``max_tokens`` when the caller passed a real value. Some
+ # transports (OpenRouter on thinking routes) inject their own
+ # default and 400 on a redundant client-side limit, so the chat
+ # baseline path passes ``openai.omit`` to skip the field
+ # entirely.
+ if not isinstance(max_tokens, openai.Omit):
+ create_kwargs["max_tokens"] = max_tokens
+ if extra_body:
+ create_kwargs["extra_body"] = extra_body
+ if extra_headers:
+ create_kwargs["extra_headers"] = extra_headers
+ if stream_options:
+ create_kwargs["stream_options"] = stream_options
+ if tools:
+ create_kwargs["tools"] = cast(list[ChatCompletionToolParam], list(tools))
+ return await client.chat.completions.create(**create_kwargs)
+
+
+async def call_provider_openai_compat_sync(
+ *,
+ model: str,
+ messages: list[dict],
+ max_tokens: int,
+ client: openai.AsyncOpenAI | None = None,
+ base_url: str | None = None,
+ api_key: str | None = None,
+ extra_body: dict[str, Any] | None = None,
+ extra_headers: dict[str, str] | None = None,
+ timeout_seconds: float = DEFAULT_REQUEST_TIMEOUT_SECONDS,
+ client_factory: type[openai.AsyncOpenAI] = openai.AsyncOpenAI,
+) -> Any:
+ """Non-streaming OpenAI-compat chat call, returns the raw SDK
+ ``ChatCompletion`` so callers that already navigate
+ ``response.usage`` / ``response.choices`` directly don't need to
+ rewrite their extraction logic.
+
+ Used by the chat title-generation path. New callers without
+ SDK-specific extraction logic should prefer ``call_provider``
+ which normalizes into ``ProviderResponse``.
+
+ Either pass a pre-built ``client`` OR ``base_url`` + ``api_key``
+ + (optionally) ``client_factory``. See ``call_provider_stream``
+ for rationale.
+ """
+ sanitize_messages_for_utf8(messages)
+ if client is None:
+ if base_url is None or api_key is None:
+ raise ValueError(
+ "call_provider_openai_compat_sync: pass either `client` "
+ "or both `base_url` and `api_key`."
+ )
+ client = client_factory(base_url=base_url, api_key=api_key)
+ create_kwargs: dict[str, Any] = {
+ "model": model,
+ "messages": cast(list[ChatCompletionMessageParam], messages),
+ "max_tokens": max_tokens,
+ "timeout": timeout_seconds,
+ }
+ if extra_body:
+ create_kwargs["extra_body"] = extra_body
+ if extra_headers:
+ create_kwargs["extra_headers"] = extra_headers
+ return await client.chat.completions.create(**create_kwargs)
+
+
+# ---------------------------------------------------------------------------
+# Batch submission (Anthropic Messages Batches API)
+# ---------------------------------------------------------------------------
+
+
+async def _submit_batch_one_request(
+ *,
+ provider: ProviderLiteral,
+ model: str,
+ api_key: str,
+ messages: list[dict],
+ max_tokens: int,
+ temperature: float | None,
+ tools: list[dict] | None,
+ tool_choice: dict | None,
+ custom_id: str,
+) -> BatchSubmissionRef:
+ """Submit a single-request batch and return the provider's handle.
+
+ The shared helper takes one ``call_provider(execution_mode="batch")``
+ invocation = one batch submission with exactly one request. Callers
+ that want to group several requests into one batch (e.g. dream
+ submitting 3 phases together for a single ``custom_id`` namespace)
+ can layer their own grouping on top — for the in-process orchestrator
+ today, one request per submission is the right granularity because
+ each phase has its own ``custom_id`` and ``apply`` handler anyway.
+
+ Result apply is async — the BatchExecutor service polls Anthropic
+ every 30s → 5min backoff, downloads results when ``processing_status
+ == 'ended'``, and dispatches to a caller-registered callback keyed
+ on ``custom_id``.
+ """
+ if provider == "anthropic":
+ return await _submit_anthropic_batch(
+ model=model,
+ api_key=api_key,
+ messages=messages,
+ max_tokens=max_tokens,
+ temperature=temperature,
+ tools=tools,
+ tool_choice=tool_choice,
+ custom_id=custom_id,
+ )
+ if provider == "openai":
+ raise NotImplementedError(
+ "OpenAI batch submission is a follow-up to Step 4 "
+ "(Anthropic-first; OpenAI batch lands when we add OpenAI "
+ "models to the dream pass)."
+ )
+ raise NotImplementedError(
+ f"execution_mode='batch' is only supported for provider='anthropic' "
+ f"today; got provider={provider!r}. Callers should route to sync_baseline."
+ )
+
+
+async def _submit_anthropic_batch(
+ *,
+ model: str,
+ api_key: str,
+ messages: list[dict],
+ max_tokens: int,
+ temperature: float | None,
+ tools: list[dict] | None,
+ tool_choice: dict | None,
+ custom_id: str,
+) -> BatchSubmissionRef:
+ """Call ``client.messages.batches.create`` for a single-request batch.
+
+ Anthropic accepts ``requests=[{custom_id, params}]`` where ``params``
+ is a ``MessageCreateParams`` dict. We reuse the same message reshape
+ + system-prompt wrapping logic the sync Anthropic path uses, so a
+ batch request and its sync equivalent produce semantically identical
+ LLM behaviour.
+ """
+ an_tools = convert_openai_tool_fmt_to_anthropic(tools)
+ if isinstance(an_tools, list) and an_tools:
+ an_tools[-1] = {**an_tools[-1], "cache_control": {"type": "ephemeral"}}
+
+ system_messages = [p["content"] for p in messages if p["role"] == "system"]
+ sysprompt = " ".join(system_messages)
+
+ anth_messages: list[dict] = []
+ last_role: str | None = None
+ for p in messages:
+ if p["role"] in ("user", "assistant"):
+ if (
+ p["role"] == last_role
+ and anth_messages
+ and isinstance(anth_messages[-1]["content"], str)
+ and isinstance(p["content"], str)
+ ):
+ anth_messages[-1]["content"] += p["content"]
+ else:
+ anth_messages.append({"role": p["role"], "content": p["content"]})
+ last_role = p["role"]
+
+ params: dict[str, Any] = {
+ "model": model,
+ "messages": anth_messages,
+ "max_tokens": max_tokens,
+ }
+ if temperature is not None:
+ params["temperature"] = temperature
+ # Only attach tools / tool_choice when the caller actually passed
+ # them — Anthropic rejects empty arrays with HTTP 400.
+ if isinstance(an_tools, list) and an_tools:
+ params["tools"] = an_tools
+ if tool_choice is not None:
+ params["tool_choice"] = tool_choice
+ if sysprompt.strip():
+ params["system"] = [
+ {
+ "type": "text",
+ "text": sysprompt,
+ "cache_control": {"type": "ephemeral"},
+ }
+ ]
+
+ client = anthropic.AsyncAnthropic(api_key=api_key)
+ # Anthropic's typed Request union is too strict for our dynamic
+ # params shape (we conditionally include ``system`` / ``tools`` /
+ # ``tool_choice``). The runtime contract accepts any dict matching
+ # ``MessageCreateParamsNonStreaming`` — cast to ``Any`` to bypass
+ # pyright's nominal check.
+ batch_requests: Any = [{"custom_id": custom_id, "params": params}]
+ batch = await client.messages.batches.create(requests=batch_requests)
+
+ return BatchSubmissionRef(
+ provider="anthropic",
+ provider_batch_id=batch.id,
+ custom_id=custom_id,
+ submitted_at=datetime.now(timezone.utc),
+ )
+
+
+async def cancel_batch(
+ *, provider: ProviderLiteral, provider_batch_id: str, api_key: str
+) -> bool:
+ """Best-effort cancel of an in-flight provider batch.
+
+ Used when local bookkeeping fails *after* the provider already
+ accepted a batch submission (e.g. the BatchExecutor pending-queue
+ write fails): without a cancel the provider would run the paid batch
+ to completion with no callback to consume it, orphaning the spend.
+ Never raises — returns ``True`` only when the provider acknowledged
+ the cancel.
+ """
+ try:
+ if provider == "anthropic":
+ client = anthropic.AsyncAnthropic(api_key=api_key)
+ await client.messages.batches.cancel(provider_batch_id)
+ return True
+ logger.warning(
+ "cancel_batch: no cancel path for provider=%s (batch=%s)",
+ provider,
+ provider_batch_id,
+ )
+ return False
+ except Exception:
+ logger.exception(
+ "cancel_batch: failed to cancel provider=%s batch=%s",
+ provider,
+ provider_batch_id,
+ )
+ return False
+
+
+# ---------------------------------------------------------------------------
+# Batch poll + download (used by the BatchExecutor service)
+# ---------------------------------------------------------------------------
+
+
+BatchStatusLiteral = Literal["pending", "processing", "ended", "failed"]
+
+
+@dataclass(slots=True)
+class BatchResultRow:
+ """One row from a downloaded batch result.
+
+ Mirrors what ``dream/batch/models.BatchResult`` carries — kept as a
+ plain dataclass at this layer so callers don't have to pull the
+ dream-pass module into shared infrastructure.
+ """
+
+ custom_id: str
+ content: str
+ input_tokens: int
+ output_tokens: int
+ cache_read_tokens: int = 0
+ cache_creation_tokens: int = 0
+ error: str | None = None
+ # Provider-native result object for callers that need raw access.
+ # Kept out of repr + pydantic serialization (it's an opaque SDK object).
+ raw_result: Any = Field(default=None, repr=False, exclude=True)
+
+
+async def poll_batch(
+ *, provider: ProviderLiteral, provider_batch_id: str, api_key: str
+) -> BatchStatusLiteral:
+ """Return the current normalized status of a submitted batch.
+
+ Maps Anthropic's ``processing_status`` (``in_progress`` /
+ ``canceling`` / ``ended``) onto a small four-state enum the
+ BatchExecutor switches on. ``canceling`` collapses to
+ ``processing`` because callers can't act on it differently — we
+ let Anthropic finish the cancellation and the next poll catches
+ ``ended`` / ``failed``.
+ """
+ if provider != "anthropic":
+ raise NotImplementedError(
+ f"poll_batch only supports provider='anthropic' today; "
+ f"got {provider!r}."
+ )
+ client = anthropic.AsyncAnthropic(api_key=api_key)
+ batch = await client.messages.batches.retrieve(provider_batch_id)
+ status = getattr(batch, "processing_status", None)
+ if status == "ended":
+ return "ended"
+ if status == "in_progress":
+ return "processing"
+ if status == "canceling":
+ return "processing"
+ # Unknown / future states → log + report pending so the caller polls again.
+ logger.warning(
+ "Unknown Anthropic batch processing_status=%r — reporting pending.",
+ status,
+ )
+ return "pending"
+
+
+async def download_batch_results(
+ *, provider: ProviderLiteral, provider_batch_id: str, api_key: str
+) -> list[BatchResultRow]:
+ """Download all per-request rows for a completed batch.
+
+ Anthropic streams results as JSONL (one JSON object per line). For
+ each line we extract:
+
+ * ``custom_id`` — caller routing key
+ * Either ``message.content`` (succeeded) → flatten to a JSON
+ string for the dream parser, OR an error string
+ * Per-row usage (input/output/cache_read/cache_creation)
+
+ The downloaded rows are returned in submission order so callers
+ can correlate by index when they don't care about ``custom_id``.
+ """
+ if provider != "anthropic":
+ raise NotImplementedError(
+ f"download_batch_results only supports provider='anthropic' "
+ f"today; got {provider!r}."
+ )
+ client = anthropic.AsyncAnthropic(api_key=api_key)
+ rows: list[BatchResultRow] = []
+ async for entry in await client.messages.batches.results(provider_batch_id):
+ custom_id = getattr(entry, "custom_id", "") or ""
+ result = getattr(entry, "result", None)
+ result_type = getattr(result, "type", None) if result is not None else None
+ if result_type == "succeeded":
+ message = getattr(result, "message", None)
+ content_text = _anthropic_content_to_text(message)
+ usage = getattr(message, "usage", None) if message is not None else None
+ input_tokens = int(getattr(usage, "input_tokens", 0) or 0)
+ output_tokens = int(getattr(usage, "output_tokens", 0) or 0)
+ cache_read = int(getattr(usage, "cache_read_input_tokens", 0) or 0)
+ cache_creation = int(getattr(usage, "cache_creation_input_tokens", 0) or 0)
+ rows.append(
+ BatchResultRow(
+ custom_id=custom_id,
+ content=content_text,
+ input_tokens=input_tokens,
+ output_tokens=output_tokens,
+ cache_read_tokens=cache_read,
+ cache_creation_tokens=cache_creation,
+ raw_result=entry,
+ )
+ )
+ else:
+ # ``errored`` / ``canceled`` / ``expired`` — surface the
+ # error string but keep token counts at 0 (the request
+ # didn't run, so we don't owe Anthropic anything for it).
+ error_obj = getattr(result, "error", None) if result is not None else None
+ error_str = (
+ str(error_obj) if error_obj is not None else (result_type or "errored")
+ )
+ rows.append(
+ BatchResultRow(
+ custom_id=custom_id,
+ content="",
+ input_tokens=0,
+ output_tokens=0,
+ error=error_str,
+ raw_result=entry,
+ )
+ )
+ return rows
+
+
+def _anthropic_content_to_text(message: Any) -> str:
+ """Flatten an Anthropic ``message.content`` blob into a string.
+
+ Three shapes the BatchExecutor's downstream parser handles:
+ * Single ``text`` block → return its ``text``.
+ * Single ``tool_use`` block → return ``json.dumps(input)``. This
+ is the "structured output" path (forced ``tool_choice`` makes
+ Claude emit exactly one tool_use block; the dream pass parses
+ the JSON straight into a Pydantic model).
+ * Multi-block / unknown → join all ``text`` blocks with newlines.
+
+ Returns ``""`` when the message is missing or empty.
+ """
+ if message is None:
+ return ""
+ content = getattr(message, "content", None) or []
+ if not content:
+ return ""
+ first = content[0]
+ first_type = getattr(first, "type", None)
+ if first_type == "tool_use" and len(content) == 1:
+ return json_module.dumps(getattr(first, "input", {}) or {})
+ if first_type == "text" and len(content) == 1:
+ return getattr(first, "text", "") or ""
+ # Multi-block fallback — concatenate text blocks.
+ parts: list[str] = []
+ for block in content:
+ if getattr(block, "type", None) == "text":
+ parts.append(getattr(block, "text", "") or "")
+ return "\n".join(parts)
diff --git a/autogpt_platform/backend/backend/util/llm/providers_test.py b/autogpt_platform/backend/backend/util/llm/providers_test.py
new file mode 100644
index 0000000000..3fd42b8e79
--- /dev/null
+++ b/autogpt_platform/backend/backend/util/llm/providers_test.py
@@ -0,0 +1,1834 @@
+"""Tests for ``util.llm.providers.call_provider``.
+
+These tests mock each provider's SDK at its construction point so the
+test suite never makes a real network call. The goal is to lock in
+that ``call_provider`` dispatches to the right SDK with the right
+arguments, and that the normalized ``ProviderResponse`` carries the
+fields each provider exposes.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from backend.util.llm.providers import (
+ DEFAULT_REQUEST_TIMEOUT_SECONDS,
+ ProviderResponse,
+ call_provider,
+)
+
+
+def _msg(role: str, content: str) -> dict:
+ return {"role": role, "content": content}
+
+
+# ---------------------------------------------------------------------------
+# Execution mode gating
+# ---------------------------------------------------------------------------
+
+
+class TestExecutionModeStubs:
+ """Flex mode + batch-on-non-Anthropic raise NotImplementedError until
+ later steps land. Pinning this keeps the contract honest: callers
+ that opt in early get a loud failure, not silent fallback to sync.
+
+ Anthropic batch lands in Step 4 (this commit) — see
+ ``TestBatchSubmission`` below for its tests.
+ """
+
+ @pytest.mark.asyncio
+ async def test_batch_mode_on_openai_raises_not_implemented(self):
+ with pytest.raises(NotImplementedError, match="OpenAI batch"):
+ await call_provider(
+ provider="openai",
+ model="gpt-4o",
+ api_key="sk-test",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ execution_mode="batch",
+ custom_id="probe",
+ )
+
+ @pytest.mark.asyncio
+ async def test_batch_mode_on_groq_raises_not_implemented(self):
+ with pytest.raises(NotImplementedError, match="provider='anthropic'"):
+ await call_provider(
+ provider="groq",
+ model="mixtral",
+ api_key="x",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ execution_mode="batch",
+ custom_id="probe",
+ )
+
+ @pytest.mark.asyncio
+ async def test_batch_mode_requires_custom_id(self):
+ with pytest.raises(ValueError, match="custom_id"):
+ await call_provider(
+ provider="anthropic",
+ model="claude-sonnet-4-6",
+ api_key="sk-test",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ execution_mode="batch",
+ )
+
+ @pytest.mark.asyncio
+ async def test_flex_mode_passes_service_tier_to_openai_responses(self):
+ """OpenAI native exposes ``service_tier="flex"`` via the Responses
+ API. The helper must inject it via ``extra_body`` so the SDK
+ forwards it on payloads even on SDK versions that don't surface
+ ``service_tier`` as a typed kwarg."""
+ from backend.util.llm.providers import _call_openai_responses
+
+ captured: dict[str, object] = {}
+
+ class _StubResponses:
+ async def create(self, **kwargs):
+ captured.update(kwargs)
+ resp = MagicMock()
+ resp.output = []
+ resp.usage = MagicMock(input_tokens=1, output_tokens=1)
+ return resp
+
+ class _StubClient:
+ def __init__(self, *args, **kwargs):
+ self.responses = _StubResponses()
+
+ with patch(
+ "backend.util.llm.providers.openai.AsyncOpenAI", new=_StubClient
+ ), patch(
+ "backend.util.llm.providers.extract_responses_content",
+ return_value="",
+ ), patch(
+ "backend.util.llm.providers.extract_responses_tool_calls",
+ return_value=[],
+ ), patch(
+ "backend.util.llm.providers.extract_responses_usage",
+ return_value=(1, 1),
+ ), patch(
+ "backend.util.llm.providers.extract_responses_reasoning",
+ return_value=None,
+ ):
+ await _call_openai_responses(
+ model="gpt-4o",
+ api_key="sk-test",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ temperature=None,
+ tools=None,
+ force_json_output=False,
+ parallel_tool_calls=False,
+ timeout_seconds=30.0,
+ service_tier="flex",
+ )
+
+ assert captured.get("extra_body") == {"service_tier": "flex"}
+
+ @pytest.mark.asyncio
+ async def test_flex_mode_passes_service_tier_via_openrouter_extra_body(
+ self,
+ ):
+ """OpenRouter forwards ``service_tier`` to OpenAI/Google upstreams
+ via ``extra_body``. The merge with the OpenRouter-extras
+ ``usage.include`` block must keep both keys — neither overrides
+ the other."""
+ from backend.util.llm.providers import _call_openai_compat
+
+ captured: dict[str, object] = {}
+
+ class _StubCompletions:
+ async def create(self, **kwargs):
+ captured.update(kwargs)
+ msg = MagicMock()
+ msg.content = ""
+ choice = MagicMock()
+ choice.message = msg
+ resp = MagicMock()
+ resp.choices = [choice]
+ resp.usage = MagicMock(prompt_tokens=1, completion_tokens=1)
+ return resp
+
+ class _StubClient:
+ def __init__(self, *args, **kwargs):
+ self.chat = SimpleNamespace(completions=_StubCompletions())
+
+ with patch(
+ "backend.util.llm.providers.openai.AsyncOpenAI", new=_StubClient
+ ), patch(
+ "backend.util.llm.providers._extract_openai_compat_cache_tokens",
+ return_value=(0, 0),
+ ), patch(
+ "backend.util.llm.providers.extract_openai_tool_calls",
+ return_value=None,
+ ), patch(
+ "backend.util.llm.providers.extract_openai_reasoning",
+ return_value=None,
+ ), patch(
+ "backend.util.llm.providers.extract_openrouter_cost",
+ return_value=None,
+ ):
+ await _call_openai_compat(
+ base_url="https://openrouter.ai/api/v1",
+ model="openai/gpt-4o",
+ api_key="ork-test",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ temperature=None,
+ tools=None,
+ force_json_output=False,
+ parallel_tool_calls=False,
+ timeout_seconds=30.0,
+ include_openrouter_extras=True,
+ service_tier="flex",
+ )
+
+ extra_body = captured.get("extra_body")
+ assert isinstance(extra_body, dict)
+ assert extra_body.get("service_tier") == "flex"
+ # OpenRouter cost-include must survive the merge — losing it
+ # silently disables cost-based rate limiting on flex turns.
+ assert extra_body.get("usage") == {"include": True}
+
+ @pytest.mark.asyncio
+ async def test_flex_mode_falls_through_to_sync_for_unsupported_provider(
+ self, caplog
+ ):
+ """Anthropic + Groq + the open-weight gateways have no flex tier.
+ Callers must get a sync execution instead of a hard error, with
+ a log line so the dashboard can surface the silent fallback."""
+ sync_mock = AsyncMock(
+ return_value=MagicMock(
+ content="ok",
+ prompt_tokens=1,
+ completion_tokens=1,
+ )
+ )
+ with patch(
+ "backend.util.llm.providers._dispatch_sync", new=sync_mock
+ ), caplog.at_level("WARNING"):
+ await call_provider(
+ provider="anthropic",
+ model="claude-sonnet-4-6",
+ api_key="sk-ant-test",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ execution_mode="flex",
+ )
+ sync_mock.assert_awaited_once()
+ assert sync_mock.call_args.kwargs.get("service_tier") is None
+ assert any(
+ "execution_mode='flex' requested for provider=anthropic" in rec.message
+ for rec in caplog.records
+ )
+
+
+# ---------------------------------------------------------------------------
+# Unsupported provider
+# ---------------------------------------------------------------------------
+
+
+class TestUnsupportedProvider:
+ @pytest.mark.asyncio
+ async def test_raises_value_error_with_provider_name(self):
+ with pytest.raises(ValueError, match="Unsupported LLM provider"):
+ await call_provider(
+ provider="made_up_provider", # type: ignore[arg-type]
+ model="x",
+ api_key="x",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ )
+
+
+# ---------------------------------------------------------------------------
+# OpenAI Responses API
+# ---------------------------------------------------------------------------
+
+
+class TestOpenAIResponses:
+ @pytest.mark.asyncio
+ async def test_dispatches_to_openai_responses_create(self):
+ fake_response = SimpleNamespace() # extractors are also mocked
+
+ async_create = AsyncMock(return_value=fake_response)
+ fake_client = SimpleNamespace(responses=SimpleNamespace(create=async_create))
+
+ with (
+ patch(
+ "backend.util.llm.providers.openai.AsyncOpenAI",
+ return_value=fake_client,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_responses_tool_calls",
+ return_value=None,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_responses_content",
+ return_value="hello world",
+ ),
+ patch(
+ "backend.util.llm.providers.extract_responses_reasoning",
+ return_value=None,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_responses_usage",
+ return_value=(11, 22),
+ ),
+ ):
+ result = await call_provider(
+ provider="openai",
+ model="gpt-4o",
+ api_key="sk-test",
+ messages=[_msg("user", "hi")],
+ max_tokens=100,
+ )
+
+ assert isinstance(result, ProviderResponse)
+ assert result.content == "hello world"
+ assert result.prompt_tokens == 11
+ assert result.completion_tokens == 22
+ async_create.assert_awaited_once()
+ kwargs = async_create.call_args.kwargs
+ assert kwargs["model"] == "gpt-4o"
+ assert kwargs["max_output_tokens"] == 100
+ assert kwargs["store"] is False
+
+
+# ---------------------------------------------------------------------------
+# Anthropic Messages API
+# ---------------------------------------------------------------------------
+
+
+class TestAnthropicMessages:
+ @pytest.mark.asyncio
+ async def test_dispatches_to_anthropic_messages_create_and_normalizes_usage(
+ self,
+ ):
+ fake_usage = SimpleNamespace(
+ input_tokens=5,
+ output_tokens=7,
+ cache_read_input_tokens=3,
+ cache_creation_input_tokens=2,
+ )
+ fake_text_block = SimpleNamespace(type="text", text="ok")
+ fake_response = SimpleNamespace(
+ content=[fake_text_block],
+ usage=fake_usage,
+ stop_reason="end_turn",
+ )
+
+ async_create = AsyncMock(return_value=fake_response)
+ fake_client = SimpleNamespace(messages=SimpleNamespace(create=async_create))
+
+ with patch(
+ "backend.util.llm.providers.anthropic.AsyncAnthropic",
+ return_value=fake_client,
+ ):
+ result = await call_provider(
+ provider="anthropic",
+ model="claude-sonnet-4-6",
+ api_key="sk-test",
+ messages=[
+ _msg("system", "you are helpful"),
+ _msg("user", "hi"),
+ ],
+ max_tokens=200,
+ temperature=0.3,
+ )
+
+ assert isinstance(result, ProviderResponse)
+ assert result.content == "ok"
+ assert result.prompt_tokens == 5
+ assert result.completion_tokens == 7
+ assert result.cache_read_tokens == 3
+ assert result.cache_creation_tokens == 2
+
+ kwargs = async_create.call_args.kwargs
+ assert kwargs["model"] == "claude-sonnet-4-6"
+ assert kwargs["max_tokens"] == 200
+ assert kwargs["temperature"] == 0.3
+ # System prompt wrapped in a cache-controlled text block.
+ assert isinstance(kwargs["system"], list)
+ assert kwargs["system"][0]["text"] == "you are helpful"
+ assert kwargs["system"][0]["cache_control"] == {"type": "ephemeral"}
+
+ @pytest.mark.asyncio
+ async def test_omits_system_field_for_whitespace_only_prompt(self):
+ """Anthropic rejects empty text blocks (HTTP 400). For
+ whitespace-only system content we must omit the field entirely."""
+ fake_usage = SimpleNamespace(input_tokens=1, output_tokens=1)
+ fake_response = SimpleNamespace(
+ content=[SimpleNamespace(type="text", text="x")],
+ usage=fake_usage,
+ stop_reason="end_turn",
+ )
+ async_create = AsyncMock(return_value=fake_response)
+ fake_client = SimpleNamespace(messages=SimpleNamespace(create=async_create))
+ with patch(
+ "backend.util.llm.providers.anthropic.AsyncAnthropic",
+ return_value=fake_client,
+ ):
+ await call_provider(
+ provider="anthropic",
+ model="claude-sonnet-4-6",
+ api_key="sk-test",
+ messages=[_msg("system", " "), _msg("user", "hi")],
+ max_tokens=10,
+ )
+ assert "system" not in async_create.call_args.kwargs
+
+ @pytest.mark.asyncio
+ async def test_passes_tool_choice_when_provided(self):
+ """Tool-use forced output relies on tool_choice making it into
+ create_kwargs. If this is dropped, the model is free to emit prose."""
+ fake_response = SimpleNamespace(
+ content=[SimpleNamespace(type="text", text="x")],
+ usage=SimpleNamespace(input_tokens=1, output_tokens=1),
+ stop_reason="end_turn",
+ )
+ async_create = AsyncMock(return_value=fake_response)
+ fake_client = SimpleNamespace(messages=SimpleNamespace(create=async_create))
+ with patch(
+ "backend.util.llm.providers.anthropic.AsyncAnthropic",
+ return_value=fake_client,
+ ):
+ await call_provider(
+ provider="anthropic",
+ model="claude-sonnet-4-6",
+ api_key="sk-test",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ tool_choice={"type": "tool", "name": "submit_dream_ops"},
+ )
+ assert async_create.call_args.kwargs["tool_choice"] == {
+ "type": "tool",
+ "name": "submit_dream_ops",
+ }
+
+ @pytest.mark.asyncio
+ async def test_raises_when_content_empty(self):
+ fake_response = SimpleNamespace(
+ content=[],
+ usage=SimpleNamespace(input_tokens=1, output_tokens=0),
+ stop_reason="end_turn",
+ )
+ with patch(
+ "backend.util.llm.providers.anthropic.AsyncAnthropic",
+ return_value=SimpleNamespace(
+ messages=SimpleNamespace(create=AsyncMock(return_value=fake_response))
+ ),
+ ):
+ with pytest.raises(ValueError, match="No content"):
+ await call_provider(
+ provider="anthropic",
+ model="claude-sonnet-4-6",
+ api_key="sk-test",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Groq
+# ---------------------------------------------------------------------------
+
+
+class TestGroq:
+ @pytest.mark.asyncio
+ async def test_rejects_tools_param(self):
+ """Groq SDK doesn't support tool calling; pin the error so we
+ don't silently strip tools and surprise callers."""
+ with pytest.raises(ValueError, match="Groq does not support tools"):
+ await call_provider(
+ provider="groq",
+ model="mixtral-8x7b",
+ api_key="x",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ tools=[{"name": "x", "parameters": {}}],
+ )
+
+ @pytest.mark.asyncio
+ async def test_dispatches_with_response_format_when_force_json(self):
+ fake_usage = SimpleNamespace(prompt_tokens=4, completion_tokens=6)
+ fake_message = SimpleNamespace(content="{}")
+ fake_choice = SimpleNamespace(message=fake_message)
+ fake_response = SimpleNamespace(choices=[fake_choice], usage=fake_usage)
+ async_create = AsyncMock(return_value=fake_response)
+ fake_client = SimpleNamespace(
+ chat=SimpleNamespace(completions=SimpleNamespace(create=async_create))
+ )
+ with patch(
+ "groq.AsyncGroq",
+ return_value=fake_client,
+ ):
+ result = await call_provider(
+ provider="groq",
+ model="mixtral-8x7b",
+ api_key="x",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ force_json_output=True,
+ )
+
+ assert result.content == "{}"
+ assert result.prompt_tokens == 4
+ assert result.completion_tokens == 6
+ kwargs = async_create.call_args.kwargs
+ assert kwargs["response_format"] == {"type": "json_object"}
+
+
+# ---------------------------------------------------------------------------
+# OpenAI-compat (OpenRouter, Llama API, AI/ML, v0)
+# ---------------------------------------------------------------------------
+
+
+def _fake_openai_chat_response(
+ content: str, prompt: int, completion: int, *, cost: float | None = None
+) -> SimpleNamespace:
+ usage = SimpleNamespace(
+ prompt_tokens=prompt,
+ completion_tokens=completion,
+ model_extra={"cost": cost} if cost is not None else None,
+ )
+ message = SimpleNamespace(content=content, tool_calls=None)
+ choice = SimpleNamespace(message=message)
+ return SimpleNamespace(choices=[choice], usage=usage)
+
+
+class TestOpenRouter:
+ @pytest.mark.asyncio
+ async def test_dispatches_with_openrouter_extras(self):
+ fake_response = _fake_openai_chat_response(
+ "hello", prompt=10, completion=5, cost=0.0123
+ )
+ async_create = AsyncMock(return_value=fake_response)
+ fake_client = SimpleNamespace(
+ chat=SimpleNamespace(completions=SimpleNamespace(create=async_create))
+ )
+ with (
+ patch(
+ "backend.util.llm.providers.openai.AsyncOpenAI",
+ return_value=fake_client,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_openai_reasoning",
+ return_value=None,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_openai_tool_calls",
+ return_value=None,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_openrouter_cost",
+ return_value=0.0123,
+ ),
+ ):
+ result = await call_provider(
+ provider="open_router",
+ model="anthropic/claude-sonnet-4-6",
+ api_key="sk-or-test",
+ messages=[_msg("user", "hi")],
+ max_tokens=100,
+ )
+
+ assert result.content == "hello"
+ assert result.cost_usd == 0.0123
+ kwargs = async_create.call_args.kwargs
+ # OpenRouter-specific extras must be present so the response
+ # carries cost data.
+ assert kwargs["extra_body"] == {"usage": {"include": True}}
+ assert "HTTP-Referer" in kwargs["extra_headers"]
+
+
+class TestLlamaAPI:
+ @pytest.mark.asyncio
+ async def test_omits_openrouter_extras(self):
+ fake_response = _fake_openai_chat_response("x", prompt=1, completion=1)
+ async_create = AsyncMock(return_value=fake_response)
+ fake_client = SimpleNamespace(
+ chat=SimpleNamespace(completions=SimpleNamespace(create=async_create))
+ )
+ with (
+ patch(
+ "backend.util.llm.providers.openai.AsyncOpenAI",
+ return_value=fake_client,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_openai_reasoning",
+ return_value=None,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_openai_tool_calls",
+ return_value=None,
+ ),
+ ):
+ await call_provider(
+ provider="llama_api",
+ model="llama-3-70b",
+ api_key="x",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ )
+ kwargs = async_create.call_args.kwargs
+ # Llama API path doesn't ask for openrouter cost extras
+ assert "extra_body" not in kwargs
+
+
+class TestAIMLAPI:
+ @pytest.mark.asyncio
+ async def test_dispatches_with_default_headers(self):
+ fake_response = _fake_openai_chat_response("x", prompt=1, completion=1)
+ async_create = AsyncMock(return_value=fake_response)
+ fake_client = SimpleNamespace(
+ chat=SimpleNamespace(completions=SimpleNamespace(create=async_create))
+ )
+ constructor = MagicMock(return_value=fake_client)
+ with (
+ patch(
+ "backend.util.llm.providers.openai.AsyncOpenAI",
+ constructor,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_openai_reasoning",
+ return_value=None,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_openai_tool_calls",
+ return_value=None,
+ ),
+ ):
+ await call_provider(
+ provider="aiml_api",
+ model="anything",
+ api_key="x",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ )
+ # AI/ML expects branded headers on the client construction.
+ ctor_kwargs = constructor.call_args.kwargs
+ assert ctor_kwargs["default_headers"]["X-Project"] == "AutoGPT"
+
+
+# ---------------------------------------------------------------------------
+# Ollama
+# ---------------------------------------------------------------------------
+
+
[email protected](autouse=True)
+def _reset_chat_base_url_cache():
+ """The ChatConfig.base_url read is memoized module-wide; clear it so
+ each test's patched ``backend.copilot.config.ChatConfig`` is the one
+ actually constructed."""
+ from backend.util.llm.providers import _read_chat_config_base_url
+
+ _read_chat_config_base_url.cache_clear()
+ yield
+ _read_chat_config_base_url.cache_clear()
+
+
+def _fake_ollama_chat_client(
+ captured: dict,
+ *,
+ content: str = "ok",
+ prompt_eval_count: int | None = 7,
+ eval_count: int | None = 9,
+) -> SimpleNamespace:
+ """Fake ``ollama.AsyncClient`` exposing a ``chat`` coroutine that
+ records its kwargs and returns a ChatResponse-shaped object."""
+
+ async def chat(**kwargs):
+ captured.update(kwargs)
+ return SimpleNamespace(
+ message=SimpleNamespace(content=content),
+ prompt_eval_count=prompt_eval_count,
+ eval_count=eval_count,
+ )
+
+ return SimpleNamespace(chat=chat)
+
+
+@contextmanager
+def _patched_ollama_dispatch(
+ captured: dict,
+ *,
+ content: str = "ok",
+ chat_base_url: str | None = None,
+):
+ """Patch set for an Ollama dispatch test: mocked SSRF validation, a
+ stubbed copilot ``ChatConfig`` (so no real settings load happens),
+ and a fake ``ollama.AsyncClient``. Yields ``(validate_mock,
+ client_ctor_mock)``."""
+ validate_mock = AsyncMock(return_value=None)
+ client_ctor = MagicMock(
+ return_value=_fake_ollama_chat_client(captured, content=content)
+ )
+ with (
+ patch("backend.util.llm.providers.validate_url_host", new=validate_mock),
+ patch(
+ "backend.copilot.config.ChatConfig",
+ return_value=SimpleNamespace(base_url=chat_base_url),
+ ),
+ patch("backend.util.llm.providers.ollama.AsyncClient", new=client_ctor),
+ ):
+ yield validate_mock, client_ctor
+
+
+class TestOllama:
+ @pytest.mark.asyncio
+ async def test_rejects_tools_param(self):
+ with pytest.raises(ValueError, match="Ollama does not support tools"):
+ await call_provider(
+ provider="ollama",
+ model="llama3",
+ api_key="",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ tools=[{"name": "x"}],
+ )
+
+ @pytest.mark.asyncio
+ async def test_dispatches_via_chat_api_with_structured_messages(self):
+ """The dream prompts carry a real system + user conversation;
+ flattening them into a repr'd ``generate`` prompt fed the model
+ bracketed Python list syntax instead of a chat. The message list
+ must reach the chat API intact, roles included."""
+ captured: dict = {}
+ with _patched_ollama_dispatch(captured):
+ await call_provider(
+ provider="ollama",
+ model="llama3",
+ api_key="",
+ messages=[
+ _msg("system", "you are a memory consolidator"),
+ _msg("user", "consolidate these transcripts"),
+ ],
+ max_tokens=4096,
+ )
+ assert captured["messages"] == [
+ {"role": "system", "content": "you are a memory consolidator"},
+ {"role": "user", "content": "consolidate these transcripts"},
+ ]
+ assert captured["stream"] is False
+
+ @pytest.mark.asyncio
+ async def test_force_json_output_requests_json_format(self):
+ """``structured_completion`` passes ``force_json_output=True`` for
+ every dream phase and the dream docs promise forced JSON works on
+ every transport — Ollama honors it via ``format="json"``."""
+ captured: dict = {}
+ with _patched_ollama_dispatch(captured, content="{}"):
+ await call_provider(
+ provider="ollama",
+ model="llama3",
+ api_key="",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ force_json_output=True,
+ )
+ assert captured["format"] == "json"
+
+ @pytest.mark.asyncio
+ async def test_plain_completion_does_not_force_json_format(self):
+ captured: dict = {}
+ with _patched_ollama_dispatch(captured):
+ await call_provider(
+ provider="ollama",
+ model="llama3",
+ api_key="",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ )
+ assert captured["format"] is None
+
+ @pytest.mark.asyncio
+ async def test_max_tokens_caps_output_via_num_predict_not_num_ctx(self):
+ """``num_ctx`` is the INPUT context window — setting it from
+ ``max_tokens`` silently truncated the consolidate/recombine
+ prompts (whole transcripts + fact lists) at the output budget.
+ The output cap belongs on ``num_predict``; ``num_ctx`` stays at
+ the model default."""
+ captured: dict = {}
+ with _patched_ollama_dispatch(captured):
+ await call_provider(
+ provider="ollama",
+ model="llama3",
+ api_key="",
+ messages=[_msg("user", "hi")],
+ max_tokens=4096,
+ )
+ assert captured["options"]["num_predict"] == 4096
+ assert "num_ctx" not in captured["options"]
+
+ @pytest.mark.asyncio
+ async def test_normalizes_chat_response_into_provider_response(self):
+ captured: dict = {}
+ with _patched_ollama_dispatch(captured, content='{"facts": []}') as (_, ctor):
+ result = await call_provider(
+ provider="ollama",
+ model="llama3",
+ api_key="",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ ollama_host="http://gpu-box:11434",
+ timeout_seconds=42.0,
+ )
+ assert isinstance(result, ProviderResponse)
+ assert result.content == '{"facts": []}'
+ assert result.prompt_tokens == 7
+ assert result.completion_tokens == 9
+ ctor.assert_called_once_with(host="http://gpu-box:11434", timeout=42.0)
+
+
+class TestOllamaTrustedHosts:
+ """SSRF trust list for the Ollama dispatch. The host can be
+ user-supplied (block input field) so it must be validated — but the
+ allowlist has to include BOTH operator-set endpoints: the block
+ layer's ``Config.ollama_host`` AND the copilot ``CHAT_BASE_URL``
+ the dream pass routes through on the local transport. Trusting only
+ the former made every local dream phase fail with a misleading
+ 'blocked IP' error whenever the two were configured differently."""
+
+ @pytest.mark.asyncio
+ async def test_trust_list_includes_chat_base_url_and_block_config_host(self):
+ from backend.util.llm.providers import settings
+
+ captured: dict = {}
+ with _patched_ollama_dispatch(
+ captured,
+ chat_base_url="http://host.docker.internal:11434/v1",
+ ) as (validate_mock, _):
+ await call_provider(
+ provider="ollama",
+ model="llama3",
+ api_key="",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ ollama_host="http://host.docker.internal:11434",
+ )
+ validate_mock.assert_awaited_once()
+ assert validate_mock.call_args.args[0] == "http://host.docker.internal:11434"
+ assert validate_mock.call_args.kwargs["trusted_hostnames"] == [
+ settings.config.ollama_host,
+ "http://host.docker.internal:11434/v1",
+ ]
+
+ @pytest.mark.asyncio
+ async def test_chat_config_failure_falls_back_to_block_config_trust_list(
+ self, caplog
+ ):
+ """A misconfigured copilot ``ChatConfig`` (its validators raise at
+ construction) must not take down block-layer Ollama calls — the
+ trust list degrades to ``Config.ollama_host`` only."""
+ from backend.util.llm.providers import settings
+
+ captured: dict = {}
+ validate_mock = AsyncMock(return_value=None)
+ with (
+ patch(
+ "backend.util.llm.providers.validate_url_host",
+ new=validate_mock,
+ ),
+ patch(
+ "backend.copilot.config.ChatConfig",
+ side_effect=ValueError("misconfigured transport"),
+ ),
+ patch(
+ "backend.util.llm.providers.ollama.AsyncClient",
+ return_value=_fake_ollama_chat_client(captured),
+ ),
+ caplog.at_level("WARNING"),
+ ):
+ result = await call_provider(
+ provider="ollama",
+ model="llama3",
+ api_key="",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ )
+ assert isinstance(result, ProviderResponse)
+ assert validate_mock.call_args.kwargs["trusted_hostnames"] == [
+ settings.config.ollama_host
+ ]
+ assert any(
+ "Could not read ChatConfig.base_url" in rec.message
+ for rec in caplog.records
+ )
+
+ @pytest.mark.asyncio
+ async def test_lan_host_matching_chat_base_url_passes_real_ssrf_check(self):
+ """Regression for the local dream-pass failure: operator points
+ ``CHAT_BASE_URL`` at a LAN GPU box (private IP) while the block
+ layer's ``ollama_host`` stays at its localhost default. The real
+ ``validate_url_host`` must accept the host via the trust match
+ instead of rejecting the private IP."""
+ captured: dict = {}
+ client_ctor = MagicMock(return_value=_fake_ollama_chat_client(captured))
+ with (
+ patch(
+ "backend.copilot.config.ChatConfig",
+ return_value=SimpleNamespace(base_url="http://192.168.1.50:11434/v1"),
+ ),
+ patch("backend.util.llm.providers.ollama.AsyncClient", new=client_ctor),
+ ):
+ result = await call_provider(
+ provider="ollama",
+ model="llama3",
+ api_key="",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ ollama_host="http://192.168.1.50:11434",
+ )
+ assert isinstance(result, ProviderResponse)
+ client_ctor.assert_called_once()
+
+ @pytest.mark.asyncio
+ async def test_chat_config_is_constructed_once_across_dispatches(self):
+ """``ChatConfig`` is a pydantic-settings class with
+ ``env_file=".env"`` — constructing it per dispatch meant dotenv
+ disk I/O and repeated validator warnings on every Ollama call.
+ The base_url read must be memoized after the first success while
+ every dispatch still gets the cached value in its trust list."""
+ captured: dict = {}
+ validate_mock = AsyncMock(return_value=None)
+ chat_config_ctor = MagicMock(
+ return_value=SimpleNamespace(
+ base_url="http://host.docker.internal:11434/v1"
+ )
+ )
+ with (
+ patch("backend.util.llm.providers.validate_url_host", new=validate_mock),
+ patch("backend.copilot.config.ChatConfig", new=chat_config_ctor),
+ patch(
+ "backend.util.llm.providers.ollama.AsyncClient",
+ return_value=_fake_ollama_chat_client(captured),
+ ),
+ ):
+ for _ in range(3):
+ await call_provider(
+ provider="ollama",
+ model="llama3",
+ api_key="",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ )
+ chat_config_ctor.assert_called_once()
+ assert validate_mock.await_count == 3
+ for call in validate_mock.call_args_list:
+ assert (
+ "http://host.docker.internal:11434/v1"
+ in call.kwargs["trusted_hostnames"]
+ )
+
+ @pytest.mark.asyncio
+ async def test_chat_config_failure_is_not_cached_as_permanent_none(self):
+ """A transient ``ChatConfig`` construction failure degrades that
+ one dispatch to the block-layer trust list, but must not be
+ memoized — once the config is fixed, the next dispatch picks up
+ ``CHAT_BASE_URL`` again."""
+ from backend.util.llm.providers import settings
+
+ captured: dict = {}
+ validate_mock = AsyncMock(return_value=None)
+ chat_config_ctor = MagicMock(
+ side_effect=[
+ ValueError("transient misconfiguration"),
+ SimpleNamespace(base_url="http://192.168.1.50:11434/v1"),
+ ]
+ )
+ with (
+ patch("backend.util.llm.providers.validate_url_host", new=validate_mock),
+ patch("backend.copilot.config.ChatConfig", new=chat_config_ctor),
+ patch(
+ "backend.util.llm.providers.ollama.AsyncClient",
+ return_value=_fake_ollama_chat_client(captured),
+ ),
+ ):
+ for _ in range(2):
+ await call_provider(
+ provider="ollama",
+ model="llama3",
+ api_key="",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ )
+ first_call, second_call = validate_mock.call_args_list
+ assert first_call.kwargs["trusted_hostnames"] == [settings.config.ollama_host]
+ assert second_call.kwargs["trusted_hostnames"] == [
+ settings.config.ollama_host,
+ "http://192.168.1.50:11434/v1",
+ ]
+
+ @pytest.mark.asyncio
+ async def test_unconfigured_private_host_is_still_rejected(self):
+ """The widened trust list must not weaken the SSRF guard: a
+ private-IP host that appears in NEITHER config value is rejected
+ before any client is constructed."""
+ client_ctor = MagicMock()
+ with (
+ patch(
+ "backend.copilot.config.ChatConfig",
+ return_value=SimpleNamespace(base_url=None),
+ ),
+ patch("backend.util.llm.providers.ollama.AsyncClient", new=client_ctor),
+ ):
+ with pytest.raises(ValueError, match="blocked or private IP"):
+ await call_provider(
+ provider="ollama",
+ model="llama3",
+ api_key="",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ ollama_host="http://169.254.169.254:11434",
+ )
+ client_ctor.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# Temperature threading
+# ---------------------------------------------------------------------------
+
+
+class TestTemperatureThreading:
+ """The dream pass tunes temperature per phase (0.2 consolidate /
+ 0.9 recombine / 0.0 sanitize) on every transport. The dispatcher
+ used to forward it only to Anthropic — every other provider
+ silently ran at its default (~1.0), degrading memory-write quality
+ with no error. Pin that each path forwards the caller's value, and
+ that ``None`` keeps the field off the wire (some reasoning models
+ reject ``temperature`` — the Anthropic-style guard applies
+ everywhere)."""
+
+ def _openai_compat_patches(self, async_create):
+ fake_client = SimpleNamespace(
+ chat=SimpleNamespace(completions=SimpleNamespace(create=async_create))
+ )
+ return (
+ patch(
+ "backend.util.llm.providers.openai.AsyncOpenAI",
+ return_value=fake_client,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_openai_reasoning",
+ return_value=None,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_openai_tool_calls",
+ return_value=None,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_openrouter_cost",
+ return_value=None,
+ ),
+ )
+
+ @pytest.mark.asyncio
+ async def test_openrouter_receives_recombine_temperature(self):
+ fake_response = _fake_openai_chat_response("x", prompt=1, completion=1)
+ async_create = AsyncMock(return_value=fake_response)
+ p1, p2, p3, p4 = self._openai_compat_patches(async_create)
+ with p1, p2, p3, p4:
+ await call_provider(
+ provider="open_router",
+ model="anthropic/claude-sonnet-4-6",
+ api_key="sk-or-test",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ temperature=0.9,
+ )
+ assert async_create.call_args.kwargs["temperature"] == 0.9
+
+ @pytest.mark.asyncio
+ async def test_openrouter_omits_temperature_when_caller_unset(self):
+ fake_response = _fake_openai_chat_response("x", prompt=1, completion=1)
+ async_create = AsyncMock(return_value=fake_response)
+ p1, p2, p3, p4 = self._openai_compat_patches(async_create)
+ with p1, p2, p3, p4:
+ await call_provider(
+ provider="open_router",
+ model="openai/o3",
+ api_key="sk-or-test",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ )
+ assert "temperature" not in async_create.call_args.kwargs
+
+ @pytest.mark.asyncio
+ async def test_openai_responses_receives_consolidate_temperature(self):
+ async_create = AsyncMock(return_value=SimpleNamespace())
+ fake_client = SimpleNamespace(responses=SimpleNamespace(create=async_create))
+ with (
+ patch(
+ "backend.util.llm.providers.openai.AsyncOpenAI",
+ return_value=fake_client,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_responses_tool_calls",
+ return_value=None,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_responses_content",
+ return_value="ok",
+ ),
+ patch(
+ "backend.util.llm.providers.extract_responses_reasoning",
+ return_value=None,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_responses_usage",
+ return_value=(1, 1),
+ ),
+ ):
+ await call_provider(
+ provider="openai",
+ model="gpt-4o",
+ api_key="sk-test",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ temperature=0.2,
+ )
+ assert async_create.call_args.kwargs["temperature"] == 0.2
+
+ @pytest.mark.asyncio
+ async def test_openai_responses_omits_temperature_when_caller_unset(self):
+ """Reasoning models reject ``temperature`` — when the caller
+ doesn't set one, the SDK must receive the omit sentinel so the
+ field never reaches the wire."""
+ import openai
+
+ async_create = AsyncMock(return_value=SimpleNamespace())
+ fake_client = SimpleNamespace(responses=SimpleNamespace(create=async_create))
+ with (
+ patch(
+ "backend.util.llm.providers.openai.AsyncOpenAI",
+ return_value=fake_client,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_responses_tool_calls",
+ return_value=None,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_responses_content",
+ return_value="ok",
+ ),
+ patch(
+ "backend.util.llm.providers.extract_responses_reasoning",
+ return_value=None,
+ ),
+ patch(
+ "backend.util.llm.providers.extract_responses_usage",
+ return_value=(1, 1),
+ ),
+ ):
+ await call_provider(
+ provider="openai",
+ model="o3",
+ api_key="sk-test",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ )
+ assert async_create.call_args.kwargs["temperature"] is openai.omit
+
+ @pytest.mark.asyncio
+ async def test_groq_receives_zero_sanitize_temperature(self):
+ """0.0 is falsy but explicitly set (the sanitize phase runs
+ deterministic) — the None-guard must forward it, not drop it."""
+ fake_usage = SimpleNamespace(prompt_tokens=1, completion_tokens=1)
+ fake_response = SimpleNamespace(
+ choices=[SimpleNamespace(message=SimpleNamespace(content="x"))],
+ usage=fake_usage,
+ )
+ async_create = AsyncMock(return_value=fake_response)
+ fake_client = SimpleNamespace(
+ chat=SimpleNamespace(completions=SimpleNamespace(create=async_create))
+ )
+ with patch("groq.AsyncGroq", return_value=fake_client):
+ await call_provider(
+ provider="groq",
+ model="mixtral-8x7b",
+ api_key="x",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ temperature=0.0,
+ )
+ assert async_create.call_args.kwargs["temperature"] == 0.0
+
+ @pytest.mark.asyncio
+ async def test_groq_omits_temperature_when_caller_unset(self):
+ fake_usage = SimpleNamespace(prompt_tokens=1, completion_tokens=1)
+ fake_response = SimpleNamespace(
+ choices=[SimpleNamespace(message=SimpleNamespace(content="x"))],
+ usage=fake_usage,
+ )
+ async_create = AsyncMock(return_value=fake_response)
+ fake_client = SimpleNamespace(
+ chat=SimpleNamespace(completions=SimpleNamespace(create=async_create))
+ )
+ with patch("groq.AsyncGroq", return_value=fake_client):
+ await call_provider(
+ provider="groq",
+ model="mixtral-8x7b",
+ api_key="x",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ )
+ assert "temperature" not in async_create.call_args.kwargs
+
+ @pytest.mark.asyncio
+ async def test_ollama_receives_temperature_in_options(self):
+ captured: dict = {}
+ with _patched_ollama_dispatch(captured):
+ await call_provider(
+ provider="ollama",
+ model="llama3",
+ api_key="",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ temperature=0.2,
+ )
+ assert captured["options"]["temperature"] == 0.2
+
+ @pytest.mark.asyncio
+ async def test_ollama_omits_temperature_when_caller_unset(self):
+ captured: dict = {}
+ with _patched_ollama_dispatch(captured):
+ await call_provider(
+ provider="ollama",
+ model="llama3",
+ api_key="",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ )
+ assert "temperature" not in captured["options"]
+
+
+# ---------------------------------------------------------------------------
+# Timeout
+# ---------------------------------------------------------------------------
+
+
+class TestTimeoutWrapping:
+ @pytest.mark.asyncio
+ async def test_timeout_raises_TimeoutError_with_provider_name(self):
+ async def hang(*args, **kwargs):
+ import asyncio as a
+
+ await a.sleep(10)
+
+ fake_client = SimpleNamespace(
+ messages=SimpleNamespace(create=hang),
+ )
+ with patch(
+ "backend.util.llm.providers.anthropic.AsyncAnthropic",
+ return_value=fake_client,
+ ):
+ with pytest.raises(TimeoutError, match="anthropic/"):
+ await call_provider(
+ provider="anthropic",
+ model="claude-sonnet-4-6",
+ api_key="x",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ timeout_seconds=0.05,
+ )
+
+
+# ---------------------------------------------------------------------------
+# UTF-8 sanitization
+# ---------------------------------------------------------------------------
+
+
+class TestUtf8Sanitization:
+ @pytest.mark.asyncio
+ async def test_replaces_unpaired_surrogates_before_dispatch(self):
+ """Caller hands us a message with an unpaired surrogate; we must
+ sanitize before the SDK tries to UTF-8 encode the request body."""
+ bad = "\ud800lol" # unpaired high surrogate
+ captured: dict = {}
+
+ fake_response = SimpleNamespace(
+ content=[SimpleNamespace(type="text", text="ok")],
+ usage=SimpleNamespace(input_tokens=1, output_tokens=1),
+ stop_reason="end_turn",
+ )
+
+ async def fake_create(**kwargs):
+ captured["messages"] = kwargs["messages"]
+ return fake_response
+
+ fake_client = SimpleNamespace(
+ messages=SimpleNamespace(create=fake_create),
+ )
+ msgs = [_msg("user", bad)]
+ with patch(
+ "backend.util.llm.providers.anthropic.AsyncAnthropic",
+ return_value=fake_client,
+ ):
+ await call_provider(
+ provider="anthropic",
+ model="claude-sonnet-4-6",
+ api_key="x",
+ messages=msgs,
+ max_tokens=10,
+ )
+ sent = captured["messages"][0]["content"]
+ # Sanitization replaces the surrogate; the suffix survives.
+ assert "lol" in sent
+ # Roundtrip through UTF-8 must succeed now.
+ sent.encode("utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Defaults
+# ---------------------------------------------------------------------------
+
+
+class TestDefaults:
+ def test_default_timeout_is_120_seconds(self):
+ # Pin the SLA — anything bigger and a stalled provider can park
+ # an executor thread for too long.
+ assert DEFAULT_REQUEST_TIMEOUT_SECONDS == 120
+
+
+# ---------------------------------------------------------------------------
+# Anthropic batch submission + poll + download
+# ---------------------------------------------------------------------------
+
+
+from backend.util.llm.providers import ( # noqa: E402
+ BatchResultRow,
+ BatchSubmissionRef,
+ download_batch_results,
+ poll_batch,
+)
+
+
+class TestBatchSubmission:
+ @pytest.mark.asyncio
+ async def test_submits_to_anthropic_batches_create(self):
+ fake_batch = SimpleNamespace(id="msgbatch_abc123")
+ async_create = AsyncMock(return_value=fake_batch)
+ fake_client = SimpleNamespace(
+ messages=SimpleNamespace(batches=SimpleNamespace(create=async_create)),
+ )
+ with patch(
+ "backend.util.llm.providers.anthropic.AsyncAnthropic",
+ return_value=fake_client,
+ ):
+ ref = await call_provider(
+ provider="anthropic",
+ model="claude-sonnet-4-6",
+ api_key="sk-ant-test",
+ messages=[
+ _msg("system", "be helpful"),
+ _msg("user", "give me a fact"),
+ ],
+ max_tokens=200,
+ temperature=0.3,
+ execution_mode="batch",
+ custom_id="passid-1:consolidate",
+ )
+
+ assert isinstance(ref, BatchSubmissionRef)
+ assert ref.provider == "anthropic"
+ assert ref.provider_batch_id == "msgbatch_abc123"
+ assert ref.custom_id == "passid-1:consolidate"
+
+ async_create.assert_awaited_once()
+ kwargs = async_create.call_args.kwargs
+ requests = kwargs["requests"]
+ assert len(requests) == 1
+ req = requests[0]
+ assert req["custom_id"] == "passid-1:consolidate"
+ params = req["params"]
+ assert params["model"] == "claude-sonnet-4-6"
+ assert params["max_tokens"] == 200
+ assert params["temperature"] == 0.3
+ # System prompt landed as cache-controlled text block.
+ assert isinstance(params["system"], list)
+ assert params["system"][0]["text"] == "be helpful"
+ assert params["system"][0]["cache_control"] == {"type": "ephemeral"}
+
+ @pytest.mark.asyncio
+ async def test_submit_includes_tool_choice_for_structured_output(self):
+ """Step 5 leans on this: pin that ``tool_choice`` and ``tools``
+ make it into the batch ``params`` so the model is constrained to
+ emit one tool_use block. Without it, the model is free to write
+ prose and the dream's JSON parser does extra work."""
+ fake_batch = SimpleNamespace(id="msgbatch_xyz")
+ async_create = AsyncMock(return_value=fake_batch)
+ fake_client = SimpleNamespace(
+ messages=SimpleNamespace(batches=SimpleNamespace(create=async_create)),
+ )
+ with patch(
+ "backend.util.llm.providers.anthropic.AsyncAnthropic",
+ return_value=fake_client,
+ ):
+ await call_provider(
+ provider="anthropic",
+ model="claude-sonnet-4-6",
+ api_key="sk-ant-test",
+ messages=[_msg("user", "hi")],
+ max_tokens=10,
+ tools=[{"name": "x", "parameters": {}}],
+ tool_choice={"type": "tool", "name": "x"},
+ execution_mode="batch",
+ custom_id="x",
+ )
+ params = async_create.call_args.kwargs["requests"][0]["params"]
+ assert params["tool_choice"] == {"type": "tool", "name": "x"}
+ assert params["tools"][0]["name"] == "x"
+
+
+class TestPollBatch:
+ @pytest.mark.asyncio
+ async def test_maps_ended_status(self):
+ fake_client = SimpleNamespace(
+ messages=SimpleNamespace(
+ batches=SimpleNamespace(
+ retrieve=AsyncMock(
+ return_value=SimpleNamespace(processing_status="ended")
+ )
+ )
+ ),
+ )
+ with patch(
+ "backend.util.llm.providers.anthropic.AsyncAnthropic",
+ return_value=fake_client,
+ ):
+ assert (
+ await poll_batch(
+ provider="anthropic",
+ provider_batch_id="msgbatch_1",
+ api_key="sk-ant-test",
+ )
+ == "ended"
+ )
+
+ @pytest.mark.asyncio
+ async def test_maps_in_progress_to_processing(self):
+ fake_client = SimpleNamespace(
+ messages=SimpleNamespace(
+ batches=SimpleNamespace(
+ retrieve=AsyncMock(
+ return_value=SimpleNamespace(processing_status="in_progress")
+ )
+ )
+ ),
+ )
+ with patch(
+ "backend.util.llm.providers.anthropic.AsyncAnthropic",
+ return_value=fake_client,
+ ):
+ assert (
+ await poll_batch(
+ provider="anthropic",
+ provider_batch_id="x",
+ api_key="sk-ant-test",
+ )
+ == "processing"
+ )
+
+ @pytest.mark.asyncio
+ async def test_unknown_status_reports_pending(self):
+ """Future-proof: if Anthropic adds a new ``processing_status``
+ value we don't recognize, we keep polling rather than failing
+ the whole pass."""
+ fake_client = SimpleNamespace(
+ messages=SimpleNamespace(
+ batches=SimpleNamespace(
+ retrieve=AsyncMock(
+ return_value=SimpleNamespace(
+ processing_status="some_future_state"
+ )
+ )
+ )
+ ),
+ )
+ with patch(
+ "backend.util.llm.providers.anthropic.AsyncAnthropic",
+ return_value=fake_client,
+ ):
+ assert (
+ await poll_batch(
+ provider="anthropic",
+ provider_batch_id="x",
+ api_key="sk-ant-test",
+ )
+ == "pending"
+ )
+
+ @pytest.mark.asyncio
+ async def test_openai_raises_not_implemented(self):
+ with pytest.raises(NotImplementedError, match="anthropic"):
+ await poll_batch(
+ provider="openai",
+ provider_batch_id="x",
+ api_key="x",
+ )
+
+
+class TestDownloadBatchResults:
+ @pytest.mark.asyncio
+ async def test_extracts_text_block_content(self):
+ """A succeeded result with a single text block flattens to the
+ text content. That's the most common dream-pass result shape
+ when tool_use isn't in play."""
+ results_iter = _fake_async_iter(
+ [
+ SimpleNamespace(
+ custom_id="passid-1:consolidate",
+ result=SimpleNamespace(
+ type="succeeded",
+ message=SimpleNamespace(
+ content=[
+ SimpleNamespace(type="text", text='{"facts": []}')
+ ],
+ usage=SimpleNamespace(
+ input_tokens=10,
+ output_tokens=20,
+ cache_read_input_tokens=3,
+ cache_creation_input_tokens=2,
+ ),
+ ),
+ ),
+ )
+ ]
+ )
+ fake_client = SimpleNamespace(
+ messages=SimpleNamespace(
+ batches=SimpleNamespace(results=AsyncMock(return_value=results_iter))
+ ),
+ )
+ with patch(
+ "backend.util.llm.providers.anthropic.AsyncAnthropic",
+ return_value=fake_client,
+ ):
+ rows = await download_batch_results(
+ provider="anthropic",
+ provider_batch_id="msgbatch_done",
+ api_key="sk-ant-test",
+ )
+ assert len(rows) == 1
+ row = rows[0]
+ assert isinstance(row, BatchResultRow)
+ assert row.custom_id == "passid-1:consolidate"
+ assert row.content == '{"facts": []}'
+ assert row.input_tokens == 10
+ assert row.output_tokens == 20
+ assert row.cache_read_tokens == 3
+ assert row.cache_creation_tokens == 2
+ assert row.error is None
+
+ @pytest.mark.asyncio
+ async def test_extracts_tool_use_input_as_json(self):
+ """Step 5 leans on this: when the dream pass uses
+ ``tool_choice={"type":"tool","name":...}`` to force structured
+ output, the result is one ``tool_use`` block whose ``input``
+ IS the structured payload. Flattening it to a JSON string is
+ what the dream parser then validates against the Pydantic
+ schema."""
+ results_iter = _fake_async_iter(
+ [
+ SimpleNamespace(
+ custom_id="passid-1:sanitize",
+ result=SimpleNamespace(
+ type="succeeded",
+ message=SimpleNamespace(
+ content=[
+ SimpleNamespace(
+ type="tool_use",
+ input={
+ "writes": [],
+ "summary_for_user": "ok",
+ },
+ )
+ ],
+ usage=SimpleNamespace(input_tokens=1, output_tokens=1),
+ ),
+ ),
+ )
+ ]
+ )
+ fake_client = SimpleNamespace(
+ messages=SimpleNamespace(
+ batches=SimpleNamespace(results=AsyncMock(return_value=results_iter))
+ ),
+ )
+ with patch(
+ "backend.util.llm.providers.anthropic.AsyncAnthropic",
+ return_value=fake_client,
+ ):
+ rows = await download_batch_results(
+ provider="anthropic",
+ provider_batch_id="x",
+ api_key="x",
+ )
+ assert rows[0].content == '{"writes": [], "summary_for_user": "ok"}'
+
+ @pytest.mark.asyncio
+ async def test_errored_row_carries_error_string_with_zero_tokens(self):
+ """Per-request errors do not fail the whole batch — they surface
+ as a row with ``error`` set and token counts at 0. The
+ BatchExecutor's dispatch handler reads this to mark the phase
+ failed in the JobStatus row."""
+ results_iter = _fake_async_iter(
+ [
+ SimpleNamespace(
+ custom_id="passid-1:recombine",
+ result=SimpleNamespace(
+ type="errored",
+ error=SimpleNamespace(message="content moderation"),
+ ),
+ )
+ ]
+ )
+ fake_client = SimpleNamespace(
+ messages=SimpleNamespace(
+ batches=SimpleNamespace(results=AsyncMock(return_value=results_iter))
+ ),
+ )
+ with patch(
+ "backend.util.llm.providers.anthropic.AsyncAnthropic",
+ return_value=fake_client,
+ ):
+ rows = await download_batch_results(
+ provider="anthropic",
+ provider_batch_id="x",
+ api_key="x",
+ )
+ assert rows[0].error is not None
+ assert "content moderation" in rows[0].error
+ assert rows[0].input_tokens == 0
+ assert rows[0].output_tokens == 0
+
+
+def _fake_async_iter(items):
+ """Build an awaitable that yields an async iterator over ``items``.
+
+ The Anthropic SDK's ``batches.results()`` returns an awaitable
+ yielding an async-iterable streamer; this helper mocks that shape
+ without dragging the real SDK into the tests.
+ """
+
+ class _Iter:
+ def __init__(self, items):
+ self._items = list(items)
+
+ def __aiter__(self):
+ return self
+
+ async def __anext__(self):
+ if not self._items:
+ raise StopAsyncIteration
+ return self._items.pop(0)
+
+ return _Iter(items)
+
+
+# ---------------------------------------------------------------------------
+# Streaming + non-streaming OpenAI-compat helpers (chat dispatch)
+# ---------------------------------------------------------------------------
+
+
+class TestCallProviderStream:
+ """Regression coverage for ``call_provider_stream``. The chat
+ baseline path delegates here; behavior changes break chat in
+ user-facing ways (tokens stop streaming, tool calls drop, etc.)."""
+
+ @pytest.mark.asyncio
+ async def test_uses_provided_client_directly(self):
+ """When a ``client`` is passed, the helper does NOT construct a
+ new one — preserves the chat layer's module-cached
+ Langfuse-wrapped client + its pooled HTTP connections."""
+ from backend.util.llm.providers import call_provider_stream
+
+ sentinel_stream = MagicMock(name="async_stream")
+ client = MagicMock()
+ client.chat.completions.create = AsyncMock(return_value=sentinel_stream)
+
+ result = await call_provider_stream(
+ client=client,
+ model="gpt-4o",
+ messages=[_msg("user", "hi")],
+ extra_body={"foo": "bar"},
+ stream_options={"include_usage": True},
+ )
+
+ assert result is sentinel_stream
+ client.chat.completions.create.assert_awaited_once()
+ kwargs = client.chat.completions.create.await_args.kwargs
+ assert kwargs["stream"] is True
+ assert kwargs["model"] == "gpt-4o"
+ assert kwargs["extra_body"] == {"foo": "bar"}
+ assert kwargs["stream_options"] == {"include_usage": True}
+
+ @pytest.mark.asyncio
+ async def test_builds_client_via_factory_when_not_provided(self):
+ """When no ``client`` is passed, the helper instantiates one
+ via ``client_factory(base_url, api_key)``. The chat layer uses
+ this branch to inject ``LangfuseAsyncOpenAI`` as the factory."""
+ from backend.util.llm.providers import call_provider_stream
+
+ captured: dict[str, object] = {}
+
+ class _StubClient:
+ def __init__(self, *, base_url: str, api_key: str):
+ captured["base_url"] = base_url
+ captured["api_key"] = api_key
+ self.chat = SimpleNamespace(completions=SimpleNamespace())
+ self.chat.completions.create = AsyncMock(return_value="stream")
+
+ result = await call_provider_stream(
+ model="claude-sonnet-4-6",
+ messages=[_msg("user", "hi")],
+ base_url="https://api.test/v1",
+ api_key="sk-test",
+ client_factory=_StubClient,
+ )
+
+ assert result == "stream"
+ assert captured == {
+ "base_url": "https://api.test/v1",
+ "api_key": "sk-test",
+ }
+
+ @pytest.mark.asyncio
+ async def test_omit_max_tokens_drops_field_from_create_call(self):
+ """OpenRouter's thinking routes inject their own ``max_tokens``
+ default and 400 if the client sends one too. The chat baseline
+ passes ``openai.omit`` to skip the field; the helper must
+ actually drop it from create_kwargs (not pass it as the omit
+ sentinel which would still register as 'present' on the dict)."""
+ import openai
+
+ from backend.util.llm.providers import call_provider_stream
+
+ client = MagicMock()
+ client.chat.completions.create = AsyncMock(return_value="s")
+ await call_provider_stream(
+ client=client,
+ model="x",
+ messages=[_msg("user", "hi")],
+ max_tokens=openai.omit,
+ )
+ kwargs = client.chat.completions.create.await_args.kwargs
+ assert "max_tokens" not in kwargs
+
+ @pytest.mark.asyncio
+ async def test_real_max_tokens_lands_in_create_kwargs(self):
+ """Direct-Anthropic mode passes an explicit max_tokens because
+ Anthropic refuses to default it when thinking is enabled. That
+ value must reach the SDK call."""
+ from backend.util.llm.providers import call_provider_stream
+
+ client = MagicMock()
+ client.chat.completions.create = AsyncMock(return_value="s")
+ await call_provider_stream(
+ client=client,
+ model="claude-opus-4-1",
+ messages=[_msg("user", "hi")],
+ max_tokens=8192,
+ )
+ kwargs = client.chat.completions.create.await_args.kwargs
+ assert kwargs["max_tokens"] == 8192
+
+ @pytest.mark.asyncio
+ async def test_raises_when_neither_client_nor_credentials(self):
+ from backend.util.llm.providers import call_provider_stream
+
+ with pytest.raises(ValueError, match="pass either"):
+ await call_provider_stream(
+ model="x",
+ messages=[_msg("user", "hi")],
+ )
+
+
+class TestCallProviderOpenAICompatSync:
+ @pytest.mark.asyncio
+ async def test_uses_provided_client_directly(self):
+ from backend.util.llm.providers import call_provider_openai_compat_sync
+
+ sentinel = MagicMock(name="response")
+ client = MagicMock()
+ client.chat.completions.create = AsyncMock(return_value=sentinel)
+
+ result = await call_provider_openai_compat_sync(
+ client=client,
+ model="claude-haiku-4-5",
+ messages=[_msg("user", "hi")],
+ max_tokens=20,
+ extra_body={"usage": {"include": True}},
+ )
+
+ assert result is sentinel
+ kwargs = client.chat.completions.create.await_args.kwargs
+ assert kwargs["model"] == "claude-haiku-4-5"
+ assert kwargs["max_tokens"] == 20
+ assert kwargs["extra_body"] == {"usage": {"include": True}}
+ assert "stream" not in kwargs
+
+ @pytest.mark.asyncio
+ async def test_raises_when_neither_client_nor_credentials(self):
+ from backend.util.llm.providers import call_provider_openai_compat_sync
+
+ with pytest.raises(ValueError, match="pass either"):
+ await call_provider_openai_compat_sync(
+ model="x",
+ messages=[_msg("user", "hi")],
+ max_tokens=20,
+ )
+
+
+class TestCancelBatch:
+ @pytest.mark.asyncio
+ async def test_anthropic_cancel_calls_sdk_and_returns_true(self):
+ from backend.util.llm.providers import cancel_batch
+
+ async_cancel = AsyncMock(return_value=SimpleNamespace(id="msgbatch_x"))
+ fake_client = SimpleNamespace(
+ messages=SimpleNamespace(batches=SimpleNamespace(cancel=async_cancel))
+ )
+ with patch(
+ "backend.util.llm.providers.anthropic.AsyncAnthropic",
+ return_value=fake_client,
+ ):
+ ok = await cancel_batch(
+ provider="anthropic",
+ provider_batch_id="msgbatch_x",
+ api_key="sk-test",
+ )
+ assert ok is True
+ async_cancel.assert_awaited_once_with("msgbatch_x")
+
+ @pytest.mark.asyncio
+ async def test_non_anthropic_provider_returns_false(self):
+ from backend.util.llm.providers import cancel_batch
+
+ ok = await cancel_batch(
+ provider="openai", provider_batch_id="b1", api_key="sk-test"
+ )
+ assert ok is False
+
+ @pytest.mark.asyncio
+ async def test_cancel_swallows_sdk_error_returns_false(self):
+ from backend.util.llm.providers import cancel_batch
+
+ async_cancel = AsyncMock(side_effect=RuntimeError("boom"))
+ fake_client = SimpleNamespace(
+ messages=SimpleNamespace(batches=SimpleNamespace(cancel=async_cancel))
+ )
+ with patch(
+ "backend.util.llm.providers.anthropic.AsyncAnthropic",
+ return_value=fake_client,
+ ):
+ ok = await cancel_batch(
+ provider="anthropic", provider_batch_id="b1", api_key="sk-test"
+ )
+ assert ok is False
diff --git a/autogpt_platform/backend/backend/util/llm/tool_use.py b/autogpt_platform/backend/backend/util/llm/tool_use.py
new file mode 100644
index 0000000000..4c2a2d605a
--- /dev/null
+++ b/autogpt_platform/backend/backend/util/llm/tool_use.py
@@ -0,0 +1,105 @@
+"""Pydantic → Anthropic tool definition conversion.
+
+Anthropic's Messages API supports forced structured output via tool
+use: provide a tool whose ``input_schema`` matches the desired output
+shape, then set ``tool_choice={"type":"tool","name":<tool_name>}``
+and the model is constrained to call exactly that tool with arguments
+matching the schema — no preamble, no markdown, no "Looking at the
+inputs, I need to..." prose. The model literally cannot emit anything
+else.
+
+This module turns any Pydantic ``BaseModel`` subclass into the tool
+definition Anthropic expects + provides the forced ``tool_choice``
+helper.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def pydantic_to_anthropic_tool(
+ response_model: type[BaseModel],
+ *,
+ tool_name: str,
+ description: str,
+) -> dict[str, Any]:
+ """Convert a Pydantic model class to an Anthropic tool definition.
+
+ Anthropic accepts a tool spec of shape
+ ``{"name": str, "description": str, "input_schema": dict}`` where
+ ``input_schema`` is a JSON Schema describing the call's arguments.
+ ``BaseModel.model_json_schema()`` returns a compatible JSON Schema
+ with one quirk: nested models are emitted as ``$ref`` pointers into
+ a ``$defs`` table. Anthropic's parser accepts ``$ref``/``$defs``
+ forms in current API versions, but inlined schemas are more
+ predictable across SDK versions — we inline them defensively.
+
+ The returned dict is safe to pass straight into
+ ``client.messages.create(tools=[<this>])`` or to include in a
+ ``BatchRequest``'s params.
+ """
+ schema = response_model.model_json_schema()
+ inlined = _inline_refs(schema)
+ # Drop fields Anthropic doesn't use (title, $defs after inlining).
+ inlined.pop("$defs", None)
+ inlined.pop("title", None)
+ return {
+ "name": tool_name,
+ "description": description,
+ "input_schema": inlined,
+ }
+
+
+def force_tool_choice(tool_name: str) -> dict[str, Any]:
+ """Build a ``tool_choice`` that forces Claude to call exactly this tool.
+
+ With ``disable_parallel_tool_use=True`` the model emits exactly
+ one tool_use block — no preamble, no parallel calls. This is what
+ eliminates the JSON-parse failures we saw on the sanitize phase
+ (where the model would emit chain-of-thought prose before the
+ JSON and break our balanced-brace extractor).
+ """
+ return {
+ "type": "tool",
+ "name": tool_name,
+ "disable_parallel_tool_use": True,
+ }
+
+
+# ---------------------------------------------------------------------------
+# $ref inlining
+# ---------------------------------------------------------------------------
+
+
+def _inline_refs(schema: dict[str, Any]) -> dict[str, Any]:
+ """Resolve all ``$ref`` indirections against ``$defs`` and inline them.
+
+ Pydantic emits ``{"$ref": "#/$defs/Foo"}`` for nested models. This
+ walks the schema, replaces each ``$ref`` with the referenced
+ definition, and returns a fully inlined copy. Mutually recursive
+ schemas would loop forever; the dream-pass schemas don't have
+ that shape (validated by tests).
+ """
+ defs = schema.get("$defs", {})
+ return _resolve(schema, defs)
+
+
+def _resolve(node: Any, defs: dict[str, Any]) -> Any:
+ if isinstance(node, dict):
+ if "$ref" in node and isinstance(node["$ref"], str):
+ ref = node["$ref"]
+ if ref.startswith("#/$defs/"):
+ key = ref.split("/")[-1]
+ target = defs.get(key)
+ if target is not None:
+ # Resolve nested refs in the target before returning.
+ return _resolve(target, defs)
+ # Unknown ref form — leave as-is rather than fabricate.
+ return node
+ return {k: _resolve(v, defs) for k, v in node.items()}
+ if isinstance(node, list):
+ return [_resolve(item, defs) for item in node]
+ return node
diff --git a/autogpt_platform/backend/backend/util/llm/tool_use_test.py b/autogpt_platform/backend/backend/util/llm/tool_use_test.py
new file mode 100644
index 0000000000..36d2288eb3
--- /dev/null
+++ b/autogpt_platform/backend/backend/util/llm/tool_use_test.py
@@ -0,0 +1,119 @@
+"""Tests for ``util.llm.tool_use``."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from backend.util.llm.tool_use import (
+ _inline_refs,
+ force_tool_choice,
+ pydantic_to_anthropic_tool,
+)
+
+
+class _Demotion(BaseModel):
+ edge_uuid: str
+ reason: str
+ new_status: Literal["superseded", "contradicted"] = "superseded"
+
+
+class _Operations(BaseModel):
+ writes: list[str] = Field(default_factory=list)
+ demotions: list[_Demotion] = Field(default_factory=list)
+ summary_for_user: str = ""
+
+
+class TestPydanticToAnthropicTool:
+ def test_returns_name_description_and_input_schema(self):
+ tool = pydantic_to_anthropic_tool(
+ _Operations,
+ tool_name="submit_dream_ops",
+ description="Submit the dream pass operations.",
+ )
+ assert tool["name"] == "submit_dream_ops"
+ assert tool["description"] == "Submit the dream pass operations."
+ assert "input_schema" in tool
+ assert tool["input_schema"]["type"] == "object"
+
+ def test_input_schema_includes_required_top_level_properties(self):
+ """If we lose `writes`/`demotions`/`summary_for_user` from the
+ schema, Anthropic will accept any shape and our parser breaks."""
+ tool = pydantic_to_anthropic_tool(_Operations, tool_name="x", description="x")
+ props = tool["input_schema"]["properties"]
+ assert "writes" in props
+ assert "demotions" in props
+ assert "summary_for_user" in props
+
+ def test_inlines_nested_model_refs(self):
+ """The whole point of the helper: nested model `_Demotion` must
+ be inlined into the demotions array's items schema, not left as
+ a `$ref` pointing into a removed `$defs` table."""
+ tool = pydantic_to_anthropic_tool(_Operations, tool_name="x", description="x")
+ demotions_items = tool["input_schema"]["properties"]["demotions"]["items"]
+ # After inlining we should see the concrete _Demotion shape, not a $ref
+ assert "$ref" not in demotions_items
+ assert demotions_items["type"] == "object"
+ assert "edge_uuid" in demotions_items["properties"]
+
+ def test_strips_defs_block_after_inlining(self):
+ tool = pydantic_to_anthropic_tool(_Operations, tool_name="x", description="x")
+ assert "$defs" not in tool["input_schema"]
+
+ def test_strips_title_after_inlining(self):
+ """Title pollutes the schema and Anthropic ignores it; drop it."""
+ tool = pydantic_to_anthropic_tool(_Operations, tool_name="x", description="x")
+ assert "title" not in tool["input_schema"]
+
+
+class TestForceToolChoice:
+ def test_returns_anthropic_forced_choice_shape(self):
+ choice = force_tool_choice("submit_dream_ops")
+ assert choice["type"] == "tool"
+ assert choice["name"] == "submit_dream_ops"
+
+ def test_disables_parallel_tool_use(self):
+ """The whole reason we use forced tool_choice is to get exactly
+ one tool_use block with no preamble. Parallel calls would
+ re-introduce the multi-block output we're trying to eliminate."""
+ choice = force_tool_choice("any_name")
+ assert choice["disable_parallel_tool_use"] is True
+
+
+class TestInlineRefs:
+ def test_passes_through_schema_without_refs(self):
+ schema = {"type": "object", "properties": {"a": {"type": "string"}}}
+ assert _inline_refs(schema) == schema
+
+ def test_inlines_single_ref(self):
+ schema = {
+ "type": "object",
+ "properties": {"foo": {"$ref": "#/$defs/Foo"}},
+ "$defs": {"Foo": {"type": "string", "minLength": 1}},
+ }
+ result = _inline_refs(schema)
+ assert result["properties"]["foo"] == {"type": "string", "minLength": 1}
+
+ def test_inlines_nested_refs_in_arrays(self):
+ schema = {
+ "type": "object",
+ "properties": {
+ "items": {"type": "array", "items": {"$ref": "#/$defs/Item"}}
+ },
+ "$defs": {
+ "Item": {"type": "object", "properties": {"x": {"type": "integer"}}}
+ },
+ }
+ result = _inline_refs(schema)
+ assert result["properties"]["items"]["items"]["type"] == "object"
+ assert (
+ result["properties"]["items"]["items"]["properties"]["x"]["type"]
+ == "integer"
+ )
+
+ def test_leaves_unknown_ref_form_alone(self):
+ """A ref to an external schema (not #/$defs/...) shouldn't crash;
+ we leave it as-is and let Anthropic decide."""
+ schema = {"$ref": "http://example.com/schemas/foo"}
+ assert _inline_refs(schema) == schema
diff --git a/autogpt_platform/backend/backend/util/settings.py b/autogpt_platform/backend/backend/util/settings.py
index b6fdfb5691..fca2d3c3fd 100644
--- a/autogpt_platform/backend/backend/util/settings.py
+++ b/autogpt_platform/backend/backend/util/settings.py
@@ -312,6 +312,14 @@ class Config(UpdateTrackingModel["Config"], BaseSettings):
"service daemon to run on",
)
+ batch_executor_port: int = Field(
+ default=8011,
+ description="The port for the BatchExecutor subprocess to run on. "
+ "The service has no inbound RPC surface today — callers interact via "
+ "the Redis-backed pending queue — but AppService requires every "
+ "subprocess to expose /health_check on a port for supervision.",
+ )
+
otto_api_url: str = Field(
default="",
description="The URL for the Otto API service",
diff --git a/autogpt_platform/frontend/package.json b/autogpt_platform/frontend/package.json
index a80ab9a9e4..ea025b0fce 100644
--- a/autogpt_platform/frontend/package.json
+++ b/autogpt_platform/frontend/package.json
@@ -107,6 +107,7 @@
"react-currency-input-field": "4.0.3",
"react-day-picker": "9.11.1",
"react-dom": "18.3.1",
+ "react-force-graph-2d": "1.29.1",
"react-hook-form": "7.66.0",
"react-icons": "5.5.0",
"react-markdown": "9.0.3",
diff --git a/autogpt_platform/frontend/pnpm-lock.yaml b/autogpt_platform/frontend/pnpm-lock.yaml
index cd4399eba8..1374f300fc 100644
--- a/autogpt_platform/frontend/pnpm-lock.yaml
+++ b/autogpt_platform/frontend/pnpm-lock.yaml
@@ -237,6 +237,9 @@ importers:
react-dom:
specifier: 18.3.1
version: 18.3.1([email protected])
+ react-force-graph-2d:
+ specifier: 1.29.1
+ version: 1.29.1([email protected])
react-hook-form:
specifier: 7.66.0
version: 7.66.0([email protected])
@@ -3531,6 +3534,9 @@ packages:
peerDependencies:
'@testing-library/dom': '>=7.21.4'
+ '@tweenjs/[email protected]':
+ resolution: {integrity: sha512-XKLA6syeBUaPzx4j3qwMqzzq+V4uo72BnlbOjmuljLrRqdsd3qnzvZZoxvMHZ23ndsRS4aufU6JOZYpCbU6T1A==}
+
resolution: {integrity: sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg==}
@@ -4143,6 +4149,10 @@ packages:
resolution: {integrity: sha512-PYAthTa2m2VKxuvSD3DPC/Gy+U+sOA1LAuT8mkmRuvw+NACSaeXEQ+NHcVF7rONl6qcaxV3Uuemwawk+7+SJLw==}
engines: {node: '>= 0.6'}
+ resolution: {integrity: sha512-rkAofCwe/FvYFUlMB0v0gWmhqtfAtV1IUkdPbfhTUyYniu5LrC0A0UJkTH0Jv3S8SvwkmfuAlY+mQIJATdocMA==}
+ engines: {node: '>=12'}
+
resolution: {integrity: sha512-n02Vykv5uA3eHGM/Z2dQrcD56kL8TyDb2p1+0P83PClMnC/nc+anbQRhIOWnSq4Ke/KvDPrY3C9hDtC/A3eHnQ==}
peerDependencies:
@@ -4428,6 +4438,9 @@ packages:
resolution: {integrity: sha512-aVNobHnJqLiUelTaHat9DZ1qM2w0C0Eym4LPI/3JxOnSokGVdsl1T1kN7TFvsEAD8G47A6VKQ0TVHqbBnYMJlQ==}
engines: {node: '>=12.0.0'}
+ resolution: {integrity: sha512-PA0FW9ZpcHbojUCMu28z9Vg/fNkwTj5YhusSAjHHDfHDGLxJ6YUKrAN2vk1fP2MMOxVw4Oko16FMlRGVBGqLKg==}
+
resolution: {integrity: sha512-RKshQI1R3YQ+n9YJz2QQ147P66ELpa1FQEg20Dk8oW9t2KgLbpDLLp9aGZ7y8WHSshDknG0bknqGw5/tyCs5tw==}
@@ -4529,6 +4542,10 @@ packages:
resolution: {integrity: sha512-PxZwGNvH7Ak8WX5iXzoK1KPZttBXNPuaOvI2ZYU7NrlM+d9Ov+TUvlLOBNGzVXAntMSMMlJPd+jY6ovrVjSmUw==}
+ resolution: {integrity: sha512-ryQkDX26yJ3CXzb3hxUVNlg1NKE4REc5crLBq661Nxzr8TNd236SaEf2ffYLXyI5tSABSeguHLqcVq4vf9L3Zg==}
+ engines: {node: '>=12'}
+
resolution: {integrity: sha512-yxQbJkAVrFXWNbTUjPqjF7G+g6pDotOUHGbkZq2NELZUMDpiJ85rIEazVb8GTaAptNW2miJAXbs1BtioA251Pw==}
@@ -4852,6 +4869,9 @@ packages:
resolution: {integrity: sha512-IH5tgjV4jE/GhHkRV0HiVYPDtvfjHQlQfJHs0usq7M30XcSBvOotpmH1IgkcXsO/5gEQZD43B//fc7SRT5S+xw==}
engines: {node: '>=12'}
+ resolution: {integrity: sha512-cElUNH+sHu95L04m92pG73t2MEJXKu+GeKUN1TJkFsu93E5W8E9Sc3kHEGJKgenGvj19m6upSn2EunvMgMD2Yw==}
+
resolution: {integrity: sha512-ALnjWlVYkXsVIGlOsuWH1+3udkYFI48Ljihfnh8FZPF2QS9o+PzGLBslO0PjzVoHLZ2KCVgAM8NVkXPJB2aNnQ==}
engines: {node: '>=12'}
@@ -4893,6 +4913,10 @@ packages:
resolution: {integrity: sha512-kpkQIM20n3oLVBKGg6oHrUchHM3xODkTzjMoj7aWQFq5QEM+R6E4WkzT5+tojDY7yjez8KgCBRoj4aEr99Fdqw==}
engines: {node: '>=12'}
+ resolution: {integrity: sha512-4tsKHUPLOVkyfEffZo1v6sFHvGFwAIIjt/W8IThbp08DYAsXZck+2pSHEG5W1+gQgEvFLdZkYvmJAbRM2EzMnA==}
+ engines: {node: '>=12'}
+
resolution: {integrity: sha512-zxV/SsA+U4yte8051P4ECydjD/S+qeYtnaIyAs9tgHCqfguma/aAQDjo85A9Z6EKhBirHRJHXIgJUlffT4wdLg==}
engines: {node: '>=12'}
@@ -4913,6 +4937,9 @@ packages:
resolution: {integrity: sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==}
engines: {node: '>=12'}
+ resolution: {integrity: sha512-F8gPlqpP+HwRPMO/8uOu5wjH110+6q4cgJvgJT6vlpy3BEaDIKlTZrgHKZSp/i1InRpVfh4puY/kvL6MxK930A==}
+
resolution: {integrity: sha512-VLaYcn81dtHVTjEHd8B+pbe9yHWpXKZUC87PzoFmsFrJqgFwDe/qxfp5MlfsfM1V5E/iVt0MmEbWQ7FVIXh/bg==}
@@ -5608,10 +5635,18 @@ packages:
resolution: {integrity: sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg==}
+ resolution: {integrity: sha512-/kXzuDnnBqyyWyhDMH7+PfP8J/oXiAavGzcRxASOMRHFuReDtofizLLJsf7nnDLAfEaMW4pVWaXrAjtnglpEkg==}
+ engines: {node: '>=12'}
+
resolution: {integrity: sha512-dKx12eRCVIzqCxFGplyFKJMPvLEWgmNtUrpTiJIR5u97zEhRG8ySrtboPHZXx7daLxQVrl643cTzbab2tkQjxg==}
engines: {node: '>= 0.4'}
+ resolution: {integrity: sha512-TdJ2KbkoiDQ7NIRx8IPGD0mAXXpLhamS7c+b7W98b0MHG7lphnda1VOQX/98UDTsttIAdH4TcP0l0MauSnLK8w==}
+ engines: {node: '>=12'}
+
resolution: {integrity: sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==}
engines: {node: '>=14'}
@@ -6025,6 +6060,10 @@ packages:
resolution: {integrity: sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==}
engines: {node: '>=8'}
+ resolution: {integrity: sha512-SP23P27OUKzXWEC/TOyWlwLviofQkCSCKONnc62eItjp69yCZZPqDQtr3Pw5gJDnPeUMqExmKydNZaJO0FU9pw==}
+ engines: {node: '>=12'}
+
resolution: {integrity: sha512-hAEKNxvHf2Iq3H60oMBHkB4wl5jn3TPF3+fXek/sRwAB5gP9xWs4r7aweSF95f99HFoz69pnZTcu8f0SIHV18w==}
@@ -6244,6 +6283,10 @@ packages:
resolution: {integrity: sha512-yr+mElb6dWxA1mzFu0+26njV5DWAQRNTi5pB6fFMm79zHrfAs3d0qjhe/IpZI4AHIUJkzvu5QXQRWOw2O0GQyw==}
+ resolution: {integrity: sha512-YKnxXEekXKzhpf7CLYA0A+oDP8V0OhICNCr5lv96FvSsDEmrb0GKM776JgQvHTMjr7DTTPEVv/1Ciaw0uEWzBA==}
+ engines: {node: '>=12'}
+
resolution: {integrity: sha512-7vuh85V5cdDofPyxn58nrPjBktZo0u9x1g8WtjQol+jZDaE+fhN+cIvTj11GndBnMnyfrUOG1sZQxCdjKh+DKg==}
engines: {node: '>= 10.13.0'}
@@ -6368,6 +6411,10 @@ packages:
resolution: {integrity: sha512-ZNOIIGMzqCGcHQEA2Q4rIQQ3Df6gSIfne+X9Rly9Bc2y55KxAZu8iGv+n2pP0bLf0XAOctJZgeloC54hWzCahQ==}
engines: {node: '>=16'}
+ resolution: {integrity: sha512-4+5mNNf4vZDSwPhKprKwz3330iisPrb08JyMgbsdFrimBCKNHecua/WBwvVg3n7vwx0C1ARjfhwIpbrbd9n5wg==}
+ engines: {node: '>=12'}
+
resolution: {integrity: sha512-woHRUZ/iF23GBP1dkDQMh1QBad9dmr8/PAwNA54VrSOVYgI12MAcE14TqnDdQOdzyEonGzMepYnqBMYdsoAr8Q==}
hasBin: true
@@ -7599,6 +7646,12 @@ packages:
peerDependencies:
react: ^18.3.1
+ resolution: {integrity: sha512-1Rl/1Z3xy2iTHKj6a0jRXGyiI86xUti81K+jBQZ+Oe46csaMikp47L5AjrzA9hY9fNGD63X8ffrqnvaORukCuQ==}
+ engines: {node: '>=12'}
+ peerDependencies:
+ react: '*'
+
resolution: {integrity: sha512-xXBqsWGKrY46ZqaHDo+ZUYiMUgi8suYu5kdrS20EG8KiL7VRQitEbNjm+UcrDYrNi1YLyfpmAeGjCZYXLT9YBw==}
engines: {node: '>=18.0.0'}
@@ -7619,6 +7672,12 @@ packages:
resolution: {integrity: sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==}
+ resolution: {integrity: sha512-kifAF4ZPD77qZKc4CKLmozq6GY1sBzPEJTIJb0wWFK6HsePJatK3jXplZn2eeAt3x67CDozgi7/rO8fNQ/AL7A==}
+ engines: {node: '>=12'}
+ peerDependencies:
+ react: '>=16.13.1'
+
resolution: {integrity: sha512-fBASbA6LnOU9dOU2eW7aQ8xmYBSXUIWr+UmF9b1efZBazGNO+rcXT/icdKnYm2pTwcRylVUYwW7H1PHfLekVzA==}
@@ -8397,6 +8456,9 @@ packages:
resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==}
+ resolution: {integrity: sha512-XPaBkWQJdsf3pLKJV9p4qN/S+fm2Oj8AIPo1BTUhg5oxkvm9+SVEGFdhyOz7tTdUTfvxMiAs4sp6/eZO2Ew+pw==}
+
resolution: {integrity: sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg==}
engines: {node: '>=18'}
@@ -12552,6 +12614,8 @@ snapshots:
dependencies:
'@testing-library/dom': 10.4.1
+ '@tweenjs/[email protected]': {}
+
dependencies:
tslib: 2.8.1
@@ -13218,6 +13282,8 @@ snapshots:
mime-types: 2.1.35
negotiator: 0.6.3
+
dependencies:
acorn: 8.15.0
@@ -13515,6 +13581,8 @@ snapshots:
dependencies:
open: 8.4.2
+
dependencies:
require-from-string: 2.0.2
@@ -13640,6 +13708,10 @@ snapshots:
+ dependencies:
+ tinycolor2: 1.6.0
+
@@ -13959,6 +14031,8 @@ snapshots:
+
dependencies:
d3-dispatch: 3.0.1
@@ -14000,6 +14074,14 @@ snapshots:
dependencies:
d3-dsv: 3.0.1
+ dependencies:
+ d3-binarytree: 1.0.2
+ d3-dispatch: 3.0.1
+ d3-octree: 1.1.0
+ d3-quadtree: 3.0.1
+ d3-timer: 3.0.1
+
dependencies:
d3-dispatch: 3.0.1
@@ -14018,6 +14100,8 @@ snapshots:
dependencies:
d3-color: 3.1.0
+
@@ -14919,10 +15003,34 @@ snapshots:
+ dependencies:
+ d3-selection: 3.0.0
+ kapsule: 1.16.3
+ preact: 10.28.2
+
dependencies:
is-callable: 1.2.7
+ dependencies:
+ '@tweenjs/tween.js': 25.0.0
+ accessor-fn: 1.5.3
+ bezier-js: 6.1.4
+ canvas-color-tracker: 1.3.2
+ d3-array: 3.2.4
+ d3-drag: 3.0.0
+ d3-force-3d: 3.0.6
+ d3-scale: 4.0.2
+ d3-scale-chromatic: 3.1.0
+ d3-selection: 3.0.0
+ d3-zoom: 3.0.0
+ float-tooltip: 1.7.5
+ index-array-by: 1.4.2
+ kapsule: 1.16.3
+ lodash-es: 4.17.23
+
dependencies:
cross-spawn: 7.0.6
@@ -15447,6 +15555,8 @@ snapshots:
+
@@ -15666,6 +15776,8 @@ snapshots:
+
dependencies:
'@types/node': 24.10.0
@@ -15794,6 +15906,10 @@ snapshots:
make-dir: 3.1.0
xmlbuilder: 15.1.1
+ dependencies:
+ lodash-es: 4.17.23
+
dependencies:
commander: 8.3.0
@@ -17314,6 +17430,13 @@ snapshots:
react: 18.3.1
scheduler: 0.23.2
+ dependencies:
+ force-graph: 1.51.4
+ prop-types: 15.8.1
+ react: 18.3.1
+ react-kapsule: 2.5.7([email protected])
+
dependencies:
react: 18.3.1
@@ -17328,6 +17451,11 @@ snapshots:
+ dependencies:
+ jerrypick: 1.1.2
+ react: 18.3.1
+
@@ -18343,6 +18471,8 @@ snapshots:
+
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/layout.tsx b/autogpt_platform/frontend/src/app/(platform)/admin/layout.tsx
index 4a458e0ef5..70d3fd7e4f 100644
--- a/autogpt_platform/frontend/src/app/(platform)/admin/layout.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/layout.tsx
@@ -8,6 +8,7 @@ import {
FileText,
Heartbeat,
CalculatorIcon,
+ Brain,
RobotIcon,
} from "@phosphor-icons/react/dist/ssr";
@@ -61,6 +62,11 @@ const sidebarLinkGroups = [
href: "/admin/block-cost-estimates",
icon: <CalculatorIcon className="h-6 w-6" />,
},
+ {
+ text: "Memory Inspector",
+ href: "/admin/memory",
+ icon: <Brain className="h-6 w-6" />,
+ },
{
text: "Admin User Management",
href: "/admin/settings",
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/memory/__tests__/memory-visualizer.test.tsx b/autogpt_platform/frontend/src/app/(platform)/admin/memory/__tests__/memory-visualizer.test.tsx
new file mode 100644
index 0000000000..5d23d46097
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/memory/__tests__/memory-visualizer.test.tsx
@@ -0,0 +1,208 @@
+import { describe, expect, test, vi } from "vitest";
+import userEvent from "@testing-library/user-event";
+import { http, HttpResponse } from "msw";
+
+import { render, screen, waitFor } from "@/tests/integrations/test-utils";
+import { server } from "@/mocks/mock-server";
+import {
+ getGetV2GetCommunityRebuildStatusMockHandler200,
+ getGetV2GetCommunityRebuildStatusResponseMock200,
+ getGetV2GetDreamPassStatusMockHandler200,
+ getGetV2GetDreamPassStatusResponseMock200,
+ getGetV2GetGraphMockHandler200,
+ getGetV2GetGraphResponseMock200,
+ getGetV2GetMemoryOverviewMockHandler200,
+ getGetV2GetMemoryOverviewResponseMock200,
+ getPostV2RebuildCommunitiesMockHandler202,
+ getPostV2RebuildCommunitiesResponseMock202,
+ getPostV2TriggerDreamPassMockHandler202,
+ getPostV2TriggerDreamPassResponseMock202,
+} from "@/app/api/__generated__/endpoints/admin/admin.msw";
+
+// react-force-graph-2d uses HTMLCanvas + window APIs and pulls in d3 at
+// import time. In the jsdom test env neither exists, so swap it for a
+// trivial stub so MemoryVisualizer's tree is renderable.
+vi.mock("react-force-graph-2d", () => ({
+ default: () => null,
+}));
+
+import { MemoryVisualizer } from "../components/MemoryVisualizer";
+
+function setupBaseHandlers() {
+ server.use(
+ getGetV2GetMemoryOverviewMockHandler200({
+ ...getGetV2GetMemoryOverviewResponseMock200(),
+ user_id: "u-1",
+ group_id: "g-1",
+ entities: 12,
+ episodes: 30,
+ relates_to_edges: 25,
+ mentions_edges: 30,
+ communities: 0,
+ }),
+ getGetV2GetGraphMockHandler200({
+ ...getGetV2GetGraphResponseMock200(),
+ user_id: "u-1",
+ group_id: "g-1",
+ nodes: [],
+ edges: [],
+ truncated: false,
+ }),
+ );
+}
+
+describe("MemoryVisualizer — 202 + polling contract", () => {
+ test("renders rebuild and dream buttons + the overview chip", async () => {
+ setupBaseHandlers();
+ render(<MemoryVisualizer />);
+
+ await screen.findByRole("button", { name: /rebuild communities/i });
+ await screen.findByRole("button", { name: /dream pass/i });
+ // Overview chip is rendered as two adjacent elements ("12" + "Entities"),
+ // so assert each label individually.
+ await screen.findByText("12");
+ await screen.findByText(/^Entities$/i);
+ });
+
+ test("clicking 'Rebuild communities' → 202 + polled status flips button label", async () => {
+ setupBaseHandlers();
+ server.use(
+ getPostV2RebuildCommunitiesMockHandler202({
+ ...getPostV2RebuildCommunitiesResponseMock202(),
+ job_id: "job-rebuild-1",
+ state: "queued",
+ }),
+ getGetV2GetCommunityRebuildStatusMockHandler200({
+ ...getGetV2GetCommunityRebuildStatusResponseMock200(),
+ job_id: "job-rebuild-1",
+ kind: "rebuild",
+ state: "running",
+ current_phase: "rebuild",
+ }),
+ );
+ render(<MemoryVisualizer />);
+ const btn = await screen.findByRole("button", {
+ name: /rebuild communities/i,
+ });
+ await userEvent.click(btn);
+
+ // After the 202 lands, the active job id is set and the poll
+ // sees state=running with current_phase=rebuild → label morphs.
+ // findByRole throws if the morphed label never appears, so this
+ // genuinely fails on a broken poll loop.
+ await screen.findByRole("button", { name: /rebuild…/i });
+ });
+
+ test("clicking 'Dream pass' → 202 + polled status shows phase in label", async () => {
+ setupBaseHandlers();
+ server.use(
+ getPostV2TriggerDreamPassMockHandler202({
+ ...getPostV2TriggerDreamPassResponseMock202(),
+ job_id: "job-dream-1",
+ state: "queued",
+ }),
+ getGetV2GetDreamPassStatusMockHandler200({
+ ...getGetV2GetDreamPassStatusResponseMock200(),
+ job_id: "job-dream-1",
+ kind: "dream_pass",
+ state: "submitted",
+ current_phase: "consolidate",
+ }),
+ );
+ render(<MemoryVisualizer />);
+ const btn = await screen.findByRole("button", { name: /dream pass/i });
+ await userEvent.click(btn);
+
+ await screen.findByRole("button", {
+ name: /batch submitted \(consolidate\)/i,
+ });
+ });
+
+ test("status-endpoint 500 stops polling + reactivates the dream button", async () => {
+ setupBaseHandlers();
+ server.use(
+ getPostV2TriggerDreamPassMockHandler202({
+ ...getPostV2TriggerDreamPassResponseMock202(),
+ job_id: "job-dream-err",
+ state: "queued",
+ }),
+ // Status endpoint flakes — the poll loop must stop and the
+ // button must come back, not spin forever.
+ http.get("*/api/admin/memory/:userId/dream/:jobId", () =>
+ HttpResponse.json({ error: "boom" }, { status: 500 }),
+ ),
+ );
+ render(<MemoryVisualizer />);
+ const btn = await screen.findByRole("button", { name: /dream pass/i });
+ await userEvent.click(btn);
+
+ // The trigger button reactivates to its idle label after the
+ // status endpoint fails — proves the active job id was cleared.
+ await waitFor(
+ async () => {
+ const idle = await screen.findByRole("button", { name: /dream pass/i });
+ // The label morphs to "Dreaming…" briefly while we're between
+ // the POST and the error; check exact-match to the idle text.
+ expect(idle.textContent?.trim()).toBe("Dream pass");
+ },
+ { timeout: 5_000 },
+ );
+ });
+
+ test(
+ "status poll failing AFTER a successful poll still reactivates the dream button",
+ { timeout: 20_000 },
+ async () => {
+ setupBaseHandlers();
+ let statusCalls = 0;
+ server.use(
+ getPostV2TriggerDreamPassMockHandler202({
+ ...getPostV2TriggerDreamPassResponseMock202(),
+ job_id: "job-dream-stale",
+ state: "queued",
+ }),
+ // First poll succeeds (running), every later poll 500s. React
+ // Query keeps the stale running status while flipping the query
+ // into error state — the terminal handler must treat the error
+ // as terminal even though stale data exists, or the button is
+ // stuck on "Dreaming…" forever with polling stopped.
+ http.get("*/api/admin/memory/:userId/dream/:jobId", () => {
+ statusCalls += 1;
+ if (statusCalls === 1) {
+ return HttpResponse.json({
+ ...getGetV2GetDreamPassStatusResponseMock200(),
+ job_id: "job-dream-stale",
+ kind: "dream_pass",
+ state: "running",
+ current_phase: "consolidate",
+ });
+ }
+ return HttpResponse.json({ error: "boom" }, { status: 500 });
+ }),
+ );
+ render(<MemoryVisualizer />);
+ const btn = await screen.findByRole("button", { name: /dream pass/i });
+ await userEvent.click(btn);
+
+ // First poll lands → phase-aware label proves status data is cached.
+ await screen.findByRole(
+ "button",
+ { name: /consolidate…/i },
+ { timeout: 5_000 },
+ );
+
+ // Second poll (one POLL_INTERVAL_MS later) errors → active job id
+ // must clear and the idle label must come back.
+ await waitFor(
+ async () => {
+ const idle = await screen.findByRole("button", {
+ name: /dream pass/i,
+ });
+ expect(idle.textContent?.trim()).toBe("Dream pass");
+ },
+ { timeout: 10_000 },
+ );
+ expect(statusCalls).toBeGreaterThanOrEqual(2);
+ },
+ );
+});
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/DreamOperationsView.tsx b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/DreamOperationsView.tsx
new file mode 100644
index 0000000000..cd7eb63cd2
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/DreamOperationsView.tsx
@@ -0,0 +1,170 @@
+"use client";
+
+import type { DreamOperationsSnapshot } from "@/app/api/__generated__/models/dreamOperationsSnapshot";
+import {
+ Accordion,
+ AccordionContent,
+ AccordionItem,
+ AccordionTrigger,
+} from "@/components/molecules/Accordion/Accordion";
+import { Text } from "@/components/atoms/Text/Text";
+import {
+ FilePlusIcon,
+ LightbulbIcon,
+ TrashIcon,
+ WarningIcon,
+} from "@phosphor-icons/react";
+import { DreamWriteRow } from "./components/DreamWriteRow";
+import { DreamDemotionRow } from "./components/DreamDemotionRow";
+import { DreamEntityInvalidationRow } from "./components/DreamEntityInvalidationRow";
+import { sectionCounts } from "./helpers";
+
+interface Props {
+ operations: DreamOperationsSnapshot | null | undefined;
+}
+
+export function DreamOperationsView({ operations }: Props) {
+ if (!operations) {
+ return (
+ <div
+ className="rounded-md border border-dashed bg-white p-4 text-center text-sm text-gray-500"
+ data-testid="dream-operations-empty"
+ >
+ No per-edge operations were returned for this dream pass.
+ </div>
+ );
+ }
+
+ const counts = sectionCounts(operations);
+ const writes = operations.writes ?? [];
+ const proposals = operations.proposals ?? [];
+ const demotions = operations.demotions ?? [];
+ const entityInvalidations = operations.entity_invalidations ?? [];
+
+ return (
+ <div
+ className="rounded-md border bg-white p-3"
+ data-testid="dream-operations-view"
+ >
+ <Text variant="small-medium" className="mb-2 uppercase text-gray-500">
+ Operations
+ </Text>
+ <Accordion
+ type="multiple"
+ defaultValue={["writes", "proposals", "demotions", "entities"]}
+ >
+ <AccordionItem value="writes">
+ <AccordionTrigger>
+ <SectionLabel
+ icon={<FilePlusIcon size={14} weight="bold" />}
+ label="Writes"
+ count={counts.writes}
+ />
+ </AccordionTrigger>
+ <AccordionContent>
+ {writes.length === 0 ? (
+ <EmptyRow text="No writes recorded." />
+ ) : (
+ <ul className="space-y-1.5">
+ {writes.map((w, i) => (
+ <DreamWriteRow
+ key={(w.edge_uuid ?? "w") + i.toString()}
+ item={w}
+ />
+ ))}
+ </ul>
+ )}
+ </AccordionContent>
+ </AccordionItem>
+
+ <AccordionItem value="proposals">
+ <AccordionTrigger>
+ <SectionLabel
+ icon={<LightbulbIcon size={14} weight="bold" />}
+ label="Proposals"
+ count={counts.proposals}
+ />
+ </AccordionTrigger>
+ <AccordionContent>
+ {proposals.length === 0 ? (
+ <EmptyRow text="No proposals recorded." />
+ ) : (
+ <ul className="space-y-1.5">
+ {proposals.map((p, i) => (
+ <DreamWriteRow
+ key={(p.edge_uuid ?? "p") + i.toString()}
+ item={p}
+ />
+ ))}
+ </ul>
+ )}
+ </AccordionContent>
+ </AccordionItem>
+
+ <AccordionItem value="demotions">
+ <AccordionTrigger>
+ <SectionLabel
+ icon={<TrashIcon size={14} weight="bold" />}
+ label="Demotions"
+ count={counts.demotions}
+ />
+ </AccordionTrigger>
+ <AccordionContent>
+ {demotions.length === 0 ? (
+ <EmptyRow text="No demotions recorded." />
+ ) : (
+ <ul className="space-y-1.5">
+ {demotions.map((d) => (
+ <DreamDemotionRow key={d.edge_uuid} item={d} />
+ ))}
+ </ul>
+ )}
+ </AccordionContent>
+ </AccordionItem>
+
+ <AccordionItem value="entities">
+ <AccordionTrigger>
+ <SectionLabel
+ icon={<WarningIcon size={14} weight="bold" />}
+ label="Entity invalidations"
+ count={counts.entities}
+ />
+ </AccordionTrigger>
+ <AccordionContent>
+ {entityInvalidations.length === 0 ? (
+ <EmptyRow text="No entity invalidations recorded." />
+ ) : (
+ <ul className="space-y-1.5">
+ {entityInvalidations.map((e) => (
+ <DreamEntityInvalidationRow key={e.entity_uuid} item={e} />
+ ))}
+ </ul>
+ )}
+ </AccordionContent>
+ </AccordionItem>
+ </Accordion>
+ </div>
+ );
+}
+
+interface SectionLabelProps {
+ icon: React.ReactNode;
+ label: string;
+ count: number;
+}
+
+function SectionLabel({ icon, label, count }: SectionLabelProps) {
+ return (
+ <span className="inline-flex items-center gap-2 text-sm font-medium text-gray-800">
+ {icon}
+ {label}
+ <span className="rounded bg-gray-100 px-1.5 py-0.5 text-xs font-normal text-gray-600">
+ {count}
+ </span>
+ </span>
+ );
+}
+
+function EmptyRow({ text }: { text: string }) {
+ return <div className="px-1 py-2 text-xs text-gray-500">{text}</div>;
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/__tests__/dream-operations-view.test.tsx b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/__tests__/dream-operations-view.test.tsx
new file mode 100644
index 0000000000..731d2df64e
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/__tests__/dream-operations-view.test.tsx
@@ -0,0 +1,118 @@
+import { describe, expect, test } from "vitest";
+
+import { render, screen } from "@/tests/integrations/test-utils";
+import type { DreamOperationsSnapshot } from "@/app/api/__generated__/models/dreamOperationsSnapshot";
+
+import { DreamOperationsView } from "../DreamOperationsView";
+
+function sampleSnapshot(): DreamOperationsSnapshot {
+ return {
+ writes: [
+ {
+ edge_uuid: "edge-write-aaaaaaaaaaaaaaaaaa",
+ content: "User prefers terse code reviews.",
+ scope: "preferences",
+ confidence: 0.92,
+ status: "active",
+ source_episode_uuids: ["epi-1", "epi-2"],
+ },
+ ],
+ proposals: [
+ {
+ edge_uuid: null,
+ content: "User is exploring memory consolidation work.",
+ scope: "interests",
+ confidence: 0.6,
+ status: "tentative",
+ source_episode_uuids: ["epi-3"],
+ },
+ {
+ edge_uuid: "edge-prop-bbbbbbbbbbbbbbbbbb",
+ content: "Possibly working at AutoGPT.",
+ confidence: null,
+ status: "tentative",
+ },
+ ],
+ demotions: [
+ {
+ edge_uuid: "edge-demo-ccccccccccccccccc",
+ reason: "Contradicted by newer episode",
+ new_status: "superseded",
+ applied: true,
+ },
+ ],
+ entity_invalidations: [
+ {
+ entity_uuid: "ent-ddddddddddddddddddd",
+ reason: "Merged with another entity",
+ edges_touched: [
+ "edge-x-111",
+ "edge-x-222",
+ "edge-x-333",
+ "edge-x-444",
+ "edge-x-555",
+ "edge-x-666",
+ "edge-x-777",
+ ],
+ },
+ ],
+ };
+}
+
+describe("DreamOperationsView", () => {
+ test("renders all four sections with their item counts", async () => {
+ render(<DreamOperationsView operations={sampleSnapshot()} />);
+
+ expect(await screen.findByText(/writes/i)).toBeDefined();
+ expect(await screen.findByText(/proposals/i)).toBeDefined();
+ expect(await screen.findByText(/demotions/i)).toBeDefined();
+ expect(await screen.findByText(/entity invalidations/i)).toBeDefined();
+
+ // Each section's count badge is shown next to the label.
+ // writes: 1, proposals: 2, demotions: 1, entities: 1.
+ expect(screen.getAllByText("1").length).toBeGreaterThanOrEqual(3);
+ expect(screen.getByText("2")).toBeDefined();
+ });
+
+ test("renders sample row content + shortened edge UUIDs", async () => {
+ render(<DreamOperationsView operations={sampleSnapshot()} />);
+
+ expect(
+ await screen.findByText("User prefers terse code reviews."),
+ ).toBeDefined();
+ expect(
+ await screen.findByText("Contradicted by newer episode"),
+ ).toBeDefined();
+ expect(await screen.findByText("Merged with another entity")).toBeDefined();
+
+ // Edge UUID is shown shortened with the `edge:` prefix.
+ expect(screen.getByText((c) => c.includes("edge-write-"))).toBeDefined();
+
+ // Confidence rendered as percentage.
+ expect(screen.getByText(/confidence: 92%/i)).toBeDefined();
+ });
+
+ test("shows skeleton/empty state when operations is null", async () => {
+ render(<DreamOperationsView operations={null} />);
+ expect(
+ await screen.findByText(/no per-edge operations were returned/i),
+ ).toBeDefined();
+ });
+
+ test("shows per-section empty rows when an array is empty", async () => {
+ render(
+ <DreamOperationsView
+ operations={{
+ writes: [],
+ proposals: [],
+ demotions: [],
+ entity_invalidations: [],
+ }}
+ />,
+ );
+ expect(await screen.findByText(/no writes recorded/i)).toBeDefined();
+ expect(screen.getByText(/no proposals recorded/i)).toBeDefined();
+ expect(screen.getByText(/no demotions recorded/i)).toBeDefined();
+ expect(screen.getByText(/no entity invalidations recorded/i)).toBeDefined();
+ });
+});
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/components/DreamDemotionRow.tsx b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/components/DreamDemotionRow.tsx
new file mode 100644
index 0000000000..ea81ccaec3
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/components/DreamDemotionRow.tsx
@@ -0,0 +1,35 @@
+import type { DemotionSummary } from "@/app/api/__generated__/models/demotionSummary";
+import { Badge } from "@/components/atoms/Badge/Badge";
+import { Text } from "@/components/atoms/Text/Text";
+import { shortenUuid } from "../helpers";
+
+interface Props {
+ item: DemotionSummary;
+}
+
+export function DreamDemotionRow({ item }: Props) {
+ return (
+ <li className="border-l-2 border-amber-200 py-1.5 pl-3">
+ <div className="flex items-start justify-between gap-2">
+ <Text variant="small-medium" className="break-words">
+ {item.reason}
+ </Text>
+ <Badge
+ variant={item.applied ? "success" : "info"}
+ size="small"
+ className="whitespace-nowrap"
+ >
+ {item.new_status}
+ </Badge>
+ </div>
+ <div className="mt-1 flex flex-wrap items-center gap-2 text-gray-500">
+ <code className="font-mono text-[10px]">
+ edge: {shortenUuid(item.edge_uuid)}
+ </code>
+ <Text variant="small" className="text-gray-500" as="span">
+ {item.applied ? "applied" : "not applied"}
+ </Text>
+ </div>
+ </li>
+ );
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/components/DreamEntityInvalidationRow.tsx b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/components/DreamEntityInvalidationRow.tsx
new file mode 100644
index 0000000000..3bac77be67
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/components/DreamEntityInvalidationRow.tsx
@@ -0,0 +1,43 @@
+import type { EntityInvalidationSummary } from "@/app/api/__generated__/models/entityInvalidationSummary";
+import { Text } from "@/components/atoms/Text/Text";
+import { shortenUuid } from "../helpers";
+
+interface Props {
+ item: EntityInvalidationSummary;
+}
+
+export function DreamEntityInvalidationRow({ item }: Props) {
+ const touched = item.edges_touched ?? [];
+ return (
+ <li className="border-l-2 border-rose-200 py-1.5 pl-3">
+ <Text variant="small-medium" className="break-words">
+ {item.reason}
+ </Text>
+ <div className="mt-1 flex flex-wrap items-center gap-2 text-gray-500">
+ <code className="font-mono text-[10px]">
+ entity: {shortenUuid(item.entity_uuid)}
+ </code>
+ <Text variant="small" className="text-gray-500" as="span">
+ {touched.length} edge{touched.length === 1 ? "" : "s"} touched
+ </Text>
+ </div>
+ {touched.length > 0 ? (
+ <div className="mt-1 flex flex-wrap gap-1">
+ {touched.slice(0, 6).map((u) => (
+ <code
+ key={u}
+ className="rounded bg-gray-50 px-1.5 py-0.5 font-mono text-[10px] text-gray-600"
+ >
+ {shortenUuid(u)}
+ </code>
+ ))}
+ {touched.length > 6 ? (
+ <Text variant="small" className="text-gray-500" as="span">
+ +{touched.length - 6} more
+ </Text>
+ ) : null}
+ </div>
+ ) : null}
+ </li>
+ );
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/components/DreamWriteRow.tsx b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/components/DreamWriteRow.tsx
new file mode 100644
index 0000000000..473ed8894e
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/components/DreamWriteRow.tsx
@@ -0,0 +1,43 @@
+import type { WriteSummary } from "@/app/api/__generated__/models/writeSummary";
+import { Badge } from "@/components/atoms/Badge/Badge";
+import { Text } from "@/components/atoms/Text/Text";
+import { formatConfidence, shortenUuid } from "../helpers";
+
+interface Props {
+ item: WriteSummary;
+}
+
+export function DreamWriteRow({ item }: Props) {
+ return (
+ <li className="border-l-2 border-violet-200 py-1.5 pl-3">
+ <div className="flex items-start justify-between gap-2">
+ <Text variant="small-medium" className="break-words">
+ {item.content}
+ </Text>
+ {item.status ? (
+ <Badge variant="info" size="small">
+ {item.status}
+ </Badge>
+ ) : null}
+ </div>
+ <div className="mt-1 flex flex-wrap items-center gap-2 text-gray-500">
+ <code className="font-mono text-[10px]">
+ edge: {shortenUuid(item.edge_uuid)}
+ </code>
+ {item.scope ? (
+ <Text variant="small" className="text-gray-500" as="span">
+ scope: {item.scope}
+ </Text>
+ ) : null}
+ <Text variant="small" className="text-gray-500" as="span">
+ confidence: {formatConfidence(item.confidence)}
+ </Text>
+ {item.source_episode_uuids && item.source_episode_uuids.length > 0 ? (
+ <Text variant="small" className="text-gray-500" as="span">
+ sources: {item.source_episode_uuids.length}
+ </Text>
+ ) : null}
+ </div>
+ </li>
+ );
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/helpers.ts b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/helpers.ts
new file mode 100644
index 0000000000..aa6fd06dd1
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamOperationsView/helpers.ts
@@ -0,0 +1,24 @@
+import type { DreamOperationsSnapshot } from "@/app/api/__generated__/models/dreamOperationsSnapshot";
+
+export function shortenUuid(uuid: string | null | undefined): string {
+ if (!uuid) return "—";
+ if (uuid.length <= 12) return uuid;
+ return `${uuid.slice(0, 12)}…`;
+}
+
+export function formatConfidence(c: number | null | undefined): string {
+ if (c === null || c === undefined) return "—";
+ return `${(c * 100).toFixed(0)}%`;
+}
+
+export function sectionCounts(ops: DreamOperationsSnapshot | null | undefined) {
+ if (!ops) {
+ return { writes: 0, proposals: 0, demotions: 0, entities: 0 };
+ }
+ return {
+ writes: ops.writes?.length ?? 0,
+ proposals: ops.proposals?.length ?? 0,
+ demotions: ops.demotions?.length ?? 0,
+ entities: ops.entity_invalidations?.length ?? 0,
+ };
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamUsageSummary/DreamUsageSummary.tsx b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamUsageSummary/DreamUsageSummary.tsx
new file mode 100644
index 0000000000..38bd1a9fde
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamUsageSummary/DreamUsageSummary.tsx
@@ -0,0 +1,128 @@
+"use client";
+
+import type { DreamPassUsage } from "@/app/api/__generated__/models/dreamPassUsage";
+import { Text } from "@/components/atoms/Text/Text";
+import { Badge } from "@/components/atoms/Badge/Badge";
+import { CoinsIcon } from "@phosphor-icons/react";
+import { formatCost, formatTokens } from "./helpers";
+
+interface Props {
+ usage: DreamPassUsage | null | undefined;
+}
+
+export function DreamUsageSummary({ usage }: Props) {
+ if (!usage) {
+ return (
+ <div
+ className="rounded-md border border-dashed bg-white p-4 text-center text-sm text-gray-500"
+ data-testid="dream-usage-empty"
+ >
+ No token usage was recorded for this dream pass.
+ </div>
+ );
+ }
+
+ const phases = usage.phases ?? [];
+ const discount = usage.discount_applied ?? 0;
+
+ return (
+ <div
+ className="rounded-md border bg-white p-3"
+ data-testid="dream-usage-summary"
+ >
+ <div className="mb-2 flex flex-wrap items-center justify-between gap-2">
+ <Text variant="small-medium" className="uppercase text-gray-500">
+ Token usage
+ </Text>
+ <div className="inline-flex items-center gap-2">
+ <CoinsIcon size={14} className="text-gray-500" />
+ <Text variant="small-medium" as="span">
+ total: {formatCost(usage.total_cost_usd)}
+ </Text>
+ {discount > 0 ? (
+ <Badge variant="success" size="small">
+ discount {(discount * 100).toFixed(0)}%
+ </Badge>
+ ) : null}
+ </div>
+ </div>
+
+ <div className="overflow-x-auto">
+ <table className="w-full text-left text-xs">
+ <thead className="text-gray-500">
+ <tr>
+ <th className="px-2 py-1 font-medium">Phase</th>
+ <th className="px-2 py-1 font-medium">Model</th>
+ <th className="px-2 py-1 text-right font-medium">In</th>
+ <th className="px-2 py-1 text-right font-medium">Out</th>
+ <th className="px-2 py-1 text-right font-medium">Cache R</th>
+ <th className="px-2 py-1 text-right font-medium">Cache W</th>
+ <th className="px-2 py-1 text-right font-medium">Cost</th>
+ </tr>
+ </thead>
+ <tbody>
+ {phases.length === 0 ? (
+ <tr>
+ <td
+ colSpan={7}
+ className="px-2 py-2 text-center italic text-gray-500"
+ >
+ No per-phase data recorded.
+ </td>
+ </tr>
+ ) : (
+ phases.map((p, i) => (
+ <tr
+ key={`${p.phase}-${i}`}
+ className="border-t border-gray-100"
+ >
+ <td className="px-2 py-1 font-medium text-gray-800">
+ {p.phase}
+ </td>
+ <td className="px-2 py-1 font-mono text-[10px] text-gray-600">
+ {p.model}
+ </td>
+ <td className="px-2 py-1 text-right tabular-nums">
+ {formatTokens(p.input_tokens)}
+ </td>
+ <td className="px-2 py-1 text-right tabular-nums">
+ {formatTokens(p.output_tokens)}
+ </td>
+ <td className="px-2 py-1 text-right tabular-nums">
+ {formatTokens(p.cache_read_tokens)}
+ </td>
+ <td className="px-2 py-1 text-right tabular-nums">
+ {formatTokens(p.cache_creation_tokens)}
+ </td>
+ <td className="px-2 py-1 text-right tabular-nums">
+ {formatCost(p.cost_usd)}
+ </td>
+ </tr>
+ ))
+ )}
+ <tr className="border-t-2 border-gray-200 bg-gray-50 font-medium">
+ <td className="px-2 py-1" colSpan={2}>
+ Totals
+ </td>
+ <td className="px-2 py-1 text-right tabular-nums">
+ {formatTokens(usage.total_input_tokens)}
+ </td>
+ <td className="px-2 py-1 text-right tabular-nums">
+ {formatTokens(usage.total_output_tokens)}
+ </td>
+ <td className="px-2 py-1 text-right tabular-nums">
+ {formatTokens(usage.total_cache_read_tokens)}
+ </td>
+ <td className="px-2 py-1 text-right tabular-nums">
+ {formatTokens(usage.total_cache_creation_tokens)}
+ </td>
+ <td className="px-2 py-1 text-right tabular-nums">
+ {formatCost(usage.total_cost_usd)}
+ </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div>
+ );
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamUsageSummary/helpers.ts b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamUsageSummary/helpers.ts
new file mode 100644
index 0000000000..3d537e359c
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/DreamUsageSummary/helpers.ts
@@ -0,0 +1,11 @@
+export function formatTokens(n: number | null | undefined): string {
+ if (n === null || n === undefined) return "—";
+ return n.toLocaleString();
+}
+
+export function formatCost(usd: number | null | undefined): string {
+ if (usd === null || usd === undefined) return "—";
+ if (usd === 0) return "$0.00";
+ if (usd < 0.01) return `$${usd.toFixed(4)}`;
+ return `$${usd.toFixed(2)}`;
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/GraphCanvas.tsx b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/GraphCanvas.tsx
new file mode 100644
index 0000000000..60dde27649
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/GraphCanvas.tsx
@@ -0,0 +1,211 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import dynamic from "next/dynamic";
+import type { GraphNode } from "@/app/api/__generated__/models/graphNode";
+import type { GraphEdge } from "@/app/api/__generated__/models/graphEdge";
+
+// react-force-graph-2d uses HTMLCanvas + window APIs at import time, so it
+// can't run during Next's server rendering pass.
+const ForceGraph2D = dynamic(() => import("react-force-graph-2d"), {
+ ssr: false,
+ loading: () => (
+ <div className="flex h-full items-center justify-center text-sm text-gray-500">
+ Loading graph engine…
+ </div>
+ ),
+});
+
+// Color palette per node "type" (custom-typed entities) / "label" fallback.
+// Mirrors the FalkorDB-browser palette in spirit — distinct, saturated,
+// readable on white.
+const TYPE_COLORS: Record<string, string> = {
+ Person: "#7dd3fc", // sky-300
+ Organization: "#86efac", // green-300
+ Project: "#fde68a", // amber-200
+ Concept: "#fca5a5", // red-300
+ Preference: "#c4b5fd", // violet-300
+ Rule: "#bef264", // lime-300
+ Episodic: "#fdba74", // orange-300
+ Community: "#93c5fd", // blue-300
+ Entity: "#f0abfc", // fuchsia-300 — default for un-typed entities
+};
+
+const EDGE_COLORS: Record<string, string> = {
+ RELATES_TO: "#a855f7", // purple-500
+ MENTIONS: "#6366f1", // indigo-500
+ HAS_MEMBER: "#ec4899", // pink-500
+};
+
+export interface GraphCanvasProps {
+ nodes: GraphNode[];
+ edges: GraphEdge[];
+ hiddenNodeTypes: Set<string>;
+ hiddenEdgeTypes: Set<string>;
+ selectedUuid: string | null;
+ onSelect: (uuid: string | null) => void;
+}
+
+type CanvasNode = GraphNode & {
+ // Position fields written back by d3-force; declared here so TS is happy.
+ x?: number;
+ y?: number;
+ fx?: number;
+ fy?: number;
+};
+
+type CanvasLink = {
+ source: string | CanvasNode;
+ target: string | CanvasNode;
+ uuid: string;
+ label: string;
+ name?: string | null;
+};
+
+// force-graph hands tooltip labels to float-tooltip, which injects them
+// via innerHTML. Node/edge names are LLM-extracted from conversation
+// content (which can carry attacker-controlled material), so everything
+// that reaches a label accessor must be HTML-escaped first.
+export function escapeHtml(value: string): string {
+ return value
+ .replace(/&/g, "&amp;")
+ .replace(/</g, "&lt;")
+ .replace(/>/g, "&gt;")
+ .replace(/"/g, "&quot;")
+ .replace(/'/g, "&#39;");
+}
+
+export function getNodeTooltipLabel(n: GraphNode): string {
+ return escapeHtml(`${n.type ?? n.label}: ${n.name ?? n.uuid.slice(0, 8)}`);
+}
+
+export function getLinkTooltipLabel(l: CanvasLink): string {
+ return escapeHtml(l.name ? `${l.label}: ${l.name}` : l.label);
+}
+
+// d3-force replaces link ``source``/``target`` string ids with node
+// object references once the simulation initializes, so both shapes
+// must be handled when matching a link against the selected node.
+export function linkTouchesNode(
+ l: CanvasLink,
+ selectedUuid: string | null,
+): boolean {
+ if (!selectedUuid) return false;
+ const sourceId = typeof l.source === "object" ? l.source.uuid : l.source;
+ const targetId = typeof l.target === "object" ? l.target.uuid : l.target;
+ return sourceId === selectedUuid || targetId === selectedUuid;
+}
+
+export function GraphCanvas({
+ nodes,
+ edges,
+ hiddenNodeTypes,
+ hiddenEdgeTypes,
+ selectedUuid,
+ onSelect,
+}: GraphCanvasProps) {
+ const fgRef = useRef<unknown>(null);
+ const wrapperRef = useRef<HTMLDivElement>(null);
+ const [size, setSize] = useState({ width: 800, height: 600 });
+
+ // Track wrapper size so the canvas fills its container.
+ useEffect(() => {
+ if (!wrapperRef.current) return;
+ const el = wrapperRef.current;
+ const ro = new ResizeObserver((entries) => {
+ for (const entry of entries) {
+ const { width, height } = entry.contentRect;
+ setSize({ width: Math.floor(width), height: Math.floor(height) });
+ }
+ });
+ ro.observe(el);
+ return () => ro.disconnect();
+ }, []);
+
+ const data = useMemo(() => {
+ function classify(n: GraphNode): string {
+ return n.type ?? n.label;
+ }
+ const visibleNodes = nodes.filter((n) => !hiddenNodeTypes.has(classify(n)));
+ const visibleNodeIds = new Set(visibleNodes.map((n) => n.uuid));
+ const visibleEdges = edges
+ .filter((e) => !hiddenEdgeTypes.has(e.label))
+ .filter(
+ (e) => visibleNodeIds.has(e.source) && visibleNodeIds.has(e.target),
+ )
+ .map((e) => ({
+ source: e.source,
+ target: e.target,
+ uuid: e.uuid,
+ label: e.label,
+ name: e.name,
+ }));
+ return {
+ nodes: visibleNodes as CanvasNode[],
+ links: visibleEdges as CanvasLink[],
+ };
+ }, [nodes, edges, hiddenNodeTypes, hiddenEdgeTypes]);
+
+ return (
+ <div ref={wrapperRef} className="h-[70vh] w-full">
+ {/* react-force-graph-2d's generic types collapse to a loose
+ `{ [k: string]: any }` shape when reached through Next's dynamic
+ import, so the accessor callbacks are cast to `never` and narrowed
+ inside. Same pattern as `graphData={data as never}`. */}
+ <ForceGraph2D
+ ref={fgRef as never}
+ width={size.width}
+ height={size.height}
+ graphData={data as never}
+ nodeId="uuid"
+ nodeLabel={getNodeTooltipLabel as never}
+ nodeRelSize={4}
+ nodeVal={
+ ((n: CanvasNode) => (n.uuid === selectedUuid ? 6 : 3)) as never
+ }
+ nodeColor={
+ ((n: CanvasNode) =>
+ TYPE_COLORS[n.type ?? n.label] ?? TYPE_COLORS.Entity) as never
+ }
+ nodeCanvasObject={
+ ((n: CanvasNode, ctx: CanvasRenderingContext2D, scale: number) => {
+ const r = (n.uuid === selectedUuid ? 6 : 3) * 0.8;
+ const color = TYPE_COLORS[n.type ?? n.label] ?? TYPE_COLORS.Entity;
+ ctx.beginPath();
+ ctx.arc(n.x ?? 0, n.y ?? 0, r, 0, 2 * Math.PI);
+ ctx.fillStyle = color;
+ ctx.fill();
+ if (n.uuid === selectedUuid) {
+ ctx.lineWidth = 1.5 / scale;
+ ctx.strokeStyle = "#111827";
+ ctx.stroke();
+ }
+ if (scale > 1.6 && n.name) {
+ const label =
+ n.name.length > 28 ? `${n.name.slice(0, 27)}…` : n.name;
+ ctx.font = `${10 / scale}px sans-serif`;
+ ctx.fillStyle = "#111827";
+ ctx.textAlign = "center";
+ ctx.textBaseline = "top";
+ ctx.fillText(label, n.x ?? 0, (n.y ?? 0) + r + 1.5 / scale);
+ }
+ }) as never
+ }
+ linkColor={
+ ((l: CanvasLink) => EDGE_COLORS[l.label] ?? "#94a3b8") as never
+ }
+ linkLabel={getLinkTooltipLabel as never}
+ linkWidth={
+ ((l: CanvasLink) =>
+ linkTouchesNode(l, selectedUuid) ? 2 : 0.6) as never
+ }
+ linkDirectionalArrowLength={3}
+ linkDirectionalArrowRelPos={0.95}
+ onNodeClick={((n: CanvasNode) => onSelect(n.uuid)) as never}
+ onBackgroundClick={() => onSelect(null)}
+ cooldownTicks={120}
+ d3VelocityDecay={0.3}
+ />
+ </div>
+ );
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/MemoryVisualizer.tsx b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/MemoryVisualizer.tsx
new file mode 100644
index 0000000000..b2db19c362
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/MemoryVisualizer.tsx
@@ -0,0 +1,592 @@
+"use client";
+
+import { useMemo, useState } from "react";
+import type { CommunityRebuildJobStatus } from "@/app/api/__generated__/models/communityRebuildJobStatus";
+import type { DreamJobStatus } from "@/app/api/__generated__/models/dreamJobStatus";
+import type { NightlyJobStatus } from "@/app/api/__generated__/models/nightlyJobStatus";
+import { GraphCanvas } from "./GraphCanvas";
+import { useMemoryVisualizer } from "./useMemoryVisualizer";
+import { DreamOperationsView } from "./DreamOperationsView/DreamOperationsView";
+import { DreamUsageSummary } from "./DreamUsageSummary/DreamUsageSummary";
+
+// Polling envelope shared across all three job kinds — see the matching
+// alias in useMemoryVisualizer.ts. Narrowed to a specific kind at the
+// view layer that reads ``status.result``.
+type AnyJobStatus =
+ | DreamJobStatus
+ | NightlyJobStatus
+ | CommunityRebuildJobStatus;
+
+export function MemoryVisualizer() {
+ const {
+ overview,
+ overviewData,
+ graph,
+ graphData,
+ triggerRebuild,
+ triggerDream,
+ ratification,
+ triggerRatification,
+ triggerNightly,
+ force,
+ setForce,
+ includeEpisodes,
+ setIncludeEpisodes,
+ includeCommunities,
+ setIncludeCommunities,
+ dreamStatusData,
+ nightlyStatusData,
+ rebuildStatusData,
+ activeDreamJobId,
+ activeNightlyJobId,
+ activeRebuildJobId,
+ } = useMemoryVisualizer();
+
+ // Per-label / per-relationship visibility toggles. Selected via a Set
+ // of "hidden" entries — empty set = show everything.
+ const [hiddenNodeTypes, setHiddenNodeTypes] = useState<Set<string>>(
+ new Set(),
+ );
+ const [hiddenEdgeTypes, setHiddenEdgeTypes] = useState<Set<string>>(
+ new Set(),
+ );
+ const [selectedUuid, setSelectedUuid] = useState<string | null>(null);
+
+ const nodes = graphData?.nodes ?? [];
+ const edges = graphData?.edges ?? [];
+ const truncated = graphData?.truncated ?? false;
+
+ // Aggregate label / relationship counts for the sidebar pills.
+ const { nodeTypeCounts, edgeTypeCounts } = useMemo(() => {
+ const ntc = new Map<string, number>();
+ const etc = new Map<string, number>();
+ for (const n of nodes) {
+ const k = n.type ?? n.label;
+ ntc.set(k, (ntc.get(k) ?? 0) + 1);
+ }
+ for (const e of edges) {
+ etc.set(e.label, (etc.get(e.label) ?? 0) + 1);
+ }
+ return { nodeTypeCounts: ntc, edgeTypeCounts: etc };
+ }, [nodes, edges]);
+
+ const selectedNode = useMemo(
+ () => (selectedUuid ? nodes.find((n) => n.uuid === selectedUuid) : null),
+ [selectedUuid, nodes],
+ );
+ const selectedNeighbors = useMemo(() => {
+ if (!selectedUuid)
+ return [] as { edge: (typeof edges)[number]; otherUuid: string }[];
+ const result: { edge: (typeof edges)[number]; otherUuid: string }[] = [];
+ for (const e of edges) {
+ if (e.source === selectedUuid)
+ result.push({ edge: e, otherUuid: e.target });
+ else if (e.target === selectedUuid)
+ result.push({ edge: e, otherUuid: e.source });
+ }
+ return result;
+ }, [selectedUuid, edges]);
+
+ return (
+ <div className="space-y-4">
+ <OverviewStrip
+ loading={overview.isLoading}
+ error={overview.error}
+ data={overviewData}
+ />
+
+ <ControlBar
+ onRebuild={triggerRebuild}
+ rebuildActiveJobId={activeRebuildJobId}
+ rebuildStatus={rebuildStatusData}
+ onDream={triggerDream}
+ dreamActiveJobId={activeDreamJobId}
+ dreamStatus={dreamStatusData}
+ onRatification={triggerRatification}
+ ratificationPending={ratification.isPending}
+ onNightly={triggerNightly}
+ nightlyActiveJobId={activeNightlyJobId}
+ nightlyStatus={nightlyStatusData}
+ force={force}
+ setForce={setForce}
+ includeEpisodes={includeEpisodes}
+ setIncludeEpisodes={setIncludeEpisodes}
+ includeCommunities={includeCommunities}
+ setIncludeCommunities={setIncludeCommunities}
+ truncated={truncated}
+ nodeCount={nodes.length}
+ edgeCount={edges.length}
+ />
+
+ <DreamResultPanel status={dreamStatusData} />
+
+ <div className="grid grid-cols-12 gap-4">
+ <Sidebar
+ nodeTypeCounts={nodeTypeCounts}
+ edgeTypeCounts={edgeTypeCounts}
+ hiddenNodeTypes={hiddenNodeTypes}
+ setHiddenNodeTypes={setHiddenNodeTypes}
+ hiddenEdgeTypes={hiddenEdgeTypes}
+ setHiddenEdgeTypes={setHiddenEdgeTypes}
+ />
+ <div className="col-span-12 rounded-md border bg-white md:col-span-7">
+ {graph.isLoading ? (
+ <div className="flex h-[70vh] items-center justify-center text-sm text-gray-500">
+ Loading graph…
+ </div>
+ ) : graph.error ? (
+ <div className="p-6 text-sm text-red-700">
+ Failed to load graph: {String(graph.error)}
+ </div>
+ ) : nodes.length === 0 ? (
+ <div className="flex h-[70vh] flex-col items-center justify-center text-sm text-gray-500">
+ No memory yet. Start a chat session to populate it.
+ </div>
+ ) : (
+ <GraphCanvas
+ nodes={nodes}
+ edges={edges}
+ hiddenNodeTypes={hiddenNodeTypes}
+ hiddenEdgeTypes={hiddenEdgeTypes}
+ selectedUuid={selectedUuid}
+ onSelect={setSelectedUuid}
+ />
+ )}
+ </div>
+ <DetailPanel
+ node={selectedNode ?? null}
+ neighbors={selectedNeighbors}
+ onClear={() => setSelectedUuid(null)}
+ />
+ </div>
+ </div>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Sub-components
+// ---------------------------------------------------------------------------
+
+interface OverviewStripProps {
+ loading: boolean;
+ error: unknown;
+ data:
+ | {
+ entities: number;
+ episodes: number;
+ relates_to_edges: number;
+ mentions_edges: number;
+ communities: number;
+ }
+ | undefined;
+}
+
+function OverviewStrip({ loading, error, data }: OverviewStripProps) {
+ if (loading) {
+ return (
+ <div className="rounded-md border bg-white p-3 text-sm text-gray-500">
+ Loading overview…
+ </div>
+ );
+ }
+ if (error) {
+ return (
+ <div className="rounded-md border border-red-200 bg-red-50 p-3 text-sm text-red-700">
+ Failed to load overview: {String(error)}
+ </div>
+ );
+ }
+ if (!data) return null;
+ return (
+ <div className="grid grid-cols-2 gap-2 md:grid-cols-5">
+ {[
+ { label: "Entities", value: data.entities },
+ { label: "Episodes", value: data.episodes },
+ { label: "Facts", value: data.relates_to_edges },
+ { label: "Mentions", value: data.mentions_edges },
+ { label: "Communities", value: data.communities },
+ ].map((stat) => (
+ <div
+ key={stat.label}
+ className="rounded-md border bg-white p-3 text-center"
+ >
+ <div className="text-xl font-bold">{stat.value}</div>
+ <div className="text-xs uppercase tracking-wide text-gray-500">
+ {stat.label}
+ </div>
+ </div>
+ ))}
+ </div>
+ );
+}
+
+interface ControlBarProps {
+ onRebuild: () => void;
+ rebuildActiveJobId: string | undefined;
+ rebuildStatus: AnyJobStatus | undefined;
+ onDream: () => void;
+ dreamActiveJobId: string | undefined;
+ dreamStatus: AnyJobStatus | undefined;
+ onRatification: () => void;
+ ratificationPending: boolean;
+ onNightly: () => void;
+ nightlyActiveJobId: string | undefined;
+ nightlyStatus: AnyJobStatus | undefined;
+ force: boolean;
+ setForce: (v: boolean) => void;
+ includeEpisodes: boolean;
+ setIncludeEpisodes: (v: boolean) => void;
+ includeCommunities: boolean;
+ setIncludeCommunities: (v: boolean) => void;
+ truncated: boolean;
+ nodeCount: number;
+ edgeCount: number;
+}
+
+function ControlBar({
+ onRebuild,
+ rebuildActiveJobId,
+ rebuildStatus,
+ onDream,
+ dreamActiveJobId,
+ dreamStatus,
+ onRatification,
+ ratificationPending,
+ onNightly,
+ nightlyActiveJobId,
+ nightlyStatus,
+ force,
+ setForce,
+ includeEpisodes,
+ setIncludeEpisodes,
+ includeCommunities,
+ setIncludeCommunities,
+ truncated,
+ nodeCount,
+ edgeCount,
+}: ControlBarProps) {
+ const rebuildActive = !!rebuildActiveJobId;
+ const dreamActive = !!dreamActiveJobId;
+ const nightlyActive = !!nightlyActiveJobId;
+ return (
+ <div className="flex flex-wrap items-center gap-3 rounded-md border bg-white p-3 text-sm">
+ <button
+ type="button"
+ onClick={onRebuild}
+ disabled={rebuildActive}
+ className="rounded-md bg-blue-600 px-3 py-1.5 text-sm font-medium text-white hover:bg-blue-700 disabled:opacity-50"
+ >
+ {rebuildActive
+ ? jobButtonLabel(rebuildStatus, "Rebuilding…")
+ : "Rebuild communities"}
+ </button>
+ <label className="flex items-center gap-2 text-gray-700">
+ <input
+ type="checkbox"
+ checked={force}
+ onChange={(e) => setForce(e.target.checked)}
+ />
+ Force
+ </label>
+ <span className="mx-2 h-5 border-l border-gray-200" />
+ <button
+ type="button"
+ onClick={onDream}
+ disabled={dreamActive}
+ className="rounded-md bg-purple-600 px-3 py-1.5 text-sm font-medium text-white hover:bg-purple-700 disabled:opacity-50"
+ title="Run ONLY the dream pass (consolidate → recombine → sanitize) — skips community rebuild and ratification."
+ >
+ {dreamActive ? jobButtonLabel(dreamStatus, "Dreaming…") : "Dream pass"}
+ </button>
+ <button
+ type="button"
+ onClick={onRatification}
+ disabled={ratificationPending}
+ className="rounded-md bg-teal-600 px-3 py-1.5 text-sm font-medium text-white hover:bg-teal-700 disabled:opacity-50"
+ title="Run ONLY the ratification supersession sweep — promotes hit tentatives, supersedes unratified ones past their grace period."
+ >
+ {ratificationPending ? "Ratifying…" : "Ratification"}
+ </button>
+ <button
+ type="button"
+ onClick={onNightly}
+ disabled={nightlyActive}
+ className="rounded-md bg-indigo-700 px-3 py-1.5 text-sm font-medium text-white hover:bg-indigo-800 disabled:opacity-50"
+ title="Run the FULL nightly batch — what the 03:00 cron does. Fans out dream pass + ratification sweep (+ future P2/P3/P4/P11 stages) in one pass."
+ >
+ {nightlyActive
+ ? jobButtonLabel(nightlyStatus, "Running nightly…")
+ : "Nightly batch"}
+ </button>
+ <span className="mx-2 h-5 border-l border-gray-200" />
+ <label className="flex items-center gap-2 text-gray-700">
+ <input
+ type="checkbox"
+ checked={includeCommunities}
+ onChange={(e) => setIncludeCommunities(e.target.checked)}
+ />
+ Communities
+ </label>
+ <label className="flex items-center gap-2 text-gray-700">
+ <input
+ type="checkbox"
+ checked={includeEpisodes}
+ onChange={(e) => setIncludeEpisodes(e.target.checked)}
+ />
+ Episodes (noisy)
+ </label>
+ <span className="ml-auto text-xs text-gray-500">
+ {nodeCount} nodes · {edgeCount} edges
+ {truncated && (
+ <span className="ml-2 rounded bg-amber-100 px-2 py-0.5 text-amber-800">
+ truncated
+ </span>
+ )}
+ {rebuildActive && rebuildStatus && (
+ <span className="ml-2">
+ rebuild: {jobStateSummary(rebuildStatus)}
+ </span>
+ )}
+ {dreamActive && dreamStatus && (
+ <span className="ml-2">dream: {jobStateSummary(dreamStatus)}</span>
+ )}
+ {nightlyActive && nightlyStatus && (
+ <span className="ml-2">
+ nightly: {jobStateSummary(nightlyStatus)}
+ </span>
+ )}
+ </span>
+ </div>
+ );
+}
+
+function jobButtonLabel(
+ status: AnyJobStatus | undefined,
+ fallback: string,
+): string {
+ if (!status) return fallback;
+ if (status.state === "submitted") {
+ return status.current_phase
+ ? `Batch submitted (${status.current_phase})…`
+ : "Batch submitted…";
+ }
+ if (status.current_phase) {
+ return `${capitalize(status.current_phase)}…`;
+ }
+ return fallback;
+}
+
+function jobStateSummary(status: AnyJobStatus): string {
+ if (status.state === "running" && status.current_phase) {
+ return `${status.state} (${status.current_phase})`;
+ }
+ if (status.state === "submitted") {
+ return status.current_phase
+ ? `batch • ${status.current_phase}`
+ : "batch submitted";
+ }
+ return status.state;
+}
+
+function capitalize(s: string): string {
+ return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+interface SidebarProps {
+ nodeTypeCounts: Map<string, number>;
+ edgeTypeCounts: Map<string, number>;
+ hiddenNodeTypes: Set<string>;
+ setHiddenNodeTypes: (s: Set<string>) => void;
+ hiddenEdgeTypes: Set<string>;
+ setHiddenEdgeTypes: (s: Set<string>) => void;
+}
+
+function Sidebar({
+ nodeTypeCounts,
+ edgeTypeCounts,
+ hiddenNodeTypes,
+ setHiddenNodeTypes,
+ hiddenEdgeTypes,
+ setHiddenEdgeTypes,
+}: SidebarProps) {
+ function togglePill(set: Set<string>, key: string): Set<string> {
+ const next = new Set(set);
+ if (next.has(key)) next.delete(key);
+ else next.add(key);
+ return next;
+ }
+ return (
+ <div className="col-span-12 space-y-3 md:col-span-3">
+ <div className="rounded-md border bg-white p-3">
+ <h3 className="mb-2 text-xs font-semibold uppercase text-gray-500">
+ Labels
+ </h3>
+ <div className="flex flex-wrap gap-1.5">
+ {[...nodeTypeCounts.entries()]
+ .sort((a, b) => b[1] - a[1])
+ .map(([k, count]) => {
+ const hidden = hiddenNodeTypes.has(k);
+ return (
+ <button
+ key={k}
+ type="button"
+ onClick={() =>
+ setHiddenNodeTypes(togglePill(hiddenNodeTypes, k))
+ }
+ className={`rounded-full border px-2 py-0.5 text-xs ${
+ hidden
+ ? "border-gray-300 text-gray-400 line-through"
+ : "border-gray-700 text-gray-700"
+ }`}
+ >
+ {k} ({count})
+ </button>
+ );
+ })}
+ </div>
+ </div>
+ <div className="rounded-md border bg-white p-3">
+ <h3 className="mb-2 text-xs font-semibold uppercase text-gray-500">
+ Relationships
+ </h3>
+ <div className="flex flex-wrap gap-1.5">
+ {[...edgeTypeCounts.entries()]
+ .sort((a, b) => b[1] - a[1])
+ .map(([k, count]) => {
+ const hidden = hiddenEdgeTypes.has(k);
+ return (
+ <button
+ key={k}
+ type="button"
+ onClick={() =>
+ setHiddenEdgeTypes(togglePill(hiddenEdgeTypes, k))
+ }
+ className={`rounded-full border px-2 py-0.5 text-xs ${
+ hidden
+ ? "border-gray-300 text-gray-400 line-through"
+ : "border-gray-700 text-gray-700"
+ }`}
+ >
+ {k} ({count})
+ </button>
+ );
+ })}
+ </div>
+ </div>
+ </div>
+ );
+}
+
+interface DetailPanelProps {
+ node: {
+ uuid: string;
+ label: string;
+ type?: string | null;
+ name?: string | null;
+ summary?: string | null;
+ } | null;
+ neighbors: {
+ edge: {
+ uuid: string;
+ label: string;
+ source: string;
+ target: string;
+ name?: string | null;
+ fact?: string | null;
+ };
+ otherUuid: string;
+ }[];
+ onClear: () => void;
+}
+
+interface DreamResultPanelProps {
+ status: AnyJobStatus | undefined;
+}
+
+function DreamResultPanel({ status }: DreamResultPanelProps) {
+ if (!status || status.state !== "complete") return null;
+ const result = status.result as Record<string, unknown> | null | undefined;
+ if (!result) return null;
+ // Only the sync_baseline path puts operations + usage on the result.
+ // For the anthropic_batch path the callback writes a smaller summary
+ // (pass_id + stats), so we just hide the panel — the graph itself
+ // refreshes via cache invalidation when the job completes.
+ const operations = result.operations as
+ | Parameters<typeof DreamOperationsView>[0]["operations"]
+ | undefined;
+ const usage = result.usage as
+ | Parameters<typeof DreamUsageSummary>[0]["usage"]
+ | undefined;
+ if (!operations || !usage) return null;
+ return (
+ <div
+ className="grid grid-cols-1 gap-3 lg:grid-cols-2"
+ data-testid="dream-result-panel"
+ >
+ <DreamOperationsView operations={operations} />
+ <DreamUsageSummary usage={usage} />
+ </div>
+ );
+}
+
+function DetailPanel({ node, neighbors, onClear }: DetailPanelProps) {
+ return (
+ <div className="col-span-12 md:col-span-2">
+ <div className="rounded-md border bg-white p-3 text-sm">
+ {!node ? (
+ <div className="text-gray-500">Click a node to inspect.</div>
+ ) : (
+ <>
+ <div className="flex items-start justify-between gap-2">
+ <div className="min-w-0">
+ <div className="truncate text-base font-semibold">
+ {node.name ?? node.uuid.slice(0, 12)}
+ </div>
+ <div className="text-xs text-gray-500">
+ {node.type ?? node.label}
+ </div>
+ </div>
+ <button
+ type="button"
+ onClick={onClear}
+ className="text-xs text-gray-400 hover:text-gray-600"
+ aria-label="Clear selection"
+ >
+ ✕
+ </button>
+ </div>
+ <div className="mt-2 font-mono text-[10px] text-gray-400">
+ {node.uuid}
+ </div>
+ {node.summary && (
+ <div className="mt-3 whitespace-pre-wrap text-xs text-gray-700">
+ {node.summary}
+ </div>
+ )}
+ <h4 className="mt-4 text-xs font-semibold uppercase text-gray-500">
+ {neighbors.length} edges
+ </h4>
+ <ul className="mt-1 max-h-72 space-y-1 overflow-y-auto text-xs">
+ {neighbors.map(({ edge, otherUuid }) => (
+ <li key={edge.uuid} className="border-l-2 border-gray-200 pl-2">
+ <div className="text-gray-700">
+ <span className="font-medium">{edge.label}</span>
+ {edge.name && (
+ <span className="text-gray-500"> · {edge.name}</span>
+ )}
+ </div>
+ {edge.fact && (
+ <div className="text-gray-600">{edge.fact}</div>
+ )}
+ <div className="font-mono text-[10px] text-gray-400">
+ → {otherUuid.slice(0, 12)}
+ </div>
+ </li>
+ ))}
+ </ul>
+ </>
+ )}
+ </div>
+ </div>
+ );
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/__tests__/graph-canvas.test.ts b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/__tests__/graph-canvas.test.ts
new file mode 100644
index 0000000000..909a0d7950
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/__tests__/graph-canvas.test.ts
@@ -0,0 +1,111 @@
+import { describe, expect, test, vi } from "vitest";
+
+// react-force-graph-2d uses HTMLCanvas + window APIs at import time, so
+// stub it out — these tests only exercise GraphCanvas's exported pure
+// helpers, not the canvas itself.
+vi.mock("react-force-graph-2d", () => ({
+ default: () => null,
+}));
+
+import {
+ escapeHtml,
+ getLinkTooltipLabel,
+ getNodeTooltipLabel,
+ linkTouchesNode,
+} from "../GraphCanvas";
+
+describe("tooltip labels stay inert through float-tooltip's innerHTML sink", () => {
+ test("node tooltip renders a malicious memory-derived name as text, not markup", () => {
+ const payload = '<img src=x onerror="window.__pwned = true">';
+ const label = getNodeTooltipLabel({
+ uuid: "node-1",
+ label: "Entity",
+ type: "Person",
+ name: payload,
+ });
+
+ // float-tooltip assigns string labels via innerHTML — simulate that
+ // sink and assert the name cannot create elements.
+ const host = document.createElement("div");
+ host.innerHTML = label;
+ expect(host.querySelector("img")).toBeNull();
+ expect(host.textContent).toBe(`Person: ${payload}`);
+ });
+
+ test("edge tooltip renders a malicious edge name as text, not markup", () => {
+ const payload = "<script>document.title = 'pwned'</script>";
+ const label = getLinkTooltipLabel({
+ uuid: "edge-1",
+ label: "RELATES_TO",
+ source: "a",
+ target: "b",
+ name: payload,
+ });
+
+ const host = document.createElement("div");
+ host.innerHTML = label;
+ expect(host.querySelector("script")).toBeNull();
+ expect(host.textContent).toBe(`RELATES_TO: ${payload}`);
+ });
+
+ test("edge tooltip falls back to the relationship label when unnamed", () => {
+ const label = getLinkTooltipLabel({
+ uuid: "edge-2",
+ label: "MENTIONS",
+ source: "a",
+ target: "b",
+ });
+ expect(label).toBe("MENTIONS");
+ });
+
+ test("node tooltip falls back to the uuid prefix when unnamed", () => {
+ const label = getNodeTooltipLabel({
+ uuid: "abcdef1234567890",
+ label: "Entity",
+ });
+ expect(label).toBe("Entity: abcdef12");
+ });
+
+ test("escapeHtml escapes every HTML-significant character", () => {
+ expect(escapeHtml(`&<>"'`)).toBe("&amp;&lt;&gt;&quot;&#39;");
+ });
+});
+
+describe("selected-node edge highlighting handles both link endpoint shapes", () => {
+ const nodeA = { uuid: "node-a", label: "Entity" };
+ const nodeB = { uuid: "node-b", label: "Entity" };
+
+ test("matches string endpoints before d3 swaps in node objects", () => {
+ const link = {
+ source: "node-a",
+ target: "node-b",
+ uuid: "e1",
+ label: "RELATES_TO",
+ };
+ expect(linkTouchesNode(link, "node-a")).toBe(true);
+ expect(linkTouchesNode(link, "node-b")).toBe(true);
+ expect(linkTouchesNode(link, "node-c")).toBe(false);
+ });
+
+ test("matches object endpoints after d3 replaces ids with node refs", () => {
+ const link = {
+ source: nodeA,
+ target: nodeB,
+ uuid: "e1",
+ label: "RELATES_TO",
+ };
+ expect(linkTouchesNode(link, "node-a")).toBe(true);
+ expect(linkTouchesNode(link, "node-b")).toBe(true);
+ expect(linkTouchesNode(link, "node-c")).toBe(false);
+ });
+
+ test("highlights nothing when no node is selected", () => {
+ const link = {
+ source: nodeA,
+ target: "node-b",
+ uuid: "e1",
+ label: "RELATES_TO",
+ };
+ expect(linkTouchesNode(link, null)).toBe(false);
+ });
+});
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/useMemoryVisualizer.ts b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/useMemoryVisualizer.ts
new file mode 100644
index 0000000000..d7100744a7
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/memory/components/useMemoryVisualizer.ts
@@ -0,0 +1,429 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import {
+ getGetV2GetCommunityRebuildStatusQueryKey,
+ getGetV2GetDreamPassStatusQueryKey,
+ getGetV2GetGraphQueryKey,
+ getGetV2GetMemoryOverviewQueryKey,
+ getGetV2GetNightlyBatchStatusQueryKey,
+ useGetV2GetCommunityRebuildStatus,
+ useGetV2GetDreamPassStatus,
+ useGetV2GetGraph,
+ useGetV2GetMemoryOverview,
+ useGetV2GetNightlyBatchStatus,
+ usePostV2RebuildCommunities,
+ usePostV2TriggerDreamPass,
+ usePostV2TriggerNightlyBatch,
+ usePostV2TriggerRatificationPass,
+} from "@/app/api/__generated__/endpoints/admin/admin";
+import type { CommunityRebuildJobStatus } from "@/app/api/__generated__/models/communityRebuildJobStatus";
+import type { DreamJobStatus } from "@/app/api/__generated__/models/dreamJobStatus";
+import type { DreamJobStatusState } from "@/app/api/__generated__/models/dreamJobStatusState";
+import type { GraphResponse } from "@/app/api/__generated__/models/graphResponse";
+import type { JobTriggerResponse } from "@/app/api/__generated__/models/jobTriggerResponse";
+import type { MemoryOverview } from "@/app/api/__generated__/models/memoryOverview";
+import type { NightlyJobStatus } from "@/app/api/__generated__/models/nightlyJobStatus";
+import type { RatificationResult } from "@/app/api/__generated__/models/ratificationResult";
+import { useToast } from "@/components/molecules/Toast/use-toast";
+
+// Polling envelope shared across all three job kinds — they're
+// structurally identical except for the typed ``result`` payload, so
+// the polling hook walks them as a union. Narrowing to a specific
+// kind happens at the view layer that reads ``status.result``.
+type AnyJobStatus =
+ | DreamJobStatus
+ | NightlyJobStatus
+ | CommunityRebuildJobStatus;
+
+// The state enum is identical across all three concrete envelopes
+// (same underlying Pydantic Literal). Pick the dream variant as the
+// canonical alias to avoid importing three identical types.
+type JobStateValue = DreamJobStatusState;
+
+const USER_ID = "me";
+
+// Polling cadence while a job is in flight. 3s is fast enough that the
+// admin sees phase transitions promptly without flooding the backend
+// (the BatchExecutor itself only walks every 10s anyway).
+const POLL_INTERVAL_MS = 3000;
+
+type TerminalState = Extract<JobStateValue, "complete" | "errored">;
+
+function isTerminal(state: JobStateValue | undefined): state is TerminalState {
+ return state === "complete" || state === "errored";
+}
+
+export function useMemoryVisualizer() {
+ const { toast } = useToast();
+ const queryClient = useQueryClient();
+ const [force, setForce] = useState(false);
+ const [includeEpisodes, setIncludeEpisodes] = useState(false);
+ const [includeCommunities, setIncludeCommunities] = useState(true);
+
+ // Track the in-flight job per kind so the polling hooks know what
+ // to watch. ``undefined`` means no job in flight for that kind.
+ const [activeDreamJobId, setActiveDreamJobId] = useState<
+ string | undefined
+ >();
+ const [activeNightlyJobId, setActiveNightlyJobId] = useState<
+ string | undefined
+ >();
+ const [activeRebuildJobId, setActiveRebuildJobId] = useState<
+ string | undefined
+ >();
+
+ const overview = useGetV2GetMemoryOverview(USER_ID);
+ const graph = useGetV2GetGraph(USER_ID, {
+ include_episodes: includeEpisodes,
+ include_communities: includeCommunities,
+ node_limit: 10000,
+ edge_limit: 20000,
+ });
+
+ // --- Triggers (POST → 202 + job_id) ---------------------------------------
+
+ const rebuild = usePostV2RebuildCommunities({
+ mutation: {
+ onSuccess: (res) => {
+ const result = res.data as JobTriggerResponse;
+ setActiveRebuildJobId(result.job_id);
+ },
+ onError: (error: Error) => {
+ toast({
+ title: "Rebuild failed to schedule",
+ description: error.message,
+ variant: "destructive",
+ });
+ },
+ },
+ });
+
+ const dream = usePostV2TriggerDreamPass({
+ mutation: {
+ onSuccess: (res) => {
+ const result = res.data as JobTriggerResponse;
+ setActiveDreamJobId(result.job_id);
+ },
+ onError: (error: Error) => {
+ toast({
+ title: "Dream pass failed to schedule",
+ description: error.message,
+ variant: "destructive",
+ });
+ },
+ },
+ });
+
+ const nightly = usePostV2TriggerNightlyBatch({
+ mutation: {
+ onSuccess: (res) => {
+ const result = res.data as JobTriggerResponse;
+ setActiveNightlyJobId(result.job_id);
+ },
+ onError: (error: Error) => {
+ toast({
+ title: "Nightly batch failed to schedule",
+ description: error.message,
+ variant: "destructive",
+ });
+ },
+ },
+ });
+
+ // Ratification stays synchronous — Cypher-only, finishes in seconds,
+ // no JobStatus row to poll for.
+ const ratification = usePostV2TriggerRatificationPass({
+ mutation: {
+ onSuccess: (res) => {
+ const result = res.data as RatificationResult;
+ if (result.error) {
+ toast({
+ title: "Ratification failed",
+ description: result.error,
+ variant: "destructive",
+ });
+ } else {
+ toast({
+ title: "Ratification complete",
+ description:
+ `examined=${result.examined_count}, ` +
+ `ratified=${result.ratified_count}, ` +
+ `superseded=${result.superseded_count}`,
+ });
+ }
+ queryClient.invalidateQueries({
+ queryKey: getGetV2GetMemoryOverviewQueryKey(USER_ID),
+ });
+ queryClient.invalidateQueries({
+ queryKey: getGetV2GetGraphQueryKey(USER_ID),
+ });
+ },
+ onError: (error: Error) => {
+ toast({
+ title: "Ratification failed",
+ description: error.message,
+ variant: "destructive",
+ });
+ },
+ },
+ });
+
+ // --- Status pollers (GET → AnyJobStatus) ----------------------------
+ //
+ // refetchInterval stops on terminal state OR on query error so a 5xx
+ // status endpoint doesn't pin the button as forever-in-flight. The
+ // useTerminalEffect handlers below also react to the error path so
+ // the toast fires + the active job id clears.
+
+ const pollOptions = {
+ refetchInterval: (query: {
+ state: { data?: { data?: AnyJobStatus | unknown }; status: string };
+ }) => {
+ if (query.state.status === "error") return false;
+ const state = (query.state.data?.data as AnyJobStatus | undefined)?.state;
+ return isTerminal(state) ? false : POLL_INTERVAL_MS;
+ },
+ staleTime: 0,
+ };
+
+ const dreamStatus = useGetV2GetDreamPassStatus(
+ USER_ID,
+ activeDreamJobId ?? "",
+ { query: { enabled: !!activeDreamJobId, ...pollOptions } },
+ );
+
+ const nightlyStatus = useGetV2GetNightlyBatchStatus(
+ USER_ID,
+ activeNightlyJobId ?? "",
+ { query: { enabled: !!activeNightlyJobId, ...pollOptions } },
+ );
+
+ const rebuildStatus = useGetV2GetCommunityRebuildStatus(
+ USER_ID,
+ activeRebuildJobId ?? "",
+ { query: { enabled: !!activeRebuildJobId, ...pollOptions } },
+ );
+
+ // --- Terminal-state handlers --------------------------------------------
+ //
+ // When a job hits ``complete`` or ``errored``: toast, invalidate the
+ // memory cache (so the visualizer refreshes with the new writes /
+ // demotions), clear the active id (stops polling).
+
+ useTerminalEffect(
+ "Dream pass",
+ activeDreamJobId,
+ dreamStatus.data?.data as AnyJobStatus | undefined,
+ dreamStatus.error,
+ () => {
+ setActiveDreamJobId(undefined);
+ queryClient.invalidateQueries({
+ queryKey: getGetV2GetDreamPassStatusQueryKey(USER_ID, activeDreamJobId),
+ });
+ queryClient.invalidateQueries({
+ queryKey: getGetV2GetMemoryOverviewQueryKey(USER_ID),
+ });
+ queryClient.invalidateQueries({
+ queryKey: getGetV2GetGraphQueryKey(USER_ID),
+ });
+ },
+ toast,
+ );
+
+ useTerminalEffect(
+ "Nightly batch",
+ activeNightlyJobId,
+ nightlyStatus.data?.data as AnyJobStatus | undefined,
+ nightlyStatus.error,
+ () => {
+ setActiveNightlyJobId(undefined);
+ queryClient.invalidateQueries({
+ queryKey: getGetV2GetNightlyBatchStatusQueryKey(
+ USER_ID,
+ activeNightlyJobId,
+ ),
+ });
+ queryClient.invalidateQueries({
+ queryKey: getGetV2GetMemoryOverviewQueryKey(USER_ID),
+ });
+ queryClient.invalidateQueries({
+ queryKey: getGetV2GetGraphQueryKey(USER_ID),
+ });
+ },
+ toast,
+ );
+
+ useTerminalEffect(
+ "Community rebuild",
+ activeRebuildJobId,
+ rebuildStatus.data?.data as AnyJobStatus | undefined,
+ rebuildStatus.error,
+ () => {
+ setActiveRebuildJobId(undefined);
+ queryClient.invalidateQueries({
+ queryKey: getGetV2GetCommunityRebuildStatusQueryKey(
+ USER_ID,
+ activeRebuildJobId,
+ ),
+ });
+ queryClient.invalidateQueries({
+ queryKey: getGetV2GetMemoryOverviewQueryKey(USER_ID),
+ });
+ queryClient.invalidateQueries({
+ queryKey: getGetV2GetGraphQueryKey(USER_ID),
+ });
+ },
+ toast,
+ );
+
+ // --- Action callbacks ---------------------------------------------------
+
+ function triggerRebuild() {
+ rebuild.mutate({ userId: USER_ID, params: { force } });
+ }
+
+ function triggerDream() {
+ dream.mutate({ userId: USER_ID });
+ }
+
+ function triggerRatification() {
+ ratification.mutate({ userId: USER_ID });
+ }
+
+ function triggerNightly() {
+ nightly.mutate({ userId: USER_ID });
+ }
+
+ const overviewData = overview.data?.data as MemoryOverview | undefined;
+ const graphData = graph.data?.data as GraphResponse | undefined;
+ const dreamStatusData = dreamStatus.data?.data as AnyJobStatus | undefined;
+ const nightlyStatusData = nightlyStatus.data?.data as
+ | AnyJobStatus
+ | undefined;
+ const rebuildStatusData = rebuildStatus.data?.data as
+ | AnyJobStatus
+ | undefined;
+
+ return {
+ overview,
+ graph,
+ rebuild,
+ dream,
+ ratification,
+ nightly,
+ triggerRebuild,
+ triggerDream,
+ triggerRatification,
+ triggerNightly,
+ force,
+ setForce,
+ includeEpisodes,
+ setIncludeEpisodes,
+ includeCommunities,
+ setIncludeCommunities,
+ overviewData,
+ graphData,
+ // Polling status + active flags consumed by MemoryVisualizer to
+ // render phase-aware button text.
+ dreamStatusData,
+ nightlyStatusData,
+ rebuildStatusData,
+ activeDreamJobId,
+ activeNightlyJobId,
+ activeRebuildJobId,
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function useTerminalEffect(
+ label: string,
+ activeJobId: string | undefined,
+ status: AnyJobStatus | undefined,
+ queryError: unknown,
+ onTerminal: () => void,
+ toast: ReturnType<typeof useToast>["toast"],
+) {
+ // Reacts to ``status`` transitioning to a terminal state OR the
+ // status-endpoint poll erroring out. Only fires when we have an
+ // active job — protects against late polls from a prior run.
+ useEffect(() => {
+ if (!activeJobId) return;
+
+ // GET /status itself failed (5xx, auth drop, network) — clear the
+ // active job id so the button reactivates and the user can retry,
+ // rather than spinning forever on a broken endpoint. This must fire
+ // even when a stale (non-terminal) status from an earlier successful
+ // poll is still cached: refetchInterval stops on query error, so
+ // without this branch nothing would ever clear the active job id.
+ if (queryError) {
+ toast({
+ title: `${label} status unavailable`,
+ description: String(
+ (queryError as { message?: string } | null)?.message ?? queryError,
+ ),
+ variant: "destructive",
+ });
+ onTerminal();
+ return;
+ }
+
+ if (!status) return;
+ if (!isTerminal(status.state)) return;
+
+ if (status.state === "complete") {
+ toast({
+ title: `${label} complete`,
+ description: completionSummary(status),
+ });
+ } else {
+ toast({
+ title: `${label} failed`,
+ description: status.error ?? "unknown error",
+ variant: "destructive",
+ });
+ }
+ onTerminal();
+ // ``onTerminal`` and ``toast`` are intentionally omitted — they
+ // change on every render and would cause infinite re-runs. The
+ // job_id + state transition + query error are what we want to
+ // react to.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [activeJobId, status?.state, queryError]);
+}
+
+function completionSummary(status: AnyJobStatus): string {
+ const result = status.result as Record<string, unknown> | null | undefined;
+ if (!result) return "OK";
+ // The result shape varies by kind; pick a few common fields and
+ // render whatever's present.
+ const parts: string[] = [];
+ if (typeof result.consolidated_count === "number") {
+ parts.push(`writes=${result.consolidated_count}`);
+ }
+ if (typeof result.proposal_count === "number") {
+ parts.push(`proposals=${result.proposal_count}`);
+ }
+ if (typeof result.demotion_count === "number") {
+ parts.push(`demotions=${result.demotion_count}`);
+ }
+ if (
+ typeof result.communities_built === "object" &&
+ result.communities_built
+ ) {
+ parts.push(`communities=${JSON.stringify(result.communities_built)}`);
+ }
+ if (typeof (result.elapsed_seconds as number | undefined) === "number") {
+ parts.push(`${(result.elapsed_seconds as number).toFixed(1)}s`);
+ }
+ if (result.dream_in_flight === true) {
+ parts.push(
+ "dream apply still in flight — counts land async via the dream pass job",
+ );
+ }
+ return parts.length ? parts.join(" — ") : "OK";
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/memory/page.tsx b/autogpt_platform/frontend/src/app/(platform)/admin/memory/page.tsx
new file mode 100644
index 0000000000..58fc9db44d
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/memory/page.tsx
@@ -0,0 +1,26 @@
+import { withRoleAccess } from "@/lib/withRoleAccess";
+import { MemoryVisualizer } from "./components/MemoryVisualizer";
+
+function MemoryDashboard() {
+ return (
+ <div className="mx-auto p-6">
+ <div className="flex flex-col gap-4">
+ <div>
+ <h1 className="text-3xl font-bold">Memory Inspector</h1>
+ <p className="text-gray-500">
+ View entities, facts, and communities stored in your Graphiti memory
+ graph. Trigger a community rebuild on demand.
+ </p>
+ </div>
+ <MemoryVisualizer />
+ </div>
+ </div>
+ );
+}
+
+export default async function MemoryDashboardPage() {
+ "use server";
+ const withAdminAccess = await withRoleAccess(["admin"]);
+ const ProtectedDashboard = await withAdminAccess(MemoryDashboard);
+ return <ProtectedDashboard />;
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/platform-costs/components/ExecutionPathBadge.tsx b/autogpt_platform/frontend/src/app/(platform)/admin/platform-costs/components/ExecutionPathBadge.tsx
new file mode 100644
index 0000000000..faefa56817
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/platform-costs/components/ExecutionPathBadge.tsx
@@ -0,0 +1,33 @@
+function ExecutionPathBadge({
+ executionPath,
+}: {
+ executionPath: string | null | undefined;
+}) {
+ if (!executionPath) return <span className="text-muted-foreground">—</span>;
+ const colors: Record<string, string> = {
+ anthropic_batch: "bg-green-500/15 text-green-700",
+ openai_batch: "bg-green-500/15 text-green-700",
+ flex: "bg-blue-500/15 text-blue-700",
+ sync_baseline: "bg-muted text-muted-foreground",
+ sync: "bg-muted text-muted-foreground",
+ };
+ // Shorten the long ``anthropic_batch`` / ``openai_batch`` /
+ // ``sync_baseline`` labels so the column doesn't dominate the
+ // table. The full path is in the title attribute for hover.
+ const display =
+ executionPath === "anthropic_batch" || executionPath === "openai_batch"
+ ? "batch"
+ : executionPath === "sync_baseline"
+ ? "sync"
+ : executionPath;
+ return (
+ <span
+ title={executionPath}
+ className={`inline-block rounded px-1.5 py-0.5 text-[10px] font-medium ${colors[executionPath] || colors.sync}`}
+ >
+ {display}
+ </span>
+ );
+}
+
+export { ExecutionPathBadge };
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/platform-costs/components/LogsTable.tsx b/autogpt_platform/frontend/src/app/(platform)/admin/platform-costs/components/LogsTable.tsx
index 3d8af1d61d..29eb9bda1b 100644
--- a/autogpt_platform/frontend/src/app/(platform)/admin/platform-costs/components/LogsTable.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/platform-costs/components/LogsTable.tsx
@@ -1,6 +1,7 @@
import type { CostLogRow } from "@/app/api/__generated__/models/costLogRow";
import type { Pagination } from "@/app/api/__generated__/models/pagination";
import { formatDuration, formatMicrodollars, formatTokens } from "../helpers";
+import { ExecutionPathBadge } from "./ExecutionPathBadge";
import { TrackingBadge } from "./TrackingBadge";
function formatLogDate(value: unknown): string {
@@ -57,6 +58,12 @@ function LogsTable({
<th scope="col" className="px-3 py-3">
Provider
</th>
+ <th scope="col" className="px-3 py-3">
+ Path
+ </th>
+ <th scope="col" className="px-3 py-3">
+ Source
+ </th>
<th scope="col" className="px-3 py-3">
Type
</th>
@@ -94,6 +101,12 @@ function LogsTable({
{log.block_name}
</td>
<td className="px-3 py-2 text-xs">{log.provider}</td>
+ <td className="px-3 py-2 text-xs">
+ <ExecutionPathBadge executionPath={log.execution_path} />
+ </td>
+ <td className="px-3 py-2 text-xs text-muted-foreground">
+ {log.source || "—"}
+ </td>
<td className="px-3 py-2 text-xs">
<TrackingBadge trackingType={log.tracking_type} />
</td>
@@ -145,7 +158,7 @@ function LogsTable({
{logs.length === 0 && (
<tr>
<td
- colSpan={11}
+ colSpan={13}
className="px-4 py-8 text-center text-muted-foreground"
>
No logs found
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/platform-costs/components/PlatformCostContent.tsx b/autogpt_platform/frontend/src/app/(platform)/admin/platform-costs/components/PlatformCostContent.tsx
index 28d11f6c3c..82a94ad9ad 100644
--- a/autogpt_platform/frontend/src/app/(platform)/admin/platform-costs/components/PlatformCostContent.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/platform-costs/components/PlatformCostContent.tsx
@@ -50,6 +50,10 @@ export function PlatformCostContent({ searchParams }: Props) {
setTypeInput,
executionIDInput,
setExecutionIDInput,
+ executionPathInput,
+ setExecutionPathInput,
+ sourceInput,
+ setSourceInput,
rateOverrides,
handleRateOverride,
updateUrl,
@@ -254,6 +258,45 @@ export function PlatformCostContent({ searchParams }: Props) {
onChange={(e) => setExecutionIDInput(e.target.value)}
/>
</div>
+ <div className="flex flex-col gap-1">
+ <label
+ htmlFor="execution-path-filter"
+ className="text-sm text-muted-foreground"
+ >
+ Path
+ </label>
+ <select
+ id="execution-path-filter"
+ className="rounded border px-3 py-1.5 text-sm"
+ value={executionPathInput}
+ onChange={(e) => setExecutionPathInput(e.target.value)}
+ >
+ <option value="">All</option>
+ <option value="sync">sync</option>
+ <option value="anthropic_batch">anthropic_batch</option>
+ <option value="openai_batch">openai_batch</option>
+ <option value="flex">flex</option>
+ <option value="sync_baseline">sync_baseline (dream)</option>
+ </select>
+ </div>
+ <div className="flex flex-col gap-1">
+ <label
+ htmlFor="source-filter"
+ className="text-sm text-muted-foreground"
+ >
+ Source
+ </label>
+ <select
+ id="source-filter"
+ className="rounded border px-3 py-1.5 text-sm"
+ value={sourceInput}
+ onChange={(e) => setSourceInput(e.target.value)}
+ >
+ <option value="">All</option>
+ <option value="copilot">copilot</option>
+ <option value="dream_pass">dream_pass</option>
+ </select>
+ </div>
<button
onClick={handleFilter}
className="rounded bg-primary px-4 py-1.5 text-sm text-primary-foreground hover:bg-primary/90"
@@ -270,6 +313,8 @@ export function PlatformCostContent({ searchParams }: Props) {
setBlockInput("");
setTypeInput("");
setExecutionIDInput("");
+ setExecutionPathInput("");
+ setSourceInput("");
updateUrl({
start: "",
end: "",
@@ -279,6 +324,8 @@ export function PlatformCostContent({ searchParams }: Props) {
block_name: "",
tracking_type: "",
graph_exec_id: "",
+ execution_path: "",
+ source: "",
page: "1",
});
}}
diff --git a/autogpt_platform/frontend/src/app/(platform)/admin/platform-costs/components/usePlatformCostContent.ts b/autogpt_platform/frontend/src/app/(platform)/admin/platform-costs/components/usePlatformCostContent.ts
index 833f5c80a8..a7c38e378c 100644
--- a/autogpt_platform/frontend/src/app/(platform)/admin/platform-costs/components/usePlatformCostContent.ts
+++ b/autogpt_platform/frontend/src/app/(platform)/admin/platform-costs/components/usePlatformCostContent.ts
@@ -24,6 +24,8 @@ interface InitialSearchParams {
block_name?: string;
tracking_type?: string;
graph_exec_id?: string;
+ execution_path?: string;
+ source?: string;
page?: string;
tab?: string;
}
@@ -46,6 +48,9 @@ export function usePlatformCostContent(searchParams: InitialSearchParams) {
urlParams.get("tracking_type") || searchParams.tracking_type || "";
const executionIDFilter =
urlParams.get("graph_exec_id") || searchParams.graph_exec_id || "";
+ const executionPathFilter =
+ urlParams.get("execution_path") || searchParams.execution_path || "";
+ const sourceFilter = urlParams.get("source") || searchParams.source || "";
const [startInput, setStartInput] = useState(toLocalInput(startDate));
const [endInput, setEndInput] = useState(toLocalInput(endDate));
@@ -55,6 +60,9 @@ export function usePlatformCostContent(searchParams: InitialSearchParams) {
const [blockInput, setBlockInput] = useState(blockFilter);
const [typeInput, setTypeInput] = useState(typeFilter);
const [executionIDInput, setExecutionIDInput] = useState(executionIDFilter);
+ const [executionPathInput, setExecutionPathInput] =
+ useState(executionPathFilter);
+ const [sourceInput, setSourceInput] = useState(sourceFilter);
const [rateOverrides, setRateOverrides] = useState<Record<string, number>>(
{},
);
@@ -72,6 +80,8 @@ export function usePlatformCostContent(searchParams: InitialSearchParams) {
block_name: blockFilter || undefined,
tracking_type: typeFilter || undefined,
graph_exec_id: executionIDFilter || undefined,
+ execution_path: executionPathFilter || undefined,
+ source: sourceFilter || undefined,
};
const {
@@ -121,6 +131,8 @@ export function usePlatformCostContent(searchParams: InitialSearchParams) {
block_name: blockInput,
tracking_type: typeInput,
graph_exec_id: executionIDInput,
+ execution_path: executionPathInput,
+ source: sourceInput,
page: "1",
});
}
@@ -193,6 +205,10 @@ export function usePlatformCostContent(searchParams: InitialSearchParams) {
setTypeInput,
executionIDInput,
setExecutionIDInput,
+ executionPathInput,
+ setExecutionPathInput,
+ sourceInput,
+ setSourceInput,
rateOverrides,
handleRateOverride,
updateUrl,
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/__tests__/dreamOperations.test.ts b/autogpt_platform/frontend/src/app/(platform)/copilot/__tests__/dreamOperations.test.ts
new file mode 100644
index 0000000000..dd65cb22e7
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/__tests__/dreamOperations.test.ts
@@ -0,0 +1,74 @@
+import type { UIMessage } from "ai";
+import { describe, expect, it, vi } from "vitest";
+
+import {
+ DREAM_OPERATIONS_PART_TYPE,
+ handleDreamOperationsPart,
+ isDreamOperationsPart,
+ readDreamOperationsPart,
+} from "../dreamOperations";
+
+type Part = UIMessage["parts"][number];
+
+function makeDreamPart(overrides?: { data?: unknown }): Part {
+ return {
+ type: DREAM_OPERATIONS_PART_TYPE,
+ data: overrides?.data ?? {
+ snapshot: {
+ writes: [],
+ proposals: [],
+ demotions: [],
+ entity_invalidations: [],
+ },
+ dream_pass_id: "dp-1",
+ user_id: "u-1",
+ },
+ } as unknown as Part;
+}
+
+describe("dream operations stream part", () => {
+ it("recognises the wire type", () => {
+ expect(isDreamOperationsPart(makeDreamPart())).toBe(true);
+ });
+
+ it("ignores unrelated part types", () => {
+ const textPart = { type: "text", text: "hi" } as unknown as Part;
+ expect(isDreamOperationsPart(textPart)).toBe(false);
+ });
+
+ it("returns the typed payload when shape is valid", () => {
+ const part = makeDreamPart();
+ const data = readDreamOperationsPart(part);
+ expect(data).not.toBeNull();
+ expect(data?.dream_pass_id).toBe("dp-1");
+ expect(data?.user_id).toBe("u-1");
+ expect(data?.snapshot.writes).toEqual([]);
+ });
+
+ it("returns null for malformed payloads instead of throwing", () => {
+ // Missing dream_pass_id — handler must swallow without crashing so a
+ // single bad event can't break the surrounding chat stream parse.
+ const bad = makeDreamPart({
+ data: { snapshot: {}, user_id: "u-1" },
+ });
+ expect(readDreamOperationsPart(bad)).toBeNull();
+ });
+
+ it("handler logs and returns without throwing for valid events", () => {
+ const debugSpy = vi.spyOn(console, "debug").mockImplementation(() => {});
+ expect(() => handleDreamOperationsPart(makeDreamPart())).not.toThrow();
+ expect(debugSpy).toHaveBeenCalledWith(
+ "[copilot] dream.operations event received",
+ "dp-1",
+ );
+ debugSpy.mockRestore();
+ });
+
+ it("handler silently no-ops on a non-dream part", () => {
+ const textPart = { type: "text", text: "hi" } as unknown as Part;
+ const debugSpy = vi.spyOn(console, "debug").mockImplementation(() => {});
+ expect(() => handleDreamOperationsPart(textPart)).not.toThrow();
+ expect(debugSpy).not.toHaveBeenCalled();
+ debugSpy.mockRestore();
+ });
+});
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/components/ChatMessagesContainer/ChatMessagesContainer.tsx b/autogpt_platform/frontend/src/app/(platform)/copilot/components/ChatMessagesContainer/ChatMessagesContainer.tsx
index 2cfd5ca236..81fdd5b093 100644
--- a/autogpt_platform/frontend/src/app/(platform)/copilot/components/ChatMessagesContainer/ChatMessagesContainer.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/components/ChatMessagesContainer/ChatMessagesContainer.tsx
@@ -357,7 +357,10 @@ export function ChatMessagesContainer({
// data-status is transient copy for the Thinking indicator; neither
// counts as "real" content that hides the indicator.
const parts = lastMessage.parts.filter(
- (p) => p.type !== "data-cursor" && p.type !== "data-status",
+ (p) =>
+ p.type !== "data-cursor" &&
+ p.type !== "data-status" &&
+ p.type !== "data-dream-operations",
);
if (parts.length === 0) return false;
@@ -398,6 +401,7 @@ export function ChatMessagesContainer({
for (let i = lastMessage.parts.length - 1; i >= 0; i--) {
const part = lastMessage.parts[i];
if (part.type === "data-cursor") continue;
+ if (part.type === "data-dream-operations") continue;
if (part.type === "data-status") {
const data = (part as { data?: { message?: unknown } }).data;
return typeof data?.message === "string" ? data.message : null;
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/dreamOperations.ts b/autogpt_platform/frontend/src/app/(platform)/copilot/dreamOperations.ts
new file mode 100644
index 0000000000..f90306b862
--- /dev/null
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/dreamOperations.ts
@@ -0,0 +1,84 @@
+import type { UIMessage } from "ai";
+
+import type { DreamOperationsSnapshot } from "@/app/api/__generated__/models/dreamOperationsSnapshot";
+
+/**
+ * AI SDK v5 wire type for the dream-pass snapshot event emitted from
+ * the backend ``dream_events.py``. Matches ``ResponseType.DREAM_OPERATIONS``
+ * on the backend (``data-dream-operations``).
+ *
+ * Real consumer (rendering a "dream summary" artifact inline in the
+ * chat stream) lands in P6 (surface dreams in chat UI) + P9 (daydreaming).
+ * Until then we just recognise the part so the UI filters it out as
+ * bookkeeping instead of crashing on an unknown part type.
+ */
+export const DREAM_OPERATIONS_PART_TYPE = "data-dream-operations" as const;
+
+export interface DreamOperationsPartData {
+ snapshot: DreamOperationsSnapshot;
+ dream_pass_id: string;
+ user_id: string;
+}
+
+interface DreamOperationsPart {
+ type: typeof DREAM_OPERATIONS_PART_TYPE;
+ data: DreamOperationsPartData;
+}
+
+/**
+ * Type guard for the dream-operations part. Mirrors the inline
+ * ``part.type === "data-status"`` checks already used elsewhere in the
+ * copilot tree (see ``helpers.ts:getLatestAssistantStatusMessage``).
+ */
+export function isDreamOperationsPart(
+ part: UIMessage["parts"][number],
+): part is DreamOperationsPart {
+ if (part.type !== DREAM_OPERATIONS_PART_TYPE) return false;
+ const data = (part as { data?: unknown }).data;
+ return !!data && typeof data === "object";
+}
+
+/**
+ * Pull the typed payload out of a dream-operations part if present.
+ *
+ * Returns ``null`` for malformed parts (missing ``data``, wrong shape)
+ * so the dispatcher can log + ignore without throwing — the AI SDK
+ * parser passes through unknown data parts verbatim and we don't want a
+ * single bad event to break the whole stream.
+ */
+export function readDreamOperationsPart(
+ part: UIMessage["parts"][number],
+): DreamOperationsPartData | null {
+ if (part.type !== DREAM_OPERATIONS_PART_TYPE) return null;
+ const data = (part as { data?: unknown }).data;
+ if (!data || typeof data !== "object") return null;
+ const candidate = data as Record<string, unknown>;
+ if (typeof candidate.dream_pass_id !== "string") return null;
+ if (typeof candidate.user_id !== "string") return null;
+ const snapshot = candidate.snapshot;
+ if (!snapshot || typeof snapshot !== "object") return null;
+ return {
+ snapshot: snapshot as DreamOperationsSnapshot,
+ dream_pass_id: candidate.dream_pass_id,
+ user_id: candidate.user_id,
+ };
+}
+
+/**
+ * Dispatcher hook for the new event variant.
+ *
+ * Until the P6 chat-surfacing UI lands we just log the snapshot — the
+ * point of this stub is to give the AI SDK parser a recognised handler
+ * so an unexpected event arriving on a live stream doesn't crash any
+ * downstream filter that assumes the part-type union is closed.
+ */
+export function handleDreamOperationsPart(
+ part: UIMessage["parts"][number],
+): void {
+ const data = readDreamOperationsPart(part);
+ if (!data) return;
+ console.debug(
+ "[copilot] dream.operations event received",
+ data.dream_pass_id,
+ );
+}
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/helpers.ts b/autogpt_platform/frontend/src/app/(platform)/copilot/helpers.ts
index ac0fefce80..ae6ad1f65c 100644
--- a/autogpt_platform/frontend/src/app/(platform)/copilot/helpers.ts
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/helpers.ts
@@ -136,6 +136,7 @@ export function getLatestAssistantStatusMessage(
for (let i = last.parts.length - 1; i >= 0; i--) {
const part = last.parts[i];
if (part.type === "data-cursor") continue;
+ if (part.type === "data-dream-operations") continue;
if (part.type === "data-status") {
const data = (part as { data?: { message?: unknown } }).data;
return typeof data?.message === "string" ? data.message : null;
diff --git a/autogpt_platform/frontend/src/app/api/openapi.json b/autogpt_platform/frontend/src/app/api/openapi.json
index 33ee854079..72e4042270 100644
--- a/autogpt_platform/frontend/src/app/api/openapi.json
+++ b/autogpt_platform/frontend/src/app/api/openapi.json
@@ -1220,6 +1220,667 @@
"security": [{ "HTTPBearerJWT": [] }]
}
},
+ "/api/admin/memory/{user_id}/communities": {
+ "get": {
+ "tags": ["v2", "admin", "admin", "memory"],
+ "summary": "List Communities",
+ "operationId": "getV2ListCommunities",
+ "security": [{ "HTTPBearerJWT": [] }],
+ "parameters": [
+ {
+ "name": "user_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "description": "User id or 'me'",
+ "title": "User Id"
+ },
+ "description": "User id or 'me'"
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "maximum": 2000,
+ "minimum": 1,
+ "default": 500,
+ "title": "Limit"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/CommunityListResponse"
+ }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/api/admin/memory/{user_id}/communities/rebuild": {
+ "post": {
+ "tags": ["v2", "admin", "admin", "memory"],
+ "summary": "Rebuild Communities",
+ "description": "Fire a community rebuild and return 202 + job_id immediately.\n\nFrontend polls\n``GET /api/admin/memory/{user_id}/communities/rebuild/{job_id}``\nfor progress.",
+ "operationId": "postV2RebuildCommunities",
+ "security": [{ "HTTPBearerJWT": [] }],
+ "parameters": [
+ {
+ "name": "user_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "description": "User id or 'me'",
+ "title": "User Id"
+ },
+ "description": "User id or 'me'"
+ },
+ {
+ "name": "force",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "boolean",
+ "description": "Reserved — the fire-and-forget wrapper currently always honours the activity gate. Kept on the signature so the frontend hook doesn't need a contract change when the force flag is threaded through to the wrapper.",
+ "default": false,
+ "title": "Force"
+ },
+ "description": "Reserved — the fire-and-forget wrapper currently always honours the activity gate. Kept on the signature so the frontend hook doesn't need a contract change when the force flag is threaded through to the wrapper."
+ }
+ ],
+ "responses": {
+ "202": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/JobTriggerResponse" }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/api/admin/memory/{user_id}/communities/rebuild/{job_id}": {
+ "get": {
+ "tags": ["v2", "admin", "admin", "memory"],
+ "summary": "Get Community Rebuild Status",
+ "description": "Read the current status of a fire-and-forget community rebuild job.",
+ "operationId": "getV2GetCommunityRebuildStatus",
+ "security": [{ "HTTPBearerJWT": [] }],
+ "parameters": [
+ {
+ "name": "user_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "description": "User id or 'me'",
+ "title": "User Id"
+ },
+ "description": "User id or 'me'"
+ },
+ {
+ "name": "job_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "description": "Job id returned by the POST",
+ "title": "Job Id"
+ },
+ "description": "Job id returned by the POST"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/CommunityRebuildJobStatus"
+ }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/api/admin/memory/{user_id}/dream": {
+ "post": {
+ "tags": ["v2", "admin", "admin", "memory"],
+ "summary": "Trigger Dream Pass",
+ "description": "Fire a dream pass and return 202 + job_id immediately.\n\nFrontend polls ``GET /api/admin/memory/{user_id}/dream/{job_id}``\nfor progress. Runs ONLY the dream pass submitter — for the full\nnightly fan-out use ``POST /{user_id}/nightly``.",
+ "operationId": "postV2TriggerDreamPass",
+ "security": [{ "HTTPBearerJWT": [] }],
+ "parameters": [
+ {
+ "name": "user_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "description": "User id or 'me'",
+ "title": "User Id"
+ },
+ "description": "User id or 'me'"
+ }
+ ],
+ "responses": {
+ "202": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/JobTriggerResponse" }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/api/admin/memory/{user_id}/dream/{job_id}": {
+ "get": {
+ "tags": ["v2", "admin", "admin", "memory"],
+ "summary": "Get Dream Pass Status",
+ "description": "Read the current status of a fire-and-forget dream pass job.",
+ "operationId": "getV2GetDreamPassStatus",
+ "security": [{ "HTTPBearerJWT": [] }],
+ "parameters": [
+ {
+ "name": "user_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "description": "User id or 'me'",
+ "title": "User Id"
+ },
+ "description": "User id or 'me'"
+ },
+ {
+ "name": "job_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "description": "Job id returned by the POST",
+ "title": "Job Id"
+ },
+ "description": "Job id returned by the POST"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/DreamJobStatus" }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/api/admin/memory/{user_id}/entities": {
+ "get": {
+ "tags": ["v2", "admin", "admin", "memory"],
+ "summary": "List Entities",
+ "operationId": "getV2ListEntities",
+ "security": [{ "HTTPBearerJWT": [] }],
+ "parameters": [
+ {
+ "name": "user_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "description": "User id or 'me'",
+ "title": "User Id"
+ },
+ "description": "User id or 'me'"
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "maximum": 10000,
+ "minimum": 1,
+ "default": 1000,
+ "title": "Limit"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/EntityListResponse" }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/api/admin/memory/{user_id}/facts": {
+ "get": {
+ "tags": ["v2", "admin", "admin", "memory"],
+ "summary": "List Facts",
+ "operationId": "getV2ListFacts",
+ "security": [{ "HTTPBearerJWT": [] }],
+ "parameters": [
+ {
+ "name": "user_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "description": "User id or 'me'",
+ "title": "User Id"
+ },
+ "description": "User id or 'me'"
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "maximum": 10000,
+ "minimum": 1,
+ "default": 1000,
+ "title": "Limit"
+ }
+ },
+ {
+ "name": "status",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "enum": ["active", "superseded", "contradicted", "any"],
+ "type": "string",
+ "default": "any",
+ "title": "Status"
+ }
+ },
+ {
+ "name": "scope",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Scope"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/FactListResponse" }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/api/admin/memory/{user_id}/graph": {
+ "get": {
+ "tags": ["v2", "admin", "admin", "memory"],
+ "summary": "Get Graph",
+ "description": "Single-shot graph payload for the visualizer canvas.\n\nReturns nodes + edges in one round-trip so the frontend can hand\nthe whole thing to a force-directed layout without N+1 fetches.\n\nDefaults to entities + communities (the \"what does my memory know\nabout\" view). ``include_episodes=True`` adds the temporal\n:Episodic nodes — useful for debugging extraction but noisy for the\ntypical inspector view.",
+ "operationId": "getV2GetGraph",
+ "security": [{ "HTTPBearerJWT": [] }],
+ "parameters": [
+ {
+ "name": "user_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "description": "User id or 'me'",
+ "title": "User Id"
+ },
+ "description": "User id or 'me'"
+ },
+ {
+ "name": "node_limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "maximum": 20000,
+ "minimum": 1,
+ "default": 5000,
+ "title": "Node Limit"
+ }
+ },
+ {
+ "name": "edge_limit",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "integer",
+ "maximum": 50000,
+ "minimum": 1,
+ "default": 10000,
+ "title": "Edge Limit"
+ }
+ },
+ {
+ "name": "include_episodes",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "boolean",
+ "default": false,
+ "title": "Include Episodes"
+ }
+ },
+ {
+ "name": "include_communities",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "type": "boolean",
+ "default": true,
+ "title": "Include Communities"
+ }
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/GraphResponse" }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/api/admin/memory/{user_id}/nightly": {
+ "post": {
+ "tags": ["v2", "admin", "admin", "memory"],
+ "summary": "Trigger Nightly Batch",
+ "description": "Fire the full nightly batch fan-out and return 202 + job_id immediately.\n\nFrontend polls ``GET /api/admin/memory/{user_id}/nightly/{job_id}``\nfor progress. Same composition as the 03:00 cron — every enabled\nbatch-family submitter runs in sequence sharing one ``nightly_id``\nfor cost-log attribution.",
+ "operationId": "postV2TriggerNightlyBatch",
+ "security": [{ "HTTPBearerJWT": [] }],
+ "parameters": [
+ {
+ "name": "user_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "description": "User id or 'me'",
+ "title": "User Id"
+ },
+ "description": "User id or 'me'"
+ }
+ ],
+ "responses": {
+ "202": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/JobTriggerResponse" }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/api/admin/memory/{user_id}/nightly/{job_id}": {
+ "get": {
+ "tags": ["v2", "admin", "admin", "memory"],
+ "summary": "Get Nightly Batch Status",
+ "description": "Read the current status of a fire-and-forget nightly batch job.",
+ "operationId": "getV2GetNightlyBatchStatus",
+ "security": [{ "HTTPBearerJWT": [] }],
+ "parameters": [
+ {
+ "name": "user_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "description": "User id or 'me'",
+ "title": "User Id"
+ },
+ "description": "User id or 'me'"
+ },
+ {
+ "name": "job_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "description": "Job id returned by the POST",
+ "title": "Job Id"
+ },
+ "description": "Job id returned by the POST"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/NightlyJobStatus" }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/api/admin/memory/{user_id}/overview": {
+ "get": {
+ "tags": ["v2", "admin", "admin", "memory"],
+ "summary": "Get Memory Overview",
+ "operationId": "getV2GetMemoryOverview",
+ "security": [{ "HTTPBearerJWT": [] }],
+ "parameters": [
+ {
+ "name": "user_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "description": "User id or 'me'",
+ "title": "User Id"
+ },
+ "description": "User id or 'me'"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/MemoryOverview" }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+ }
+ }
+ }
+ }
+ }
+ },
+ "/api/admin/memory/{user_id}/ratification": {
+ "post": {
+ "tags": ["v2", "admin", "admin", "memory"],
+ "summary": "Trigger Ratification Pass",
+ "description": "Trigger an on-demand ratification sweep for the user (in isolation).\n\nForwards to ``Scheduler.execute_ratification_pass_now``. Runs ONLY\nthe ratification supersession sweep — does NOT run dream pass or\ncommunity rebuild. Useful for testing ratification behavior\nwithout the full nightly fan-out.",
+ "operationId": "postV2TriggerRatificationPass",
+ "security": [{ "HTTPBearerJWT": [] }],
+ "parameters": [
+ {
+ "name": "user_id",
+ "in": "path",
+ "required": true,
+ "schema": {
+ "type": "string",
+ "description": "User id or 'me'",
+ "title": "User Id"
+ },
+ "description": "User id or 'me'"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/RatificationResult" }
+ }
+ }
+ },
+ "401": {
+ "$ref": "#/components/responses/HTTP401NotAuthenticatedError"
+ },
+ "422": {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/HTTPValidationError" }
+ }
+ }
+ }
+ }
+ }
+ },
"/api/admin/platform-costs/dashboard": {
"get": {
"tags": ["v2", "admin", "platform-cost", "admin"],
@@ -1438,6 +2099,28 @@
"anyOf": [{ "type": "string" }, { "type": "null" }],
"title": "Graph Exec Id"
}
+ },
+ {
+ "name": "execution_path",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "description": "Filter on metadata.execution_path (e.g. 'anthropic_batch', 'sync_baseline', 'flex'). Lets admins narrow rows to a single dispatch mode for cost-savings audits.",
+ "title": "Execution Path"
+ },
+ "description": "Filter on metadata.execution_path (e.g. 'anthropic_batch', 'sync_baseline', 'flex'). Lets admins narrow rows to a single dispatch mode for cost-savings audits."
+ },
+ {
+ "name": "source",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "description": "Filter on metadata.source (e.g. 'dream_pass', 'copilot'). Distinguishes background/system spend from interactive.",
+ "title": "Source"
+ },
+ "description": "Filter on metadata.source (e.g. 'dream_pass', 'copilot'). Distinguishes background/system spend from interactive."
}
],
"responses": {
@@ -1549,6 +2232,24 @@
"anyOf": [{ "type": "string" }, { "type": "null" }],
"title": "Graph Exec Id"
}
+ },
+ {
+ "name": "execution_path",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Execution Path"
+ }
+ },
+ {
+ "name": "source",
+ "in": "query",
+ "required": false,
+ "schema": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Source"
+ }
}
],
"responses": {
@@ -12112,6 +12813,11 @@
"source_platform": {
"anyOf": [{ "type": "string" }, { "type": "null" }],
"title": "Source Platform"
+ },
+ "kind": { "type": "string", "title": "Kind", "default": "normal" },
+ "dream_pass_id": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Dream Pass Id"
}
},
"type": "object",
@@ -12206,20 +12912,117 @@
],
"description": "Null when no weekly cap is configured (unlimited)."
},
- "tier": {
- "$ref": "#/components/schemas/SubscriptionTier",
- "default": "NO_TIER"
+ "tier": {
+ "$ref": "#/components/schemas/SubscriptionTier",
+ "default": "NO_TIER"
+ },
+ "reset_cost": {
+ "type": "integer",
+ "title": "Reset Cost",
+ "description": "Credit cost (in cents) to reset the daily limit. 0 = feature disabled.",
+ "default": 0
+ }
+ },
+ "type": "object",
+ "title": "CoPilotUsagePublic",
+ "description": "Current usage status for a user — public (client-safe) shape."
+ },
+ "CommunityListResponse": {
+ "properties": {
+ "user_id": { "type": "string", "title": "User Id" },
+ "items": {
+ "items": { "$ref": "#/components/schemas/CommunitySummary" },
+ "type": "array",
+ "title": "Items"
+ }
+ },
+ "type": "object",
+ "required": ["user_id", "items"],
+ "title": "CommunityListResponse"
+ },
+ "CommunityRebuildJobStatus": {
+ "properties": {
+ "job_id": { "type": "string", "title": "Job Id" },
+ "user_id": { "type": "string", "title": "User Id" },
+ "kind": {
+ "type": "string",
+ "enum": ["nightly", "dream_pass", "rebuild"],
+ "title": "Kind"
+ },
+ "state": {
+ "type": "string",
+ "enum": ["queued", "running", "submitted", "complete", "errored"],
+ "title": "State"
+ },
+ "started_at": {
+ "type": "string",
+ "format": "date-time",
+ "title": "Started At"
+ },
+ "updated_at": {
+ "type": "string",
+ "format": "date-time",
+ "title": "Updated At"
+ },
+ "completed_at": {
+ "anyOf": [
+ { "type": "string", "format": "date-time" },
+ { "type": "null" }
+ ],
+ "title": "Completed At"
+ },
+ "current_phase": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Current Phase",
+ "description": "Free-form phase label set by the work body. Dream pass uses 'consolidate' | 'recombine' | 'sanitize' | 'apply'; nightly batch reuses those plus 'ratification'; community rebuild uses 'leiden' | 'summarize' | 'persist'."
+ },
+ "batch_id": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Batch Id"
+ },
+ "result": {
+ "anyOf": [
+ { "$ref": "#/components/schemas/RebuildResult" },
+ { "type": "null" }
+ ]
+ },
+ "error": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Error"
+ }
+ },
+ "type": "object",
+ "required": [
+ "job_id",
+ "user_id",
+ "kind",
+ "state",
+ "started_at",
+ "updated_at"
+ ],
+ "title": "CommunityRebuildJobStatus",
+ "description": "JobStatus envelope for ``kind=\"rebuild\"``."
+ },
+ "CommunitySummary": {
+ "properties": {
+ "uuid": { "type": "string", "title": "Uuid" },
+ "name": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Name"
+ },
+ "summary": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Summary"
},
- "reset_cost": {
+ "member_count": {
"type": "integer",
- "title": "Reset Cost",
- "description": "Credit cost (in cents) to reset the daily limit. 0 = feature disabled.",
+ "title": "Member Count",
"default": 0
}
},
"type": "object",
- "title": "CoPilotUsagePublic",
- "description": "Current usage status for a user — public (client-safe) shape."
+ "required": ["uuid"],
+ "title": "CommunitySummary"
},
"ConfirmLinkResponse": {
"properties": {
@@ -12495,6 +13298,14 @@
"cache_creation_tokens": {
"anyOf": [{ "type": "integer" }, { "type": "null" }],
"title": "Cache Creation Tokens"
+ },
+ "execution_path": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Execution Path"
+ },
+ "source": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Source"
}
},
"type": "object",
@@ -12597,7 +13408,7 @@
},
"metadata": {
"$ref": "#/components/schemas/ChatSessionMetadata",
- "default": { "dry_run": false }
+ "default": { "dry_run": false, "kind": "normal" }
}
},
"type": "object",
@@ -12892,6 +13703,22 @@
"required": ["success"],
"title": "DeleteLinkResponse"
},
+ "DemotionSummary": {
+ "properties": {
+ "edge_uuid": { "type": "string", "title": "Edge Uuid" },
+ "reason": { "type": "string", "title": "Reason" },
+ "new_status": {
+ "type": "string",
+ "enum": ["superseded", "contradicted"],
+ "title": "New Status"
+ },
+ "applied": { "type": "boolean", "title": "Applied", "default": true }
+ },
+ "type": "object",
+ "required": ["edge_uuid", "reason", "new_status"],
+ "title": "DemotionSummary",
+ "description": "One line per demoted RELATES_TO edge."
+ },
"DiscoverToolsRequest": {
"properties": {
"server_url": {
@@ -13005,6 +13832,227 @@
"required": ["url", "relevance_score"],
"title": "Document"
},
+ "DreamJobStatus": {
+ "properties": {
+ "job_id": { "type": "string", "title": "Job Id" },
+ "user_id": { "type": "string", "title": "User Id" },
+ "kind": {
+ "type": "string",
+ "enum": ["nightly", "dream_pass", "rebuild"],
+ "title": "Kind"
+ },
+ "state": {
+ "type": "string",
+ "enum": ["queued", "running", "submitted", "complete", "errored"],
+ "title": "State"
+ },
+ "started_at": {
+ "type": "string",
+ "format": "date-time",
+ "title": "Started At"
+ },
+ "updated_at": {
+ "type": "string",
+ "format": "date-time",
+ "title": "Updated At"
+ },
+ "completed_at": {
+ "anyOf": [
+ { "type": "string", "format": "date-time" },
+ { "type": "null" }
+ ],
+ "title": "Completed At"
+ },
+ "current_phase": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Current Phase",
+ "description": "Free-form phase label set by the work body. Dream pass uses 'consolidate' | 'recombine' | 'sanitize' | 'apply'; nightly batch reuses those plus 'ratification'; community rebuild uses 'leiden' | 'summarize' | 'persist'."
+ },
+ "batch_id": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Batch Id"
+ },
+ "result": {
+ "anyOf": [
+ { "$ref": "#/components/schemas/DreamPassResult" },
+ { "type": "null" }
+ ]
+ },
+ "error": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Error"
+ }
+ },
+ "type": "object",
+ "required": [
+ "job_id",
+ "user_id",
+ "kind",
+ "state",
+ "started_at",
+ "updated_at"
+ ],
+ "title": "DreamJobStatus",
+ "description": "JobStatus envelope for ``kind=\"dream_pass\"``."
+ },
+ "DreamOperationsSnapshot": {
+ "properties": {
+ "writes": {
+ "items": { "$ref": "#/components/schemas/WriteSummary" },
+ "type": "array",
+ "title": "Writes"
+ },
+ "proposals": {
+ "items": { "$ref": "#/components/schemas/WriteSummary" },
+ "type": "array",
+ "title": "Proposals"
+ },
+ "demotions": {
+ "items": { "$ref": "#/components/schemas/DemotionSummary" },
+ "type": "array",
+ "title": "Demotions"
+ },
+ "entity_invalidations": {
+ "items": {
+ "$ref": "#/components/schemas/EntityInvalidationSummary"
+ },
+ "type": "array",
+ "title": "Entity Invalidations"
+ }
+ },
+ "type": "object",
+ "title": "DreamOperationsSnapshot",
+ "description": "Detailed per-operation rollup of a single dream pass.\n\nShape used by three downstream consumers:\n 1. The admin memory-visualizer UI (renders the per-edge detail).\n 2. AgentProbe eval scorers (read via ``rawExchangeKey``).\n 3. The future chat-stream ``dream.operations`` SSE event (P6 + P9\n daydreaming, see ``dream/TODO.md``).\n\nKept additive on ``DreamPassResult`` so adding fields here doesn't\nbump the count-only top-level columns existing clients rely on."
+ },
+ "DreamPassResult": {
+ "properties": {
+ "user_id": { "type": "string", "title": "User Id" },
+ "pass_id": { "type": "string", "title": "Pass Id" },
+ "started_at": {
+ "anyOf": [
+ { "type": "string", "format": "date-time" },
+ { "type": "null" }
+ ],
+ "title": "Started At"
+ },
+ "completed_at": {
+ "anyOf": [
+ { "type": "string", "format": "date-time" },
+ { "type": "null" }
+ ],
+ "title": "Completed At"
+ },
+ "elapsed_seconds": {
+ "anyOf": [{ "type": "number" }, { "type": "null" }],
+ "title": "Elapsed Seconds"
+ },
+ "execution_path": {
+ "type": "string",
+ "enum": ["sync_baseline", "anthropic_batch", "openai_batch"],
+ "title": "Execution Path",
+ "default": "sync_baseline"
+ },
+ "consolidated_count": {
+ "type": "integer",
+ "title": "Consolidated Count",
+ "default": 0
+ },
+ "proposal_count": {
+ "type": "integer",
+ "title": "Proposal Count",
+ "default": 0
+ },
+ "demotion_count": {
+ "type": "integer",
+ "title": "Demotion Count",
+ "default": 0
+ },
+ "entity_invalidation_count": {
+ "type": "integer",
+ "title": "Entity Invalidation Count",
+ "default": 0
+ },
+ "summary_for_user": {
+ "type": "string",
+ "title": "Summary For User",
+ "default": ""
+ },
+ "dream_session_id": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Dream Session Id"
+ },
+ "operations": {
+ "anyOf": [
+ { "$ref": "#/components/schemas/DreamOperationsSnapshot" },
+ { "type": "null" }
+ ]
+ },
+ "usage": {
+ "anyOf": [
+ { "$ref": "#/components/schemas/DreamPassUsage" },
+ { "type": "null" }
+ ]
+ },
+ "error": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Error"
+ },
+ "skipped": {
+ "type": "boolean",
+ "title": "Skipped",
+ "default": false
+ },
+ "skip_reason": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Skip Reason"
+ }
+ },
+ "type": "object",
+ "required": ["user_id", "pass_id"],
+ "title": "DreamPassResult",
+ "description": "Return value of ``execute_dream_pass`` and the admin API.\n\nMirrors ``RebuildResponse`` from the community-rebuild endpoint so\nthe admin frontend can render both with the same toast logic."
+ },
+ "DreamPassUsage": {
+ "properties": {
+ "phases": {
+ "items": { "$ref": "#/components/schemas/PhaseUsage" },
+ "type": "array",
+ "title": "Phases"
+ },
+ "total_input_tokens": {
+ "type": "integer",
+ "title": "Total Input Tokens",
+ "default": 0
+ },
+ "total_output_tokens": {
+ "type": "integer",
+ "title": "Total Output Tokens",
+ "default": 0
+ },
+ "total_cache_read_tokens": {
+ "type": "integer",
+ "title": "Total Cache Read Tokens",
+ "default": 0
+ },
+ "total_cache_creation_tokens": {
+ "type": "integer",
+ "title": "Total Cache Creation Tokens",
+ "default": 0
+ },
+ "total_cost_usd": {
+ "anyOf": [{ "type": "number" }, { "type": "null" }],
+ "title": "Total Cost Usd"
+ },
+ "discount_applied": {
+ "type": "number",
+ "title": "Discount Applied",
+ "default": 0.0
+ }
+ },
+ "type": "object",
+ "title": "DreamPassUsage",
+ "description": "Aggregate usage across all phases of one dream pass.\n\nSurfaced on ``DreamPassResult.usage`` so eval / admin UI / billing\ncan read tokens + cost without recomputing. Written to\n``PlatformCostLog`` from apply.py with ``provider='dream_pass'``;\ncharged against the user's rate-limit window via\n``persist_and_record_usage`` so dream-pass spend rolls into the\nsame daily/weekly subscription tier budget as chat-execution\noverage."
+ },
"EnableShareRequest": {
"properties": {
"auto_share_executions": {
@@ -13017,6 +14065,47 @@
"title": "EnableShareRequest",
"description": "Whether to auto-link every ``run_agent`` execution in this chat.\n\nWhen true, the backend creates ``ChatLinkedShare`` rows for every\nexisting agent run AND auto-links any new runs that land while the\nshare is active. When false, only the chat messages are shared\n(cards in the viewer render in their \"execution not shared\" state)."
},
+ "EntityInvalidationSummary": {
+ "properties": {
+ "entity_uuid": { "type": "string", "title": "Entity Uuid" },
+ "reason": { "type": "string", "title": "Reason" },
+ "edges_touched": {
+ "items": { "type": "string" },
+ "type": "array",
+ "title": "Edges Touched"
+ }
+ },
+ "type": "object",
+ "required": ["entity_uuid", "reason"],
+ "title": "EntityInvalidationSummary",
+ "description": "Per-entity invalidation rollup."
+ },
+ "EntityListResponse": {
+ "properties": {
+ "user_id": { "type": "string", "title": "User Id" },
+ "items": {
+ "items": { "$ref": "#/components/schemas/EntitySummary" },
+ "type": "array",
+ "title": "Items"
+ }
+ },
+ "type": "object",
+ "required": ["user_id", "items"],
+ "title": "EntityListResponse"
+ },
+ "EntitySummary": {
+ "properties": {
+ "uuid": { "type": "string", "title": "Uuid" },
+ "name": { "type": "string", "title": "Name" },
+ "summary": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Summary"
+ }
+ },
+ "type": "object",
+ "required": ["uuid", "name"],
+ "title": "EntitySummary"
+ },
"ErrorResponse": {
"properties": {
"type": {
@@ -13402,6 +14491,57 @@
"title": "ExecutionStartedResponse",
"description": "Response for run/schedule actions."
},
+ "FactListResponse": {
+ "properties": {
+ "user_id": { "type": "string", "title": "User Id" },
+ "items": {
+ "items": { "$ref": "#/components/schemas/FactSummary" },
+ "type": "array",
+ "title": "Items"
+ }
+ },
+ "type": "object",
+ "required": ["user_id", "items"],
+ "title": "FactListResponse"
+ },
+ "FactSummary": {
+ "properties": {
+ "uuid": { "type": "string", "title": "Uuid" },
+ "source": { "type": "string", "title": "Source" },
+ "target": { "type": "string", "title": "Target" },
+ "name": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Name"
+ },
+ "fact": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Fact"
+ },
+ "status": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Status"
+ },
+ "scope": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Scope"
+ },
+ "confidence": {
+ "anyOf": [{ "type": "number" }, { "type": "null" }],
+ "title": "Confidence"
+ },
+ "created_at": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Created At"
+ },
+ "expired_at": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Expired At"
+ }
+ },
+ "type": "object",
+ "required": ["uuid", "source", "target"],
+ "title": "FactSummary"
+ },
"FailedExecutionDetail": {
"properties": {
"execution_id": { "type": "string", "title": "Execution Id" },
@@ -13625,9 +14765,37 @@
}
},
"type": "object",
- "required": ["name", "description"],
- "title": "Graph",
- "description": "Creatable graph model used in API create/update endpoints."
+ "required": ["name", "description"],
+ "title": "Graph",
+ "description": "Creatable graph model used in API create/update endpoints."
+ },
+ "GraphEdge": {
+ "properties": {
+ "uuid": { "type": "string", "title": "Uuid" },
+ "label": { "type": "string", "title": "Label" },
+ "source": { "type": "string", "title": "Source" },
+ "target": { "type": "string", "title": "Target" },
+ "name": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Name"
+ },
+ "fact": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Fact"
+ },
+ "status": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Status"
+ },
+ "scope": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Scope"
+ }
+ },
+ "type": "object",
+ "required": ["uuid", "label", "source", "target"],
+ "title": "GraphEdge",
+ "description": "An edge in the visualizer graph payload."
},
"GraphExecution": {
"properties": {
@@ -14240,6 +15408,53 @@
"title": "GraphModelWithoutNodes",
"description": "GraphModel variant that excludes nodes, links, and sub-graphs from serialization.\n\nUsed in contexts like the store where exposing internal graph structure\nis not desired. Inherits all computed fields from GraphModel but marks\nnodes and links as excluded from JSON output."
},
+ "GraphNode": {
+ "properties": {
+ "uuid": { "type": "string", "title": "Uuid" },
+ "label": { "type": "string", "title": "Label" },
+ "type": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Type"
+ },
+ "name": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Name"
+ },
+ "summary": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Summary"
+ }
+ },
+ "type": "object",
+ "required": ["uuid", "label"],
+ "title": "GraphNode",
+ "description": "A node in the visualizer graph payload.\n\n``label`` is the primary FalkorDB label (Entity / Episodic /\nCommunity); ``type`` (if present) is the more-specific custom\nentity type from ``MemoryFact``-typed extraction (Person /\nOrganization / Project / Concept / Preference / Rule). The frontend\nuses ``type`` for color-coding when present, falls back to ``label``."
+ },
+ "GraphResponse": {
+ "properties": {
+ "user_id": { "type": "string", "title": "User Id" },
+ "group_id": { "type": "string", "title": "Group Id" },
+ "nodes": {
+ "items": { "$ref": "#/components/schemas/GraphNode" },
+ "type": "array",
+ "title": "Nodes"
+ },
+ "edges": {
+ "items": { "$ref": "#/components/schemas/GraphEdge" },
+ "type": "array",
+ "title": "Edges"
+ },
+ "truncated": {
+ "type": "boolean",
+ "title": "Truncated",
+ "description": "True when the result was capped by ``node_limit`` / ``edge_limit``. Frontend should surface this so the user knows they're not seeing the full graph.",
+ "default": false
+ }
+ },
+ "type": "object",
+ "required": ["user_id", "group_id", "nodes", "edges"],
+ "title": "GraphResponse"
+ },
"GraphSettings": {
"properties": {
"human_in_the_loop_safe_mode": {
@@ -14429,6 +15644,31 @@
"title": "InvoiceListItem",
"description": "A single invoice surfaced from Stripe for the billing UI.\n\nMirrors the subset of `stripe.Invoice` we expose to the client. ``hosted_invoice_url``\nopens the Stripe-hosted view; ``invoice_pdf_url`` lets users download the PDF directly.\n\n``total_cents`` is the invoice total (what the user owes / will be charged); use it\nfor the displayed amount. ``amount_paid_cents`` is what Stripe has actually settled\nso far — `0` for ``open``/``draft`` invoices — and is kept for callers that need to\nshow outstanding balances separately."
},
+ "JobTriggerResponse": {
+ "properties": {
+ "job_id": { "type": "string", "title": "Job Id" },
+ "user_id": { "type": "string", "title": "User Id" },
+ "kind": {
+ "type": "string",
+ "enum": ["nightly", "dream_pass", "rebuild"],
+ "title": "Kind"
+ },
+ "state": {
+ "type": "string",
+ "enum": ["queued", "running", "submitted", "complete", "errored"],
+ "title": "State"
+ },
+ "started_at": {
+ "type": "string",
+ "format": "date-time",
+ "title": "Started At"
+ }
+ },
+ "type": "object",
+ "required": ["job_id", "user_id", "kind", "state", "started_at"],
+ "title": "JobTriggerResponse",
+ "description": "202 response from a fire-and-forget admin trigger.\n\nFrontend captures ``job_id`` and polls ``GET .../{job_id}`` for\nprogress. ``state`` is always ``\"queued\"`` at this point — the\nscheduler picks the job up within sub-second and flips it to\n``running``."
+ },
"LibraryAgent": {
"properties": {
"id": { "type": "string", "title": "Id" },
@@ -15234,6 +16474,32 @@
"title": "MemoryForgetConfirmResponse",
"description": "Response after deleting specific memory edges."
},
+ "MemoryOverview": {
+ "properties": {
+ "user_id": { "type": "string", "title": "User Id" },
+ "group_id": { "type": "string", "title": "Group Id" },
+ "entities": { "type": "integer", "title": "Entities" },
+ "episodes": { "type": "integer", "title": "Episodes" },
+ "relates_to_edges": {
+ "type": "integer",
+ "title": "Relates To Edges"
+ },
+ "mentions_edges": { "type": "integer", "title": "Mentions Edges" },
+ "communities": { "type": "integer", "title": "Communities" }
+ },
+ "type": "object",
+ "required": [
+ "user_id",
+ "group_id",
+ "entities",
+ "episodes",
+ "relates_to_edges",
+ "mentions_edges",
+ "communities"
+ ],
+ "title": "MemoryOverview",
+ "description": "Counts surfaced in the visualizer's header strip."
+ },
"MemorySearchResponse": {
"properties": {
"type": {
@@ -15370,6 +16636,129 @@
"title": "NeedLoginResponse",
"description": "Response when login is needed."
},
+ "NightlyBatchResult": {
+ "properties": {
+ "user_id": { "type": "string", "title": "User Id" },
+ "nightly_id": {
+ "type": "string",
+ "title": "Nightly Id",
+ "description": "UUID correlating every per-submitter cost-log row for this pass. The dream pass and ratification supersession sweep all share this id."
+ },
+ "started_at": {
+ "type": "string",
+ "format": "date-time",
+ "title": "Started At"
+ },
+ "completed_at": {
+ "anyOf": [
+ { "type": "string", "format": "date-time" },
+ { "type": "null" }
+ ],
+ "title": "Completed At"
+ },
+ "elapsed_seconds": {
+ "anyOf": [{ "type": "number" }, { "type": "null" }],
+ "title": "Elapsed Seconds"
+ },
+ "dream": {
+ "anyOf": [
+ { "$ref": "#/components/schemas/DreamPassResult" },
+ { "type": "null" }
+ ]
+ },
+ "ratification": {
+ "anyOf": [
+ { "$ref": "#/components/schemas/RatificationResult" },
+ { "type": "null" }
+ ]
+ },
+ "dream_in_flight": {
+ "type": "boolean",
+ "title": "Dream In Flight",
+ "default": false
+ },
+ "skipped": {
+ "type": "boolean",
+ "title": "Skipped",
+ "default": false
+ },
+ "skip_reason": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Skip Reason"
+ },
+ "error": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Error"
+ }
+ },
+ "type": "object",
+ "required": ["user_id", "nightly_id", "started_at"],
+ "title": "NightlyBatchResult",
+ "description": "Structured outcome of one nightly-batch-submit pass.\n\nSurfaced via the scheduler wrapper + admin endpoint so we can\naudit \"what fired tonight for this user\" without scraping logs."
+ },
+ "NightlyJobStatus": {
+ "properties": {
+ "job_id": { "type": "string", "title": "Job Id" },
+ "user_id": { "type": "string", "title": "User Id" },
+ "kind": {
+ "type": "string",
+ "enum": ["nightly", "dream_pass", "rebuild"],
+ "title": "Kind"
+ },
+ "state": {
+ "type": "string",
+ "enum": ["queued", "running", "submitted", "complete", "errored"],
+ "title": "State"
+ },
+ "started_at": {
+ "type": "string",
+ "format": "date-time",
+ "title": "Started At"
+ },
+ "updated_at": {
+ "type": "string",
+ "format": "date-time",
+ "title": "Updated At"
+ },
+ "completed_at": {
+ "anyOf": [
+ { "type": "string", "format": "date-time" },
+ { "type": "null" }
+ ],
+ "title": "Completed At"
+ },
+ "current_phase": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Current Phase",
+ "description": "Free-form phase label set by the work body. Dream pass uses 'consolidate' | 'recombine' | 'sanitize' | 'apply'; nightly batch reuses those plus 'ratification'; community rebuild uses 'leiden' | 'summarize' | 'persist'."
+ },
+ "batch_id": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Batch Id"
+ },
+ "result": {
+ "anyOf": [
+ { "$ref": "#/components/schemas/NightlyBatchResult" },
+ { "type": "null" }
+ ]
+ },
+ "error": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Error"
+ }
+ },
+ "type": "object",
+ "required": [
+ "job_id",
+ "user_id",
+ "kind",
+ "state",
+ "started_at",
+ "updated_at"
+ ],
+ "title": "NightlyJobStatus",
+ "description": "JobStatus envelope for ``kind=\"nightly\"``."
+ },
"NoResultsResponse": {
"properties": {
"type": {
@@ -16004,6 +17393,44 @@
"title": "PendingHumanReviewModel",
"description": "Response model for pending human review data.\n\nRepresents a human review request that is awaiting user action.\nContains all necessary information for a user to review and approve\nor reject data from a Human-in-the-Loop block execution.\n\nAttributes:\n id: Unique identifier for the review record\n user_id: ID of the user who must perform the review\n node_exec_id: ID of the node execution that created this review\n node_id: ID of the node definition (for grouping reviews from same node)\n graph_exec_id: ID of the graph execution containing the node\n graph_id: ID of the graph template being executed\n graph_version: Version number of the graph template\n payload: The actual data payload awaiting review\n instructions: Instructions or message for the reviewer\n editable: Whether the reviewer can edit the data\n status: Current review status (WAITING, APPROVED, or REJECTED)\n review_message: Optional message from the reviewer\n created_at: Timestamp when review was created\n updated_at: Timestamp when review was last modified\n reviewed_at: Timestamp when review was completed (if applicable)"
},
+ "PhaseUsage": {
+ "properties": {
+ "phase": {
+ "type": "string",
+ "enum": ["consolidate", "recombine", "sanitize"],
+ "title": "Phase"
+ },
+ "model": { "type": "string", "title": "Model" },
+ "input_tokens": {
+ "type": "integer",
+ "title": "Input Tokens",
+ "default": 0
+ },
+ "output_tokens": {
+ "type": "integer",
+ "title": "Output Tokens",
+ "default": 0
+ },
+ "cache_read_tokens": {
+ "type": "integer",
+ "title": "Cache Read Tokens",
+ "default": 0
+ },
+ "cache_creation_tokens": {
+ "type": "integer",
+ "title": "Cache Creation Tokens",
+ "default": 0
+ },
+ "cost_usd": {
+ "anyOf": [{ "type": "number" }, { "type": "null" }],
+ "title": "Cost Usd"
+ }
+ },
+ "type": "object",
+ "required": ["phase", "model"],
+ "title": "PhaseUsage",
+ "description": "Per-phase token + cost telemetry."
+ },
"PickerTokenResponse": {
"properties": {
"access_token": {
@@ -16845,6 +18272,103 @@
"title": "RateLimitResetResponse",
"description": "Response from resetting the daily rate limit."
},
+ "RatificationResult": {
+ "properties": {
+ "user_id": { "type": "string", "title": "User Id" },
+ "started_at": {
+ "type": "string",
+ "format": "date-time",
+ "title": "Started At"
+ },
+ "completed_at": {
+ "anyOf": [
+ { "type": "string", "format": "date-time" },
+ { "type": "null" }
+ ],
+ "title": "Completed At"
+ },
+ "examined_count": {
+ "type": "integer",
+ "title": "Examined Count",
+ "default": 0
+ },
+ "ratified_count": {
+ "type": "integer",
+ "title": "Ratified Count",
+ "default": 0
+ },
+ "superseded_count": {
+ "type": "integer",
+ "title": "Superseded Count",
+ "default": 0
+ },
+ "error": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Error"
+ },
+ "skipped": {
+ "type": "boolean",
+ "title": "Skipped",
+ "default": false
+ },
+ "skip_reason": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Skip Reason"
+ },
+ "per_edge_errors": {
+ "items": { "type": "string" },
+ "type": "array",
+ "title": "Per Edge Errors"
+ }
+ },
+ "type": "object",
+ "required": ["user_id", "started_at"],
+ "title": "RatificationResult",
+ "description": "Structured outcome of a single ratification pass.\n\nSurfaced via the scheduler wrapper so admin / future metrics can\nread promotion vs. supersession counts without re-scanning Graphiti."
+ },
+ "RebuildResult": {
+ "properties": {
+ "user_id": { "type": "string", "title": "User Id" },
+ "started_at": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Started At"
+ },
+ "communities_built": { "title": "Communities Built" },
+ "elapsed_seconds": {
+ "anyOf": [{ "type": "number" }, { "type": "null" }],
+ "title": "Elapsed Seconds"
+ },
+ "error": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Error"
+ },
+ "skipped": {
+ "type": "boolean",
+ "title": "Skipped",
+ "default": false
+ },
+ "skip_reason": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Skip Reason"
+ },
+ "activity": {
+ "anyOf": [
+ { "additionalProperties": true, "type": "object" },
+ { "type": "null" }
+ ],
+ "title": "Activity"
+ },
+ "forced": { "type": "boolean", "title": "Forced", "default": false },
+ "execution_path": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Execution Path"
+ }
+ },
+ "type": "object",
+ "required": ["user_id"],
+ "title": "RebuildResult",
+ "description": "Typed envelope around ``rebuild_communities_for_user``'s return dict.\n\nLives here (admin routes) rather than in ``copilot/graphiti/communities.py``\nbecause the dict-returning rebuild function predates the admin-API\ntyping pass. Hoisting it to ``communities.py`` (and changing the\nfunction signature) is a follow-up cleanup."
+ },
"RecentExecution": {
"properties": {
"status": { "type": "string", "title": "Status" },
@@ -17573,7 +19097,7 @@
},
"metadata": {
"$ref": "#/components/schemas/ChatSessionMetadata",
- "default": { "dry_run": false }
+ "default": { "dry_run": false, "kind": "normal" }
}
},
"type": "object",
@@ -21034,6 +22558,44 @@
],
"title": "WorkspaceFileItem"
},
+ "WriteSummary": {
+ "properties": {
+ "edge_uuid": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Edge Uuid"
+ },
+ "content": { "type": "string", "title": "Content" },
+ "scope": {
+ "type": "string",
+ "title": "Scope",
+ "default": "real:global"
+ },
+ "confidence": {
+ "anyOf": [{ "type": "number" }, { "type": "null" }],
+ "title": "Confidence"
+ },
+ "status": {
+ "type": "string",
+ "enum": ["active", "tentative"],
+ "title": "Status",
+ "default": "active"
+ },
+ "source_episode_uuids": {
+ "items": { "type": "string" },
+ "type": "array",
+ "title": "Source Episode Uuids"
+ },
+ "source_fact_uuids": {
+ "items": { "type": "string" },
+ "type": "array",
+ "title": "Source Fact Uuids"
+ }
+ },
+ "type": "object",
+ "required": ["content"],
+ "title": "WriteSummary",
+ "description": "One line per envelope written by apply.py.\n\nCarries the durable Graphiti edge uuid so the eval / admin UI / the\nfuture inline chat-stream `dream.operations` event (P9 daydreaming)\ncan render or audit individual operations. ``edge_uuid`` is None\nwhen the underlying ``enqueue_episode`` call did not return one\n(FalkorDB unreachable, etc.) — we still record the attempted write."
+ },
"backend__api__features__chat__share__ShareResponse": {
"properties": {
"share_url": { "type": "string", "title": "Share Url" },
diff --git a/autogpt_platform/frontend/src/services/feature-flags/__tests__/flag-defaults.test.ts b/autogpt_platform/frontend/src/services/feature-flags/__tests__/flag-defaults.test.ts
new file mode 100644
index 0000000000..b13869bcee
--- /dev/null
+++ b/autogpt_platform/frontend/src/services/feature-flags/__tests__/flag-defaults.test.ts
@@ -0,0 +1,48 @@
+import { renderHook } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { Flag, useGetFlag } from "../use-get-flag";
+
+// LD is enabled but has not answered for any key — the exact window
+// (init lag, outage, missing flag key) where useGetFlag falls through
+// to defaultFlags in production.
+vi.mock("launchdarkly-react-client-sdk", () => ({
+ useFlags: () => ({}),
+}));
+
+vi.mock("@/app/(platform)/marketplace/components/HeroSection/helpers", () => ({
+ DEFAULT_SEARCH_TERMS: [],
+}));
+
+vi.mock("@/services/environment", () => ({
+ environment: { areFeatureFlagsEnabled: () => true },
+}));
+
+const DREAM_GRAPHITI_FLAGS = [
+ Flag.GRAPHITI_MEMORY,
+ Flag.GRAPHITI_COMMUNITIES_ENABLED,
+ Flag.DREAM_PASS_ENABLED,
+ Flag.DREAM_PASS_WEB_FACT_CHECK,
+ Flag.DREAM_PASS_INVALIDATE_ENTITY,
+] as const;
+
+describe("dream/graphiti flag defaults fail closed", () => {
+ beforeEach(() => {
+ Object.keys(process.env)
+ .filter((k) => k.startsWith("NEXT_PUBLIC_FORCE_FLAG_"))
+ .forEach((k) => delete process.env[k]);
+ });
+
+ it.each(DREAM_GRAPHITI_FLAGS)(
+ "resolves %s to false when LaunchDarkly has not answered, mirroring the backend's default=False gating",
+ (flag) => {
+ const { result } = renderHook(() => useGetFlag(flag));
+ expect(result.current).toBe(false);
+ },
+ );
+
+ it("still lets local dev force-enable the stack via the env override", () => {
+ process.env.NEXT_PUBLIC_FORCE_FLAG_DREAM_PASS_ENABLED = "true";
+ const { result } = renderHook(() => useGetFlag(Flag.DREAM_PASS_ENABLED));
+ expect(result.current).toBe(true);
+ });
+});
diff --git a/autogpt_platform/frontend/src/services/feature-flags/use-get-flag.ts b/autogpt_platform/frontend/src/services/feature-flags/use-get-flag.ts
index 977fa69fda..8ce41fcf4b 100644
--- a/autogpt_platform/frontend/src/services/feature-flags/use-get-flag.ts
+++ b/autogpt_platform/frontend/src/services/feature-flags/use-get-flag.ts
@@ -17,6 +17,19 @@ export enum Flag {
GENERIC_TRIGGER_AGENTS = "generic-trigger-agents",
CHAT_SEARCH = "chat-search",
CHAT_SHARING = "chat-sharing",
+ // Graphiti memory + dream-system gates. Mirror of the backend
+ // ``Flag`` enum in ``backend/util/feature_flag.py``. Frontend reads
+ // them when memory/dream-related UI surfaces ship (P6+ on the
+ // dream-system roadmap). They default false below to match the
+ // backend's fail-closed gating (default=False, opt-in only) — a
+ // LaunchDarkly outage or missing flag key must not switch the
+ // feature on. Use ``NEXT_PUBLIC_FORCE_FLAG_*`` env overrides to
+ // enable the stack for local-dev / Playwright runs.
+ GRAPHITI_MEMORY = "graphiti-memory",
+ GRAPHITI_COMMUNITIES_ENABLED = "graphiti-communities-enabled",
+ DREAM_PASS_ENABLED = "dream-pass-enabled",
+ DREAM_PASS_WEB_FACT_CHECK = "dream-pass-web-fact-check",
+ DREAM_PASS_INVALIDATE_ENTITY = "dream-pass-invalidate-entity",
}
const isPwMockEnabled = process.env.NEXT_PUBLIC_PW_TEST === "true";
@@ -33,6 +46,11 @@ const defaultFlags = {
[Flag.GENERIC_TRIGGER_AGENTS]: false,
[Flag.CHAT_SEARCH]: false,
[Flag.CHAT_SHARING]: false,
+ [Flag.GRAPHITI_MEMORY]: false,
+ [Flag.GRAPHITI_COMMUNITIES_ENABLED]: false,
+ [Flag.DREAM_PASS_ENABLED]: false,
+ [Flag.DREAM_PASS_WEB_FACT_CHECK]: false,
+ [Flag.DREAM_PASS_INVALIDATE_ENTITY]: false,
};
type FlagValues = typeof defaultFlags;
@@ -78,6 +96,16 @@ function readEnvOverride(flag: Flag): string | undefined {
return process.env.NEXT_PUBLIC_FORCE_FLAG_CHAT_SEARCH;
case Flag.CHAT_SHARING:
return process.env.NEXT_PUBLIC_FORCE_FLAG_CHAT_SHARING;
+ case Flag.GRAPHITI_MEMORY:
+ return process.env.NEXT_PUBLIC_FORCE_FLAG_GRAPHITI_MEMORY;
+ case Flag.GRAPHITI_COMMUNITIES_ENABLED:
+ return process.env.NEXT_PUBLIC_FORCE_FLAG_GRAPHITI_COMMUNITIES_ENABLED;
+ case Flag.DREAM_PASS_ENABLED:
+ return process.env.NEXT_PUBLIC_FORCE_FLAG_DREAM_PASS_ENABLED;
+ case Flag.DREAM_PASS_WEB_FACT_CHECK:
+ return process.env.NEXT_PUBLIC_FORCE_FLAG_DREAM_PASS_WEB_FACT_CHECK;
+ case Flag.DREAM_PASS_INVALIDATE_ENTITY:
+ return process.env.NEXT_PUBLIC_FORCE_FLAG_DREAM_PASS_INVALIDATE_ENTITY;
}
}
diff --git a/docs/platform/copilot-local-llm.md b/docs/platform/copilot-local-llm.md
index 6372ffbb54..03e6d01cd3 100644
--- a/docs/platform/copilot-local-llm.md
+++ b/docs/platform/copilot-local-llm.md
@@ -41,7 +41,7 @@ four chat transports. When `CHAT_USE_LOCAL=true`:
| Routes the baseline (fast) path to `CHAT_BASE_URL` over OpenAI-compatible HTTP | ✅ |
| Supports the SDK / extended-thinking path (Claude Agent SDK) | ❌ — auto-downgrades to fast |
| `api_key` falls back to `OPEN_ROUTER_API_KEY` / `OPENAI_API_KEY` if `CHAT_API_KEY` is unset | ❌ — explicit `CHAT_API_KEY` only |
-| Auxiliary models (`title_model`, `simulation_model`) inherit `fast_standard_model` if left at default | ✅ |
+| Aux + advanced models (`title_model`, `simulation_model`, `fast_advanced_model`) inherit `fast_standard_model` if left at a cloud default | ✅ |
| Allows non-`anthropic/*` SDK model slugs (vendor validator skipped) | ✅ |
The downgrade is logged at WARNING when an `extended_thinking` request
@@ -73,12 +73,14 @@ CHAT_API_KEY=ollama
# resolve them. See "Picking a model" below.
CHAT_FAST_STANDARD_MODEL=hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M
-# Optional — overrides for advanced tier and aux models. If you leave
-# them out, the local transport derives title_model and simulation_model
-# from CHAT_FAST_STANDARD_MODEL automatically; CHAT_FAST_ADVANCED_MODEL
-# stays at its cloud default and you should set it to the same Ollama
-# slug (or a bigger one if you have the VRAM).
-CHAT_FAST_ADVANCED_MODEL=hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M
+# Optional — override for the advanced tier. If you leave it out, the
+# local transport derives title_model, simulation_model, AND
+# CHAT_FAST_ADVANCED_MODEL from CHAT_FAST_STANDARD_MODEL automatically
+# (see _apply_local_aux_models in backend/backend/copilot/config.py),
+# so the advanced toggle never sends a cloud-only slug to Ollama. Set
+# it explicitly only if you want a bigger model for the advanced tier
+# and have the VRAM for it.
+CHAT_FAST_ADVANCED_MODEL=qwen3:14b-q4_K_M
```
## Picking a model
@@ -91,7 +93,7 @@ model that handles all three.
| --- | --- | --- | --- |
| **Default** | `hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M` | Unsloth-recommended; solid OpenAI-shim tool-calling at 4B; 256 k native context; reasoning model (the chat UI renders its thinking separately from the answer) | ~3.4 GB resident; runs on a 16 GB laptop, GPU-accelerated |
| **Tight RAM** | `qwen3:4b` | Smaller; native tools; set `think: false` to avoid the unclosed-`<think>` tool-call render bug | ~3-4 GB resident |
-| **GPU / advanced** | `qwen3:14b-instruct-q4_K_M` | Best tool-selection accuracy in this size class | ~12 GB VRAM |
+| **GPU / advanced** | `qwen3:14b-q4_K_M` | Best tool-selection accuracy in this size class | ~12 GB VRAM |
Pull whichever you choose:
@@ -335,14 +337,98 @@ request, which can take 5-15 s for 8 B models on CPU. Subsequent
requests are much faster while the model stays resident.
**Every AutoPilot turn takes minutes on CPU** — expected on CPU-only
-hosts, not a hang. AutoPilot ships a ~3 k-token system prompt and the
+hosts, not a hang. AutoPilot ships an ~8 k-token system prompt and the
model must *prefill* (compute KV-cache state for) every token of that
prompt before the first output token is emitted. On 4 CPU cores an
8 B Q4 model prefills at roughly **3-4 tokens/sec**, so a fresh turn
-takes ~10-15 min just to start generating. Title generation (~70-token
+takes ~35-45 min just to start generating. Title generation (~70-token
prompt) finishes in seconds because there's almost nothing to prefill.
A consumer GPU brings this down to seconds. If you're CPU-only and
just want to validate the install end-to-end, tail the Ollama server
log (see the per-platform commands in "Verifying the wiring" above)
and watch for the `POST /v1/chat/completions` line — once it appears
with a 200, prefill finished and the model is generating.
+
+## Dream pass + memory under local transport
+
+The graphiti memory layer and the nightly dream pass both ride the
+same self-hosted backend `CHAT_USE_LOCAL=true` points at. Three
+things you should know:
+
+### Dream pass runs sync-baseline only
+
+The dream pass's batch path (Anthropic batch, OpenAI batch) is
+provider-locked and unavailable on local backends. `CHAT_USE_LOCAL=true`
+forces `execution_path="sync_baseline"` regardless of which API keys
+might be set elsewhere on the box — your local LLM handles all three
+phases (consolidate / recombine / sanitize) on the same endpoint as
+chat. Cost-log rows label `provider="ollama"` so the admin
+platform-costs dashboard distinguishes them from cloud spend.
+
+### Memory uses the chat models by default
+
+When `CHAT_USE_LOCAL=true`, `GraphitiConfig._apply_local_graphiti_models`
+rewrites the cloud OpenAI defaults to local Ollama equivalents:
+
+| Setting | Cloud default | Local default |
+|---|---|---|
+| `GRAPHITI_LLM_MODEL` | `gpt-4.1-mini` | `hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M` |
+| `GRAPHITI_RERANKER_MODEL` | `gpt-4.1-nano` | `hf.co/unsloth/Qwen3.5-4B-GGUF:Q4_K_M` |
+| `GRAPHITI_EMBEDDER_MODEL` | `text-embedding-3-small` | `nomic-embed-text` |
+
+The LLM + reranker reuse the same Qwen 3.5 4B model the `--with-ollama`
+installer already pulls for chat, so no extra `ollama pull` is needed
+unless you've overridden them. The embedder is a separate model — see
+the next section.
+
+You can pin your own slugs at any time by setting the matching
+`GRAPHITI_*_MODEL` env var; the validator only touches slots still at
+their cloud default. A custom slug (`qwen3:8b`, `hf.co/...`,
+`my-registry.io/model:tag`) passes through untouched.
+
+### Embeddings require an embedding model pulled into Ollama
+
+Ollama doesn't ship an embedding model in its default model set, so
+graphiti's per-turn entity extraction will 404 on `/v1/embeddings`
+until you pull one:
+
+```bash
+ollama pull nomic-embed-text
+```
+
+Without it, chat still works, but `graphiti.add_episode(...)` fails
+silently per turn — the agent loses memory of the conversation
+between sessions. With it pulled, graphiti round-trips
+embeddings against the same Ollama endpoint as the LLM, and
+warm-context retrieval works end-to-end on the local stack.
+
+If you'd rather use a different embedding model (e.g.
+`mxbai-embed-large` for higher recall at higher disk cost), pull
+that and set `GRAPHITI_EMBEDDER_MODEL=<slug>` to override the
+local default.
+
+### Community rebuild stays on sync tier
+
+`graphiti_config.community_rebuild_use_flex_tier=True` (the default)
+is treated as a *request*, not a guarantee. OpenAI's flex tier only
+delivers the ~50% discount through OpenRouter's pass-through to
+OpenAI / Google upstreams, so on local + Anthropic transports the
+flex client is silently swapped for the regular `OpenAIClient`
+(logged at INFO). The weekly community rebuild still runs — at full
+sync price, which on local Ollama is `$0`.
+
+### Subscription mode caveat
+
+If you also use Claude Code subscription (`CHAT_USE_CLAUDE_CODE_SUBSCRIPTION=true`)
+for the chat path, the dream pass needs a separate `ANTHROPIC_API_KEY`
+set in the environment. The Claude Code OAuth token authenticates the
+chat CLI only; per Anthropic's Feb-2026 ToS update, OAuth tokens
+**cannot** call the Messages API directly. Without `ANTHROPIC_API_KEY`,
+the dream pass writes an `errored` JobStatus with a friendly hint
+pointing you at this section.
+
+A separate Anthropic Agent-SDK credit pool launches **2026-06-15**
+($20 Pro / $100 Max-5x / $200 Max-20x at standard API rates,
+one-time opt-in). Once that lands, subscription users will have
+the option of routing the dream pass through the Agent SDK instead
+of the Messages API — coverage tracked as a post-Jun-15 follow-up.