core-runtime 0.1.1__py3-none-any.whl

shared/infrastructure/knowledge/knowledge_service.py

@@ -0,0 +1,155 @@
+# src/shared/infrastructure/knowledge/knowledge_service.py
+
+"""
+Centralized access to CORE's knowledge graph and declared capabilities.
+
+CONSTITUTIONAL COMPLIANCE:
+- Treated as the read-only interface to the system state.
+- Sourced from the operational database view `core.knowledge_graph`.
+
+HEALED (V2.3.0):
+- Shadow Sensation: Now accepts an optional LimbWorkspace.
+- If a workspace is provided, it builds a "Shadow Graph" that includes
+  uncommitted changes, preventing "Semantic Blindness" during refactoring.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from sqlalchemy import text
+
+from shared.infrastructure.database.session_manager import get_session
+from shared.logger import getLogger
+
+
+if TYPE_CHECKING:
+    from shared.infrastructure.context.limb_workspace import LimbWorkspace
+
+logger = getLogger(__name__)
+
+
+# ID: c96a7d9f-1b00-4655-a111-3de39228a74f
+class KnowledgeGraphBuilder:
+    """
+    Compatibility wrapper that preserves the historical import path:
+    `shared.infrastructure.knowledge.knowledge_service.KnowledgeGraphBuilder`.
+    """
+
+    def __init__(
+        self, root_path: Path | str, workspace: LimbWorkspace | None = None
+    ) -> None:
+        # Lazy import prevents heavy graph dependencies at module import time.
+        from shared.infrastructure.knowledge_graph_service import (
+            KnowledgeGraphBuilder as _CanonicalKnowledgeGraphBuilder,
+        )
+
+        self._builder = _CanonicalKnowledgeGraphBuilder(
+            Path(root_path), workspace=workspace
+        )
+
+    # ID: 07b55eae-aa87-47a7-a04f-332e3f38769c
+    def build(self) -> dict[str, Any]:
+        return self._builder.build()
+
+
+# ID: bfdee087-408b-4c07-ab43-d673dbb3eca0
+class KnowledgeService:
+    """
+    A read-only interface to the knowledge graph.
+    """
+
+    def __init__(
+        self,
+        repo_path: Path | str = ".",
+        session=None,
+        workspace: LimbWorkspace | None = None,
+    ):
+        self.repo_path = Path(repo_path)
+        self._session = session
+        self.workspace = workspace
+
+    # ID: f508b9a0-3ddd-4e36-9c72-f5a19820b769
+    async def get_graph(self) -> dict[str, Any]:
+        """
+        Loads the knowledge graph.
+
+        HEALED: If a workspace is present, it returns a 'Shadow Graph' representing
+        the future state of the code. Otherwise, it queries the database SSOT.
+        """
+        # SENSATION: Check the virtual overlay first
+        if self.workspace:
+            logger.info("📡 Sensation: Building Shadow Graph from workspace overlay...")
+            try:
+                builder = KnowledgeGraphBuilder(
+                    self.repo_path, workspace=self.workspace
+                )
+                return builder.build()
+            except Exception as e:
+                logger.warning(
+                    "Shadow graph build failed, continuing with empty graph: %s", e
+                )
+                return {"metadata": {"mode": "SHADOW_FALLBACK"}, "symbols": {}}
+
+        logger.info("Loading knowledge graph from database view...")
+        symbols_map = {}
+        try:
+
+            async def _fetch_data(s):
+                result = await s.execute(
+                    text("SELECT * FROM core.knowledge_graph ORDER BY symbol_path")
+                )
+                return result.mappings().all()
+
+            if self._session:
+                rows = await _fetch_data(self._session)
+            else:
+                async with get_session() as session:
+                    rows = await _fetch_data(session)
+
+            for row in rows:
+                row_dict = dict(row)
+                symbol_path = row_dict.get("symbol_path")
+                if symbol_path:
+                    if "uuid" in row_dict and row_dict["uuid"] is not None:
+                        row_dict["uuid"] = str(row_dict["uuid"])
+                    if "vector_id" in row_dict and row_dict["vector_id"] is not None:
+                        row_dict["vector_id"] = str(row_dict["vector_id"])
+                    row_dict["capabilities"] = row_dict.get("capabilities_array", [])
+                    symbols_map[symbol_path] = row_dict
+
+            knowledge_graph = {"symbols": symbols_map}
+            logger.info(
+                "Successfully loaded %s symbols from the database.", len(symbols_map)
+            )
+            return knowledge_graph
+        except Exception as e:
+            logger.error(
+                "Failed to load knowledge graph from database: %s", e, exc_info=True
+            )
+            return {"symbols": {}}
+
+    # ID: f833244f-7d17-4510-be4b-9dcbd106e9fa
+    async def list_capabilities(self) -> list[str]:
+        """Returns all capability keys directly from the database."""
+        if self._session:
+            result = await self._session.execute(
+                text("SELECT name FROM core.capabilities ORDER BY name")
+            )
+            return [row[0] for row in result]
+        else:
+            async with get_session() as session:
+                result = await session.execute(
+                    text("SELECT name FROM core.capabilities ORDER BY name")
+                )
+                return [row[0] for row in result]
+
+    # ID: 3f6515de-ffb2-4119-90c0-aecc89aae54a
+    async def search_capabilities(self, query: str, limit: int = 5) -> list[str]:
+        """
+        Placeholder for semantic search (usually handled by CognitiveService).
+        """
+        all_caps = await self.list_capabilities()
+        q_lower = query.lower()
+        return [c for c in all_caps if q_lower in c.lower()][:limit]

shared/infrastructure/knowledge_graph_service.py

@@ -0,0 +1,214 @@
+# src/shared/infrastructure/knowledge_graph_service.py
+
+"""
+Knowledge Graph Builder - Sensory-Aware Logic Service.
+
+Introspects the codebase and creates an in-memory representation of symbols.
+
+UPGRADED: Accepts an optional LimbWorkspace to build a "Shadow Graph" of
+uncommitted changes (Future Truth) combined with the base repository
+(Historical Truth).
+
+Constitutional Alignment:
+- Pillar I (Octopus): Distributed sensation - the graph "tastes" the Crate.
+- Pillar II (UNIX): Stateless fact extraction.
+"""
+
+from __future__ import annotations
+
+import ast
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from shared.ast_utility import (
+    FunctionCallVisitor,
+    calculate_structural_hash,
+    extract_base_classes,
+    extract_docstring,
+    extract_parameters,
+    parse_metadata_comment,
+)
+from shared.logger import getLogger
+
+
+if TYPE_CHECKING:
+    from shared.infrastructure.context.limb_workspace import LimbWorkspace
+
+logger = getLogger(__name__)
+
+
+# ID: 8052e09f-edbb-4de2-974e-efcfbb139b32
+class KnowledgeGraphBuilder:
+    """
+    Scans source code to build a comprehensive in-memory knowledge graph.
+
+    Supports virtualized sensation via LimbWorkspace to prevent
+    "Semantic Blindness" during autonomous refactoring.
+    """
+
+    def __init__(self, root_path: Path, workspace: LimbWorkspace | None = None) -> None:
+        """
+        Initialize the builder.
+
+        Args:
+            root_path: Path to the repository root.
+            workspace: Optional LimbWorkspace providing a virtualized overlay of
+                      uncommitted changes.
+        """
+        self.root_path = root_path.resolve()
+        self.src_dir = self.root_path / "src"
+        self.workspace = workspace
+
+        self.symbols: dict[str, dict[str, Any]] = {}
+        self.domain_map = self._load_domain_map()
+        self.entry_point_patterns = self._load_entry_point_patterns()
+
+    def _load_domain_map(self) -> dict[str, str]:
+        """
+        Loads the architectural domain map.
+        Source structure file has been removed — returns empty map.
+        Callers fall back to heuristic domain detection.
+        """
+        return {}
+
+    def _load_entry_point_patterns(self) -> list[dict[str, Any]]:
+        """
+        Loads entry point patterns.
+        Patterns file has been removed — returns empty list.
+        """
+        return []
+
+    # ID: df77032e-a986-4846-8c38-9849daabe695
+    def build(self) -> dict[str, Any]:
+        """
+        Executes the full scan and returns the in-memory graph.
+
+        If a workspace is present, it builds a "Shadow Graph" that merges
+        uncommitted changes with the existing codebase.
+        """
+        mode = "SHADOW" if self.workspace else "STANDARD"
+        logger.info("Building knowledge graph (%s mode) for: %s", mode, self.root_path)
+
+        self.symbols = {}
+
+        if self.workspace:
+            files_to_scan = self.workspace.list_files(directory="src", pattern="*.py")
+        else:
+            if not self.src_dir.exists():
+                logger.warning("Source directory not found: %s", self.src_dir)
+                return {"metadata": {}, "symbols": {}}
+
+            files_to_scan = [
+                str(p.relative_to(self.root_path)) for p in self.src_dir.rglob("*.py")
+            ]
+
+        for rel_path in files_to_scan:
+            self._scan_file_v2(rel_path)
+
+        return {
+            "metadata": {
+                "generated_at": datetime.now(UTC).isoformat(),
+                "repo_root": str(self.root_path),
+                "symbol_count": len(self.symbols),
+                "mode": mode,
+            },
+            "symbols": self.symbols,
+        }
+
+    def _scan_file_v2(self, rel_path: str) -> None:
+        """Scans a file using the sensory overlay (workspace if available)."""
+        try:
+            if self.workspace:
+                content = self.workspace.read_text(rel_path)
+            else:
+                content = (self.root_path / rel_path).read_text(encoding="utf-8")
+
+            tree = ast.parse(content, filename=rel_path)
+            source_lines = content.splitlines()
+
+            for node in ast.walk(tree):
+                if isinstance(
+                    node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+                ):
+                    self._process_symbol(node, Path(rel_path), source_lines)
+
+        except Exception as e:
+            logger.error("Failed to process file %s: %s", rel_path, e)
+
+    def _determine_domain(self, file_path: Path) -> str:
+        """Determines the architectural domain of a file (file_path is relative to root)."""
+        abs_file_path = (self.root_path / file_path).resolve()
+
+        parts = file_path.parts
+        if "features" in parts:
+            idx = parts.index("features")
+            if idx + 1 < len(parts):
+                candidate = parts[idx + 1]
+                if candidate and not candidate.endswith(".py"):
+                    return candidate
+
+        for domain_path, domain_name in self.domain_map.items():
+            try:
+                if str(abs_file_path).startswith(str(Path(domain_path).resolve())):
+                    return domain_name
+            except Exception as e:
+                logger.debug(
+                    "Domain map resolution failed for %s against %s: %s",
+                    abs_file_path,
+                    domain_path,
+                    e,
+                )
+                continue
+
+        return "unknown"
+
+    def _process_symbol(
+        self, node: ast.AST, rel_path: Path, source_lines: list[str]
+    ) -> None:
+        """Extracts metadata for a symbol."""
+        name = getattr(node, "name", None)
+        if not isinstance(name, str) or not name:
+            return
+
+        symbol_path_key = f"{rel_path.as_posix()}::{name}"
+
+        metadata = parse_metadata_comment(node, source_lines) or {}
+        docstring = (extract_docstring(node) or "").strip()
+
+        call_visitor = FunctionCallVisitor()
+        try:
+            call_visitor.visit(node)
+        except Exception as e:
+            logger.debug(
+                "FunctionCallVisitor failed on %s::%s — skipping call extraction: %s",
+                rel_path.as_posix(),
+                name,
+                e,
+            )
+
+        symbol_data: dict[str, Any] = {
+            "uuid": symbol_path_key,
+            "key": metadata.get("capability"),
+            "symbol_path": symbol_path_key,
+            "name": name,
+            "type": type(node).__name__,
+            "file_path": rel_path.as_posix(),
+            "domain": self._determine_domain(rel_path),
+            "is_public": not name.startswith("_"),
+            "title": name.replace("_", " ").title(),
+            "description": docstring.split("\n")[0] if docstring else None,
+            "docstring": docstring,
+            "calls": sorted(set(getattr(call_visitor, "calls", []) or [])),
+            "line_number": getattr(node, "lineno", 0),
+            "end_line_number": getattr(node, "end_lineno", getattr(node, "lineno", 0)),
+            "is_async": isinstance(node, ast.AsyncFunctionDef),
+            "parameters": extract_parameters(node) if hasattr(node, "args") else [],
+            "is_class": isinstance(node, ast.ClassDef),
+            "base_classes": (
+                extract_base_classes(node) if isinstance(node, ast.ClassDef) else []
+            ),
+            "structural_hash": calculate_structural_hash(node),
+        }
+
+        self.symbols[symbol_path_key] = symbol_data