From d21641df5f5dca8ef2f67f4994cd44c2d3b95b66 Mon Sep 17 00:00:00 2001 From: SanduniU Date: Tue, 13 Aug 2024 19:34:58 +0530 Subject: [PATCH] Restructure the quickstart section of the documentation --- README.md | 62 +++++++++++++++++++------------------------- ballerina/Module.md | 62 +++++++++++++++++++------------------------- ballerina/Package.md | 62 +++++++++++++++++++------------------------- 3 files changed, 78 insertions(+), 108 deletions(-) diff --git a/README.md b/README.md index 8d625c4..e09e072 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,6 @@ The `ballarinax/openai.Assistants` connector allows developers to seamlessly int To use the OpenAI Connector, you must have access to the OpenAI API through a [OpenAI Platform account](https://platform.openai.com) and a project under it. If you do not have a OpenAI Platform account, you can sign up for one [here](https://platform.openai.com/signup). -#### Create a OpenAI API Key 1. Open the [OpenAI Platform Dashboard](https://platform.openai.com). @@ -40,42 +39,18 @@ To use the OpenAI Connector, you must have access to the OpenAI API through a [O ## Quickstart -A typical integration of the Assistants API has the following flow: - -1. **Create an Assistant** - - Define its custom instructions and pick a model. - - If helpful, add files and enable tools like Code Interpreter, File Search, and Function calling. - -2. **Create a Thread** - - Create a Thread when a user starts a conversation. - -3. **Add Messages to the Thread** - - Add Messages to the Thread as the user asks questions. - -4. **Run the Assistant** - - Run the Assistant on the Thread to generate a response by calling the model and the tools. - -This starter guide walks through the key steps to create and run an Assistant that uses the Code Interpreter tool. In this example, we're creating an Assistant that is a personal math tutor. -### Setting HTTP Headers in Ballerina - -Calls to the Assistants API require that you pass a beta HTTP header. In Ballerina, you can define the header as follows: - -```ballerina -final map headers = { - "OpenAI-Beta": ["assistants=v2"] -}; -``` - -### Step 1 : Setting up the connector To use the `OpenAI Assistants` connector in your Ballerina application, update the `.bal` file as follows: +### Step 1: Import the module -1. Import the `openai.assistants` module. +Import the `openai.assistants` module. ```ballerina import ballerinax/openai.assistants; ``` -2. Create a `assistants:ConnectionConfig` with the obtained access token and initialize the connector with it. +### Step 2: Instantiate a new connector + +Create a `assistants:ConnectionConfig` with the obtained access token and initialize the connector with it. ```ballerina configurable string token = ?; @@ -87,11 +62,21 @@ final assistants:Client openAIAssistant = check new({ }); ``` -### Step 2: Create an Assistant +#### Setting HTTP Headers in Ballerina -Now, utilize the available connector operations to create an Assistant. +Calls to the Assistants API require that you pass a beta HTTP header. In Ballerina, you can define the header as follows: +```ballerina +final map headers = { + "OpenAI-Beta": ["assistants=v2"] +}; +``` +### Step 3: Invoke the connector operations + +Now, utilize the available connector operations. + +#### Generate an assistant ```ballerina public function main() returns error? { @@ -115,7 +100,7 @@ public function main() returns error? { } ``` -### Step 3: Create a thread +#### Create a thread A Thread represents a conversation between a user and one or many Assistants. You can create a Thread when a user (or your AI application) starts a conversation with your Assistant. @@ -131,7 +116,7 @@ public function main() returns error?{ } ``` -### Step 4: Add a message to the thread +#### Add a message to the thread The contents of the messages your users or applications create are added as Message objects to the Thread. Messages can contain both text and files. There is no limit to the number of Messages you can add to Threads — the context that does not fit into the model's context window will be truncated automatically. @@ -151,8 +136,7 @@ public function main() returns error?{ } ``` - -### Step 5: Create a run +#### Create a run Once all the user Messages have been added to the Thread, you can Run the Thread with any Assistant. Creating a Run uses the model and tools associated with the Assistant to generate a response. These responses are added to the Thread as Assistant Messages. @@ -187,6 +171,12 @@ public function main() returns error?{ } ``` +### Step 4: Run the Ballerina application + +```bash +bal run +``` + ## Examples The `OpenAI Assistants` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/module-ballerinax-openai.assistants/tree/main/examples/), covering the following use cases: diff --git a/ballerina/Module.md b/ballerina/Module.md index 32be54a..ef5a5dd 100644 --- a/ballerina/Module.md +++ b/ballerina/Module.md @@ -29,46 +29,20 @@ To use the OpenAI Connector, you must have access to the OpenAI API through a [O 5. Store the API key securely to use in your application OpenAI Platform - - ## Quickstart -A typical integration of the Assistants API has the following flow: - -1. **Create an Assistant** - - Define its custom instructions and pick a model. - - If helpful, add files and enable tools like Code Interpreter, File Search, and Function calling. - -2. **Create a Thread** - - Create a Thread when a user starts a conversation. - -3. **Add Messages to the Thread** - - Add Messages to the Thread as the user asks questions. - -4. **Run the Assistant** - - Run the Assistant on the Thread to generate a response by calling the model and the tools. - -This starter guide walks through the key steps to create and run an Assistant that uses the Code Interpreter tool. In this example, we're creating an Assistant that is a personal math tutor. -### Setting HTTP Headers in Ballerina - -Calls to the Assistants API require that you pass a beta HTTP header. In Ballerina, you can define the header as follows: - -```ballerina -final map headers = { - "OpenAI-Beta": ["assistants=v2"] -}; -``` - -### Step 1 : Setting up the connector To use the `OpenAI Assistants` connector in your Ballerina application, update the `.bal` file as follows: +### Step 1: Import the module -1. Import the `openai.assistants` module. +Import the `openai.assistants` module. ```ballerina import ballerinax/openai.assistants; ``` -2. Create a `assistants:ConnectionConfig` with the obtained access token and initialize the connector with it. +### Step 2: Instantiate a new connector + +Create a `assistants:ConnectionConfig` with the obtained access token and initialize the connector with it. ```ballerina configurable string token = ?; @@ -80,11 +54,21 @@ final assistants:Client openAIAssistant = check new({ }); ``` -### Step 2: Create an Assistant +#### Setting HTTP Headers in Ballerina + +Calls to the Assistants API require that you pass a beta HTTP header. In Ballerina, you can define the header as follows: + +```ballerina +final map headers = { + "OpenAI-Beta": ["assistants=v2"] +}; +``` -Now, utilize the available connector operations to create an Assistant. +### Step 3: Invoke the connector operations +Now, utilize the available connector operations. +#### Generate an assistant ```ballerina public function main() returns error? { @@ -108,7 +92,7 @@ public function main() returns error? { } ``` -### Step 3: Create a thread +#### Create a thread A Thread represents a conversation between a user and one or many Assistants. You can create a Thread when a user (or your AI application) starts a conversation with your Assistant. @@ -124,7 +108,7 @@ public function main() returns error?{ } ``` -### Step 4: Add a message to the thread +#### Add a message to the thread The contents of the messages your users or applications create are added as Message objects to the Thread. Messages can contain both text and files. There is no limit to the number of Messages you can add to Threads — the context that does not fit into the model's context window will be truncated automatically. @@ -145,7 +129,7 @@ public function main() returns error?{ ``` -### Step 5: Create a run +#### Create a run Once all the user Messages have been added to the Thread, you can Run the Thread with any Assistant. Creating a Run uses the model and tools associated with the Assistant to generate a response. These responses are added to the Thread as Assistant Messages. @@ -180,6 +164,12 @@ public function main() returns error?{ } ``` +### Step 4: Run the Ballerina application + +```bash +bal run +``` + ## Examples The `OpenAI Assistants` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/module-ballerinax-openai-assistants/tree/main/examples/), covering the following use cases: diff --git a/ballerina/Package.md b/ballerina/Package.md index 32be54a..ef5a5dd 100644 --- a/ballerina/Package.md +++ b/ballerina/Package.md @@ -29,46 +29,20 @@ To use the OpenAI Connector, you must have access to the OpenAI API through a [O 5. Store the API key securely to use in your application OpenAI Platform - - ## Quickstart -A typical integration of the Assistants API has the following flow: - -1. **Create an Assistant** - - Define its custom instructions and pick a model. - - If helpful, add files and enable tools like Code Interpreter, File Search, and Function calling. - -2. **Create a Thread** - - Create a Thread when a user starts a conversation. - -3. **Add Messages to the Thread** - - Add Messages to the Thread as the user asks questions. - -4. **Run the Assistant** - - Run the Assistant on the Thread to generate a response by calling the model and the tools. - -This starter guide walks through the key steps to create and run an Assistant that uses the Code Interpreter tool. In this example, we're creating an Assistant that is a personal math tutor. -### Setting HTTP Headers in Ballerina - -Calls to the Assistants API require that you pass a beta HTTP header. In Ballerina, you can define the header as follows: - -```ballerina -final map headers = { - "OpenAI-Beta": ["assistants=v2"] -}; -``` - -### Step 1 : Setting up the connector To use the `OpenAI Assistants` connector in your Ballerina application, update the `.bal` file as follows: +### Step 1: Import the module -1. Import the `openai.assistants` module. +Import the `openai.assistants` module. ```ballerina import ballerinax/openai.assistants; ``` -2. Create a `assistants:ConnectionConfig` with the obtained access token and initialize the connector with it. +### Step 2: Instantiate a new connector + +Create a `assistants:ConnectionConfig` with the obtained access token and initialize the connector with it. ```ballerina configurable string token = ?; @@ -80,11 +54,21 @@ final assistants:Client openAIAssistant = check new({ }); ``` -### Step 2: Create an Assistant +#### Setting HTTP Headers in Ballerina + +Calls to the Assistants API require that you pass a beta HTTP header. In Ballerina, you can define the header as follows: + +```ballerina +final map headers = { + "OpenAI-Beta": ["assistants=v2"] +}; +``` -Now, utilize the available connector operations to create an Assistant. +### Step 3: Invoke the connector operations +Now, utilize the available connector operations. +#### Generate an assistant ```ballerina public function main() returns error? { @@ -108,7 +92,7 @@ public function main() returns error? { } ``` -### Step 3: Create a thread +#### Create a thread A Thread represents a conversation between a user and one or many Assistants. You can create a Thread when a user (or your AI application) starts a conversation with your Assistant. @@ -124,7 +108,7 @@ public function main() returns error?{ } ``` -### Step 4: Add a message to the thread +#### Add a message to the thread The contents of the messages your users or applications create are added as Message objects to the Thread. Messages can contain both text and files. There is no limit to the number of Messages you can add to Threads — the context that does not fit into the model's context window will be truncated automatically. @@ -145,7 +129,7 @@ public function main() returns error?{ ``` -### Step 5: Create a run +#### Create a run Once all the user Messages have been added to the Thread, you can Run the Thread with any Assistant. Creating a Run uses the model and tools associated with the Assistant to generate a response. These responses are added to the Thread as Assistant Messages. @@ -180,6 +164,12 @@ public function main() returns error?{ } ``` +### Step 4: Run the Ballerina application + +```bash +bal run +``` + ## Examples The `OpenAI Assistants` connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/module-ballerinax-openai-assistants/tree/main/examples/), covering the following use cases: