Partial ChatClient docs

Author: markpollack

spring-ai-docs/src/main/antora/modules/ROOT/nav.adoc

@@ -2,6 +2,7 @@
 * xref:concepts.adoc[AI Concepts]
 * xref:getting-started.adoc[Getting Started]
 * xref:api/index.adoc[]
+** xref:api/chatclient.adoc[]
 ** xref:api/chatmodel.adoc[]
 *** xref:api/chat/openai-chat.adoc[OpenAI]
 **** xref:api/chat/functions/openai-chat-functions.adoc[Function Calling]

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

@@ -0,0 +1,102 @@
+[[ChatClient]]
+= Chat Client API
+
+The `ChatClient` offers a fluent API for stateless interaction with an AI Model. It supports both a synchronous and reactive programming model.
+
+The fluent API has methods for building up the constituent parts of a `Prompt` that is passed to the AI model as input.
+The `Prompt` contains the instructional text to guide the AI model's output and behavior. From the API point of view, prompts consist of a collection of messages.
+
+The AI model processes two main types of messages: user messages, which are direct inputs from the user, and system messages, which are generated by the system to guide the conversation.
+
+These messages often contain template placeholders that are substituted at runtime based on user input to customize the response of the AI model to the user input.
+
+There are also Prompt options that can be specified., such as the name of the AI Model to generate content and the temperature setting that controls the randomness or creativity of the generated output.
+
+== Using an autoconfigured ChatClient.Builder
+
+In the most simple use case, Spring AI provides Spring Boot autoconfiguration, creating a prototype `ChatClient.Builder` bean for you to inject into your class.
+Here is a simple example of retrieving a String response to a simple user request.
+
+```java
+@RestController
+class MyController {
+
+    private final ChatClient chatClient;
+
+    public MyController(ChatClient.Builder chatClientBuilder) {
+        this.chatClient = chatClientBuilder.build();
+    }
+
+    @GetMapping("/ai")
+    String generation(String userInput) {
+        return this.chatClient.prompt()
+            .user(userInput)
+            .call()
+            .content();
+    }
+}
+```
+
+In this simple example, the user input sets the contents of the user message. The call method sends a request to the AI model, and the context method returns the AI model's response as a String.
+
+
+== Returing a `ChatResponse`
+
+The response from the AI model is a rich structure defined by the type ChatResponse.
+ChatResponse includes metadata about how the response was generated and can also contain multiple responses, known as generations, each with its own metadata.
+The metadata includes the number of tokens (each token is approximately 3/4 of a word) used to create the response. This information is important because hosted AI models charge based on the number of tokens used per request.
+
+An example to return the `ChatResponse` object that contains the metadata is shown below by invoking `chatResponse()` after the `call()` method.
+
+
+```java
+ChatResponse chatResponse = this.chatClient.prompt()
+    .user("Tell me a joke")
+    .call()
+    .chatResponse();
+```
+
+== Returning an Entity
+
+You often want to return an entity class that is mapped from the returned String. The `entity` method provides this functionality.
+
+For example, given the Java record:
+
+```java
+record ActorFilms(String actor, List<String> movies) {
+}
+```
+
+You can easily map the AI model's output to this record using the `entity` method, as shown below:
+
+```java
+ActorFilms actorFilms = chatClient.prompt()
+    .user("Generate the filmography for a random actor.")
+    .call()
+    .entity(ActorFilms.class);
+```
+
+There is also an overloaded `entity` method with the signature `entity(ParameterizedTypeReference<T> type)` that lets you specify types such as generic Lists.
+
+== Streaming Responses
+
+The `stream` lets you get an asynchronous response as shown below
+```java
+Flux<String> output = this.chatClient.prompt()
+    .user("Tell me a joke")
+    .stream()
+    .content();
+```
+
+You can also stream the `ChatResponse` using the method `Flux<ChatResponse> chatResponse()`.
+
+== Using defaults and parameters
+
+It is often useful to create a `ChatClient` with default user and/or system text defined at design time.
+By design time, we mean creating it at application startup in a `@Configuration` class.
+You can then replace the user or system parameters in the main runtime code.
+
+Here is a simple example which defines the system text without using any parameters.
+The system text sets the context, instructions, and overall desired behavior for the model's response
+
+== Passing in user and system parameters