quantum-framework 0.18.0__py3-none-any.whl

quantum/runtime/knowledge_service.py

@@ -0,0 +1,546 @@
+"""
+Quantum Knowledge Service - RAG with ChromaDB + Ollama embeddings.
+
+Provides indexing, vector search, and RAG query capabilities for
+the q:knowledge / q:query knowledge: datasource integration.
+"""
+
+import os
+import re
+import glob
+import hashlib
+import logging
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+
+class KnowledgeError(Exception):
+    """Raised when knowledge base operations fail."""
+    pass
+
+
+class KnowledgeService:
+    """ChromaDB + Ollama embeddings service for RAG."""
+
+    def __init__(self, llm_service=None):
+        self.llm_service = llm_service
+        self._collections: Dict[str, Any] = {}  # name -> ChromaDB collection
+        self._client = None
+        self._ollama_base_url = os.getenv(
+            'QUANTUM_LLM_BASE_URL', 'http://localhost:11434'
+        ).rstrip('/')
+
+    def _get_client(self, persist: bool = False, persist_path: Optional[str] = None):
+        """Get or create ChromaDB client."""
+        if self._client is not None:
+            return self._client
+
+        try:
+            import chromadb
+        except ImportError:
+            raise KnowledgeError(
+                "q:knowledge needs the optional RAG dependencies, which are not "
+                "installed.\n"
+                "  pip install 'quantum-framework[rag]'   (or: pip install chromadb)\n"
+                "You also need an embedding model available on your LLM server, "
+                "e.g. `ollama pull nomic-embed-text`."
+            )
+
+        if persist and persist_path:
+            self._client = chromadb.PersistentClient(path=persist_path)
+        else:
+            self._client = chromadb.Client()
+
+        return self._client
+
+    @staticmethod
+    def _collection_name(name: str) -> str:
+        """A ChromaDB collection name for any q:knowledge name.
+
+        ChromaDB accepts 3-512 characters from [a-zA-Z0-9._-], starting and
+        ending alphanumeric. `<q:knowledge name="kb">` failed with ChromaDB's
+        own validation message. The prefix makes every name long enough and
+        keeps Quantum's collections recognisable in a shared store.
+        """
+        safe = re.sub(r'[^a-zA-Z0-9._-]', '-', str(name)).strip('._-') or 'base'
+        return f"quantum-{safe}"[:512]
+
+    @staticmethod
+    def _fingerprint(all_texts, embed_model, chunk_size, chunk_overlap) -> str:
+        """What the index was built from: texts, their sources, and chunking."""
+        digest = hashlib.sha256()
+        digest.update(f"{embed_model}|{chunk_size}|{chunk_overlap}".encode())
+        for item in all_texts:
+            digest.update(str(item.get('source', '')).encode())
+            digest.update(b'\x00')
+            digest.update(str(item.get('text', '')).encode())
+            digest.update(b'\x00')
+            digest.update(f"{item.get('chunk_size')}|{item.get('chunk_overlap')}".encode())
+        return digest.hexdigest()
+
+    def index_knowledge(
+        self,
+        name: str,
+        sources: list,
+        embed_model: str = "nomic-embed-text",
+        chunk_size: int = 500,
+        chunk_overlap: int = 50,
+        persist: bool = False,
+        persist_path: Optional[str] = None,
+        rebuild: bool = False,
+        database_service=None,
+        exec_context=None,
+    ):
+        """
+        Index knowledge base sources into ChromaDB.
+
+        Args:
+            name: Knowledge base name (used as collection name)
+            sources: List of KnowledgeSourceNode objects
+            embed_model: Ollama embedding model name
+            chunk_size: Characters per chunk
+            chunk_overlap: Overlap between chunks
+            persist: Whether to persist ChromaDB to disk
+            persist_path: Path for ChromaDB persistence
+            rebuild: Force reindex even if collection exists
+            database_service: DatabaseService for query-type sources
+            exec_context: ExecutionContext for variable resolution
+        """
+        client = self._get_client(persist, persist_path)
+
+        # Extract text first: whether the stored index is still valid depends
+        # on what the sources say NOW. Reading them is cheap; embedding is the
+        # expensive part, and that is what an unchanged fingerprint skips.
+        all_texts = []
+        for source in sources:
+            texts = self._extract_source_text(
+                source, database_service, exec_context
+            )
+            all_texts.extend(texts)
+
+        fingerprint = self._fingerprint(all_texts, embed_model, chunk_size, chunk_overlap)
+
+        # Knowledge bases persist by default (./.quantum/knowledge). The stored
+        # collection used to be reused whenever it had any chunks — so a base
+        # named "docs" indexed last week answered from last week's text, and
+        # changing the q:source did nothing. Measured: inline sources declared
+        # in a new file came back as chunks of docs/index.md from an earlier
+        # run. Reuse only when the fingerprint matches.
+        if not rebuild:
+            try:
+                existing = client.get_collection(self._collection_name(name))
+            except Exception:
+                existing = None
+            if existing is not None:
+                if (existing.count() > 0
+                        and (existing.metadata or {}).get("quantum_fingerprint") == fingerprint):
+                    self._collections[name] = existing
+                    logger.info(f"Knowledge base '{name}' already indexed ({existing.count()} chunks)")
+                    return
+                logger.info(f"Knowledge base '{name}': sources changed, reindexing")
+                rebuild = True
+
+        if rebuild:
+            try:
+                client.delete_collection(self._collection_name(name))
+            except Exception:
+                pass
+
+        collection = client.get_or_create_collection(
+            name=self._collection_name(name),
+            metadata={"hnsw:space": "cosine", "quantum_fingerprint": fingerprint}
+        )
+
+        if not all_texts:
+            logger.warning(f"Knowledge base '{name}': no text extracted from sources")
+            self._collections[name] = collection
+            return
+
+        # Chunk all extracted texts
+        all_chunks = []
+        all_metadata = []
+        for text_item in all_texts:
+            text = text_item['text']
+            source_label = text_item.get('source', 'inline')
+            cs = text_item.get('chunk_size', chunk_size)
+            co = text_item.get('chunk_overlap', chunk_overlap)
+
+            chunks = self._chunk_text(text, cs, co)
+            for i, chunk in enumerate(chunks):
+                all_chunks.append(chunk)
+                all_metadata.append({
+                    "source": source_label,
+                    "chunk_index": i,
+                    "total_chunks": len(chunks),
+                })
+
+        if not all_chunks:
+            self._collections[name] = collection
+            return
+
+        # Generate embeddings via Ollama
+        embeddings = self._generate_embeddings(all_chunks, embed_model)
+
+        # Generate IDs
+        ids = [
+            f"{name}_{hashlib.md5(chunk.encode()).hexdigest()[:12]}_{i}"
+            for i, chunk in enumerate(all_chunks)
+        ]
+
+        # Upsert into ChromaDB (batch to avoid limits)
+        batch_size = 100
+        for start in range(0, len(all_chunks), batch_size):
+            end = min(start + batch_size, len(all_chunks))
+            collection.upsert(
+                ids=ids[start:end],
+                documents=all_chunks[start:end],
+                embeddings=embeddings[start:end],
+                metadatas=all_metadata[start:end],
+            )
+
+        self._collections[name] = collection
+        logger.info(f"Knowledge base '{name}' indexed: {len(all_chunks)} chunks from {len(all_texts)} text segments")
+
+    def _extract_source_text(
+        self, source, database_service=None, exec_context=None
+    ) -> List[Dict[str, Any]]:
+        """
+        Extract text from a KnowledgeSourceNode.
+
+        Returns list of dicts: [{text, source, chunk_size?, chunk_overlap?}]
+        """
+        results = []
+        st = source.source_type
+        extra = {}
+        if source.chunk_size is not None:
+            extra['chunk_size'] = source.chunk_size
+        if source.chunk_overlap is not None:
+            extra['chunk_overlap'] = source.chunk_overlap
+
+        if st == 'text':
+            if source.content:
+                results.append({'text': source.content, 'source': 'inline', **extra})
+
+        elif st == 'file':
+            path = Path(source.path)
+            if path.exists() and path.is_file():
+                try:
+                    text = path.read_text(encoding='utf-8')
+                    results.append({'text': text, 'source': str(path), **extra})
+                except Exception as e:
+                    logger.warning(f"Failed to read file {path}: {e}")
+            else:
+                logger.warning(f"Knowledge source file not found: {source.path}")
+
+        elif st == 'directory':
+            dir_path = Path(source.path)
+            pattern = source.pattern or '*.md'
+            if dir_path.exists() and dir_path.is_dir():
+                for file_path in sorted(dir_path.glob(pattern)):
+                    if file_path.is_file():
+                        try:
+                            text = file_path.read_text(encoding='utf-8')
+                            results.append({'text': text, 'source': str(file_path), **extra})
+                        except Exception as e:
+                            logger.warning(f"Failed to read {file_path}: {e}")
+            else:
+                logger.warning(f"Knowledge source directory not found: {source.path}")
+
+        elif st == 'url':
+            logger.warning("URL source type is not yet implemented for q:knowledge")
+
+        elif st == 'query':
+            if database_service and source.datasource and source.sql:
+                try:
+                    result = database_service.execute_query(
+                        source.datasource, source.sql, {}
+                    )
+                    for row in result.data:
+                        # Concatenate all string values in the row
+                        parts = [str(v) for v in row.values() if v is not None]
+                        text = ' '.join(parts)
+                        if text.strip():
+                            results.append({'text': text, 'source': f"query:{source.datasource}", **extra})
+                except Exception as e:
+                    logger.warning(f"Failed to execute knowledge source query: {e}")
+            else:
+                logger.warning("Query source requires datasource, sql, and database_service")
+
+        return results
+
+    def _chunk_text(self, text: str, chunk_size: int = 500, chunk_overlap: int = 50) -> List[str]:
+        """
+        Split text into chunks using a sliding window with paragraph/sentence awareness.
+
+        Args:
+            text: Input text
+            chunk_size: Target characters per chunk
+            chunk_overlap: Overlap between chunks
+
+        Returns:
+            List of text chunks
+        """
+        if not text or not text.strip():
+            return []
+
+        text = text.strip()
+
+        # If text is smaller than chunk_size, return as single chunk
+        if len(text) <= chunk_size:
+            return [text]
+
+        # Split into paragraphs first
+        paragraphs = re.split(r'\n\s*\n', text)
+
+        chunks = []
+        current_chunk = ""
+
+        for paragraph in paragraphs:
+            paragraph = paragraph.strip()
+            if not paragraph:
+                continue
+
+            # If adding this paragraph exceeds chunk_size
+            if current_chunk and len(current_chunk) + len(paragraph) + 1 > chunk_size:
+                chunks.append(current_chunk.strip())
+                # Start new chunk with overlap from end of previous
+                if chunk_overlap > 0 and len(current_chunk) > chunk_overlap:
+                    current_chunk = current_chunk[-chunk_overlap:] + "\n" + paragraph
+                else:
+                    current_chunk = paragraph
+            else:
+                if current_chunk:
+                    current_chunk += "\n" + paragraph
+                else:
+                    current_chunk = paragraph
+
+            # If single paragraph exceeds chunk_size, split by sentences
+            while len(current_chunk) > chunk_size:
+                # Find a good split point (end of sentence)
+                split_at = chunk_size
+                for sep in ['. ', '! ', '? ', '\n', '; ', ', ']:
+                    idx = current_chunk.rfind(sep, 0, chunk_size)
+                    if idx > chunk_size // 3:
+                        split_at = idx + len(sep)
+                        break
+
+                chunks.append(current_chunk[:split_at].strip())
+                if chunk_overlap > 0:
+                    overlap_start = max(0, split_at - chunk_overlap)
+                    current_chunk = current_chunk[overlap_start:]
+                else:
+                    current_chunk = current_chunk[split_at:]
+
+        # Don't forget the last chunk
+        if current_chunk.strip():
+            chunks.append(current_chunk.strip())
+
+        return chunks
+
+    def _generate_embeddings(self, texts: List[str], model: str = "nomic-embed-text") -> List[List[float]]:
+        """
+        Generate embeddings via Ollama /api/embed endpoint.
+
+        Args:
+            texts: List of text strings to embed
+            model: Ollama embedding model name
+
+        Returns:
+            List of embedding vectors
+        """
+        if not texts:
+            return []
+
+        url = f"{self._ollama_base_url}/api/embed"
+
+        # Batch to avoid very large payloads
+        all_embeddings = []
+        batch_size = 50
+
+        for start in range(0, len(texts), batch_size):
+            batch = texts[start:start + batch_size]
+            payload = {
+                "model": model,
+                "input": batch,
+            }
+
+            try:
+                embed_timeout = int(os.getenv('QUANTUM_EMBED_TIMEOUT', '50'))
+                resp = requests.post(url, json=payload, timeout=embed_timeout)
+                resp.raise_for_status()
+                data = resp.json()
+
+                embeddings = data.get("embeddings", [])
+                if len(embeddings) != len(batch):
+                    raise KnowledgeError(
+                        f"Embedding count mismatch: expected {len(batch)}, got {len(embeddings)}"
+                    )
+                all_embeddings.extend(embeddings)
+
+            except requests.ConnectionError:
+                raise KnowledgeError(
+                    f"Cannot connect to Ollama at {self._ollama_base_url}. "
+                    "Ensure Ollama is running (ollama serve) and the embedding model is pulled "
+                    f"(ollama pull {model})"
+                )
+            except requests.Timeout:
+                raise KnowledgeError(f"Embedding request timed out for model {model}")
+            except requests.HTTPError as e:
+                raise KnowledgeError(f"Ollama embedding API error: {e.response.status_code} - {e.response.text}")
+            except KnowledgeError:
+                raise
+            except Exception as e:
+                raise KnowledgeError(f"Embedding generation error: {e}")
+
+        return all_embeddings
+
+    def search(
+        self,
+        name: str,
+        query_text: str,
+        n_results: int = 5,
+        embed_model: str = "nomic-embed-text",
+    ) -> List[Dict[str, Any]]:
+        """
+        Vector similarity search on a knowledge base.
+
+        Args:
+            name: Knowledge base name
+            query_text: Search query text
+            n_results: Number of results to return
+            embed_model: Embedding model to use for query
+
+        Returns:
+            List of dicts: [{content, relevance, source, chunk_index}]
+        """
+        collection = self._collections.get(name)
+        if collection is None:
+            raise KnowledgeError(f"Knowledge base '{name}' not found. Define it with <q:knowledge> first.")
+
+        if collection.count() == 0:
+            return []
+
+        # Generate query embedding
+        query_embedding = self._generate_embeddings([query_text], embed_model)
+        if not query_embedding:
+            return []
+
+        # Search ChromaDB
+        results = collection.query(
+            query_embeddings=query_embedding,
+            n_results=min(n_results, collection.count()),
+            include=["documents", "metadatas", "distances"],
+        )
+
+        # Format results
+        formatted = []
+        documents = results.get("documents", [[]])[0]
+        metadatas = results.get("metadatas", [[]])[0]
+        distances = results.get("distances", [[]])[0]
+
+        for doc, meta, dist in zip(documents, metadatas, distances):
+            # ChromaDB cosine distance: 0 = identical, 2 = opposite
+            # Convert to relevance score: 1.0 = perfect match, 0.0 = no match
+            relevance = max(0.0, 1.0 - dist / 2.0)
+            formatted.append({
+                "content": doc,
+                "relevance": round(relevance, 4),
+                "source": meta.get("source", "unknown"),
+                "chunk_index": meta.get("chunk_index", 0),
+            })
+
+        return formatted
+
+    def rag_query(
+        self,
+        name: str,
+        question: str,
+        model: Optional[str] = None,
+        n_results: int = 5,
+        embed_model: str = "nomic-embed-text",
+    ) -> Dict[str, Any]:
+        """
+        Full RAG pipeline: search + LLM answer.
+
+        Args:
+            name: Knowledge base name
+            question: User question
+            model: LLM model for answer generation
+            n_results: Number of chunks to retrieve for context
+            embed_model: Embedding model for search
+
+        Returns:
+            Dict: {answer, sources, confidence}
+        """
+        if self.llm_service is None:
+            raise KnowledgeError("LLM service is required for RAG queries. Ensure Ollama is available.")
+
+        # Step 1: Vector search
+        search_results = self.search(name, question, n_results, embed_model)
+
+        if not search_results:
+            return {
+                "answer": "No relevant information found in the knowledge base.",
+                "sources": [],
+                "confidence": 0.0,
+            }
+
+        # Step 2: Build context from search results
+        context_parts = []
+        sources = []
+        for i, result in enumerate(search_results):
+            context_parts.append(f"[{i+1}] {result['content']}")
+            src = result.get('source', 'unknown')
+            if src not in sources:
+                sources.append(src)
+
+        context = "\n\n".join(context_parts)
+
+        # Step 3: Generate answer via LLM
+        system_prompt = (
+            "You are a helpful assistant that answers questions based on the provided context. "
+            "Only use information from the context below. If the context doesn't contain "
+            "enough information to answer, say so. Be concise and accurate."
+        )
+
+        prompt = (
+            f"Context:\n{context}\n\n"
+            f"Question: {question}\n\n"
+            f"Answer:"
+        )
+
+        try:
+            llm_result = self.llm_service.generate(
+                prompt=prompt,
+                model=model,
+                system=system_prompt,
+                temperature=0.3,
+            )
+
+            answer = llm_result.get("data", "")
+            success = llm_result.get("success", False)
+        except Exception as e:
+            logger.error(f"RAG query failed for '{name}': {e}")
+            # Raised, not returned. This used to come back as the ANSWER —
+            # "Error generating answer: LLM request timed out after 60s", with
+            # confidence 0 — so a page rendered the failure as if the model
+            # had said it.
+            raise KnowledgeError(f"RAG answer for '{name}' failed: {e}") from e
+
+        if not success or not answer:
+            raise KnowledgeError(
+                f"RAG answer for '{name}' failed: "
+                f"{llm_result.get('error') or 'the model returned no answer'}")
+
+        # Calculate confidence based on search relevance
+        avg_relevance = sum(r['relevance'] for r in search_results) / len(search_results) if search_results else 0.0
+
+        return {
+            "answer": answer.strip(),
+            "sources": sources,
+            "confidence": round(avg_relevance, 4),
+        }

