genkitx-weaviate is a community plugin for using Weaviate vector database with Genkit. Built by Xavier Portilla Edo.

Table of Contents

• Table of Contents
• Installation
• Configuration
  • Configuration Options
• Usage
  • Indexer
    • Basic Examples
    • Within a Flow
  • Retriever
    • Basic Examples
    • Within a Flow
• Examples
• Features
• API Reference
  • Main Exports
• Contributing
• Need Support?
• Credits
• License

Installation

Install the plugin in your project with your favorite package manager:

npm install genkitx-weaviate

or

pnpm add genkitx-weaviate

Configuration

To use the plugin, you need to configure it with your Weaviate instance details:

import { genkit } from 'genkit';
import { weaviate } from 'genkitx-weaviate';
import { textEmbedding004 } from '@genkit-ai/vertexai';

const ai = genkit({
  plugins: [
    weaviate({
      clientParams: {
        host: 'localhost', // or 'your-cluster.weaviate.network' for Weaviate Cloud
        port: 8080, // optional, defaults to 8080 for local, 443 for cloud
        grpcPort: 50051, // optional, defaults to 50051 for local
        apiKey: process.env.WEAVIATE_API_KEY, // optional, for Weaviate Cloud
      },
      collections: [
        {
          collectionName: 'Documents',
          embedder: textEmbedding004,
        },
      ],
    }),
  ],
});

Configuration Options

• clientParams: Configuration for the Weaviate client

  • host: Hostname of your Weaviate instance (without protocol) - e.g., 'localhost' or 'my-cluster.weaviate.network'
  • port: Optional HTTP port (default: 8080 for local, 443 for cloud)
  • grpcPort: Optional gRPC port (default: 50051 for local)
  • secure: Optional boolean for secure connection (default: false for local, true for cloud)
  • apiKey: Optional API key for authentication (required for Weaviate Cloud)
  • headers: Optional custom headers
  • timeout: Optional timeout in milliseconds (default: 30000)

• collections: Array of collection configurations

  • collectionName: Name of the Weaviate collection
  • embedder: Optional embedder to use for this collection
  • embedderOptions: Optional embedder configuration
  • createCollectionIfMissing: Whether to create the collection if it doesn't exist (default: true)
  • collectionConfig: Optional collection configuration

Usage

The plugin provides two main functionalities: index and retrieve. You can use them directly or within a Genkit flow.

Indexer

The indexer stores documents and their embeddings in a Weaviate collection.

Basic Examples

import { weaviateIndexerRef } from 'genkitx-weaviate';

const indexer = weaviateIndexerRef({
  collectionName: 'Documents',
});

const documents = [
  { 
    text: 'Weaviate is a vector database',
    metadata: { source: 'docs' }
  },
  { 
    text: 'Genkit is an AI framework',
    metadata: { source: 'docs' }
  },
];

await ai.index({ indexer, documents });

Within a Flow

export const indexerFlow = ai.defineFlow(
  {
    name: 'indexerFlow',
    inputSchema: z.array(z.object({
      text: z.string(),
      metadata: z.record(z.any()).optional(),
    })),
    outputSchema: z.string(),
  },
  async (documents) => {
    const indexer = weaviateIndexerRef({
      collectionName: 'Documents',
    });

    await ai.index({ indexer, documents });
    return 'Documents indexed successfully';
  }
);

Retriever

The retriever searches for similar documents in a Weaviate collection based on vector similarity.

Basic Examples

import { weaviateRetrieverRef } from 'genkitx-weaviate';

const retriever = weaviateRetrieverRef({
  collectionName: 'Documents',
});

const results = await ai.retrieve({ 
  retriever, 
  query: 'What is a vector database?',
  options: {
    k: 5, // Number of results to return
    distance: 0.7, // Optional distance threshold
  }
});

Within a Flow

export const retrieverFlow = ai.defineFlow(
  {
    name: 'retrieverFlow',
    inputSchema: z.string(),
    outputSchema: z.string(),
  },
  async (query) => {
    const retriever = weaviateRetrieverRef({
      collectionName: 'Documents',
    });

    const docs = await ai.retrieve({ 
      retriever, 
      query,
      options: { k: 5 }
    });

    const llmResponse = await ai.generate({
      prompt: `Answer the question based on the following context:\n\nContext: ${docs.map(d => d.text).join('\n\n')}\n\nQuestion: ${query}`,
    });

    return llmResponse.text;
  }
);

Examples

You can find more examples in the examples folder.

Features

• Easy Integration: Simple setup with Genkit
• Multiple Collections: Support for multiple Weaviate collections
• Flexible Configuration: Customizable collection settings
• Type Safety: Full TypeScript support
• Latest Weaviate Client: Uses weaviate-client v3.10.0
• Auto-Collection Creation: Automatically creates collections if they don't exist
• Metadata Support: Store and retrieve document metadata
• Distance Filtering: Filter results by similarity distance
• Batch Operations: Efficient batch insertion and retrieval

API Reference

For detailed API documentation, please refer to the TypeScript definitions in the source code.

Main Exports

• weaviate(params): Main plugin function
• weaviateIndexerRef(params): Create an indexer reference
• weaviateRetrieverRef(params): Create a retriever reference
• WeaviateClientWrapper: Client wrapper class
• Types: WeaviatePluginParams, WeaviateClientParams, CollectionConfig

Contributing

Want to contribute to the project? That's awesome! Head over to our Contribution Guidelines.

Need Support?

[!NOTE]
This repository depends on Google's Genkit. For issues and questions related to Genkit, please refer to instructions available in Genkit's repository.

Reach out by opening a discussion on GitHub Discussions.

Credits

This plugin is proudly maintained by Xavier Portilla Edo.

License

This project is licensed under the Apache 2.0 License.