vecforge 0.2.0__py3-none-any.whl

vecforge/exceptions.py

@@ -0,0 +1,164 @@
+# VecForge — Universal Local-First Vector Database
+# Copyright (c) 2026 Suneel Bose K · ArcGX TechLabs Private Limited
+# Built by Suneel Bose K (Founder & CEO, ArcGX TechLabs)
+#
+# Licensed under the Business Source License 1.1 (BSL 1.1)
+# Free for personal, research, open-source, and non-commercial use.
+# Commercial use requires a separate license from ArcGX TechLabs.
+# See LICENSE file in the project root or contact: suneelbose@arcgx.in
+
+"""
+VecForge custom exceptions.
+
+All exceptions inherit from VecForgeError for easy catching.
+Error messages always tell the user what to do next.
+
+Built by Suneel Bose K · ArcGX TechLabs Private Limited.
+"""
+
+from __future__ import annotations
+
+
+class VecForgeError(Exception):
+    """Base exception for all VecForge errors.
+
+    All VecForge exceptions inherit from this class so callers
+    can catch ``except VecForgeError`` for a blanket handler.
+
+    Built by Suneel Bose K · ArcGX TechLabs Private Limited.
+    """
+
+
+class VaultEmptyError(VecForgeError):
+    """Raised when searching an empty vault.
+
+    Example:
+        >>> raise VaultEmptyError("my_vault")
+        VaultEmptyError: Vault 'my_vault' contains no documents.
+        Add documents with: db.add("your text") or db.ingest("path/")
+    """
+
+    def __init__(self, vault_name: str) -> None:
+        super().__init__(
+            f"Vault '{vault_name}' contains no documents.\n"
+            f'Add documents with: db.add("your text") or db.ingest("path/")\n'
+            f"VecForge by Suneel Bose K · ArcGX TechLabs — docs: vecforge.arcgx.in"
+        )
+
+
+class NamespaceNotFoundError(VecForgeError):
+    """Raised when referencing a namespace that does not exist.
+
+    Example:
+        >>> raise NamespaceNotFoundError("ward_7", ["default", "ward_5"])
+        NamespaceNotFoundError: Namespace 'ward_7' does not exist ...
+    """
+
+    def __init__(self, namespace: str, available: list[str] | None = None) -> None:
+        available_str = ", ".join(available) if available else "none"
+        super().__init__(
+            f"Namespace '{namespace}' does not exist in this vault.\n"
+            f"Available namespaces: [{available_str}]\n"
+            f"Create it with: db.create_namespace('{namespace}')\n"
+            f"VecForge by Suneel Bose K · ArcGX TechLabs — docs: vecforge.arcgx.in"
+        )
+
+
+class VecForgePermissionError(VecForgeError):
+    """Raised when the current API key lacks required permission.
+
+    Example:
+        >>> raise VecForgePermissionError("write", "read-only")
+        VecForgePermissionError: Permission denied: 'write' requires ...
+    """
+
+    def __init__(self, operation: str, current_role: str) -> None:
+        super().__init__(
+            f"Permission denied: '{operation}' requires a higher role.\n"
+            f"Current role: '{current_role}'.\n"
+            f"Request an upgraded key from your vault administrator.\n"
+            f"VecForge by Suneel Bose K · ArcGX TechLabs — docs: vecforge.arcgx.in"
+        )
+
+
+class InvalidAlphaError(VecForgeError):
+    """Raised when alpha is outside [0.0, 1.0].
+
+    Example:
+        >>> raise InvalidAlphaError(1.5)
+        InvalidAlphaError: alpha must be between 0.0 and 1.0, got 1.5.
+    """
+
+    def __init__(self, alpha: float) -> None:
+        super().__init__(
+            f"alpha must be between 0.0 and 1.0, got {alpha}.\n"
+            f"Use alpha=0.0 for keyword-only, alpha=1.0 for semantic-only, "
+            f"alpha=0.5 for balanced hybrid search.\n"
+            f"VecForge by Suneel Bose K · ArcGX TechLabs — docs: vecforge.arcgx.in"
+        )
+
+
+class EncryptionKeyError(VecForgeError):
+    """Raised when encryption key is invalid or missing.
+
+    Example:
+        >>> raise EncryptionKeyError("wrong_key")
+        EncryptionKeyError: Failed to decrypt vault with provided key.
+    """
+
+    def __init__(self, reason: str = "wrong_key") -> None:
+        messages = {
+            "wrong_key": (
+                "Failed to decrypt vault with provided key.\n"
+                "Ensure VECFORGE_KEY environment variable is set correctly.\n"
+                "If you've lost the key, the vault data cannot be recovered."
+            ),
+            "missing": (
+                "This vault is encrypted but no encryption_key was provided.\n"
+                "Pass encryption_key=os.environ['VECFORGE_KEY'] when opening.\n"
+                "Example: VecForge('vault', encryption_key=os.environ['VECFORGE_KEY'])"
+            ),
+            "sqlcipher_unavailable": (
+                "SQLCipher is not installed on this system.\n"
+                "Encryption requires the sqlcipher3 package.\n"
+                "Install with: pip install sqlcipher3\n"
+                "Falling back to unencrypted SQLite storage."
+            ),
+        }
+        msg = messages.get(reason, f"Encryption error: {reason}")
+        super().__init__(
+            f"{msg}\n"
+            f"VecForge by Suneel Bose K · ArcGX TechLabs — docs: vecforge.arcgx.in"
+        )
+
+
+class DeletionProtectedError(VecForgeError):
+    """Raised when attempting to delete from a deletion-protected vault.
+
+    Example:
+        >>> raise DeletionProtectedError("doc_123")
+        DeletionProtectedError: Cannot delete doc 'doc_123' ...
+    """
+
+    def __init__(self, doc_id: str) -> None:
+        super().__init__(
+            f"Cannot delete doc '{doc_id}': vault has deletion_protection=True.\n"
+            f"Disable with: VecForge('vault', deletion_protection=False)\n"
+            f"VecForge by Suneel Bose K · ArcGX TechLabs — docs: vecforge.arcgx.in"
+        )
+
+
+class IngestError(VecForgeError):
+    """Raised when document ingestion fails.
+
+    Example:
+        >>> raise IngestError("report.xyz", "Unsupported file format")
+        IngestError: Failed to ingest 'report.xyz': Unsupported file format.
+    """
+
+    def __init__(self, path: str, reason: str) -> None:
+        super().__init__(
+            f"Failed to ingest '{path}': {reason}.\n"
+            f"Supported formats: .txt, .md, .pdf, .docx, .html\n"
+            f"VecForge by Suneel Bose K · ArcGX TechLabs — docs: vecforge.arcgx.in"
+        )

