feat: Elasticsearch integration for VectorIO

.github/workflows/integration-vector-io-tests.yml

@@ -31,7 +31,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        vector-io-provider: ["inline::faiss", "inline::sqlite-vec", "inline::milvus", "remote::chromadb", "remote::pgvector", "remote::weaviate", "remote::qdrant"]
+        vector-io-provider: ["inline::faiss", "inline::sqlite-vec", "inline::milvus", "remote::chromadb", "remote::pgvector", "remote::weaviate", "remote::qdrant", "remote::elasticsearch"]
         python-version: ${{ github.event.schedule == '0 0 * * *' && fromJSON('["3.12", "3.13"]') || fromJSON('["3.12"]') }}
       fail-fast: false # we want to run all tests regardless of failure
 
@@ -146,6 +146,14 @@ jobs:
           docker logs weaviate
           exit 1
 
+      - name: Setup Elasticsearch
+        if: matrix.vector-io-provider == 'remote::elasticsearch'
+        id: setup-elasticsearch
+        run: |
+          curl -fsSL https://elastic.co/start-local | sh -s -- -v 9.2.0 --esonly
+          source elastic-start-local/.env
+          echo "elasticsearch-api-key=$ES_LOCAL_API_KEY" >> "$GITHUB_OUTPUT"
+
       - name: Build Llama Stack
         run: |
           uv run --no-sync llama stack list-deps ci-tests | xargs -L1 uv pip install
@@ -170,6 +178,8 @@ jobs:
           QDRANT_URL: ${{ matrix.vector-io-provider == 'remote::qdrant' && 'http://localhost:6333' || '' }}
           ENABLE_WEAVIATE: ${{ matrix.vector-io-provider == 'remote::weaviate' && 'true' || '' }}
           WEAVIATE_CLUSTER_URL: ${{ matrix.vector-io-provider == 'remote::weaviate' && 'localhost:8080' || '' }}
+          ELASTICSEARCH_URL: ${{ matrix.vector-io-provider == 'remote::elasticsearch' && 'http://localhost:9200' || '' }}
+          ELASTICSEARCH_API_KEY: ${{ matrix.vector-io-provider == 'remote::elasticsearch' && steps.setup-elasticsearch.outputs.elasticsearch-api-key || '' }}
         run: |
           uv run --no-sync \
             pytest -sv --stack-config="files=inline::localfs,inference=inline::sentence-transformers,vector_io=${{ matrix.vector-io-provider }}" \
@@ -196,6 +206,11 @@ jobs:
         run: |
           docker logs qdrant > qdrant.log
 
+      - name: Write Elasticsearch logs to file
+        if: ${{ always() && matrix.vector-io-provider == 'remote::elasticsearch' }}
+        run: |
+          docker logs es-local-dev > elasticsearch.log
+
       - name: Upload all logs to artifacts
         if: ${{ always() }}
         uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0

docs/docs/concepts/apis/api_providers.mdx

@@ -9,7 +9,7 @@ sidebar_position: 2
 
 The goal of Llama Stack is to build an ecosystem where users can easily swap out different implementations for the same API. Examples for these include:
 - LLM inference providers (e.g., Fireworks, Together, AWS Bedrock, Groq, Cerebras, SambaNova, vLLM, etc.),
