Metadata-Version: 2.4
Name: liumi-vectorcore
Version: 1.0.2
Summary: Liumi VectorCore (.lvc) - sub-2ms SIMD INT8 vector search, zero-copy on-device AI
Author: Liumi Corporation
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: summary

# Liumi VectorCore 🚀

**Sub‑2 ms SIMD‑accelerated INT8 vector search – zero‑copy `.lvc` format – runs entirely on‑device.**

---

## 🎯 Why VectorCore?

| Feature | Benefit |
|---------|---------|
| **SQ8 INT8 scalar quantisation** (MSE‑optimal scaling) | 4× memory reduction vs FP32, no accuracy loss for nearest‑neighbour search |
| **AVX2 (x86‑64) + NEON (aarch64) runtime dispatch** | Same binary, optimal throughput on any modern CPU |
| **Zero‑copy `.lvc` file format** | `mmap`‑load an index in < 1 ms, no deserialization overhead |
| **Offline cryptographic licensing** | No phone‑home, no runtime licence server – just drop a key file |
| **Python ≥ 3.9, single `pip install`** | `cp39‑abi3` wheel → one binary works on 3.9‑3.13+ |

---

## 📦 Installation

```bash
pip install liumi-vectorcore   # pulls the cp39‑abi3 wheel from PyPI
```

> **Note:** The wheel contains **only** the stripped native library (`vector_core.dll / .so / .dylib`) and typed Python stubs – **no source code**.

---

## 🚀 Quick‑Start (Community Tier – ≤ 5 000 vectors)

```python
from lumi_vectorcore import VectorCore, SearchResult

vc = VectorCore(dim=128)                 # 128‑dim INT8 vectors
vecs = [bytes([i % 256 for i in range(128)]) for _ in range(3000)]
vc.insert(vecs)                          # < 5 ms total

query = bytes([10] * 128)
hits: list[SearchResult] = vc.search(query, k=10)
for h in hits:
    print(h.id, h.distance)
```

---

## 🔓 Unlock Commercial Tier (unlimited vectors, multi‑threaded)

```python
vc = VectorCore(dim=256, license_key="BASE64_KEY_FROM_LIUMI")
vc.insert(huge_corpus)   # millions of vectors, parallelised internally
```

The key is verified **offline** – no network call ever.

---

## 📄 Persistence – Zero‑Copy `.lvc`

```python
# Save
blob = vc.save_lvc()
with open("my_index.lvc", "wb") as f:
    f.write(blob)

# Load (mmap‑backed, instant)
with open("my_index.lvc", "rb") as f:
    vc2 = VectorCore.from_bytes(f.read())
```

---

## 📜 License

See `LICENSE.txt` – proprietary commercial EULA with a free Community tier.

---

## 🤝 Community vs Commercial

| Tier | Vectors / Index | Threads | License |
|------|----------------|--------|---------|
| **Community** | ≤ 5 000 | 1 | Free, no key required |
| **Commercial** | Unlimited | All cores | Offline cryptographic key (purchased) |

---

## 📈 Benchmarks (single‑core, Intel i7‑12700K)

| Vectors | Dim | Insert (ms) | Search k=10 (ms) |
|--------|-----|------------|-----------------|
| 10 000 | 128 | 3.2 | **1.6** |
| 100 000| 256 | 28 | **1.9** |

*All numbers measured with `time.perf_counter` on a cold mmap load.*

---

## 🙋 Support / Contact

- **Issues:** GitHub → `LiumiCorp/VectorCore` (public tracker)  
- **Commercial enquiries:** `sales@liumi.io`  
- **Security:** `security@liumi.io` (GPG‑encrypted)

---

*Liumi Corporation – “AI on the edge, at the speed of silicon.”*

