topos-node 1.2.7__tar.gz → 1.3.1__tar.gz

{topos_node-1.2.7/topos_node.egg-info → topos_node-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topos-node
-Version: 1.2.7
+Version: 1.3.1
 Summary: Topos personal AI engine (FastAPI): local data, sync, control plane WebSocket client
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://topos.dialogues.ai

{topos_node-1.2.7 → topos_node-1.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "topos-node"
-version = "1.2.7"
+version = "1.3.1"
 description = "Topos personal AI engine (FastAPI): local data, sync, control plane WebSocket client"
 readme = "README.md"
 license = "Apache-2.0"
@@ -84,6 +84,12 @@ where = ["."]
 include = ["topos*", "shared*"]
 
 [tool.pytest.ini_options]
+# tmp_path hygiene: this suite's fixtures build whole node DBs (100s of MB per
+# run). Keep only the last run's FAILED dirs — passed dirs are removed as tests
+# finish, so tmp never accumulates across runs. Killed runs can still leave
+# locked roots behind; topos.runtime_housekeeping sweeps those on node start.
+tmp_path_retention_count = 1
+tmp_path_retention_policy = "failed"
 filterwarnings = [
   "ignore::DeprecationWarning:pydantic.*",
   "ignore:on_event is deprecated.*:DeprecationWarning:fastapi.*",
@@ -106,5 +112,5 @@ markers = [
   "eval_nightly: statistical privacy eval (attacker advantage, minimality, latency); nightly",
   "eval_release: release-tier privacy eval (negotiation A/B, Pareto); run per release",
 ]
-pythonpath = ["tests/gap/p3/engine", "tests/gap/p4/engine", "tests/gap/qq/engine", "tests/acceptance/wiki_mvp"]
+pythonpath = ["tests/gap/p3/engine", "tests/gap/p4/engine", "tests/gap/qq/engine", "tests/acceptance/wiki_mvp", "tests/evals/time_signal"]
 testpaths = ["tests"]

{topos_node-1.2.7 → topos_node-1.3.1}/topos/__version__.py

@@ -1,6 +1,6 @@
 """Topos Control Plane Version Information."""
 
-__version__ = "1.2.7"
-__version_info__ = (1, 2, 7)
+__version__ = "1.3.1"
+__version_info__ = (1, 3, 1)
 
 __all__ = ["__version__", "__version_info__"]

topos_node-1.3.1/topos/api/conversation_context.py

@@ -0,0 +1,142 @@
+"""Owner-set conversation context tag (work | personal).
+
+Second labeling axis alongside source posture: posture says whose words the
+content is; context_tag says which life domain the thread belongs to. Set at
+the conversation level (the thread in `conversations`); every message in the
+thread inherits it at read/derivation time. Owner-only; never inferred here.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Body, Depends, HTTPException
+
+from ..auth import require_api_key
+from ..core.state import get_db_connection
+from ..storage.db.migrations.conversation_context_v1 import CONTEXT_TAG_VALUES
+
+router = APIRouter()
+
+
+def _conversation_row(conn, conversation_id: str, dataset_id: str):
+    return conn.execute(
+        "SELECT conversation_id, dataset_id, context_tag, context_tag_source "
+        "FROM conversations WHERE conversation_id=? AND dataset_id=?",
+        (conversation_id, dataset_id),
+    ).fetchone()
+
+
+def read_conversation_context(conn, conversation_id: str, dataset_id: str) -> dict | None:
+    """Context-tag payload for a conversation, or None when it is unknown.
+
+    Shared by the HTTP endpoint below and the WS handler
+    (core.handlers.config get_conversation_context) so both stay one source.
+    """
+    row = _conversation_row(conn, conversation_id, dataset_id)
+    if row is None:
+        return None
+    return {
+        "status": "ok",
+        "conversation_id": row[0],
+        "dataset_id": row[1],
+        "context_tag": row[2],
+        "context_tag_source": row[3],
+    }
+
+
+def write_conversation_context(conn, conversation_id: str, dataset_id: str, raw_tag) -> dict:
+    """Owner set/clear of the context tag.
+
+    Raises ValueError on an invalid tag, LookupError when the conversation is
+    unknown. Shared by the HTTP endpoint and the WS handler.
+    """
+    tag = str(raw_tag).strip().lower() if raw_tag is not None else None
+    if tag is not None and tag not in CONTEXT_TAG_VALUES:
+        raise ValueError(f"context_tag must be one of {sorted(CONTEXT_TAG_VALUES)} or null")
+    if _conversation_row(conn, conversation_id, dataset_id) is None:
+        raise LookupError("Unknown conversation")
+    # Owner decisions always win: stamped 'owner' even when clearing, so the
+    # auto-classifier never refills a conversation the owner chose to untag.
+    conn.execute(
+        "UPDATE conversations SET context_tag=?, context_tag_source='owner', "
+        "updated_at=datetime('now') WHERE conversation_id=? AND dataset_id=?",
+        (tag, conversation_id, dataset_id),
+    )
+    conn.commit()
+    return {
+        "status": "ok",
+        "conversation_id": conversation_id,
+        "dataset_id": dataset_id,
+        "context_tag": tag,
+        "context_tag_source": "owner",
+    }
+
+
+@router.get(
+    "/conversations/{conversation_id}/context",
+    dependencies=[Depends(require_api_key)],
+)
+async def get_conversation_context(conversation_id: str, dataset_id: str) -> dict:
+    conn = get_db_connection()
+    if conn is None:
+        raise HTTPException(status_code=503, detail="Database not available")
+    data = read_conversation_context(conn, conversation_id, dataset_id)
+    if data is None:
+        raise HTTPException(status_code=404, detail="Unknown conversation")
+    return data
+
+
+@router.put(
+    "/conversations/{conversation_id}/context",
+    dependencies=[Depends(require_api_key)],
+)
+async def set_conversation_context(
+    conversation_id: str,
+    payload: dict = Body(default_factory=dict),
+) -> dict:
+    dataset_id = str(payload.get("dataset_id") or "").strip()
+    if not dataset_id:
+        raise HTTPException(status_code=422, detail="dataset_id is required")
+    conn = get_db_connection()
+    if conn is None:
+        raise HTTPException(status_code=503, detail="Database not available")
+    try:
+        return write_conversation_context(conn, conversation_id, dataset_id, payload.get("context_tag"))
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    except LookupError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+
+
+# --- classifier model config (settings surface) -----------------------------------
+
+
+@router.get("/conversation-context-llm-config", dependencies=[Depends(require_api_key)])
+async def get_context_llm_config() -> dict:
+    from ..config.conversation_context_llm import effective_config_for_api
+    from ..config.settings import settings
+
+    conn = get_db_connection()
+    if conn is None:
+        raise HTTPException(status_code=503, detail="Database not available")
+    return {"status": "ok", **effective_config_for_api(settings, conn)}
+
+
+@router.put("/conversation-context-llm-config", dependencies=[Depends(require_api_key)])
+async def put_context_llm_config(payload: dict = Body(default=None)) -> dict:
+    from ..config.conversation_context_llm import (
+        ENGINE_CONFIG_KEY_CONVERSATION_CONTEXT_LLM_MODEL,
+        effective_config_for_api,
+        normalize_put_model,
+    )
+    from ..config.settings import settings
+    from ..core.state import set_engine_config_value
+
+    conn = get_db_connection()
+    if conn is None:
+        raise HTTPException(status_code=503, detail="Database not available")
+    try:
+        model = normalize_put_model(payload)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    set_engine_config_value(conn, ENGINE_CONFIG_KEY_CONVERSATION_CONTEXT_LLM_MODEL, model)
+    return {"status": "ok", **effective_config_for_api(settings, conn)}

topos_node-1.3.1/topos/api/facts_llm_config.py

@@ -0,0 +1,63 @@
+"""Read/update the owner-selected facts-LLM extraction model (engine_config)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import APIRouter, Body, Depends, HTTPException
+
+from ..auth import require_api_key
+from ..config.facts_llm import (
+    ENGINE_CONFIG_KEY_FACTS_LLM_MODEL,
+    effective_config_for_api,
+    normalize_put_model,
+)
+from ..config.settings import settings
+from ..core.state import get_db_connection, set_engine_config_value
+
+logger = logging.getLogger("topos.api.facts_llm_config")
+
+router = APIRouter(tags=["facts-llm"])
+
+
+@router.get("/v1/facts-llm-config", dependencies=[Depends(require_api_key)])
+async def get_facts_llm_config() -> dict[str, Any]:
+    conn = get_db_connection()
+    if not conn:
+        raise HTTPException(status_code=503, detail="Database not available")
+    try:
+        return {"status": "ok", **effective_config_for_api(settings, conn)}
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("get_facts_llm_config failed: %s", exc)
+        raise HTTPException(status_code=500, detail="Failed to read config") from exc
+
+
+@router.put("/v1/facts-llm-config", dependencies=[Depends(require_api_key)])
+async def put_facts_llm_config(body: dict[str, Any] = Body(default=None)) -> dict[str, Any]:
+    conn = get_db_connection()
+    if not conn:
+        raise HTTPException(status_code=503, detail="Database not available")
+    try:
+        model = normalize_put_model(body)
+        set_engine_config_value(conn, ENGINE_CONFIG_KEY_FACTS_LLM_MODEL, model)
+        return {"status": "ok", **effective_config_for_api(settings, conn)}
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("put_facts_llm_config failed: %s", exc)
+        raise HTTPException(status_code=500, detail="Failed to save config") from exc
+
+
+@router.delete("/v1/facts-llm-config", dependencies=[Depends(require_api_key)])
+async def delete_facts_llm_model_override() -> dict[str, Any]:
+    """Clear the device override; the effective model reverts to env defaults."""
+    conn = get_db_connection()
+    if not conn:
+        raise HTTPException(status_code=503, detail="Database not available")
+    try:
+        set_engine_config_value(conn, ENGINE_CONFIG_KEY_FACTS_LLM_MODEL, "")
+        return {"status": "ok", **effective_config_for_api(settings, conn)}
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("delete facts_llm model override failed: %s", exc)
+        raise HTTPException(status_code=500, detail="Failed to clear config") from exc

topos_node-1.3.1/topos/api/local_mcp.py

@@ -0,0 +1,119 @@
+"""Local API for MCP-style tools (no Control Plane). Same auth as engine; for same-device/offline use."""
+
+from __future__ import annotations
+
+import uuid
+
+from fastapi import APIRouter, Body, Depends
+
+from ..auth import require_api_key
+from ..core.handlers import handle_control_plane_request
+
+router = APIRouter(prefix="/api/local", tags=["local-mcp"])
+
+
+def _local_mcp_payload(extra: dict | None = None) -> dict:
+    """Payload for local MCP requests; source=claude_desktop so engine counts per source."""
+    p = {"mcp_source": "claude_desktop"}
+    if extra:
+        p.update(extra)
+    return p
+
+
+@router.post("/list_database_tables")
+async def local_list_database_tables(_: None = Depends(require_api_key)) -> dict:  # noqa: B008
+    """List tables (same as CP-forwarded tool). Requires Bearer TOPOS_KEY."""
+    msg = {"id": str(uuid.uuid4()), "type": "list_database_tables", "payload": _local_mcp_payload()}
+    out = await handle_control_plane_request(msg)
+    if out.get("status") == "error":
+        return {"status": "error", "error": out.get("error", "unknown")}
+    return out.get("payload", {})
+
+
+@router.post("/verify_claim")
+async def local_verify_claim(
+    body: dict = Body(default_factory=dict),
+    _: None = Depends(require_api_key),  # noqa: B008
+) -> dict:
+    """Same-device truth check (PLAN_TRUTHFULNESS_PLUGIN.md). Owner-key only;
+    mirrors the CP door: `app_id` is mandatory and `mode` is pinned to fun —
+    this route cannot reach a mode the registry doesn't ship. Body:
+    {"statement": "...", "app_id": "truth-mirror"}."""
+    statement = str(body.get("statement") or "").strip()
+    app_id = str(body.get("app_id") or "").strip()
+    if not statement or not app_id:
+        return {"status": "error", "error": "statement and app_id required"}
+    msg = {
+        "id": str(uuid.uuid4()),
+        "type": "verify_claim",
+        "payload": {"statement": statement, "mode": "fun", "caller_app_id": app_id},
+    }
+    out = await handle_control_plane_request(msg)
+    if out.get("status") == "error":
+        return {"status": "error", "error": out.get("error", "unknown")}
+    return out.get("payload", {})
+
+
+@router.post("/truth_prompts")
+async def local_truth_prompts(
+    body: dict = Body(default_factory=dict),
+    _: None = Depends(require_api_key),  # noqa: B008
+) -> dict:
+    """Same-device "ask me" prompt seeds (fun aperture; topics only, no
+    stances). Body: {"app_id": "truth-mirror", "limit": 5}."""
+    app_id = str(body.get("app_id") or "").strip()
+    if not app_id:
+        return {"status": "error", "error": "app_id required"}
+    msg = {
+        "id": str(uuid.uuid4()),
+        "type": "truth_prompts",
+        "payload": {"mode": "fun", "caller_app_id": app_id,
+                    "limit": int(body.get("limit") or 5)},
+    }
+    out = await handle_control_plane_request(msg)
+    if out.get("status") == "error":
+        return {"status": "error", "error": out.get("error", "unknown")}
+    return out.get("payload", {})
+
+
+@router.post("/truth_seed_fact")
+async def local_truth_seed_fact(
+    body: dict = Body(default_factory=dict),
+    _: None = Depends(require_api_key),  # noqa: B008
+) -> dict:
+    """Owner adds a fun fact to their own sheet (refused outside the fun
+    aperture). Body: {"predicate": "favorite_food", "value": "tacos",
+    "app_id": "truth-mirror"}."""
+    app_id = str(body.get("app_id") or "").strip()
+    if not app_id:
+        return {"status": "error", "error": "app_id required"}
+    msg = {
+        "id": str(uuid.uuid4()),
+        "type": "truth_seed_fact",
+        "payload": {
+            "mode": "fun",
+            "caller_app_id": app_id,
+            "predicate": str(body.get("predicate") or ""),
+            "value": str(body.get("value") or ""),
+        },
+    }
+    out = await handle_control_plane_request(msg)
+    if out.get("status") == "error":
+        return {"status": "error", "error": out.get("error", "unknown")}
+    return out.get("payload", {})
+
+
+@router.post("/get_table_schema")
+async def local_get_table_schema(
+    body: dict = Body(default_factory=dict),
+    _: None = Depends(require_api_key),  # noqa: B008
+) -> dict:
+    """Get table schema (same as CP-forwarded tool). Body: {"table_name": "..."}. Requires Bearer TOPOS_KEY."""
+    table_name = (body.get("table_name") or "").strip()
+    if not table_name:
+        return {"status": "error", "error": "table_name required"}
+    msg = {"id": str(uuid.uuid4()), "type": "get_table_schema", "payload": _local_mcp_payload({"table_name": table_name})}
+    out = await handle_control_plane_request(msg)
+    if out.get("status") == "error":
+        return {"status": "error", "error": out.get("error", "unknown")}
+    return out.get("payload", {})

{topos_node-1.2.7 → topos_node-1.3.1}/topos/api/signal.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import logging
 from typing import Any, Dict, Optional
 
-from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi import APIRouter, Body, Depends, HTTPException, Query
 from pydantic import BaseModel, Field
 
 from ..auth import require_api_key
@@ -480,6 +480,34 @@ async def list_facts(
     )
 
 
+@router.post("/facts/verdict")
+async def post_fact_verdict(
+    object_id: str = Body(...),
+    action: str = Body(..., description="confirm | reject | edit"),
+    object_value: Optional[str] = Body(default=None),
+    asserted_by: Optional[str] = Body(default=None),
+    note: Optional[str] = Body(default=None),
+    _api_key: str = Depends(require_api_key),
+):
+    """Owner verdict on one fact: confirm (attest true), reject (close +
+    tombstone this value), or edit (correct the value and/or attribution)."""
+    from ..features.facts.verdicts import apply_fact_verdict
+
+    try:
+        return apply_fact_verdict(
+            _entities_conn(),
+            object_id=object_id,
+            action=action,
+            object_value=object_value,
+            asserted_by=asserted_by,
+            note=note,
+        )
+    except LookupError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
 @router.get("/insights")
 async def list_stat_insights(
     dimension: Optional[str] = Query(default=None, max_length=40),
@@ -623,3 +651,21 @@ async def refresh_dimension_brief(
         return await service.refresh_brief(dimension, limit=limit)
     except ValueError as exc:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+# --------------------------------------------------------------- attention triage
+
+@router.get("/attention/dashboard")
+async def attention_dashboard(
+    _api_key: str = Depends(require_api_key),
+    days: int = Query(14, ge=1, le=90),
+    include_titles: bool = Query(True),
+):
+    """Data spine for the /data/attention tab (PLAN_ATTENTION_ANALYTICS_EXECUTION WS5.1)."""
+    from ..core.state import get_db_connection
+    from ..features.triage.dashboard import attention_dashboard_data
+
+    conn = get_db_connection()
+    if conn is None:
+        raise HTTPException(status_code=503, detail="database unavailable")
+    return attention_dashboard_data(conn, days=days, include_titles=include_titles)

{topos_node-1.2.7 → topos_node-1.3.1}/topos/app.py

@@ -5,6 +5,7 @@ import importlib.util
 import logging
 import os
 import sys
+import threading
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
@@ -15,6 +16,7 @@ from .api import (
     app_registry as app_registry_routes,
     backup as backup_routes,
     compute_remote as compute_remote_routes,
+    conversation_context as conversation_context_routes,
     engine_run as engine_run_routes,
     data_commit as data_commit_routes,
     db as db_routes,
@@ -39,6 +41,7 @@ from .api import (
     ui_config as ui_config_routes,
     data_explorer_table_prefs as data_explorer_table_prefs_routes,
     sanitization_ollama_config as sanitization_ollama_config_routes,
+    facts_llm_config as facts_llm_config_routes,
     signal_extraction_config as signal_extraction_config_routes,
     filter_lab as filter_lab_routes,
     enrichment_lab as enrichment_lab_routes,
@@ -106,6 +109,7 @@ app.include_router(device_routes.router)
 app.include_router(backup_routes.router)
 app.include_router(analytics_routes.router)
 app.include_router(sources_routes.router)
+app.include_router(conversation_context_routes.router, prefix="/v1")
 app.include_router(source_install_routes.router, prefix="/v1")
 app.include_router(source_scrub_routes.router, prefix="/v1")
 app.include_router(intelligence_lifecycle_routes.router, prefix="/v1")
@@ -123,6 +127,7 @@ app.include_router(ui_config_routes.router)
 app.include_router(data_explorer_table_prefs_routes.router)
 app.include_router(user_identity_routes.router)
 app.include_router(sanitization_ollama_config_routes.router)
+app.include_router(facts_llm_config_routes.router)
 app.include_router(signal_extraction_config_routes.router)
 app.include_router(filter_lab_routes.router)
 app.include_router(enrichment_lab_routes.router)
@@ -167,19 +172,9 @@ async def startup_event() -> None:
                 logger.info("Stage 9 migrations applied at startup: %d renames", len(result["applied"]))
     except Exception as e:
         logger.debug("Stage 9 migrations at startup (non-fatal): %s", e)
-    # Upgrade runner: compare the stamped derivation baseline against the
-    # shipped version and re-derive what this release invalidated (manifest in
-    # topos/upgrades). Heavy steps run in a daemon thread; the node serves
-    # stale derived data meanwhile. Fresh installs stamp-and-skip.
-    try:
-        from .core.state import get_db_connection as _get_conn_for_upgrades
-        from .upgrades.runner import start_background as _start_upgrades
-
-        _upgrade_conn = state.db_conn if state.db_conn is not None else _get_conn_for_upgrades()
-        if _upgrade_conn is not None:
-            _start_upgrades(_upgrade_conn)
-    except Exception as e:
-        logger.warning("Upgrade runner at startup failed (non-fatal): %s", e)
+    # Upgrade runner is armed later — after control-plane / local readiness —
+    # so the React UI can fetch bootstrap data before enrichment reprocess
+    # contends for SQLite / Ollama / MPS. See _arm_upgrade_runner below.
     try:
         from .core.state import get_db_connection as _get_conn_for_pipeline
         from .pipeline.job_runner import recover_pipeline_jobs, start_pipeline_worker
@@ -291,6 +286,41 @@ async def startup_event() -> None:
     start_runtime_update_monitor()
     start_update_hotkey_listener()
 
+    # Upgrade runner: plan/stamp cheaply, but defer heavy re-derivation until the
+    # UI can bootstrap (CP connected + grace). Fresh installs stamp-and-skip.
+    try:
+        from .core.state import get_db_connection as _get_conn_for_upgrades
+        from .upgrades.runner import (
+            ready_timeout_seconds as _upgrade_ready_timeout,
+            start_background as _start_upgrades,
+            ui_grace_seconds as _upgrade_ui_grace,
+        )
+
+        _upgrade_conn = state.db_conn if state.db_conn is not None else _get_conn_for_upgrades()
+        if _upgrade_conn is not None:
+            _upgrade_ready = threading.Event()
+            _start_upgrades(
+                _upgrade_conn,
+                ready_event=_upgrade_ready,
+                ui_grace_s=_upgrade_ui_grace(),
+                ready_timeout_s=_upgrade_ready_timeout(),
+            )
+
+            async def _signal_upgrade_ui_ready() -> None:
+                try:
+                    if state.control_plane_client is not None:
+                        await state.control_plane_client.wait_until_connected(
+                            timeout_s=_upgrade_ready_timeout()
+                        )
+                except Exception as ready_exc:  # noqa: BLE001
+                    logger.debug("Upgrade UI-ready wait ended: %s", ready_exc)
+                finally:
+                    _upgrade_ready.set()
+
+            asyncio.create_task(_signal_upgrade_ui_ready())
+    except Exception as e:
+        logger.warning("Upgrade runner at startup failed (non-fatal): %s", e)
+
     if settings.enable_sync and settings.topos_user_id:
         state.sync_client = SyncClient(
             sync_url=settings.get_sync_url(),

{topos_node-1.2.7 → topos_node-1.3.1}/topos/canonicalization/mappers/browser_activity_mapper.py

@@ -24,6 +24,7 @@ from __future__ import annotations
 import json
 from dataclasses import dataclass
 from typing import Any, Optional
+from urllib.parse import urlparse
 
 from ...ingestion.parsers.base import NormalizedRecord
 from .base import CanonicalMapper, CanonicalRecord, MappingMetadata
@@ -77,6 +78,13 @@ class BrowserActivityCanonicalMapper(CanonicalMapper):
             "schema": payload.get("schema") or payload.get("schema_id"),
         }
         hostname = payload.get("hostname")
+        if not hostname and payload.get("url"):
+            # BT6 (PLAN_ATTENTION_TRIAGE.md): some plugin batches send url
+            # without hostname; derive it so downstream vocab never goes empty.
+            try:
+                hostname = urlparse(str(payload.get("url"))).hostname
+            except ValueError:
+                hostname = None
         if hostname:
             metadata["hostname"] = hostname
 

{topos_node-1.2.7 → topos_node-1.3.1}/topos/cli/commands.py

@@ -230,6 +230,10 @@ def main(db_path, topos_key, set_topos_key, discover, port, host, skip_update_ch
         os.environ["TOPOS_DATABASE_PATH"] = db_path
         click.echo(f"Database path: {db_path}")
 
+    from topos.runtime_housekeeping import start_background_housekeeping
+
+    start_background_housekeeping()
+
     _emit_startup_banner(host=host, port=port)
     uvicorn.run(app, host=host, port=port, log_config=get_uvicorn_log_config())