codexa 0.4.0__py3-none-any.whl

semantic_code_intelligence/bridge/context_provider.py

@@ -0,0 +1,245 @@
+"""Context provider — structured context generation for external AI pipelines.
+
+The ``ContextProvider`` is the heart of CodexA's cooperation model.  It
+wraps the existing semantic search, symbol analysis, and dependency tools
+into a single entry point that external AI assistants can call to enrich
+their prompts with deep repository knowledge.
+
+All public methods return plain ``dict`` objects ready for JSON
+serialisation, so they can be consumed by any agent that speaks JSON —
+no CodexA-specific types leak across the boundary.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any
+
+from semantic_code_intelligence.analysis.ai_features import (
+    explain_file,
+    explain_symbol,
+    generate_ai_context,
+    summarize_repository,
+)
+from semantic_code_intelligence.context.engine import (
+    CallGraph,
+    ContextBuilder,
+    DependencyMap,
+)
+from semantic_code_intelligence.llm.safety import SafetyValidator
+from semantic_code_intelligence.services.search_service import search_codebase
+from semantic_code_intelligence.utils.logging import get_logger
+
+logger = get_logger("bridge.context")
+
+
+class ContextProvider:
+    """Generates structured context for consumption by external AI agents.
+
+    Usage::
+
+        provider = ContextProvider(Path("/my/project"))
+        ctx = provider.context_for_symbol("authenticate")
+        # ctx is a plain dict ready to be injected into an LLM prompt
+
+    All expensive work (scanning, parsing) is done lazily on first access.
+    """
+
+    def __init__(self, project_root: Path) -> None:
+        self._root = project_root.resolve()
+        self._builder: ContextBuilder | None = None
+        self._indexed = False
+        self._validator = SafetyValidator()
+
+    # --- lazy indexing -------------------------------------------------
+
+    def _ensure_indexed(self) -> ContextBuilder:
+        if self._builder is not None and self._indexed:
+            return self._builder
+
+        from semantic_code_intelligence.config.settings import load_config
+        from semantic_code_intelligence.indexing.scanner import scan_repository
+
+        self._builder = ContextBuilder()
+        config = load_config(self._root)
+        scanned = scan_repository(self._root, config.index)
+        for sf in scanned:
+            full = str(self._root / sf.relative_path)
+            try:
+                self._builder.index_file(full)
+            except Exception:
+                logger.debug("Skip %s", full)
+        self._indexed = True
+        return self._builder
+
+    # --- public context generators ----------------------------------
+
+    def context_for_query(
+        self,
+        query: str,
+        *,
+        top_k: int = 5,
+        threshold: float = 0.2,
+        include_repo_summary: bool = False,
+    ) -> dict[str, Any]:
+        """Return semantic-search context for a natural-language query.
+
+        Designed to be injected as additional context into an LLM prompt
+        by an external AI assistant.
+        """
+        snippets: list[dict[str, Any]] = []
+        try:
+            results = search_codebase(query, self._root, top_k=top_k, threshold=threshold)
+            snippets = [r.to_dict() for r in results]
+        except Exception:
+            logger.debug("Search unavailable — returning empty snippets.")
+
+        resp: dict[str, Any] = {
+            "query": query,
+            "snippet_count": len(snippets),
+            "snippets": snippets,
+        }
+
+        if include_repo_summary:
+            builder = self._ensure_indexed()
+            resp["repo_summary"] = summarize_repository(builder).to_dict()
+
+        return resp
+
+    def context_for_symbol(
+        self,
+        symbol_name: str,
+        *,
+        file_path: str | None = None,
+        include_call_graph: bool = True,
+        include_dependencies: bool = True,
+    ) -> dict[str, Any]:
+        """Return rich context around a symbol for external AI consumption.
+
+        Includes the symbol's definition, related symbols, callers/callees,
+        and dependency information.
+        """
+        builder = self._ensure_indexed()
+
+        if file_path:
+            builder.index_file(file_path)
+
+        matches = builder.find_symbol(symbol_name)
+        if not matches:
+            return {"symbol_name": symbol_name, "found": False}
+
+        explanations = [explain_symbol(s, builder).to_dict() for s in matches[:5]]
+        context_windows = [
+            builder.build_context(s).to_dict() for s in matches[:5]
+        ]
+
+        result: dict[str, Any] = {
+            "symbol_name": symbol_name,
+            "found": True,
+            "match_count": len(matches),
+            "explanations": explanations,
+            "context_windows": context_windows,
+        }
+
+        if include_call_graph:
+            all_syms = builder.get_all_symbols()
+            graph = CallGraph()
+            graph.build(all_syms)
+            callers = [e.to_dict() for e in graph.callers_of(symbol_name)]
+            callees: list[dict[str, Any]] = []
+            for edge in graph.edges:
+                if edge.caller.endswith(f":{symbol_name}"):
+                    callees.append(edge.to_dict())
+            result["call_graph"] = {"callers": callers, "callees": callees}
+
+        if include_dependencies:
+            for s in matches[:1]:
+                dep_map = DependencyMap()
+                if s.file_path in builder._file_contents:
+                    dep_map.add_file(s.file_path, builder._file_contents[s.file_path])
+                result["dependencies"] = dep_map.to_dict()
+
+        return result
+
+    def context_for_file(self, file_path: str) -> dict[str, Any]:
+        """Return structured context for an entire file."""
+        builder = self._ensure_indexed()
+        builder.index_file(file_path)
+
+        symbols = builder.get_symbols(file_path)
+        explanations = explain_file(file_path)
+
+        dep_map = DependencyMap()
+        if file_path in builder._file_contents:
+            dep_map.add_file(file_path, builder._file_contents[file_path])
+
+        return {
+            "file_path": file_path,
+            "symbol_count": len(symbols),
+            "symbols": [s.to_dict() for s in symbols],
+            "explanations": [e.to_dict() for e in explanations],
+            "dependencies": dep_map.to_dict(),
+        }
+
+    def context_for_repo(self) -> dict[str, Any]:
+        """Return a repository-level summary."""
+        builder = self._ensure_indexed()
+        summary = summarize_repository(builder)
+        return summary.to_dict()
+
+    def validate_code(self, code: str) -> dict[str, Any]:
+        """Validate code (e.g. AI-generated) for safety issues."""
+        report = self._validator.validate(code)
+        return report.to_dict()
+
+    def get_dependencies(self, file_path: str) -> dict[str, Any]:
+        """Return file-level dependency map."""
+        builder = self._ensure_indexed()
+        # Resolve relative paths against project root
+        resolved = Path(file_path)
+        if not resolved.is_absolute():
+            resolved = self._root / resolved
+        resolved_str = str(resolved)
+        builder.index_file(resolved_str)
+        dep_map = DependencyMap()
+        if resolved_str in builder._file_contents:
+            dep_map.add_file(resolved_str, builder._file_contents[resolved_str])
+        return {"file_path": file_path, "dependencies": dep_map.to_dict()}
+
+    def get_call_graph(self, symbol_name: str) -> dict[str, Any]:
+        """Return callers and callees for a symbol."""
+        builder = self._ensure_indexed()
+        all_syms = builder.get_all_symbols()
+        graph = CallGraph()
+        graph.build(all_syms)
+        callers = [e.to_dict() for e in graph.callers_of(symbol_name)]
+        callees: list[dict[str, Any]] = []
+        for edge in graph.edges:
+            if edge.caller.endswith(f":{symbol_name}"):
+                callees.append(edge.to_dict())
+        edges = callers + callees
+        return {
+            "symbol_name": symbol_name,
+            "callers": callers,
+            "callees": callees,
+            "edges": edges,
+        }
+
+    def find_references(self, symbol_name: str) -> dict[str, Any]:
+        """Find all references to a symbol."""
+        builder = self._ensure_indexed()
+        all_syms = builder.get_all_symbols()
+        refs: list[dict[str, Any]] = []
+        for sym in all_syms:
+            if sym.name == symbol_name:
+                refs.append(sym.to_dict())
+            elif symbol_name in sym.body:
+                refs.append({
+                    "referencing_symbol": sym.name,
+                    "kind": sym.kind,
+                    "file_path": sym.file_path,
+                    "start_line": sym.start_line,
+                    "end_line": sym.end_line,
+                })
+        return {"symbol_name": symbol_name, "reference_count": len(refs), "references": refs}

semantic_code_intelligence/bridge/protocol.py

@@ -0,0 +1,167 @@
+"""Agent cooperation protocol — request/response types for external AI systems.
+
+Defines a model-neutral JSON protocol that any IDE AI assistant (Copilot,
+Cursor, Continue, etc.) can use to request context from CodexA and receive
+structured responses.
+
+The protocol is intentionally simple and stateless — every request carries
+the information needed to produce a response.  This keeps the bridge
+lightweight and easy to integrate with any tool that speaks JSON.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+class RequestKind(str, Enum):
+    """Types of requests the bridge can handle."""
+
+    SEMANTIC_SEARCH = "semantic_search"
+    EXPLAIN_SYMBOL = "explain_symbol"
+    EXPLAIN_FILE = "explain_file"
+    GET_CONTEXT = "get_context"
+    GET_DEPENDENCIES = "get_dependencies"
+    GET_CALL_GRAPH = "get_call_graph"
+    SUMMARIZE_REPO = "summarize_repo"
+    FIND_REFERENCES = "find_references"
+    VALIDATE_CODE = "validate_code"
+    LIST_CAPABILITIES = "list_capabilities"
+
+    # Phase 19 — AI Agent Tooling Protocol
+    INVOKE_TOOL = "invoke_tool"
+    LIST_TOOLS = "list_tools"
+
+
+# ---------------------------------------------------------------------------
+# Request / Response
+# ---------------------------------------------------------------------------
+
+@dataclass
+class AgentRequest:
+    """Incoming request from an external AI agent or IDE extension.
+
+    Attributes:
+        kind: The type of operation requested.
+        params: Operation-specific parameters (key-value).
+        request_id: Optional caller-assigned ID for correlation.
+        source: Optional identifier for the calling agent (e.g. "copilot").
+    """
+
+    kind: str
+    params: dict[str, Any] = field(default_factory=dict)
+    request_id: str = ""
+    source: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the request to a plain dictionary."""
+        return {
+            "kind": self.kind,
+            "params": self.params,
+            "request_id": self.request_id,
+            "source": self.source,
+        }
+
+    def to_json(self) -> str:
+        """Serialize the request to a JSON string."""
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "AgentRequest":
+        """Create an AgentRequest from a dictionary."""
+        return cls(
+            kind=data.get("kind", ""),
+            params=data.get("params", {}),
+            request_id=data.get("request_id", ""),
+            source=data.get("source", ""),
+        )
+
+    @classmethod
+    def from_json(cls, text: str) -> "AgentRequest":
+        """Create an AgentRequest by parsing a JSON string."""
+        return cls.from_dict(json.loads(text))
+
+
+@dataclass
+class AgentResponse:
+    """Outgoing response to an external AI agent or IDE extension.
+
+    Attributes:
+        success: Whether the request was handled without error.
+        data: The structured response payload.
+        error: Human-readable error message if success is False.
+        request_id: Echoes the caller's request_id for correlation.
+        elapsed_ms: Time taken to process the request.
+    """
+
+    success: bool
+    data: dict[str, Any] = field(default_factory=dict)
+    error: str = ""
+    request_id: str = ""
+    elapsed_ms: float = 0.0
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the response to a plain dictionary."""
+        result: dict[str, Any] = {
+            "success": self.success,
+            "request_id": self.request_id,
+            "elapsed_ms": round(self.elapsed_ms, 2),
+        }
+        if self.success:
+            result["data"] = self.data
+        else:
+            result["error"] = self.error
+        return result
+
+    def to_json(self, indent: int | None = None) -> str:
+        """Serialize the response to a JSON string."""
+        return json.dumps(self.to_dict(), indent=indent)
+
+
+# ---------------------------------------------------------------------------
+# Capabilities manifest
+# ---------------------------------------------------------------------------
+
+@dataclass
+class BridgeCapabilities:
+    """Advertises what CodexA can do to external consumers.
+
+    Returned in response to ``list_capabilities`` requests and also
+    served at ``GET /`` by the bridge server.
+    """
+
+    version: str = "0.9.0"
+    name: str = "CodexA Bridge"
+    description: str = (
+        "Semantic code intelligence provider — context, search, "
+        "explanation, dependency analysis, and safety validation "
+        "for external AI coding assistants."
+    )
+    supported_requests: list[str] = field(
+        default_factory=lambda: [k.value for k in RequestKind]
+    )
+    tools: list[dict[str, Any]] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the capabilities manifest to a plain dictionary."""
+        result: dict[str, Any] = {
+            "version": self.version,
+            "name": self.name,
+            "description": self.description,
+            "supported_requests": self.supported_requests,
+        }
+        if self.tools:
+            result["tools"] = self.tools
+        return result
+
+    def to_json(self, indent: int = 2) -> str:
+        """Serialize the capabilities manifest to a JSON string."""
+        return json.dumps(self.to_dict(), indent=indent)