📝 Add docstrings to camand/feat_choose_summarize

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

@@ -51,26 +51,33 @@ async def summarize_chunk(idx, chunk, total_chunks, summarization_agent, ctx):
 
 
 @last_model_retry_soft_fail
-async def document_summarize(  # pylint: disable=too-many-locals
-    ctx: RunContext, *, instructions: str | None = None
+async def document_summarize(  # pylint: disable=too-many-locals, too-many-statements
+    ctx: RunContext,
+    *,
+    instructions: str | None = None,
+    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"
-    "Summarize this doc in English" -> instructions = "In English"
-    "Summarize this doc" -> instructions = "" (default)
-
-    Args:
-        instructions (str | None): The instructions the user gave to use for the summarization
+    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 = (
@@ -91,6 +98,15 @@ async def document_summarize(  # pylint: disable=too-many-locals
                 "You must explain this to the user and ask them to provide documents."
             )
 
+        if doc_index is not None:
+            try:
+                text_attachment = [text_attachment[doc_index]]
+            except IndexError as exc:
+                raise ModelRetry(
+                    f"Document index {doc_index} is out of range. "
+                    f"There are {len(text_attachment)} documents available."
+                ) from exc
+
         documents = [await read_document_content(doc) for doc in text_attachment]
 
         # Chunk documents and summarize each chunk
@@ -186,4 +202,4 @@ async def document_summarize(  # pylint: disable=too-many-locals
         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