Metadata-Version: 2.4
Name: aioniq-trace
Version: 0.1.1
Summary: TRACE — local-first binary vector search SDK (wraps the trace_core engine)
Author: TRACE
License: Apache-2.0
Project-URL: Homepage, https://github.com/CalBearKen/TRACE
Project-URL: Repository, https://github.com/CalBearKen/TRACE
Project-URL: Documentation, https://github.com/CalBearKen/TRACE/tree/main/docs/sdk/guide
Project-URL: Issues, https://github.com/CalBearKen/TRACE/issues
Keywords: vector-search,embeddings,binary-quantization,hamming,semantic-search,local-first,mcp,rag,memory
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Intended Audience :: Developers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26.0
Requires-Dist: pydantic>=2.0
Requires-Dist: typer>=0.12
Provides-Extra: text
Requires-Dist: sentence-transformers>=3.0.0; extra == "text"
Requires-Dist: torch>=2.4.0; extra == "text"
Provides-Extra: visual
Requires-Dist: transformers>=4.48.0; extra == "visual"
Requires-Dist: torch>=2.4.0; extra == "visual"
Requires-Dist: Pillow>=10.4.0; extra == "visual"
Provides-Extra: all
Requires-Dist: aioniq-trace[text,visual]; extra == "all"
Requires-Dist: hnswlib>=0.8.0; extra == "all"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: auth
Requires-Dist: requests>=2.32.2; extra == "auth"
Requires-Dist: cryptography>=44.0.1; extra == "auth"
Requires-Dist: PyJWT>=2.8.0; extra == "auth"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: cython>=3.0.0; extra == "dev"
Requires-Dist: numpy>=1.26.0; extra == "dev"
Requires-Dist: cibuildwheel; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: wheel>=0.42; extra == "dev"
Requires-Dist: requests>=2.32.2; extra == "dev"
Requires-Dist: cryptography>=44.0.1; extra == "dev"
Requires-Dist: bandit>=1.7; extra == "dev"
Requires-Dist: pip-audit>=2.7; extra == "dev"
Requires-Dist: cyclonedx-bom>=4.0; extra == "dev"
Dynamic: license-file

# aioniq-trace

**Local-first binary vector search.** TRACE compresses dense embeddings into compact binary
signatures (~32× smaller) and searches them with vectorized XOR + popcount Hamming distance on
the CPU — linear, streaming-append, no GPU, no network. Your data never leaves the machine.

> Install as `aioniq-trace`, import as `vector_trace`.

## Install

```bash
pip install aioniq-trace                 # core
pip install "aioniq-trace[text]"         # + sentence-transformers text embeddings
pip install "aioniq-trace[visual]"       # + CLIP image / text embeddings
pip install "aioniq-trace[mcp]"          # + Model Context Protocol server for agents
```

## Quickstart

```python
import time, vector_trace

with vector_trace.TraceIndex("~/my_index", families=["text_dated"]) as idx:
    idx.ingest("Met Dana at the harbor.", family="text_dated", timestamp=time.time())
    for r in idx.search("foggy day by the water", family="text_dated"):
        print(r.rank, round(r.confidence, 3), r.preview)
```

From the CLI:

```bash
trace index create -d ~/.trace/idx -f text_dated
trace index ingest "the harbor was foggy" -F text_dated -d ~/.trace/idx
trace index search "misty docks"          -F text_dated -d ~/.trace/idx
trace mcp        # run the MCP server (stdio) for AI agents
```

## Features

- **Compact & fast** — sign-bit quantization (~32× smaller) + vectorized Hamming search on CPU.
- **Local-first** — on-disk indexes; no cloud, no telemetry.
- **Multiple families** — text, visual (CLIP), and persona embeddings, plus bring-your-own vectors.
- **Cross-modal timeline** — one time axis across families; `recall_at_time()` for "what was happening around then".
- **Agent-ready** — Python API, a `trace` CLI, and an MCP server exposing 7 tools.

## Documentation

Guides — getting started, concepts, Python API, CLI, MCP, configuration — are in the
repository: https://github.com/CalBearKen/TRACE

## License

Apache-2.0 — see [LICENSE](LICENSE). A separately-licensed commercial edition adds a
hardware-accelerated engine.

Copyright © 2026 Aioniq.
