update docs

docs/docs/tools/improve.md

@@ -98,6 +98,28 @@ the tool can automatically approve the PR when the user checks the self-review c
 
     ![self_review_2](https://codium.ai/images/pr_agent/self_review_2.png){width=512}
 
+### How many code suggestions are generated?
+PR-Agent uses a dynamic strategy to generate code suggestions based on the size of the pull request (PR). Here's how it works:
+
+1. Chunking large PRs:
+
+   - PR-Agent divides large PRs into 'chunks'.
+   - Each chunk contains up to `pr_code_suggestions.max_context_tokens` tokens (default: 14,000).
+
+
+2. Generating suggestions:
+
+   - For each chunk, PR-Agent generates up to `pr_code_suggestions.num_code_suggestions_per_chunk` suggestions (default: 4).
+
+
+This approach has two main benefits:
+
+- Scalability: The number of suggestions scales with the PR size, rather than being fixed.
+- Quality: By processing smaller chunks, the AI can maintain higher quality suggestions, as larger contexts tend to decrease AI performance.
+
+Note: Chunking is primarily relevant for large PRs. For most PRs (up to 500 lines of code), PR-Agent will be able to process the entire code in a single call.
+
+
 ### 'Extra instructions' and 'best practices'
 
 #### Extra instructions
@@ -170,18 +192,10 @@ Using a combination of both can help the AI model to provide relevant and tailor
 ??? example "General options"
     
     <table>
-      <tr>
-        <td><b>num_code_suggestions</b></td>
-        <td>Number of code suggestions provided by the 'improve' tool. Default is 4 for CLI, 0 for auto tools.</td>
-      </tr>
       <tr>
         <td><b>extra_instructions</b></td>
         <td>Optional extra instructions to the tool. For example: "focus on the changes in the file X. Ignore change in ...".</td>
       </tr>
-      <tr>
-        <td><b>rank_suggestions</b></td>
-        <td>If set to true, the tool will rank the suggestions, based on importance. Default is false.</td>
-      </tr>
       <tr>
         <td><b>commitable_code_suggestions</b></td>
         <td>If set to true, the tool will display the suggestions as commitable code comments. Default is false.</td>
@@ -212,29 +226,25 @@ Using a combination of both can help the AI model to provide relevant and tailor
       </tr>
     </table>
 
-??? example "params for 'extended' mode"
+??? example "Params for number of suggestions and AI calls"
 
     <table>
       <tr>
         <td><b>auto_extended_mode</b></td>
-        <td>Enable extended mode automatically (no need for the --extended option). Default is true.</td>
+        <td>Enable chunking the PR code and running the tool on each chunk. Default is true.</td>
       </tr>
       <tr>
         <td><b>num_code_suggestions_per_chunk</b></td>
-        <td>Number of code suggestions provided by the 'improve' tool, per chunk. Default is 5.</td>
+        <td>Number of code suggestions provided by the 'improve' tool, per chunk. Default is 4.</td>
+      </tr>
+      <tr>
+        <td><b>max_number_of_calls</b></td>
+        <td>Maximum number of chunks. Default is 3.</td>
       </tr>
       <tr>
         <td><b>rank_extended_suggestions</b></td>
         <td>If set to true, the tool will rank the suggestions, based on importance. Default is true.</td>
       </tr>
-      <tr>
-        <td><b>max_number_of_calls</b></td>
-        <td>Maximum number of chunks. Default is 5.</td>
-      </tr>
-      <tr>
-        <td><b>final_clip_factor</b></td>
-        <td>Factor to remove suggestions with low confidence. Default is 0.9.</td>
-      </tr>
     </table>
 
 ## A note on code suggestions quality

docs/docs/usage-guide/automations_and_usage.md

@@ -175,10 +175,10 @@ By uploading a local `.pr_agent.toml` file to the root of the repo's main branch
 For example, if your local `.pr_agent.toml` file contains:
 ```
 [pr_reviewer]
-inline_code_comments = true
+extra_instructions = "Answer in japanese"
 ```
 
-Each time you invoke a `/review` tool, it will use inline code comments.
+Each time you invoke a `/review` tool, it will use the extra instructions you set in the local configuration file.
 
 
 Note that among other limitations, BitBucket provides relatively low rate-limits for applications (up to 1000 requests per hour), and does not provide an API to track the actual rate-limit usage.

pr_agent/settings/configuration.toml

@@ -108,7 +108,6 @@ enable_help_text=false
 
 [pr_code_suggestions] # /improve #
 max_context_tokens=14000
-num_code_suggestions=4
 commitable_code_suggestions = false
 extra_instructions = ""
 rank_suggestions = false

pr_agent/tools/pr_code_suggestions.py

@@ -44,10 +44,8 @@ class PRCodeSuggestions:
             self.is_extended = self._get_is_extended(args or [])
         except:
             self.is_extended = False
-        if self.is_extended:
+        num_code_suggestions = get_settings().pr_code_suggestions.num_code_suggestions_per_chunk
-            num_code_suggestions = get_settings().pr_code_suggestions.num_code_suggestions_per_chunk
+
-        else:
-            num_code_suggestions = get_settings().pr_code_suggestions.num_code_suggestions
 
         self.ai_handler = ai_handler()
         self.ai_handler.main_pr_language = self.main_language
@@ -601,7 +599,6 @@ class PRCodeSuggestions:
             if get_settings().pr_code_suggestions.final_clip_factor != 1:
                 max_len = max(
                     len(data_sorted),
-                    get_settings().pr_code_suggestions.num_code_suggestions,
                     get_settings().pr_code_suggestions.num_code_suggestions_per_chunk,
                 )
                 new_len = int(0.5 + max_len * get_settings().pr_code_suggestions.final_clip_factor)