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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topos-node
-Version: 1.2.7
+Version: 1.3.0
 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.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "topos-node"
-version = "1.2.7"
+version = "1.3.0"
 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.0}/topos/__version__.py

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

topos_node-1.3.0/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.0/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.0/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.0}/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.0}/topos/app.py

@@ -15,6 +15,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 +40,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 +108,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 +126,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)

{topos_node-1.2.7 → topos_node-1.3.0}/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.0}/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())
 

topos_node-1.3.0/topos/config/conversation_context_llm.py

@@ -0,0 +1,106 @@
+"""Conversation-context classifier model: env default + per-node device override.
+
+The owner picks which local model auto-categorizes new conversations as
+work/personal (features.signal.conversation_context). Resolution order, first
+non-empty wins — same contract as facts_llm:
+
+  1. engine_config["conversation_context_llm_model"] — device override the UI
+     writes; takes effect on the next enrichment batch, no restart needed.
+  2. Settings.ollama_extraction_model — the ingest-time extraction tier.
+  3. Settings.ollama_query_model — the floor tier.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger("topos.config.conversation_context_llm")
+
+ENGINE_CONFIG_KEY_CONVERSATION_CONTEXT_LLM_MODEL = "conversation_context_llm_model"
+
+_MAX_MODEL_NAME_LEN = 200
+
+
+def _read_engine_config_value(conn: Optional[sqlite3.Connection], key: str) -> Optional[str]:
+    if conn is None:
+        return None
+    try:
+        row = conn.execute("SELECT value FROM engine_config WHERE key = ?", (key,)).fetchone()
+        if not row:
+            return None
+        try:
+            return str(row["value"])  # sqlite3.Row
+        except (TypeError, IndexError, KeyError):
+            return str(row[0])
+    except Exception:  # noqa: BLE001 — missing table/row on fresh DB is not fatal
+        return None
+
+
+def device_context_llm_model(conn: Optional[sqlite3.Connection]) -> str:
+    raw = _read_engine_config_value(conn, ENGINE_CONFIG_KEY_CONVERSATION_CONTEXT_LLM_MODEL)
+    return str(raw or "").strip()
+
+
+def resolve_context_llm_model(settings: Any, conn: Optional[sqlite3.Connection] = None) -> str:
+    override = device_context_llm_model(conn)
+    if override:
+        return override
+    for attr in ("ollama_extraction_model", "ollama_query_model"):
+        value = str(getattr(settings, attr, "") or "").strip()
+        if value:
+            return value
+    return ""
+
+
+def normalize_put_model(payload: Any) -> str:
+    """{"model": "<name>"} or bare string → stored value; empty clears."""
+    if payload is None:
+        return ""
+    if isinstance(payload, str):
+        model = payload
+    elif isinstance(payload, dict):
+        model = payload.get("model") or ""
+    else:
+        raise ValueError("body must be a JSON object with a 'model' string")
+    model = str(model).strip()
+    if len(model) > _MAX_MODEL_NAME_LEN:
+        raise ValueError(f"model name too long (max {_MAX_MODEL_NAME_LEN} chars)")
+    if model and any(ch in model for ch in " \t\n\r"):
+        raise ValueError("model name must not contain whitespace")
+    return model
+
+
+def effective_config_for_api(settings: Any, conn: Optional[sqlite3.Connection]) -> Dict[str, Any]:
+    """Resolved classifier model + local model catalog for the settings picker."""
+    override = device_context_llm_model(conn)
+    effective = resolve_context_llm_model(settings, conn)
+    if override:
+        source = "device_override"
+    elif str(getattr(settings, "ollama_extraction_model", "") or "").strip():
+        source = "extraction_model_default"
+    else:
+        source = "query_model_fallback"
+
+    available = []
+    try:
+        from ..engine.backends.ollama import OllamaAdapter
+
+        adapter = OllamaAdapter()
+        for name in adapter.list_models():
+            available.append(
+                {
+                    "name": name,
+                    "supports_thinking": adapter.model_supports_thinking(name),
+                }
+            )
+    except Exception as exc:  # noqa: BLE001 — catalog is a nicety, never a failure
+        logger.debug("context_llm available-model probe failed: %s", exc)
+
+    return {
+        "model": effective,
+        "override": override or None,
+        "source": source,
+        "available_models": available,
+    }