Add documentation for generic model api

Fixes #267

spring-ai-core/src/main/java/org/springframework/ai/model/ModelOptions.java

@@ -17,7 +17,7 @@
 package org.springframework.ai.model;
 
 /**
- * Interface representing the customizable options for AI model interactions. This
+ * Interface representing the customizable options for AI model interactions. This marker
  * interface allows for the specification of various settings and parameters that can
  * influence the behavior and output of AI models. It is designed to provide flexibility
  * and adaptability in different AI scenarios, ensuring that the AI models can be

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/etl-pipeline.adoc

@@ -8,14 +8,51 @@ The RAG use case is text to augment the capabilities of generative models by ret
 
 == API Overview
 
+There are three main components of the ETL pipeline,
+
+* `DocumentReader` that implements `Supplier<List<Document>>`
+* `DocumentTransformer` that implements `Function<List<Document>, List<Document>>`
+* `DocumentWriter` that implements `Consumer<List<Document>>`
+
+The `Document` class contains text and metadata and is created from PDFs, text files and other document types via the `DocumentReader`.
+
+To construct a simple ETL pipeline, you can chain together an instance of each type.
+
+Let's say we have the following instances of those three ETL types
+
+* `PagePdfDocumentReader` an implementation of `DocumentReader`
+* `TokenTextSplitter` an implementation of `DocumentTransformer`
+* `VectorStore` an implementation of `DocumentWriter`
+
+To perform the basic loading of data into a Vector Database for use with the Retrieval Augmented Generation pattern, use the following code.
+[source,java]
+----
+vectorStore.accept(tokenTextSplitter.apply(pdfReader.get()));
+----
+
+== Getting Started
+
+To begin creating a Spring AI RAG application, follow these steps:
+
+. Download the latest https://github.com/spring-projects/spring-cli/releases[Spring CLI Release]
+and follow the https://docs.spring.io/spring-cli/reference/installation.html#_setting_up_your_path_or_alias[installation instructions].
+. To create a simple OpenAI-based application, use the command:
++
+```shell
+spring boot new --from ai-rag --name myrag
+```
+. Consult the generated `README.md` file for guidance on obtaining an OpenAI API Key and running your first AI RAG application.
+
+== ETL Interfaces and Implementations
 === DocumentReader
 
 Provides a source of documents from diverse origins.
-```java
+[source,java]
+----
 public interface DocumentReader extends Supplier<List<Document>> {
 
 }
-```
+----
 
 ==== JsonReader
 The `JsonReader` Parses documents in JSON format.
@@ -154,13 +191,13 @@ The `TextSplitter` an abstract base class that helps divides documents to fit th
 ==== TokenTextSplitter
 Splits documents while preserving token-level integrity.
 
-==== ContentFormatTransformer*::
+==== ContentFormatTransformer
 Ensures uniform content formats across all documents.
 
-==== KeywordMetadataEnricher*::
+==== KeywordMetadataEnricher
 Augments documents with essential keyword metadata.
 
-==== SummaryMetadataEnricher*::
+==== SummaryMetadataEnricher
 Enriches documents with summarization metadata for enhanced retrieval.
 
 === DocumentWriter

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/generic-model.adoc

@@ -3,8 +3,7 @@
 
 In order to provide a foundation for all AI Model clients, the Generic Model API was created.
 This makes it easy to contribute new AI Model support to Spring AI by following a common pattern.
-The following sections walk through this API and how it works.
-
+The following sections walk through this API.
 
 == Class Diagram
 
@@ -12,12 +11,125 @@ image::spring-ai-generic-model-api.jpg[width=900, align="center"]
 
 == ModelClient
 
+The ModelClient interface provides a generic API for invoking AI models. It is designed to handle the interaction with various types of AI models by abstracting the process of sending requests and receiving responses. The interface uses Java generics to accommodate different types of requests and responses, enhancing flexibility and adaptability across different AI model implementations.
+
+The interface is defined below:
+
+[source,java]
+----
+public interface ModelClient<TReq extends ModelRequest<?>, TRes extends ModelResponse<?>> {
+
+	/**
+	 * Executes a method call to the AI model.
+	 * @param request the request object to be sent to the AI model
+	 * @return the response from the AI model
+	 */
+	TRes call(TReq request);
+
+}
+----
+
 == StreamingModelClient
 
+The StreamingModelClient interface provides a generic API for invoking a AI models with streaming response. It abstracts the process of sending requests and receiving a streaming responses. The interface uses Java generics to accommodate different types of requests and responses, enhancing flexibility and adaptability across different AI model implementations.
+
+[source,java]
+----
+public interface StreamingModelClient<TReq extends ModelRequest<?>, TResChunk extends ModelResponse<?>> {
+
+	/**
+	 * Executes a method call to the AI model.
+	 * @param request the request object to be sent to the AI model
+	 * @return the streaming response from the AI model
+	 */
+	Flux<TResChunk> stream(TReq request);
+
+}
+----
+
+
 == ModelRequest
 
+Interface representing a request to an AI model. This interface encapsulates the necessary information required to interact with an AI model, including instructions or inputs (of generic type T) and additional model options. It provides a standardized way to send requests to AI models, ensuring that all necessary details are included and can be easily managed.
+
+[source,java]
+----
+public interface ModelRequest<T> {
+
+	/**
+	 * Retrieves the instructions or input required by the AI model.
+	 * @return the instructions or input required by the AI model
+	 */
+	T getInstructions(); // required input
+
+	/**
+	 * Retrieves the customizable options for AI model interactions.
+	 * @return the customizable options for AI model interactions
+	 */
+	ModelOptions getOptions();
+
+}
+----
+
 == ModelOptions
 
+Interface representing the customizable options for AI model interactions. This marker interface allows for the specification of various settings and parameters that can influence the behavior and output of AI models. It is designed to provide flexibility and adaptability in different AI scenarios, ensuring that the AI models can be fine-tuned according to specific requirements.
+
+[source,java]
+----
+public interface ModelOptions {
+
+}
+----
+
 == ModelResponse
 
+Interface representing the response received from an AI model. This interface provides methods to access the main result or a list of results generated by the AI model, along with the response metadata. It serves as a standardized way to encapsulate and manage the output from AI models, ensuring easy retrieval and processing of the generated information.
+
+[source,java]
+----
+public interface ModelResponse<T extends ModelResult<?>> {
+
+	/**
+	 * Retrieves the result of the AI model.
+	 * @return the result generated by the AI model
+	 */
+	T getResult();
+
+	/**
+	 * Retrieves the list of generated outputs by the AI model.
+	 * @return the list of generated outputs
+	 */
+	List<T> getResults();
+
+	/**
+	 * Retrieves the response metadata associated with the AI model's response.
+	 * @return the response metadata
+	 */
+	ResponseMetadata getMetadata();
+
+}
+----
+
+
 == ModelResult
+ This interface provides methods to access the main output of the AI model and the metadata associated with this result. It is designed to offer a standardized and comprehensive way to handle and interpret the outputs generated by AI models.
+
+[source,java]
+----
+public interface ModelResult<T> {
+
+	/**
+	 * Retrieves the output generated by the AI model.
+	 * @return the output generated by the AI model
+	 */
+	T getOutput();
+
+	/**
+	 * Retrieves the metadata associated with the result of an AI model.
+	 * @return the metadata associated with the result
+	 */
+	ResultMetadata getMetadata();
+
+}
+----