Missing guides

Author: Katia Aresti

AGENTS.md

@@ -47,11 +47,11 @@ See `.editorconfig` for full details.
 
 ### Module Categories
 
-- **`infinispan-remote/`** — Tutorials using Hot Rod client to connect to an Infinispan Server (client-server mode)
-- **`infinispan-embedded/`** — Tutorials embedding Infinispan as a library (no server needed)
-- **`integrations/`** — Tutorials for Spring Boot, Quarkus, and Hibernate integrations
-- **`infinispan-ai/`** — AI/vector search tutorials (LangChain4j, vector search)
-- **`non-java-clients/`** — C++, C#, JavaScript Hot Rod client examples
+- **`infinispan-remote/`** - Tutorials using Hot Rod client to connect to an Infinispan Server (client-server mode)
+- **`infinispan-embedded/`** - Tutorials embedding Infinispan as a library (no server needed)
+- **`integrations/`** - Tutorials for Spring Boot, Quarkus, and Hibernate integrations
+- **`infinispan-ai/`** - AI/vector search tutorials (LangChain4j, vector search)
+- **`non-java-clients/`** - C++, C#, JavaScript Hot Rod client examples
 
 ### Shared Connection Helper
 
@@ -63,15 +63,15 @@ See `.editorconfig` for full details.
 ### Tutorial Module Pattern
 
 Each tutorial module follows the same structure:
-- `src/main/java/` — Runnable main class demonstrating the feature
-- `src/test/java/` — JUnit 5 test that exercises the same feature
-- `pom.xml` — Inherits from root, declares `exec-maven-plugin` for `mvn exec:exec`
-- `guide.adoc` (optional) — AsciiDoc tutorial guide published to infinispan.org
+- `src/main/java/` - Runnable main class demonstrating the feature
+- `src/test/java/` - JUnit 5 test that exercises the same feature
+- `pom.xml` - Inherits from root, declares `exec-maven-plugin` for `mvn exec:exec`
+- `guide.adoc` (optional) - AsciiDoc tutorial guide published to infinispan.org
 
 ### Documentation
 
-- `documentation/asciidoc/` — AsciiDoc source for published tutorial docs
-- `docs-maven-plugin/` — Custom Maven plugin that processes `guide.adoc` files from each tutorial into the website format
+- `documentation/asciidoc/` - AsciiDoc source for published tutorial docs
+- `docs-maven-plugin/` - Custom Maven plugin that processes `guide.adoc` files from each tutorial into the website format
 - Guides are built with the `guides` Maven profile
 
 ## CI
@@ -80,6 +80,6 @@ GitHub Actions runs on pushes and PRs to `main`, `development`, and `16.0.x` bra
 
 ## Branch Strategy
 
-- `development` — uses latest Infinispan dev version (`quay.io/infinispan-test/server:main`)
-- `main` — uses latest stable Infinispan release
+- `development` - uses latest Infinispan dev version (`quay.io/infinispan-test/server:main`)
+- `main` - uses latest stable Infinispan release
 - All contributions target `main`

docs-maven-plugin/src/main/java/org/infinispan/tutorial/docs/GuideMetadataGenerator.java

@@ -6,10 +6,13 @@
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Comparator;
+import java.util.HashMap;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 import java.util.stream.Stream;
 
 import org.asciidoctor.Asciidoctor;
@@ -142,7 +145,67 @@ private void processGuide(Path guideFile, String id, Asciidoctor asciidoctor,
       }
 
       guides.add(guide);
