class VectorDB:
    """
    Dead-simple local vector database powered by usearch HNSW.

    SQLite stores metadata and text; usearch stores vectors in separate
    .usearch files per collection. Provides Chroma-like API with built-in
    quantization for storage efficiency.

    Storage layout:
    - {path} - SQLite database (metadata, text, FTS)
    - {path}.{collection}.usearch - usearch HNSW index per collection

    Encryption (optional):
    - SQLite encrypted via SQLCipher (transparent page-level AES-256)
    - Index files encrypted via AES-256-GCM (at-rest only, zero runtime overhead)
    """

    def __init__(
        self,
        path: str | Path = ":memory:",
        distance_strategy: DistanceStrategy = DistanceStrategy.COSINE,
        quantization: Quantization = Quantization.FLOAT,
        *,
        encryption_key: str | bytes | None = None,
        auto_migrate: bool = False,
    ):
        """Initialize the vector database.

        Args:
            path: Database file path or ":memory:" for in-memory database.
            distance_strategy: Default distance metric for similarity search.
            quantization: Default vector compression strategy.
            encryption_key: Optional passphrase or 32-byte key for at-rest encryption.
                Encrypts both SQLite (via SQLCipher) and usearch index files (via AES-256-GCM).
            auto_migrate: If True, automatically migrate v1.x sqlite-vec data
                to usearch. If False (default), raise MigrationRequiredError
                when legacy data is detected. Use check_migration() to preview.

        Raises:
            MigrationRequiredError: If auto_migrate=False and legacy sqlite-vec
                data is detected. Contains details about what needs migration.
            EncryptionUnavailableError: If encryption_key provided but encryption
                dependencies are missing.
            EncryptionError: If encrypted database cannot be opened (wrong key).
            ValueError: If encryption_key used with ":memory:" database.
        """
        self.path = str(path)
        self.distance_strategy = distance_strategy
        self.quantization = quantization
        self.auto_migrate = auto_migrate
        self._encryption_key = encryption_key
        self._collections: dict[str, VectorCollection] = {}

        # Create connection (encrypted or plain)
        if encryption_key is not None:
            if self.path == ":memory:":
                raise ValueError(
                    "In-memory databases cannot be encrypted. "
                    "Use a file path for encrypted databases."
                )
            self.conn = create_encrypted_connection(
                self.path,
                encryption_key,
                check_same_thread=False,
                timeout=30.0,
            )
            self._encrypted = True
            _logger.info("Opened encrypted database: %s", self.path)
        else:
            self.conn = sqlite3.connect(
                self.path, check_same_thread=False, timeout=30.0
            )
            self.conn.execute("PRAGMA journal_mode=WAL")
            self.conn.execute("PRAGMA synchronous=NORMAL")
            self._encrypted = False

        # Check for required migration before allowing collection access
        if not auto_migrate and self.path != ":memory:":
            migration_info = VectorDB.check_migration(self.path)
            if migration_info["needs_migration"]:
                self.conn.close()
                raise MigrationRequiredError(
                    path=self.path,
                    collections=migration_info["collections"],
                    total_vectors=migration_info["total_vectors"],
                    migration_info=migration_info,
                )

    def list_collections(self) -> list[str]:
        """
        Return names of all initialized collections.

        Only returns collections that have been accessed via `collection()` in this
        session. Does not scan the database for collections created in previous sessions.

        Returns:
            List of collection names currently cached in this VectorDB instance.

        Example:
            >>> db = VectorDB("app.db")
            >>> db.collection("users")
            >>> db.collection("products")
            >>> db.list_collections()
            ['users', 'products']
        """
        return list(self._collections.keys())

    def search_collections(
        self,
        query: Sequence[float],
        collections: list[str] | None = None,
        k: int = 10,
        filter: dict[str, Any] | None = None,
        *,
        normalize_scores: bool = True,
        parallel: bool = True,
    ) -> list[tuple[Document, float, str]]:
        """
        Search across multiple collections with merged, ranked results.

        Performs similarity search on each collection and merges results using
        score normalization for fair comparison across distance metrics.

        Args:
            query: Query vector (must match dimension of all searched collections).
            collections: List of collection names to search. None searches all
                initialized collections (from list_collections()).
            k: Number of top results to return after merging.
            filter: Optional metadata filter applied to all collections.
            normalize_scores: If True, convert distances to similarity scores
                in [0, 1] range using `1 / (1 + distance)`. Enables fair
                comparison across COSINE [0,2] and L2 [0,∞) metrics.
            parallel: If True, search collections concurrently using ThreadPoolExecutor.

        Returns:
            List of (Document, similarity_score, collection_name) tuples,
            sorted by descending similarity score (highest first).

        Raises:
            ValueError: If no collections specified and none initialized,
                or if collections have mismatched dimensions.
            KeyError: If a specified collection name doesn't exist.

        Example:
            >>> db = VectorDB("app.db")
            >>> db.collection("users").add_texts(["alice"], embeddings=[[0.1]*384])
            >>> db.collection("products").add_texts(["widget"], embeddings=[[0.2]*384])
            >>> results = db.search_collections([0.15]*384, k=2)
            >>> for doc, score, coll in results:
            ...     print(f"{coll}: {doc.page_content} ({score:.3f})")
        """
        target_names = (
            collections if collections is not None else self.list_collections()
        )

        if not target_names:
            return []

        # Resolve and validate collections
        targets: list[VectorCollection] = []
        dims: set[int | None] = set()
        for name in target_names:
            if name not in self._collections:
                raise KeyError(
                    f"Collection '{name}' not initialized. Call db.collection('{name}') first."
                )
            coll = self._collections[name]
            targets.append(coll)
            dims.add(coll._dim)

        # Check dimension consistency (ignore None for empty collections)
        dims.discard(None)
        if len(dims) > 1:
            raise ValueError(
                f"Dimension mismatch across collections: {dims}. "
                "All searched collections must have the same embedding dimension."
            )

        # Search function for each collection
        def _search_one(coll: VectorCollection) -> list[tuple[Document, float, str]]:
            results = coll.similarity_search(query, k=k, filter=filter)
            return [(doc, dist, coll.name) for doc, dist in results]

        # Execute searches
        all_results: list[tuple[Document, float, str]] = []
        if parallel and len(targets) > 1:
            from concurrent.futures import ThreadPoolExecutor

            with ThreadPoolExecutor(max_workers=min(len(targets), 8)) as executor:
                futures = [executor.submit(_search_one, coll) for coll in targets]
                for future in futures:
                    all_results.extend(future.result())
        else:
            for coll in targets:
                all_results.extend(_search_one(coll))

        # Normalize scores: similarity = 1 / (1 + distance)
        if normalize_scores:
            all_results = [
                (doc, 1.0 / (1.0 + dist), name) for doc, dist, name in all_results
            ]
        else:
            # Invert for sorting (lower distance = higher rank)
            all_results = [(doc, -dist, name) for doc, dist, name in all_results]

        # Sort by score descending and take top k
        all_results.sort(key=lambda x: x[1], reverse=True)
        return all_results[:k]

    def collection(
        self,
        name: str = "default",
        distance_strategy: DistanceStrategy | None = None,
        quantization: Quantization | None = None,
    ) -> VectorCollection:
        """
        Get or create a named collection.

        Collections provide isolated namespaces within a single database.
        Each collection has its own usearch index file.

        Args:
            name: Collection name (alphanumeric + underscore only).
            distance_strategy: Override database-level distance metric.
            quantization: Override database-level quantization.

        Returns:
            VectorCollection instance.

        Raises:
            ValueError: If collection name contains invalid characters.
        """
        cache_key = name
        if cache_key not in self._collections:
            self._collections[cache_key] = VectorCollection(
                conn=self.conn,
                db_path=self.path,
                name=name,
                distance_strategy=distance_strategy or self.distance_strategy,
                quantization=quantization or self.quantization,
                encryption_key=self._encryption_key,
            )
        return self._collections[cache_key]

    # ------------------------------------------------------------------ #
    # Integrations
    # ------------------------------------------------------------------ #
    def as_langchain(
        self, embeddings: Embeddings | None = None, collection_name: str = "default"
    ) -> SimpleVecDBVectorStore:
        """Return a LangChain-compatible vector store interface."""
        from .integrations.langchain import SimpleVecDBVectorStore

        return SimpleVecDBVectorStore(
            db_path=self.path, embedding=embeddings, collection_name=collection_name
        )

    def as_llama_index(self, collection_name: str = "default") -> SimpleVecDBLlamaStore:
        """Return a LlamaIndex-compatible vector store interface."""
        from .integrations.llamaindex import SimpleVecDBLlamaStore

        return SimpleVecDBLlamaStore(db_path=self.path, collection_name=collection_name)

    # ------------------------------------------------------------------ #
    # Convenience
    # ------------------------------------------------------------------ #
    @staticmethod
    def check_migration(path: str | Path) -> dict[str, Any]:
        """
        Check if a database needs migration from sqlite-vec (dry-run).

        Use this before opening a v1.x database to understand what will
        be migrated. Does not modify the database.

        Args:
            path: Path to the SQLite database file

        Returns:
            Dict with migration info:
            - needs_migration: bool
            - collections: list of collection names with legacy data
            - total_vectors: estimated total vector count
            - estimated_size_mb: approximate usearch index size
            - rollback_notes: instructions for reverting if needed

        Example:
            >>> info = VectorDB.check_migration("mydb.db")
            >>> if info["needs_migration"]:
            ...     print(f"Will migrate {info['total_vectors']} vectors")
            ...     print(info["rollback_notes"])
        """
        path = str(path)
        if path == ":memory:" or not Path(path).exists():
            return {
                "needs_migration": False,
                "collections": [],
                "total_vectors": 0,
                "estimated_size_mb": 0.0,
                "rollback_notes": "",
            }

        try:
            conn = sqlite3.connect(path, check_same_thread=False)
        except sqlite3.DatabaseError:
            # Database may be encrypted or corrupted - cannot check migration
            return {
                "needs_migration": False,
                "collections": [],
                "total_vectors": 0,
                "estimated_size_mb": 0.0,
                "rollback_notes": "",
            }

        try:
            # Check for legacy sqlite-vec tables
            tables = conn.execute(
                "SELECT name FROM sqlite_master WHERE type='table'"
            ).fetchall()
        except sqlite3.DatabaseError:
            # Database is encrypted or corrupted - cannot check migration
            conn.close()
            return {
                "needs_migration": False,
                "collections": [],
                "total_vectors": 0,
                "estimated_size_mb": 0.0,
                "rollback_notes": "",
            }

        try:
            table_names = {t[0] for t in tables}

            legacy_collections = []
            total_vectors = 0
            total_bytes = 0

            # Check default collection
            if "vec_index" in table_names:
                try:
                    count = conn.execute("SELECT COUNT(*) FROM vec_index").fetchone()[0]
                    if count > 0:
                        legacy_collections.append("default")
                        total_vectors += count
                        # Estimate: rowid(8) + embedding blob
                        row = conn.execute(
                            "SELECT embedding FROM vec_index LIMIT 1"
                        ).fetchone()
                        if row and row[0]:
                            dim = len(row[0]) // 4
                            total_bytes += count * dim * 4  # float32
                except Exception:
                    pass

            # Check named collections (vectors_{name})
            for table in table_names:
                if table.startswith("vectors_") and table != "vec_index":
                    collection_name = table[8:]  # Remove "vectors_" prefix
                    try:
                        count = conn.execute(
                            f"SELECT COUNT(*) FROM {table}"
                        ).fetchone()[0]
                        if count > 0:
                            legacy_collections.append(collection_name)
                            total_vectors += count
                            row = conn.execute(
                                f"SELECT embedding FROM {table} LIMIT 1"
                            ).fetchone()
                            if row and row[0]:
                                dim = len(row[0]) // 4
                                total_bytes += count * dim * 4
                    except Exception:
                        pass

            estimated_mb = total_bytes / (1024 * 1024)

            rollback_notes = ""
            if legacy_collections:
                rollback_notes = f"""
MIGRATION ROLLBACK INSTRUCTIONS:
================================
1. BEFORE upgrading, backup your database:
   cp {path} {path}.backup

2. If migration fails or you need to revert:
   - Delete the new .usearch files: {path}.*.usearch
   - Restore from backup: cp {path}.backup {path}
   - Downgrade to simplevecdb<2.0.0

3. After successful migration, the legacy sqlite-vec tables are dropped.
   Keep your backup until you've verified the migration worked correctly.

4. New storage layout after migration:
   - {path} (SQLite: metadata, text, FTS, embeddings)
   - {path}.<collection>.usearch (usearch HNSW index per collection)
"""

            return {
                "needs_migration": len(legacy_collections) > 0,
                "collections": legacy_collections,
                "total_vectors": total_vectors,
                "estimated_size_mb": round(estimated_mb, 2),
                "rollback_notes": rollback_notes.strip(),
            }
        finally:
            conn.close()

    def vacuum(self, checkpoint_wal: bool = True) -> None:
        """
        Reclaim disk space by rebuilding the SQLite database file.

        Note: This only affects SQLite metadata storage. Usearch indexes
        don't support in-place compaction; use rebuild_index() for that.

        Args:
            checkpoint_wal: If True (default), also truncate the WAL file.
        """
        if checkpoint_wal:
            self.conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
        self.conn.execute("VACUUM")
        self.conn.execute("PRAGMA optimize")

    def save(self) -> None:
        """Save all collection indexes to disk."""
        for collection in self._collections.values():
            collection.save()

    def close(self) -> None:
        """Close the database connection and save indexes."""
        self.save()
        self.conn.close()

    def __del__(self) -> None:
        try:
            self.close()
        except Exception:
            pass