[docs] Conversation Classes (#43)

packages/docs/package.json

@@ -19,6 +19,7 @@
         "@mantine/spotlight": "^7.0.0-alpha.21",
         "@mantine/vanilla-extract": "^7.0.0-alpha.21",
         "@vanilla-extract/css": "^1.12.0",
+        "@vercel/analytics": "^1.0.2",
         "contentlayer": "^0.3.4",
         "next": "13.4.12",
         "next-contentlayer": "^0.3.4",

packages/docs/src/app/layout.tsx

@@ -1,6 +1,7 @@
 import "@mantine/core/styles.css";
 import "@mantine/spotlight/styles.css";
 import "@mantine/code-highlight/styles.css";
+import { Analytics } from "@vercel/analytics/react";
 import { ColorSchemeScript } from "@mantine/core";
 import Shell from "./components/Shell/Shell";
 import DocsSpotlight from "./components/DocsSpotlight/DocsSpotlight";
@@ -59,6 +60,7 @@ const AppLayout = ({ children }: AppLayoutProps) => {
                     <DocsSpotlight />
                     <Shell>{children}</Shell>
                 </Providers>
+                <Analytics />
             </body>
         </html>
     );

packages/docs/src/mdx/docs/conversation/chatcompletion-service.mdx

@@ -7,4 +7,47 @@ api: classes/ChatCompletionService.html
 
 > This is an internal class. You can interact with it when authoring plugins, but you shouldn't need to instantiate it.
 
-<UnderConstruction path="classes/ChatCompletionService.html" />
+The `ChatCompletionService` exposes the methods used by the `Conversation` to interact with the Chat Completion API.
+Unlike most other classes (of the `Conversation` class), it is not exposed as a property of the `Conversation` class.
+It is essentially a utility class for internal use by the library and can be very complex to work with standalone.
+
+However, it is exposed to plugins, in order to allow complex behaviors and side effects.
+This page will cover what this service accomplishes, but there aren't much patterns to follow when using it.
+
+## Getting a chat completion response from the API
+
+The `getChatCompletionResponse` method is in charge of getting a response from the Chat Completion API using the appropriate handler:
+
+- `handleStreamedResponse`: used when the `stream` option is enabled.
+- `handleNonStreamedResponse`: used when the `stream` option is disabled.
+
+It then returns the response as a `Promise<Message>`.
+
+### Handling a streamed response
+
+When the `stream` option is enabled, the `handleStreamedResponse` method will be used to get a response from the Chat Completion API.
+One particular distinction of this method is that it is **synchronous**. 
+It does not wait for the API response to be received, because it is easy to predict the initial state of the message:
+
+- The message content will be empty.
+- The message will be updated internally, periodically, as the API sends new data.
+
+The goal here is to get the message instance out as soon as possible.
+This allows client code to subscribe to the message's events, such as `onUpdate` or `onContentStream`, without missing any event.
+
+### Handling a non-streamed response
+
+When the `stream` option is disabled, the `handleNonStreamedResponse` method will be used to get a response from the Chat Completion API.
+Unlike the previous handler, this one is **asynchronous**.
+It will wait for the API response to be received, and then return the message instance.
+
+## Getting the assistant's response
+
+The `getAssistantResponse` method is a wrapper around the `getChatCompletionResponse` method.
+It gets the chat completion response, moderates it, adds the message to the `ConversationHistory` and returns the message.
+
+### Moderation
+
+The `moderateMessage` method is a wrapper around the `moderate` method of the `Message` class.
+The role of the `Message.moderate` method is only to get the message's moderation status.
+The `moderateMessage` method will use this status to determine whether or not it should throw a `ModerationException`.

packages/docs/src/mdx/docs/conversation/conversation-callable-functions.mdx

@@ -7,4 +7,109 @@ api: classes/ConversationCallableFunctions.html
 
 > This is an internal class. You'll interact with it and configure it through the `Conversation` class, but you shouldn't need to instantiate it.
 
-<UnderConstruction path="classes/ConversationCallableFunctions.html" />
+The `ConversationCallableFunctions` class is what keeps track of the callable functions in a conversation and manages them.
+
+## Configuring in conversation constructor
+
+You'll most likely be interacting with this class through the `Conversation` class.
+More specifically, through the `callableFunctions` property of the `Conversation` constructor.
+
+```ts
+const conversation = new Conversation({
+    callableFunctions: {
+        /* options */
+    },
+});
+```
+
+The options you pass are conveniently the same as the [`toJSON`](#serialization-and-deserialization) method:
+
+-   `functions`: The callable functions available to the conversation.
+    These should be a [JSON representation of a `CallableFunction`](../callable-function/callable-function#serialization-and-deserialization).
+
+## Managing Callable Functions
+
+The `ConversationCallableFunctions` class has various methods to manage the functions available in the conversation.
+
+### Adding Callable Functions
+
+You can add a function using the `addFunction` method.
+This method takes either a [`CallableFunction`](../callable-function/callable-function) instance or a [JSON representation of a `CallableFunction`](../callable-function/callable-function#serialization-and-deserialization).
+
+```ts
+const callableFunction = new CallableFunction(/* ... */);
+
+conversation.callableFunctions.addFunction(callableFunction);
+conversation.callableFunctions.addFunction(callableFunction.toJSON());
+```
+
+### Getting the Callable Functions
+
+You can get the callable functions in the conversation using the `getFunctions` method.
+
+```ts
+const callableFunctions = conversation.callableFunctions.getFunctions();
+```
+
+### Removing Callable Functions
+
+You can remove a specific callable function with the `removeFunction` method or remove all of them with the `clearFunctions` method.
+
+```ts
+const callableFunction = new CallableFunction(/* ... */);
+conversation.callableFunctions.addFunction(callableFunction);
+
+// Remove a specific function
+conversation.callableFunctions.removeFunction(callableFunction);
+conversation.callableFunctions.removeFunction(callableFunction.id);
+
+// Remove all functions
+conversation.callableFunctions.clearFunctions();
+```
+
+## Event Listeners
+
+You can listen to various events on a `ConversationCallableFunctions` instance.
+These allow you to react to certain events, such as when a function is added.
+
+All events shown below have an `on`, `once` and `off` method (e.g: `onCallableFunctionAdded`, `onceCallableFunctionAdded`, `offCallableFunctionAdded`).
+
+-   `on`: Adds a listener to the event. Takes a callback function as an argument.
+-   `once`: Same as `on`, but the listener will only be called once before being automatically unsubscribed.
+-   `off`: Removes a listener from the event. Takes the callback function passed to `on` or `once` as an argument.
+
+### CallableFunctionAdded
+
+This event fires when a function is added to the callable functions, with the following arguments:
+
+-   `callableFunction`: The function that was added.
+
+### CallableFunctionRemoved
+
+This event fires when a function is removed to the callable functions, with the following arguments:
+
+-   `callableFunction`: The function that was removed.
+
+## Serialization and Deserialization
+
+You can serialize the conversation callable functions to JSON using the `toJSON` method.
+This is especially useful if you want to persist a conversation callable functions in a database or file.
+Use the `toJSON` method to serialize a conversation callable functions to JSON.
+
+```ts
+const callableFunctions = conversation.callableFunctions;
+const callableFunctionsJson = callableFunctions.toJSON();
+```
+
+You can then deserialize a conversation callable functions from JSON using the `fromJSON` static method.
+
+```ts
+const callableFunctions = ConversationCallableFunctions.fromJSON(callableFunctionsJson);
+
+// ... do some operations on the callableFunctions ...
+
+const conversation = new Conversation({ callableFunctions: callableFunctions.toJSON() });
+```
+
+> The conversation callable functions are automatically serialized/deserialized when serializing a `Conversation`.
+> You should only use these methods if you want to serialize/deserialize only the `ConversationCallableFunctions`.