-      Files.copy(guideFile, guidesOutputDir.resolve(id + ".adoc"));
+
+      String resolved = resolveIncludes(content, guideFile.getParent());
+      Files.writeString(guidesOutputDir.resolve(id + ".adoc"), resolved);
+   }
+
+   private static final Pattern INCLUDE_PATTERN =
+         Pattern.compile("^include::(.+?)\\[tag=(\\w[\\w-]*)\\]\\s*$", Pattern.MULTILINE);
+
+   private final Map<Path, List<String>> fileCache = new HashMap<>();
+
+   private String resolveIncludes(String content, Path baseDir) {
+      Matcher matcher = INCLUDE_PATTERN.matcher(content);
+      StringBuilder sb = new StringBuilder();
+      while (matcher.find()) {
+         String filePath = matcher.group(1);
+         String tagName = matcher.group(2);
+         String extracted = extractTag(baseDir.resolve(filePath), tagName);
+         matcher.appendReplacement(sb, Matcher.quoteReplacement(extracted));
+      }
+      matcher.appendTail(sb);
+      return sb.toString();
+   }
+
+   private String extractTag(Path file, String tag) {
+      List<String> lines = fileCache.computeIfAbsent(file, f -> {
+         try {
+            return Files.readAllLines(f);
+         } catch (IOException e) {
+            System.err.println("WARNING: Cannot read include file: " + f);
+            return List.of();
+         }
+      });
+      if (lines.isEmpty()) {
+         return "// Include not found: " + file.getFileName() + "[tag=" + tag + "]";
+      }
+
+      String startMarker = "tag::" + tag + "[]";
+      String endMarker = "end::" + tag + "[]";
+      StringBuilder sb = new StringBuilder();
+      boolean capturing = false;
+      for (String line : lines) {
+         if (line.contains(startMarker)) {
+            capturing = true;
+            continue;
+         }
+         if (line.contains(endMarker)) {
+            capturing = false;
+            continue;
+         }
+         if (capturing) {
+            sb.append(line).append('\n');
+         }
+      }
+      String result = sb.toString();
+      if (result.isEmpty()) {
+         return "// Tag not found: " + tag + " in " + file.getFileName();
+      }
+      if (result.endsWith("\n")) {
+         result = result.substring(0, result.length() - 1);
+      }
+      return result;
    }
 
    private String attrString(Document doc, String name) {

infinispan-ai/langchain4j/guide.adoc

@@ -31,68 +31,36 @@ Add LangChain4j with the Infinispan embedding store and an ONNX embedding model:
 </dependency>
 ----
 
-The quantized MiniLM model runs locally — no API keys or external services needed.
+The quantized MiniLM model runs locally. No API keys or external services needed.
 
-== Step 2: Initialize the Embedding Model
+== Step 2: Initialize the Model and Create the Embedding Store
 
-Create a local embedding model that converts text to vectors:
+Create a local embedding model that converts text to vectors, then connect the embedding store to Infinispan:
 
 [source,java]
 ----
-EmbeddingModel embeddingModel = new AllMiniLmL6V2QuantizedEmbeddingModel();
-System.out.println("Dimension: " + embeddingModel.dimension()); // 384
+include::src/main/java/org/infinispan/tutorial/simple/ai/langchain4j/InfinispanLangchain4j.java[tag=setup]
 ----
 
-== Step 3: Create the Infinispan Embedding Store
-
-Connect the embedding store to Infinispan:
-
-[source,java]
-----
-ConfigurationBuilder builder = TutorialsConnectorHelper.connectionConfig();
-InfinispanEmbeddingStore embeddingStore = InfinispanEmbeddingStore.builder()
-      .cacheName("langchain4j-embeddings")
-      .dimension(embeddingModel.dimension())
-      .infinispanConfigBuilder(builder)
-      .distance(3) // inner product distance
-      .build();
-----
-
-== Step 4: Store Text as Embeddings
+== Step 3: Store Text as Embeddings
 
 Convert text segments to vectors and store them:
 
 [source,java]
 ----
-TextSegment segment = TextSegment.from(
-      "Infinispan supports vector search for AI use cases",
-      Metadata.from("source", "docs").put("topic", "ai"));
-
-Embedding embedding = embeddingModel.embed(segment).content();
-embeddingStore.add(embedding, segment);
+include::src/main/java/org/infinispan/tutorial/simple/ai/langchain4j/InfinispanLangchain4j.java[tag=add-embedding]
 ----
 
-== Step 5: Search by Semantic Similarity
+== Step 4: Search by Semantic Similarity
 
-Query with natural language — the model finds semantically similar text, not just keyword matches:
+Query with natural language. The model finds semantically similar text, not just keyword matches:
 
 [source,java]
 ----
-String query = "How can I use Infinispan with AI?";
-Embedding queryEmbedding = embeddingModel.embed(query).content();
-
-EmbeddingSearchRequest request = EmbeddingSearchRequest.builder()
-      .queryEmbedding(queryEmbedding)
-      .maxResults(3)
-      .build();
-
-EmbeddingSearchResult<TextSegment> result = embeddingStore.search(request);
-for (EmbeddingMatch<TextSegment> match : result.matches()) {
-   System.out.printf("Score: %.4f | %s%n", match.score(), match.embedded().text());
-}
+include::src/main/java/org/infinispan/tutorial/simple/ai/langchain4j/InfinispanLangchain4j.java[tag=search]
 ----
 
-== Step 6: Run the Tutorial
+== Step 5: Run the Tutorial
 
 [source,bash]
 ----

infinispan-ai/langchain4j/src/main/java/org/infinispan/tutorial/simple/ai/langchain4j/InfinispanLangchain4j.java

@@ -30,6 +30,7 @@ public static void main(String[] args) {
       }
    }
 
