Metadata-Version: 2.4
Name: weavscope
Version: 0.1.0
Summary: A clean, multi-tenant Weaviate wrapper for isolated data management.
Project-URL: Homepage, https://github.com/mmycin/weavscope
Project-URL: Repository, https://github.com/mmycin/weavscope
Project-URL: Issues, https://github.com/mmycin/weavscope/issues
Author-email: "Tahcin Ul Karim (Mycin)" <mycin.mit@gmail.com>
License: MIT
License-File: LICENSE
Keywords: multi-tenancy,search,vector-database,weaviate
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: weaviate-client[agents]>=4.20.4
Provides-Extra: test
Requires-Dist: pytest>=9.0.2; extra == 'test'
Description-Content-Type: text/markdown

# WeavScope 🔭

![WeavScope Banner](assets/banner.jpg)


A clean, multi-tenant wrapper for Weaviate.

WeavScope simplifies working with isolated data in Weaviate by providing a context-managed "Scope" that automatically handles connection, tenant creation, and cleanup based on your configuration.

## Features

- **Config-Driven Lifecycle**: Pass a `WeaviateConfig` object; the wrapper handles the connection.
- **Auto-Tenant Management**: Automatically create a tenant on entry and **DELETES it on exit**.
- **Fluent API**: Simplified batch ingestion and querying (`scope.batch` / `scope.query`).
- **Idempotent Inserts**: Automatic deterministic UUID generation based on `(object_id, tenant_id)`.

## Installation

```bash
pip install weavscope
```

## Quick Start

```python
from weavscope import WeavScope, WeaviateConfig

# 1. Define your connection and class settings
config = WeaviateConfig(
    WEAVIATE_HOST="localhost",  # Your Weaviate host
    WEAVIATE_PORT=8080,
    WEAVIATE_CLASS_NAME="Articles",
    WEAVIATE_EMBEDDING_MODEL_PROVIDER="gemini",
    WEAVIATE_EMBEDDING_MODEL_NAME="gemini-embedding-001",
    WEAVIATE_EMBEDDING_MODEL_API_KEY="[ENCRYPTION_KEY]"
)

# 2. Use WeavScope to isolate operations to a specific tenant
# The tenant 'project-A' is created on entry and DELETED on exit.
with WeavScope(config, tenant_id="project-A") as scope:
    # Batch-insert objects
    scope.batch.add_objects(
        objects=[
            {"title": "Intro to AI", "content": "AI is changing the world..."},
            {"title": "Vector DBs", "content": "Vector databases are cool."}
        ],
        id_field="title"  # Ensures deterministic UUIDs
    )
    
    # Semantic search within the tenant
    results = scope.query.hybrid("machine learning")
    
    for hit in results:
        print(f"Found: {hit['properties']['title']} (score: {hit['score']})")

# Connection is closed and tenant 'project-A' (with all its data) is deleted.
```

## Manual Management

If you don't want the automatic deletion behavior, simply omit the `tenant_id` from the constructor:

```python
with WeavScope(config) as scope:
    # Manually ensure a tenant exists
    scope.ensure_tenant("permanent-tenant")

    # The collection is created automatically if it didn't exist
    scope.batch.add_objects(
        tenant_id="permanent-tenant",
        objects=[...]
    )
```

## AI/LLM Documentation

For AI coding assistants and LLMs looking for an in-depth technical overview of WeavScope's architecture and API, please refer to [LLM.txt](LLM.txt).

## License

MIT - Copyright (c) 2026 Tahcin Ul Karim (Mycin)