-- Vector databases (e.g., ChromaDB, Weaviate, Qdrant, Milvus, FAISS, PGVector, etc.),
+- Vector databases (e.g., ChromaDB, Weaviate, Qdrant, Milvus, FAISS, PGVector, Elasticsearch, etc.),
 - Safety providers (e.g., Meta's Llama Guard, AWS Bedrock Guardrails, etc.)
 
 Providers come in two flavors:

docs/docs/index.mdx

@@ -54,7 +54,7 @@ Llama Stack consists of a server (with multiple pluggable API providers) and Cli
 Llama Stack provides adapters for popular providers across all API categories:
 
 - **Inference**: Meta Reference, Ollama, Fireworks, Together, NVIDIA, vLLM, AWS Bedrock, OpenAI, Anthropic, and more
-- **Vector Databases**: FAISS, Chroma, Milvus, Postgres, Weaviate, Qdrant, and others
+- **Vector Databases**: FAISS, Chroma, Milvus, Postgres, Weaviate, Qdrant, Elasticsearch and others
 - **Safety**: Llama Guard, Prompt Guard, Code Scanner, AWS Bedrock
 - **Training & Evaluation**: HuggingFace, TorchTune, NVIDIA NEMO
 

docs/docs/providers/index.mdx

@@ -9,7 +9,7 @@ sidebar_position: 1
 
 The goal of Llama Stack is to build an ecosystem where users can easily swap out different implementations for the same API. Examples for these include:
 - LLM inference providers (e.g., Meta Reference, Ollama, Fireworks, Together, AWS Bedrock, Groq, Cerebras, SambaNova, vLLM, OpenAI, Anthropic, Gemini, WatsonX, etc.),
-- Vector databases (e.g., FAISS, SQLite-Vec, ChromaDB, Weaviate, Qdrant, Milvus, PGVector, etc.),
+- Vector databases (e.g., FAISS, SQLite-Vec, ChromaDB, Weaviate, Qdrant, Milvus, PGVector, Elasticsearch, etc.),
 - Safety providers (e.g., Meta's Llama Guard, Prompt Guard, Code Scanner, AWS Bedrock Guardrails, etc.),
 - Tool Runtime providers (e.g., RAG Runtime, Brave Search, etc.)
 

docs/docs/providers/vector_io/remote_elasticsearch.mdx

@@ -0,0 +1,104 @@
+---
+description: |
+  [Elasticsearch](https://www.elastic.co/) is a vector database provider for Llama Stack.
+  It allows you to store and query vectors directly within an Elasticsearch database.
+  That means you're not limited to storing vectors in memory or in a separate service.
+
+  ## Features
+  Elasticsearch supports:
+  - Store embeddings and their metadata
+  - Vector search
+  - Full-text search
+  - Fuzzy search
+  - Hybrid search
+  - Document storage
+  - Metadata filtering
+  - Inference service
+  - Machine Learning integrations
+
+  ## Usage
+
+  To use Elasticsearch in your Llama Stack project, follow these steps:
+
+  1. Install the necessary dependencies.
+  2. Configure your Llama Stack project to use Elasticsearch.
+  3. Start storing and querying vectors.
+
+  ## Installation
+
+  You can test Elasticsearch locally by running this script in the terminal:
+
+  ```bash
+  curl -fsSL https://elastic.co/start-local | sh
+  ```
+
+  Or you can [start a free trial](https://www.elastic.co/cloud/cloud-trial-overview?utm_campaign=llama-stack-integration) on Elastic Cloud.
+  For more information on how to deploy Elasticsearch, see the [official documentation](https://www.elastic.co/docs/deploy-manage/deploy).
+
+  ## Documentation
+  See [Elasticsearch's documentation](https://www.elastic.co/docs/solutions/search) for more details about Elasticsearch in general.
+sidebar_label: Remote - Elasticsearch
+title: remote::elasticsearch
+---
+
+# remote::elasticsearch
+
+## Description
+
+
+[Elasticsearch](https://www.elastic.co/) is a vector database provider for Llama Stack.
+It allows you to store and query vectors directly within an Elasticsearch database.
+That means you're not limited to storing vectors in memory or in a separate service.
+
+## Features
+Elasticsearch supports:
+- Store embeddings and their metadata
+- Vector search
+- Full-text search
+- Fuzzy search
+- Hybrid search
+- Document storage
+- Metadata filtering
+- Inference service
+- Machine Learning integrations
+
+## Usage
+
+To use Elasticsearch in your Llama Stack project, follow these steps:
+
+1. Install the necessary dependencies.
+2. Configure your Llama Stack project to use Elasticsearch.
+3. Start storing and querying vectors.
+
+## Installation
+
+You can test Elasticsearch locally by running this script in the terminal:
+
+```bash
+curl -fsSL https://elastic.co/start-local | sh
+```
+
+Or you can [start a free trial](https://www.elastic.co/cloud/cloud-trial-overview?utm_campaign=llama-stack-integration) on Elastic Cloud.
+For more information on how to deploy Elasticsearch, see the [official documentation](https://www.elastic.co/docs/deploy-manage/deploy).
+
+## Documentation
+See [Elasticsearch's documentation](https://www.elastic.co/docs/solutions/search) for more details about Elasticsearch in general.
+
+
+## Configuration
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `elasticsearch_api_key` | `str \| None` | No |  | The API key for the Elasticsearch instance |
+| `elasticsearch_url` | `str \| None` | No | localhost:9200 | The URL of the Elasticsearch instance |
+| `persistence` | `KVStoreReference \| None` | No |  | Config for KV store backend (SQLite only for now) |
+
+## Sample Configuration
+
+```yaml
+elasticsearch_url: ${env.ELASTICSEARCH_URL:=localhost:9200}
+elasticsearch_api_key: ${env.ELASTICSEARCH_API_KEY:=}
+persistence:
+  namespace: vector_io::elasticsearch
+  backend: kv_default
+```

docs/sidebars.ts

@@ -160,7 +160,8 @@ const sidebars: SidebarsConfig = {
             'providers/vector_io/remote_milvus',
             'providers/vector_io/remote_pgvector',
             'providers/vector_io/remote_qdrant',
-            'providers/vector_io/remote_weaviate'
+            'providers/vector_io/remote_weaviate',
+            'providers/vector_io/remote_elasticsearch'
           ],
         },
         {

pyproject.toml

@@ -150,6 +150,7 @@ test = [
     "pymilvus>=2.6.1",
     "milvus-lite>=2.5.0",
     "weaviate-client>=4.16.4",
+    "elasticsearch>=8.16.0, <9.0.0"
 ]
 docs = [
     "setuptools",
@@ -332,6 +333,7 @@ exclude = [
     "^src/llama_stack/providers/remote/vector_io/qdrant/",
     "^src/llama_stack/providers/remote/vector_io/sample/",
     "^src/llama_stack/providers/remote/vector_io/weaviate/",
+    "^src/llama_stack/providers/remote/vector_io/elasticsearch/",
     "^src/llama_stack/providers/utils/bedrock/client\\.py$",
     "^src/llama_stack/providers/utils/bedrock/refreshable_boto_session\\.py$",
     "^src/llama_stack/providers/utils/inference/embedding_mixin\\.py$",

src/llama_stack/distributions/ci-tests/build.yaml

@@ -27,6 +27,7 @@ distribution_spec:
     - provider_type: remote::pgvector
     - provider_type: remote::qdrant
     - provider_type: remote::weaviate
+    - provider_type: remote::elasticsearch
     files:
     - provider_type: inline::localfs
     safety:

src/llama_stack/distributions/ci-tests/run-with-postgres-store.yaml

@@ -145,6 +145,14 @@ providers:
       persistence:
         namespace: vector_io::weaviate
         backend: kv_default
+  - provider_id: ${env.ELASTICSEARCH_URL:+elasticsearch}
+    provider_type: remote::elasticsearch
+    config:
+      elasticsearch_url: ${env.ELASTICSEARCH_URL:=localhost:9200}
+      elasticsearch_api_key: ${env.ELASTICSEARCH_API_KEY:=}
+      persistence:
+        namespace: vector_io::elasticsearch
+        backend: kv_default
   files:
   - provider_id: meta-reference-files
     provider_type: inline::localfs

src/llama_stack/distributions/ci-tests/run.yaml

@@ -145,6 +145,14 @@ providers:
       persistence:
         namespace: vector_io::weaviate
         backend: kv_default
+  - provider_id: ${env.ELASTICSEARCH_URL:+elasticsearch}
+    provider_type: remote::elasticsearch
+    config:
+      elasticsearch_url: ${env.ELASTICSEARCH_URL:=localhost:9200}
+      elasticsearch_api_key: ${env.ELASTICSEARCH_API_KEY:=}
+      persistence:
+        namespace: vector_io::elasticsearch
+        backend: kv_default
   files:
   - provider_id: meta-reference-files
     provider_type: inline::localfs

src/llama_stack/distributions/starter-gpu/build.yaml

@@ -28,6 +28,7 @@ distribution_spec:
     - provider_type: remote::pgvector
     - provider_type: remote::qdrant
     - provider_type: remote::weaviate
+    - provider_type: remote::elasticsearch
     files:
     - provider_type: inline::localfs
     safety:

src/llama_stack/distributions/starter-gpu/run-with-postgres-store.yaml

@@ -145,6 +145,14 @@ providers:
       persistence:
         namespace: vector_io::weaviate
         backend: kv_default
+  - provider_id: ${env.ELASTICSEARCH_URL:+elasticsearch}
+    provider_type: remote::elasticsearch
+    config:
+      elasticsearch_url: ${env.ELASTICSEARCH_URL:=localhost:9200}
+      elasticsearch_api_key: ${env.ELASTICSEARCH_API_KEY:=}
+      persistence:
+        namespace: vector_io::elasticsearch
+        backend: kv_default
   files:
   - provider_id: meta-reference-files
     provider_type: inline::localfs

src/llama_stack/distributions/starter-gpu/run.yaml

@@ -145,6 +145,14 @@ providers:
       persistence:
         namespace: vector_io::weaviate
         backend: kv_default
+  - provider_id: ${env.ELASTICSEARCH_URL:+elasticsearch}
+    provider_type: remote::elasticsearch
+    config:
+      elasticsearch_url: ${env.ELASTICSEARCH_URL:=localhost:9200}
+      elasticsearch_api_key: ${env.ELASTICSEARCH_API_KEY:=}
+      persistence:
+        namespace: vector_io::elasticsearch
+        backend: kv_default
   files:
   - provider_id: meta-reference-files
     provider_type: inline::localfs

src/llama_stack/distributions/starter/build.yaml

@@ -28,6 +28,7 @@ distribution_spec:
     - provider_type: remote::pgvector
     - provider_type: remote::qdrant
     - provider_type: remote::weaviate
+    - provider_type: remote::elasticsearch
     files:
     - provider_type: inline::localfs
     safety:

src/llama_stack/distributions/starter/run-with-postgres-store.yaml

@@ -145,6 +145,14 @@ providers:
       persistence:
         namespace: vector_io::weaviate
         backend: kv_default
+  - provider_id: ${env.ELASTICSEARCH_URL:+elasticsearch}
+    provider_type: remote::elasticsearch
+    config:
+      elasticsearch_url: ${env.ELASTICSEARCH_URL:=localhost:9200}
+      elasticsearch_api_key: ${env.ELASTICSEARCH_API_KEY:=}
+      persistence:
+        namespace: vector_io::elasticsearch
+        backend: kv_default
   files:
   - provider_id: meta-reference-files
     provider_type: inline::localfs

src/llama_stack/distributions/starter/run.yaml

@@ -145,6 +145,14 @@ providers:
       persistence:
         namespace: vector_io::weaviate
         backend: kv_default
+  - provider_id: ${env.ELASTICSEARCH_URL:+elasticsearch}
+    provider_type: remote::elasticsearch
+    config:
+      elasticsearch_url: ${env.ELASTICSEARCH_URL:=localhost:9200}
+      elasticsearch_api_key: ${env.ELASTICSEARCH_API_KEY:=}
+      persistence:
+        namespace: vector_io::elasticsearch
+        backend: kv_default
   files:
   - provider_id: meta-reference-files
     provider_type: inline::localfs

src/llama_stack/distributions/starter/starter.py

@@ -32,6 +32,7 @@
 )
 from llama_stack.providers.registry.inference import available_providers
 from llama_stack.providers.remote.vector_io.chroma.config import ChromaVectorIOConfig
+from llama_stack.providers.remote.vector_io.elasticsearch.config import ElasticsearchVectorIOConfig
 from llama_stack.providers.remote.vector_io.pgvector.config import (
     PGVectorVectorIOConfig,
 )
@@ -121,6 +122,7 @@ def get_distribution_template(name: str = "starter") -> DistributionTemplate:
             BuildProvider(provider_type="remote::pgvector"),
             BuildProvider(provider_type="remote::qdrant"),
             BuildProvider(provider_type="remote::weaviate"),
+            BuildProvider(provider_type="remote::elasticsearch"),
         ],
         "files": [BuildProvider(provider_type="inline::localfs")],
         "safety": [
@@ -237,6 +239,15 @@ def get_distribution_template(name: str = "starter") -> DistributionTemplate:
                     cluster_url="${env.WEAVIATE_CLUSTER_URL:=}",
                 ),
             ),
+            Provider(
+                provider_id="${env.ELASTICSEARCH_URL:+elasticsearch}",
+                provider_type="remote::elasticsearch",
+                config=ElasticsearchVectorIOConfig.sample_run_config(
+                    f"~/.llama/distributions/{name}",
+                    elasticsearch_url="${env.ELASTICSEARCH_URL:=localhost:9200}",
+                    elasticsearch_api_key="${env.ELASTICSEARCH_API_KEY:=}",
+                ),
+            ),
         ],
         "files": [files_provider],
     }