Metadata-Version: 2.5
Name: massengine
Version: 1.1.3
Summary: Official Python SDK for the MassEngine vector and hybrid search database.
Project-URL: Homepage, https://massengine.com
Project-URL: Documentation, https://massengine.com/docs
Project-URL: Repository, https://github.com/massengine-dev/massengine-python
Author-email: MassEngine <dev@massengine.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: bm25,embeddings,hybrid-search,massengine,rag,vector-database
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# MassEngine Python SDK (`massengine`)

Official zero-dependency Python client for [MassEngine](https://massengine.com) — the sub-5ms filtered and hybrid vector search database.

## Installation

```bash
pip install massengine
```

## Quickstart

```python
from massengine import MassEngineClient, Doc

# Connect to a local quickstart cluster (http://localhost:8080) or cloud gateway:
client = MassEngineClient(
    base_url="http://localhost:8080",
    api_key="mk_your_tenant_or_meadm_admin_key",
)

# 1. Ingest vectors + structured metadata
client.ingest(
    "acme-prod",
    [
        Doc(
            id="doc-1",
            vector=[0.12, -0.44, 0.88, 0.05],
            category=1,
            metadata={"department": "security", "clearance": 3, "tags": ["soc2", "policy"]},
        )
    ],
)

# 2. Hybrid dense + BM25 search with rich metadata filter operators
res = client.search(
    "acme-prod",
    vector=[0.12, -0.44, 0.88, 0.05],
    query_text="soc2 policy",
    hybrid_alpha=0.7,
    k=10,
    min_score=0.5,
    metadata_filter={
        "department": {"$in": ["security", "legal"]},
        "clearance": {"$gte": 2},
        "tags": {"$contains": "soc2"},
    },
)
print(res["hits"])

# 3. In-place metadata patching without re-embedding
client.patch_doc(
    "acme-prod",
    "doc-1",
    metadata={"clearance": 4, "reviewed": True},
)

# 4. Inspect tenant quota & billable usage
usage = client.get_tenant_usage("acme-prod")
print(usage)
```

## License

Apache License 2.0
