turboquant-tools 0.1.0__tar.gz

turboquant_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FreezeVII
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

turboquant_tools-0.1.0/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: turboquant-tools
+Version: 0.1.0
+Summary: CLI + MCP Server + Python Library for TurboQuant-based embedding compression
+Author: FreezeVII
+License: MIT
+Project-URL: Homepage, https://github.com/FreezeVII/turboquant-tools
+Project-URL: Source, https://github.com/FreezeVII/turboquant-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: click>=8.0
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=0.1; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# 🧊 TurboQuant Tools
+
+> **Compress AI embeddings by 5–7× with near-lossless quality.**
+
+CLI + Python Library + [MCP](https://modelcontextprotocol.io) Server for extreme vector compression using [Google's TurboQuant](https://research.google/blog/turboquant-redefining-ai-efficiency-with-extreme-compression/) (PolarQuant + QJL) — wrapped in a clean numpy-first API.
+
+[![PyPI](https://img.shields.io/pypi/v/turboquant-tools)](https://pypi.org/project/turboquant-tools/)
+[![Python](https://img.shields.io/pypi/pyversions/turboquant-tools)](https://www.python.org)
+[![License](https://img.shields.io/github/license/FreezeVII/turboquant-tools)](LICENSE)
+[![Tests](https://github.com/FreezeVII/turboquant-tools/actions/workflows/python-tests.yml/badge.svg)](https://github.com/FreezeVII/turboquant-tools/actions)
+
+---
+
+## 🚀 Quick Start
+
+```bash
+pip install turboquant-tools
+```
+
+Compress a `.npy` embedding file:
+
+```bash
+turboquant compress embeddings.npy compressed.tq
+```
+
+Restore:
+
+```bash
+turboquant decompress compressed.tq restored.npy
+```
+
+Estimate savings:
+
+```bash
+turboquant estimate embeddings.npy --bits 3
+# Original: 153.00 MB -> Compressed: 20.13 MB (7.60×, save 87%)
+```
+
+---
+
+## 📦 What's Inside
+
+| Command / Tool | Description |
+|---|---|
+| `turboquant compress` | Compress `.npy` embeddings → `.tq` binary |
+| `turboquant decompress` | Restore `.tq` → `.npy` |
+| `turboquant estimate` | Predict compression ratio before running |
+| `turboquant mcp-server` | MCP stdio server (AI agent integration) |
+| Python `compress()` | Compress numpy arrays in code |
+| Python `decompress()` | Restore in code |
+
+---
+
+## 🔧 CLI Reference
+
+### compress
+
+```bash
+turboquant compress INPUT [OUTPUT] [OPTIONS]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `INPUT` | — | `.npy` file with float32 embeddings `(n, d)` |
+| `OUTPUT` | `{stem}_tq{b}.tq` | Output `.tq` file |
+| `-b, --bits` | `3` | Bit width (3 or 4) |
+| `-o, --output` | — | Alternative to positional OUTPUT |
+| `--no-qjl` | off | Skip QJL correction (faster, lower quality) |
+
+**Examples:**
+
+```bash
+# Basic 3-bit compression
+turboquant compress wiki_embeddings.npy wiki.tq
+
+# 4-bit compression (higher quality)
+turboquant compress embeddings.npy -b 4
+
+# Fast mode (no QJL)
+turboquant compress big_set.npy -b 3 --no-qjl
+```
+
+### decompress
+
+```bash
+turboquant decompress INPUT [OUTPUT]
+```
+
+### estimate
+
+```bash
+turboquant estimate INPUT [--bits N]
+```
+
+---
+
+## 🐍 Python API
+
+```python
+from turboquant_tools import compress, decompress, estimate_savings
+import numpy as np
+
+# Load or generate embeddings
+vectors = np.random.randn(10000, 384).astype(np.float32)
+
+# Compress (5–7× reduction)
+compressed = compress(vectors, bits=3, use_qjl=False)
+print(f"{vectors.nbytes / 1e6:.1f} MB → {compressed.nbytes / 1e6:.1f} MB ({compressed.memory.ratio:.1f}×)")
+
+# Restore
+restored = decompress(compressed)
+print(f"MAE: {np.abs(restored - vectors).mean():.4f}")
+
+# Estimate without running
+est = estimate_savings(n_vectors=100000, dim=768, bits=3)
+print(est)  # Original: X MB -> Compressed: Y MB (7.60×, save 87%)
+```
+
+**CompressedVectors** objects carry metadata:
+
+```python
+compressed.n_vectors   # original count
+compressed.dim         # original dimension
+compressed.nbytes      # compressed size in bytes
+compressed.memory      # MemoryBytes(original, compressed, ratio)
+compressed.data        # raw .tq bytes (save to disk)
+```
+
+---
+
+## 🤖 MCP Server (AI Agents)
+
+TurboQuant Tools ships with a native **MCP server** for AI agent integration — works with any MCP-compatible host (Hermes, Claude Desktop, etc.).
+
+### Start
+
+```bash
+turboquant mcp-server
+```
+
+### Register in your MCP client
+
+**Hermes Agent** (`~/.hermes/config.yaml`):
+
+```yaml
+mcp_servers:
+  turboquant-tools:
+    command: turboquant
+    args: ["mcp-server"]
+    enabled: true
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "turboquant-tools": {
+      "command": "turboquant",
+      "args": ["mcp-server"]
+    }
+  }
+}
+```
+
+### Available Tools
+
+| Tool | Description |
+|---|---|
+| `compress_embeddings` | Compress vectors in-memory |
+| `decompress_embeddings` | Restore compressed vectors |
+| `estimate_savings_mcp` | Predict compression ratio |
+| `embed_and_compress` | Embed texts via API + compress in one step |
+
+---
+
+## 📊 Performance
+
+Measured on random float32 embeddings (CPU, no GPU needed):
+
+| Vectors | Dim | Mode | Original | Compressed | Ratio | MAE |
+|---|---|---|---|---|---|---|
+| 20 | 384 | PolarQuant 3-bit | 30 KB | 10 KB | **3.0×** | 2.6 |
+| 20 | 384 | TurboQuant (QJL) | 30 KB | 20 KB | 1.5× | 3.3 |
+| 100K | 384 | PolarQuant 3-bit | 153 MB | 20 MB | **7.6×** | — |
+
+**Use cases:**
+- **RAG pipelines** — compress vector DB indexes
+- **Edge devices** — fit embeddings in limited RAM
+- **Storage savings** — reduce cloud costs for large vector stores
+- **Memory-bound agents** — compress context vectors on the fly
+
+---
+
+## 🧪 Development
+
+```bash
+git clone https://github.com/FreezeVII/turboquant-tools.git
+cd turboquant-tools
+pip install -e .
+pip install pytest
+pytest tests/
+```
+
+### Run tests
+
+```bash
+pytest tests/ -v
+```
+
+---
+
+## 🧱 How It Works
+
+Two-stage compression inspired by [Google's TurboQuant](https://research.google/blog/turboquant-redefining-ai-efficiency-with-extreme-compression/):
+
+1. **PolarQuant** — Random Hadamard rotation + scalar quantization to 3–4 bits per dimension. Captures magnitude and direction.
+2. **QJL** (optional) — Quantized Johnson-Lindenstrauss residual correction. Recovers high-frequency detail lost in PolarQuant.
+
+Both stages run **CPU-only** via PyTorch — no GPU required. The `.tq` binary format uses a 30-byte header with magic bytes (`TQT2`) + packed indices and norms.
+
+Under the hood this wraps [OnlyTerp/turboquant](https://github.com/OnlyTerp/turboquant), a reference PyTorch implementation.
+
+---
+
+## 📄 License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+## 🙌 Contributing
+
+PRs welcome! Ideas:
+- FAISS index compression (`compress_faiss`)
+- Onnx / numpy-only backend (no PyTorch dep)
+- Streaming compression for billion-scale datasets
+- Pre-built wheels for faster install
+
+---
+
+<p align="center">Made with 🧊 for the vector search community.</p>

turboquant_tools-0.1.0/README.md

@@ -0,0 +1,242 @@
+# 🧊 TurboQuant Tools
+
+> **Compress AI embeddings by 5–7× with near-lossless quality.**
+
+CLI + Python Library + [MCP](https://modelcontextprotocol.io) Server for extreme vector compression using [Google's TurboQuant](https://research.google/blog/turboquant-redefining-ai-efficiency-with-extreme-compression/) (PolarQuant + QJL) — wrapped in a clean numpy-first API.
+
+[![PyPI](https://img.shields.io/pypi/v/turboquant-tools)](https://pypi.org/project/turboquant-tools/)
+[![Python](https://img.shields.io/pypi/pyversions/turboquant-tools)](https://www.python.org)
+[![License](https://img.shields.io/github/license/FreezeVII/turboquant-tools)](LICENSE)
+[![Tests](https://github.com/FreezeVII/turboquant-tools/actions/workflows/python-tests.yml/badge.svg)](https://github.com/FreezeVII/turboquant-tools/actions)
+
+---
+
+## 🚀 Quick Start
+
+```bash
+pip install turboquant-tools
+```
+
+Compress a `.npy` embedding file:
+
+```bash
+turboquant compress embeddings.npy compressed.tq
+```
+
+Restore:
+
+```bash
+turboquant decompress compressed.tq restored.npy
+```
+
+Estimate savings:
+
+```bash
+turboquant estimate embeddings.npy --bits 3
+# Original: 153.00 MB -> Compressed: 20.13 MB (7.60×, save 87%)
+```
+
+---
+
+## 📦 What's Inside
+
+| Command / Tool | Description |
+|---|---|
+| `turboquant compress` | Compress `.npy` embeddings → `.tq` binary |
+| `turboquant decompress` | Restore `.tq` → `.npy` |
+| `turboquant estimate` | Predict compression ratio before running |
+| `turboquant mcp-server` | MCP stdio server (AI agent integration) |
+| Python `compress()` | Compress numpy arrays in code |
+| Python `decompress()` | Restore in code |
+
+---
+
+## 🔧 CLI Reference
+
+### compress
+
+```bash
+turboquant compress INPUT [OUTPUT] [OPTIONS]
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `INPUT` | — | `.npy` file with float32 embeddings `(n, d)` |
+| `OUTPUT` | `{stem}_tq{b}.tq` | Output `.tq` file |
+| `-b, --bits` | `3` | Bit width (3 or 4) |
+| `-o, --output` | — | Alternative to positional OUTPUT |
+| `--no-qjl` | off | Skip QJL correction (faster, lower quality) |
+
+**Examples:**
+
+```bash
+# Basic 3-bit compression
+turboquant compress wiki_embeddings.npy wiki.tq
+
+# 4-bit compression (higher quality)
+turboquant compress embeddings.npy -b 4
+
+# Fast mode (no QJL)
+turboquant compress big_set.npy -b 3 --no-qjl
+```
+
+### decompress
+
+```bash
+turboquant decompress INPUT [OUTPUT]
+```
+
+### estimate
+
+```bash
+turboquant estimate INPUT [--bits N]
+```
+
+---
+
+## 🐍 Python API
+
+```python
+from turboquant_tools import compress, decompress, estimate_savings
+import numpy as np
+
+# Load or generate embeddings
+vectors = np.random.randn(10000, 384).astype(np.float32)
+
+# Compress (5–7× reduction)
+compressed = compress(vectors, bits=3, use_qjl=False)
+print(f"{vectors.nbytes / 1e6:.1f} MB → {compressed.nbytes / 1e6:.1f} MB ({compressed.memory.ratio:.1f}×)")
+
+# Restore
+restored = decompress(compressed)
+print(f"MAE: {np.abs(restored - vectors).mean():.4f}")
+
+# Estimate without running
+est = estimate_savings(n_vectors=100000, dim=768, bits=3)
+print(est)  # Original: X MB -> Compressed: Y MB (7.60×, save 87%)
+```
+
+**CompressedVectors** objects carry metadata:
+
+```python
+compressed.n_vectors   # original count
+compressed.dim         # original dimension
+compressed.nbytes      # compressed size in bytes
+compressed.memory      # MemoryBytes(original, compressed, ratio)
+compressed.data        # raw .tq bytes (save to disk)
+```
+
+---
+
+## 🤖 MCP Server (AI Agents)
+
+TurboQuant Tools ships with a native **MCP server** for AI agent integration — works with any MCP-compatible host (Hermes, Claude Desktop, etc.).
+
+### Start
+
+```bash
+turboquant mcp-server
+```
+
+### Register in your MCP client
+
+**Hermes Agent** (`~/.hermes/config.yaml`):
+
+```yaml
+mcp_servers:
+  turboquant-tools:
+    command: turboquant
+    args: ["mcp-server"]
+    enabled: true
+```
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "turboquant-tools": {
+      "command": "turboquant",
+      "args": ["mcp-server"]
+    }
+  }
+}
+```
+
+### Available Tools
+
+| Tool | Description |
+|---|---|
+| `compress_embeddings` | Compress vectors in-memory |
+| `decompress_embeddings` | Restore compressed vectors |
+| `estimate_savings_mcp` | Predict compression ratio |
+| `embed_and_compress` | Embed texts via API + compress in one step |
+
+---
+
+## 📊 Performance
+
+Measured on random float32 embeddings (CPU, no GPU needed):
+
+| Vectors | Dim | Mode | Original | Compressed | Ratio | MAE |
+|---|---|---|---|---|---|---|
+| 20 | 384 | PolarQuant 3-bit | 30 KB | 10 KB | **3.0×** | 2.6 |
+| 20 | 384 | TurboQuant (QJL) | 30 KB | 20 KB | 1.5× | 3.3 |
+| 100K | 384 | PolarQuant 3-bit | 153 MB | 20 MB | **7.6×** | — |
+
+**Use cases:**
+- **RAG pipelines** — compress vector DB indexes
+- **Edge devices** — fit embeddings in limited RAM
+- **Storage savings** — reduce cloud costs for large vector stores
+- **Memory-bound agents** — compress context vectors on the fly
+
+---
+
+## 🧪 Development
+
+```bash
+git clone https://github.com/FreezeVII/turboquant-tools.git
+cd turboquant-tools
+pip install -e .
+pip install pytest
+pytest tests/
+```
+
+### Run tests
+
+```bash
+pytest tests/ -v
+```
+
+---
+
+## 🧱 How It Works
+
+Two-stage compression inspired by [Google's TurboQuant](https://research.google/blog/turboquant-redefining-ai-efficiency-with-extreme-compression/):
+
+1. **PolarQuant** — Random Hadamard rotation + scalar quantization to 3–4 bits per dimension. Captures magnitude and direction.
+2. **QJL** (optional) — Quantized Johnson-Lindenstrauss residual correction. Recovers high-frequency detail lost in PolarQuant.
+
+Both stages run **CPU-only** via PyTorch — no GPU required. The `.tq` binary format uses a 30-byte header with magic bytes (`TQT2`) + packed indices and norms.
+
+Under the hood this wraps [OnlyTerp/turboquant](https://github.com/OnlyTerp/turboquant), a reference PyTorch implementation.
+
+---
+
+## 📄 License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+## 🙌 Contributing
+
+PRs welcome! Ideas:
+- FAISS index compression (`compress_faiss`)
+- Onnx / numpy-only backend (no PyTorch dep)
+- Streaming compression for billion-scale datasets
+- Pre-built wheels for faster install
+
+---
+
+<p align="center">Made with 🧊 for the vector search community.</p>

turboquant_tools-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "turboquant-tools"
+version = "0.1.0"
+description = "CLI + MCP Server + Python Library for TurboQuant-based embedding compression"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [{name = "FreezeVII"}]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "numpy>=1.24",
+    "click>=8.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/FreezeVII/turboquant-tools"
+Source = "https://github.com/FreezeVII/turboquant-tools"
+
+[project.scripts]
+turboquant = "turboquant_tools.cli:main"
+
+[project.optional-dependencies]
+mcp = ["fastmcp>=0.1"]
+dev = ["pytest>=7", "pytest-cov"]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+testpaths = ["tests"]

turboquant_tools-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

turboquant_tools-0.1.0/src/turboquant_tools/__init__.py

@@ -0,0 +1,8 @@
+"""
+turboquant_tools — CLI + MCP Server + Library for TurboQuant embedding compression.
+"""
+
+from .core import compress, decompress, estimate_savings
+from .core import CompressedVectors, MemoryBytes
+
+__version__ = "0.1.0"

turboquant_tools-0.1.0/src/turboquant_tools/cli.py

@@ -0,0 +1,100 @@
+"""
+CLI for turboquant-tools.
+"""
+from __future__ import annotations
+import sys
+from pathlib import Path
+import click
+import numpy as np
+from turboquant_tools import compress, decompress, estimate_savings
+
+
+@click.group()
+def main():
+    """TurboQuant Tools - compress AI embeddings with 5x memory reduction."""
+    pass
+
+
+@main.command()
+@click.argument("input", type=click.Path(exists=True, dir_okay=False))
+@click.argument("output", type=click.Path(dir_okay=False), required=False)
+@click.option("--bits", "-b", default=3, type=int, help="Target bit width (default: 3)")
+@click.option("--output", "-o", default=None, help="Output .tq file path (alternative to positional OUTPUT)")
+@click.option("--no-qjl", is_flag=True, default=False, help="Skip QJL correction (faster but lower quality)")
+def compress_cmd(input, output, bits, no_qjl):
+    """Compress .npy embedding vectors to .tq format.
+
+    INPUT is a .npy file with float32 embeddings (n_vectors x dimensions).
+    OUTPUT is the destination .tq file. If omitted, auto-names based on input.
+    """
+    vectors = np.load(input)
+    if vectors.ndim != 2:
+        click.echo(f"Error: expected 2D array, got {vectors.ndim}D", err=True)
+        sys.exit(1)
+    n, d = vectors.shape
+    click.echo(f"Vectors: {n} x {d} ({vectors.nbytes / 1e6:.2f} MB)", err=True)
+    compressed = compress(vectors, bits=bits, use_qjl=not no_qjl)
+    out_path = output or click.get_current_context().params.get("output")
+    if out_path is None:
+        out_path = f"{Path(input).stem}_tq{bits}.tq"
+    with open(out_path, "wb") as f:
+        f.write(compressed.data)
+    click.echo(f"Compressed: {compressed.nbytes / 1e6:.2f} MB ({compressed.memory.ratio:.1f}x)")
+    click.echo(f"Saved to: {out_path}")
+
+
+@main.command()
+@click.argument("input", type=click.Path(exists=True, dir_okay=False))
+@click.argument("output", type=click.Path(dir_okay=False), required=False)
+@click.option("--output", "-o", default=None, help="Output .npy file path (alternative to positional OUTPUT)")
+def decompress_cmd(input, output):
+    """Restore compressed .tq file to .npy.
+
+    INPUT is a .tq compressed file.
+    OUTPUT is the destination .npy file. If omitted, auto-names based on input.
+    """
+    from turboquant_tools.core import CompressedVectors
+    with open(input, "rb") as f:
+        data = f.read()
+    import struct
+    magic = struct.unpack_from("<4s", data, 0)[0]
+    if magic != b"TQT2":
+        click.echo(f"Error: not a valid .tq file", err=True)
+        sys.exit(1)
+    compressed = CompressedVectors(data=data, shape=(0, 0), bits=0)
+    restored = decompress(compressed)
+    out_path = output or click.get_current_context().params.get("output")
+    if out_path is None:
+        out_path = f"{Path(input).stem}_restored.npy"
+    np.save(out_path, restored)
+    click.echo(f"Restored: {restored.shape} ({restored.nbytes / 1e6:.2f} MB)")
+    click.echo(f"Saved to: {out_path}")
+
+
+@main.command()
+@click.argument("input", type=click.Path(exists=True, dir_okay=False))
+@click.option("--bits", "-b", default=3, type=int, help="Target bit width (default: 3)")
+def estimate_cmd(input, bits):
+    """Estimate compression savings without running the algorithm."""
+    arr = np.load(input, mmap_mode='r')
+    if arr.ndim != 2:
+        click.echo(f"Error: expected 2D array", err=True)
+        sys.exit(1)
+    n, d = arr.shape
+    del arr
+    click.echo(str(estimate_savings(n, d, bits=bits)))
+
+
+@main.command()
+def mcp_server():
+    """Start the MCP protocol server (stdio transport for Hermes AI agents)."""
+    try:
+        from turboquant_tools.mcp_server import run_server
+        run_server()
+    except ImportError:
+        click.echo("MCP server requires: pip install turboquant-tools[mcp]", err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()