linear-b · azigler · Jan 8, 2025 · Jan 8, 2025 · Jan 8, 2025 · Jan 8, 2025
diff --git a/docs/automations/integrations/askAI/add-tests/README.md b/docs/automations/integrations/askAI/add-tests/README.md
@@ -1,24 +1,24 @@
 ---
-title: Automation - Ask AI to Suggest Tests
-description: Use gitStream's integration with AI services to suggests additional tests
+title: Automation - Ask AI to Generate Unit Tests
+description: Use gitStream's integration with AI services to recommend tests for the changes in the PR.
 category: [quality, genai, copilot, tests, efficiency]
 starter_kits: [genai]
 ---
-# Ask AI to Suggest Tests
+# Ask AI to Generate Unit Tests
 
 <!-- --8<-- [start:example]-->
-Use AI to suggests additional test cases for uncovered or modified functions in the PR, including edge cases.
+Use AI to recommend unit tests for the changes in a PR.
 
 !!! info "Configuration Description"
 
     Conditions (all must be true):
 
     * A PR is created or new code has been committed to the PR.
-    * The PR has a label "askai tests"
+    * The PR has a label `askai tests`.
 
     Automation Actions:
 
-    * Add a comment with suggested tests generated by an AI model
+    * Add a comment with AI-generated tests recommendations for the PR.
 
 !!! example "Configuration Example"
     ```yaml+jinja

diff --git a/docs/automations/integrations/askAI/code-review/README.md b/docs/automations/integrations/askAI/code-review/README.md
@@ -1,24 +1,24 @@
 ---
-title: Automation - Ask AI for a Code Review
-description: Use gitStream's integration with AI services to perform a comprehensive code review to your code
+title: Automation - Ask AI for a PR Review Checklist
+description: Use gitStream's integration with AI services to perform a initial code review for a PR.
 category: [quickstart, quality, genai, copilot, tests, efficiency]
 starter_kits: [genai]
 ---
-# Ask AI for a Code Review
+# Ask AI for a PR Review Checklist
 
 <!-- --8<-- [start:example]-->
-Use AI to perform a comprehensive code review, identify bugs, security risks, performance issues, deprecated methods, and style guide violations, and suggests improvements.
+Use AI to generate an initial code review checklist, identify bugs, security risks, performance issues, deprecated methods, and style guide violations, and suggests improvements. The automation provides insights and recommended next actions for a human reviewer.
 
 !!! info "Configuration Description"
 
     Conditions (all must be true):
 
     * A PR is created or new code has been committed to the PR.
-    * The PR has a label "askai cr"
+    * The PR has a label `askai cr`.
 
     Automation Actions:
 
-    * Add a comment with a code review generated by an AI model
+    * Add a comment with an AI-generated code review checklist for the PR.
 
 !!! example "Configuration Example"
     ```yaml+jinja

diff --git a/docs/automations/integrations/askAI/document/README.md b/docs/automations/integrations/askAI/document/README.md
@@ -1,23 +1,24 @@
 ---
-title: Automation - Ask AI to provide PR documentation
-description: Use gitStream's integration with AI services to generate conscious documentation of the changes in the PR.
+title: Automation - Ask AI to Generate Documentation
+description: Use gitStream's integration with AI services to recommend documentation for the changes in the PR.
 category: [quality, genai, copilot, tests, efficiency]
+starter_kits: [genai]
 ---
-# Ask AI to provide PR documentation
+# Ask AI to Generate Documentation
 
 <!-- --8<-- [start:example]-->
-Use AI to generate documentation for the newly added features and changes based on the code diff.
+Use AI to recommend new or updated documentation for changes in a PR, focusing on functionality, parameters, and expected behavior.
 
 !!! info "Configuration Description"
 
     Conditions (all must be true):
 
-    * A PR is created, or new code has been committed to the PR.
-    * The PR has a label "askai document"
+    * A PR is created or new code has been committed to the PR.
+    * The PR has a label `askai document`.
 
     Automation Actions:
 
