velune-cli 0.9.0__py3-none-any.whl

velune/retrieval/slow_path.py

@@ -0,0 +1,364 @@
+"""Slow path retriever: deep graph traversal (< 2000ms, HIGH complexity only)."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+logger = logging.getLogger("velune.retrieval.slow_path")
+
+
+class SlowPathRetriever:
+    """Slow path using deep graph traversal and contextual search."""
+
+    # Traversal limits
+    CALLS_DEPTH = 2
+    IMPORTS_DEPTH = 1
+    TARGET_LATENCY_MS = 2000
+
+    def __init__(
+        self,
+        fast_path_retriever: Any,
+        import_graph: Any,
+        call_graph: Any,
+        episodic_memory: Any,
+        lineage_memory: Any,
+    ) -> None:
+        """Initialize slow path retriever.
+
+        Parameters
+        ----------
+        fast_path_retriever:
+            FastPathRetriever instance (to reuse results)
+        import_graph:
+            Import graph for traversal
+        call_graph:
+            Call graph for traversal
+        episodic_memory:
+            Episodic memory for context
+        lineage_memory:
+            Lineage memory for decisions/failures
+        """
+        self.fast_path = fast_path_retriever
+        self.import_graph = import_graph
+        self.call_graph = call_graph
+        self.episodic_memory = episodic_memory
+        self.lineage_memory = lineage_memory
+
+    async def retrieve(
+        self,
+        query: str,
+        fast_results: list[Any],
+        budget: Any,
+        workspace_root: str = "",
+    ) -> list[Any]:
+        """Run slow path retrieval (< 2000ms).
+
+        Steps:
+        1. Identify high-blast-radius nodes from fast path
+        2. Traverse CALLS edges (depth 2)
+        3. Traverse IMPORTS edges (depth 1)
+        4. Search episodic memory for sessions mentioning these nodes
+        5. Retrieve lineage decisions/failures
+        6. Return new chunks not in fast path
+
+        Parameters
+        ----------
+        query:
+            Query text (for logging/context)
+        fast_results:
+            Results from fast path (starting points)
+        budget:
+            Context budget
+        workspace_root:
+            Workspace root for scoping
+
+        Returns
+        -------
+        list[ContextChunk]:
+            Additional chunks from slow path
+        """
+        start_time = time.perf_counter()
+
+        chunks: list[Any] = []
+
+        # Step 1: Identify high-blast-radius nodes
+        blast_radius_nodes = self._identify_high_blast_radius_nodes(fast_results)
+        logger.debug(f"Identified {len(blast_radius_nodes)} high-blast-radius nodes")
+
+        # Step 2: Traverse CALLS edges
+        call_graph_results = await self._traverse_call_graph(blast_radius_nodes)
+        chunks.extend(call_graph_results)
+
+        # Step 3: Traverse IMPORTS edges
+        import_graph_results = await self._traverse_import_graph(blast_radius_nodes)
+        chunks.extend(import_graph_results)
+
+        # Step 4: Search episodic memory
+        episodic_results = await self._search_episodic_context(blast_radius_nodes, workspace_root)
+        chunks.extend(episodic_results)
+
+        # Step 5: Retrieve lineage decisions
+        lineage_results = await self._retrieve_lineage_context(blast_radius_nodes)
+        chunks.extend(lineage_results)
+
+        # Filter: keep only chunks not already in fast_results
+        fast_ids = {r.id for r in fast_results}
+        filtered_chunks = [c for c in chunks if c.id not in fast_ids]
+
+        elapsed_ms = (time.perf_counter() - start_time) * 1000
+        logger.debug(f"Slow path complete: {len(filtered_chunks)} new chunks in {elapsed_ms:.0f}ms")
+
+        if elapsed_ms > self.TARGET_LATENCY_MS:
+            logger.warning(
+                f"Slow path exceeded target latency: {elapsed_ms:.0f}ms > {self.TARGET_LATENCY_MS}ms"
+            )
+
+        return filtered_chunks
+
+    def _identify_high_blast_radius_nodes(self, fast_results: list[Any]) -> list[str]:
+        """Identify high-blast-radius nodes from fast path results.
+
+        High-blast-radius: files/symbols that many other nodes depend on.
+
+        Parameters
+        ----------
+        fast_results:
+            Fast path results
+
+        Returns
+        -------
+        list[str]:
+            Node IDs to traverse from
+        """
+        nodes = []
+
+        for result in fast_results:
+            # Extract node ID from metadata
+            node_id = result.metadata.get("symbol_id") or result.metadata.get("path")
+            if node_id:
+                nodes.append(node_id)
+
+        return nodes[:10]  # Limit to top 10
+
+    async def _traverse_call_graph(self, start_nodes: list[str]) -> list[Any]:
+        """Traverse call graph from starting nodes.
+
+        Parameters
+        ----------
+        start_nodes:
+            Starting node IDs
+
+        Returns
+        -------
+        list[ContextChunk]:
+            Chunks from call graph traversal
+        """
+        from velune.retrieval.pipeline import ContextChunk
+
+        chunks = []
+
+        try:
+            # Traverse from each node
+            for node_id in start_nodes:
+                # Get callers (who calls this function)
+                callers = await self.call_graph.get_neighbors(
+                    node=node_id,
+                    depth=self.CALLS_DEPTH,
+                    direction="incoming",  # Who calls this
+                )
+
+                # Add as chunks
+                for caller in callers:
+                    chunk = ContextChunk(
+                        id=f"callgraph_{caller.get('id')}",
+                        source="call_graph",
+                        content=f"Function: {caller.get('name')}\nCalls: {node_id}",
+                        metadata={
+                            "node_id": caller.get("id"),
+                            "tokens": 50,
+                        },
+                        relevance_score=0.3,
+                    )
+                    chunks.append(chunk)
+
+            logger.debug(f"Call graph traversal found {len(chunks)} results")
+            return chunks
+
+        except Exception as e:
+            logger.debug(f"Call graph traversal failed: {e}")
+            return []
+
+    async def _traverse_import_graph(self, start_nodes: list[str]) -> list[Any]:
+        """Traverse import graph from starting nodes.
+
+        Parameters
+        ----------
+        start_nodes:
+            Starting node IDs (file paths)
+
+        Returns
+        -------
+        list[ContextChunk]:
+            Chunks from import graph traversal
+        """
+        from velune.retrieval.pipeline import ContextChunk
+
+        chunks = []
+
+        try:
+            # Traverse from each node
+            for node_id in start_nodes:
+                # Get import neighbors
+                neighbors = await self.import_graph.get_neighbors(
+                    node=node_id,
+                    depth=self.IMPORTS_DEPTH,
+                    edge_type="imports",
+                )
+
+                # Add as chunks
+                for neighbor in neighbors:
+                    chunk = ContextChunk(
+                        id=f"imports_{neighbor.get('id')}",
+                        source="import_graph",
+                        content=f"Module: {neighbor.get('path')}\nImports: {node_id}",
+                        metadata={
+                            "node_id": neighbor.get("id"),
+                            "path": neighbor.get("path"),
+                            "tokens": 50,
+                        },
+                        relevance_score=0.25,
+                    )
+                    chunks.append(chunk)
+
+            logger.debug(f"Import graph traversal found {len(chunks)} results")
+            return chunks
+
+        except Exception as e:
+            logger.debug(f"Import graph traversal failed: {e}")
+            return []
+
+    async def _search_episodic_context(
+        self,
+        node_ids: list[str],
+        workspace_root: str,
+    ) -> list[Any]:
+        """Search episodic memory for sessions mentioning these nodes.
+
+        Parameters
+        ----------
+        node_ids:
+            Node IDs to search for
+        workspace_root:
+            Workspace root for scoping
+
+        Returns
+        -------
+        list[ContextChunk]:
+            Chunks from episodic memory
+        """
+        from velune.retrieval.pipeline import ContextChunk
+
+        chunks = []
+
+        try:
+            # Search for sessions mentioning these nodes
+            for node_id in node_ids:
+                # Convert node ID to searchable form
+                search_term = node_id.split("/")[-1]  # Get filename
+
+                # LIKE search in episodic memory
+                results = await self.episodic_memory.search_turns(
+                    pattern=f"%{search_term}%",
+                    limit=3,
+                )
+
+                # Add as chunks
+                for result in results:
+                    chunk = ContextChunk(
+                        id=f"episodic_{result.get('turn_id')}",
+                        source="episodic",
+                        content=result.get("content", ""),
+                        metadata={
+                            "turn_id": result.get("turn_id"),
+                            "session_id": result.get("session_id"),
+                            "tokens": len(result.get("content", "")) // 4,
+                        },
+                        relevance_score=0.35,
+                    )
+                    chunks.append(chunk)
+
+            logger.debug(f"Episodic context search found {len(chunks)} results")
+            return chunks
+
+        except Exception as e:
+            logger.debug(f"Episodic context search failed: {e}")
+            return []
+
+    async def _retrieve_lineage_context(self, node_ids: list[str]) -> list[Any]:
+        """Retrieve lineage decisions/failures related to these nodes.
+
+        Parameters
+        ----------
+        node_ids:
+            Node IDs to search for
+
+        Returns
+        -------
+        list[ContextChunk]:
+            Chunks from lineage memory
+        """
+        from velune.retrieval.pipeline import ContextChunk
+
+        chunks = []
+
+        try:
+            # Search lineage for decisions/failures
+            for node_id in node_ids:
+                # Get related decisions
+                decisions = await self.lineage_memory.get_decisions(
+                    node_id=node_id,
+                    limit=2,
+                )
+
+                for decision in decisions:
+                    chunk = ContextChunk(
+                        id=f"lineage_decision_{decision.get('id')}",
+                        source="lineage",
+                        content=f"Decision: {decision.get('summary')}\nReason: {decision.get('reasoning')}",
+                        metadata={
+                            "decision_id": decision.get("id"),
+                            "node_id": node_id,
+                            "tokens": len(decision.get("reasoning", "")) // 4,
+                        },
+                        relevance_score=0.45,
+                    )
+                    chunks.append(chunk)
+
+                # Get related failures
+                failures = await self.lineage_memory.get_failures(
+                    node_id=node_id,
+                    limit=2,
+                )
+
+                for failure in failures:
+                    chunk = ContextChunk(
+                        id=f"lineage_failure_{failure.get('id')}",
+                        source="lineage",
+                        content=f"Failure: {failure.get('summary')}\nMitigation: {failure.get('mitigation')}",
+                        metadata={
+                            "failure_id": failure.get("id"),
+                            "node_id": node_id,
+                            "tokens": len(failure.get("mitigation", "")) // 4,
+                        },
+                        relevance_score=0.4,
+                    )
+                    chunks.append(chunk)
+
+            logger.debug(f"Lineage context retrieval found {len(chunks)} results")
+            return chunks
+
+        except Exception as e:
+            logger.debug(f"Lineage context retrieval failed: {e}")
+            return []

velune/retrieval/vector.py

@@ -0,0 +1,203 @@
+"""Vector retrieval layer using Qdrant client.
+
+The Qdrant client and its compiled backend are resolved lazily so that wiring
+this retriever during bootstrap costs nothing. A ``client_provider`` callable
+is preferred over a concrete ``client``: it lets us share the semantic tier's
+single Qdrant connection (two clients on the same local path would deadlock the
+store) without forcing that connection to open at startup.
+"""
+
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from velune.retrieval.schemas import RetrievalDocument, RetrievalHit, RetrievalSource
+
+logger = logging.getLogger("velune.retrieval.vector")
+
+
+def _qmodels() -> Any:
+    """Lazily import qdrant http models (defers the qdrant_client import)."""
+    from qdrant_client.http import models as qmodels
+
+    return qmodels
+
+
+class VectorRetriever:
+    """Retrieves context from Qdrant vector database using dense embeddings."""
+
+    def __init__(
+        self,
+        collection_name: str = "velune_symbols",
+        location: str = ".velune/qdrant_local_store",
+        client: Any | None = None,
+        client_provider: Callable[[], Any] | None = None,
+    ) -> None:
+        self.collection_name = collection_name
+        self.location = location
+        self._client = client
+        self._client_provider = client_provider
+        self._client_resolved = client is not None
+        self._detected_dimension: int | None = None
+
+    @property
+    def client(self) -> Any:
+        """Resolve the Qdrant client on first use (provider > location)."""
+        if not self._client_resolved:
+            self._client_resolved = True
+            if self._client_provider is not None:
+                self._client = self._client_provider()
+            else:
+                from qdrant_client import QdrantClient
+
+                loc = self.location
+                if loc.startswith(".") or "/" in loc or "\\" in loc:
+                    self._client = QdrantClient(path=loc)
+                else:
+                    self._client = QdrantClient(location=loc)
+        return self._client
+
+    def _ensure_collection_for_dimension(self, dim: int) -> None:
+        """Create or verify collection for the given dimension."""
+        if self._detected_dimension == dim:
+            return  # Already configured
+
+        client = self.client
+        if client is None:
+            return  # Degraded mode — no vector backend available
+        qmodels = _qmodels()
+
+        try:
+            collections = client.get_collections().collections
+            existing = next((c for c in collections if c.name == self.collection_name), None)
+
+            if existing:
+                # Check if dimension matches
+                info = client.get_collection(self.collection_name)
+                existing_dim = info.config.params.vectors.size
+                if existing_dim != dim:
+                    logger.warning(
+                        "Embedding dimension changed from %d to %d. "
+                        "Recreating collection '%s'. Existing vectors lost.",
+                        existing_dim,
+                        dim,
+                        self.collection_name,
+                    )
+                    client.delete_collection(self.collection_name)
+                    existing = None
+
+            if not existing:
+                client.create_collection(
+                    collection_name=self.collection_name,
+                    vectors_config=qmodels.VectorParams(size=dim, distance=qmodels.Distance.COSINE),
+                )
+                logger.info(
+                    "Collection '%s' initialized with dimension %d", self.collection_name, dim
+                )
+
+            self._detected_dimension = dim
+        except Exception as e:
+            logger.error("Failed to ensure collection for dimension %d: %s", dim, e)
+
+    def upsert(self, doc: RetrievalDocument) -> None:
+        """Inserts or updates a document with its embedding in Qdrant."""
+        if not doc.embedding:
+            return
+
+        dim = len(doc.embedding)
+        self._ensure_collection_for_dimension(dim)
+
+        client = self.client
+        if client is None:
+            return
+        qmodels = _qmodels()
+        try:
+            client.upsert(
+                collection_name=self.collection_name,
+                points=[
+                    qmodels.PointStruct(
+                        id=hash(doc.id) % (2**63 - 1),  # Map string ID to uint64
+                        vector=doc.embedding,  # exact length, no padding
+                        payload={
+                            "doc_id": doc.id,
+                            "content": doc.content,
+                            "namespace": doc.namespace,
+                            **doc.metadata,
+                        },
+                    )
+                ],
+            )
+        except Exception as e:
+            logger.error("Failed to upsert document: %s", e)
+
+    def retrieve(
+        self, query_vector: list[float], top_k: int = 10, namespace: str | None = None
+    ) -> list[RetrievalHit]:
+        """Queries Qdrant vector spaces and returns matching document hits."""
+        client = self.client
+        if client is None:
+            return []  # Degraded mode — no vector backend available
+        qmodels = _qmodels()
+
+        if not self._detected_dimension:
+            try:
+                collections = client.get_collections().collections
+                existing = any(c.name == self.collection_name for c in collections)
+                if existing:
+                    info = client.get_collection(self.collection_name)
+                    self._detected_dimension = info.config.params.vectors.size
+                else:
+                    return []
+            except Exception:
+                return []
+
+        if self._detected_dimension and len(query_vector) != self._detected_dimension:
+            logger.error(
+                "Query dimension mismatch — skipping vector retrieval. "
+                "Query dimension %d != collection dimension %d.",
+                len(query_vector),
+                self._detected_dimension,
+            )
+            return []
+
+        hits: list[RetrievalHit] = []
+        try:
+            # Build filters
+            query_filter = None
+            if namespace:
+                query_filter = qmodels.Filter(
+                    must=[
+                        qmodels.FieldCondition(
+                            key="namespace", match=qmodels.MatchValue(value=namespace)
+                        )
+                    ]
+                )
+
+            results = client.query_points(
+                collection_name=self.collection_name,
+                query=query_vector,
+                query_filter=query_filter,
+                limit=top_k,
+            ).points
+
+            for rank, res in enumerate(results):
+                payload = res.payload or {}
+                doc = RetrievalDocument(
+                    id=payload.get("doc_id", str(res.id)),
+                    content=payload.get("content", ""),
+                    namespace=payload.get("namespace", "default"),
+                    metadata={
+                        k: v
+                        for k, v in payload.items()
+                        if k not in ("doc_id", "content", "namespace")
+                    },
+                )
+                hits.append(
+                    RetrievalHit(
+                        document=doc, score=res.score, source=RetrievalSource.VECTOR, rank=rank + 1
+                    )
+                )
+        except Exception as e:
+            logger.error("Failed to retrieve matching documents from Qdrant: %s", e)
+
+        return hits

velune/telemetry/__init__.py

@@ -0,0 +1,59 @@
+"""Telemetry package for Velune CLI.
+
+Provides structured logging, span tracking, and usage analytics.
+"""
+
+from __future__ import annotations
+
+from velune.telemetry.cognition import CognitivePerformanceAnalytics
+from velune.telemetry.debug import (
+    DebugTimer,
+    PipelineMetrics,
+    RoutingDecision,
+    TokenCounter,
+    debug_timer,
+    log_debug_info,
+)
+from velune.telemetry.doctor import (
+    get_telemetry_status,
+    print_provider_health_report,
+    print_telemetry_report,
+)
+from velune.telemetry.logging import bind_context, clear_context, configure_logging, context_scope
+from velune.telemetry.spans import (
+    SpanContext,
+    async_span,
+    create_run_id,
+    create_span_id,
+    get_current_run_id,
+    get_current_span_id,
+    span,
+)
+from velune.telemetry.usage_tracker import SessionUsageTracker, UsageSummary, get_tracker
+
+__all__ = [
+    "CognitivePerformanceAnalytics",
+    "configure_logging",
+    "bind_context",
+    "clear_context",
+    "context_scope",
+    "SpanContext",
+    "create_run_id",
+    "create_span_id",
+    "get_current_run_id",
+    "get_current_span_id",
+    "span",
+    "async_span",
+    "SessionUsageTracker",
+    "get_tracker",
+    "UsageSummary",
+    "DebugTimer",
+    "debug_timer",
+    "TokenCounter",
+    "RoutingDecision",
+    "PipelineMetrics",
+    "log_debug_info",
+    "print_telemetry_report",
+    "get_telemetry_status",
+    "print_provider_health_report",
+]