steerdev 0.4.27__py3-none-any.whl

steerdev_agent/api/prd.py

@@ -0,0 +1,281 @@
+"""PRD API client for SteerDev Agent.
+
+Provides methods for interacting with PRD documents and comments
+during agent-driven PRD analysis and task generation.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from loguru import logger
+from pydantic import BaseModel
+
+from steerdev_agent.api.client import SteerDevClient
+
+
+class PRDComment(BaseModel):
+    """PRD comment model."""
+
+    id: str
+    prd_id: str
+    parent_id: str | None = None
+    content: str
+    comment_type: str  # question, answer, note
+    context: str | None = None
+    category: str | None = None
+    author_type: str  # agent, user
+    author_id: str
+    author_name: str | None = None
+    is_resolved: bool = False
+    created_at: str
+    updated_at: str
+
+
+class PRDDocument(BaseModel):
+    """PRD document model."""
+
+    id: str
+    project_id: str
+    title: str
+    content: str
+    source: str
+    source_file_name: str | None = None
+    status: str  # draft, analyzing, clarifying, planning, ready, completed
+    implementation_plan: dict[str, Any] | None = None
+    run_id: str | None = None
+    created_by: str
+    created_at: str
+    updated_at: str
+
+
+class PRDClient(SteerDevClient):
+    """API client for PRD operations.
+
+    Used by the agent to:
+    - Get PRD document content
+    - Post analysis questions as comments
+    - Update PRD status
+    - Save implementation plans
+    """
+
+    def get_prd(self, prd_id: str) -> PRDDocument | None:
+        """Get a PRD document by ID.
+
+        Args:
+            prd_id: PRD document ID.
+
+        Returns:
+            PRD document or None if not found.
+        """
+        try:
+            response = self.get(f"/prd/{prd_id}")
+
+            if response.status_code == 200:
+                data = response.json()
+                return PRDDocument(**data)
+            if response.status_code == 404:
+                return None
+
+            logger.error(f"Failed to get PRD: {response.status_code} - {response.text}")
+            return None
+
+        except Exception as e:
+            logger.error(f"Error getting PRD: {e}")
+            return None
+
+    def update_prd_status(self, prd_id: str, status: str) -> PRDDocument | None:
+        """Update PRD status.
+
+        Args:
+            prd_id: PRD document ID.
+            status: New status value.
+
+        Returns:
+            Updated PRD document or None on failure.
+        """
+        try:
+            response = self.patch(f"/prd/{prd_id}", json={"status": status})
+
+            if response.status_code == 200:
+                data = response.json()
+                return PRDDocument(**data)
+
+            logger.error(f"Failed to update PRD status: {response.status_code} - {response.text}")
+            return None
+
+        except Exception as e:
+            logger.error(f"Error updating PRD status: {e}")
+            return None
+
+    def save_implementation_plan(
+        self,
+        prd_id: str,
+        plan: dict[str, Any],
+    ) -> PRDDocument | None:
+        """Save implementation plan to PRD document.
+
+        Args:
+            prd_id: PRD document ID.
+            plan: Implementation plan dictionary.
+
+        Returns:
+            Updated PRD document or None on failure.
+        """
+        try:
+            response = self.patch(
+                f"/prd/{prd_id}",
+                json={
+                    "implementation_plan": plan,
+                    "status": "ready",
+                },
+            )
+
+            if response.status_code == 200:
+                data = response.json()
+                return PRDDocument(**data)
+
+            logger.error(
+                f"Failed to save implementation plan: {response.status_code} - {response.text}"
+            )
+            return None
+
+        except Exception as e:
+            logger.error(f"Error saving implementation plan: {e}")
+            return None
+
+    def post_questions(
+        self,
+        prd_id: str,
+        questions: list[dict[str, str]],
+        agent_id: str,
+        agent_name: str = "SteerDev Agent",
+    ) -> list[PRDComment]:
+        """Post analysis questions as comments.
+
+        Args:
+            prd_id: PRD document ID.
+            questions: List of question dicts with keys: question, context, category.
+            agent_id: Agent ID posting the questions.
+            agent_name: Display name for the agent.
+
+        Returns:
+            List of created comments.
+        """
+        try:
+            comments_data = [
+                {
+                    "content": q.get("question", ""),
+                    "comment_type": "question",
+                    "context": q.get("context"),
+                    "category": q.get("category"),
+                    "author_type": "agent",
+                    "author_id": agent_id,
+                    "author_name": agent_name,
+                }
+                for q in questions
+            ]
+
+            response = self.post(
+                f"/prd/{prd_id}/comments",
+                json={"comments": comments_data},
+            )
+
+            if response.status_code == 201:
+                data = response.json()
+                return [PRDComment(**c) for c in data.get("comments", [])]
+
+            logger.error(f"Failed to post questions: {response.status_code} - {response.text}")
+            return []
+
+        except Exception as e:
+            logger.error(f"Error posting questions: {e}")
+            return []
+
+    def get_comments(self, prd_id: str) -> list[PRDComment]:
+        """Get all comments for a PRD.
+
+        Args:
+            prd_id: PRD document ID.
+
+        Returns:
+            List of comments.
+        """
+        try:
+            response = self.get(f"/prd/{prd_id}/comments")
+
+            if response.status_code == 200:
+                data = response.json()
+                return [PRDComment(**c) for c in data.get("comments", [])]
+
+            logger.error(f"Failed to get comments: {response.status_code} - {response.text}")
+            return []
+
+        except Exception as e:
+            logger.error(f"Error getting comments: {e}")
+            return []
+
+    def resolve_comment(self, prd_id: str, comment_id: str) -> PRDComment | None:
+        """Mark a question as resolved.
+
+        Args:
+            prd_id: PRD document ID.
+            comment_id: Comment ID to resolve.
+
+        Returns:
+            Updated comment or None on failure.
+        """
+        try:
+            response = self.post(f"/prd/{prd_id}/comments/{comment_id}/resolve")
+
+            if response.status_code == 200:
+                data = response.json()
+                return PRDComment(**data)
+
+            logger.error(f"Failed to resolve comment: {response.status_code} - {response.text}")
+            return None
+
+        except Exception as e:
+            logger.error(f"Error resolving comment: {e}")
+            return None
+
+    def post_note(
+        self,
+        prd_id: str,
+        content: str,
+        agent_id: str,
+        agent_name: str = "SteerDev Agent",
+    ) -> PRDComment | None:
+        """Post a general note as a comment.
+
+        Args:
+            prd_id: PRD document ID.
+            content: Note content.
+            agent_id: Agent ID posting the note.
+            agent_name: Display name for the agent.
+
+        Returns:
+            Created comment or None on failure.
+        """
+        try:
+            response = self.post(
+                f"/prd/{prd_id}/comments",
+                json={
+                    "content": content,
+                    "comment_type": "note",
+                    "author_type": "agent",
+                    "author_id": agent_id,
+                    "author_name": agent_name,
+                },
+            )
+
+            if response.status_code == 201:
+                data = response.json()
+                return PRDComment(**data)
+
+            logger.error(f"Failed to post note: {response.status_code} - {response.text}")
+            return None
+
+        except Exception as e:
+            logger.error(f"Error posting note: {e}")
+            return None