📝 docs: improve askAI plugin documentation

docs/faq.md

@@ -14,11 +14,12 @@ Choose which repositories are permitted to use GitHub Actions.
 
 [x] Allow all actions and reusable workflows
 
-## Does gitStream services have access to my code?
+## Does gitStream have access to my code?
 
-Like any other CI/CD automation, the source code is being scanned in the repo and is not shared with any external services. Only metadata related to and affecting the workflow is shared to allow rule-based automation on the repo.
+Like any other CI/CD automation, the source code is being scanned in the repo and is not shared with any external services. Only metadata related to and affecting the workflow is shared to allow rule-based automation on the repo. An exception to this is when you configure your own gitStream plugins that may connect to other services, such as using the [`askAI`](/filter-function-plugins/#askai) plugin, which will provide context to the configured model provider.
 
 ## Why does gitStream require permission to write code?
+
 To support automations that either Approve or Merge PRs, the git providers require code write scope.
 
 ## What repos are supported?
@@ -34,7 +35,7 @@ Yes. When a merge queue is used, and gitStream is set as a required check, gitSt
 
 The `.cm` file uses YAML with JINJA2. For your favorite editor to automatically choose the right syntax, you can use modelines.
 
-Add the following line to the top of the `.cm` file (the default has it already): 
+Add the following line to the top of the `.cm` file (the default has it already):
 
 ```
 # -*- mode: yaml -*-

docs/integrations/askAI.md

@@ -1,43 +1,39 @@
 ---
 title: Integrate gitStream with AI
-description: Use gitStream to integrate with AI services for Review, describe and add tests.
+description: Use gitStream to integrate with AI for different use cases.
 category: [quality, genai, copilot, tests, efficiency]
 ---
 # Integrate gitStream with AI
 
 <!-- --8<-- [start:examples]-->
 !!! warning "Required gitStream Plugins"
-    This example requires you to install the [`askAI`](/filter-function-plugins/#askai) plugin.
+    This example requires you to install the [`askAI`](/filter-function-plugins/#askai) plugin, which will provide context to the configured model provider and may incur API costs.
 
     [Learn more about gitStream plugins](/plugins/).
 
-## Ask AI to Summarize the Changes in a PR
+## Ask AI to summarize the changes in a PR
 
 --8<-- "docs/automations/integrations/askAI/summarize-pr/README.md:example"
 
-## Ask AI to Suggest Tests
-
---8<-- "docs/automations/integrations/askAI/add-tests/README.md:example"
-
-## Ask AI for a Code Review
+## Ask AI to review the changes in a PR
 
 --8<-- "docs/automations/integrations/askAI/code-review/README.md:example"
 
-## Ask AI for Documentation
+## Ask AI for improvements to the changes in a PR
 
---8<-- "docs/automations/integrations/askAI/document/README.md:example"
+--8<-- "docs/automations/integrations/askAI/improve/README.md:example"
 
-## Ask AI for Code Improvements
+## Ask AI for documentation covering the changes in a PR
 
---8<-- "docs/automations/integrations/askAI/improve/README.md:example"
+--8<-- "docs/automations/integrations/askAI/document/README.md:example"
 
-<!-- ## Ask AI for anything
+## Ask AI for tests covering the changes in a PR
 
---8<-- "docs/automations/integrations/askAI/code-review/README.md:example" -->
+--8<-- "docs/automations/integrations/askAI/add-tests/README.md:example"
 <!-- --8<-- [end:examples]-->
 
 ## Additional Resources
 
 --8<-- "docs/snippets/general.md"
 
---8<-- "docs/snippets/automation-footer.md"
+--8<-- "docs/snippets/automation-footer.md"

plugins/filters/askAI/index.js

@@ -1,12 +1,12 @@
 /**
  * @module askAI
- * @description A gitStream plugin to interact with AI models. Currently works with `ChatGPR-4o-mini`.
- * @param {Object} context - The context that will be attached to the prompt .
- * @param {string} role - Role instructions for the conversation.
- * @param {string} prompt - The prompt string.
- * @param {Object} token - The token to the AI model.
- * @returns {Object} Returns the response from the AI model.
- * @example {{ branch | generateDescription(pr, repo, source) }}
+ * @description A gitStream plugin to facilitate AI workflows with OpenAI's `gpt-4o-2024-08-06` model.
+ * @param {Object} context - The context to be sent to the AI model with the prompt.
+ * @param {string} role - The system role or persona for the AI to adopt while generating the response.
+ * @param {string} prompt - The specific request or question you want the AI to respond to, after the context has been provided.
+ * @param {Object} token - Your OpenAI API token.
+ * @returns {Object} Returns the AI-generated response based on the provided context and prompt.
+ * @example {{ source | askAI("Experienced developer", "Summarize the changes in this PR in bullet points.", env.OPEN_AI_TOKEN) }}
  * @license MIT
  * */
 

plugins/filters/askAI/reference.md

@@ -1,26 +1,26 @@
 <a name="module_generateDescription"></a>
 
 ## askAI
-A gitStream plugin to interact with AI models. Currently works with `ChatGPR-4o-mini`
 
-![Example PR description](screenshots/askAI-describe-PR.png)
+!!! warning "Data privacy"
+    The [`askAI`](/filter-function-plugins/#askai) plugin will provide context to the configured model provider and may incur API costs.
+
+    [Learn more about gitStream plugins](/plugins/).
+
+A gitStream plugin to facilitate AI workflows with OpenAI's `gpt-4o-2024-08-06` model.
 
 **Returns**: <code>Object</code> -  Returns the AI-generated response based on the provided context and prompt.
 **License**: MIT
 
 | Param   | Type     | Description                                                                                                        |
 | ------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
-| context | `Object` | The context that needs to be sent to the AI model for analysis.                                                    |
-| role    | `string` |  Free text. If not empty, Defines the role or persona for the AI to adopt while generating the response.           |
+| context | `Object` | The context to be sent to the AI model with the prompt.                                                            |
+| role    | `string` | The system role or persona for the AI to adopt while generating the response.                                      |
 | prompt  | `string` | The specific request or question you want the AI to respond to, after the context has been provided.               |
-| token   | `Object` | The token to the AI model                                                                                          |
-
+| token   | `string` | Your OpenAI API token.                                                                                             |
 
 **Example**
-!!! tip "Encoding output"
-    The output of AI models may be lengthy, which might cause issues when setting the comment. We recommend using the [`encode`](./filter-functions.md#encode) filter function, as shown in the example, to ensure that the comment is passed fully.
-    The [`add-comment`](./automation-actions.md#add-comment) action automatically decodes encoded strings.
-
+
 ```yaml
-{{ source | askAI("QA tester", "Based on the given context, search for new functions without tests and suggest the tests to add. If all functions are covered completely, return 'no tests to suggest.'", env.OPEN_AI_TOKEN) }}
+{{ {{ source | askAI("Experienced developer", "Summarize the changes in this PR in bullet points.", env.OPEN_AI_TOKEN) }} }}
 ```