topos-node 0.1.0__py3-none-any.whl

topos/api/local_mcp.py

@@ -0,0 +1,46 @@
+"""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("/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/api/messenger_analytics.py

@@ -0,0 +1,385 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Sequence
+
+from fastapi import APIRouter, Depends, Query
+
+from ..analytics.messenger_communities import (
+    MESSENGER_COMMUNITIES_TABLE,
+    MESSENGER_PARTICIPANT_IMPORTANCE_TABLE,
+    MESSENGER_SOCIAL_EDGES_TABLE,
+    compute_and_persist_messenger_analytics,
+    ensure_messenger_analytics_tables,
+)
+from ..analytics.messenger_graph import extract_messenger_graph
+from ..analytics.messenger_labels import resolve_participant_labels
+from ..auth import require_api_key
+from ..core.state import get_db_connection
+
+router = APIRouter()
+
+
+def _normalize_source_filter(
+    source_id: Optional[str],
+    source_ids: Optional[str],
+) -> List[str]:
+    out: List[str] = []
+    if source_id and source_id.strip():
+        out.append(source_id.strip())
+    if source_ids:
+        for value in source_ids.split(","):
+            if value.strip():
+                out.append(value.strip())
+    return sorted(set(out))
+
+
+def _source_scope(source_filter: Sequence[str]) -> str:
+    if not source_filter:
+        return "all"
+    return ",".join(sorted(set(source_filter)))
+
+
+def _rows_to_dicts(rows: Sequence[Any]) -> List[Dict[str, Any]]:
+    out: List[Dict[str, Any]] = []
+    for row in rows:
+        if hasattr(row, "keys"):
+            out.append({k: row[k] for k in row.keys()})
+        else:
+            out.append(dict(row))
+    return out
+
+
+@router.get("/messenger-analytics/recompute", dependencies=[Depends(require_api_key)])
+async def recompute_messenger_analytics_get_alias() -> Dict[str, Any]:
+    """Method helper for users accidentally using GET on recompute."""
+    return {"status": "error", "error": "Use POST /v1/messenger-analytics/recompute"}
+
+
+@router.post("/messenger-analytics/recompute", dependencies=[Depends(require_api_key)])
+async def recompute_messenger_analytics(
+    dataset_id: str = Query(...),
+    period_granularity: str = Query("month"),
+    source_id: Optional[str] = Query(None),
+    source_ids: Optional[str] = Query(None),
+    start_ts: Optional[str] = Query(None),
+    end_ts: Optional[str] = Query(None),
+    cumulative: bool = Query(False),
+) -> Dict[str, Any]:
+    conn = get_db_connection()
+    if not conn:
+        return {"status": "error", "error": "Database not available"}
+    source_filter = _normalize_source_filter(source_id, source_ids)
+    result = compute_and_persist_messenger_analytics(
+        dataset_id=dataset_id,
+        conn=conn,
+        start_ts=start_ts,
+        end_ts=end_ts,
+        source_ids=source_filter or None,
+        period_granularity=period_granularity,
+        cumulative=cumulative,
+    )
+    return {"status": "ok", **result}
+
+
+def _maybe_compute_if_missing(
+    *,
+    conn: Any,
+    dataset_id: str,
+    period_key: str,
+    source_filter: Sequence[str],
+    ensure_data: bool,
+) -> None:
+    if not ensure_data:
+        return
+    source_scope = _source_scope(source_filter)
+    row = conn.execute(
+        f"""
+        SELECT 1
+        FROM {MESSENGER_PARTICIPANT_IMPORTANCE_TABLE}
+        WHERE dataset_id = ? AND period_key = ? AND source_scope = ?
+        LIMIT 1
+        """,
+        (dataset_id, period_key, source_scope),
+    ).fetchone()
+    if row:
+        return
+    compute_and_persist_messenger_analytics(
+        dataset_id=dataset_id,
+        conn=conn,
+        source_ids=source_filter or None,
+        period_granularity="month",
+    )
+
+
+@router.get("/messenger-analytics/graph", dependencies=[Depends(require_api_key)])
+async def get_messenger_graph(
+    dataset_id: str = Query(...),
+    period: str = Query(...),
+    source_id: Optional[str] = Query(None),
+    source_ids: Optional[str] = Query(None),
+    ensure_data: bool = Query(True),
+) -> Dict[str, Any]:
+    conn = get_db_connection()
+    if not conn:
+        return {"status": "error", "error": "Database not available"}
+    ensure_messenger_analytics_tables(conn)
+    source_filter = _normalize_source_filter(source_id, source_ids)
+    _maybe_compute_if_missing(
+        conn=conn,
+        dataset_id=dataset_id,
+        period_key=period,
+        source_filter=source_filter,
+        ensure_data=ensure_data,
+    )
+    source_scope = _source_scope(source_filter)
+    rows = _rows_to_dicts(
+        conn.execute(
+            f"""
+            SELECT source_id, target_id, weight, edge_type, edge_type_counts_json
+            FROM {MESSENGER_SOCIAL_EDGES_TABLE}
+            WHERE dataset_id = ? AND period_key = ? AND source_scope = ?
+            ORDER BY source_id, target_id
+            """,
+            (dataset_id, period, source_scope),
+        ).fetchall()
+    )
+    nodes = _rows_to_dicts(
+        conn.execute(
+            f"""
+            SELECT i.participant_id, i.centrality_degree, c.community_id
+            FROM {MESSENGER_PARTICIPANT_IMPORTANCE_TABLE} i
+            LEFT JOIN {MESSENGER_COMMUNITIES_TABLE} c
+              ON c.dataset_id = i.dataset_id
+             AND c.period_key = i.period_key
+             AND c.source_scope = i.source_scope
+             AND c.participant_id = i.participant_id
+            WHERE i.dataset_id = ? AND i.period_key = ? AND i.source_scope = ?
+            ORDER BY i.centrality_degree DESC, i.participant_id
+            """,
+            (dataset_id, period, source_scope),
+        ).fetchall()
+    )
+    labels_by_participant = resolve_participant_labels(
+        conn,
+        dataset_id=dataset_id,
+        participant_ids=[str(row["participant_id"]) for row in nodes if row.get("participant_id")],
+    )
+    graph_nodes = [
+        {
+            "id": row["participant_id"],
+            "label": labels_by_participant.get(str(row["participant_id"]), {}).get("label", row["participant_id"]),
+            "display_name": labels_by_participant.get(str(row["participant_id"]), {}).get("display_name"),
+            "identifier": labels_by_participant.get(str(row["participant_id"]), {}).get("identifier"),
+            "importance": float(row.get("centrality_degree") or 0.0),
+            "community_id": row.get("community_id"),
+        }
+        for row in nodes
+    ]
+    graph_edges = []
+    for row in rows:
+        counts_raw = row.get("edge_type_counts_json")
+        counts = {}
+        if counts_raw:
+            try:
+                import json
+
+                counts = json.loads(counts_raw)
+            except Exception:
+                counts = {}
+        graph_edges.append(
+            {
+                "source": row["source_id"],
+                "target": row["target_id"],
+                "weight": float(row.get("weight") or 0.0),
+                "edge_type": row.get("edge_type"),
+                "edge_type_counts": counts,
+            }
+        )
+    return {
+        "status": "ok",
+        "dataset_id": dataset_id,
+        "period": period,
+        "source_scope": source_scope,
+        "nodes": graph_nodes,
+        "edges": graph_edges,
+    }
+
+
+@router.get("/messenger-analytics/importance", dependencies=[Depends(require_api_key)])
+async def get_messenger_importance(
+    dataset_id: str = Query(...),
+    period: str = Query(...),
+    source_id: Optional[str] = Query(None),
+    source_ids: Optional[str] = Query(None),
+    ensure_data: bool = Query(True),
+) -> Dict[str, Any]:
+    conn = get_db_connection()
+    if not conn:
+        return {"status": "error", "error": "Database not available"}
+    ensure_messenger_analytics_tables(conn)
+    source_filter = _normalize_source_filter(source_id, source_ids)
+    _maybe_compute_if_missing(
+        conn=conn,
+        dataset_id=dataset_id,
+        period_key=period,
+        source_filter=source_filter,
+        ensure_data=ensure_data,
+    )
+    source_scope = _source_scope(source_filter)
+    rows = _rows_to_dicts(
+        conn.execute(
+            f"""
+            SELECT participant_id, centrality_degree, centrality_betweenness
+            FROM {MESSENGER_PARTICIPANT_IMPORTANCE_TABLE}
+            WHERE dataset_id = ? AND period_key = ? AND source_scope = ?
+            ORDER BY centrality_degree DESC, centrality_betweenness DESC
+            """,
+            (dataset_id, period, source_scope),
+        ).fetchall()
+    )
+    labels_by_participant = resolve_participant_labels(
+        conn,
+        dataset_id=dataset_id,
+        participant_ids=[str(row["participant_id"]) for row in rows if row.get("participant_id")],
+    )
+    importance = []
+    for row in rows:
+        participant_id = str(row["participant_id"])
+        labels = labels_by_participant.get(participant_id, {})
+        importance.append(
+            {
+                **row,
+                "participant_label": labels.get("label", participant_id),
+                "participant_display_name": labels.get("display_name"),
+                "participant_identifier": labels.get("identifier"),
+            }
+        )
+    return {
+        "status": "ok",
+        "dataset_id": dataset_id,
+        "period": period,
+        "source_scope": source_scope,
+        "importance": importance,
+    }
+
+
+@router.get("/messenger-analytics/communities", dependencies=[Depends(require_api_key)])
+async def get_messenger_communities(
+    dataset_id: str = Query(...),
+    period: str = Query(...),
+    source_id: Optional[str] = Query(None),
+    source_ids: Optional[str] = Query(None),
+    ensure_data: bool = Query(True),
+) -> Dict[str, Any]:
+    conn = get_db_connection()
+    if not conn:
+        return {"status": "error", "error": "Database not available"}
+    ensure_messenger_analytics_tables(conn)
+    source_filter = _normalize_source_filter(source_id, source_ids)
+    _maybe_compute_if_missing(
+        conn=conn,
+        dataset_id=dataset_id,
+        period_key=period,
+        source_filter=source_filter,
+        ensure_data=ensure_data,
+    )
+    source_scope = _source_scope(source_filter)
+    rows = _rows_to_dicts(
+        conn.execute(
+            f"""
+            SELECT participant_id, community_id
+            FROM {MESSENGER_COMMUNITIES_TABLE}
+            WHERE dataset_id = ? AND period_key = ? AND source_scope = ?
+            ORDER BY community_id, participant_id
+            """,
+            (dataset_id, period, source_scope),
+        ).fetchall()
+    )
+    participant_ids = [str(row["participant_id"]) for row in rows if row.get("participant_id")]
+    labels_by_participant = resolve_participant_labels(
+        conn,
+        dataset_id=dataset_id,
+        participant_ids=participant_ids,
+    )
+    grouped: Dict[int, List[str]] = {}
+    for row in rows:
+        community_id = int(row["community_id"])
+        grouped.setdefault(community_id, []).append(row["participant_id"])
+    communities = [
+        {
+            "community_id": cid,
+            "participants": participants,
+            "participants_labeled": [
+                {
+                    "id": pid,
+                    "label": labels_by_participant.get(str(pid), {}).get("label", pid),
+                }
+                for pid in participants
+            ],
+        }
+        for cid, participants in sorted(grouped.items(), key=lambda item: item[0])
+    ]
+    return {
+        "status": "ok",
+        "dataset_id": dataset_id,
+        "period": period,
+        "source_scope": source_scope,
+        "communities": communities,
+    }
+
+
+@router.get("/messenger-analytics/periods", dependencies=[Depends(require_api_key)])
+async def get_messenger_periods(
+    dataset_id: str = Query(...),
+    source_id: Optional[str] = Query(None),
+    source_ids: Optional[str] = Query(None),
+    include_empty: bool = Query(False),
+) -> Dict[str, Any]:
+    conn = get_db_connection()
+    if not conn:
+        return {"status": "error", "error": "Database not available"}
+    ensure_messenger_analytics_tables(conn)
+    source_filter = _normalize_source_filter(source_id, source_ids)
+    source_scope = _source_scope(source_filter)
+    rows = _rows_to_dicts(
+        conn.execute(
+            f"""
+            SELECT DISTINCT period_key
+            FROM {MESSENGER_PARTICIPANT_IMPORTANCE_TABLE}
+            WHERE dataset_id = ? AND source_scope = ?
+            ORDER BY period_key
+            """,
+            (dataset_id, source_scope),
+        ).fetchall()
+    )
+    periods = [row["period_key"] for row in rows]
+    if include_empty or periods:
+        return {"status": "ok", "dataset_id": dataset_id, "source_scope": source_scope, "periods": periods}
+
+    extraction = extract_messenger_graph(
+        dataset_id=dataset_id,
+        conn=conn,
+        source_ids=source_filter or None,
+        period_granularity="month",
+    )
+    fallback_periods = [p["period_key"] for p in extraction.get("periods", [])]
+    return {"status": "ok", "dataset_id": dataset_id, "source_scope": source_scope, "periods": fallback_periods}
+
+
+@router.get("/messenger-analytics/sources", dependencies=[Depends(require_api_key)])
+async def get_messenger_sources(dataset_id: str = Query(...)) -> Dict[str, Any]:
+    conn = get_db_connection()
+    if not conn:
+        return {"status": "error", "error": "Database not available"}
+    rows = _rows_to_dicts(
+        conn.execute(
+            """
+            SELECT DISTINCT source_id
+            FROM conversation_messages
+            WHERE dataset_id = ?
+            ORDER BY source_id
+            """,
+            (dataset_id,),
+        ).fetchall()
+    )
+    return {"status": "ok", "dataset_id": dataset_id, "sources": [r["source_id"] for r in rows]}

topos/api/query_api.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from ..analytics.duckdb_adapter import DuckDBAdapter
+
+router = APIRouter()
+
+
+@router.post("/query")
+async def run_query() -> dict:
+    _ = DuckDBAdapter
+    return {"status": "stub"}

topos/api/sanitization_ollama_config.py

@@ -0,0 +1,64 @@
+"""Read/update device-local Ollama sanitization overrides (engine_config JSON)."""
+
+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.sanitization_ollama import (
+    ENGINE_CONFIG_KEY_SANITIZATION_OLLAMA_DEVICE,
+    effective_config_for_api,
+    normalize_put_device_overrides,
+)
+from ..config.settings import settings
+from ..core.state import get_db_connection, set_engine_config_value
+
+logger = logging.getLogger("topos.api.sanitization_ollama_config")
+
+router = APIRouter(tags=["sanitization-ollama"])
+
+
+@router.get("/v1/sanitization-ollama-config", dependencies=[Depends(require_api_key)])
+async def get_sanitization_ollama_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_sanitization_ollama_config failed: %s", exc)
+        raise HTTPException(status_code=500, detail="Failed to read config") from exc
+
+
+@router.put("/v1/sanitization-ollama-config", dependencies=[Depends(require_api_key)])
+async def put_sanitization_ollama_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:
+        payload = body or {}
+        json_str = normalize_put_device_overrides(payload)
+        set_engine_config_value(conn, ENGINE_CONFIG_KEY_SANITIZATION_OLLAMA_DEVICE, json_str)
+        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_sanitization_ollama_config failed: %s", exc)
+        raise HTTPException(status_code=500, detail="Failed to save config") from exc
+
+
+@router.delete("/v1/sanitization-ollama-config", dependencies=[Depends(require_api_key)])
+async def delete_sanitization_ollama_device_overrides() -> dict[str, Any]:
+    """Clear device overrides; effective config reverts to Settings / env only."""
+    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_SANITIZATION_OLLAMA_DEVICE, "{}")
+        return {"status": "ok", **effective_config_for_api(settings, conn)}
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("delete sanitization_ollama overrides failed: %s", exc)
+        raise HTTPException(status_code=500, detail="Failed to clear config") from exc