Metadata-Version: 2.1
Name: violas
Version: 0.0.1
Summary: Core grouped vector retrieval primitives from the SemanticVG project.
Home-page: https://github.com/DoubleNorth/SemanticVG
Author: SemanticVG Authors
License: UNKNOWN
Project-URL: Documentation, https://github.com/DoubleNorth/SemanticVG#readme
Project-URL: Issues, https://github.com/DoubleNorth/SemanticVG/issues
Keywords: vector-database,vector-search,retrieval,semantic-search
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: tqdm
Provides-Extra: faiss
Requires-Dist: faiss-cpu ; extra == 'faiss'

# Violas

Violas is a lightweight Python package for grouped vector retrieval.

It exposes the core storage and retrieval primitives from the SemanticVG
project without bundling the benchmark pipelines, datasets, or experiment
artifacts. The package is meant to be a small installable surface for:

- semantic-keyed vector groups
- representative-based retrieval
- relation-aware expansion
- HDMG-backed mixed semantic-vector search

## Install

```bash
pip install violas
```

Optional FAISS-backed acceleration:

```bash
pip install "violas[faiss]"
```

## Quick Start

```python
import numpy as np

from violas import VectorGroup, VectorMap

vectors = [np.random.rand(4) for _ in range(5)]
group = VectorGroup(
    group_name="demo",
    representative=np.mean(vectors, axis=0),
    rep_description="demo representative",
    vectors=vectors,
    descriptions=[{"text": f"item {i}"} for i in range(5)],
)

vm = VectorMap()
vm.insert("example", group)

query = np.random.rand(4)
results = vm.search(query, top_k=3)
for result in results:
    print(result)
```

## Public API

- `VectorGroup`: grouped retrieval unit with representative and member vectors
- `VectorMap`: semantic-keyed storage, indexing, and search entry point
- `VectorRef` and `VectorRelation`: relation primitives for contextual expansion
- `create_context_chain()` and relation helpers for linked retrieval workflows

The full research repository, documentation, and benchmark results live at:
https://github.com/DoubleNorth/SemanticVG


