Update docs

01-chat-models/chat-models-ollama/README.md

@@ -55,6 +55,7 @@ The application relies on the native Testcontainers support in Spring Boot to sp
 ## Calling the application
 
 You can now call the application that will use Ollama and llama2 to generate text based on a default prompt.
+This example uses [httpie](https://httpie.io) to send HTTP requests.
 
 ```shell
 http :8080/ai/chat

01-chat-models/chat-models-openai/README.md

@@ -46,7 +46,8 @@ Finally, run the Spring Boot application.
 
 ## Calling the application
 
-You can now call the application that will use Ollama and llama2 to generate text based on a default prompt.
+You can now call the application that will use OpenAI and _gpt-3.5-turbo_ to generate text based on a default prompt.
+This example uses [httpie](https://httpie.io) to send HTTP requests.
 
 ```shell
 http :8080/ai/chat

02-prompts/prompts-basics-ollama/README.md

@@ -1,25 +1,39 @@
 # Prompts Basic: Ollama
 
-## Running the application
+Prompting using simple text with LLMs via Ollama.
+
+# Running the application
+
+The application relies on Ollama for providing LLMs. You can either run Ollama locally on your laptop (macOS or Linux), or rely on the Testcontainers support in Spring Boot to spin up an Ollama service automatically.
 
 ### When using Ollama
 
+First, make sure you have [Ollama](https://ollama.ai) installed on your laptop (macOS or Linux).
+Then, use Ollama to run the _llama2_ large language model.
+
 ```shell
 ollama run llama2
 ```
 
+Finally, run the Spring Boot application.
+
 ```shell
 ./gradlew bootRun
 ```
 
 ### When using Docker/Podman
 
+The application relies on the native Testcontainers support in Spring Boot to spin up an Ollama service with a _llama2_ model at startup time.
+
 ```shell
 ./gradlew bootTestRun
 ```
 
 ## Calling the application
 
+You can now call the application that will use Ollama and llama2 to generate an answer to your questions.
+This example uses [httpie](https://httpie.io) to send HTTP requests.
+
 ```shell
 http --raw "What is the capital of Italy?" :8080/ai/chat/simple
 ```

02-prompts/prompts-basics-openai/README.md

@@ -1,19 +1,31 @@
 # Prompts Basic: OpenAI
 
+Prompting using simple text with LLMs via OpenAI.
+
 ## Running the application
 
+The application relies on an OpenAI API for providing LLMs.
+
 ### When using OpenAI
 
+First, make sure you have an OpenAI account.
+Then, define an environment variable with the OpenAI API Key associated to your OpenAI account as the value.
+
 ```shell
 export SPRING_AI_OPENAI_API_KEY=<INSERT KEY HERE>
 ```
 
+Finally, run the Spring Boot application.
+
 ```shell
 ./gradlew bootRun
 ```
 
 ## Calling the application
 
+You can now call the application that will use OpenAI and _gpt-3.5-turbo_ to generate an answer to your questions.
+This example uses [httpie](https://httpie.io) to send HTTP requests.
+
 ```shell
 http --raw "What is the capital of Italy?" :8080/ai/chat/simple
 ```

02-prompts/prompts-messages-ollama/README.md

@@ -1,25 +1,39 @@
 # Prompts Messages: Ollama
 
-## Running the application
+Prompting using structured messages and roles with LLMs via Ollama.
+
+# Running the application
+
+The application relies on Ollama for providing LLMs. You can either run Ollama locally on your laptop (macOS or Linux), or rely on the Testcontainers support in Spring Boot to spin up an Ollama service automatically.
 
 ### When using Ollama
 
+First, make sure you have [Ollama](https://ollama.ai) installed on your laptop (macOS or Linux).
+Then, use Ollama to run the _llama2_ large language model.
+
 ```shell
 ollama run llama2
 ```
 
+Finally, run the Spring Boot application.
+
 ```shell
 ./gradlew bootRun
 ```
 
 ### When using Docker/Podman
 
+The application relies on the native Testcontainers support in Spring Boot to spin up an Ollama service with a _llama2_ model at startup time.
+
 ```shell
 ./gradlew bootTestRun
 ```
 
 ## Calling the application
 
+You can now call the application that will use Ollama and llama2 to generate an answer to your questions.
+This example uses [httpie](https://httpie.io) to send HTTP requests.
+
 ```shell
 http --raw "What is the capital of Italy?" :8080/ai/chat/single
 ```

02-prompts/prompts-messages-openai/README.md

@@ -1,19 +1,31 @@
 # Prompts Messages: OpenAI
 
+Prompting using structured messages and roles with LLMs via OpenAI.
+
 ## Running the application
 
+The application relies on an OpenAI API for providing LLMs.
+
 ### When using OpenAI
 
+First, make sure you have an OpenAI account.
+Then, define an environment variable with the OpenAI API Key associated to your OpenAI account as the value.
+
 ```shell
 export SPRING_AI_OPENAI_API_KEY=<INSERT KEY HERE>
 ```
 
+Finally, run the Spring Boot application.
+
 ```shell
 ./gradlew bootRun
 ```
 
 ## Calling the application
 
+You can now call the application that will use OpenAI and _gpt-3.5-turbo_ to generate an answer to your questions.
+This example uses [httpie](https://httpie.io) to send HTTP requests.
+
 ```shell
 http --raw "What is the capital of Italy?" :8080/ai/chat/single
 ```

02-prompts/prompts-templates-ollama/README.md

@@ -1,25 +1,39 @@
 # Prompts Templates: Ollama
 
-## Running the application
+Prompting using templates with LLMs via Ollama.
+
+# Running the application
+
+The application relies on Ollama for providing LLMs. You can either run Ollama locally on your laptop (macOS or Linux), or rely on the Testcontainers support in Spring Boot to spin up an Ollama service automatically.
 
 ### When using Ollama
 
+First, make sure you have [Ollama](https://ollama.ai) installed on your laptop (macOS or Linux).
+Then, use Ollama to run the _llama2_ large language model.
+
 ```shell
 ollama run llama2
 ```
 
+Finally, run the Spring Boot application.
+
 ```shell
 ./gradlew bootRun
 ```
 
 ### When using Docker/Podman
 
+The application relies on the native Testcontainers support in Spring Boot to spin up an Ollama service with a _llama2_ model at startup time.
+
 ```shell
 ./gradlew bootTestRun
 ```
 
 ## Calling the application
 
+You can now call the application that will use Ollama and llama2 to generate an answer to your questions.
+This example uses [httpie](https://httpie.io) to send HTTP requests.
+
 ```shell
 http :8080/ai/chat/user genre="rock" instrument="piano"
 ```

02-prompts/prompts-templates-openai/README.md

@@ -1,19 +1,31 @@
 # Prompts Templates: OpenAI
 
+Prompting using templates with LLMs via OpenAI.
+
 ## Running the application
 
+The application relies on an OpenAI API for providing LLMs.
+
 ### When using OpenAI
 
+First, make sure you have an OpenAI account.
+Then, define an environment variable with the OpenAI API Key associated to your OpenAI account as the value.
+
 ```shell
 export SPRING_AI_OPENAI_API_KEY=<INSERT KEY HERE>
 ```
 
+Finally, run the Spring Boot application.
+
 ```shell
 ./gradlew bootRun
 ```
 
 ## Calling the application
 
+You can now call the application that will use OpenAI and _gpt-3.5-turbo_ to generate an answer to your questions.
+This example uses [httpie](https://httpie.io) to send HTTP requests.
+
 ```shell
 http :8080/ai/chat/user genre="rock" instrument="piano"
 ```

03-output-parsers/output-parsers-ollama/README.md

@@ -1,25 +1,39 @@
 # Output Parsers: Ollama
 
-## Running the application
+Parsing the LLM output as structured objects (Beans, Map, List) via Ollama.
+
+# Running the application
+
+The application relies on Ollama for providing LLMs. You can either run Ollama locally on your laptop (macOS or Linux), or rely on the Testcontainers support in Spring Boot to spin up an Ollama service automatically.
 
 ### When using Ollama
 
+First, make sure you have [Ollama](https://ollama.ai) installed on your laptop (macOS or Linux).
+Then, use Ollama to run the _llama2_ large language model.
+
 ```shell
 ollama run llama2
 ```
 
+Finally, run the Spring Boot application.
+
 ```shell
 ./gradlew bootRun
 ```
 
 ### When using Docker/Podman
 
+The application relies on the native Testcontainers support in Spring Boot to spin up an Ollama service with a _llama2_ model at startup time.
+
 ```shell
 ./gradlew bootTestRun
 ```
 
 ## Calling the application
 
+You can now call the application that will use Ollama and llama2 to generate an answer to your questions.
+This example uses [httpie](https://httpie.io) to send HTTP requests.
+
 ```shell
 http :8080/ai/chat/bean genre="rock" instrument="piano"
 ```

03-output-parsers/output-parsers-openai/README.md

@@ -1,19 +1,31 @@
 # Output Parsers: OpenAI
 
+Parsing the LLM output as structured objects (Beans, Map, List) via Open AI.
+
 ## Running the application
 
+The application relies on an OpenAI API for providing LLMs.
+
 ### When using OpenAI
 
+First, make sure you have an OpenAI account.
+Then, define an environment variable with the OpenAI API Key associated to your OpenAI account as the value.
+
 ```shell
 export SPRING_AI_OPENAI_API_KEY=<INSERT KEY HERE>
 ```
 
+Finally, run the Spring Boot application.
+
 ```shell
 ./gradlew bootRun
 ```
 
 ## Calling the application
 
+You can now call the application that will use OpenAI and _gpt-3.5-turbo_ to generate an answer to your questions.
+This example uses [httpie](https://httpie.io) to send HTTP requests.
+
 ```shell
 http :8080/ai/chat/bean genre="rock" instrument="piano"
 ```

04-embedding-models/embedding-models-ollama/README.md

@@ -1,25 +1,69 @@
 # Embedding Models: Ollama
 
+Vector transformation (embeddings) with LLMs via Ollama.
+
+## Description
+
+Spring AI provides an `EmbeddingClient` abstraction for integrating with LLMs via several providers, including Ollama.
+
+When using the _Spring AI Ollama Spring Boot Starter_, an `EmbeddingClient` object is autoconfigured for you to use Ollama.
+By default, the _llama2_ model is used.
+
+```java
+@RestController
+class EmbeddingController {
+    private final EmbeddingClient embeddingClient;
+
+    EmbeddingController(EmbeddingClient embeddingClient) {
+        this.embeddingClient = embeddingClient;
+    }
+
+    @GetMapping("/ai/embed")
+    String embed(@RequestParam(defaultValue = "And Gandalf yelled: 'You shall not pass!'") String message) {
+        var embeddings = embeddingClient.embed(message);
+        return "Size of the embedding vector: " + embeddings.size();
+    }
+}
+```
+
 ## Running the application
 
+The application relies on Ollama for providing LLMs. You can either run Ollama locally on your laptop (macOS or Linux), or rely on the Testcontainers support in Spring Boot to spin up an Ollama service automatically.
+
 ### When using Ollama
 
+First, make sure you have [Ollama](https://ollama.ai) installed on your laptop (macOS or Linux).
+Then, use Ollama to run the _llama2_ large language model.
+
 ```shell
 ollama run llama2
 ```
 
+Finally, run the Spring Boot application.
+
 ```shell
 ./gradlew bootRun
 ```
 
 ### When using Docker/Podman
 
+The application relies on the native Testcontainers support in Spring Boot to spin up an Ollama service with a _llama2_ model at startup time.
+
 ```shell
 ./gradlew bootTestRun
 ```
 
 ## Calling the application
 
+You can now call the application that will use Ollama and llama2 to generate a vector representation (embeddings) of a default text.
+This example uses [httpie](https://httpie.io) to send HTTP requests.
+
 ```shell
 http :8080/ai/embed
 ```
+
+Try passing your custom prompt and check the result.
+
+```shell
+http :8080/ai/embed message=="The capital of Italy is Rome"
+```