universal-mcp-applications 0.1.12__tar.gz → 0.1.14__tar.gz

universal_mcp_applications-0.1.14/GEMINI.md

@@ -0,0 +1,125 @@
+# Agent.md — Python + uv
+
+Purpose
+- This repository uses Python managed by uv for dependency resolution, virtual environments, locking, and execution. Always prefer uv subcommands (add/remove/run/sync/export) over raw pip/venv commands.
+
+Core rules
+- Use `uv add` to add or upgrade dependencies so that both `pyproject.toml` and `uv.lock` stay in sync; do not use `pip install` directly.
+- Keep runtime dependencies in `[project.dependencies]` and development-only tools in the `dev` group via `uv add --dev ...`.
+- Use `uv run` to execute Python, test, and tooling commands without manually activating a virtual environment.
+
+Project bootstrap
+- New project (scaffold files): `uv init`
+- First install or clean install: `uv sync`
+- Run the app: `uv run python -m <your_module>` or `uv run main.py`
+- REPL: `uv run python`
+- Scripts in pyproject: prefer `uv run <command>` to ensure the correct environment is used
+
+Managing dependencies
+- Add runtime dependency: `uv add <name>` (e.g., `uv add httpx`)
+- Add dev dependencies: `uv add --dev pytest ruff`
+- Pin/upgrade by constraint: `uv add "httpx>=0.27"` or adjust `pyproject.toml` and then `uv sync`
+- Remove dependency: `uv remove <name>`
+- Export lock for external tooling: `uv export --format requirements-txt --output-file requirements.txt`
+
+Locking and environments
+- `uv run` and `uv sync` will ensure the environment matches `pyproject.toml` and `uv.lock`
+- Avoid manual `pip install` or manual `venv` activation; let uv manage the environment
+- Commit `uv.lock` to version control for reproducible installs
+
+pyproject guidance
+- Dependencies live under `[project]` → `dependencies = [...]`
+- Development-only tooling should go under a dev group (e.g., `uv add --dev ruff pytest`) for clean separation
+- Keep `requires-python` current (e.g., `>=3.12`) to match the team’s baseline
+
+Usage in this repo
+- When adding libraries or changing versions, propose `uv add ...` changes that update both `pyproject.toml` and `uv.lock`, then run `uv run pytest -q` to validate
+- Prefer minimal diffs, explain the plan, apply changes, and run tests/tooling via `uv run`
+- If build/test fails, inspect error context, adjust constraints or code, and re-run via `uv run`
+
+Common commands (copy/paste)
+- Initialize: `uv init`  |  Install deps: `uv sync`
+- Add runtime: `uv add <pkg>`  |  Add dev: `uv add --dev <pkg>`
+- Remove: `uv remove <pkg>`
+- Run app: `uv run python -m <your_module>` or `uv run main.py`
+- Tests: `uv run pytest -q`
+- Lint/format: `uv run ruff check .` and/or `uv run ruff format .`
+- Export: `uv export --format requirements-txt --output-file requirements.txt`
+
+Of course. Based on your request and the example `app.py` you provided, here is a new section that you can append to your `gemini.md` file. This section provides clear guidance on how to write effective tool names and descriptions, using the Perplexity `chat` function as a concrete example.
+
+The proposed changes will make the function's purpose much clearer, especially its ability to access and cite real-time web information, which is a key feature.
+
+***
+
+### Tool Function Naming and Descriptions
+
+To ensure the AI agent can effectively understand and use the tools available, function names and their descriptions (docstrings) must be clear, descriptive, and accurate. A good description outlines the tool's purpose, its key capabilities, and what it returns.
+
+**Core Principles:**
+- **Use Action-Oriented Names:** Function names should be verbs that clearly state what the tool *does* (e.g., `search`, `create_file`, `list_users`).
+- **Be Specific in Descriptions:** The docstring is the primary source of context for the AI. It should explicitly mention the service it interacts with (e.g., "Perplexity AI") and its unique features (e.g., "performs real-time web searches," "provides citations").
+- **Detail Inputs and Outputs:** Clearly describe the purpose of each argument and what the function returns, as this helps the agent formulate correct calls.
+
+**Example: Improving the Perplexity Tool**
+
+Let's refine the tool in `app.py` to be more descriptive and unlock its full potential. The original `chat` function is too generic. We will rename it to `search` and significantly improve its docstring.
+
+**BEFORE:** The original function name and description are too simple.
+
+```python
+# from app.py
+def chat(
+    self,
+    query: str,
+    model: Literal[...] = "sonar",
+    temperature: float = 1,
+    system_prompt: str = "Be precise and concise.",
+) -> dict[str, Any] | str:
+    """
+    Initiates a chat completion request to generate AI responses using various models with customizable parameters.
+    ...
+    Tags:
+        chat, generate, ai, completion, important
+    """
+```
+
+**AFTER:** The updated name and description are highly specific, highlighting the core web search and citation capabilities. Do not leave any empty lines between the descriptions.
+
+```python
+# from app.py
+def search(
+    self,
+    query: str,
+    model: Literal[
+        "r1-1776",
+        "sonar",
+        "sonar-pro",
+        "sonar-reasoning",
+        "sonar-reasoning-pro",
+        "sonar-deep-research",
+    ] = "sonar-pro",
+    temperature: float = 1,
+    system_prompt: str = "You are a helpful AI assistant that answers questions using real-time information from the web.",
+) -> dict[str, Any] | str:
+    """
+    Performs a real-time web search using Perplexity AI to answer a query with up-to-date information and citations.
+    This tool is ideal for questions about current events, facts, or any topic that requires access to the latest information from the internet. It returns a natural language answer along with the sources used.
+
+    Args:
+        query: The search query or question to ask. For example: "What are the latest developments in AI regulation?"
+        model: The Perplexity model to use. 'sonar-pro' is recommended for comprehensive, up-to-date answers.
+        temperature: Controls randomness in the model's output. Higher values make the output more random, lower values make it more deterministic. Defaults to 1.
+        system_prompt: The initial system message to guide the model's behavior.
+
+    Returns:
+        A dictionary containing the generated 'content' (str) and a list of 'citations' (list) from the web search.
+
+    Raises:
+        AuthenticationError: Raised when API authentication fails due to missing or invalid credentials.
+        HTTPError: Raised when the API request fails or returns an error status.
+
+    Tags:
+        search, web, research, citations, current events, important
+    """
+```

