Weaviate

Build vector search with Weaviate using v4 syntax, proper module configuration, and production-ready patterns.

Security Scan

The skill's documentation and instructions match a Weaviate v4 best-practices guide, but the runtime instructions reference provider API keys (OpenAI, Cohere) and environment access that the skill's metadata does not declare — an inconsistency you should resolve before trusting credentials to this skill.

Purpose & Capability

The name/description (Weaviate v4 guidance) aligns with the content: schema/collection design, modules, batch operations, hybrid search, and HNSW tuning. The instructions cover expected topics for building production vector search with Weaviate.

Instruction Scope

SKILL.md instructs runtime use of provider API keys in client headers (e.g., headers={"X-OpenAI-Api-Key": os.environ["OPENAI_API_KEY"]}, X-Cohere-Api-Key). Those environment accesses are not declared in requires.env. The instructions also tell users how to enable modules and how to pass keys to the client, which is expected for this skill, but the skill text directly references reading environment variables the registry metadata does not list — per the evaluator rules this is scope inconsistency. There is no direct instruction to read arbitrary files, but the env-var usage grants access to secrets when the agent executes code.

Install Mechanism

This is an instruction-only skill with no install spec or code files. That minimizes disk-write and external-install risk; nothing is downloaded or executed by the skill itself.

Credentials

The skill's docs require API keys for OpenAI and Cohere (and suggest headers for them) yet the registry lists no required env vars or primary credential. Asking for provider API keys is proportionate to the stated purpose, but failing to declare these credentials is a misalignment and a security/operational concern. The skill also suggests using high-privilege models (e.g., gpt-4) and enabling API-based modules; users should be cautioned to use scoped keys and quotas.

Persistence & Privilege

always:false and no install hooks; the skill does not request persistent system presence. Autonomous invocation is allowed (platform default) but not combined with other high-privilege indicators here.

What to consider before installing

This skill is a v4 Weaviate usage guide and is otherwise coherent, but it references provider API keys (OPENAI_API_KEY, X-Cohere-Api-Key) and shows examples that read os.environ — yet the registry metadata lists no required env vars. Before installing or running: 1) Treat this as documentation you will run locally, not a black-box plugin that needs your keys. 2) Do not paste full/high-privilege provider keys into the agent chat; instead create scoped API keys with limited quotas for testing. 3) Verify any code you run that calls weaviate.connect_to_*() will only receive the specific env vars you intend to share. 4) If you want the skill to manage keys, ask the publisher to update the metadata to declare required env vars (e.g., OPENAI_API_KEY, COHERE_API_KEY) so the platform can surface permissions. 5) If you prefer to avoid external providers, use the local transformer module option shown (text2vec-transformers) to keep embedding generation on-premises. If you need higher assurance, request the publisher to provide an explicit list of required credentials and a minimal example that uses least-privilege keys; until then, treat the missing env-var declarations as a red flag.

Critical: v4 Only (Dec 2024+)

v3 syntax is DEPRECATED. Before generating ANY Weaviate code:

1. Verify client version — must be weaviate-client>=4.0
2. Use context managers — with weaviate.connect_to_*() as client: or explicit client.close()
3. New imports — from weaviate.classes.config import Configure, Property

If you see v3 patterns (weaviate.Client(), client.schema.create_class(), path=[...] filters), stop and rewrite.

Quick Reference

Topic	File
v3→v4 migration table	v4-syntax.md
Module configuration	modules.md
Batch, hybrid, HNSW	operations.md

v4 Syntax Essentials

# Connection (ALWAYS close)
with weaviate.connect_to_local() as client:
    # Collections (not classes)
    collection = client.collections.get("Article")
    
    # Queries
    response = collection.query.hybrid("search term", alpha=0.7)
    
    # Vector access
    vector = obj.vector["default"]  # Dict, not List
    
    # Filters
    Filter.by_property("category").equal("tech")

Scope

This skill covers:

• Schema design for RAG and semantic search
• Vectorizer and reranker module configuration
• Batch imports with error handling
• Hybrid search tuning (alpha parameter)
• HNSW index configuration for scale

Core Rules

1. Always Verify Modules

Before using text2vec-openai, generative-openai, or rerankers, verify they're enabled:

# docker-compose.yml
ENABLE_MODULES: 'text2vec-openai,generative-openai,reranker-cohere'

2. API Keys in Headers

client = weaviate.connect_to_local(
    headers={"X-OpenAI-Api-Key": os.environ["OPENAI_API_KEY"]}
)

3. Batch with Context Manager

with client.batch.dynamic() as batch:
    for item in data:
        batch.add_object(properties=item, collection="Name")

4. Hybrid Search Alpha

• alpha=0 → BM25 only (keyword)
• alpha=1 → Vector only (semantic)
• alpha=0.5-0.75 → Balanced (typical for RAG)

5. Apply Filters BEFORE Vector Search

Filters in where reduce the search space first — always filter before near_text/near_vector.

6. Named Vectors vs Single Vector

Choose one pattern per collection:

# Single vector (simpler)
vectorizer_config=Configure.Vectorizer.text2vec_openai()

# Named vectors (multiple embeddings per object)
vector_config=[
    Configure.Vectors.text2vec_openai(name="content", source_properties=["body"]),
]

7. Debug Empty Results

Check in order: schema exists → vectorizer ran → distance threshold → filter syntax. Use _additional { vector } to verify vectors were generated.