Address Vespa integration review feedback

Author: kudos07

.github/workflows/vespa.yml

@@ -29,7 +29,7 @@ concurrency:
 env:
   PYTHONUNBUFFERED: "1"
   FORCE_COLOR: "1"
-  TEST_MATRIX_OS: '["ubuntu-latest", "windows-latest", "macos-latest"]'
+  TEST_MATRIX_OS: '["ubuntu-latest"]'
   TEST_MATRIX_PYTHON: '["3.10", "3.14"]'
 
 jobs:
@@ -82,6 +82,9 @@ jobs:
       - name: Run unit tests
         run: hatch run test:unit-cov-retry
 
+      - name: Run Vespa container
+        run: docker compose up -d --wait
+
       # On PR: generates coverage comment artifact. On push to main: stores coverage baseline on data branch.
       - name: Store unit tests coverage
         if: matrix.python-version == '3.10' && runner.os == 'Linux' && github.event_name != 'schedule'
@@ -95,6 +98,9 @@ jobs:
           MINIMUM_ORANGE: 60
 
       - name: Run integration tests
+        env:
+          VESPA_RUN_INTEGRATION_TESTS: "1"
+          VESPA_URL: "http://localhost"
         run: hatch run test:integration-cov-append-retry
 
       - name: Store combined coverage

integrations/vespa/CHANGELOG.md

@@ -3,41 +3,12 @@
 [![PyPI - Version](https://img.shields.io/pypi/v/vespa-haystack.svg)](https://pypi.org/project/vespa-haystack)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/vespa-haystack.svg)](https://pypi.org/project/vespa-haystack)
 
-- [Changelog](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/vespa/CHANGELOG.md)
-
+- [Integration page](https://haystack.deepset.ai/integrations/vespa)
 ---
 
-`vespa-haystack` provides a Haystack `DocumentStore` plus keyword and embedding retrievers for
-[Vespa](https://vespa.ai/).
-
-This integration assumes you already have a Vespa application and schema running. The document store
-connects to that existing setup and lets you write documents and query them from Haystack pipelines.
-
-## Examples
-
-- [Keyword retrieval example](examples/keyword_retrieval.py)
-- [Embedding retrieval example](examples/embedding_retrieval.py)
-
-## Local Smoke Test
-
-To verify the integration against a real local Vespa instance, start Docker Desktop and run:
-
-```bash
-hatch run python scripts/local_keyword_smoke_test.py
-```
-
-This deploys a minimal Vespa application locally, writes three documents, runs a direct filter query,
-and checks keyword retrieval through `VespaKeywordRetriever`.
-
-## Notes
-
-- Set `VESPA_URL` to your Vespa endpoint before running the examples.
-- Make sure your Vespa schema field names match the ones you pass into `VespaDocumentStore`.
-- Vespa document IDs are written through the Vespa document path (`data_id`). The optional `id_field`
-  is only used when a query response also exposes an explicit id field.
-- For embedding retrieval, your Vespa schema must already include a tensor field and a ranking profile
-  compatible with nearest-neighbor search. The example assumes a ranking profile named `semantic`.
-
 ## Contributing
 
 Refer to the general [Contribution Guidelines](https://github.com/deepset-ai/haystack-core-integrations/blob/main/CONTRIBUTING.md).
+
+To run integration tests locally, you need a Docker container running Vespa with the bundled application deployed.
+Use the provided `docker-compose.yml` file to start the container: `docker compose up -d`.

integrations/vespa/README.md

@@ -0,0 +1,15 @@
+services:
+  vespa:
+    image: vespaengine/vespa:latest
+    container_name: vespa
+    hostname: vespa
+    ports:
+      - "8080:8080"
+      - "19071:19071"
+    volumes:
+      - ./vespa_app:/vespa_app:ro
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:19071/ApplicationStatus"]
+      interval: 10s
+      timeout: 5s
+      retries: 30

integrations/vespa/docker-compose.yml

@@ -54,7 +54,6 @@
     VespaEmbeddingRetriever(
         document_store=document_store,
         top_k=2,
-        ranking="semantic",
         query_tensor_name="query_embedding",
     ),
 )

integrations/vespa/examples/embedding_retrieval.py

@@ -21,6 +21,7 @@
 # This example assumes your Vespa schema already exists and contains:
 # - a text field named `content`
 # - metadata fields `category` and `author`
+# - a ranking profile named `bm25`
 document_store = VespaDocumentStore(
     schema="doc",
     namespace="doc",

integrations/vespa/examples/keyword_retrieval.py

@@ -1,6 +1,9 @@
 loaders:
   - modules:
+      - haystack_integrations.components.retrievers.vespa.keyword_retriever
+      - haystack_integrations.components.retrievers.vespa.embedding_retriever
       - haystack_integrations.document_stores.vespa.document_store
+      - haystack_integrations.document_stores.vespa.filters
     search_path: [../src]
 processors:
   - type: filter

integrations/vespa/pydoc/config_docusaurus.yml

@@ -5,11 +5,20 @@ build-backend = "hatchling.build"
 [project]
 name = "vespa-haystack"
 dynamic = ["version"]
-description = "Haystack integration for vespa"
+description = "Haystack integration for Vespa"
 readme = "README.md"
 requires-python = ">=3.10"
 license = "Apache-2.0"
-keywords = []
+keywords = [
+  "haystack",
+  "vespa",
+  "document-store",
+  "retriever",
+  "search",
+  "retrieval",
+  "rag",
+  "vector-search",
+]
 authors = [{ name = "deepset GmbH", email = "info@deepset.ai" }]
 classifiers = [
   "License :: OSI Approved :: Apache Software License",
@@ -23,7 +32,7 @@ classifiers = [
   "Programming Language :: Python :: Implementation :: CPython",
   "Programming Language :: Python :: Implementation :: PyPy",
 ]
-dependencies = ["haystack-ai", "pyvespa"]
+dependencies = ["haystack-ai>=2.28.0", "pyvespa>=0.58.0"]
 
 [project.urls]
 Documentation = "https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/vespa#readme"
@@ -119,7 +128,7 @@ select = [
 ignore = [
     # Allow non-abstract empty methods in abstract base classes
     "B027",
-    # Allow function calls in argument defaults (common Haystack pattern for Secret.from_env_var)
+    # Allow function calls in argument defaults
     "B008",
     # Ignore checks for possible passwords
     "S105",