# Pseudo-code for src/cgis/storage/vector_base.py
from abc import ABC, abstractmethod
from typing import List, Tuple

class BaseVectorStore(ABC):
    @abstractmethod
    def connect(self) -> None:
        pass

    @abstractmethod
    def upsert_embeddings(self, records: List[Tuple[str, List[float]]]) -> None:
        """Upserts a batch of (node_fqn, embedding_vector) records."""
        pass

    @abstractmethod
    def delete_embeddings(self, node_fqns: List[str]) -> None:
        """Deletes embeddings for specific FQNs (used during incremental updates)."""
        pass

    @abstractmethod
    def search_similarity(self, query_vector: List[float], limit: int = 5) -> List[Tuple[str, float]]:
        """Returns List of (node_fqn, cosine_similarity_score)."""
        pass

# Pseudo-code for src/cgis/pipeline.py

def _persist_incremental(self, store: SQLiteStore, vector_store: BaseVectorStore, changed_files: Dict[str, str], ...):
    # 1. Save SQLite graph atomically as usual
    store.save_incremental_batch(...)
    
    # 2. Extract and generate embeddings ONLY for modified nodes
    embedding_records = []
    for node in all_nodes:
        if node.file_path in changed_files:
            # Construct semantic text payload (FQN + Docstring or Name)
            docstring = node.metadata.get("docstring", "")
            payload = f"Node FQN: {node.id}\nType: {node.type.value}\nDescription: {docstring or node.name}"
            
            # Generate embedding vector (using local fast-embed or external API)
            vector = self._embedding_service.embed_text(payload)
            embedding_records.append((node.id, vector))

    # 3. Upsert to Vector Database
    if embedding_records:
        # First, delete old stale embeddings for these FQNs
        stale_fqns = [record[0] for record in embedding_records]
        vector_store.delete_embeddings(stale_fqns)
        vector_store.upsert_embeddings(embedding_records)

# Pseudo-code for src/cgis/query/hybrid.py

class HybridRetriever:
    def __init__(self, store: SQLiteStore, vector_store: BaseVectorStore, embedding_service):
        self.store = store
        self.vector_store = vector_store
        self.embedding_service = embedding_service
        self.query_engine = QueryEngine(store)

    def retrieve_context(self, query_text: str, limit: int = 3) -> dict:
        """
        Executes a hybrid semantic-structural query.
        """
        # 1. Generate query embedding vector
        query_vector = self.embedding_service.embed_text(query_text)
        
        # 2. Query Vector DB for top semantic matches
        matches = self.vector_store.search_similarity(query_vector, limit=limit)
        
        results = []
        
        # 3. For each matched FQN, pull its structural and behavioral call graphs
        for fqn, score in matches:
            node = self.store.get_node(fqn)
            if node:
                # Retrieve execution flow graph (depth 1 to save tokens)
                nodes, edges = self.query_engine.get_flow_graph(fqn, max_depth=1)
                
                results.append({
                    "focal_node": node,
                    "similarity_score": score,
                    "subgraph": {"nodes": nodes, "edges": edges}
                })
                
        return {"query": query_text, "results": results}