codrspot-processor-mcp 0.1.0__py3-none-any.whl

codepreproc_client/layer1_business/api_client/superkg_client.py

@@ -0,0 +1,327 @@
+"""Client for the SuperKG proxy: POST /v1/superkg/* (contracts/openapi.yaml).
+
+Real network calls, not a direct connection to SuperKG - codepreproc-server
+is the only thing that holds the real SuperKG URL/credentials
+(layer3_core/superkg/connector.py on the server). This crosses the same
+JWT-gated boundary as promote/registry; identity (tenant_id/user_id) is
+derived server-side from the JWT, never sent by the client. Every method
+takes `project_id` because authorization is scoped per-project (see
+layer2_infra/api/authz.py::superkg_system_authorized on the server).
+
+All public methods are safe to call without awaiting result checks - they
+absorb exceptions and return None/[]/no-op on any failure so the rest of
+codepreproc is unaffected when SuperKG (or the server) is unavailable.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Awaitable, Callable
+
+import httpx
+
+from codepreproc_client.layer1_business.api_client.net_guard import assert_safe_to_send
+from contracts.dtos import (
+    SuperkgBootstrapRequest,
+    SuperkgChunkMetadata,
+    SuperkgDecisionRequest,
+    SuperkgEnrichRequest,
+    SuperkgIngestRequest,
+    SuperkgLogActivityRequest,
+    SuperkgQueryRequest,
+    SuperkgSessionCloseRequest,
+    SuperkgSessionOpenRequest,
+    SuperkgTransitionRequest,
+)
+
+if TYPE_CHECKING:
+    from contracts.dtos import CodeChunk
+    from contracts.ir import BusinessLogicDiff
+
+JWTProvider = Callable[[str], Awaitable[str]]  # project_id -> bearer token
+
+
+@dataclass
+class KGScore:
+    kg_score: float = 0.0
+    signals: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class EnrichResult:
+    trace_id: str
+    kg_scores: dict[str, KGScore] = field(default_factory=dict)
+    pattern_suggestions: list[dict[str, Any]] = field(default_factory=list)
+    warnings: list[dict[str, Any]] = field(default_factory=list)
+
+_log = logging.getLogger("codepreproc.superkg_client")
+
+
+class SuperKGClient:
+    """Thin async wrapper around codepreproc-server's `/v1/superkg/*` proxy."""
+
+    def __init__(
+        self,
+        base_url: str,
+        jwt_provider: JWTProvider,
+        enabled: bool = True,
+        timeout: float = 10.0,
+        enrich_timeout: float = 0.8,
+    ) -> None:
+        self.enabled = enabled
+        self._base = base_url.rstrip("/")
+        self._jwt_provider = jwt_provider
+        self._timeout = timeout
+        self._enrich_timeout = enrich_timeout
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    async def _headers(self, project_id: str) -> dict[str, str]:
+        jwt = await self._jwt_provider(project_id)
+        return {"Authorization": f"Bearer {jwt}"}
+
+    async def _post(
+        self, path: str, project_id: str, request, *, kind: str | None = None, timeout: float | None = None
+    ) -> dict | None:
+        if not self.enabled:
+            return None
+        assert_safe_to_send(request)
+        payload = request.model_dump(mode="json")
+        if kind is not None:
+            payload["kind"] = kind
+        try:
+            headers = await self._headers(project_id)
+            async with httpx.AsyncClient(base_url=self._base, timeout=timeout or self._timeout) as client:
+                resp = await client.post(f"/v1/superkg{path}", json=payload, headers=headers)
+                resp.raise_for_status()
+                return resp.json()
+        except Exception as exc:
+            _log.debug("SuperKG proxy POST %s failed: %s", path, exc)
+            return None
+
+    async def _delete(self, path: str, project_id: str, request) -> None:
+        if not self.enabled:
+            return
+        assert_safe_to_send(request)
+        try:
+            headers = await self._headers(project_id)
+            async with httpx.AsyncClient(base_url=self._base, timeout=self._timeout) as client:
+                resp = await client.request(
+                    "DELETE", f"/v1/superkg{path}", json=request.model_dump(mode="json"), headers=headers
+                )
+                resp.raise_for_status()
+        except Exception as exc:
+            _log.debug("SuperKG proxy DELETE %s failed: %s", path, exc)
+
+    # ------------------------------------------------------------------
+    # Project bootstrap
+    # ------------------------------------------------------------------
+
+    async def bootstrap(self, project_id: str, name: str, description: str) -> str | None:
+        """Register a project as a SuperKG system. Returns the system_id or None."""
+        data = await self._post(
+            "/bootstrap", project_id, SuperkgBootstrapRequest(project_id=project_id, name=name, description=description)
+        )
+        return data.get("system_id") if data else None
+
+    # ------------------------------------------------------------------
+    # Sessions
+    # ------------------------------------------------------------------
+
+    async def open_session(self, project_id: str, system_id: str, context: str) -> str | None:
+        """Open a work session in SuperKG. Returns session_id or None."""
+        data = await self._post(
+            "/session", project_id, SuperkgSessionOpenRequest(project_id=project_id, system_id=system_id, context=context)
+        )
+        return data.get("session_id") if data else None
+
+    async def close_session(self, project_id: str, session_id: str) -> None:
+        """Close a SuperKG session (fire-and-forget)."""
+        await self._delete(
+            "/session", project_id, SuperkgSessionCloseRequest(project_id=project_id, session_id=session_id)
+        )
+
+    # ------------------------------------------------------------------
+    # Decisions & activity
+    # ------------------------------------------------------------------
+
+    async def record_decision(
+        self,
+        project_id: str,
+        system_id: str,
+        session_id: str | None,
+        intent: str,
+        plan_summary: dict,
+        bld: "BusinessLogicDiff | None" = None,
+        expected_sequence: int | None = None,
+    ) -> None:
+        """Record a semantic edit decision in SuperKG (fire-and-forget)."""
+        req = SuperkgDecisionRequest(
+            project_id=project_id,
+            system_id=system_id,
+            session_id=session_id,
+            intent=intent,
+            plan_summary=plan_summary,
+            bld=bld.model_dump(mode="json") if bld is not None else None,
+            expected_sequence=expected_sequence,
+        )
+        await self._post("/activity", project_id, req, kind="decision")
+
+    async def log_activity(self, project_id: str, system_id: str, activity_type: str, details: dict) -> None:
+        """Log a work activity event in SuperKG (fire-and-forget)."""
+        req = SuperkgLogActivityRequest(
+            project_id=project_id, system_id=system_id, activity_type=activity_type, details=details
+        )
+        await self._post("/activity", project_id, req, kind="activity")
+
+    async def transition_status(
+        self, project_id: str, system_id: str, entity_id: str, entity_type: str, new_status: str
+    ) -> None:
+        """Apply a state transition to an entity (fire-and-forget)."""
+        req = SuperkgTransitionRequest(
+            project_id=project_id,
+            system_id=system_id,
+            entity_id=entity_id,
+            entity_type=entity_type,
+            new_status=new_status,
+        )
+        await self._post("/activity", project_id, req, kind="transition")
+
+    # ------------------------------------------------------------------
+    # Queries
+    # ------------------------------------------------------------------
+
+    async def get_snapshot(self, project_id: str, system_id: str) -> dict | None:
+        """Return a consistent snapshot of the system state."""
+        data = await self._post(
+            "/query", project_id, SuperkgQueryRequest(project_id=project_id, system_id=system_id, kind="snapshot")
+        )
+        return data.get("data") if data else None
+
+    async def get_context(self, project_id: str, system_id: str, mode: str = "narrative") -> dict | None:
+        """Return LLM-ready context for a system in the requested mode.
+
+        Modes: reflexive, comparative, narrative, consolidation, simulation.
+        """
+        data = await self._post(
+            "/query",
+            project_id,
+            SuperkgQueryRequest(project_id=project_id, system_id=system_id, kind="context", mode=mode),
+        )
+        return data.get("data") if data else None
+
+    async def get_insights(self, project_id: str, system_id: str) -> list[dict]:
+        """List insights for a system."""
+        data = await self._post(
+            "/query", project_id, SuperkgQueryRequest(project_id=project_id, system_id=system_id, kind="insights")
+        )
+        return data.get("items", []) if data else []
+
+    async def get_patterns(self, project_id: str, system_id: str) -> list[dict]:
+        """List observed patterns across all systems."""
+        data = await self._post(
+            "/query", project_id, SuperkgQueryRequest(project_id=project_id, system_id=system_id, kind="patterns")
+        )
+        return data.get("items", []) if data else []
+
+    # ------------------------------------------------------------------
+    # Ingest (granular entity registration)
+    # ------------------------------------------------------------------
+
+    async def ingest_component(self, project_id: str, system_id: str, file_path: str, language: str) -> str | None:
+        """Register a source file as a SuperKG component. Returns component_id or None."""
+        data = await self._post(
+            "/ingest",
+            project_id,
+            SuperkgIngestRequest(
+                project_id=project_id, system_id=system_id, kind="component", file_path=file_path, language=language
+            ),
+        )
+        return data.get("id") if data else None
+
+    async def ingest_object(
+        self,
+        project_id: str,
+        system_id: str,
+        component_id: str | None,
+        chunk: "CodeChunk",
+    ) -> None:
+        """Register a CodeChunk's metadata as a SuperKG object (fire-and-forget).
+
+        Raw source (`chunk.body`) is never sent - net_guard.py forbids a
+        `body` field from crossing the client->server boundary.
+        """
+        metadata = SuperkgChunkMetadata(
+            chunk_id=chunk.chunk_id,
+            project_id=chunk.project_id,
+            file_path=chunk.file_path,
+            language=chunk.language,
+            symbol=chunk.symbol,
+            kind=chunk.kind,
+            start_line=chunk.start_line,
+            end_line=chunk.end_line,
+            signature=chunk.signature,
+            git_sha=chunk.git_sha,
+            content_hash=chunk.content_hash,
+        )
+        await self._post(
+            "/ingest",
+            project_id,
+            SuperkgIngestRequest(
+                project_id=project_id, system_id=system_id, kind="object", component_id=component_id, chunk=metadata
+            ),
+        )
+
+    async def ingest_repo_map(
+        self, project_id: str, system_id: str, repo_map: dict[str, Any], output_path: str | None = None
+    ) -> None:
+        """Register a generated repository map as project-level knowledge."""
+        await self._post(
+            "/ingest",
+            project_id,
+            SuperkgIngestRequest(
+                project_id=project_id,
+                system_id=system_id,
+                kind="repo_map",
+                repo_map=repo_map,
+                output_path=output_path,
+            ),
+        )
+
+    # ------------------------------------------------------------------
+    # Enrichment
+    # ------------------------------------------------------------------
+
+    async def enrich(self, project_id: str, system_id: str, query: str, candidates: list[dict]) -> EnrichResult | None:
+        """Call the enrich proxy with top reranked candidates. Returns None on timeout/failure/disabled."""
+        data = await self._post(
+            "/enrich",
+            project_id,
+            SuperkgEnrichRequest(project_id=project_id, system_id=system_id, query=query, candidates=candidates),
+            timeout=self._enrich_timeout,
+        )
+        if not data:
+            return None
+        raw_scores = data.get("kg_scores", {})
+        kg_scores = {
+            cid: KGScore(kg_score=float(v.get("kg_score", 0.0)), signals=v.get("signals", {}))
+            for cid, v in raw_scores.items()
+        }
+        return EnrichResult(
+            trace_id=data.get("trace_id", ""),
+            kg_scores=kg_scores,
+            pattern_suggestions=data.get("pattern_suggestions", []),
+            warnings=data.get("warnings", []),
+        )
+
+    # ------------------------------------------------------------------
+    # Health
+    # ------------------------------------------------------------------
+
+    async def health(self) -> dict | None:
+        """SuperKG proxy health isn't exposed as a distinct endpoint - reachability is
+        implied by any successful call above; callers should not depend on this."""
+        return None