Merge pull request #436 from Mng-dev-ai/feat/ai-pr-description

AI-Generated PR Description Feature Request

Author: Mng-dev-ai

CLAUDE.md

@@ -37,6 +37,9 @@
 - Narrow `except` clauses to specific exception types — never `except Exception` when the actual failure modes are known (e.g., `except (KeyError, SomeLibError)` not `except Exception`)
 - Do not translate exceptions across boundaries just to change the type — if an upstream function already raises a meaningful error, let it propagate; only catch-and-wrap when the caller genuinely needs a different status code or error shape that the original doesn't provide
 - Do not handle hypothetical input shapes — if you have evidence of the actual data format (logs, tests, type definitions), write code for that format only; do not add branches for types or structures you have not observed
+- Do not use Python's `str.format()` or f-strings to interpolate untrusted/user-provided content that may contain `{` or `}` characters (e.g., code diffs, source code snippets, JSON) — use string concatenation or `string.Template` instead
+- Add `Field(max_length=...)` to all `str` fields on Pydantic request models — bare `str` allows unbounded payloads; also add `min_length=1` when empty strings are invalid
+- Do not instantiate services directly in FastAPI route handlers — add a factory function in `deps.py` and inject via `Depends()`; route files should not import `SessionLocal`
 - Don't add comments or docstrings for self-explanatory code — but do add inline comments for non-obvious logic, implicit conventions, or design decisions that aren't clear from the code alone
 - Do not delete existing comments without asking first — they may capture context that isn't obvious from the code
 - Let the code speak for itself - use clear variable/function names instead of comments
@@ -213,7 +216,7 @@
 - Use CSS keyframe animations via Tailwind (`animate-fade-in`, `animate-fade-in-up`, `animate-dot-pulse`, etc.) for enter/state transitions — do not use `framer-motion` or other JS animation libraries
 - Use `transition-colors duration-200` for hover/focus, `transition-all duration-300` for complex state changes like drag-and-drop
 - Use `transition-[padding] duration-500 ease-in-out` for sidebar/layout animations
-- Loading states: `animate-spin` for spinners, `animate-pulse` for skeletons, `animate-bounce` with staggered `animationDelay` for dot loaders
+- Loading states: `animate-spin` for circular spinner icons only (e.g., `Loader2`), `animate-pulse` for non-circular icons used as loading indicators and skeletons, `animate-bounce` with staggered `animationDelay` for dot loaders
 - Expandable content: `transition-all duration-200` with `max-h-*` and `opacity` toggling
 - Dropdowns: `animate-fadeIn` for entry — no scale transforms on buttons
 

backend/app/api/endpoints/github.py

@@ -1,20 +1,24 @@
 from typing import NoReturn
 
-from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi import APIRouter, Depends, HTTPException, Query, status
 
-from app.core.deps import get_github_service
+from app.core.deps import get_claude_agent_service, get_github_service
 from app.core.security import get_current_user
 from app.models.db_models.user import User
 from app.models.schemas.github import (
     CreatePullRequestRequest,
     CreatePullRequestResponse,
+    GeneratePRDescriptionRequest,
+    GeneratePRDescriptionResponse,
     GitHubCollaborator,
     GitHubPRCommentsResponse,
     GitHubPRListResponse,
     GitHubReposResponse,
 )
-from app.services.exceptions import GitHubException
+from app.services.claude_agent import ClaudeAgentService
+from app.services.exceptions import ClaudeAgentException, GitHubException
 from app.services.github import GitHubService
+from app.utils.validators import APIKeyValidationError
 
 router = APIRouter()
 
