From 54d72f8f573024c3509f1fd4da7281568c27bfb8 Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Wed, 11 Feb 2026 13:33:55 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`camand/?=
 =?UTF-8?q?feat=5Fchoose=5Fsummarize`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Docstrings generation was requested by @camilleAND.

* https://github.com/suitenumerique/conversations/pull/282#issuecomment-3883186168

The following files were modified:

* `src/backend/chat/tools/document_summarize.py`
---
 src/backend/chat/tools/document_summarize.py | 42 ++++++++++----------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/src/backend/chat/tools/document_summarize.py b/src/backend/chat/tools/document_summarize.py
index 7b570322..4b23e6da 100644
--- a/src/backend/chat/tools/document_summarize.py
+++ b/src/backend/chat/tools/document_summarize.py
@@ -58,26 +58,26 @@ async def document_summarize(  # pylint: disable=too-many-locals, too-many-state
     doc_index: int | None = None,
 ) -> ToolReturn:
     """
-    Generate a complete, ready-to-use summary of the documents in context
-    (do not request the documents to the user).
-    Return this summary directly to the user WITHOUT any modification,
-    or additional summarization.
-    The summary is already optimized and MUST be presented as-is in the final response
-    or translated preserving the information.
-
-    Instructions are optional but should reflect the user's request.
-
-    Examples:
-    "Summarize this doc in 2 paragraphs" -> instructions = "summary in 2 paragraphs", doc_index=None
-    "Summarize this doc in English" -> instructions = "In English", doc_index=None
-    "Summarize this doc" -> instructions = "" (default), doc_index=None
-    "Summarize the last document" -> instructions = "", doc_index=-1
-    "Summarize the first document" -> instructions = "", doc_index=0
-
-    Args:
-        instructions (str | None): The instructions the user gave to use for the summarization
-        doc_index (int | None): The index of the document to summarize (e.g. 0 for first, -1 for last).
-                               If None, summarizes all text documents found.
+    Produce a final, user-ready summary for one or more text documents from the conversation.
+    
+    Builds per-chunk summaries for the selected documents, synthesizes them into a single coherent
+    markdown-formatted summary that is intended to be returned to the user verbatim.
+    
+    Parameters:
+        instructions (str | None): Optional user instructions to guide the summary (e.g., length,
+            language, style). When omitted, a default hint is used.
+        doc_index (int | None): If provided, summarize only the document at this index (0-based;
+            negative indices allowed, e.g. -1 for the last document). If `None`, all text documents
+            found in the conversation are summarized.
+    
+    Returns:
+        str: The final synthesized summary formatted in Markdown.
+    
+    Raises:
+        ModelCannotRetry: If no text documents are found in the conversation or on unexpected errors
+            that should stop processing and be reported to the user.
+        ModelRetry: For retryable errors such as an out-of-range `doc_index`, errors during chunk
+            processing, merge-generation failures, or when the summarization produces an empty result.
     """
     try:
         instructions_hint = (
@@ -202,4 +202,4 @@ async def summarize_chunk_with_semaphore(idx, chunk, total_chunks):
         raise ModelCannotRetry(
             f"An unexpected error occurred during document summarization: {type(exc).__name__}. "
             "You must explain this to the user and not try to answer based on your knowledge."
-        ) from exc
+        ) from exc
\ No newline at end of file