-    * Add a comment with a summary of the PR
+    * Add a comment with AI-generated documentation recommendations for the PR.
 
 !!! example "Configuration Example"
     ```yaml+jinja

diff --git a/docs/automations/integrations/askAI/improve/README.md b/docs/automations/integrations/askAI/improve/README.md
@@ -1,23 +1,25 @@
 ---
-title: Automation - Ask AI for code suggestions to improve the PR
-description: Use gitStream's integration with AI services to generate code suggestions to improve the PR.
+title: Automation - Ask AI for PR Improvements
+description: Use gitStream's integration with AI services to recommend improvements to a PR.
 category: [quality, genai, copilot, tests, efficiency]
+starter_kits: [genai]
 ---
-# Ask AI to provide code suggestions to improve the PR
+
+# Ask AI for PR Improvements
 
 <!-- --8<-- [start:example]-->
-Use AI to generate suggestions for improvement in the code changes.
+Use AI to recommend improvements to a PR that enhance readability, performance, security, and maintainability.
 
 !!! info "Configuration Description"
 
     Conditions (all must be true):
 
-    * A PR is created, or a new code has been committed to the PR.
-    * The PR has a label "askai improve"
+    * A PR is created or new code has been committed to the PR.
+    * The PR has a label `askai improve`.
 
     Automation Actions:
 
-    * Add a comment with improvement suggestions for the added code
+    * Add a comment with AI-generated improvement suggestions for the PR.
 
 !!! example "Configuration Example"
     ```yaml+jinja

diff --git a/docs/automations/integrations/askAI/summarize-pr/README.md b/docs/automations/integrations/askAI/summarize-pr/README.md
@@ -1,12 +1,12 @@
 ---
-title: Automation - Ask AI to Summarize the Changes in a PR
-description: Use gitStream's integration with AI services to generate a summary of the changes in the PR.
+title: Automation - Ask AI to Summarize a PR
+description: Use gitStream's integration with AI services to generate a concise bullet-point summary of a PR.
 category: [quality, genai, copilot, tests, efficiency]
 ---
-# Ask AI to Summarize the Changes in a PR
+# Ask AI to Summarize a PR
 
 <!-- --8<-- [start:example]-->
-Use AI to generate a concise bullet-point summary of the changes in the pull request.
+Use AI to generate a concise bullet-point summary of changes in a PR.
 
 ![summarized-pr](/automations/integrations/askAI/summarize-pr/summarized-pr.png)
 
@@ -15,11 +15,11 @@ Use AI to generate a concise bullet-point summary of the changes in the pull req
     Conditions (all must be true):
 
     * A PR is created or new code has been committed to the PR.
-    * The PR has a label "askai summarize"
+    * The PR has a label `askai summarize`.
 
     Automation Actions:
 