@@ -79,6 +83,32 @@ async def create_pull_request(
         _raise_from_github(exc)
 
 
+@router.post(
+    "/generate-pr-description",
+    response_model=GeneratePRDescriptionResponse,
+)
+async def generate_pr_description(
+    request: GeneratePRDescriptionRequest,
+    current_user: User = Depends(get_current_user),
+    ai_service: ClaudeAgentService = Depends(get_claude_agent_service),
+) -> GeneratePRDescriptionResponse:
+    try:
+        description = await ai_service.generate_pr_description(
+            request.title, request.diff, request.model_id, current_user
+        )
+    except APIKeyValidationError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e),
+        ) from e
+    except ClaudeAgentException as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=str(e),
+        ) from e
+    return GeneratePRDescriptionResponse(description=description)
+
+
 @router.get("/collaborators")
 async def list_collaborators(
     owner: str = Query(..., min_length=1),

backend/app/core/deps.py

@@ -12,6 +12,7 @@
 from app.models.db_models.user import User
 from app.services.agent import AgentService
 from app.services.chat import ChatService
+from app.services.claude_agent import ClaudeAgentService
 from app.services.command import CommandService
 from app.services.exceptions import UserException
 from app.services.github import GitHubService
@@ -86,6 +87,10 @@ def get_github_service(
     return GitHubService(token=github_token)
 
 
+def get_claude_agent_service() -> ClaudeAgentService:
+    return ClaudeAgentService(session_factory=SessionLocal)
+
+
 def get_marketplace_service() -> MarketplaceService:
     return MarketplaceService()
 

backend/app/models/schemas/github.py

@@ -1,6 +1,6 @@
 from typing import Any
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 class GitHubRepo(BaseModel):
@@ -70,3 +70,13 @@ class CreatePullRequestResponse(BaseModel):
 class GitHubCollaborator(BaseModel):
     login: str
     avatar_url: str
+
+
+class GeneratePRDescriptionRequest(BaseModel):
+    title: str = Field(max_length=256)
+    diff: str = Field(min_length=1, max_length=200_000)
+    model_id: str = Field(max_length=128)
+
+
+class GeneratePRDescriptionResponse(BaseModel):
+    description: str

backend/app/prompts/generate_pr_description.py

@@ -0,0 +1,16 @@
+GENERATE_PR_DESCRIPTION_SYSTEM_PROMPT = """You are a pull request description writer. Given a git diff and a PR title, produce a clear, well-structured PR description in GitHub-flavored Markdown.
+
+Output ONLY the description with no preamble, explanation, or meta-commentary.
+
+<guidelines>
+- Start with a concise summary (1-3 sentences) explaining what changed and why
+- Use a "## Changes" section with bullet points for notable changes
+- Group related changes logically (e.g., by feature area, file type)
+- Mention any breaking changes, new dependencies, or configuration changes if present
+- Keep it concise — focus on the "what" and "why", not line-by-line details
+- Do not include a test plan section unless the diff contains test files
+- Do not include generic boilerplate like "Please review" or "Let me know if you have questions"
+- If the diff is too large or unclear, summarize at a high level based on the file paths and change patterns
+</guidelines>"""
+
+GENERATE_PR_DESCRIPTION_TITLE_PREFIX = "Title: "

backend/app/services/claude_agent.py

@@ -25,6 +25,10 @@
 from app.models.db_models.user import User, UserSettings
 from app.models.schemas.settings import ProviderType
 from app.prompts.enhance_prompt import ENHANCE_PROMPT
+from app.prompts.generate_pr_description import (
+    GENERATE_PR_DESCRIPTION_SYSTEM_PROMPT,
+    GENERATE_PR_DESCRIPTION_TITLE_PREFIX,
+)
 from app.prompts.system_prompt import DEFAULT_PERSONA_NAME
 from app.prompts.generate_title import (
     GENERATE_TITLE_SYSTEM_PROMPT,
@@ -39,6 +43,7 @@
 from app.services.transports import SandboxTransport
 from app.services.transports.factory import create_sandbox_transport
 from app.services.user import UserService
+from app.utils.validators import validate_model_api_keys
 
 settings = get_settings()
 logger = logging.getLogger(__name__)
@@ -331,6 +336,41 @@ async def generate_title(self, prompt: str, user: User) -> str | None:
             logger.debug("Title generation SDK call failed for user %s", user.id)
             return None
 
+    async def generate_pr_description(
+        self, title: str, diff: str, model_id: str, user: User
+    ) -> str:
+        user_settings = await UserService(
+            session_factory=self.session_factory
+        ).get_user_settings(user.id)
+
+        validate_model_api_keys(user_settings, model_id)
+        env, _, actual_model_id = self._build_auth_env(model_id, user_settings)
+
+        options = ClaudeAgentOptions(
+            system_prompt=GENERATE_PR_DESCRIPTION_SYSTEM_PROMPT,
+            permission_mode="default",
+            model=actual_model_id,
+            max_turns=1,
+            env=env,
+        )
+
+        try:
+            description = ""
+            async with ClaudeSDKClient(options=options) as client:
+                user_message = (
+                    GENERATE_PR_DESCRIPTION_TITLE_PREFIX + title + "\n\n" + diff
+                )
+                await client.query(user_message)
+                async for message in client.receive_response():
+                    if isinstance(message, ResultMessage) and message.result:
+                        description = message.result
+
+            if not description:
+                raise ClaudeAgentException("AI returned an empty description")
+            return description
+        except ClaudeSDKError as e:
+            raise ClaudeAgentException(f"Failed to generate PR description: {e}") from e
+
     @staticmethod
     def _build_permission_server(
         permission_mode: str, chat_id: str, sandbox_provider: str = "docker"