codegraph-engine 2.1.1__py3-none-any.whl

codegraph/memory/__init__.py

@@ -0,0 +1,3 @@
+from .store import MemoryStore
+
+__all__ = ["MemoryStore"]

codegraph/memory/store.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import builtins
+import sqlite3
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+
+class MemoryStore:
+    def __init__(self, db_path: Path) -> None:
+        self.db_path = db_path
+        with self.session() as con:
+            con.execute("CREATE TABLE IF NOT EXISTS memory (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+
+    def connect(self) -> sqlite3.Connection:
+        return sqlite3.connect(self.db_path)
+
+    @contextmanager
+    def session(self) -> Iterator[sqlite3.Connection]:
+        con = self.connect()
+        try:
+            yield con
+            con.commit()
+        except BaseException:
+            con.rollback()
+            raise
+        finally:
+            con.close()
+
+    def list(self) -> builtins.list[tuple[str, str]]: 
+        with self.session() as con:
+            return list(con.execute("SELECT key, value FROM memory ORDER BY key"))
+
+    def search(self, query: str, limit: int = 20) -> builtins.list[tuple[str, str]]: 
+        if not query.strip():
+            raise ValueError("memory query must be non-empty")
+        with self.session() as con:
+            return list(con.execute(
+                "SELECT key, value FROM memory WHERE key LIKE ? OR value LIKE ? ORDER BY key LIMIT ?",
+                (f"%{query}%", f"%{query}%", limit),
+            ))
+
+    def clear(self) -> None:
+        with self.session() as con:
+            con.execute("DELETE FROM memory")

codegraph/models.py

@@ -0,0 +1,289 @@
+"""Unified domain models for the CodeGraph intelligence engine."""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Literal
+
+from pydantic import BaseModel
+
+from codegraph.graph.models import GraphEdge
+from codegraph.indexing.models import (
+    CallRef,
+    Chunk,
+    ImportRef,
+    InheritanceRef,
+    Reference,
+    Symbol,
+    build_canonical_id,
+    normalize_module,
+)
+
+Import = ImportRef
+Call = CallRef
+
+NodeType = Literal[
+    "FILE",
+    "MODULE",
+    "CLASS",
+    "FUNCTION",
+    "METHOD",
+    "API_ENDPOINT",
+    "API",
+    "TEST",
+    "TYPE",
+    "CONFIG",
+    "EXTERNAL_SERVICE",
+]
+
+EdgeType = Literal[
+    "DEFINES",
+    "CONTAINS",
+    "IMPORTS",
+    "EXPORTS",
+    "REEXPORTS",
+    "CALLS",
+    "CALLED_BY",
+    "POSSIBLE_CALLS",
+    "REFERENCES",
+    "EXTENDS",
+    "IMPLEMENTS",
+    "USES",
+    "ROUTES_TO",
+    "TESTS",
+    "DEPENDS_ON",
+    "CONFIGURES",
+]
+
+ErrorCategory = Literal[
+    "INVALID_INPUT",
+    "NOT_FOUND",
+    "SECURITY_DENIED",
+    "STALE_INDEX",
+    "INDEX_STALE",
+    "INDEX_UNAVAILABLE",
+    "PARSER_ERROR",
+    "UNSUPPORTED_LANGUAGE",
+    "STORAGE_ERROR",
+    "INTERNAL_ERROR",
+]
+
+
+@dataclass(frozen=True)
+class Repository:
+    path: str
+    name: str
+    head_commit: str | None = None
+    branch: str | None = None
+
+
+@dataclass(frozen=True)
+class File:
+    path: str
+    hash: str
+    language: str
+    indexed_at: int = 0
+    status: str = "ok"  # ok | parse_failed
+    parse_error: str | None = None
+
+
+@dataclass(frozen=True)
+class SymbolLocation:
+    canonical_id: str
+    path: str
+    start_line: int
+    end_line: int
+    source_hash: str = ""
+
+
+@dataclass(frozen=True)
+class GraphNode:
+    node_id: str
+    node_type: str
+    name: str
+    file: str | None = None
+    start_line: int | None = None
+    end_line: int | None = None
+    metadata: dict[str, object] = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class RepositorySnapshot:
+    repository: str
+    indexed_commit: str | None
+    current_commit: str | None
+    parser_version: str
+    schema_version: int
+    index_generation: int
+    timestamp: int
+    file_count: int
+    symbol_count: int
+    reference_count: int
+
+
+@dataclass(frozen=True)
+class FreshnessState:
+    status: str  # FRESH | PARTIALLY_STALE | STALE | UNKNOWN
+    indexed_commit: str | None
+    current_commit: str | None
+    modified_files: list[str]
+    deleted_files: list[str]
+    added_files: list[str]
+    parse_failed_files: list[str]
+    detail: str
+
+
+@dataclass(frozen=True)
+class ContextCandidate:
+    file: str
+    symbol: str | None
+    canonical_id: str | None
+    kind: str
+    start_line: int
+    end_line: int
+    snippet: str
+    confidence: str = "HIGH"
+    freshness: str = "FRESH"
+    relationship: str = ""
+    distance: int = 0
+    score: float = 0.0
+
+
+class TestRelationship(BaseModel):
+    schema_version: str = "1.0"
+    file: str
+    symbol: str | None = None
+    target_symbol: str | None = None
+    classification: str = "VERIFIED_TEST"  # VERIFIED_TEST | POSSIBLE_TEST
+    relationship: str
+    confidence: str
+    start_line: int = 1
+    evidence: str
+
+
+class ImpactItem(BaseModel):
+    symbol: str | None = None
+    file: str
+    impact_type: str  # direct | indirect | potential | test | api | config | doc
+    relationship: str = "CALLS"
+    confidence: str = "HIGH"
+    label: str = "verified"  # verified | inferred | possible
+    distance: int = 1
+    line: int = 1
+    evidence: str = ""
+
+
+class ImpactResult(BaseModel):
+    schema_version: str = "2.0"
+    subject: str
+    canonical_id: str | None = None
+    direct_callers: list[dict[str, object]] = []
+    transitive_callers: list[dict[str, object]] = []
+    directly_affected: list[dict[str, object]] = []
+    indirectly_affected: list[dict[str, object]] = []
+    potential: list[dict[str, object]] = []
+    dependencies: list[dict[str, object]] = []
+    dependent_modules: list[dict[str, object]] = []
+    related_apis: list[dict[str, object]] = []
+    related_tests: list[dict[str, object]] = []
+    configuration: list[dict[str, object]] = []
+    documentation: list[dict[str, object]] = []
+    recent_modifications: list[dict[str, object]] = []
+    evidence: list[dict[str, object]] = []
+    label_legend: dict[str, str] = {}
+    note: str = (
+        "Static analysis cannot confirm runtime behavior. "
+        "Do not assert failure solely from static dependency data."
+    )
+
+    def as_dict(self) -> dict[str, object]:
+        return self.model_dump()
+
+
+class ArchitectureNode(BaseModel):
+    id: str
+    name: str
+    layer: str  # entry_point | route | controller | service | repository | model | config | test | external
+    file: str
+    line: int = 1
+    confidence: str = "HIGH"
+
+
+class ArchitectureEdge(BaseModel):
+    source: str
+    target: str
+    relationship: str
+    confidence: str = "HIGH"
+    evidence: str = ""
+
+
+class MCPError(BaseModel):
+    schema_version: str = "1.0"
+    error_code: ErrorCategory
+    message: str
+    details: dict[str, object] = {}
+
+    def as_dict(self) -> dict[str, object]:
+        return self.model_dump()
+
+
+@dataclass
+class ObservabilityMetrics:
+    index_duration_ms: float = 0.0
+    files_scanned: int = 0
+    files_changed: int = 0
+    files_unchanged: int = 0
+    files_removed: int = 0
+    files_parse_failed: int = 0
+    symbols_count: int = 0
+    references_count: int = 0
+    graph_edges_count: int = 0
+    search_latency_ms: float = 0.0
+    context_compile_latency_ms: float = 0.0
+    database_size_bytes: int = 0
+    cache_hits: int = 0
+    cache_misses: int = 0
+
+    @property
+    def cache_hit_rate(self) -> float:
+        total = self.cache_hits + self.cache_misses
+        return round(self.cache_hits / total, 3) if total > 0 else 0.0
+
+    def as_dict(self) -> dict[str, object]:
+        d = asdict(self)
+        d["cache_hit_rate"] = self.cache_hit_rate
+        return d
+
+
+__all__ = [
+    "ArchitectureEdge",
+    "ArchitectureNode",
+    "Call",
+    "CallRef",
+    "Chunk",
+    "ContextCandidate",
+    "EdgeType",
+    "ErrorCategory",
+    "File",
+    "FreshnessState",
+    "GraphEdge",
+    "GraphNode",
+    "ImpactItem",
+    "ImpactResult",
+    "Import",
+    "ImportRef",
+    "InheritanceRef",
+    "MCPError",
+    "NodeType",
+    "ObservabilityMetrics",
+    "Reference",
+    "Repository",
+    "RepositorySnapshot",
+    "Symbol",
+    "SymbolLocation",
+    "TestRelationship",
+    "build_canonical_id",
+    "normalize_module",
+]

codegraph/observability.py

@@ -0,0 +1,151 @@
+"""Production Observability and Structured Metrics.
+
+Invariants:
+- Never log raw repository source code.
+- Never log secrets or credentials.
+- Zero network dependencies or cloud uploads.
+- Structured metrics buffer available locally for audits, benchmarks, and doctor diagnostics.
+"""
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass
+class ExecutionTiming:
+    planning_ms: float = 0.0
+    search_ms: float = 0.0
+    graph_ms: float = 0.0
+    framework_ms: float = 0.0
+    tests_ms: float = 0.0
+    git_ms: float = 0.0
+    evidence_ms: float = 0.0
+    ranking_ms: float = 0.0
+    compilation_ms: float = 0.0
+    serialization_ms: float = 0.0
+    total_ms: float = 0.0
+
+    def as_dict(self) -> dict[str, float]:
+        return {
+            "planning_ms": round(self.planning_ms, 2),
+            "search_ms": round(self.search_ms, 2),
+            "graph_ms": round(self.graph_ms, 2),
+            "framework_ms": round(self.framework_ms, 2),
+            "tests_ms": round(self.tests_ms, 2),
+            "git_ms": round(self.git_ms, 2),
+            "evidence_ms": round(self.evidence_ms, 2),
+            "ranking_ms": round(self.ranking_ms, 2),
+            "compilation_ms": round(self.compilation_ms, 2),
+            "serialization_ms": round(self.serialization_ms, 2),
+            "total_ms": round(self.total_ms, 2),
+        }
+
+
+@dataclass
+class ExecutionMetadata:
+    latency_ms: float = 0.0
+    cache_hit: bool = False
+    index_generation: int = 0
+    candidate_count: int = 0
+    selected_count: int = 0
+    mode: str = "BALANCED"  # FAST | BALANCED | DEEP
+    timing: ExecutionTiming | None = None
+
+    def as_dict(self) -> dict[str, object]:
+        res: dict[str, object] = {
+            "latency_ms": round(self.latency_ms, 2),
+            "cache_hit": self.cache_hit,
+            "index_generation": self.index_generation,
+            "candidate_count": self.candidate_count,
+            "selected_count": self.selected_count,
+            "mode": self.mode,
+        }
+        if self.timing:
+            res["timing"] = self.timing.as_dict()
+        return res
+
+
+@dataclass
+class OperationMetric:
+    request_id: str
+    tool_or_op: str
+    latency_ms: float
+    index_generation: int = 0
+    cache_hit: bool = False
+    candidate_count: int = 0
+    selected_count: int = 0
+    estimated_tokens: int = 0
+    task_intent: str = "UNDERSTAND"
+    ambiguity_state: str = "CLEAR"
+    freshness: str = "FRESH"
+    error_class: str | None = None
+    timestamp: float = field(default_factory=time.time)
+
+    def as_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+class MetricsRegistry:
+    """Thread-safe, bounded in-memory metrics tracker."""
+
+    def __init__(self, max_records: int = 500) -> None:
+        self.max_records = max_records
+        self._records: list[OperationMetric] = []
+
+    def record(self, metric: OperationMetric) -> None:
+        self._records.append(metric)
+        if len(self._records) > self.max_records:
+            self._records = self._records[-self.max_records :]
+
+    def get_summary(self) -> dict[str, object]:
+        total = len(self._records)
+        if not total:
+            return {
+                "total_operations": 0,
+                "avg_latency_ms": 0.0,
+                "cache_hit_rate": 0.0,
+                "errors": 0,
+            }
+        avg_lat = sum(r.latency_ms for r in self._records) / total
+        cache_hits = sum(1 for r in self._records if r.cache_hit)
+        errors = sum(1 for r in self._records if r.error_class is not None)
+        return {
+            "total_operations": total,
+            "avg_latency_ms": round(avg_lat, 2),
+            "cache_hit_rate": round(cache_hits / total, 3),
+            "errors": errors,
+            "recent_operations": [r.as_dict() for r in self._records[-10:]],
+        }
+
+    def clear(self) -> None:
+        self._records.clear()
+
+
+# Global in-memory metrics registry for current process
+_GLOBAL_METRICS = MetricsRegistry()
+
+
+def get_global_metrics() -> MetricsRegistry:
+    return _GLOBAL_METRICS
+
+
+class Timer:
+    """Context manager for measuring latency with high precision."""
+
+    def __init__(self) -> None:
+        self.start_time = 0.0
+        self.elapsed_ms = 0.0
+
+    def __enter__(self) -> Timer:
+        self.start_time = time.perf_counter()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.elapsed_ms = (time.perf_counter() - self.start_time) * 1000.0
+
+
+def create_request_id() -> str:
+    return uuid.uuid4().hex[:12]