tools guide

README.md

@@ -17,20 +17,22 @@ Making pull requests less painful with an AI agent
 
 CodiumAI `PR-Agent` is an open-source tool aiming to help developers review pull requests faster and more efficiently. It automatically analyzes the pull request and can provide several types of commands:
 
-‣ **Auto Description (`/describe`)**: Automatically generating [PR description](https://github.com/Codium-ai/pr-agent/pull/229#issue-1860711415) - title, type, summary, code walkthrough and labels.
+‣ **Auto Description ([`/describe`](./docs/DESCRIBE.md))**: Automatically generating PR description - title, type, summary, code walkthrough and labels.
 \
-‣ **Auto Review (`/review`)**: [Adjustable feedback](https://github.com/Codium-ai/pr-agent/pull/229#issuecomment-1695022908) about the PR main theme, type, relevant tests, security issues, score, and various suggestions for the PR content.
+‣ **Auto Review ([`/review`](./docs/REVIEW.md))**: Adjustable feedback about the PR main theme, type, relevant tests, security issues, score, and various suggestions for the PR content.
 \
-‣ **Question Answering (`/ask ...`)**: Answering [free-text questions](https://github.com/Codium-ai/pr-agent/pull/229#issuecomment-1695021332) about the PR.
+‣ **Question Answering ([`/ask ...`](./docs/ASK.md))**: Answering free-text questions about the PR.
 \
-‣ **Code Suggestions (`/improve`)**: [Committable code suggestions](https://github.com/Codium-ai/pr-agent/pull/229#discussion_r1306919276) for improving the PR.
+‣ **Code Suggestions ([`/improve`](./docs/IMPROVE.md))**: Committable code suggestions for improving the PR.
 \
-‣ **Update Changelog (`/update_changelog`)**: Automatically updating the CHANGELOG.md file with the [PR changes](https://github.com/Codium-ai/pr-agent/pull/168#discussion_r1282077645).
+‣ **Update Changelog ([`/update_changelog`](./docs/UPDATE_CHANGELOG.md))**: Automatically updating the CHANGELOG.md file with the PR changes.
 \
-‣ **Find similar issue (`/similar_issue`)**: Automatically retrieves and presents [similar issues](https://github.com/Alibaba-MIIL/ASL/issues/107).
+‣ **Find similar issue ([`/similar_issue`](./docs/SIMILAR_ISSUE.md))**: Automatically retrieves and presents similar issues
 
 
-See the [usage guide](./Usage.md) for instructions how to run the different tools from [CLI](./Usage.md#working-from-a-local-repo-cli), or by [online usage](./Usage.md#online-usage), as well as additional details on optional commands and configurations.
+See the [Usage Guide](./Usage.md) for instructions how to run the different tools from _CLI_, _online usage_, Or by _automatically triggering_ them when a new PR is opened.
+
+See the [Tools Guide](./docs/TOOLS_GUIDE.md) for detailed description of the different tools.
 
 [Release notes](./RELEASE_NOTES.md)
 

Usage.md

@@ -1,4 +1,4 @@
-## Usage guide
+## Usage Guide
 
 ### Table of Contents
 - [Introduction](#introduction)
@@ -261,26 +261,4 @@ And use the following settings (you have to replace the values) in .secrets.toml
 [azure_devops]
 org = "https://dev.azure.com/YOUR_ORGANIZATION/"
 pat = "YOUR_PAT_TOKEN"
-```
-
-#### Similar issue tool
-
-[Example usage](https://github.com/Alibaba-MIIL/ASL/issues/107)
-
-<img src=./pics/similar_issue_tool.png width="768">
-
-To enable usage of the '**similar issue**' tool, you need to set the following keys in `.secrets.toml` (or in the relevant environment variables):
-```
-[pinecone]
-api_key = "..."
-environment = "..."
-```
-These parameters can be obtained by registering to [Pinecone](https://app.pinecone.io/?sessionType=signup/).
-
-- To invoke the 'similar issue' tool from **CLI**, run:
-`python3 cli.py --issue_url=... similar_issue`
-
-- To invoke the 'similar' issue tool via online usage, [comment](https://github.com/Codium-ai/pr-agent/issues/178#issuecomment-1716934893) on a PR:
-`/similar_issue`
-
-- You can also enable the 'similar issue' tool to run automatically when a new issue is opened, by adding it to the [pr_commands list in the github_app section](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L66)
+```

docs/ASK.md

@@ -0,0 +1,11 @@
+# ASK Tool
+
+The `ask` tool answers questions about the PR, based on the PR code changes.
+It can be invoked manually by commenting on any PR:
+```
+/ask "..."
+```
+For example:
+
+<kbd><img src=./../pics/ask_comment.png width="768"></kbd>
+<kbd><img src=./../pics/ask.png width="768"></kbd>

docs/DESCRIBE.md

@@ -0,0 +1,50 @@
+# Describe Tool
+
+The `describe` tool scans the PR code changes, and automatically generates PR description - title, type, summary, code walkthrough and labels.
+It can ba invoked manually by commenting on any PR:
+```
+/describe
+```
+For example:
+
+<kbd><img src=./../pics/describe_comment.png width="768"></kbd>
+
+<kbd><img src=./../pics/describe.png width="768"></kbd>
+
+The `describe` tool can also be triggered automatically every time a new PR is opened. See examples for automatic triggers for [GitHub App](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools) and [GitHub Action](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#working-with-github-action)
+
+### Configuration options
+
+Under the section 'pr_description', the [configuration file](./../pr_agent/settings/configuration.toml#L28) contains options to customize the 'describe' tool:
+
+- `publish_labels`: if set to true, the tool will publish the labels to the PR. Default is true.
+
+- `publish_description_as_comment`: if set to true, the tool will publish the description as a comment to the PR. If false, it will overwrite the origianl description. Default is false.
+
+- `add_original_user_description`: if set to true, the tool will add the original user description to the generated description. Default is false.
+
+- `add_original_user_title`: if set to true, the tool will keep the original PR title, and won't change it. Default is false.
+
+- `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...".
+
+#### Markers template
+
+markers template enable to easily integrate user's content and auto-generated content.
+
+- `use_description_markers`: if set to true, the tool will use markers template. It replaces every marker of the form `pr_agent:marker_name` with the relevant content. Default is false.
+For example, if the PR original description was:
+```
+User content...
+
+## PR Type:
+pr_agent:pr_type
+
+## PR Description:
+pr_agent:summary
+
+## PR Walkthrough:
+pr_agent:walkthrough
+```
+The marker `pr_agent:pr_type` will be replaced with the PR type, `pr_agent:summary` will be replaced with the PR summary, and `pr_agent:walkthrough` will be replaced with the PR walkthrough.
+
+- `include_generated_by_header`: if set to true, the tool will add a dedicated header: 'Generated by PR Agent at ...' to any automatic content. Default is true.

docs/IMPROVE.md

@@ -0,0 +1,34 @@
+# Describe Tool
+
+The `improve` tool scans the PR code changes, and automatically generate committable suggestions for improving the PR code.
+It can be invoked manually by commenting on any PR:
+```
+/improve
+```
+For example:
+
+<kbd><img src=./../pics/improve_comment.png width="768"></kbd>
+<kbd><img src=./../pics/improve.png width="768"></kbd>
+
+The `improve` tool can also be triggered automatically every time a new PR is opened. See examples for automatic triggers for [GitHub App](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools) and [GitHub Action](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#working-with-github-action)
+
+An extended mode, which does not involve PR Compression and provides more comprehensive suggestions, can be invoked by commenting on any PR:
+```
+/improve --extended
+```
+Note that the extended mode divides the PR code changes into chunks, up to the token limits, where each chunk is handled separately (multiple calls to GPT-4).
+Hence, the total number of suggestions is proportional to the number of chunks, i.e. the size of the PR.
+
+### Configuration options
+
+Under the section 'pr_code_suggestions', the [configuration file](./../pr_agent/settings/configuration.toml#L40) contains options to customize the 'improve' tool:
+
+- `num_code_suggestions`: number of code suggestions provided by the 'improve' tool. Default is 4.
+- `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...".
+- `rank_suggestions`: if set to true, the tool will rank the suggestions, based on importance. Default is false.
+
+#### params for '/improve --extended' mode
+- `num_code_suggestions_per_chunk`: number of code suggestions provided by the 'improve' tool, per chunk. Default is 8.
+- `rank_extended_suggestions`: if set to true, the tool will rank the suggestions, based on importance. Default is true.
+- `max_number_of_calls`: maximum number of chunks. Default is 5.
+- `final_clip_factor`: factor to remove suggestions with low confidence. Default is 0.9.

docs/REVIEW.md

@@ -0,0 +1,38 @@
+# Describe Tool
+
+The `review` tool scans the PR code changes, and automatically generates a PR review.
+It can ba invoked manually by commenting on any PR:
+```
+/review
+```
+For example:
+
+<kbd><img src=./../pics/review_comment.png width="768"></kbd>
+<kbd><img src=./../pics/describe.png width="768"></kbd>
+
+The `review` tool can also be triggered automatically every time a new PR is opened. See examples for automatic triggers for [GitHub App](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#github-app-automatic-tools) and [GitHub Action](https://github.com/Codium-ai/pr-agent/blob/main/Usage.md#working-with-github-action)
+
+### Configuration options
+
+Under the section 'pr_reviewer', the [configuration file](./../pr_agent/settings/configuration.toml#L16) contains options to customize the 'review' tool:
+
+- `require_focused_review`: if set to true, the tool will add a section - 'is the PR a focused one'. Default is false.
+- `require_score_review`: if set to true, the tool will add a section that scores the PR. Default is false.
+- `require_tests_review`: if set to true, the tool will add a section that checks if the PR contains tests. Default is true.
+- `require_security_review`: if set to true, the tool will add a section that checks if the PR contains security issues. Default is true.
+- `require_estimate_effort_to_review`: if set to true, the tool will add a section that estimates thed effort needed to review the PR. Default is true.
+- `num_code_suggestions`: number of code suggestions provided by the 'review' tool. Default is 4.
+- `inline_code_comments`: if set to true, the tool will publish the code suggestions as comments on the code diff. Default is false.
+- `automatic_review`: if set to false, no automatic reviews will be done. Default is true.
+- `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...".
+
+#### PR Reflection
+By invoking:
+```
+/reflect_and_review
+```
+The module will first ask the author questions about the PR, and will guide the review based on his answers.
+
+<kbd><img src=./../pics/reflection_questions.png width="768"></kbd>
+<kbd><img src=./../pics/reflection_answers.png width="768"></kbd>
+<kbd><img src=./../pics/reflection_insights.png width="768"></kbd>

docs/SIMILAR_ISSUE.md

@@ -0,0 +1,31 @@
+# Similar Issue Tool
+The similar issue tool retrieves the most similar issues to the current issue.
+It can ba invoked manually by commenting on any PR:
+```
+/similar_issue
+```
+For example:
+
+<kbd><img src=./../pics/similar_issue_original_issue.png width="768"></kbd>
+<kbd><img src=./../pics/similar_issue_comment.png width="768"></kbd>
+<kbd><img src=./../pics/similar_issue.png width="768"></kbd>
+
+Note that to perform retrieval, the `similar_issue` tool indexes all the repo previous issues (once).
+
+To enable usage of the '**similar issue**' tool, you need to set the following keys in `.secrets.toml` (or in the relevant environment variables):
+```
+[pinecone]
+api_key = "..."
+environment = "..."
+```
+These parameters can be obtained by registering to [Pinecone](https://app.pinecone.io/?sessionType=signup/).
+
+
+### How to use:
+- To invoke the 'similar issue' tool from **CLI**, run:
+`python3 cli.py --issue_url=... similar_issue`
+
+- To invoke the 'similar' issue tool via online usage, [comment](https://github.com/Codium-ai/pr-agent/issues/178#issuecomment-1716934893) on a PR:
+`/similar_issue`
+
+- You can also enable the 'similar issue' tool to run automatically when a new issue is opened, by adding it to the [pr_commands list in the github_app section](https://github.com/Codium-ai/pr-agent/blob/main/pr_agent/settings/configuration.toml#L66)

docs/TOOLS_GUIDE.md

@@ -0,0 +1,7 @@
+## Tools Guide
+- [DESCRIBE](./DESCRIBE.md)
+- [REVIEW](./REVIEW.md)
+- [IMPROVE](./IMPROVE.md)
+- [ASK](./ASK.md)
+- [SIMILAR_ISSUE](./SIMILAR_ISSUE.md)
+- [UPDATE CHANGELOG](./UPDATE_CHANGELOG.md)

docs/UPDATE_CHANGELOG.md

@@ -0,0 +1,19 @@
+# Update Changelog Tool
+
+The `update_changelog` tool automatically updates the CHANGELOG.md file with the PR changes.
+It can be invoked manually by commenting on any PR:
+```
+/update_changelog
+```
+For example:
+
+<kbd><img src=./../pics/update_changelog_comment.png width="768"></kbd>
+<kbd><img src=./../pics/update_changelog.png width="768"></kbd>
+
+
+### Configuration options
+
+Under the section 'pr_update_changelog', the [configuration file](./../pr_agent/settings/configuration.toml#L50) contains options to customize the 'update changelog' tool:
+
+- `push_changelog_changes`: whether to push the changes to changelog changes, or just print them. Default is false (print only).
+- `extra_instructions`: Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...

pr_agent/agent/pr_agent.py

@@ -67,8 +67,8 @@ class PRAgent:
         args = update_settings_from_args(args)
 
         action = action.lstrip("/").lower()
-        if action == "reflect_and_review" and not get_settings().pr_reviewer.ask_and_reflect:
-            action = "review"
+        if action == "reflect_and_review":
+            get_settings().pr_reviewer.ask_and_reflect = True
         if action == "answer":
             if notify:
                 notify()