{universal_mcp_applications-0.1.12 → universal_mcp_applications-0.1.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: universal-mcp-applications
-Version: 0.1.12
+Version: 0.1.14
 Summary: A Universal MCP Application: universal_mcp_applications
 Project-URL: Homepage, https://github.com/universal-mcp/applications
 Project-URL: Repository, https://github.com/universal-mcp/applications
@@ -22,7 +22,7 @@ Requires-Dist: google-genai>=1.33.0
 Requires-Dist: google-search-results>=2.4.2
 Requires-Dist: gql[all]>=3.5.2
 Requires-Dist: httpx-aiohttp>=0.1.8
-Requires-Dist: markitdown[audio-transcription,az-doc-intel,docx,outlook,pdf,pptx,xls,xlsx]==0.1.3
+Requires-Dist: markitdown[audio-transcription,az-doc-intel,docx,outlook,pdf,pptx,xls,xlsx]>=0.1.3
 Requires-Dist: office365-rest-python-client>=2.6.2
 Requires-Dist: openai>=1.75.0
 Requires-Dist: pyairtable>=3.1.1

{universal_mcp_applications-0.1.12 → universal_mcp_applications-0.1.14}/bump_and_release.sh

@@ -81,7 +81,6 @@ if [ "$1" = "release" ]; then
     rm -rf .pytest_cache
     rm -rf .ruff_cache
     rm -rf .mypy_cache
-    rm -rf .venv
     rm -rf .cache
     rm -rf .DS_Store
     rm -rf .idea

{universal_mcp_applications-0.1.12 → universal_mcp_applications-0.1.14}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "universal-mcp-applications"
-version = "0.1.12"
+version = "0.1.14"
 description = "A Universal MCP Application: universal_mcp_applications"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -30,7 +30,7 @@ dependencies = [
     "google-search-results>=2.4.2",
     "gql[all]>=3.5.2",
     "httpx-aiohttp>=0.1.8",
-    "markitdown[audio-transcription,az-doc-intel,docx,outlook,pdf,pptx,xls,xlsx]==0.1.3",
+    "markitdown[audio-transcription,az-doc-intel,docx,outlook,pdf,pptx,xls,xlsx]>=0.1.3",
     "office365-rest-python-client>=2.6.2",
     "openai>=1.75.0",
     "pyairtable>=3.1.1",

universal_mcp_applications-0.1.14/src/scripts/docgen.py

@@ -0,0 +1,516 @@
+"""Docstring generator using litellm with structured output.
+
+This module provides a simple way to generate docstrings and suggest improved
+names for Python functions using LLMs with structured output.
+"""
+
+import ast
+import json
+import os
+from pathlib import Path
+import re
+import sys
+import time
+import traceback
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+import litellm
+from pydantic import BaseModel, Field
+
+# --- CHANGE 1: Import prompts from the new prompts.py file ---
+from src.scripts.prompts import SYSTEM_PROMPT_TEMPLATE, USER_PROMPT_TEMPLATE
+
+
+class DescriptionOutput(BaseModel):
+    """Structure for the generated description output."""
+
+    description: str = Field(description="A clear, detailed description of what the function does")
+    suggested_name: Optional[str] = Field(None, description="A better name for the function, if applicable")
+
+
+class FunctionExtractor(ast.NodeVisitor):
+    """
+    An AST node visitor that collects the source code of all function
+    and method definitions within a Python script.
+    """
+
+    def __init__(self, source_code: str):
+        self.source_lines = source_code.splitlines(keepends=True)
+        self.functions: list[tuple[str, str]] = []  # Store tuples of (function_name, function_source)
+
+    def _get_source_segment(self, node: ast.AST) -> str | None:
+        """Safely extracts the source segment for a node using ast.get_source_segment."""
+        try:
+            source_segment = ast.get_source_segment("".join(self.source_lines), node)
+            return source_segment
+        except Exception as e:
+            print(
+                f"Warning: Could not retrieve source for node {getattr(node, 'name', 'unknown')} at line {getattr(node, 'lineno', 'unknown')}: {e}"
+            )
+            return None
+
+    def visit_FunctionDef(self, node: ast.FunctionDef):
+        """Visits a regular function definition and collects it if not excluded."""
+        if not node.name.startswith("_") and node.name != "list_tools":
+            source_code = self._get_source_segment(node)
+            if source_code:
+                self.functions.append((node.name, source_code))
+        self.generic_visit(node)
+
+    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef):
+        """Visits an asynchronous function definition and collects it if not excluded."""
+        if not node.name.startswith("_") and node.name != "list_tools":
+            source_code = self._get_source_segment(node)
+            if source_code:
+                self.functions.append((node.name, source_code))
+        self.generic_visit(node)
+
+
+def extract_functions_from_script(file_path: str) -> list[tuple[str, str]]:
+    """
+    Reads a Python script and extracts the source code of all functions.
+
+    Args:
+        file_path: The path to the Python (.py) script.
+
+    Returns:
+        A list of tuples, where each tuple contains the function name (str)
+        and its full source code (str), including decorators.
+        Returns an empty list if the file cannot be read, parsed, or contains no functions.
+
+    Raises:
+        FileNotFoundError: If the file_path does not exist.
+        SyntaxError: If the file contains invalid Python syntax.
+        Exception: For other potential I/O or AST processing errors.
+    """
+    try:
+        with open(file_path, encoding="utf-8") as f:
+            source_code = f.read()
+    except FileNotFoundError:
+        print(f"Error: File not found at {file_path}")
+        raise
+    except Exception as e:
+        print(f"Error reading file {file_path}: {e}")
+        raise
+
+    try:
+        tree = ast.parse(source_code, filename=file_path)
+    except SyntaxError as e:
+        print(f"Error: Invalid Python syntax in {file_path} at line {e.lineno}, offset {e.offset}: {e.msg}")
+        raise
+    except Exception as e:
+        print(f"Error parsing {file_path} into AST: {e}")
+        raise
+
+    try:
+        extractor = FunctionExtractor(source_code)
+        extractor.visit(tree)
+
+        if not extractor.functions:
+            print("Warning: No functions found in the file.")
+
+        return extractor.functions
+    except Exception as e:
+        print(f"Error during function extraction: {e}")
+        import traceback
+
+        traceback.print_exc()
+        return []
+
+
+def extract_json_from_text(text):
+    """Extract valid JSON from text that might contain additional content.
+
+    Args:
+        text: Raw text response from the model
+
+    Returns:
+        Dict containing the extracted JSON data
+
+    Raises:
+        ValueError: If no valid JSON could be extracted
+    """
+    json_match = re.search(r"```(?:json)?\s*([\s\S]*?)\s*```", text)
+    if json_match:
+        try:
+            return json.loads(json_match.group(1))
+        except json.JSONDecodeError:
+            pass
+
+    try:
+        start = text.find("{")
+        if start >= 0:
+            brace_count = 0
+            for i in range(start, len(text)):
+                if text[i] == "{":
+                    brace_count += 1
+                elif text[i] == "}":
+                    brace_count -= 1
+                    if brace_count == 0:
+                        return json.loads(text[start : i + 1])
+    except json.JSONDecodeError:
+        pass
+
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as e:
+        raise ValueError("Could not extract valid JSON from the response") from e
+
+
+def parse_existing_docstring(docstring: str | None) -> tuple[str, str]:
+    """
+    Parses an existing docstring to separate the summary from the rest.
+
+    Args:
+        docstring: The existing docstring string.
+
+    Returns:
+        A tuple containing (summary, rest_of_docstring).
+        'rest_of_docstring' will include Args, Returns, etc.
+    """
+    if not docstring:
+        return "", ""
+
+    lines = docstring.strip().split('\n')
+    summary_lines = []
+    rest_lines = []
+    summary_done = False
+
+    # Sections that mark the end of the summary
+    section_markers = ("Args:", "Returns:", "Raises:", "Tags:", "Example:", "Examples:")
+
+    for i, line in enumerate(lines):
+        stripped_line = line.strip()
+        if not summary_done and stripped_line and not stripped_line.startswith(section_markers):
+            summary_lines.append(line.strip())
+        elif not summary_done and not stripped_line and summary_lines:
+            # This blank line marks the end of the summary
+            summary_done = True
+            rest_lines = lines[i+1:]
+            break
+        elif stripped_line.startswith(section_markers):
+             # A section starts immediately after the summary
+            summary_done = True
+            rest_lines = lines[i:]
+            break
+        else:
+            # We are already in the rest of the docstring
+            rest_lines.append(line)
+
+    summary = " ".join(summary_lines)
+    # Reconstruct the rest of the docstring, preserving original indentation
+    rest_of_docstring = "\n".join(rest_lines)
+
+    return summary, rest_of_docstring
+
+
+def generate_description(
+    function_code: str, file_content: str, model: str = "perplexity/sonar"
+) -> DescriptionOutput:
+    """
+    Generate a high-quality description and suggest a name for a Python function.
+
+    Args:
+        function_code: The source code of the function to document.
+        file_content: The entire content of the Python file for context.
+        model: The model to use for generating the description.
+
+    Returns:
+        A DescriptionOutput object containing the description and optional name.
+    """
+    system_prompt = SYSTEM_PROMPT_TEMPLATE.format(file_content=file_content)
+    user_prompt = USER_PROMPT_TEMPLATE.format(function_code=function_code)
+
+    # --- NEW: Retry logic with exponential backoff ---
+    max_retries = 3
+    base_delay = 2  # in seconds
+
+    for attempt in range(max_retries):
+        try:
+            response = litellm.completion(
+                model=model,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_prompt},
+                ],
+            )
+            response_text = response.choices[0].message.content
+            try:
+                parsed_data = extract_json_from_text(response_text)
+                return DescriptionOutput(
+                    description=parsed_data.get("description", "No description available."),
+                    suggested_name=parsed_data.get("suggested_name"),
+                )
+            except ValueError as e:
+                print(f"  - JSON extraction failed: {e}")
+                return DescriptionOutput(description="Failed to extract description.")
+
+        except litellm.InternalServerError as e:
+            if attempt < max_retries - 1:
+                delay = base_delay * (2**attempt)
+                print(
+                    f"  - Server error occurred: {e}. Retrying in {delay} seconds... (Attempt {attempt + 1}/{max_retries})",
+                    file=sys.stderr,
+                )
+                time.sleep(delay)
+            else:
+                print(f"  - Max retries reached. Error generating description: {e}", file=sys.stderr)
+                return DescriptionOutput(description=f"Error generating description after {max_retries} retries: {e}")
+
+        except Exception as e:
+            print(f"  - An unexpected error occurred: {e}", file=sys.stderr)
+            return DescriptionOutput(description=f"An unexpected error occurred: {e}")
+
+    return DescriptionOutput(description="Failed to generate description after all retries.")
+
+def insert_docstring_into_function(function_code: str, docstring: str) -> str:
+    """
+    Insert a docstring into a function's code, replacing an existing one if present.
+
+    Args:
+        function_code: The source code of the function snippet.
+        docstring: The formatted docstring string content.
+
+    Returns:
+        The updated function code with the docstring inserted.
+    """
+    try:
+        lines = function_code.splitlines(keepends=True)
+        tree = ast.parse(function_code)
+        if not tree.body or not isinstance(tree.body[0], (ast.FunctionDef, ast.AsyncFunctionDef)):
+            return function_code
+
+        func_node = tree.body[0]
+
+        # --- REVISED INDENTATION LOGIC ---
+        # Determine the correct indentation from the function's existing body.
+        if func_node.body:
+            # Use the indentation of the first statement in the body (e.g., the old docstring).
+            first_body_line_str = lines[func_node.body[0].lineno - 1]
+            body_indent = first_body_line_str[: len(first_body_line_str) - len(first_body_line_str.lstrip())]
+        else:
+            # Fallback for empty functions: calculate from the 'def' line.
+            def_line = lines[func_node.lineno - 1]
+            def_indent = def_line[: len(def_line) - len(def_line.lstrip())]
+            body_indent = def_indent + "    "
+        # --- END OF REVISED LOGIC ---
+
+        # Format the new docstring with the determined indentation
+        new_docstring_lines_formatted = [f'{body_indent}"""\n']
+        new_docstring_lines_formatted.extend([f"{body_indent}{line}\n" for line in docstring.splitlines()])
+        new_docstring_lines_formatted.append(f'{body_indent}"""\n')
+
+        # Check if the first statement is an existing docstring
+        existing_docstring_node = None
+        if (
+            func_node.body and
+            isinstance(func_node.body[0], ast.Expr) and
+            isinstance(func_node.body[0].value, ast.Constant) and
+            isinstance(func_node.body[0].value.value, str)
+        ):
+            existing_docstring_node = func_node.body[0]
+
+        # Splice the code
+        insert_idx = func_node.body[0].lineno - 1 if func_node.body else func_node.lineno
+        pre_insertion_lines = lines[:insert_idx]
+
+        if existing_docstring_node:
+            post_insertion_lines = lines[existing_docstring_node.end_lineno:]
+        else:
+            post_insertion_lines = lines[insert_idx:]
+
+        output_lines = pre_insertion_lines + new_docstring_lines_formatted + post_insertion_lines
+
+        final_code = "".join(output_lines)
+        ast.parse(final_code) # Validate syntax
+        return final_code
+
+    except Exception as e:
+        print(f"Error processing function snippet for insertion: {e}", file=sys.stderr)
+        traceback.print_exc(file=sys.stderr)
+        return function_code
+
+
+def rename_function_in_code(function_code: str, old_name: str, new_name: str) -> str:
+    """
+    Safely renames a function within its source code snippet.
+
+    Args:
+        function_code: The source code of the function.
+        old_name: The original name of the function.
+        new_name: The new name for the function.
+
+    Returns:
+        The function code with the updated name.
+    """
+    # This regex looks for 'def' or 'async def' followed by the old name
+    pattern = r"(async\s+def|def)\s+" + re.escape(old_name) + r"(\s*\()"
+    replacement = r"\1 " + new_name + r"\2"
+    
+    new_function_code, num_replacements = re.subn(pattern, replacement, function_code, 1)
+
+    if num_replacements == 0:
+        print(f"  - Warning: Could not rename function '{old_name}'. Name not found in definition.")
+        return function_code
+    
+    return new_function_code
+
+
+def update_list_tools_method(content: str, old_name: str, new_name: str) -> str:
+    """
+    Updates the list_tools method by renaming a function reference.
+
+    This function uses regex to find the `list_tools` method and replace
+    `self.old_name` with `self.new_name` within its return list, preserving
+    surrounding code and formatting.
+
+    Args:
+        content: The full source code of the file as a string.
+        old_name: The original name of the function to replace.
+        new_name: The new name for the function.
+
+    Returns:
+        The updated file content with the function renamed in list_tools.
+    """
+    # Regex to find `self.old_name` followed by a comma, newline, or closing bracket
+    # This ensures we only replace the specific tool reference in the list.
+    pattern = r"(self\.)" + re.escape(old_name) + r"(?=\s*[,\]])"
+    replacement = r"\1" + new_name
+
+    # First, find the list_tools method definition to narrow the search area
+    list_tools_match = re.search(r"def\s+list_tools\s*\([^)]*\):\s*return\s*\[[^\]]*\]", content, re.DOTALL)
+    
+    if not list_tools_match:
+        print("  - Warning: `list_tools` method not found or has an unexpected format. Cannot update tool list.")
+        return content
+
+    list_tools_code = list_tools_match.group(0)
+    
+    # Perform the replacement only within the found method block
+    updated_list_tools_code, num_replacements = re.subn(pattern, replacement, list_tools_code)
+
+    if num_replacements > 0:
+        print(f"  - Renamed '{old_name}' to '{new_name}' in `list_tools` method.")
+        return content.replace(list_tools_code, updated_list_tools_code)
+    else:
+        print(f"  - Warning: Function '{old_name}' not found in `list_tools` method.")
+        return content
+
+
+def process_file(file_path: str, model: str = "perplexity/sonar") -> int:
+    """
+    Process a Python file to update docstrings and optionally rename functions.
+
+    Args:
+        file_path: Path to the Python file to process.
+        model: The model to use for generating descriptions.
+
+    Returns:
+        Number of functions processed.
+    """
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    with open(file_path, encoding="utf-8") as f:
+        original_content = f.read()
+
+    functions = extract_functions_from_script(file_path)
+    if not functions:
+        print(f"No functions found in {file_path}")
+        return 0
+
+    updated_content = original_content
+    count = 0
+
+    for function_name, function_code in functions:
+        print(f"Processing function: {function_name}")
+
+        try:
+            func_tree = ast.parse(function_code)
+            func_node = func_tree.body[0]
+            existing_docstring = ast.get_docstring(func_node, clean=True)
+            _, rest_of_docstring = parse_existing_docstring(existing_docstring)
+        except (SyntaxError, IndexError):
+            print(f"  - Could not parse function '{function_name}', skipping.")
+            continue
+
+        # 1. Generate new description and check for suggested name
+        output = generate_description(function_code, original_content, model)
+        new_description = output.description.strip()
+        suggested_name = output.suggested_name
+
+        if not new_description or "Error generating description" in new_description:
+            print(f"  - Failed to generate description for '{function_name}', skipping.")
+            continue
+
+        # 2. Reconstruct the full docstring content
+        reconstructed_docstring = new_description
+        if rest_of_docstring:
+            reconstructed_docstring += "\n\n" + rest_of_docstring
+        
+        # 3. Handle function renaming if suggested
+        code_to_update = function_code
+        is_renamed = False
+        if suggested_name and suggested_name != function_name:
+            print(f"  - Renaming function '{function_name}' to '{suggested_name}'")
+            code_to_update = rename_function_in_code(code_to_update, function_name, suggested_name)
+            is_renamed = True
+
+        # 4. Insert the new docstring back into the (potentially renamed) function code
+        updated_function_block = insert_docstring_into_function(code_to_update, reconstructed_docstring)
+
+        # 5. If any changes were made, update the main content
+        if updated_function_block != function_code:
+            updated_content = updated_content.replace(function_code, updated_function_block)
+            count += 1
+            print(f"  - Updated function block for '{suggested_name or function_name}'.")
+            
+            # 6. If the function was renamed, also update the list_tools method
+            if is_renamed:
+                updated_content = update_list_tools_method(updated_content, function_name, suggested_name)
+
+    if updated_content != original_content:
+        with open(file_path, "w", encoding="utf-8") as f:
+            f.write(updated_content)
+        print(f"\nUpdated {count} functions in {file_path}")
+    else:
+        print("\nNo changes made to the file.")
+
+    return count
+
+
+app = typer.Typer()
+@app.command()
+def docgen(
+    file_path: Path = typer.Argument(..., help="Path to the Python file to process"),
+    model: str = typer.Option(
+        "gemini/gemini-2.5-pro",
+        "--model",
+        "-m",
+        help="Model to use for generating docstrings",
+    ),
+):
+    """
+    Generate/update docstrings and function names in Python files using LLMs.
+
+    This command uses litellm to generate high-quality docstring descriptions
+    and suggest better function names, updating the file accordingly.
+    """
+    if not file_path.exists():
+        console.print(f"[red]Error: File not found: {file_path}[/red]")
+        raise typer.Exit(1)
+
+    try:
+        processed = process_file(str(file_path), model)
+        console.print(f"[green]Successfully processed {processed} functions[/green]")
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1) from e
+
+if __name__ == "__main__":
+    app()