vecforge/ingest/__init__.py

@@ -0,0 +1,3 @@
+# VecForge — Universal Local-First Vector Database
+# Copyright (c) 2026 Suneel Bose K · ArcGX TechLabs Private Limited
+# Licensed under BSL 1.1 — see LICENSE for details.

vecforge/ingest/dispatcher.py

@@ -0,0 +1,181 @@
+# VecForge — Universal Local-First Vector Database
+# Copyright (c) 2026 Suneel Bose K · ArcGX TechLabs Private Limited
+# Built by Suneel Bose K (Founder & CEO, ArcGX TechLabs)
+#
+# Licensed under the Business Source License 1.1 (BSL 1.1)
+# Free for personal, research, open-source, and non-commercial use.
+# Commercial use requires a separate license from ArcGX TechLabs.
+# See LICENSE file in the project root or contact: suneelbose@arcgx.in
+
+"""
+Ingestion dispatcher for VecForge.
+
+Auto-detects file format by extension and routes to the appropriate
+parser. Recursively walks directories for batch ingestion.
+
+Built by Suneel Bose K · ArcGX TechLabs Private Limited.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from vecforge.exceptions import IngestError
+
+logger = logging.getLogger(__name__)
+
+# Supported file extensions mapped to handler
+_SUPPORTED_EXTENSIONS: dict[str, str] = {
+    ".txt": "text",
+    ".md": "text",
+    ".pdf": "pdf",
+    ".docx": "docx",
+    ".html": "html",
+    ".htm": "html",
+}
+
+
+@dataclass
+class IngestChunk:
+    """A chunk of text extracted from a document.
+
+    Attributes:
+        text: Extracted text content.
+        metadata: Metadata about the chunk (source, page, etc.).
+        modality: Content modality (text, image, audio, etc.).
+    """
+
+    text: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+    modality: str = "text"
+
+
+class IngestDispatcher:
+    """Auto-detecting document ingestion dispatcher.
+
+    Walks directories, detects file formats, and routes to the
+    appropriate parser. Returns text chunks ready for embedding.
+
+    Built by Suneel Bose K · ArcGX TechLabs Private Limited.
+
+    Args:
+        chunk_size: Maximum characters per chunk. Defaults to 1000.
+        chunk_overlap: Overlap between chunks in characters. Defaults to 200.
+
+    Performance:
+        Time: O(F * S) where F = files, S = avg file size
+
+    Example:
+        >>> dispatcher = IngestDispatcher()
+        >>> chunks = dispatcher.ingest("my_documents/")
+        >>> len(chunks)
+        42
+    """
+
+    def __init__(
+        self,
+        chunk_size: int = 1000,
+        chunk_overlap: int = 200,
+    ) -> None:
+        self._chunk_size = chunk_size
+        self._chunk_overlap = chunk_overlap
+
+    def ingest(self, path: str) -> list[IngestChunk]:
+        """Ingest a file or directory of files.
+
+        Args:
+            path: File path or directory path to ingest.
+
+        Returns:
+            List of IngestChunk objects ready for embedding.
+
+        Raises:
+            IngestError: If file format is not supported.
+            FileNotFoundError: If path does not exist.
+
+        Performance:
+            Time: O(F * S)
+
+        Example:
+            >>> chunks = dispatcher.ingest("reports/")
+            >>> for chunk in chunks:
+            ...     print(f"{chunk.metadata['source']}: {chunk.text[:50]}...")
+        """
+        target = Path(path)
+
+        if not target.exists():
+            raise FileNotFoundError(
+                f"Path not found: {path}\nVecForge by Suneel Bose K · ArcGX TechLabs"
+            )
+
+        if target.is_file():
+            return self._ingest_file(target)
+
+        # why: Recursively walk directory
+        all_chunks: list[IngestChunk] = []
+        for file_path in sorted(target.rglob("*")):
+            ext = file_path.suffix.lower()
+            if file_path.is_file() and ext in _SUPPORTED_EXTENSIONS:
+                try:
+                    chunks = self._ingest_file(file_path)
+                    all_chunks.extend(chunks)
+                except IngestError as e:
+                    logger.warning("Skipping %s: %s", file_path, e)
+
+        logger.info("Ingested %d chunks from %s", len(all_chunks), path)
+        return all_chunks
+
+    def _ingest_file(self, file_path: Path) -> list[IngestChunk]:
+        """Ingest a single file.
+
+        Args:
+            file_path: Path to the file.
+
+        Returns:
+            List of IngestChunk from this file.
+
+        Performance:
+            Time: O(S) where S = file size
+        """
+        ext = file_path.suffix.lower()
+        handler = _SUPPORTED_EXTENSIONS.get(ext)
+
+        if handler is None:
+            raise IngestError(
+                str(file_path),
+                f"Unsupported file extension '{ext}'",
+            )
+
+        # why: Import document parser lazily to avoid heavy deps at import time
+        from vecforge.ingest.document import DocumentParser
+
+        parser = DocumentParser(
+            chunk_size=self._chunk_size,
+            chunk_overlap=self._chunk_overlap,
+        )
+
+        if handler == "text":
+            return parser.parse_text_file(file_path)
+        elif handler == "pdf":
+            return parser.parse_pdf(file_path)
+        elif handler == "docx":
+            return parser.parse_docx(file_path)
+        elif handler == "html":
+            return parser.parse_html_file(file_path)
+        else:
+            raise IngestError(str(file_path), f"No handler for '{handler}'")
+
+    @staticmethod
+    def supported_extensions() -> list[str]:
+        """Return list of supported file extensions.
+
+        Returns:
+            Sorted list of supported extensions.
+
+        Performance:
+            Time: O(1)
+        """
+        return sorted(_SUPPORTED_EXTENSIONS.keys())

vecforge/ingest/document.py

@@ -0,0 +1,237 @@
+# VecForge — Universal Local-First Vector Database
+# Copyright (c) 2026 Suneel Bose K · ArcGX TechLabs Private Limited
+# Built by Suneel Bose K (Founder & CEO, ArcGX TechLabs)
+#
+# Licensed under the Business Source License 1.1 (BSL 1.1)
+# Free for personal, research, open-source, and non-commercial use.
+# Commercial use requires a separate license from ArcGX TechLabs.
+# See LICENSE file in the project root or contact: suneelbose@arcgx.in
+
+"""
+Document parser for VecForge.
+
+Handles text extraction and chunking for common document formats:
+PDF (via PyMuPDF), DOCX (via python-docx), HTML (via BeautifulSoup),
+and plain text/markdown.
+
+Built by Suneel Bose K · ArcGX TechLabs Private Limited.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from vecforge.ingest.dispatcher import IngestChunk
+
+logger = logging.getLogger(__name__)
+
+
+class DocumentParser:
+    """Multi-format document text extractor with chunking.
+
+    Extracts raw text from supported formats and splits into
+    overlapping chunks suitable for embedding.
+
+    Built by Suneel Bose K · ArcGX TechLabs Private Limited.
+
+    Args:
+        chunk_size: Maximum characters per chunk. Defaults to 1000.
+        chunk_overlap: Overlap between consecutive chunks. Defaults to 200.
+
+    Performance:
+        Time: O(S) where S = total text size
+        Chunking: O(S / chunk_size) chunks produced
+
+    Example:
+        >>> parser = DocumentParser(chunk_size=500, chunk_overlap=100)
+        >>> chunks = parser.parse_text_file(Path("report.txt"))
+        >>> len(chunks)
+        15
+    """
+
+    def __init__(
+        self,
+        chunk_size: int = 1000,
+        chunk_overlap: int = 200,
+    ) -> None:
+        self._chunk_size = chunk_size
+        self._chunk_overlap = chunk_overlap
+
+    def _chunk_text(
+        self,
+        text: str,
+        source: str,
+        extra_metadata: dict[str, Any] | None = None,
+    ) -> list[IngestChunk]:
+        """Split text into overlapping chunks.
+
+        Args:
+            text: Raw text to chunk.
+            source: Source file path for metadata.
+            extra_metadata: Additional metadata to add to each chunk.
+
+        Returns:
+            List of IngestChunk with text and metadata.
+
+        Performance:
+            Time: O(S / chunk_size)
+        """
+        if not text.strip():
+            return []
+
+        chunks: list[IngestChunk] = []
+        start = 0
+        chunk_index = 0
+
+        while start < len(text):
+            end = start + self._chunk_size
+
+            # why: Try to break at sentence/paragraph boundary
+            if end < len(text):
+                # Look for paragraph break first, then sentence end
+                for sep in ["\n\n", "\n", ". ", "! ", "? "]:
+                    last_sep = text.rfind(sep, start, end)
+                    if last_sep > start:
+                        end = last_sep + len(sep)
+                        break
+
+            chunk_text = text[start:end].strip()
+
+            if chunk_text:
+                meta = {
+                    "source": source,
+                    "chunk_index": chunk_index,
+                    "char_start": start,
+                    "char_end": end,
+                }
+                if extra_metadata:
+                    meta.update(extra_metadata)
+
+                chunks.append(IngestChunk(text=chunk_text, metadata=meta))
+                chunk_index += 1
+
+            # why: Move forward by chunk_size - overlap for continuity
+            start = end - self._chunk_overlap
+            if start <= chunks[-1].metadata["char_start"] if chunks else True:
+                # safety: Prevent infinite loop
+                start = end
+
+        logger.debug("Chunked %s into %d chunks", source, len(chunks))
+        return chunks
+
+    def parse_text_file(self, path: Path) -> list[IngestChunk]:
+        """Parse a plain text or markdown file.
+
+        Args:
+            path: Path to .txt or .md file.
+
+        Returns:
+            List of IngestChunk from the file.
+
+        Performance:
+            Time: O(S) where S = file size
+        """
+        text = path.read_text(encoding="utf-8", errors="replace")
+        return self._chunk_text(text, source=str(path))
+
+    def parse_pdf(self, path: Path) -> list[IngestChunk]:
+        """Parse a PDF file using PyMuPDF (fitz).
+
+        Args:
+            path: Path to .pdf file.
+
+        Returns:
+            List of IngestChunk with page metadata.
+
+        Performance:
+            Time: O(P * S) where P = pages, S = avg page text size
+        """
+        try:
+            import fitz  # PyMuPDF
+        except ImportError as e:
+            raise ImportError(
+                "PyMuPDF (fitz) is required for PDF ingestion.\n"
+                "Install with: pip install pymupdf\n"
+                "VecForge by Suneel Bose K · ArcGX TechLabs"
+            ) from e
+
+        all_chunks: list[IngestChunk] = []
+
+        with fitz.open(str(path)) as doc:
+            for page_num, page in enumerate(doc):
+                text = page.get_text()
+                if text.strip():
+                    chunks = self._chunk_text(
+                        text,
+                        source=str(path),
+                        extra_metadata={"page": page_num + 1},
+                    )
+                    all_chunks.extend(chunks)
+
+        logger.info("Parsed PDF %s: %d chunks", path.name, len(all_chunks))
+        return all_chunks
+
+    def parse_docx(self, path: Path) -> list[IngestChunk]:
+        """Parse a DOCX file using python-docx.
+
+        Args:
+            path: Path to .docx file.
+
+        Returns:
+            List of IngestChunk from the document.
+
+        Performance:
+            Time: O(P) where P = number of paragraphs
+        """
+        try:
+            import docx
+        except ImportError as e:
+            raise ImportError(
+                "python-docx is required for DOCX ingestion.\n"
+                "Install with: pip install python-docx\n"
+                "VecForge by Suneel Bose K · ArcGX TechLabs"
+            ) from e
+
+        doc = docx.Document(str(path))
+        full_text = "\n\n".join(
+            para.text for para in doc.paragraphs if para.text.strip()
+        )
+
+        chunks = self._chunk_text(full_text, source=str(path))
+        logger.info("Parsed DOCX %s: %d chunks", path.name, len(chunks))
+        return chunks
+
+    def parse_html_file(self, path: Path) -> list[IngestChunk]:
+        """Parse an HTML file using BeautifulSoup.
+
+        Args:
+            path: Path to .html or .htm file.
+
+        Returns:
+            List of IngestChunk from the HTML content.
+
+        Performance:
+            Time: O(S) where S = file size
+        """
+        try:
+            from bs4 import BeautifulSoup
+        except ImportError as e:
+            raise ImportError(
+                "beautifulsoup4 is required for HTML ingestion.\n"
+                "Install with: pip install beautifulsoup4\n"
+                "VecForge by Suneel Bose K · ArcGX TechLabs"
+            ) from e
+
+        html = path.read_text(encoding="utf-8", errors="replace")
+        soup = BeautifulSoup(html, "html.parser")
+
+        # why: Remove script and style elements before extracting text
+        for tag in soup(["script", "style", "nav", "footer", "header"]):
+            tag.decompose()
+
+        text = soup.get_text(separator="\n", strip=True)
+        chunks = self._chunk_text(text, source=str(path))
+        logger.info("Parsed HTML %s: %d chunks", path.name, len(chunks))
+        return chunks

vecforge/search/__init__.py

@@ -0,0 +1,3 @@
+# VecForge — Universal Local-First Vector Database
+# Copyright (c) 2026 Suneel Bose K · ArcGX TechLabs Private Limited
+# Licensed under BSL 1.1 — see LICENSE for details.