[rashidi]

Overview

Adds a new tutorial module, ai-pgvector, demonstrating how to implement semantic vector similarity search in Spring Boot using Spring AI and PostgreSQL's pgvector extension.

Motivation & Architecture

Rather than introducing a dedicated, standalone vector database that complicates deployment and data synchronization, pgvector brings vector embeddings directly into PostgreSQL. This preserves ACID guarantees, simplifies backups and migrations, and allows combining semantic similarity search with relational filters.

Key Changes

• Module Setup:
  • Added ai-pgvector submodule to settings.gradle.kts and root README.adoc.
  • Configured build.gradle.kts with spring-ai-starter-vector-store-pgvector, PostgreSQL driver, and Testcontainers dependencies.
• Service Implementation (zin.rashidi.boot.ai.pgvector):
  • DocumentItem: Domain record for ingesting text content and metadata attributes.
  • SemanticSearchService: Encapsulates document ingestion and similarity search using Spring AI's VectorStore and SearchRequest.
  • Configured HNSW index and COSINE_DISTANCE metric in application.properties.
• Testing with Testcontainers:
  • TestcontainersConfiguration: Configured an ephemeral pgvector/pgvector:pg16 container using @ServiceConnection.
  • SemanticSearchIntegrationTests: Implemented a deterministic, keyword-aware in-memory EmbeddingModel to ensure tests run hermetically in CI without external LLM API keys or network latency.
• Documentation:
  • Added complete tutorial article in ai-pgvector/README.adoc.

Verification

• Verified module build and tests locally:

  ./gradlew :ai-pgvector:build