+   // tag::setup[]
    static void initEmbeddingModel() {
       embeddingModel = new AllMiniLmL6V2QuantizedEmbeddingModel();
       System.out.println("Embedding model initialized. Dimension: " + embeddingModel.dimension());
@@ -45,6 +46,7 @@ static void connectAndCreateStore() {
             .build();
       System.out.println("Connected to Infinispan and created embedding store.");
    }
+   // end::setup[]
 
    static void storeAndSearch() {
       // Store some text segments with metadata
@@ -57,6 +59,7 @@ static void storeAndSearch() {
 
       System.out.println("Stored 3 text segments with embeddings.\n");
 
+      // tag::search[]
       // Search by similarity
       String query = "How can I use Infinispan with AI?";
       System.out.println("Query: \"" + query + "\"");
@@ -75,13 +78,16 @@ static void storeAndSearch() {
          System.out.printf("  Score: %.4f | Text: %s%n",
                match.score(), match.embedded().text());
       }
+      // end::search[]
    }
 
+   // tag::add-embedding[]
    static void addEmbedding(String text, Metadata metadata) {
       TextSegment segment = TextSegment.from(text, metadata);
       Embedding embedding = embeddingModel.embed(segment).content();
       embeddingStore.add(embedding, segment);
    }
+   // end::add-embedding[]
 
    static void disconnect() {
       if (embeddingStore != null) {

infinispan-ai/mcp-server/AGENTS.md

@@ -1,7 +1,7 @@
 This project connects to an Infinispan server via its MCP endpoint.
 
 Always use the Infinispan MCP server tools to interact with Infinispan (manage caches, counters, schemas, entries).
-Do not use curl or the REST API directly — the MCP server is the intended interface.
+Do not use curl or the REST API directly. The MCP server is the intended interface.
 
 The Infinispan MCP server is configured in `.mcp.json` and provides tools for:
 - Cache operations (create, list, get, put, remove, query)

infinispan-ai/vector-search/guide.adoc

@@ -0,0 +1,89 @@
+= Vector Search with Infinispan
+:summary: Perform kNN vector search and hybrid queries combining vector similarity with full-text and metadata filters
+:mode: ai
+:topics: vector-search,knn
+:keywords: vector,knn,embedding,similarity,cosine,hybrid,full-text,indexed,protobuf
+:duration: 10
+:source-dir: infinispan-ai/vector-search
+
+== What You Will Learn
+
+How to store entities with vector embeddings in Infinispan and perform kNN (k-nearest neighbor) vector searches, including hybrid queries that combine vector similarity with full-text search and metadata filters.
+
+== Prerequisites
+
+* Java 17+
+* An Infinispan Server running on `localhost:11222` (or Docker/Podman available for Testcontainers)
+
+== Step 1: Define an Indexed Entity with a Vector Field
+
+Use the `@Vector` annotation to declare a vector field with its dimension and similarity function:
+
+[source,java]
+----
+@Proto
+@Indexed
+public record Beer(
+      @Keyword(projectable = true, sortable = true)
+      String name,
+
+      @Keyword(projectable = true, normalizer = "lowercase")
+      String style,
+
+      @Keyword(projectable = true, sortable = true, normalizer = "lowercase")
+      String brewery,
+
+      @Keyword(projectable = true, normalizer = "lowercase")
+      String country,
+
+      @Basic(projectable = true, sortable = true)
+      Double abv,
+
+      @Text
+      String description,
+
+      @Vector(dimension = 3, similarity = VectorSimilarity.COSINE)
+      float[] descriptionEmbedding
+) {
+}
+----
+
+== Step 2: Connect and Register the Schema
+
+Connect to the server and register the Protobuf schema for your entity:
+
+[source,java]
+----
+include::src/main/java/org/infinispan/tutorial/simple/remote/vectorsearch/VectorSearchQuickstart.java[tag=connect]
+----
+
+== Step 3: Perform a kNN Vector Search
+
+Use the `<->` operator with `~:k` to find the k nearest neighbors:
+
+[source,java]
+----
+include::src/main/java/org/infinispan/tutorial/simple/remote/vectorsearch/VectorSearchQuickstart.java[tag=knn]
+----
+
+== Step 4: Run Hybrid Queries
+
+Combine vector similarity with metadata filters using the `filtering` clause, or with full-text filters:
+
+[source,java]
+----
+include::src/main/java/org/infinispan/tutorial/simple/remote/vectorsearch/VectorSearchQuickstart.java[tag=hybrid]
+----
+
+== Step 5: Run the Tutorial
+
+[source,bash]
+----
+mvn package exec:exec
+----
+
+The output demonstrates full-text search, keyword/range filters, projections, kNN vector search with score projections, and hybrid queries filtering by style, country, and description text.
+
+== What's Next
+
+* link:../langchain4j/guide.html[Semantic search with LangChain4j] for vector search with an AI embedding model

infinispan-ai/vector-search/src/main/java/org/infinispan/tutorial/simple/remote/vectorsearch/VectorSearchQuickstart.java

@@ -48,6 +48,7 @@ public static void main(String[] args) throws Exception {
       disconnect();
    }
 
+   // tag::connect[]
    static void connect() throws Exception {
       ConfigurationBuilder builder = TutorialsConnectorHelper.connectionConfig();
       builder.addContextInitializer(new BeerSchemaImpl());
@@ -60,6 +61,7 @@ static void connect() throws Exception {
       cacheManager.administration().schemas().createOrUpdate(new BeerSchemaImpl());
       cache = cacheManager.getCache(CACHE_NAME);
    }
+   // end::connect[]
 
    static void disconnect() {
       TutorialsConnectorHelper.stop(cacheManager);
@@ -157,6 +159,7 @@ static void projectionsAndSorting() {
 
    // ---- Vector search (kNN) ----
 
+   // tag::knn[]
    static void knnVectorSearch() {
       System.out.println("=== kNN: 3 beers closest to 'dark roasty' vector [0.9, 0.1, 0.1] ===");
       Query<Beer> query = cache.query(
@@ -168,6 +171,7 @@ static void knnVectorSearch() {
       }
       System.out.println();
    }
+   // end::knn[]
 
    static void scoreProjection() {
       System.out.println("=== kNN with score: 3 beers closest to 'light crisp lager' vector [0.05, 0.9, 0.1] ===");
@@ -184,6 +188,7 @@ static void scoreProjection() {
 
    // ---- Hybrid queries: vector + metadata ----
 
+   // tag::hybrid[]
    static void hybridFilterByStyle() {
       System.out.println("=== Hybrid: closest to 'refreshing summer beer' [0.05, 0.95, 0.05], only lagers under 5% ABV ===");
       Query<Object[]> query = cache.query(
@@ -228,4 +233,5 @@ static void hybridFullTextAndVector() {
       }
       System.out.println();
    }
+   // end::hybrid[]
 }