quantum/runtime/llm_cache.py

@@ -0,0 +1,100 @@
+"""
+Quantum LLM Cache - TTL cache for q:llm responses.
+
+q:llm has carried a `cache` attribute since it was written, wired to nothing.
+LLM calls are the slowest and most expensive thing a Quantum component can do,
+so a cache is not a nicety — a repeated prompt during development costs seconds
+and, on a paid provider, money.
+
+Keyed on everything that can change the answer: provider, model, endpoint, the
+full message list (or prompt+system), temperature, max_tokens and the requested
+response format. Two calls that differ in any of those are different calls.
+"""
+
+import hashlib
+import json
+import threading
+import time
+from typing import Any, Dict, Optional
+
+
+class LLMCache:
+    """In-process TTL cache for LLM responses."""
+
+    def __init__(self, max_entries: int = 500):
+        self._entries: Dict[str, Dict[str, Any]] = {}
+        self._lock = threading.Lock()
+        self.max_entries = max_entries
+        self.hits = 0
+        self.misses = 0
+
+    @staticmethod
+    def build_key(**parts: Any) -> str:
+        """Build a stable key from the call's distinguishing parameters."""
+        payload = json.dumps(parts, sort_keys=True, default=str)
+        return hashlib.sha256(payload.encode('utf-8')).hexdigest()
+
+    def get(self, key: str) -> Optional[Dict[str, Any]]:
+        """Return a cached response, or None if absent or expired."""
+        with self._lock:
+            entry = self._entries.get(key)
+            if entry is None:
+                self.misses += 1
+                return None
+
+            expires_at = entry['expires_at']
+            if expires_at is not None and time.time() > expires_at:
+                del self._entries[key]
+                self.misses += 1
+                return None
+
+            self.hits += 1
+            # Copy so a caller mutating the result cannot poison the cache
+            return dict(entry['value'])
+
+    def set(self, key: str, value: Dict[str, Any], ttl: Optional[int] = None):
+        """Store a response. ttl in seconds; None means no expiry."""
+        with self._lock:
+            if len(self._entries) >= self.max_entries:
+                # Evict the entry closest to expiry (None sorts last)
+                oldest = min(
+                    self._entries.items(),
+                    key=lambda kv: (kv[1]['expires_at'] is None, kv[1]['expires_at'] or 0),
+                )
+                del self._entries[oldest[0]]
+
+            self._entries[key] = {
+                'value': dict(value),
+                'expires_at': (time.time() + ttl) if ttl else None,
+            }
+
+    def clear(self):
+        with self._lock:
+            self._entries.clear()
+
+    def stats(self) -> Dict[str, Any]:
+        with self._lock:
+            total = self.hits + self.misses
+            return {
+                'entries': len(self._entries),
+                'hits': self.hits,
+                'misses': self.misses,
+                'hitRate': round(self.hits / total, 4) if total else 0.0,
+            }
+
+
+_llm_cache: Optional[LLMCache] = None
+
+
+def get_llm_cache() -> LLMCache:
+    """Get the process-wide LLM cache."""
+    global _llm_cache
+    if _llm_cache is None:
+        _llm_cache = LLMCache()
+    return _llm_cache
+
+
+def reset_llm_cache():
+    """Reset the global cache (for tests)."""
+    global _llm_cache
+    _llm_cache = None