echo-vector 0.1.1__tar.gz

echo_vector-0.1.1/.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "git add -A && git diff --cached --quiet || (COUNT=$(git diff --cached --name-only | wc -l | tr -d ' '); FILES=$(git diff --cached --name-only | head -3 | tr '\n' ' ' | sed 's/ $//'); if [ \"$COUNT\" -le 3 ]; then MSG=\"auto: edit $FILES\"; else FIRST=$(git diff --cached --name-only | head -2 | paste -sd ', '); MSG=\"auto: edit $COUNT files ($FIRST, ...)\"; fi; git commit -m \"$MSG\" 2>/dev/null || true)",
+            "statusMessage": "Committing changes..."
+          }
+        ]
+      }
+    ]
+  }
+}

echo_vector-0.1.1/.github/workflows/workflow.yml

@@ -0,0 +1,78 @@
+name: CI/CD
+
+on:
+  push:
+    branches: [main, master]
+    tags: ["v*.*.*"]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install ruff
+        run: pip install "ruff>=0.3,<1"
+      - name: Check formatting
+        run: ruff format --check echovector/ tests/
+      - name: Check linting
+        run: ruff check echovector/ tests/
+
+  typecheck:
+    name: Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install package with dev and api deps
+        run: pip install -e ".[dev,api]"
+      - name: Run mypy
+        run: mypy echovector/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package with dev and api deps
+        run: pip install -e ".[dev,api]"
+      - name: Format code
+        run: ruff format echovector/ tests/
+      - name: Run tests
+        run: pytest tests/ -m "not slow and not gpu" -q
+
+  publish:
+    name: Publish to PyPI
+    needs: [lint, typecheck, test]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install hatch
+        run: pip install hatch
+      - name: Build package
+        run: hatch build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

echo_vector-0.1.1/.gitignore

