batho 0.1.4__py3-none-any.whl

batho/bridge/http_api.py

@@ -0,0 +1,383 @@
+"""REST HTTP API for the Batho bridge, mountable into the dashboard server."""
+
+from __future__ import annotations
+
+import http.server
+import json
+import urllib.parse
+from pathlib import Path
+from typing import Any
+
+from batho.bridge.artifact_loader import (
+    ArtifactLoader,
+    ArtifactNotFoundError,
+    ArtifactParseError,
+    ChecksumMismatchError,
+)
+from batho.bridge.constants import DEFAULT_BRIDGE_HTTP_PORT, KNOWN_ARTIFACT_TYPES
+from batho.bridge.models import BridgeErrorResponse, BridgeResponse, IndexListResponse
+from batho.bridge.registry_client import ArtifactRegistryBridge
+from batho.utils.logging import get_logger
+
+LOGGER = get_logger(__name__, component="bridge")
+
+
+def _json_response(data: Any, status: int = 200) -> tuple[bytes, int, dict[str, str]]:
+    body = json.dumps(data, ensure_ascii=False, default=str).encode("utf-8")
+    headers = {
+        "Content-Type": "application/json; charset=utf-8",
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "GET, OPTIONS",
+        "Access-Control-Allow-Headers": "Content-Type",
+    }
+    return body, status, headers
+
+
+def _ok(data: Any, meta: dict[str, Any] | None = None) -> tuple[bytes, int, dict[str, str]]:
+    return _json_response(BridgeResponse(data=data, meta=meta or {}).model_dump(exclude_none=True))
+
+
+def _err(code: str, message: str, detail: Any = None, status: int = 400) -> tuple[bytes, int, dict[str, str]]:
+    payload = BridgeErrorResponse(
+        error={"code": code, "message": message, "detail": detail}
+    ).model_dump(exclude_none=True)
+    return _json_response(payload, status=status)
+
+
+class BridgeAPIHandler:
+    """HTTP request handler for bridge REST endpoints.
+
+    This is designed to be invoked from a ``DualRootHandler`` or standalone
+    server.  It does *not* subclass ``BaseHTTPRequestHandler``; instead it
+    exposes a ``dispatch(path, query)`` method that returns a response
+    triple ``(body_bytes, status, headers)``.
+    """
+
+    def __init__(self, ctn_dir: Path) -> None:
+        self.ctn_dir = ctn_dir.resolve()
+        self._bridge = ArtifactRegistryBridge(self.ctn_dir)
+        self._loader = ArtifactLoader(self.ctn_dir)
+
+    def dispatch(self, path: str, query: dict[str, list[str]]) -> tuple[bytes, int, dict[str, str]]:
+        """Dispatch a request to the appropriate handler."""
+        # Strip leading /api/v1/bridge/
+        prefix = "/api/v1/bridge/"
+        if not path.startswith(prefix):
+            return _err("invalid_path", f"Path must start with {prefix}", status=404)
+
+        route = path[len(prefix):].strip("/")
+        segments = [s for s in route.split("/") if s]
+
+        if not segments:
+            return _ok({"endpoints": [
+                "GET /indexes",
+                "GET /indexes/{index_id}",
+                "GET /artifacts?type=&index_id=&limit=",
+                "GET /artifacts/{artifact_type}?index_id=",
+                "GET /artifacts/content?path=",
+                "GET /stats",
+                "GET /patches",
+                "GET /patches/{operation_id}",
+                "GET /snapshots/diff?base=&new=",
+            ]})
+
+        if segments[0] == "indexes":
+            return self._handle_indexes(segments, query)
+        if segments[0] == "index-meta":
+            return self._handle_index_meta()
+        if segments[0] == "artifacts":
+            return self._handle_artifacts(segments, query)
+        if segments[0] == "stats":
+            return self._handle_stats()
+        if segments[0] == "patches":
+            return self._handle_patches(segments, query)
+        if segments[0] == "snapshots" and len(segments) >= 2 and segments[1] == "diff":
+            return self._handle_snapshot_diff(query)
+
+        return _err("unknown_endpoint", f"Unknown endpoint: {route}", status=404)
+
+    def _handle_indexes(
+        self, segments: list[str], query: dict[str, list[str]]
+    ) -> tuple[bytes, int, dict[str, str]]:
+        if len(segments) == 1:
+            # GET /indexes
+            entries, current_index_id, persistence_model, schema_version = self._bridge.list_indexes()
+            resp = IndexListResponse(
+                data=[e.model_dump(exclude_none=True) for e in entries],
+                current_index_id=current_index_id,
+                persistence_model=persistence_model,
+                schema_version=schema_version,
+                meta={"count": len(entries)},
+            )
+            return _json_response(resp.model_dump(exclude_none=True))
+        if len(segments) == 2:
+            # GET /indexes/{index_id}
+            index_id = segments[1]
+            entries, _, _, _ = self._bridge.list_indexes()
+            for entry in entries:
+                if entry.index_id == index_id:
+                    return _ok(entry.model_dump(exclude_none=True))
+            return _err("index_not_found", f"Index not found: {index_id}", status=404)
+        return _err("invalid_path", "Invalid indexes path", status=404)
+
+    def _handle_artifacts(
+        self, segments: list[str], query: dict[str, list[str]]
+    ) -> tuple[bytes, int, dict[str, str]]:
+        if len(segments) == 1:
+            # GET /artifacts?type=&index_id=&limit=
+            artifact_type = _first(query.get("type"))
+            limit_str = _first(query.get("limit"))
+            limit = int(limit_str) if limit_str and limit_str.isdigit() else 50
+
+            if artifact_type:
+                if artifact_type not in KNOWN_ARTIFACT_TYPES:
+                    return _err(
+                        "unknown_artifact_type",
+                        f"Unknown artifact type: {artifact_type}. Known: {sorted(KNOWN_ARTIFACT_TYPES)}",
+                    )
+                records = self._bridge.get_artifacts_by_type(artifact_type, limit=limit)
+            else:
+                # Return a summary of all types
+                types = self._bridge.list_artifact_types()
+                summary: dict[str, Any] = {}
+                for t in types[:limit]:
+                    summary[t] = len(self._bridge.get_artifacts_by_type(t, limit=1))
+                return _ok(summary, meta={"types": len(types)})
+
+            return _ok(
+                [r.model_dump(exclude_none=True) for r in records],
+                meta={"count": len(records), "artifact_type": artifact_type},
+            )
+
+        if len(segments) == 2:
+            # GET /artifacts/{artifact_type}?index_id=
+            artifact_type = segments[1]
+            if artifact_type not in KNOWN_ARTIFACT_TYPES:
+                return _err(
+                    "unknown_artifact_type",
+                    f"Unknown artifact type: {artifact_type}. Known: {sorted(KNOWN_ARTIFACT_TYPES)}",
+                )
+
+            index_id = _first(query.get("index_id"))
+            try:
+                data = self._loader.load_json(artifact_type, index_id=index_id)
+            except ArtifactNotFoundError as exc:
+                return _err("artifact_not_found", str(exc), status=404)
+            except ChecksumMismatchError as exc:
+                return _err("checksum_mismatch", str(exc), status=409)
+            except ArtifactParseError as exc:
+                return _err("parse_error", str(exc), status=500)
+
+            return _ok(
+                data,
+                meta={"artifact_type": artifact_type, "index_id": index_id or "current"},
+            )
+
+        if len(segments) == 3 and segments[2] == "content":
+            # GET /artifacts/{artifact_type}/content?path=
+            logical_path = _first(query.get("path"))
+            if not logical_path:
+                return _err("missing_param", "Query parameter 'path' is required")
+
+            record = self._bridge.get_artifact_by_logical_path(logical_path)
+            if not record:
+                return _err("artifact_not_found", f"No artifact at path: {logical_path}", status=404)
+
+            try:
+                content = self._loader.load_artifact(record)
+            except (ArtifactNotFoundError, ChecksumMismatchError, ArtifactParseError) as exc:
+                return _err(type(exc).__name__.replace("Error", "").lower(), str(exc), status=404)
+
+            return _ok(
+                content.data,
+                meta={
+                    "artifact_type": record.artifact_type,
+                    "logical_path": record.logical_path,
+                    "resolved_path": content.resolved_path,
+                    "checksum_verified": content.checksum_verified,
+                },
+            )
+
+        return _err("invalid_path", "Invalid artifacts path", status=404)
+
+    def _handle_patches(
+        self, segments: list[str], query: dict[str, list[str]]
+    ) -> tuple[bytes, int, dict[str, str]]:
+        """Handle /patches and /patches/{operation_id} endpoints."""
+        if len(segments) == 1:
+            # GET /patches — return patches/index.json
+            try:
+                data = self._loader.load_json("patches_index")
+            except ArtifactNotFoundError as exc:
+                return _err("artifact_not_found", str(exc), status=404)
+            except ChecksumMismatchError as exc:
+                return _err("checksum_mismatch", str(exc), status=409)
+            except ArtifactParseError as exc:
+                return _err("parse_error", str(exc), status=500)
+            return _ok(data, meta={"artifact_type": "patches_index"})
+
+        if len(segments) == 2:
+            # GET /patches/{operation_id} — return individual patch detail
+            operation_id = segments[1]
+            patch_path = self.ctn_dir / "patches" / f"patch_{operation_id}.json"
+            if not patch_path.exists():
+                return _err(
+                    "patch_not_found",
+                    f"Patch detail not found: {operation_id}",
+                    status=404,
+                )
+            try:
+                raw = patch_path.read_text(encoding="utf-8")
+                data = json.loads(raw)
+            except (OSError, json.JSONDecodeError) as exc:
+                return _err("parse_error", str(exc), status=500)
+            return _ok(data, meta={"operation_id": operation_id})
+
+        return _err("invalid_path", "Invalid patches path", status=404)
+
+    def _handle_snapshot_diff(
+        self, query: dict[str, list[str]]
+    ) -> tuple[bytes, int, dict[str, str]]:
+        """Handle GET /snapshots/diff?base={id}&new={id}.
+
+        Computes a lightweight entity delta between two snapshot files.
+        """
+        base_id = _first(query.get("base"))
+        new_id = _first(query.get("new"))
+        if not base_id or not new_id:
+            return _err(
+                "missing_param",
+                "Both 'base' and 'new' snapshot IDs are required",
+            )
+
+        base_path = self.ctn_dir / "snapshots" / f"{base_id}.json"
+        new_path = self.ctn_dir / "snapshots" / f"{new_id}.json"
+
+        if not base_path.exists():
+            return _err(
+                "snapshot_not_found",
+                f"Base snapshot not found: {base_id}",
+                status=404,
+            )
+        if not new_path.exists():
+            return _err(
+                "snapshot_not_found",
+                f"New snapshot not found: {new_id}",
+                status=404,
+            )
+
+        try:
+            base_data = json.loads(base_path.read_text(encoding="utf-8"))
+            new_data = json.loads(new_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            return _err("parse_error", str(exc), status=500)
+
+        # Compute entity delta
+        base_entities = {}
+        new_entities = {}
+        for ent in base_data.get("entities", []):
+            eid = ent.get("id") or ent.get("fqn")
+            if eid:
+                base_entities[eid] = ent.get("hash", "")
+        for ent in new_data.get("entities", []):
+            eid = ent.get("id") or ent.get("fqn")
+            if eid:
+                new_entities[eid] = ent.get("hash", "")
+
+        added = [eid for eid in new_entities if eid not in base_entities]
+        removed = [eid for eid in base_entities if eid not in new_entities]
+        modified = [
+            eid for eid in new_entities
+            if eid in base_entities and new_entities[eid] != base_entities[eid]
+        ]
+        unchanged = [
+            eid for eid in new_entities
+            if eid in base_entities and new_entities[eid] == base_entities[eid]
+        ]
+
+        base_file_count = len(base_data.get("files", base_data.get("file_entries", [])))
+        new_file_count = len(new_data.get("files", new_data.get("file_entries", [])))
+        base_loc = base_data.get("stats", {}).get("loc_total", 0)
+        new_loc = new_data.get("stats", {}).get("loc_total", 0)
+
+        diff = {
+            "base_snapshot_id": base_id,
+            "new_snapshot_id": new_id,
+            "entities": {
+                "added": len(added),
+                "removed": len(removed),
+                "modified": len(modified),
+                "unchanged": len(unchanged),
+                "added_ids": added[:50],
+                "removed_ids": removed[:50],
+                "modified_ids": modified[:50],
+            },
+            "files": {
+                "base_count": base_file_count,
+                "new_count": new_file_count,
+                "delta": new_file_count - base_file_count,
+            },
+            "loc": {
+                "base": base_loc,
+                "new": new_loc,
+                "delta": new_loc - base_loc,
+            },
+        }
+        return _ok(diff)
+
+    def _handle_stats(self) -> tuple[bytes, int, dict[str, str]]:
+        stats = self._bridge.stats()
+        return _ok(stats.model_dump(exclude_none=True))
+
+
+def _first(values: list[str] | None) -> str | None:
+    if values:
+        return values[0]
+    return None
+
+
+class BridgeHTTPRequestHandler(http.server.BaseHTTPRequestHandler):
+    """Standalone HTTP request handler that serves bridge API endpoints."""
+
+    ctn_dir: Path
+
+    def __init__(self, *args, ctn_dir: Path | None = None, **kwargs):
+        if ctn_dir is not None:
+            self.ctn_dir = ctn_dir
+        super().__init__(*args, **kwargs)
+
+    def do_GET(self):
+        parsed = urllib.parse.urlparse(self.path)
+        query = urllib.parse.parse_qs(parsed.query)
+        handler = BridgeAPIHandler(self.ctn_dir)
+        body, status, headers = handler.dispatch(parsed.path, query)
+        self.send_response(status)
+        for key, value in headers.items():
+            self.send_header(key, value)
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_OPTIONS(self):
+        self.send_response(204)
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Access-Control-Allow-Methods", "GET, OPTIONS")
+        self.send_header("Access-Control-Allow-Headers", "Content-Type")
+        self.end_headers()
+
+    def log_message(self, format, *args):
+        LOGGER.info("bridge_http_request", method=self.command, path=self.path, status=args[1] if len(args) > 1 else "-")
+
+
+def create_bridge_server(ctn_dir: Path, host: str = "127.0.0.1", port: int = DEFAULT_BRIDGE_HTTP_PORT):
+    """Create a standalone bridge HTTP server."""
+    from functools import partial
+    handler = partial(BridgeHTTPRequestHandler, ctn_dir=ctn_dir)
+    return http.server.ThreadingHTTPServer((host, port), handler)
+
+
+__all__ = [
+    "BridgeAPIHandler",
+    "BridgeHTTPRequestHandler",
+    "create_bridge_server",
+]

batho/bridge/mcp_server.py

@@ -0,0 +1,159 @@
+"""MCP server for the Batho bridge using FastMCP."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Any
+
+try:
+    from mcp.server.fastmcp import FastMCP
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "The 'mcp' package is required for the bridge MCP server. "
+        "Install it with: pip install mcp>=1.0.0"
+    ) from exc
+
+from batho.bridge.artifact_loader import (
+    ArtifactLoader,
+    ArtifactNotFoundError,
+    ArtifactParseError,
+    ChecksumMismatchError,
+)
+from batho.bridge.constants import DEFAULT_MCP_SSE_PORT, KNOWN_ARTIFACT_TYPES
+from batho.bridge.registry_client import ArtifactRegistryBridge
+from batho.utils.logging import get_logger
+
+LOGGER = get_logger(__name__, component="bridge")
+
+
+def create_mcp_server(ctn_dir: Path) -> FastMCP:
+    """Create and configure a FastMCP server bound to *ctn_dir*."""
+    bridge = ArtifactRegistryBridge(ctn_dir)
+    loader = ArtifactLoader(ctn_dir)
+    mcp = FastMCP("batho-bridge")
+
+    @mcp.tool()
+    def bridge_list_indexes() -> str:
+        """List all available index IDs and timestamps."""
+        entries, current_index_id, _, _ = bridge.list_indexes()
+        result = {
+            "current_index_id": current_index_id,
+            "indexes": [
+                {"index_id": e.index_id, "timestamp": e.timestamp, "root": e.root}
+                for e in entries
+            ],
+        }
+        return json.dumps(result, indent=2)
+
+    @mcp.tool()
+    def bridge_get_index(index_id: str) -> str:
+        """Get metadata for a specific index."""
+        entries, _, _, _ = bridge.list_indexes()
+        for entry in entries:
+            if entry.index_id == index_id:
+                return json.dumps(entry.model_dump(exclude_none=True), indent=2)
+        return json.dumps({"error": f"Index not found: {index_id}"})
+
+    @mcp.tool()
+    def bridge_list_artifacts(index_id: str | None = None, artifact_type: str | None = None) -> str:
+        """List artifact records, optionally filtered by type or index."""
+        if artifact_type and artifact_type not in KNOWN_ARTIFACT_TYPES:
+            return json.dumps(
+                {
+                    "error": f"Unknown artifact type: {artifact_type}",
+                    "known_types": sorted(KNOWN_ARTIFACT_TYPES),
+                }
+            )
+
+        if artifact_type:
+            records = bridge.get_artifacts_by_type(artifact_type, limit=200)
+        else:
+            records = []
+            for t in bridge.list_artifact_types()[:20]:
+                records.extend(bridge.get_artifacts_by_type(t, limit=10))
+
+        result = [r.model_dump(exclude_none=True) for r in records]
+        return json.dumps(result, indent=2)
+
+    @mcp.tool()
+    def bridge_get_artifact(artifact_type: str, index_id: str | None = None) -> str:
+        """Load and return full JSON content for an artifact type."""
+        if artifact_type not in KNOWN_ARTIFACT_TYPES:
+            return json.dumps(
+                {
+                    "error": f"Unknown artifact type: {artifact_type}",
+                    "known_types": sorted(KNOWN_ARTIFACT_TYPES),
+                }
+            )
+
+        try:
+            data = loader.load_json(artifact_type, index_id=index_id)
+        except ArtifactNotFoundError as exc:
+            return json.dumps({"error": str(exc)})
+        except ChecksumMismatchError as exc:
+            return json.dumps({"error": str(exc), "warning": "checksum_mismatch"})
+        except ArtifactParseError as exc:
+            return json.dumps({"error": str(exc)})
+
+        return json.dumps({"ok": True, "artifact_type": artifact_type, "data": data}, indent=2, default=str)
+
+    @mcp.tool()
+    def bridge_get_artifact_by_path(logical_path: str) -> str:
+        """Load artifact content by its exact logical path."""
+        record = bridge.get_artifact_by_logical_path(logical_path)
+        if not record:
+            return json.dumps({"error": f"No artifact at path: {logical_path}"})
+
+        try:
+            content = loader.load_artifact(record)
+        except (ArtifactNotFoundError, ChecksumMismatchError, ArtifactParseError) as exc:
+            return json.dumps({"error": str(exc)})
+
+        return json.dumps(
+            {
+                "ok": True,
+                "record": record.model_dump(exclude_none=True),
+                "data": content.data,
+                "resolved_path": content.resolved_path,
+                "checksum_verified": content.checksum_verified,
+            },
+            indent=2,
+            default=str,
+        )
+
+    @mcp.tool()
+    def bridge_search_artifacts(query: str, artifact_type: str | None = None) -> str:
+        """Fuzzy search artifacts by logical path."""
+        records = bridge.search_artifacts(query, artifact_type=artifact_type)
+        result = [r.model_dump(exclude_none=True) for r in records]
+        return json.dumps(result, indent=2)
+
+    @mcp.tool()
+    def bridge_get_stats() -> str:
+        """Return registry statistics."""
+        stats = bridge.stats()
+        return json.dumps(stats.model_dump(exclude_none=True), indent=2)
+
+    return mcp
+
+
+def run_mcp_stdio(ctn_dir: Path) -> None:
+    """Run the MCP server over stdio (default for IDE integrations)."""
+    mcp = create_mcp_server(ctn_dir)
+    mcp.run(transport="stdio")
+
+
+def run_mcp_sse(ctn_dir: Path, host: str = "127.0.0.1", port: int = DEFAULT_MCP_SSE_PORT) -> None:
+    """Run the MCP server over SSE transport."""
+    mcp = create_mcp_server(ctn_dir)
+    LOGGER.info("mcp_sse_starting", host=host, port=port)
+    mcp.run(transport="sse", host=host, port=port)
+
+
+__all__ = [
+    "create_mcp_server",
+    "run_mcp_stdio",
+    "run_mcp_sse",
+]

batho/bridge/models.py

@@ -0,0 +1,102 @@
+"""Pydantic models for the Batho bridge API."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ArtifactRecord(BaseModel):
+    """A single artifact as returned by the registry."""
+
+    artifact_id: str
+    artifact_type: str
+    logical_path: str
+    physical_path: str
+    checksum: str = ""
+    size_bytes: int = 0
+    schema_version: str = ""
+    producer: str = ""
+    run_id: str = ""
+    sync_status: str = "local_only"
+    cloud_content_id: str | None = None
+    last_sync_at: str | None = None
+    sync_error: str | None = None
+    retry_count: int = 0
+    retention_class: str = "default"
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    created_at: str = ""
+    updated_at: str = ""
+
+
+class IndexEntry(BaseModel):
+    """A single index entry from .ctn/index.json."""
+
+    index_id: str
+    timestamp: str
+    root: str
+    file_count: int = 0
+    entity_count: int = 0
+    relationship_count: int = 0
+    repo_hash: str = ""
+    staleness_score: float = 1.0
+    stack: dict[str, Any] = Field(default_factory=dict)
+    outputs: dict[str, str] = Field(default_factory=dict)
+    stats: dict[str, Any] = Field(default_factory=dict)
+    metrics: dict[str, Any] = Field(default_factory=dict)
+    build: dict[str, Any] = Field(default_factory=dict)
+    schemas: dict[str, Any] = Field(default_factory=dict)
+    persistence: dict[str, Any] = Field(default_factory=dict)
+    snapshot_id: str = ""
+
+
+class IndexListResponse(BaseModel):
+    """Response envelope for the indexes list endpoint."""
+
+    ok: bool = True
+    data: list[IndexEntry] = Field(default_factory=list)
+    current_index_id: str = ""
+    persistence_model: str | None = None
+    schema_version: str | None = None
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+
+class BridgeResponse(BaseModel):
+    """Unified envelope for all bridge HTTP responses."""
+
+    ok: bool = True
+    data: Any = None
+    meta: dict[str, Any] = Field(default_factory=dict)
+
+
+class BridgeErrorResponse(BaseModel):
+    """Error envelope for bridge HTTP responses."""
+
+    ok: bool = False
+    error: dict[str, Any] = Field(default_factory=dict)
+
+
+class RegistryStats(BaseModel):
+    """Registry statistics."""
+
+    enabled: bool = False
+    registry_path: str = ""
+    backend: str = "sqlite"
+    artifact_count: int = 0
+    deleted_artifact_count: int = 0
+    content_blob_count: int = 0
+    artifact_types: dict[str, int] = Field(default_factory=dict)
+    sync_status: dict[str, int] = Field(default_factory=dict)
+    db_size_bytes: int = 0
+
+
+__all__ = [
+    "ArtifactRecord",
+    "IndexEntry",
+    "IndexListResponse",
+    "BridgeResponse",
+    "BridgeErrorResponse",
+    "RegistryStats",
+]