datarobot-genai 0.2.14__tar.gz → 0.2.15__tar.gz

{datarobot_genai-0.2.14 → datarobot_genai-0.2.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datarobot-genai
-Version: 0.2.14
+Version: 0.2.15
 Summary: Generic helpers for GenAI
 Project-URL: Homepage, https://github.com/datarobot-oss/datarobot-genai
 Author: DataRobot, Inc.

{datarobot_genai-0.2.14 → datarobot_genai-0.2.15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "datarobot-genai"
-version = "0.2.14"
+version = "0.2.15"
 description = "Generic helpers for GenAI"
 readme = "README.md"
 requires-python = ">=3.10, <3.13"

{datarobot_genai-0.2.14 → datarobot_genai-0.2.15}/src/datarobot_genai/drmcp/tools/clients/confluence.py

@@ -31,6 +31,14 @@ from .atlassian import get_atlassian_cloud_id
 logger = logging.getLogger(__name__)
 
 
+class ConfluenceError(Exception):
+    """Exception for Confluence API errors."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
 class ConfluencePage(BaseModel):
     """Pydantic model for Confluence page."""
 
@@ -133,7 +141,7 @@ class ConfluenceClient:
 
         Raises
         ------
-            ValueError: If page is not found
+            ConfluenceError: If page is not found
             httpx.HTTPStatusError: If the API request fails
         """
         cloud_id = await self._get_cloud_id()
@@ -142,7 +150,7 @@ class ConfluenceClient:
         response = await self._client.get(url, params={"expand": self.EXPAND_FIELDS})
 
         if response.status_code == HTTPStatus.NOT_FOUND:
-            raise ValueError(f"Page with ID '{page_id}' not found")
+            raise ConfluenceError(f"Page with ID '{page_id}' not found", status_code=404)
 
         response.raise_for_status()
         return self._parse_response(response.json())
@@ -161,7 +169,7 @@ class ConfluenceClient:
 
         Raises
         ------
-            ValueError: If the page is not found
+            ConfluenceError: If the page is not found
             httpx.HTTPStatusError: If the API request fails
         """
         cloud_id = await self._get_cloud_id()
@@ -181,10 +189,111 @@ class ConfluenceClient:
         results = data.get("results", [])
 
         if not results:
-            raise ValueError(f"Page with title '{title}' not found in space '{space_key}'")
+            raise ConfluenceError(
+                f"Page with title '{title}' not found in space '{space_key}'", status_code=404
+            )
 
         return self._parse_response(results[0])
 
+    def _extract_error_message(self, response: httpx.Response) -> str:
+        """Extract error message from Confluence API error response."""
+        try:
+            error_data = response.json()
+            # Confluence API returns errors in different formats
+            if "message" in error_data:
+                return error_data["message"]
+            if "errorMessages" in error_data and error_data["errorMessages"]:
+                return "; ".join(error_data["errorMessages"])
+            if "errors" in error_data:
+                errors = error_data["errors"]
+                if isinstance(errors, list):
+                    return "; ".join(str(e) for e in errors)
+                if isinstance(errors, dict):
+                    return "; ".join(f"{k}: {v}" for k, v in errors.items())
+        except Exception:
+            pass
+        return response.text or "Unknown error"
+
+    async def create_page(
+        self,
+        space_key: str,
+        title: str,
+        body_content: str,
+        parent_id: int | None = None,
+    ) -> ConfluencePage:
+        """
+        Create a new Confluence page in a specified space.
+
+        Args:
+            space_key: The key of the Confluence space where the page should live
+            title: The title of the new page
+            body_content: The content in Confluence Storage Format (XML) or raw text
+            parent_id: Optional ID of the parent page for creating a child page
+
+        Returns
+        -------
+            ConfluencePage with the created page data
+
+        Raises
+        ------
+            ConfluenceError: If space not found, parent page not found, duplicate title,
+                            permission denied, or invalid content
+            httpx.HTTPStatusError: If the API request fails with unexpected status
+        """
+        cloud_id = await self._get_cloud_id()
+        url = f"{ATLASSIAN_API_BASE}/ex/confluence/{cloud_id}/wiki/rest/api/content"
+
+        payload: dict[str, Any] = {
+            "type": "page",
+            "title": title,
+            "space": {"key": space_key},
+            "body": {
+                "storage": {
+                    "value": body_content,
+                    "representation": "storage",
+                }
+            },
+        }
+
+        if parent_id is not None:
+            payload["ancestors"] = [{"id": parent_id}]
+
+        response = await self._client.post(url, json=payload)
+
+        if response.status_code == HTTPStatus.NOT_FOUND:
+            error_msg = self._extract_error_message(response)
+            if parent_id is not None and "ancestor" in error_msg.lower():
+                raise ConfluenceError(
+                    f"Parent page with ID '{parent_id}' not found", status_code=404
+                )
+            raise ConfluenceError(
+                f"Space '{space_key}' not found or resource unavailable: {error_msg}",
+                status_code=404,
+            )
+
+        if response.status_code == HTTPStatus.CONFLICT:
+            raise ConfluenceError(
+                f"A page with title '{title}' already exists in space '{space_key}'",
+                status_code=409,
+            )
+
+        if response.status_code == HTTPStatus.FORBIDDEN:
+            raise ConfluenceError(
+                f"Permission denied: you don't have access to create pages in space '{space_key}'",
+                status_code=403,
+            )
+
+        if response.status_code == HTTPStatus.BAD_REQUEST:
+            error_msg = self._extract_error_message(response)
+            raise ConfluenceError(f"Invalid request: {error_msg}", status_code=400)
+
+        if response.status_code == HTTPStatus.TOO_MANY_REQUESTS:
+            raise ConfluenceError("Rate limit exceeded. Please try again later.", status_code=429)
+
+        response.raise_for_status()
+
+        return self._parse_response(response.json())
+
     async def __aenter__(self) -> "ConfluenceClient":
         """Async context manager entry."""
         return self

{datarobot_genai-0.2.14 → datarobot_genai-0.2.15}/src/datarobot_genai/drmcp/tools/clients/jira.py

@@ -107,10 +107,10 @@ class JiraClient:
         self._cloud_id = await get_atlassian_cloud_id(self._client, service_type="jira")
         return self._cloud_id
 
-    async def _get_full_url(self, url: str) -> str:
+    async def _get_full_url(self, path: str) -> str:
         """Return URL for Jira API."""
         cloud_id = await self._get_cloud_id()
-        return f"{ATLASSIAN_API_BASE}/ex/jira/{cloud_id}/rest/api/3/{url}"
+        return f"{ATLASSIAN_API_BASE}/ex/jira/{cloud_id}/rest/api/3/{path}"
 
     async def get_jira_issue(self, issue_key: str) -> Issue:
         """
@@ -209,6 +209,79 @@ class JiraClient:
         jsoned = response.json()
         return jsoned["key"]
 
+    async def update_jira_issue(self, issue_key: str, fields: dict[str, Any]) -> list[str]:
+        """
+        Update Jira issue.
+
+        Args:
+            issue_key: The key of the Jira issue, e.g., 'PROJ-123'
+            fields: A dictionary of field names and their new values
+                e.g., {'description': 'New content'}
+
+        Returns
+        -------
+            List of updated fields
+
+        Raises
+        ------
+            httpx.HTTPStatusError: If the API request fails
+        """
+        url = await self._get_full_url(f"issue/{issue_key}")
+        payload = {"fields": fields}
+
+        response = await self._client.put(url, json=payload)
+
+        response.raise_for_status()
+        return list(fields.keys())
+
+    async def get_available_jira_transitions(self, issue_key: str) -> dict[str, str]:
+        """
+        Get Available Jira Transitions.
+
+        Args:
+            issue_key: The key of the Jira issue, e.g., 'PROJ-123'
+
+        Returns
+        -------
+            Dictionary where key is the transition name and value is the transition ID
+
+        Raises
+        ------
+            httpx.HTTPStatusError: If the API request fails
+        """
+        url = await self._get_full_url(f"issue/{issue_key}/transitions")
+        response = await self._client.get(url)
+        response.raise_for_status()
+        jsoned = response.json()
+        transitions = {
+            transition["name"]: transition["id"] for transition in jsoned.get("transitions", [])
+        }
+        return transitions
+
+    async def transition_jira_issue(self, issue_key: str, transition_id: str) -> None:
+        """
+        Transition Jira issue.
+
+        Args:
+            issue_key: The key of the Jira issue, e.g., 'PROJ-123'
+            transition_id: Id of target transitionm e.g. '123'.
+                Can be obtained from `get_available_jira_transitions`.
+
+        Returns
+        -------
+            Nothing
+
+        Raises
+        ------
+            httpx.HTTPStatusError: If the API request fails
+        """
+        url = await self._get_full_url(f"issue/{issue_key}")
+        payload = {"transition": {"id": transition_id}}
+
+        response = await self._client.post(url, json=payload)
+
+        response.raise_for_status()
+
     async def __aenter__(self) -> "JiraClient":
         """Async context manager entry."""
         return self

{datarobot_genai-0.2.14 → datarobot_genai-0.2.15}/src/datarobot_genai/drmcp/tools/confluence/tools.py

@@ -23,6 +23,7 @@ from fastmcp.tools.tool import ToolResult
 from datarobot_genai.drmcp.core.mcp_instance import dr_mcp_tool
 from datarobot_genai.drmcp.tools.clients.atlassian import get_atlassian_access_token
 from datarobot_genai.drmcp.tools.clients.confluence import ConfluenceClient
+from datarobot_genai.drmcp.tools.clients.confluence import ConfluenceError
 
 logger = logging.getLogger(__name__)
 
@@ -65,8 +66,8 @@ async def confluence_get_page(
                         "'space_key' is required when identifying a page by title."
                     )
                 page_response = await client.get_page_by_title(page_id_or_title, space_key)
-    except ValueError as e:
-        logger.error(f"Value error getting Confluence page: {e}")
+    except ConfluenceError as e:
+        logger.error(f"Confluence error getting page: {e}")
         raise ToolError(str(e))
     except Exception as e:
         logger.error(f"Unexpected error getting Confluence page: {e}")
@@ -79,3 +80,61 @@ async def confluence_get_page(
         content=f"Successfully retrieved page '{page_response.title}'.",
         structured_content=page_response.as_flat_dict(),
     )
+
+
+@dr_mcp_tool(tags={"confluence", "write", "create", "page"})
+async def confluence_create_page(
+    *,
+    space_key: Annotated[str, "The key of the Confluence space where the new page should live."],
+    title: Annotated[str, "The title of the new page."],
+    body_content: Annotated[
+        str,
+        "The content of the page, typically in Confluence Storage Format (XML) or raw text.",
+    ],
+    parent_id: Annotated[
+        int | None,
+        "The ID of the parent page, used to create a child page.",
+    ] = None,
+) -> ToolResult:
+    """Create a new documentation page in a specified Confluence space.
+
+    Use this tool to create new Confluence pages with content in storage format.
+    The page will be created at the root level of the space unless a parent_id
+    is provided, in which case it will be created as a child page.
+
+    Usage:
+        - Root page: space_key="PROJ", title="New Page", body_content="<p>Content</p>"
+        - Child page: space_key="PROJ", title="Sub Page", body_content="<p>Content</p>",
+                      parent_id=123456
+    """
+    if not all([space_key, title, body_content]):
+        raise ToolError(
+            "Argument validation error: space_key, title, and body_content are required fields."
+        )
+
+    access_token = await get_atlassian_access_token()
+    if isinstance(access_token, ToolError):
+        raise access_token
+
+    try:
+        async with ConfluenceClient(access_token) as client:
+            page_response = await client.create_page(
+                space_key=space_key,
+                title=title,
+                body_content=body_content,
+                parent_id=parent_id,
+            )
+    except ConfluenceError as e:
+        logger.error(f"Confluence error creating page: {e}")
+        raise ToolError(str(e))
+    except Exception as e:
+        logger.error(f"Unexpected error creating Confluence page: {e}")
+        raise ToolError(
+            f"An unexpected error occurred while creating Confluence page "
+            f"'{title}' in space '{space_key}': {str(e)}"
+        )
+
+    return ToolResult(
+        content=f"New page '{title}' created successfully in space '{space_key}'.",
+        structured_content={"new_page_id": page_response.page_id, "title": page_response.title},
+    )

datarobot_genai-0.2.15/src/datarobot_genai/drmcp/tools/jira/tools.py

@@ -0,0 +1,209 @@
+# Copyright 2025 DataRobot, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import logging
+from typing import Annotated
+from typing import Any
+
+from fastmcp.exceptions import ToolError
+from fastmcp.tools.tool import ToolResult
+
+from datarobot_genai.drmcp.core.mcp_instance import dr_mcp_tool
+from datarobot_genai.drmcp.tools.clients.atlassian import get_atlassian_access_token
+from datarobot_genai.drmcp.tools.clients.jira import JiraClient
+
+logger = logging.getLogger(__name__)
+
+
+@dr_mcp_tool(tags={"jira", "read", "get", "issue"})
+async def jira_get_issue(
+    *, issue_key: Annotated[str, "The key (ID) of the Jira issue to retrieve, e.g., 'PROJ-123'."]
+) -> ToolResult:
+    """Retrieve all fields and details for a single Jira issue by its key."""
+    if not issue_key:
+        raise ToolError("Argument validation error: 'issue_key' cannot be empty.")
+
+    access_token = await get_atlassian_access_token()
+    if isinstance(access_token, ToolError):
+        raise access_token
+
+    try:
+        async with JiraClient(access_token) as client:
+            issue = await client.get_jira_issue(issue_key)
+    except Exception as e:
+        logger.error(f"Unexpected error while getting Jira issue: {e}")
+        raise ToolError(
+            f"An unexpected error occurred while getting Jira issue '{issue_key}': {str(e)}"
+        )
+
+    return ToolResult(
+        content=f"Successfully retrieved details for issue '{issue_key}'.",
+        structured_content=issue.as_flat_dict(),
+    )
+
+
+@dr_mcp_tool(tags={"jira", "create", "add", "issue"})
+async def jira_create_issue(
+    *,
+    project_key: Annotated[str, "The key of the project where the issue should be created."],
+    summary: Annotated[str, "A brief summary or title for the new issue."],
+    issue_type: Annotated[str, "The type of issue to create (e.g., 'Task', 'Bug', 'Story')."],
+    description: Annotated[str | None, "Detailed description of the issue."] = None,
+) -> ToolResult:
+    """Create a new Jira issue with mandatory project, summary, and type information."""
+    if not all([project_key, summary, issue_type]):
+        raise ToolError(
+            "Argument validation error: project_key, summary, and issue_type are required fields."
+        )
+
+    access_token = await get_atlassian_access_token()
+    if isinstance(access_token, ToolError):
+        raise access_token
+
+    async with JiraClient(access_token) as client:
+        # Maybe we should cache it somehow?
+        # It'll be probably constant through whole mcp server lifecycle...
+        issue_types = await client.get_jira_issue_types(project_key=project_key)
+
+        try:
+            issue_type_id = issue_types[issue_type]
+        except KeyError:
+            possible_issue_types = ",".join(issue_types)
+            raise ToolError(
+                f"Unexpected issue type `{issue_type}`. Possible values are {possible_issue_types}."
+            )
+
+    try:
+        async with JiraClient(access_token) as client:
+            issue_key = await client.create_jira_issue(
+                project_key=project_key,
+                summary=summary,
+                issue_type_id=issue_type_id,
+                description=description,
+            )
+    except Exception as e:
+        logger.error(f"Unexpected error while creating Jira issue: {e}")
+        raise ToolError(f"An unexpected error occurred while creating Jira issue: {str(e)}")
+
+    return ToolResult(
+        content=f"Successfully created issue '{issue_key}'.",
+        structured_content={"newIssueKey": issue_key, "projectKey": project_key},
+    )
+
+
+@dr_mcp_tool(tags={"jira", "update", "edit", "issue"})
+async def jira_update_issue(
+    *,
+    issue_key: Annotated[str, "The key (ID) of the Jira issue to retrieve, e.g., 'PROJ-123'."],
+    fields_to_update: Annotated[
+        dict[str, Any],
+        "A dictionary of field names and their new values (e.g., {'summary': 'New content'}).",
+    ],
+) -> ToolResult:
+    """
+    Modify descriptive fields or custom fields on an existing Jira issue using its key.
+    If you want to update issue status you should use `jira_transition_issue` tool instead.
+
+    Some fields needs very specific schema to allow update.
+    You should follow jira rest api guidance.
+    Good example is description field:
+        "description": {
+            "type": "text",
+            "version": 1,
+            "text": [
+                {
+                    "type": "paragraph",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": "[HERE YOU PUT REAL DESCRIPTION]"
+                        }
+                    ]
+                }
+            ]
+        }
+    """
+    if not issue_key:
+        raise ToolError("Argument validation error: 'issue_key' cannot be empty.")
+    if not fields_to_update or not isinstance(fields_to_update, dict):
+        raise ToolError(
+            "Argument validation error: 'fields_to_update' must be a non-empty dictionary."
+        )
+
+    access_token = await get_atlassian_access_token()
+    if isinstance(access_token, ToolError):
+        raise access_token
+
+    try:
+        async with JiraClient(access_token) as client:
+            updated_fields = await client.update_jira_issue(
+                issue_key=issue_key, fields=fields_to_update
+            )
+    except Exception as e:
+        logger.error(f"Unexpected error while updating Jira issue: {e}")
+        raise ToolError(f"An unexpected error occurred while updating Jira issue: {str(e)}")
+
+    updated_fields_str = ",".join(updated_fields)
+    return ToolResult(
+        content=f"Successfully updated issue '{issue_key}'. Fields modified: {updated_fields_str}.",
+        structured_content={"updatedIssueKey": issue_key, "fields": updated_fields},
+    )
+
+
+@dr_mcp_tool(tags={"jira", "update", "transition", "issue"})
+async def jira_transition_issue(
+    *,
+    issue_key: Annotated[str, "The key (ID) of the Jira issue to transition, e.g. 'PROJ-123'."],
+    transition_name: Annotated[
+        str, "The exact name of the target status/transition (e.g., 'In Progress')."
+    ],
+) -> ToolResult:
+    """
+    Move a Jira issue through its defined workflow to a new status.
+    This leverages Jira's workflow engine directly.
+    """
+    if not all([issue_key, transition_name]):
+        raise ToolError("Argument validation error: issue_key and transition name/ID are required.")
+
+    access_token = await get_atlassian_access_token()
+    if isinstance(access_token, ToolError):
+        raise access_token
+
+    async with JiraClient(access_token) as client:
+        available_transitions = await client.get_available_jira_transitions(issue_key=issue_key)
+
+        try:
+            transition_id = available_transitions[transition_name]
+        except KeyError:
+            available_transitions_str = ",".join(available_transitions)
+            raise ToolError(
+                f"Unexpected transition name `{transition_name}`. "
+                f"Possible values are {available_transitions_str}."
+            )
+
+    try:
+        async with JiraClient(access_token) as client:
+            await client.transition_jira_issue(issue_key=issue_key, transition_id=transition_id)
+    except Exception as e:
+        logger.error(f"Unexpected error while transitioning Jira issue: {e}")
+        raise ToolError(f"An unexpected error occurred while transitioning Jira issue: {str(e)}")
+
+    return ToolResult(
+        content=f"Successfully transitioned issue '{issue_key}' to status '{transition_name}'.",
+        structured_content={
+            "transitionedIssueKey": issue_key,
+            "newStatusName": transition_name,
+            "newStatusId": transition_id,
+        },
+    )

datarobot_genai-0.2.14/src/datarobot_genai/drmcp/tools/jira/tools.py

@@ -1,101 +0,0 @@
-# Copyright 2025 DataRobot, Inc.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#   http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-import logging
-from typing import Annotated
-
-from fastmcp.exceptions import ToolError
-from fastmcp.tools.tool import ToolResult
-
-from datarobot_genai.drmcp.core.mcp_instance import dr_mcp_tool
-from datarobot_genai.drmcp.tools.clients.atlassian import get_atlassian_access_token
-from datarobot_genai.drmcp.tools.clients.jira import JiraClient
-
-logger = logging.getLogger(__name__)
-
-
-@dr_mcp_tool(tags={"jira", "read", "get", "issue"})
-async def jira_get_issue(
-    *, issue_key: Annotated[str, "The key (ID) of the Jira issue to retrieve, e.g., 'PROJ-123'."]
-) -> ToolResult:
-    """Retrieve all fields and details for a single Jira issue by its key."""
-    if not issue_key:
-        raise ToolError("Argument validation error: 'issue_key' cannot be empty.")
-
-    access_token = await get_atlassian_access_token()
-    if isinstance(access_token, ToolError):
-        raise access_token
-
-    try:
-        async with JiraClient(access_token) as client:
-            issue = await client.get_jira_issue(issue_key)
-    except Exception as e:
-        logger.error(f"Unexpected error while getting Jira issue: {e}")
-        raise ToolError(
-            f"An unexpected error occurred while getting Jira issue '{issue_key}': {str(e)}"
-        )
-
-    return ToolResult(
-        content=f"Successfully retrieved details for issue '{issue_key}'.",
-        structured_content=issue.as_flat_dict(),
-    )
-
-
-@dr_mcp_tool(tags={"jira", "create", "add", "issue"})
-async def jira_create_issue(
-    *,
-    project_key: Annotated[str, "The key of the project where the issue should be created."],
-    summary: Annotated[str, "A brief summary or title for the new issue."],
-    issue_type: Annotated[str, "The type of issue to create (e.g., 'Task', 'Bug', 'Story')."],
-    description: Annotated[str | None, "Detailed description of the issue."] = None,
-) -> ToolResult:
-    """Create a new Jira issue with mandatory project, summary, and type information."""
-    if not all([project_key, summary, issue_type]):
-        raise ToolError(
-            "Argument validation error: project_key, summary, and issue_type are required fields."
-        )
-
-    access_token = await get_atlassian_access_token()
-    if isinstance(access_token, ToolError):
-        raise access_token
-
-    async with JiraClient(access_token) as client:
-        # Maybe we should cache it somehow?
-        # It'll be probably constant through whole mcp server lifecycle...
-        issue_types = await client.get_jira_issue_types(project_key=project_key)
-
-        try:
-            issue_type_id = issue_types[issue_type]
-        except KeyError:
-            possible_issue_types = ",".join(issue_types)
-            raise ToolError(
-                f"Unexpected issue type `{issue_type}`. Possible values are {possible_issue_types}."
-            )
-
-    try:
-        async with JiraClient(access_token) as client:
-            issue_key = await client.create_jira_issue(
-                project_key=project_key,
-                summary=summary,
-                issue_type_id=issue_type_id,
-                description=description,
-            )
-    except Exception as e:
-        logger.error(f"Unexpected error while creating Jira issue: {e}")
-        raise ToolError(f"An unexpected error occurred while creating Jira issue: {str(e)}")
-
-    return ToolResult(
-        content=f"Successfully created issue '{issue_key}'.",
-        structured_content={"newIssueKey": issue_key, "projectKey": project_key},
-    )