echo-vector 0.1.1__py3-none-any.whl

echovector/audio/streaming.py

@@ -0,0 +1,33 @@
+from collections.abc import Generator
+
+import numpy as np
+import numpy.typing as npt
+import soundfile as sf
+
+
+class AudioStreamer:
+    """Streams audio data in blocks."""
+
+    def __init__(self, block_size: int = 4096) -> None:
+        """Initialize the streamer.
+
+        Args:
+            block_size: Number of frames per block.
+        """
+        self.block_size = block_size
+
+    def stream(self, file_path: str) -> Generator[npt.NDArray[np.float32], None, None]:
+        """Stream audio from a file.
+
+        Args:
+            file_path: Path to the audio file.
+
+        Yields:
+            Blocks of audio data as numpy arrays.
+        """
+        for block in sf.blocks(
+            file_path, blocksize=self.block_size, dtype="float32", always_2d=False
+        ):
+            if block.ndim > 1:
+                block = np.mean(block, axis=1, dtype=np.float32)
+            yield block

echovector/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI module for EchoVector."""

echovector/cli/main.py

@@ -0,0 +1,165 @@
+"""Command-line interface for EchoVector."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from echovector import EchoVector
+
+app = typer.Typer(
+    name="echovector",
+    help="EchoVector CLI for semantic text search over audio files.",
+    add_completion=False,
+)
+console = Console()
+
+
+def _open_engine(store_dir: Path, backend: str, device: str | None) -> EchoVector:
+    if device:
+        return EchoVector(store_dir=store_dir, backend=backend, device=device)
+    return EchoVector(store_dir=store_dir, backend=backend)
+
+
+@app.command()
+def index(
+    files: Annotated[
+        list[Path],
+        typer.Argument(help="Audio files or directories to index."),
+    ],
+    recursive: Annotated[
+        bool,
+        typer.Option("--recursive", "-r", help="Recursively search directories for audio files."),
+    ] = False,
+    store_dir: Annotated[
+        Path,
+        typer.Option("--store-dir", help="Directory for index files."),
+    ] = Path(".echovector"),
+    backend: Annotated[str, typer.Option("--backend", help="Embedding backend to use.")] = "clap",
+    device: Annotated[
+        str | None,
+        typer.Option("--device", help="Model device, e.g. cpu or cuda."),
+    ] = None,
+    reset: Annotated[
+        bool,
+        typer.Option("--reset", help="Clear the existing index before indexing."),
+    ] = False,
+    chunk_seconds: Annotated[
+        float,
+        typer.Option("--chunk-seconds", help="Audio chunk size to embed."),
+    ] = 10.0,
+    overlap_seconds: Annotated[
+        float,
+        typer.Option("--overlap-seconds", help="Overlap between adjacent chunks."),
+    ] = 1.0,
+) -> None:
+    """Index audio files for search."""
+    try:
+        if device:
+            engine = EchoVector(
+                store_dir=store_dir,
+                backend=backend,
+                device=device,
+                chunk_seconds=chunk_seconds,
+                overlap_seconds=overlap_seconds,
+            )
+        else:
+            engine = EchoVector(
+                store_dir=store_dir,
+                backend=backend,
+                chunk_seconds=chunk_seconds,
+                overlap_seconds=overlap_seconds,
+            )
+        if reset:
+            engine.reset()
+        count = engine.index(files, recursive=recursive)
+    except Exception as exc:
+        console.print(f"[bold red]Indexing failed:[/bold red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+    console.print(f"[bold green]Indexing complete.[/bold green] Indexed {count} chunk(s).")
+    console.print(f"[dim]Store: {store_dir}[/dim]")
+
+
+@app.command()
+def search(
+    query: Annotated[str, typer.Argument(help="Text query to search for.")],
+    top_k: Annotated[
+        int,
+        typer.Option("--top-k", "-k", help="Number of top results to return."),
+    ] = 5,
+    store_dir: Annotated[
+        Path,
+        typer.Option("--store-dir", help="Directory containing the index."),
+    ] = Path(".echovector"),
+    backend: Annotated[
+        str,
+        typer.Option("--backend", help="Embedding backend used for the index."),
+    ] = "clap",
+    device: Annotated[
+        str | None,
+        typer.Option("--device", help="Model device, e.g. cpu or cuda."),
+    ] = None,
+) -> None:
+    """Search an existing vector index without scanning audio files."""
+    try:
+        engine = _open_engine(store_dir=store_dir, backend=backend, device=device)
+        results = engine.search(query, top_k=top_k)
+    except Exception as exc:
+        console.print(f"[bold red]Search failed:[/bold red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+    table = Table(title=f"Top {top_k} Results for '{query}'")
+    table.add_column("Score", justify="right", style="cyan", no_wrap=True)
+    table.add_column("File", style="magenta")
+    table.add_column("Timestamp", justify="right", style="green")
+
+    for result in results:
+        table.add_row(
+            f"{result.score:.4f}",
+            str(result.metadata.get("filename", result.filepath)),
+            f"{result.timestamp_range.start:.1f}s-{result.timestamp_range.end:.1f}s",
+        )
+
+    if results:
+        console.print(table)
+    else:
+        console.print("[yellow]No results found.[/yellow]")
+
+
+@app.command()
+def stats(
+    store_dir: Annotated[
+        Path,
+        typer.Option("--store-dir", help="Directory containing the index."),
+    ] = Path(".echovector"),
+    backend: Annotated[
+        str,
+        typer.Option("--backend", help="Embedding backend used for the index."),
+    ] = "clap",
+    device: Annotated[
+        str | None,
+        typer.Option("--device", help="Model device, e.g. cpu or cuda."),
+    ] = None,
+) -> None:
+    """Display statistics about the current index."""
+    try:
+        stats_data = _open_engine(store_dir=store_dir, backend=backend, device=device).stats()
+    except Exception as exc:
+        console.print(f"[bold red]Stats failed:[/bold red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+    table = Table(title="Index Statistics", show_header=False)
+    table.add_column("Metric", style="cyan")
+    table.add_column("Value", style="magenta")
+
+    for key, value in stats_data.items():
+        table.add_row(key, str(value))
+
+    console.print(table)
+
+
+if __name__ == "__main__":
+    app()

echovector/core.py

@@ -0,0 +1,289 @@
+"""Core public API for EchoVector."""
+
+from collections.abc import Sequence
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import Any, cast
+
+import numpy as np
+import numpy.typing as npt
+import soundfile as sf
+
+from echovector.audio.metadata import extract_metadata
+from echovector.audio.processor import AudioProcessor as FileAudioProcessor
+from echovector.embeddings.base import EmbeddingBackend
+from echovector.embeddings.factory import get_embedding_model
+from echovector.indexing.faiss_index import FaissIndex
+from echovector.search.results import SearchResult, TimestampRange
+
+AUDIO_EXTENSIONS = {".wav", ".mp3", ".flac", ".m4a", ".ogg", ".aiff", ".aif"}
+
+
+class EchoVector:
+    """High-level interface for indexing and searching audio files."""
+
+    def __init__(
+        self,
+        store_dir: str | Path = ".echovector",
+        backend: str | EmbeddingBackend = "clap",
+        recursive: bool = True,
+        chunk_seconds: float = 10.0,
+        overlap_seconds: float = 1.0,
+        sample_rate: int = 48_000,
+        **backend_kwargs: Any,
+    ) -> None:
+        """Initialize EchoVector."""
+        if chunk_seconds <= 0.0:
+            raise ValueError("chunk_seconds must be positive.")
+        if overlap_seconds < 0.0:
+            raise ValueError("overlap_seconds cannot be negative.")
+        if overlap_seconds >= chunk_seconds:
+            raise ValueError("overlap_seconds must be smaller than chunk_seconds.")
+
+        self.store_dir = Path(store_dir)
+        self.store_dir.mkdir(parents=True, exist_ok=True)
+        self.index_path = self.store_dir / "index.faiss"
+        self.db_path = self.store_dir / "metadata.sqlite"
+        self.recursive = recursive
+        self.chunk_seconds = chunk_seconds
+        self.overlap_seconds = overlap_seconds
+        self.sample_rate = sample_rate
+        self.audio_processor = FileAudioProcessor(target_sample_rate=sample_rate, mono=True)
+
+        self.embedder = (
+            get_embedding_model(backend, **backend_kwargs) if isinstance(backend, str) else backend
+        )
+        self.index_backend = FaissIndex(
+            dimension=self.embedder.embedding_dim,
+            db_path=str(self.db_path),
+        )
+
+        if self.index_path.exists():
+            self.index_backend.load(str(self.index_path))
+
+    def index(
+        self,
+        targets: str | Path | Sequence[str | Path],
+        recursive: bool | None = None,
+        batch_size: int = 16,
+        force: bool = False,
+    ) -> int:
+        """Index audio chunks from paths or directories.
+
+        Args:
+            targets: One or more file paths or directories to index.
+            recursive: Override the instance-level recursive setting.
+            batch_size: Number of chunks to embed per batch.
+            force: If True, remove and re-index files that are already stored.
+                   If False (default), already-indexed files are skipped.
+
+        Returns:
+            Number of new chunks added to the index.
+        """
+        files = self._resolve_audio_files(
+            targets,
+            self.recursive if recursive is None else recursive,
+        )
+        if not files:
+            return 0
+
+        if force:
+            for file_path in files:
+                int_ids = self.index_backend.store.delete_by_filepath(str(file_path))
+                if int_ids:
+                    self.index_backend.remove_int_ids(int_ids)
+        else:
+            files = [f for f in files if not self.index_backend.store.has_filepath(str(f))]
+            if not files:
+                return 0
+
+        indexed_chunks = 0
+        with TemporaryDirectory(prefix="echovector-chunks-") as temp_dir:
+            chunk_paths: list[Path] = []
+            chunk_ids: list[str] = []
+            chunk_metadata: list[dict[str, Any]] = []
+
+            for file_path in files:
+                audio = self.audio_processor.load_audio(str(file_path))
+                for (
+                    chunk_number,
+                    start_seconds,
+                    end_seconds,
+                    chunk_audio,
+                ) in self._iter_chunks(audio):
+                    chunk_path = Path(temp_dir) / f"chunk-{indexed_chunks:08d}.wav"
+                    sf.write(chunk_path, chunk_audio, self.sample_rate)
+                    chunk_paths.append(chunk_path)
+                    chunk_ids.append(f"{file_path}#{start_seconds:.3f}-{end_seconds:.3f}")
+                    chunk_metadata.append(
+                        self._metadata_for_chunk(
+                            file_path,
+                            chunk_number,
+                            start_seconds,
+                            end_seconds,
+                        )
+                    )
+                    indexed_chunks += 1
+
+                    if len(chunk_paths) >= batch_size:
+                        self._add_chunk_batch(chunk_paths, chunk_ids, chunk_metadata)
+                        chunk_paths = []
+                        chunk_ids = []
+                        chunk_metadata = []
+
+            if chunk_paths:
+                self._add_chunk_batch(chunk_paths, chunk_ids, chunk_metadata)
+
+        self.index_backend.save(str(self.index_path))
+        return indexed_chunks
+
+    def search(self, query: str, top_k: int = 5) -> list[SearchResult]:
+        """Search indexed audio with a text query."""
+        if top_k < 0:
+            raise ValueError("top_k must be non-negative.")
+        if top_k == 0:
+            return []
+
+        query_embedding = self._normalize_rows(self.embedder.embed_text([query]))
+        distances, ids, metadata_rows = self.index_backend.search(query_embedding, k=top_k)
+
+        results: list[SearchResult] = []
+        for offset, string_id in enumerate(ids[0] if ids else []):
+            if string_id is None:
+                continue
+            metadata = metadata_rows[0][offset] if metadata_rows and metadata_rows[0] else {}
+            metadata = metadata or {}
+            results.append(
+                SearchResult(
+                    filepath=str(metadata.get("filepath", string_id)),
+                    timestamp_range=TimestampRange(
+                        start=float(metadata.get("start", 0.0)),
+                        end=float(metadata.get("end", metadata.get("duration", 0.0))),
+                    ),
+                    score=float(distances[0][offset]),
+                    metadata=metadata,
+                )
+            )
+
+        return results
+
+    def stats(self) -> dict[str, Any]:
+        """Return basic index statistics."""
+        return {
+            "store_dir": str(self.store_dir),
+            "index_path": str(self.index_path),
+            "metadata_path": str(self.db_path),
+            "embedding_dim": self.embedder.embedding_dim,
+            "chunks": int(self.index_backend.index.ntotal),
+            "vectors": int(self.index_backend.index.ntotal),
+            "chunk_seconds": self.chunk_seconds,
+            "overlap_seconds": self.overlap_seconds,
+        }
+
+    def reset(self) -> None:
+        """Clear the current on-disk and in-memory index."""
+        if self.index_path.exists():
+            self.index_path.unlink()
+        if self.db_path.exists():
+            self.index_backend.store.close()
+            self.db_path.unlink()
+        self.index_backend = FaissIndex(
+            dimension=self.embedder.embedding_dim,
+            db_path=str(self.db_path),
+        )
+
+    def _resolve_audio_files(
+        self,
+        targets: str | Path | Sequence[str | Path],
+        recursive: bool,
+    ) -> list[Path]:
+        target_list = [targets] if isinstance(targets, (str, Path)) else targets
+        files: list[Path] = []
+
+        for target in target_list:
+            path = Path(target).expanduser()
+            if path.is_dir():
+                iterator = path.rglob("*") if recursive else path.glob("*")
+                files.extend(
+                    candidate
+                    for candidate in iterator
+                    if candidate.is_file() and candidate.suffix.lower() in AUDIO_EXTENSIONS
+                )
+            elif path.is_file() and path.suffix.lower() in AUDIO_EXTENSIONS:
+                files.append(path)
+            elif not path.exists():
+                raise FileNotFoundError(f"Audio path not found: {path}")
+
+        return sorted(dict.fromkeys(files))
+
+    def _metadata_for_chunk(
+        self,
+        path: Path,
+        chunk_number: int,
+        start_seconds: float,
+        end_seconds: float,
+    ) -> dict[str, Any]:
+        metadata = extract_metadata(str(path))
+        return {
+            "filepath": str(path),
+            "filename": path.name,
+            "chunk_id": chunk_number,
+            "start": start_seconds,
+            "end": end_seconds,
+            "chunk_duration": end_seconds - start_seconds,
+            "duration": metadata.duration,
+            "sample_rate": metadata.sample_rate,
+            "channels": metadata.channels,
+            "format": metadata.format,
+            "file_size": metadata.file_size,
+        }
+
+    def _iter_chunks(
+        self,
+        audio: npt.NDArray[np.float32],
+    ) -> list[tuple[int, float, float, npt.NDArray[np.float32]]]:
+        chunk_samples = round(self.chunk_seconds * self.sample_rate)
+        overlap_samples = round(self.overlap_seconds * self.sample_rate)
+        step_samples = chunk_samples - overlap_samples
+
+        chunks: list[tuple[int, float, float, npt.NDArray[np.float32]]] = []
+        if len(audio) == 0:
+            return chunks
+
+        start_sample = 0
+        chunk_number = 0
+        while start_sample < len(audio):
+            end_sample = min(start_sample + chunk_samples, len(audio))
+            chunk = audio[start_sample:end_sample]
+            start_seconds = start_sample / self.sample_rate
+            end_seconds = end_sample / self.sample_rate
+            chunks.append((chunk_number, start_seconds, end_seconds, chunk))
+
+            if end_sample == len(audio):
+                break
+            start_sample += step_samples
+            chunk_number += 1
+
+        return chunks
+
+    def _add_chunk_batch(
+        self,
+        chunk_paths: Sequence[Path],
+        chunk_ids: Sequence[str],
+        chunk_metadata: Sequence[dict[str, Any]],
+    ) -> None:
+        embeddings = self.embedder.embed_audio([str(path) for path in chunk_paths])
+        self.index_backend.add(
+            self._normalize_rows(embeddings),
+            list(chunk_ids),
+            list(chunk_metadata),
+        )
+
+    def _normalize_rows(
+        self,
+        embeddings: npt.NDArray[np.float32],
+    ) -> npt.NDArray[np.float32]:
+        embeddings_f32 = np.asarray(embeddings, dtype=np.float32)
+        norms = np.linalg.norm(embeddings_f32, axis=1, keepdims=True)
+        norms[norms == 0.0] = 1.0
+        return cast("npt.NDArray[np.float32]", embeddings_f32 / norms)

echovector/embeddings/__init__.py

@@ -0,0 +1,15 @@
+"""EchoVector embeddings module.
+
+Contains backends for generating embeddings from audio and text.
+"""
+
+from echovector.embeddings.base import EmbeddingBackend
+from echovector.embeddings.cache import EmbeddingCache
+from echovector.embeddings.factory import EmbeddingFactory, get_embedding_model
+
+__all__ = [
+    "EmbeddingBackend",
+    "EmbeddingCache",
+    "EmbeddingFactory",
+    "get_embedding_model",
+]

echovector/embeddings/ast_model.py

@@ -0,0 +1,41 @@
+"""AST (Audio Spectrogram Transformer) embedding backend stub."""
+
+import numpy as np
+import numpy.typing as npt
+
+from echovector.embeddings.base import EmbeddingBackend
+
+
+class ASTBackend(EmbeddingBackend):
+    """Stub implementation for the AST embedding backend."""
+
+    def __init__(self, model_name: str = "MIT/ast-finetuned-audioset-10-10-0.4593") -> None:
+        """Initialize the stub AST backend."""
+        self.model_name = model_name
+
+    @property
+    def embedding_dim(self) -> int:
+        """Return a stub embedding dimension."""
+        return 768
+
+    def embed_audio(self, audio_paths: list[str]) -> npt.NDArray[np.float32]:
+        """Embed a batch of audio files.
+
+        Args:
+            audio_paths: List of file paths to audio files.
+
+        Raises:
+            NotImplementedError: As this is a stub.
+        """
+        raise NotImplementedError("AST audio embedding not implemented.")
+
+    def embed_text(self, texts: list[str]) -> npt.NDArray[np.float32]:
+        """Embed a batch of text queries.
+
+        Args:
+            texts: List of text strings.
+
+        Raises:
+            NotImplementedError: AST backend does not support text embeddings.
+        """
+        raise NotImplementedError("AST backend does not support text embeddings.")

echovector/embeddings/base.py

@@ -0,0 +1,43 @@
+"""Base protocols and types for EchoVector embedding backends."""
+
+from typing import Protocol
+
+import numpy as np
+import numpy.typing as npt
+
+
+class EmbeddingBackend(Protocol):
+    """Protocol for embedding models."""
+
+    @property
+    def embedding_dim(self) -> int:
+        """Return the dimensionality of the generated embeddings.
+
+        Returns:
+            The integer dimension size.
+        """
+        ...
+
+    def embed_audio(self, audio_paths: list[str]) -> npt.NDArray[np.float32]:
+        """Embed a batch of audio files.
+
+        Args:
+            audio_paths: List of file paths to audio files.
+
+        Returns:
+            A numpy array of shape (batch_size, embedding_dim).
+        """
+        ...
+
+    def embed_text(self, texts: list[str]) -> npt.NDArray[np.float32]:
+        """Embed a batch of text queries.
+
+        Raises NotImplementedError if the backend does not support text embeddings.
+
+        Args:
+            texts: List of text strings.
+
+        Returns:
+            A numpy array of shape (batch_size, embedding_dim).
+        """
+        ...

echovector/embeddings/cache.py

@@ -0,0 +1,96 @@
+"""Content-addressed caching for audio embeddings."""
+
+import hashlib
+from pathlib import Path
+from typing import cast
+
+import numpy as np
+import numpy.typing as npt
+
+
+class EmbeddingCache:
+    """Content-addressed storage for embeddings.
+
+    Embeddings are cached based on the hash of the file content or text.
+    """
+
+    def __init__(self, cache_dir: str | Path = ".cache/echovector") -> None:
+        """Initialize the embedding cache.
+
+        Args:
+            cache_dir: Directory to store the cache files.
+        """
+        self.cache_dir = Path(cache_dir)
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+    def _compute_file_hash(self, filepath: str) -> str:
+        """Compute SHA-256 hash of a file's contents."""
+        hasher = hashlib.sha256()
+        with open(filepath, "rb") as f:
+            while chunk := f.read(8192):
+                hasher.update(chunk)
+        return hasher.hexdigest()
+
+    def _compute_text_hash(self, text: str) -> str:
+        """Compute SHA-256 hash of a text string."""
+        hasher = hashlib.sha256()
+        hasher.update(text.encode("utf-8"))
+        return hasher.hexdigest()
+
+    def _get_cache_path(self, hash_key: str) -> Path:
+        """Get the file path for a cached embedding."""
+        return self.cache_dir / f"{hash_key}.npy"
+
+    def get_audio_embedding(self, filepath: str) -> npt.NDArray[np.float32] | None:
+        """Retrieve cached embedding for an audio file.
+
+        Args:
+            filepath: Path to the audio file.
+
+        Returns:
+            The embedding array if cached, else None.
+        """
+        hash_key = self._compute_file_hash(filepath)
+        cache_path = self._get_cache_path(hash_key)
+
+        if cache_path.exists():
+            return cast("npt.NDArray[np.float32]", np.load(cache_path))
+        return None
+
+    def put_audio_embedding(self, filepath: str, embedding: npt.NDArray[np.float32]) -> None:
+        """Store embedding for an audio file in cache.
+
+        Args:
+            filepath: Path to the audio file.
+            embedding: The embedding array.
+        """
+        hash_key = self._compute_file_hash(filepath)
+        cache_path = self._get_cache_path(hash_key)
+        np.save(cache_path, embedding)
+
+    def get_text_embedding(self, text: str) -> npt.NDArray[np.float32] | None:
+        """Retrieve cached embedding for a text string.
+
+        Args:
+            text: The text string.
+
+        Returns:
+            The embedding array if cached, else None.
+        """
+        hash_key = self._compute_text_hash(text)
+        cache_path = self._get_cache_path(hash_key)
+
+        if cache_path.exists():
+            return cast("npt.NDArray[np.float32]", np.load(cache_path))
+        return None
+
+    def put_text_embedding(self, text: str, embedding: npt.NDArray[np.float32]) -> None:
+        """Store embedding for a text string in cache.
+
+        Args:
+            text: The text string.
+            embedding: The embedding array.
+        """
+        hash_key = self._compute_text_hash(text)
+        cache_path = self._get_cache_path(hash_key)
+        np.save(cache_path, embedding)