Weaviate Adapter

The [weaviate] extra provides WeaviateRetriever, a hybrid-search retriever backed by a Weaviate instance.

pip install "schematize[weaviate]"

Environment variables

Variable	Default	Description
`WV_URL`	`localhost`	Weaviate host
`WV_PORT`	`8080`	Weaviate HTTP port
`WV_GRPC_PORT`	`50051`	Weaviate gRPC port
`WV_API_KEY`	(empty)	Weaviate API key

Set these in your .env file or shell. The retriever reads them at instantiation time; you can also pass them explicitly (see below).

Basic usage

from schematize.retrieval.weaviate import WeaviateRetriever

retriever = WeaviateRetriever(collection_name="LegalDocuments")

This connects using the environment variables above and runs hybrid search against the LegalDocuments collection.

Named vector

If your collection uses named vectors, specify which one to search:

retriever = WeaviateRetriever(
    collection_name="LegalDocuments",
    target_vector="text_embedding",
)

Property filters

Narrow results by property equality before the vector search:

retriever = WeaviateRetriever(
    collection_name="LegalDocuments",
    filters={"language": "pl", "document_type": "judgment"},
)

Multiple filters are combined with AND.

Explicit connection parameters

Override environment variables at construction time:

retriever = WeaviateRetriever(
    collection_name="LegalDocuments",
    host="weaviate.internal",
    port=8080,
    grpc_port=50051,
    api_key="my-key",
)

Return format

Each document is returned as a dict of collection properties plus a _score key from Weaviate's hybrid search metadata:

{
    "text": "...",
    "title": "...",
    "_score": 0.87,
}

API reference

WeaviateRetriever

WeaviateRetriever(
    collection_name: str,
    target_vector: Optional[str] = None,
    filters: Optional[dict[str, str]] = None,
    host: Optional[str] = None,
    port: Optional[int] = None,
    grpc_port: Optional[int] = None,
    api_key: Optional[str] = None,
)

DocumentRetriever backed by a Weaviate hybrid-search index.

Works with any Weaviate collection. Connection parameters are read from environment variables by default but can be overridden.

Parameters:

Name	Type	Description	Default
`collection_name`	`str`	Weaviate collection to query.	required
`target_vector`	`Optional[str]`	Named vector to use for hybrid search. `None` uses the collection default.	`None`
`filters`	`Optional[dict[str, str]]`	Property-equality filters applied to every query, e.g. `{"language": "pl", "document_type": "judgment"}`.	`None`
`host`	`Optional[str]`	Weaviate host (default: `WV_URL` env var or `"localhost"`).	`None`
`port`	`Optional[int]`	Weaviate HTTP port (default: `WV_PORT` env var or `8080`).	`None`
`grpc_port`	`Optional[int]`	Weaviate gRPC port (default: `WV_GRPC_PORT` env var or `50051`).	`None`
`api_key`	`Optional[str]`	Weaviate API key (default: `WV_API_KEY` env var).	`None`