@@ -0,0 +1,67 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+.mutmut-cache/
+.hypothesis/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# ML Models & Data
+*.pt
+*.pth
+*.onnx
+*.bin
+models/
+*.faiss
+*.db
+
+# Audio fixtures (keep generated ones)
+tests/fixtures/audio/*.wav
+tests/fixtures/audio/*.mp3
+tests/fixtures/audio/*.flac
+tests/fixtures/audio/*.m4a
+!tests/fixtures/audio/.gitkeep
+
+# Documentation build
+site/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.local
+
+# Benchmark outputs
+benchmark_results/

echo_vector-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.12
+    hooks:
+      - id: ruff-format
+      - id: ruff
+        args: [--fix]

echo_vector-0.1.1/.python-version

@@ -0,0 +1 @@
+3.12

echo_vector-0.1.1/CLAUDE.md

@@ -0,0 +1,88 @@
+# Claude Code Behavior Rules (Speed Optimized)
+
+## Core principle
+Prefer fast, minimal, direct edits over exploration or deep analysis.
+
+Optimize for:
+- speed of change
+- minimal tool usage
+- smallest sufficient context
+
+Avoid unnecessary searching or reasoning depth unless required.
+
+---
+
+## Planning
+- Skip planning for small or obvious changes.
+- For larger tasks: max 3–5 bullets only.
+- Do not over-explain or explore alternatives unless asked.
+
+---
+
+## File editing behavior
+- Make targeted edits directly when the affected files are known or implied.
+- Do NOT scan the full codebase before editing unless necessary.
+- Prefer local reasoning over global search.
+- Group edits into a single pass per file.
+
+Avoid:
+- broad repository exploration before action
+- unnecessary dependency tracing
+- repeated file re-reading
+
+---
+
+## Progress updates
+Only report when:
+- an edit is completed
+- a bug cause is identified
+- a blocker is encountered
+
+Keep updates:
+- under 50–75 words
+- bullet-based only
+- no narration of intermediate steps
+
+---
+
+## Debugging style
+Use a fast hypothesis model:
+
+1. likely cause
+2. quick verification
+3. fix
+
+Do NOT:
+- exhaustively search all possible causes
+- inspect unrelated modules unless required
+
+---
+
+## Tool usage rules
+- Prefer fewer tool calls
+- Avoid repeated file opens
+- Do not re-read files unless state has changed
+- Do not perform broad searches unless explicitly requested
+
+---
+
+## Code changes
+- Prioritize minimal viable fix
+- Avoid large refactors unless requested
+- Do not optimize prematurely
+- Preserve existing structure unless necessary
+
+---
+
+## When to slow down
+Only increase exploration when:
+- multiple files clearly involved
+- root cause is unknown after initial check
+- system-level change is required
+
+---
+
+## Output style
+- Default to short bullet points
+- Avoid repetition of context
+- No step-by-step narration unless debugging complex issues

echo_vector-0.1.1/Makefile

@@ -0,0 +1,48 @@
+.PHONY: install lint typecheck test test-unit test-integration test-e2e test-perf coverage mutate docs serve-docs clean
+
+install:
+	uv sync --all-extras
+
+lint:
+	uv run ruff check echovector/ tests/
+	uv run ruff format --check echovector/ tests/
+
+lint-fix:
+	uv run ruff check --fix echovector/ tests/
+	uv run ruff format echovector/ tests/
+
+typecheck:
+	uv run mypy echovector/
+
+test:
+	uv run pytest tests/ -v
+
+test-unit:
+	uv run pytest tests/unit/ -v
+
+test-integration:
+	uv run pytest tests/integration/ -v -m integration
+
+test-e2e:
+	uv run pytest tests/e2e/ -v -m e2e
+
+test-perf:
+	uv run pytest tests/performance/ -v -m performance
+
+coverage:
+	uv run pytest tests/ --cov=echovector --cov-report=html --cov-report=term-missing
+
+mutate:
+	uv run mutmut run
+
+docs:
+	cd docs && uv run mkdocs build
+
+serve-docs:
+	cd docs && uv run mkdocs serve
+
+clean:
+	rm -rf dist/ build/ *.egg-info/ .pytest_cache/ .mypy_cache/ .ruff_cache/ htmlcov/ .coverage site/ .mutmut-cache/
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+
+all: lint typecheck test

echo_vector-0.1.1/PKG-INFO

@@ -0,0 +1,288 @@
+Metadata-Version: 2.4
+Name: echo_vector
+Version: 0.1.1
+Summary: Semantic text search over audio files without full transcription
+Project-URL: Homepage, https://github.com/ahron-maslin/echo_vector
+Project-URL: Documentation, https://github.com/ahron-maslin/echo_vector#readme
+Project-URL: Repository, https://github.com/ahron-maslin/echo_vector
+Project-URL: Issues, https://github.com/ahron-maslin/echo_vector/issues
+Project-URL: Changelog, https://github.com/ahron-maslin/echo_vector/blob/main/CHANGELOG.md
+Author: EchoVector Contributors
+License-Expression: MIT
+Keywords: CLAP,FAISS,audio,embeddings,search,semantic,vector
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: faiss-cpu<2,>=1.7
+Requires-Dist: librosa<1,>=0.10
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: pydantic<3,>=2.5
+Requires-Dist: pydub<1,>=0.25
+Requires-Dist: rich<14,>=13.7
+Requires-Dist: soundfile<1,>=0.12
+Requires-Dist: tqdm<5,>=4.66
+Requires-Dist: typer[all]<1,>=0.12
+Provides-Extra: all
+Requires-Dist: fastapi<1,>=0.109; extra == 'all'
+Requires-Dist: httpx2<3,>=2.0; extra == 'all'
+Requires-Dist: hypothesis<7,>=6.92; extra == 'all'
+Requires-Dist: mkdocs-gen-files<1,>=0.5; extra == 'all'
+Requires-Dist: mkdocs-literate-nav<1,>=0.6; extra == 'all'
+Requires-Dist: mkdocs-material<10,>=9.5; extra == 'all'
+Requires-Dist: mkdocstrings[python]<1,>=0.24; extra == 'all'
+Requires-Dist: mutmut<3,>=2.4; extra == 'all'
+Requires-Dist: mypy<2,>=1.8; extra == 'all'
+Requires-Dist: pre-commit<4,>=3.6; extra == 'all'
+Requires-Dist: pytest-asyncio<1,>=0.23; extra == 'all'
+Requires-Dist: pytest-cov<6,>=5.0; extra == 'all'
+Requires-Dist: pytest-xdist<4,>=3.5; extra == 'all'
+Requires-Dist: pytest<9,>=8.0; extra == 'all'
+Requires-Dist: ruff<1,>=0.15; extra == 'all'
+Requires-Dist: torch<3,>=2.1; extra == 'all'
+Requires-Dist: transformers<5,>=4.36; extra == 'all'
+Requires-Dist: uvicorn[standard]<1,>=0.27; extra == 'all'
+Provides-Extra: api
+Requires-Dist: fastapi<1,>=0.109; extra == 'api'
+Requires-Dist: uvicorn[standard]<1,>=0.27; extra == 'api'
+Provides-Extra: clap
+Requires-Dist: torch<3,>=2.1; extra == 'clap'
+Requires-Dist: transformers<5,>=4.36; extra == 'clap'
+Provides-Extra: dev
+Requires-Dist: httpx2<3,>=2.0; extra == 'dev'
+Requires-Dist: hypothesis<7,>=6.92; extra == 'dev'
+Requires-Dist: mutmut<3,>=2.4; extra == 'dev'
+Requires-Dist: mypy<2,>=1.8; extra == 'dev'
+Requires-Dist: pre-commit<4,>=3.6; extra == 'dev'
+Requires-Dist: pytest-asyncio<1,>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov<6,>=5.0; extra == 'dev'
+Requires-Dist: pytest-xdist<4,>=3.5; extra == 'dev'
+Requires-Dist: pytest<9,>=8.0; extra == 'dev'
+Requires-Dist: ruff<1,>=0.15; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-gen-files<1,>=0.5; extra == 'docs'
+Requires-Dist: mkdocs-literate-nav<1,>=0.6; extra == 'docs'
+Requires-Dist: mkdocs-material<10,>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]<1,>=0.24; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# 🔊 EchoVector
+
+> **Semantic text search over audio files — without full transcription.**
+
+[![CI](https://github.com/echovector/echovector/actions/workflows/test.yml/badge.svg)](https://github.com/echovector/echovector/actions/workflows/test.yml)
+[![Coverage](https://img.shields.io/badge/coverage-%3E95%25-brightgreen)](.)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](.)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+---
+
+## What is EchoVector?
+
+EchoVector indexes audio files by generating **semantic embeddings directly from audio waveforms**, then lets you search them with natural language text queries — all without transcribing a single word.
+
+### Traditional approach (slow & expensive)
+
+```
+Audio → Full Transcription → Text Embeddings → Text Search
+```
+
+### EchoVector approach (fast & efficient)
+
+```
+Audio → Audio Chunks → Audio Embeddings ─┐
+                                          ├─► ANN Search → Results
+Text Query → Text Embedding ──────────────┘
+```
+
+## Features
+
+- 🎵 **Multi-format support** — MP3, WAV, FLAC, M4A
+- 🧠 **Direct audio embeddings** — No transcription needed
+- 🔍 **Semantic search** — Query with natural language
+- ⚡ **FAISS-powered** — Approximate nearest neighbor search
+- 🔌 **Pluggable backends** — CLAP, Whisper, wav2vec2, HuBERT, AST
+- 🧪 **Offline smoke backend** — `local` backend for CI/Kaggle tests without model downloads
+- 📊 **Rich CLI** — Progress bars, colors, benchmarking mode
+- 🌐 **REST API** — Optional FastAPI server
+- 📦 **Production-ready** — Typed, tested, documented
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install echovector
+```
+
+Or with uv:
+
+```bash
+uv add echovector
+```
+
+### CLI Usage
+
+```bash
+# One-time indexing: split audio into timestamped chunks and embed each chunk
+echovector index ./meetings
+
+# Fast repeated search: embed only the text query and search the saved FAISS index
+echovector search "discussion about transformers"
+
+# Search with options
+echovector search "pricing strategy" --top-k 10
+
+# View index statistics
+echovector stats
+```
+
+For a no-download smoke test, use the deterministic local backend:
+
+```bash
+echovector index ./meetings --backend local --store-dir ./ev-index
+echovector search "high alarm tone" --backend local --store-dir ./ev-index
+echovector stats --backend local --store-dir ./ev-index
+```
+
+The search command does not reopen or scan the audio files. All expensive audio processing happens
+during `index`; `search` loads the saved vector index, embeds the short text query, and returns the
+nearest timestamped chunks.
+
+### Python API
+
+```python
+from echovector import EchoVector
+
+ev = EchoVector()
+
+# Index audio files
+ev.index("./meetings")
+
+# Search with natural language
+results = ev.search("conversation about CUDA kernels")
+
+for r in results:
+    print(
+        f"{r.filepath} "
+        f"[{r.timestamp_range.start:.1f}s - {r.timestamp_range.end:.1f}s] "
+        f"score={r.score:.4f}"
+    )
+```
+
+## Testing on Kaggle
+
+Kaggle is useful for GPU-backed CLAP tests, but first check the runtime Python version:
+
+```python
+import sys
+print(sys.version)
+```
+
+EchoVector currently declares `Python >=3.12`. If the Kaggle image is older, install and test in a
+Python 3.12-capable environment instead, or relax the project requirement only after validating the
+test suite on that Python version.
+
+### Notebook smoke test without internet/model downloads
+
+Upload this repository as a Kaggle dataset, attach it to a notebook, then run:
+
+```python
+%cd /kaggle/input/<your-echo-vector-dataset>
+!pip install -e . --no-deps
+!pip install numpy soundfile librosa faiss-cpu typer rich pydantic
+!python -m pytest tests/ -q
+```
+
+Create a tiny audio corpus and test the real CLI/index path:
+
+```python
+import os
+import numpy as np
+import soundfile as sf
+
+audio_dir = "/kaggle/working/ev-audio"
+index_dir = "/kaggle/working/ev-index"
+os.makedirs(audio_dir, exist_ok=True)
+
+sr = 16000
+t = np.linspace(0, 1.0, sr, endpoint=False)
+sf.write(f"{audio_dir}/high_tone.wav", 0.25 * np.sin(2 * np.pi * 880 * t), sr)
+sf.write(f"{audio_dir}/low_tone.wav", 0.25 * np.sin(2 * np.pi * 110 * t), sr)
+```
+
+```python
+!echovector index /kaggle/working/ev-audio --backend local --store-dir /kaggle/working/ev-index --reset
+!echovector search "high alarm tone" --backend local --store-dir /kaggle/working/ev-index --top-k 2
+!echovector stats --backend local --store-dir /kaggle/working/ev-index
+```
+
+This validates packaging, audio loading, FAISS persistence, metadata storage, and the CLI without
+depending on Hugging Face downloads.
+
+### CLAP semantic test
+
+For actual semantic text-to-audio search, enable internet in the notebook settings and use a GPU
+runtime if available:
+
+```python
+!pip install transformers torch faiss-cpu librosa soundfile
+!echovector index /kaggle/input/<audio-dataset> --backend clap --device cuda --store-dir /kaggle/working/clap-index --recursive --reset
+!echovector search "people discussing pricing strategy" --backend clap --device cuda --store-dir /kaggle/working/clap-index --top-k 10
+```
+
+If GPU is unavailable, replace `--device cuda` with `--device cpu`; it will be slower. Keep indexes
+under `/kaggle/working` so they are writable during the notebook session.
+
+## Architecture
+
+```
+echovector/
+├── audio/        # Audio loading, chunking, streaming, metadata
+├── embeddings/   # Pluggable embedding backends (CLAP, Whisper, etc.)
+├── indexing/     # Vector index backends (FAISS, with pluggable design)
+├── search/       # Search engine, filtering, result hydration
+├── cli/          # Typer-based CLI with Rich output
+├── api/          # Optional FastAPI server
+├── evaluation/   # Metrics (recall@k, throughput)
+├── benchmarks/   # Reproducible benchmark harness
+└── utils/        # Config, logging, helpers
+```
+
+## Supported Embedding Backends
+
+| Backend | Text+Audio Aligned | Notes |
+|---------|-------------------|-------|
+| **CLAP** (default) | ✅ | Best for text→audio search |
+| Whisper Encoder | ❌ | Audio-only embeddings |
+| wav2vec2 | ❌ | Audio-only, good for speech |
+| HuBERT | ❌ | Audio-only, self-supervised |
+| Audio Spectrogram Transformer | ❌ | Audio-only, classification-focused |
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/echovector/echovector.git
+cd echovector
+uv sync --all-extras
+
+# Run checks
+make lint
+make typecheck
+make test
+make coverage
+```
+
+## License
+
+MIT