-    * Add a comment with a summary of the PR
+    * Add a comment with an AI-generated summary of the PR.
 
 !!! example "Configuration Example"
     ```yaml+jinja

diff --git a/docs/downloads/automation-library/integrations/askAI/askAI_CR.cm b/docs/downloads/automation-library/integrations/askAI/askAI_CR.cm
@@ -14,9 +14,11 @@ automations:
       - action: add-comment@v1
         args:
           comment: |
-            # ✨ gitStream Review ✨
-            {{ source | askAI("Code reviewer",
+            ## gitStream askAI: code review checklist for this PR ✨
+            {{ source | askAI("experienced software developer focused on code reviews",
               "Review the PR code diff.
-              - Identify bugs, security risks, and performance issues
-              - Check for deprecated methods and style guide violations
-              - Provide specific improvement suggestions based on the changes", env.OPEN_AI_TOKEN) }}
+              - Identify bugs, security risks, and performance issues.
+              - Check for deprecated methods and style guide violations.
+              - Suggest specific improvements based on the changes.
+              - Provide a code review checklist that can be utilized by a human reviewer.", env.OPEN_AI_TOKEN) }}
+            _This response was generated by the gitStream askAI plugin._
diff --git a/docs/downloads/automation-library/integrations/askAI/askAI_document.cm b/docs/downloads/automation-library/integrations/askAI/askAI_document.cm
@@ -14,8 +14,10 @@ automations:
       - action: add-comment@v1
         args:
           comment: |
-            # 🧪 Test Suggestions 🧪
-            {{ source | askAI("Technical writer",
-              "Review the code diff and generate documentation for any newly added features or significant changes. 
-              Focus on describing functionality, parameters, and expected behavior. 
-              Format the output in clear, concise bullet points or paragraphs.", env.OPEN_AI_TOKEN) }}
+            ## gitStream askAI: recommended documentation for this PR 📑
+            {{ source | askAI("experienced technical writer focused on documentation",
+              "Review the PR code diff.
+              - Generate documentation for any newly added features or significant changes. 
+              - Focus on describing functionality, parameters, and expected behavior. 
+              - Format the output in clear, concise bullet points or paragraphs.", env.OPEN_AI_TOKEN) }}
+            _This response was generated by the gitStream askAI plugin._
diff --git a/docs/downloads/automation-library/integrations/askAI/askAI_improve.cm b/docs/downloads/automation-library/integrations/askAI/askAI_improve.cm
@@ -14,7 +14,9 @@ automations:
       - action: add-comment@v1
         args:
           comment: |
-            # 🧪 Test Suggestions 🧪
-            {{ source | askAI("Experienced developer",
-              "Review the code diff and suggest improvements to enhance readability, performance, and maintainability. 
-              Focus only on the modified code and provide specific, actionable recommendations.", env.OPEN_AI_TOKEN) }}
+            ## gitStream askAI: recommended improvements for this PR 🔨
+            {{ source | askAI("experienced software developer focused on code reviews",
+              "Review the PR code diff.
+              - Suggest improvements to enhance readability, performance, security, and maintainability. 
+              - Focus only on the modified code and provide specific, actionable recommendations.", env.OPEN_AI_TOKEN) }}
+            _This response was generated by the gitStream askAI plugin._
diff --git a/docs/downloads/automation-library/integrations/askAI/askAI_summarize.cm b/docs/downloads/automation-library/integrations/askAI/askAI_summarize.cm
@@ -14,6 +14,7 @@ automations:
       - action: add-comment@v1
         args:
           comment: |
-            # 📜 PR Summary 📜
-            {{ source | askAI("Experienced developer",
-              "Summarize the changes in this PR in bullet points.", env.OPEN_AI_TOKEN) }}
+            ## gitStream askAI: summary for this PR 📜
+            {{ source | askAI("experienced software developer focused on code reviews",
+              "Review the PR code diff.
+              - Summarize the changes in the PR in an unordered list.", env.OPEN_AI_TOKEN) }}
diff --git a/docs/downloads/automation-library/integrations/askAI/askAI_tests.cm b/docs/downloads/automation-library/integrations/askAI/askAI_tests.cm
@@ -14,8 +14,10 @@ automations:
       - action: add-comment@v1
         args:
           comment: |
-            # 🧪 Test Suggestions 🧪
-            {{ source | askAI("QA tester",
-              "Identify any new or modified functions without test coverage in this PR.
-              Suggest specific test cases to add, including edge cases.
-              If all functions are covered, return 'No additional tests needed.'", env.OPEN_AI_TOKEN) }}
+            ## gitStream askAI: recommended tests for this PR 🧪
+            {{ source | askAI("experienced software developer focused on QA testing",
+              "Review the PR code diff.
+              - Identify any new or modified functions without test coverage.
+              - Suggest specific test cases to add, including edge cases.
+              - If all functions are covered, return 'No additional tests needed.'", env.OPEN_AI_TOKEN) }}
+            _This response was generated by the gitStream askAI plugin._
diff --git a/docs/faq.md b/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. By default, only metadata related to and affecting the workflow is shared to allow rule-based automation on the repo. 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 -*-

diff --git a/docs/integrations/askAI.md b/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.
+    These examples 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 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 for a PR Review Checklist
 
 --8<-- "docs/automations/integrations/askAI/code-review/README.md:example"
 
-## Ask AI for Documentation
+## Ask AI for PR Improvements
 
---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 to Generate Documentation
 
---8<-- "docs/automations/integrations/askAI/improve/README.md:example"
+--8<-- "docs/automations/integrations/askAI/document/README.md:example"
 
-<!-- ## Ask AI for anything
+## Ask AI to Generate Tests
 
---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"
diff --git a/plugins/filters/askAI/index.js b/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 {string} 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
  * */
 

diff --git a/plugins/filters/askAI/reference.md b/plugins/filters/askAI/reference.md
@@ -1,6 +1,7 @@
 <a name="module_generateDescription"></a>
 
 ## askAI
+
 The AskAI plugin allows gitStream workflows to interact with external AI services, enabling advanced automation capabilities such as code analysis, test case generation, and PR summarization. This plugin requires a valid API token for the AI service, which must be securely provided as an environment variable.
 
 !!! note "Security note"
@@ -15,14 +16,13 @@ The AskAI plugin allows gitStream workflows to interact with external AI service
 
 | 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**
-    
+
 ```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) }}
 ```