Merge pull request #1824 from OSSCA-2025-Egg-Benedict/feature/sequence-diagram

Improve/describe tool documentation and make add_diagram feature opt-in by default

docs/docs/tools/describe.md

@@ -56,6 +56,21 @@ Everything below this marker is treated as previously auto-generated content and
 
 ![Describe comment](https://codium.ai/images/pr_agent/pr_description_user_description.png){width=512}
 
+### Sequence Diagram Support 
+When the `enable_pr_diagram` option is enabled in your configuration, the `/describe` tool will include a `Mermaid` sequence diagram in the PR description.
+
+This diagram represents interactions between components/functions based on the diff content.
+
+### How to enable
+
+In your configuration:
+
+```
+toml
+[pr_description]
+enable_pr_diagram = true
+```
+
 ## Configuration options
 
 !!! example "Possible configurations"
@@ -109,6 +124,10 @@ Everything below this marker is treated as previously auto-generated content and
         <td><b>enable_help_text</b></td>
         <td>If set to true, the tool will display a help text in the comment. Default is false.</td>
       </tr>
+      <tr>
+  <td><b>add_diagram</b></td>
+  <td>If set to true, the tool will generate a <code>Mermaid</code> sequence diagram (in code block format) describing component interactions based on the code changes. Default is false.</td>
+      </tr>
     </table>
 
 ## Inline file summary 💎

pr_agent/settings/configuration.toml

@@ -104,6 +104,7 @@ enable_pr_type=true
 final_update_message = true
 enable_help_text=false
 enable_help_comment=true
+enable_pr_diagram=false # adds a section with a diagram of the PR changes
 # describe as comment
 publish_description_as_comment=false
 publish_description_as_comment_persistent=true

pr_agent/settings/pr_description_prompts.toml

@@ -49,6 +49,9 @@ class PRDescription(BaseModel):
 {%- if enable_semantic_files_types %}
     pr_files: List[FileDescription] = Field(max_items=20, description="a list of all the files that were changed in the PR, and summary of their changes. Each file must be analyzed regardless of change size.")
 {%- endif %}
+{%- if enable_pr_diagram %}
+    changes_diagram: str = Field(description="a horizontal diagram that represents the main PR changes, in the format of a mermaid flowchart. The diagram should be concise and easy to read. Leave empty if no diagram is relevant.")
+{%- endif %}
 =====
 
 
@@ -76,6 +79,12 @@ pr_files:
     label_key_1
 ...
 {%- endif %}
+{%- if enable_pr_diagram %}
+  changes_diagram: |
+    ```mermaid
+    ...
+    ```
+{%- endif %}
 ```
 
 Answer should be a valid YAML, and nothing else. Each YAML output MUST be after a newline, with proper indent, and block scalar indicator ('|')
@@ -157,6 +166,12 @@ pr_files:
     label_key_1
 ...
 {%- endif %}
+{%- if enable_pr_diagram %}
+  changes_diagram: |
+    ```mermaid
+    ...
+    ```
+{%- endif %}
 ```
 (replace '...' with the actual values)
 {%- endif %}
@@ -164,4 +179,4 @@ pr_files:
 
 Response (should be a valid YAML, and nothing else):
 ```yaml
-"""
+"""

pr_agent/tools/pr_description.py

@@ -72,7 +72,8 @@ class PRDescription:
             "enable_semantic_files_types": get_settings().pr_description.enable_semantic_files_types,
             "related_tickets": "",
             "include_file_summary_changes": len(self.git_provider.get_diff_files()) <= self.COLLAPSIBLE_FILE_LIST_THRESHOLD,
-            'duplicate_prompt_examples': get_settings().config.get('duplicate_prompt_examples', False),
+            "duplicate_prompt_examples": get_settings().config.get("duplicate_prompt_examples", False),
+            "enable_pr_diagram": get_settings().pr_description.get("enable_pr_diagram", False),
         }
 
         self.user_description = self.git_provider.get_user_description()
@@ -456,6 +457,10 @@ class PRDescription:
             self.data['labels'] = self.data.pop('labels')
         if 'description' in self.data:
             self.data['description'] = self.data.pop('description')
+        if 'changes_diagram' in self.data:
+            changes_diagram = self.data.pop('changes_diagram')
+            if changes_diagram.strip():
+                self.data['changes_diagram'] = changes_diagram
         if 'pr_files' in self.data:
             self.data['pr_files'] = self.data.pop('pr_files')
 
@@ -820,4 +825,4 @@ def replace_code_tags(text):
     parts = text.split('`')
     for i in range(1, len(parts), 2):
         parts[i] = '<code>' + parts[i] + '</code>'
-    return ''.join(parts)
+    return ''.join(parts)