steerdev 0.4.27__py3-none-any.whl

steerdev_agent/handlers/prd.py

@@ -0,0 +1,533 @@
+"""PRD message handler for agent-driven PRD analysis and task generation.
+
+This handler processes messages from the SteerDev API related to PRD documents:
+- prd_analyze: Analyze PRD and generate clarification questions
+- prd_generate_plan: Generate implementation plan from clarified PRD
+- prd_generate_tasks: Generate development tasks from implementation plan
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from loguru import logger
+from pydantic import BaseModel
+from rich.console import Console
+
+from steerdev_agent.api.client import get_agent_id
+from steerdev_agent.api.prd import PRDClient
+from steerdev_agent.api.tasks import TasksClient
+from steerdev_agent.prompt.templates import PromptTemplates
+
+console = Console()
+
+
+class PRDAnalyzePayload(BaseModel):
+    """Payload for prd_analyze message type."""
+
+    type: str = "prd_analyze"
+    prd_id: str
+    prd_content: str
+    prd_title: str
+
+
+class PRDGeneratePlanPayload(BaseModel):
+    """Payload for prd_generate_plan message type."""
+
+    type: str = "prd_generate_plan"
+    prd_id: str
+    prd_content: str
+    prd_title: str
+    clarifications: list[dict[str, str]] = []
+
+
+class PRDGenerateTasksPayload(BaseModel):
+    """Payload for prd_generate_tasks message type."""
+
+    type: str = "prd_generate_tasks"
+    prd_id: str
+    project_id: str
+    prd_title: str
+    implementation_plan: dict[str, Any]
+    linear_team_id: str | None = None
+    linear_project_id: str | None = None
+
+
+class PRDHandlerResult(BaseModel):
+    """Result of PRD handler operation."""
+
+    success: bool
+    message_type: str
+    prd_id: str
+    data: dict[str, Any] = {}
+    error: str | None = None
+
+
+class PRDHandler:
+    """Handler for PRD-related agent messages.
+
+    This handler integrates with the SteerDev API to:
+    1. Analyze PRDs and post clarification questions
+    2. Generate implementation plans
+    3. Generate development tasks
+
+    It uses LLM (via prompts) for analysis and stores results via the API.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        agent_id: str | None = None,
+        agent_name: str = "SteerDev Agent",
+    ) -> None:
+        """Initialize the PRD handler.
+
+        Args:
+            api_key: API key for authentication.
+            agent_id: Agent ID for attribution.
+            agent_name: Display name for the agent.
+        """
+        self.api_key = api_key
+        self.agent_id = agent_id or get_agent_id() or "unknown"
+        self.agent_name = agent_name
+        self._prd_client: PRDClient | None = None
+        self._tasks_client: TasksClient | None = None
+
+    @property
+    def prd_client(self) -> PRDClient:
+        """Get or create PRD client."""
+        if self._prd_client is None:
+            self._prd_client = PRDClient(api_key=self.api_key)
+        return self._prd_client
+
+    @property
+    def tasks_client(self) -> TasksClient:
+        """Get or create Tasks client."""
+        if self._tasks_client is None:
+            self._tasks_client = TasksClient(api_key=self.api_key)
+        return self._tasks_client
+
+    def handle_message(self, message_content: str) -> PRDHandlerResult:
+        """Handle a PRD-related message.
+
+        Args:
+            message_content: JSON string containing the message payload.
+
+        Returns:
+            Handler result with success status and data.
+        """
+        try:
+            payload = json.loads(message_content)
+            message_type = payload.get("type", "unknown")
+
+            if message_type == "prd_analyze":
+                return self._handle_analyze(PRDAnalyzePayload(**payload))
+            elif message_type == "prd_generate_plan":
+                return self._handle_generate_plan(PRDGeneratePlanPayload(**payload))
+            elif message_type == "prd_generate_tasks":
+                return self._handle_generate_tasks(PRDGenerateTasksPayload(**payload))
+            else:
+                return PRDHandlerResult(
+                    success=False,
+                    message_type=message_type,
+                    prd_id=payload.get("prd_id", "unknown"),
+                    error=f"Unknown message type: {message_type}",
+                )
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse message content: {e}")
+            return PRDHandlerResult(
+                success=False,
+                message_type="unknown",
+                prd_id="unknown",
+                error=f"Invalid JSON: {e}",
+            )
+        except Exception as e:
+            logger.exception(f"Error handling PRD message: {e}")
+            return PRDHandlerResult(
+                success=False,
+                message_type="unknown",
+                prd_id="unknown",
+                error=str(e),
+            )
+
+    def _handle_analyze(self, payload: PRDAnalyzePayload) -> PRDHandlerResult:
+        """Handle PRD analysis - generate clarification questions.
+
+        This method:
+        1. Builds the analysis prompt
+        2. Returns the prompt for the agent to execute
+        3. The agent response should be parsed and questions posted via API
+
+        Args:
+            payload: Analysis payload with PRD content.
+
+        Returns:
+            Result with prompt to execute.
+        """
+        console.print(f"\n[bold cyan]Analyzing PRD: {payload.prd_title}[/bold cyan]")
+
+        # Build the analysis prompt
+        prompt = PromptTemplates.format_prd_analyze(
+            prd_title=payload.prd_title,
+            prd_content=payload.prd_content,
+        )
+
+        # Return the prompt - the runner will execute this and call back with results
+        return PRDHandlerResult(
+            success=True,
+            message_type="prd_analyze",
+            prd_id=payload.prd_id,
+            data={
+                "prompt": prompt,
+                "next_action": "execute_and_parse",
+                "response_handler": "parse_analysis_response",
+            },
+        )
+
+    def parse_analysis_response(
+        self,
+        prd_id: str,
+        response_text: str,
+    ) -> PRDHandlerResult:
+        """Parse LLM analysis response and post questions to API.
+
+        Args:
+            prd_id: PRD document ID.
+            response_text: Raw LLM response text.
+
+        Returns:
+            Result with posted questions data.
+        """
+        try:
+            # Extract JSON from response (may be wrapped in markdown code block)
+            json_text = response_text
+            if "```json" in response_text:
+                start = response_text.find("```json") + 7
+                end = response_text.find("```", start)
+                json_text = response_text[start:end].strip()
+            elif "```" in response_text:
+                start = response_text.find("```") + 3
+                end = response_text.find("```", start)
+                json_text = response_text[start:end].strip()
+
+            data = json.loads(json_text)
+            questions = data.get("questions", [])
+            summary = data.get("summary", "")
+            observations = data.get("initial_observations", "")
+
+            # Post questions as comments
+            if questions:
+                posted_comments = self.prd_client.post_questions(
+                    prd_id=prd_id,
+                    questions=questions,
+                    agent_id=self.agent_id,
+                    agent_name=self.agent_name,
+                )
+                console.print(f"[green]Posted {len(posted_comments)} questions[/green]")
+            else:
+                console.print("[yellow]No questions to post[/yellow]")
+
+            # Post summary and observations as notes
+            if summary:
+                self.prd_client.post_note(
+                    prd_id=prd_id,
+                    content=f"**Summary:** {summary}",
+                    agent_id=self.agent_id,
+                    agent_name=self.agent_name,
+                )
+
+            if observations:
+                self.prd_client.post_note(
+                    prd_id=prd_id,
+                    content=f"**Initial Observations:** {observations}",
+                    agent_id=self.agent_id,
+                    agent_name=self.agent_name,
+                )
+
+            # Update PRD status to clarifying
+            self.prd_client.update_prd_status(prd_id, "clarifying")
+
+            return PRDHandlerResult(
+                success=True,
+                message_type="prd_analyze",
+                prd_id=prd_id,
+                data={
+                    "questions_count": len(questions),
+                    "summary": summary,
+                },
+            )
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse analysis response: {e}")
+            # Try to recover - update status anyway
+            self.prd_client.update_prd_status(prd_id, "clarifying")
+            return PRDHandlerResult(
+                success=False,
+                message_type="prd_analyze",
+                prd_id=prd_id,
+                error=f"Failed to parse response: {e}",
+            )
+        except Exception as e:
+            logger.exception(f"Error parsing analysis response: {e}")
+            return PRDHandlerResult(
+                success=False,
+                message_type="prd_analyze",
+                prd_id=prd_id,
+                error=str(e),
+            )
+
+    def _handle_generate_plan(self, payload: PRDGeneratePlanPayload) -> PRDHandlerResult:
+        """Handle implementation plan generation.
+
+        Args:
+            payload: Plan generation payload with PRD content and clarifications.
+
+        Returns:
+            Result with prompt to execute.
+        """
+        console.print(f"\n[bold cyan]Generating plan for: {payload.prd_title}[/bold cyan]")
+
+        # Build the plan generation prompt
+        prompt = PromptTemplates.format_prd_generate_plan(
+            prd_title=payload.prd_title,
+            prd_content=payload.prd_content,
+            clarifications=payload.clarifications,
+        )
+
+        return PRDHandlerResult(
+            success=True,
+            message_type="prd_generate_plan",
+            prd_id=payload.prd_id,
+            data={
+                "prompt": prompt,
+                "next_action": "execute_and_parse",
+                "response_handler": "parse_plan_response",
+            },
+        )
+
+    def parse_plan_response(
+        self,
+        prd_id: str,
+        response_text: str,
+    ) -> PRDHandlerResult:
+        """Parse LLM plan response and save to API.
+
+        Args:
+            prd_id: PRD document ID.
+            response_text: Raw LLM response text.
+
+        Returns:
+            Result with saved plan data.
+        """
+        try:
+            # Extract JSON from response
+            json_text = response_text
+            if "```json" in response_text:
+                start = response_text.find("```json") + 7
+                end = response_text.find("```", start)
+                json_text = response_text[start:end].strip()
+            elif "```" in response_text:
+                start = response_text.find("```") + 3
+                end = response_text.find("```", start)
+                json_text = response_text[start:end].strip()
+
+            plan = json.loads(json_text)
+
+            # Save the implementation plan
+            updated_prd = self.prd_client.save_implementation_plan(prd_id, plan)
+
+            if updated_prd:
+                console.print("[green]Implementation plan saved[/green]")
+                sections_count = len(plan.get("sections", []))
+                console.print(f"[dim]Sections: {sections_count}[/dim]")
+
+                return PRDHandlerResult(
+                    success=True,
+                    message_type="prd_generate_plan",
+                    prd_id=prd_id,
+                    data={
+                        "plan": plan,
+                        "sections_count": sections_count,
+                    },
+                )
+            else:
+                return PRDHandlerResult(
+                    success=False,
+                    message_type="prd_generate_plan",
+                    prd_id=prd_id,
+                    error="Failed to save implementation plan",
+                )
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse plan response: {e}")
+            return PRDHandlerResult(
+                success=False,
+                message_type="prd_generate_plan",
+                prd_id=prd_id,
+                error=f"Failed to parse response: {e}",
+            )
+        except Exception as e:
+            logger.exception(f"Error parsing plan response: {e}")
+            return PRDHandlerResult(
+                success=False,
+                message_type="prd_generate_plan",
+                prd_id=prd_id,
+                error=str(e),
+            )
+
+    def _handle_generate_tasks(self, payload: PRDGenerateTasksPayload) -> PRDHandlerResult:
+        """Handle task generation from implementation plan.
+
+        Args:
+            payload: Task generation payload with implementation plan.
+
+        Returns:
+            Result with prompt to execute.
+        """
+        console.print(f"\n[bold cyan]Generating tasks for: {payload.prd_title}[/bold cyan]")
+
+        # Build the task generation prompt
+        prompt = PromptTemplates.format_prd_generate_tasks(
+            prd_title=payload.prd_title,
+            implementation_plan=payload.implementation_plan,
+        )
+
+        return PRDHandlerResult(
+            success=True,
+            message_type="prd_generate_tasks",
+            prd_id=payload.prd_id,
+            data={
+                "prompt": prompt,
+                "next_action": "execute_and_parse",
+                "response_handler": "parse_tasks_response",
+                "project_id": payload.project_id,
+                "linear_team_id": payload.linear_team_id,
+                "linear_project_id": payload.linear_project_id,
+            },
+        )
+
+    def parse_tasks_response(
+        self,
+        prd_id: str,
+        response_text: str,
+        project_id: str,
+        linear_team_id: str | None = None,
+        linear_project_id: str | None = None,
+    ) -> PRDHandlerResult:
+        """Parse LLM tasks response and create tasks via API.
+
+        Args:
+            prd_id: PRD document ID.
+            response_text: Raw LLM response text.
+            project_id: Project ID to create tasks in.
+            linear_team_id: Optional Linear team ID.
+            linear_project_id: Optional Linear project ID.
+
+        Returns:
+            Result with created tasks data.
+        """
+        try:
+            # Extract JSON from response
+            json_text = response_text
+            if "```json" in response_text:
+                start = response_text.find("```json") + 7
+                end = response_text.find("```", start)
+                json_text = response_text[start:end].strip()
+            elif "```" in response_text:
+                start = response_text.find("```") + 3
+                end = response_text.find("```", start)
+                json_text = response_text[start:end].strip()
+
+            data = json.loads(json_text)
+            tasks = data.get("tasks", [])
+
+            if not tasks:
+                return PRDHandlerResult(
+                    success=True,
+                    message_type="prd_generate_tasks",
+                    prd_id=prd_id,
+                    data={"tasks_count": 0, "message": "No tasks to create"},
+                )
+
+            # Create tasks via API
+            created_count = 0
+            failed_count = 0
+            created_task_ids: list[str] = []
+
+            for task in tasks:
+                try:
+                    created_task = self.tasks_client.create_task(
+                        project_id=project_id,
+                        title=task.get("title", "Untitled Task"),
+                        prompt=task.get("description", ""),
+                        priority=task.get("priority", 3),
+                        source="prd",
+                        metadata={
+                            "prd_id": prd_id,
+                            "section": task.get("section"),
+                            "dependencies": task.get("dependencies", []),
+                        },
+                    )
+                    if created_task:
+                        created_count += 1
+                        created_task_ids.append(created_task.get("id", ""))
+                    else:
+                        failed_count += 1
+
+                except Exception as e:
+                    logger.error(f"Failed to create task: {e}")
+                    failed_count += 1
+
+            console.print(f"[green]Created {created_count} tasks[/green]")
+            if failed_count > 0:
+                console.print(f"[yellow]Failed to create {failed_count} tasks[/yellow]")
+
+            # Update PRD status to completed
+            self.prd_client.update_prd_status(prd_id, "completed")
+
+            return PRDHandlerResult(
+                success=True,
+                message_type="prd_generate_tasks",
+                prd_id=prd_id,
+                data={
+                    "tasks_count": created_count,
+                    "failed_count": failed_count,
+                    "task_ids": created_task_ids,
+                },
+            )
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse tasks response: {e}")
+            return PRDHandlerResult(
+                success=False,
+                message_type="prd_generate_tasks",
+                prd_id=prd_id,
+                error=f"Failed to parse response: {e}",
+            )
+        except Exception as e:
+            logger.exception(f"Error parsing tasks response: {e}")
+            return PRDHandlerResult(
+                success=False,
+                message_type="prd_generate_tasks",
+                prd_id=prd_id,
+                error=str(e),
+            )
+
+    def close(self) -> None:
+        """Close client connections."""
+        if self._prd_client:
+            self._prd_client.close()
+            self._prd_client = None
+        if self._tasks_client:
+            self._tasks_client.close()
+            self._tasks_client = None
+
+    def __enter__(self) -> PRDHandler:
+        """Enter context manager."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Exit context manager."""
+        self.close()