{kwargs["description"]}
" + + # Remove icon_prop and logo_props - SDK auto-generates these and ignores user input + kwargs.pop("icon_prop", None) + kwargs.pop("logo_props", None) + + elif method_key == "update": + # Auto-generate description_html from description if needed + if "description" in kwargs and kwargs["description"]: + if "description_html" not in kwargs or not kwargs["description_html"]: + kwargs["description_html"] = f"{kwargs["description"]}
" + + # Remove icon_prop and logo_props - SDK auto-generates these and ignores user input + kwargs.pop("icon_prop", None) + kwargs.pop("logo_props", None) + + # Strip identifier if provided + if "identifier" in kwargs and kwargs["identifier"]: + kwargs["identifier"] = kwargs["identifier"].strip() + + elif method_key == "retrieve": + # UUID validation + project_id = kwargs.get("project_id", "") + if "{description}
" - elif description_html is not None: - payload["description_html"] = description_html - if project_lead is not None: - payload["project_lead"] = project_lead - if icon_prop is not None: - payload["icon_prop"] = icon_prop - if logo_props is not None: - payload["logo_props"] = logo_props - if icon_prop is not None and logo_props is None: - payload["logo_props"] = icon_prop - if logo_props is not None and icon_prop is None: - payload["icon_prop"] = logo_props - - if emoji is not None: - payload["emoji"] = emoji - if cover_image is not None: - payload["cover_image"] = cover_image - if network is not None: - payload["network"] = network - - # Add other optional fields - if default_assignee is not None: - payload["default_assignee"] = default_assignee - if module_view is not None: - payload["module_view"] = module_view - if cycle_view is not None: - payload["cycle_view"] = cycle_view - if issue_views_view is not None: - payload["issue_views_view"] = issue_views_view - if page_view is not None: - payload["page_view"] = page_view - if intake_view is not None: - payload["intake_view"] = intake_view - if guest_view_all_features is not None: - payload["guest_view_all_features"] = guest_view_all_features - if archive_in is not None: - payload["archive_in"] = archive_in - if close_in is not None: - payload["close_in"] = close_in - if timezone is not None: - payload["timezone"] = timezone - if time_tracking_enabled is not None: - payload["time_tracking_enabled"] = time_tracking_enabled - if is_issue_type_enabled is not None: - payload["is_issue_type_enabled"] = is_issue_type_enabled - - # Try to create project - result = await method_executor.execute("projects", "create", **payload) - - if result["success"]: - return await PlaneToolBase.format_success_payload_with_url( - f"Successfully created project '{name}' with identifier '{base_identifier}'", result["data"], "project", context - ) - else: - # Check if it's a conflict error (name or identifier already taken) - error_msg = result.get("error", "").lower() - if "already taken" in error_msg or "409" in error_msg or "conflict" in error_msg: - # Check if it's a name conflict (more common) vs identifier conflict - if "name" in error_msg and "identifier" not in error_msg: - # Name conflict - inform user to choose a different name - log.info(f"Project name '{name}' already exists. Error: {result["error"]}\nPayload: {payload}") - error_payload: Dict[str, Any] = PlaneToolBase.format_error_payload( - f"Failed to create project: A project with the name '{name}' already exists. Please choose a different name.", - result["error"], - ) - return error_payload - else: - # Identifier conflict - retry with new identifier - new_identifier = PlaneToolBase.generate_fallback_identifier(base_identifier) - payload["identifier"] = new_identifier - retry_result = await method_executor.execute("projects", "create", **payload) - - if retry_result["success"]: - return await PlaneToolBase.format_success_payload_with_url( - f"Successfully created project '{name}' with identifier '{new_identifier}' (original '{base_identifier}' was taken)", - retry_result["data"], - "project", - context, - ) - else: - log.info(f"Failed to create project. Error: {retry_result["error"]}\nPayload: {payload}") - error_payload_retry: Dict[str, Any] = PlaneToolBase.format_error_payload( - "Failed to create project even with alternative identifier", retry_result["error"] - ) - return error_payload_retry - else: - # Check if project was actually created despite the error (e.g. timeout) - try: - # We need to check if the project exists in the DB with the same identifier and workspace_slug - query = """ - SELECT p.id, p.name, p.identifier, p.workspace_id - FROM projects p - JOIN workspaces w ON p.workspace_id = w.id - WHERE p.identifier = $1 AND w.slug = $2 AND p.deleted_at IS NULL - """ - row = await PlaneDBPool.fetchrow(query, (base_identifier, workspace_slug)) - if row: - project_data = { - "id": str(row["id"]), - "name": row["name"], - "identifier": row["identifier"], - "workspace_id": str(row["workspace_id"]), - # Add workspace_slug for context - "workspace_slug": workspace_slug, - } - return await PlaneToolBase.format_success_payload_with_url( - f"Successfully created project '{name}' with identifier '{base_identifier}'", - project_data, - "project", - context, - ) - except Exception as e: - log.error(f"Failed to recover project creation from DB: {e}") - - log.info(f"Failed to create project. Error: {result["error"]}\nPayload: {payload}") - return PlaneToolBase.format_error_payload("Failed to create project", result["error"]) - - @tool - async def projects_list(workspace_slug: Optional[str] = None, per_page: Optional[int] = 20, cursor: Optional[str] = None) -> Dict[str, Any]: - """List projects in the workspace. - - Args: - workspace_slug: Workspace slug (provide if known, otherwise auto-detected) - per_page: Number of projects per page (default: 20, max: 100) - cursor: Pagination cursor for next page - """ - # Auto-fill workspace_slug from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - - result = await method_executor.execute("projects", "list", workspace_slug=workspace_slug, per_page=per_page, cursor=cursor) - - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully retrieved projects list", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to list projects", result["error"]) - - @tool - async def projects_retrieve(project_id: str, workspace_slug: Optional[str] = None) -> Dict[str, Any]: - """Retrieve a single project by ID. - - Args: - project_id: Project ID (required) - workspace_slug: Workspace slug (provide if known, otherwise auto-detected) - """ - # Lightweight validation to prevent bad calls and noisy 404s - # - Reject placeholders like "tags - update_data["description_html"] = f"
{description}
" - elif description_html is not None: - update_data["description_html"] = description_html - if project_lead is not None: - update_data["project_lead"] = project_lead - if icon_prop is not None: - update_data["icon_prop"] = icon_prop - if logo_props is not None: - update_data["logo_props"] = logo_props - if icon_prop is not None and logo_props is None: - update_data["logo_props"] = icon_prop - if logo_props is not None and icon_prop is None: - update_data["icon_prop"] = logo_props - if emoji is not None: - update_data["emoji"] = emoji - if cover_image is not None: - update_data["cover_image"] = cover_image - if network is not None: - update_data["network"] = network - - # Other optional fields - # Plane rejects empty identifier updates; only send when non-empty - if identifier is not None and isinstance(identifier, str) and identifier.strip(): - update_data["identifier"] = identifier.strip() - if default_assignee is not None: - update_data["default_assignee"] = default_assignee - if module_view is not None: - update_data["module_view"] = module_view - if cycle_view is not None: - update_data["cycle_view"] = cycle_view - if issue_views_view is not None: - update_data["issue_views_view"] = issue_views_view - if page_view is not None: - update_data["page_view"] = page_view - if intake_view is not None: - update_data["intake_view"] = intake_view - if is_time_tracking_enabled is not None: - update_data["is_time_tracking_enabled"] = is_time_tracking_enabled - if is_issue_type_enabled is not None: - update_data["is_issue_type_enabled"] = is_issue_type_enabled - if guest_view_all_features is not None: - update_data["guest_view_all_features"] = guest_view_all_features - if archive_in is not None: - update_data["archive_in"] = archive_in - if close_in is not None: - update_data["close_in"] = close_in - if timezone is not None: - update_data["timezone"] = timezone - - result = await method_executor.execute( - "projects", - "update", - project_id=project_id, - workspace_slug=workspace_slug, - **update_data, - ) - - if result["success"]: - return await PlaneToolBase.format_success_payload_with_url("Successfully updated project", result["data"], "project", context) - else: - return PlaneToolBase.format_error_payload("Failed to update project", result["error"]) - - @tool - async def projects_archive(project_id: str, workspace_slug: Optional[str] = None) -> Dict[str, Any]: - """Archive a project. - - Args: - project_id: Project ID (required) - workspace_slug: Workspace slug (provide if known, otherwise auto-detected) - """ - # Auto-fill workspace_slug from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - - result = await method_executor.execute("projects", "archive", project_id=project_id, workspace_slug=workspace_slug) - - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully archived project", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to archive project", result["error"]) - - @tool - async def projects_unarchive(project_id: str, workspace_slug: Optional[str] = None) -> Dict[str, Any]: - """Restore an archived project. - - Args: - project_id: Project ID (required) - workspace_slug: Workspace slug (provide if known, otherwise auto-detected) - """ - # Auto-fill workspace_slug from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - - result = await method_executor.execute("projects", "unarchive", project_id=project_id, workspace_slug=workspace_slug) - - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully unarchived project", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to unarchive project", result["error"]) - - return [ - projects_create, - projects_list, - projects_retrieve, - projects_update, - projects_archive, - projects_unarchive, - ] +# import re +# from pi import logger +# from pi.core.db import PlaneDBPool +# from langchain_core.tools import tool +# from .base import PlaneToolBase +# +# log = logger.getChild(__name__) +# +# def get_project_tools(method_executor, context): +# """Return LangChain tools for the projects category using method_executor and context.""" +# +# [ORIGINAL 525 LINES OF MANUAL @tool DEFINITIONS OMITTED FOR BREVITY] +# [See git history for full original implementation] +# +# return [ +# projects_create, +# projects_list, +# projects_retrieve, +# projects_update, +# projects_delete, +# projects_get_features, +# projects_update_features, +# ] diff --git a/apps/pi/pi/services/actions/tools/properties.py b/apps/pi/pi/services/actions/tools/properties.py index a8b22c1953..872ed8f9ad 100644 --- a/apps/pi/pi/services/actions/tools/properties.py +++ b/apps/pi/pi/services/actions/tools/properties.py @@ -13,498 +13,214 @@ Properties API tools for Plane custom property management. """ -from typing import Any -from typing import Dict -from typing import Optional +from pi.services.actions.tool_generator import generate_tools_for_category +from pi.services.actions.tool_metadata import ToolMetadata +from pi.services.actions.tool_metadata import ToolParameter -from langchain_core.tools import tool +# ============================================================================ +# TOOL METADATA DEFINITIONS +# ============================================================================ -from .base import PlaneToolBase +PROPERTIES_TOOL_DEFINITIONS = { + # ========================================================================== + # Core Property CRUD + # ========================================================================== + "create": ToolMetadata( + name="properties_create", + description="Create a new work item property (custom field) for a specific work item type.", + sdk_method="create_property", + parameters=[ + ToolParameter(name="display_name", type="str", required=True, description="Display name for the property (required)"), + ToolParameter( + name="property_type", + type="str", + required=True, + description="Type of property: TEXT, DATETIME, DECIMAL, BOOLEAN, OPTION, RELATION, URL, EMAIL, FILE", + ), + ToolParameter(name="type_id", type="str", required=True, description="Work item type ID this property belongs to (required)"), + ToolParameter(name="project_id", type="Optional[str]", required=False, description="Project ID", auto_fill_from_context=True), + ToolParameter(name="workspace_slug", type="Optional[str]", required=False, description="Workspace slug", auto_fill_from_context=True), + ToolParameter( + name="relation_type", + type="Optional[str]", + required=False, + description="Relation type for RELATION properties: ONE_TO_ONE, ONE_TO_MANY, MANY_TO_ONE, MANY_TO_MANY", + ), + ToolParameter(name="description", type="Optional[str]", required=False, description="Description of the property"), + ToolParameter(name="is_required", type="Optional[bool]", required=False, description="Whether this property is required for work items"), + ToolParameter(name="default_value", type="Optional[list]", required=False, description="List of default values for the property"), + ToolParameter( + name="settings", + type="Optional[dict]", + required=False, + description="Property settings (TextAttributeSettings for TEXT, DateAttributeSettings for DATETIME)", + ), + ToolParameter(name="is_active", type="Optional[bool]", required=False, description="Whether the property is active"), + ToolParameter(name="is_multi", type="Optional[bool]", required=False, description="Whether this property supports multiple values"), + ToolParameter(name="validation_rules", type="Optional[dict]", required=False, description="Validation rules for the property"), + ToolParameter(name="options", type="Optional[list]", required=False, description="List of options for OPTION type properties"), + ToolParameter( + name="external_source", type="Optional[str]", required=False, description="External system source identifier (e.g., 'github', 'jira')" + ), + ToolParameter(name="external_id", type="Optional[str]", required=False, description="External system's identifier for this property"), + ], + returns_entity_type="property", + ), + "list": ToolMetadata( + name="properties_list", + description="List all work item properties (custom fields) for a specific work item type.", + sdk_method="list_properties", + parameters=[ + ToolParameter(name="type_id", type="str", required=True, description="Work item type ID to list properties for"), + ToolParameter(name="project_id", type="Optional[str]", required=False, description="Project ID", auto_fill_from_context=True), + ToolParameter(name="workspace_slug", type="Optional[str]", required=False, description="Workspace slug", auto_fill_from_context=True), + ], + ), + "retrieve": ToolMetadata( + name="properties_retrieve", + description="Get a single work item property by ID.", + sdk_method="retrieve_property", + parameters=[ + ToolParameter(name="property_id", type="str", required=True, description="Property ID to retrieve"), + ToolParameter(name="type_id", type="str", required=True, description="Work item type ID this property belongs to"), + ToolParameter(name="project_id", type="Optional[str]", required=False, description="Project ID", auto_fill_from_context=True), + ToolParameter(name="workspace_slug", type="Optional[str]", required=False, description="Workspace slug", auto_fill_from_context=True), + ], + ), + "update": ToolMetadata( + name="properties_update", + description="Update work item property details.", + sdk_method="update_property", + parameters=[ + ToolParameter(name="property_id", type="str", required=True, description="Property ID to update"), + ToolParameter(name="type_id", type="str", required=True, description="Work item type ID this property belongs to"), + ToolParameter(name="project_id", type="Optional[str]", required=False, description="Project ID", auto_fill_from_context=True), + ToolParameter(name="workspace_slug", type="Optional[str]", required=False, description="Workspace slug", auto_fill_from_context=True), + ToolParameter(name="display_name", type="Optional[str]", required=False, description="Display name for the property"), + ToolParameter( + name="property_type", + type="Optional[str]", + required=False, + description="Type of property: TEXT, DATETIME, DECIMAL, BOOLEAN, OPTION, RELATION, URL, EMAIL, FILE", + ), + ToolParameter(name="relation_type", type="Optional[str]", required=False, description="Relation type for RELATION properties"), + ToolParameter(name="description", type="Optional[str]", required=False, description="Description of the property"), + ToolParameter(name="is_required", type="Optional[bool]", required=False, description="Whether this property is required"), + ToolParameter(name="default_value", type="Optional[list]", required=False, description="List of default values"), + ToolParameter(name="settings", type="Optional[dict]", required=False, description="Property settings"), + ToolParameter(name="is_active", type="Optional[bool]", required=False, description="Whether the property is active"), + ToolParameter(name="is_multi", type="Optional[bool]", required=False, description="Whether this property supports multiple values"), + ToolParameter(name="validation_rules", type="Optional[dict]", required=False, description="Validation rules"), + ToolParameter(name="external_source", type="Optional[str]", required=False, description="External system source identifier"), + ToolParameter(name="external_id", type="Optional[str]", required=False, description="External system's identifier"), + ], + returns_entity_type="property", + ), + "delete": ToolMetadata( + name="properties_delete", + description="Delete a work item property.", + sdk_method="delete_property", + parameters=[ + ToolParameter(name="property_id", type="str", required=True, description="Property ID to delete"), + ToolParameter(name="type_id", type="str", required=True, description="Work item type ID this property belongs to"), + ToolParameter(name="project_id", type="Optional[str]", required=False, description="Project ID", auto_fill_from_context=True), + ToolParameter(name="workspace_slug", type="Optional[str]", required=False, description="Workspace slug", auto_fill_from_context=True), + ], + returns_entity_type="property", + ), + # ========================================================================== + # Property Options (for OPTION type properties) + # ========================================================================== + "create_option": ToolMetadata( + name="properties_create_option", + description="Create a new option for an OPTION type property.", + sdk_method="create_property_option", + parameters=[ + ToolParameter(name="property_id", type="str", required=True, description="Property ID to add option to"), + ToolParameter(name="type_id", type="str", required=True, description="Work item type ID"), + ToolParameter(name="name", type="str", required=True, description="Option display name"), + ToolParameter(name="project_id", type="Optional[str]", required=False, description="Project ID", auto_fill_from_context=True), + ToolParameter(name="workspace_slug", type="Optional[str]", required=False, description="Workspace slug", auto_fill_from_context=True), + ToolParameter(name="value", type="Optional[str]", required=False, description="Option value (defaults to name if not provided)"), + ], + returns_entity_type="property_option", + ), + "list_options": ToolMetadata( + name="properties_list_options", + description="List all options for an OPTION type property.", + sdk_method="list_property_options", + parameters=[ + ToolParameter(name="property_id", type="str", required=True, description="Property ID to list options for"), + ToolParameter(name="type_id", type="str", required=True, description="Work item type ID"), + ToolParameter(name="project_id", type="Optional[str]", required=False, description="Project ID", auto_fill_from_context=True), + ToolParameter(name="workspace_slug", type="Optional[str]", required=False, description="Workspace slug", auto_fill_from_context=True), + ], + ), + "retrieve_option": ToolMetadata( + name="properties_retrieve_option", + description="Get a property option by ID.", + sdk_method="retrieve_property_option", + parameters=[ + ToolParameter(name="property_id", type="str", required=True, description="Property ID"), + ToolParameter(name="type_id", type="str", required=True, description="Work item type ID"), + ToolParameter(name="option_id", type="str", required=True, description="Option ID to retrieve"), + ToolParameter(name="project_id", type="Optional[str]", required=False, description="Project ID", auto_fill_from_context=True), + ToolParameter(name="workspace_slug", type="Optional[str]", required=False, description="Workspace slug", auto_fill_from_context=True), + ], + ), + "update_option": ToolMetadata( + name="properties_update_option", + description="Update a property option.", + sdk_method="update_property_option", + parameters=[ + ToolParameter(name="property_id", type="str", required=True, description="Property ID"), + ToolParameter(name="type_id", type="str", required=True, description="Work item type ID"), + ToolParameter(name="option_id", type="str", required=True, description="Option ID to update"), + ToolParameter(name="project_id", type="Optional[str]", required=False, description="Project ID", auto_fill_from_context=True), + ToolParameter(name="workspace_slug", type="Optional[str]", required=False, description="Workspace slug", auto_fill_from_context=True), + ToolParameter(name="name", type="Optional[str]", required=False, description="Option display name"), + ToolParameter(name="value", type="Optional[str]", required=False, description="Option value"), + ], + returns_entity_type="property_option", + ), + "delete_option": ToolMetadata( + name="properties_delete_option", + description="Delete a property option.", + sdk_method="delete_property_option", + parameters=[ + ToolParameter(name="property_id", type="str", required=True, description="Property ID"), + ToolParameter(name="type_id", type="str", required=True, description="Work item type ID"), + ToolParameter(name="option_id", type="str", required=True, description="Option ID to delete"), + ToolParameter(name="project_id", type="Optional[str]", required=False, description="Project ID", auto_fill_from_context=True), + ToolParameter(name="workspace_slug", type="Optional[str]", required=False, description="Workspace slug", auto_fill_from_context=True), + ], + returns_entity_type="property_option", + ), + # ========================================================================== + # Property Values (values set on work items) + # ========================================================================== + "create_value": ToolMetadata( + name="properties_create_value", + description='Set a property value on a work item. For simple types (TEXT), provide the value directly. For single-select (OPTION), provide the Option ID. For multi-select, provide a JSON-formatted list of Option IDs (e.g., \'["uuid1", "uuid2"]\').', # noqa: E501 + sdk_method="create_property_value", + parameters=[ + ToolParameter(name="property_id", type="str", required=True, description="Property ID"), + ToolParameter(name="type_id", type="str", required=True, description="Work item type ID"), + ToolParameter(name="issue_id", type="str", required=True, description="Work item ID to set value on"), + ToolParameter(name="value", type="str", required=True, description="Property value (use Option ID for OPTION types)"), + ToolParameter(name="project_id", type="Optional[str]", required=False, description="Project ID", auto_fill_from_context=True), + ToolParameter(name="workspace_slug", type="Optional[str]", required=False, description="Workspace slug", auto_fill_from_context=True), + ], + returns_entity_type="property_value", + ), +} -# Factory wired via CATEGORY_TO_PROVIDER in tools/__init__.py -# Returns LangChain tools implementing property actions + +# ============================================================================ +# TOOL FACTORY +# ============================================================================ def get_property_tools(method_executor, context): - """Return LangChain tools for the properties category using method_executor and context.""" - """Get all Properties API tools.""" - - @tool - async def properties_create( - display_name: str, - property_type: str, - type_id: str, - relation_type: Optional[str] = None, - description: Optional[str] = None, - is_required: Optional[bool] = None, - default_value: Optional[list] = None, - settings: Optional[dict] = None, - is_active: Optional[bool] = None, - is_multi: Optional[bool] = None, - validation_rules: Optional[dict] = None, - external_source: Optional[str] = None, - external_id: Optional[str] = None, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Create a new work item property. - - Args: - display_name: Display name for the property (required) - property_type: Type of property - TEXT, DATETIME, DECIMAL, BOOLEAN, OPTION, RELATION, URL, EMAIL, FILE (required) - type_id: Work item type ID this property belongs to (required) - relation_type: Relation type for RELATION properties - ONE_TO_ONE, ONE_TO_MANY, MANY_TO_ONE, MANY_TO_MANY - description: Description of the property - is_required: Whether this property is required for work items - default_value: List of default values for the property - settings: Property settings (TextAttributeSettings for TEXT, DateAttributeSettings for DATETIME) - is_active: Whether the property is active - is_multi: Whether this property supports multiple values - validation_rules: Validation rules for the property - external_source: External system source identifier (e.g., 'github', 'jira') - external_id: External system's identifier for this property - project_id: Project ID (auto-filled from context if not provided) - workspace_slug: Workspace slug (auto-filled from context if not provided) - """ - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "properties", - "create", - display_name=display_name, - property_type=property_type, - type_id=type_id, - relation_type=relation_type, - description=description, - is_required=is_required, - default_value=default_value, - settings=settings, - is_active=is_active, - is_multi=is_multi, - validation_rules=validation_rules, - external_source=external_source, - external_id=external_id, - project_id=project_id, - workspace_slug=workspace_slug, - ) - if result["success"]: - return PlaneToolBase.format_success_payload(f"Successfully created property '{display_name}'", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to create property", result["error"]) - - @tool - async def properties_list( - type_id: str, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """List all work item properties for a specific work item type. - - Args: - type_id: Work item type ID to list properties for (required) - project_id: Project ID (auto-filled from context if not provided) - workspace_slug: Workspace slug (auto-filled from context if not provided) - """ - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "properties", - "list", - type_id=type_id, - project_id=project_id, - workspace_slug=workspace_slug, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully retrieved properties list", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to list properties", result["error"]) - - @tool - async def properties_retrieve( - property_id: str, - type_id: str, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Get a single work item property by ID. - - Args: - property_id: Property ID to retrieve (required) - type_id: Work item type ID this property belongs to (required) - project_id: Project ID (auto-filled from context if not provided) - workspace_slug: Workspace slug (auto-filled from context if not provided) - """ - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "properties", - "retrieve", - property_id=property_id, - type_id=type_id, - project_id=project_id, - workspace_slug=workspace_slug, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully retrieved property", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to retrieve property", result["error"]) - - @tool - async def properties_update( - property_id: str, - type_id: str, - display_name: Optional[str] = None, - property_type: Optional[str] = None, - relation_type: Optional[str] = None, - description: Optional[str] = None, - is_required: Optional[bool] = None, - default_value: Optional[list] = None, - settings: Optional[dict] = None, - is_active: Optional[bool] = None, - is_multi: Optional[bool] = None, - validation_rules: Optional[dict] = None, - external_source: Optional[str] = None, - external_id: Optional[str] = None, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Update work item property details. - - Args: - property_id: Property ID to update (required) - type_id: Work item type ID this property belongs to (required) - display_name: Display name for the property - property_type: Type of property - TEXT, DATETIME, DECIMAL, BOOLEAN, OPTION, RELATION, URL, EMAIL, FILE - relation_type: Relation type for RELATION properties - ONE_TO_ONE, ONE_TO_MANY, MANY_TO_ONE, MANY_TO_MANY - description: Description of the property - is_required: Whether this property is required for work items - default_value: List of default values for the property - settings: Property settings (TextAttributeSettings for TEXT, DateAttributeSettings for DATETIME) - is_active: Whether the property is active - is_multi: Whether this property supports multiple values - validation_rules: Validation rules for the property - external_source: External system source identifier (e.g., 'github', 'jira') - external_id: External system's identifier for this property - project_id: Project ID (auto-filled from context if not provided) - workspace_slug: Workspace slug (auto-filled from context if not provided) - """ - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - # Build update data - update_data: dict[str, Any] = {} - if display_name is not None: - update_data["display_name"] = display_name - if property_type is not None: - update_data["property_type"] = property_type - if relation_type is not None: - update_data["relation_type"] = relation_type - if description is not None: - update_data["description"] = description - if is_required is not None: - update_data["is_required"] = is_required - if default_value is not None: - update_data["default_value"] = default_value - if settings is not None: - update_data["settings"] = settings - if is_active is not None: - update_data["is_active"] = is_active - if is_multi is not None: - update_data["is_multi"] = is_multi - if validation_rules is not None: - update_data["validation_rules"] = validation_rules - if external_source is not None: - update_data["external_source"] = external_source - if external_id is not None: - update_data["external_id"] = external_id - - result = await method_executor.execute( - "properties", - "update", - property_id=property_id, - type_id=type_id, - project_id=project_id, - workspace_slug=workspace_slug, - **update_data, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully updated property", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to update property", result["error"]) - - @tool - async def properties_delete( - property_id: str, - type_id: str, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Delete a work item property. - - Args: - property_id: Property ID to delete (required) - type_id: Work item type ID this property belongs to (required) - project_id: Project ID (auto-filled from context if not provided) - workspace_slug: Workspace slug (auto-filled from context if not provided) - """ - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "properties", - "delete", - property_id=property_id, - type_id=type_id, - project_id=project_id, - workspace_slug=workspace_slug, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully deleted property", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to delete property", result["error"]) - - @tool - async def properties_create_option( - property_id: str, - type_id: str, - name: str, - value: Optional[str] = None, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Create a property option.""" - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "properties", - "create_option", - property_id=property_id, - type_id=type_id, - name=name, - value=value, - project_id=project_id, - workspace_slug=workspace_slug, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully created property option", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to create property option", result["error"]) - - @tool - async def properties_create_value( - property_id: str, - type_id: str, - issue_id: str, - value: str, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Create a property value.""" - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "properties", - "create_value", - property_id=property_id, - type_id=type_id, - issue_id=issue_id, - value=value, - project_id=project_id, - workspace_slug=workspace_slug, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully created property value", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to create property value", result["error"]) - - @tool - async def properties_list_options( - property_id: str, - type_id: str, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """List property options.""" - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "properties", - "list_options", - property_id=property_id, - type_id=type_id, - project_id=project_id, - workspace_slug=workspace_slug, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully retrieved property options", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to list property options", result["error"]) - - @tool - async def properties_list_values( - type_id: str, - issue_id: str, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """List property values.""" - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "properties", - "list_values", - type_id=type_id, - issue_id=issue_id, - project_id=project_id, - workspace_slug=workspace_slug, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully retrieved property values", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to list property values", result["error"]) - - @tool - async def properties_retrieve_option( - property_id: str, - type_id: str, - option_id: str, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Get property option by ID.""" - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "properties", - "retrieve_option", - property_id=property_id, - type_id=type_id, - option_id=option_id, - project_id=project_id, - workspace_slug=workspace_slug, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully retrieved property option", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to retrieve property option", result["error"]) - - @tool - async def properties_update_option( - property_id: str, - type_id: str, - option_id: str, - name: Optional[str] = None, - value: Optional[str] = None, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Update property option.""" - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - # Build update data - update_data = {} - if name is not None: - update_data["name"] = name - if value is not None: - update_data["value"] = value - - result = await method_executor.execute( - "properties", - "update_option", - property_id=property_id, - type_id=type_id, - option_id=option_id, - project_id=project_id, - workspace_slug=workspace_slug, - **update_data, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully updated property option", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to update property option", result["error"]) - - @tool - async def properties_delete_option( - property_id: str, - type_id: str, - option_id: str, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Delete property option.""" - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "properties", - "delete_option", - property_id=property_id, - type_id=type_id, - option_id=option_id, - project_id=project_id, - workspace_slug=workspace_slug, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully deleted property option", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to delete property option", result["error"]) - - return [ - properties_create, - properties_list, - properties_retrieve, - properties_update, - properties_delete, - properties_create_option, - properties_create_value, - properties_list_options, - properties_list_values, - properties_retrieve_option, - properties_update_option, - properties_delete_option, - ] + """Return LangChain tools for the properties category using auto-generation from metadata.""" + return generate_tools_for_category("properties", method_executor, context, PROPERTIES_TOOL_DEFINITIONS) diff --git a/apps/pi/pi/services/actions/tools/states.py b/apps/pi/pi/services/actions/tools/states.py index 6b618321e5..fd58d67325 100644 --- a/apps/pi/pi/services/actions/tools/states.py +++ b/apps/pi/pi/services/actions/tools/states.py @@ -11,201 +11,372 @@ """ States API tools for Plane workflow state management. + +MIGRATED TO AUTO-GENERATED TOOLS +Tool metadata defined in this file (STATE_TOOL_DEFINITIONS) for modularity. +Old manual definitions kept below for comparison/rollback safety. """ -from typing import Any from typing import Dict -from typing import Optional -from langchain_core.tools import tool +from pi.services.actions.tool_generator import generate_tools_for_category +from pi.services.actions.tool_metadata import ToolMetadata +from pi.services.actions.tool_metadata import ToolParameter -from .base import PlaneToolBase - -# Factory wired via CATEGORY_TO_PROVIDER in tools/__init__.py -# Returns LangChain tools implementing state actions +# Tool metadata for states category +STATE_TOOL_DEFINITIONS: Dict[str, ToolMetadata] = { + "create": ToolMetadata( + name="states_create", + description="Create a new workflow state", + sdk_method="create_state", + returns_entity_type="state", + parameters=[ + ToolParameter(name="name", type="str", required=True, description="State name (required)"), + ToolParameter(name="color", type="str", required=True, description="State color in hex format (required)"), + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID (required - provide from conversation context or previous actions)", + auto_fill_from_context=True, + property_transform="skip", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (provide if known, otherwise auto-detected)", + auto_fill_from_context=True, + property_transform="skip", + ), + ToolParameter(name="description", type="Optional[str]", required=False, description="State description", property_transform="name"), + ToolParameter( + name="group", + type="Optional[str]", + required=False, + description="State group (backlog, unstarted, started, completed, cancelled)", + property_transform="name", + ), + ToolParameter(name="sequence", type="Optional[int]", required=False, description="Display sequence order", property_transform="name"), + ToolParameter( + name="is_triage", type="Optional[bool]", required=False, description="Whether this is a triage state", property_transform="name" + ), + ToolParameter( + name="default", type="Optional[bool]", required=False, description="Whether this is the default state", property_transform="name" + ), + ToolParameter( + name="external_source", + type="Optional[str]", + required=False, + description='External source identifier (e.g., "jira")', + property_transform="name", + ), + ToolParameter(name="external_id", type="Optional[str]", required=False, description="External system ID", property_transform="name"), + ], + ), + "list": ToolMetadata( + name="states_list", + description="List all workflow states in a project", + sdk_method="list_states", + parameters=[ + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID (required - provide from conversation context or previous actions)", + auto_fill_from_context=True, + property_transform="skip", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (provide if known, otherwise auto-detected)", + auto_fill_from_context=True, + property_transform="skip", + ), + ], + ), + "retrieve": ToolMetadata( + name="states_retrieve", + description="Retrieve details of a specific workflow state", + sdk_method="retrieve_state", + parameters=[ + ToolParameter(name="state_id", type="str", required=True, description="State ID (required)"), + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID (required - provide from conversation context or previous actions)", + auto_fill_from_context=True, + property_transform="skip", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (provide if known, otherwise auto-detected)", + auto_fill_from_context=True, + property_transform="skip", + ), + ], + ), + "update": ToolMetadata( + name="states_update", + description="Update an existing workflow state", + sdk_method="update_state", + returns_entity_type="state", + parameters=[ + ToolParameter(name="state_id", type="str", required=True, description="State ID (required)"), + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID (required - provide from conversation context or previous actions)", + auto_fill_from_context=True, + property_transform="skip", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (provide if known, otherwise auto-detected)", + auto_fill_from_context=True, + property_transform="skip", + ), + ToolParameter(name="name", type="Optional[str]", required=False, description="New state name", property_transform="name"), + ToolParameter(name="color", type="Optional[str]", required=False, description="New state color", property_transform="name"), + ToolParameter(name="description", type="Optional[str]", required=False, description="New state description", property_transform="name"), + ToolParameter(name="sequence", type="Optional[int]", required=False, description="Display sequence order", property_transform="name"), + ToolParameter( + name="group", + type="Optional[str]", + required=False, + description="State group (backlog, unstarted, started, completed, cancelled)", + property_transform="name", + ), + ToolParameter( + name="is_triage", type="Optional[bool]", required=False, description="Whether this is a triage state", property_transform="name" + ), + ToolParameter( + name="default", type="Optional[bool]", required=False, description="Whether this is the default state", property_transform="name" + ), + ToolParameter( + name="external_source", + type="Optional[str]", + required=False, + description='External source identifier (e.g., "jira")', + property_transform="name", + ), + ToolParameter(name="external_id", type="Optional[str]", required=False, description="External system ID", property_transform="name"), + ], + ), +} def get_state_tools(method_executor, context): - """Return LangChain tools for the states category using method_executor and context.""" + """Return LangChain tools for the states category using auto-generation from metadata.""" - @tool - async def states_create( - name: str, - color: str, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - description: Optional[str] = None, - group: Optional[str] = None, - sequence: Optional[int] = None, - is_triage: Optional[bool] = None, - default: Optional[bool] = None, - external_source: Optional[str] = None, - external_id: Optional[str] = None, - ) -> Dict[str, Any]: - """Create a new workflow state. + state_tools = generate_tools_for_category( + category="states", + method_executor=method_executor, + context=context, + tool_definitions=STATE_TOOL_DEFINITIONS, + ) - Args: - name: State name (required) - color: State color in hex format (required) - project_id: Project ID (required - provide from conversation context or previous actions) - workspace_slug: Workspace slug (provide if known, otherwise auto-detected) - description: State description - group: State group (backlog, unstarted, started, completed, cancelled) - sequence: Display sequence order - is_triage: Whether this is a triage state - default: Whether this is the default state - external_source: External source identifier (e.g., "jira") - external_id: External system ID - """ - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] + return state_tools - result = await method_executor.execute( - "states", - "create", - name=name, - color=color, - project_id=project_id, - workspace_slug=workspace_slug, - description=description, - group=group, - sequence=sequence, - is_triage=is_triage, - default=default, - external_source=external_source, - external_id=external_id, - ) - if result["success"]: - return await PlaneToolBase.format_success_payload_with_url(f"Successfully created state '{name}'", result["data"], "state", context) - else: - return PlaneToolBase.format_error_payload("Failed to create state", result["error"]) +# ============================================================================ +# OLD MANUAL TOOL DEFINITIONS (COMMENTED OUT - KEPT FOR COMPARISON) +# To rollback: uncomment below and comment out the auto-generation code above +# ============================================================================ - @tool - async def states_list( - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """List all workflow states in a project.""" - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "states", - "list", - project_id=project_id, - workspace_slug=workspace_slug, - ) - - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully retrieved states list", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to list states", result["error"]) - - @tool - async def states_retrieve( - state_id: str, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Retrieve details of a specific workflow state. - - Args: - state_id: State ID (required) - project_id: Project ID (required - provide from conversation context or previous actions) - workspace_slug: Workspace slug (provide if known, otherwise auto-detected) - """ - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "states", - "retrieve", - state_id=state_id, - project_id=project_id, - workspace_slug=workspace_slug, - ) - - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully retrieved state details", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to retrieve state", result["error"]) - - @tool - async def states_update( - state_id: str, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - name: Optional[str] = None, - color: Optional[str] = None, - description: Optional[str] = None, - sequence: Optional[int] = None, - group: Optional[str] = None, - is_triage: Optional[bool] = None, - default: Optional[bool] = None, - external_source: Optional[str] = None, - external_id: Optional[str] = None, - ) -> Dict[str, Any]: - """Update an existing workflow state. - - Args: - state_id: State ID (required) - name: New state name - color: New state color - description: New state description - sequence: Display sequence order - group: State group (backlog, unstarted, started, completed, cancelled) - is_triage: Whether this is a triage state - default: Whether this is the default state - external_source: External source identifier (e.g., "jira") - external_id: External system ID - project_id: Project ID (required - provide from conversation context or previous actions) - workspace_slug: Workspace slug (provide if known, otherwise auto-detected) - """ - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - # Build update data with only non-None values - update_data = { - k: v - for k, v in { - "name": name, - "color": color, - "description": description, - "sequence": sequence, - "group": group, - "is_triage": is_triage, - "default": default, - "external_source": external_source, - "external_id": external_id, - }.items() - if v is not None - } - - result = await method_executor.execute( - "states", - "update", - state_id=state_id, - project_id=project_id, - workspace_slug=workspace_slug, - **update_data, - ) - - if result["success"]: - return await PlaneToolBase.format_success_payload_with_url(f"Successfully updated state '{state_id}'", result["data"], "state", context) - else: - return PlaneToolBase.format_error_payload("Failed to update state", result["error"]) - - return [states_create, states_list, states_retrieve, states_update] +# from typing import Optional +# from langchain_core.tools import tool +# from .base import PlaneToolBase +# +# def get_state_tools(method_executor, context): +# """Return LangChain tools for the states category using method_executor and context.""" +# +# @tool +# async def states_create( +# name: str, +# color: str, +# project_id: Optional[str] = None, +# workspace_slug: Optional[str] = None, +# description: Optional[str] = None, +# group: Optional[str] = None, +# sequence: Optional[int] = None, +# is_triage: Optional[bool] = None, +# default: Optional[bool] = None, +# external_source: Optional[str] = None, +# external_id: Optional[str] = None, +# ) -> Dict[str, Any]: +# """Create a new workflow state. +# +# Args: +# name: State name (required) +# color: State color in hex format (required) +# project_id: Project ID (required - provide from conversation context or previous actions) +# workspace_slug: Workspace slug (provide if known, otherwise auto-detected) +# description: State description +# group: State group (backlog, unstarted, started, completed, cancelled) +# sequence: Display sequence order +# is_triage: Whether this is a triage state +# default: Whether this is the default state +# external_source: External source identifier (e.g., "jira") +# external_id: External system ID +# """ +# # Auto-fill from context if not provided +# if workspace_slug is None and "workspace_slug" in context: +# workspace_slug = context["workspace_slug"] +# if project_id is None and "project_id" in context: +# project_id = context["project_id"] +# +# result = await method_executor.execute( +# "states", +# "create", +# name=name, +# color=color, +# project_id=project_id, +# workspace_slug=workspace_slug, +# description=description, +# group=group, +# sequence=sequence, +# is_triage=is_triage, +# default=default, +# external_source=external_source, +# external_id=external_id, +# ) +# +# if result["success"]: +# return await PlaneToolBase.format_success_payload_with_url(f"Successfully created state '{name}'", result["data"], "state", context) +# else: +# return PlaneToolBase.format_error_payload("Failed to create state", result["error"]) +# +# @tool +# async def states_list( +# project_id: Optional[str] = None, +# workspace_slug: Optional[str] = None, +# ) -> Dict[str, Any]: +# """List all workflow states in a project.""" +# # Auto-fill from context if not provided +# if workspace_slug is None and "workspace_slug" in context: +# workspace_slug = context["workspace_slug"] +# if project_id is None and "project_id" in context: +# project_id = context["project_id"] +# +# result = await method_executor.execute( +# "states", +# "list", +# project_id=project_id, +# workspace_slug=workspace_slug, +# ) +# +# if result["success"]: +# return PlaneToolBase.format_success_payload("Successfully retrieved states list", result["data"]) +# else: +# return PlaneToolBase.format_error_payload("Failed to list states", result["error"]) +# +# @tool +# async def states_retrieve( +# state_id: str, +# project_id: Optional[str] = None, +# workspace_slug: Optional[str] = None, +# ) -> Dict[str, Any]: +# """Retrieve details of a specific workflow state. +# +# Args: +# state_id: State ID (required) +# project_id: Project ID (required - provide from conversation context or previous actions) +# workspace_slug: Workspace slug (provide if known, otherwise auto-detected) +# """ +# # Auto-fill from context if not provided +# if workspace_slug is None and "workspace_slug" in context: +# workspace_slug = context["workspace_slug"] +# if project_id is None and "project_id" in context: +# project_id = context["project_id"] +# +# result = await method_executor.execute( +# "states", +# "retrieve", +# state_id=state_id, +# project_id=project_id, +# workspace_slug=workspace_slug, +# ) +# +# if result["success"]: +# return PlaneToolBase.format_success_payload("Successfully retrieved state details", result["data"]) +# else: +# return PlaneToolBase.format_error_payload("Failed to retrieve state", result["error"]) +# +# @tool +# async def states_update( +# state_id: str, +# project_id: Optional[str] = None, +# workspace_slug: Optional[str] = None, +# name: Optional[str] = None, +# color: Optional[str] = None, +# description: Optional[str] = None, +# sequence: Optional[int] = None, +# group: Optional[str] = None, +# is_triage: Optional[bool] = None, +# default: Optional[bool] = None, +# external_source: Optional[str] = None, +# external_id: Optional[str] = None, +# ) -> Dict[str, Any]: +# """Update an existing workflow state. +# +# Args: +# state_id: State ID (required) +# name: New state name +# color: New state color +# description: New state description +# sequence: Display sequence order +# group: State group (backlog, unstarted, started, completed, cancelled) +# is_triage: Whether this is a triage state +# default: Whether this is the default state +# external_source: External source identifier (e.g., "jira") +# external_id: External system ID +# project_id: Project ID (required - provide from conversation context or previous actions) +# workspace_slug: Workspace slug (provide if known, otherwise auto-detected) +# """ +# # Auto-fill from context if not provided +# if workspace_slug is None and "workspace_slug" in context: +# workspace_slug = context["workspace_slug"] +# if project_id is None and "project_id" in context: +# project_id = context["project_id"] +# +# # Build update data with only non-None values +# update_data = { +# k: v +# for k, v in { +# "name": name, +# "color": color, +# "description": description, +# "sequence": sequence, +# "group": group, +# "is_triage": is_triage, +# "default": default, +# "external_source": external_source, +# "external_id": external_id, +# }.items() +# if v is not None +# } +# +# result = await method_executor.execute( +# "states", +# "update", +# state_id=state_id, +# project_id=project_id, +# workspace_slug=workspace_slug, +# **update_data, +# ) +# +# if result["success"]: +# return await PlaneToolBase.format_success_payload_with_url(f"Successfully updated state '{state_id}'", result["data"], "state", context) +# else: +# return PlaneToolBase.format_error_payload("Failed to update state", result["error"]) +# +# return [states_create, states_list, states_retrieve, states_update] diff --git a/apps/pi/pi/services/actions/tools/stickies.py b/apps/pi/pi/services/actions/tools/stickies.py new file mode 100644 index 0000000000..1f5991ad3f --- /dev/null +++ b/apps/pi/pi/services/actions/tools/stickies.py @@ -0,0 +1,242 @@ +# SPDX-FileCopyrightText: 2023-present Plane Software, Inc. +# SPDX-License-Identifier: LicenseRef-Plane-Commercial +# +# Licensed under the Plane Commercial License (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# https://plane.so/legals/eula +# +# DO NOT remove or modify this notice. +# NOTICE: Proprietary and confidential. Unauthorized use or distribution is prohibited. + +""" +Stickies API tools for Plane quick notes operations. +""" + +from typing import Any +from typing import Dict + +from pi.services.actions.tool_generator import generate_tools_for_category +from pi.services.actions.tool_metadata import ToolMetadata +from pi.services.actions.tool_metadata import ToolParameter + +# ============================================================================ +# STICKIES-SPECIFIC HANDLER FUNCTIONS +# ============================================================================ + + +async def _stickies_pre_handler( + metadata: ToolMetadata, + kwargs: Dict[str, Any], + context: Dict[str, Any], + category: str, + method_key: str, + method_executor: Any = None, +) -> Dict[str, Any]: + """Pre-processing handler for stickies tools. + + Handles: + - Auto-generate description_html from description if not provided + """ + # If description is provided but description_html is not, auto-generate HTML version + # The UI displays description_html, so we need to ensure it's populated + if method_key in ["create", "update"]: + if "description" in kwargs and kwargs["description"] is not None: + if "description_html" not in kwargs or kwargs.get("description_html") is None: + # Convert plain text to simple HTML paragraph + # Escape HTML special characters and preserve line breaks + import html + + escaped_description = html.escape(kwargs["description"]) + # Replace newlines with{escaped_description}
" + + return kwargs + + +# ============================================================================ +# STICKIES TOOL DEFINITIONS +# ============================================================================ + +STICKY_TOOL_DEFINITIONS: Dict[str, ToolMetadata] = { + "create": ToolMetadata( + name="stickies_create", + description="Create a new sticky note for quick annotations. The main content/text should go in 'description' parameter.", + sdk_method="create_sticky", + returns_entity_type="sticky", + pre_handler=_stickies_pre_handler, + parameters=[ + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ToolParameter( + name="name", + type="Optional[str]", + required=False, + description="Optional title/heading for the sticky note", + ), + ToolParameter( + name="description", + type="Optional[str]", + required=False, + description="Main content/text of the sticky note (use this for user's content)", + ), + ToolParameter( + name="description_html", + type="Optional[str]", + required=False, + description="HTML formatted content (optional, auto-generated from description if not provided)", + ), + ToolParameter( + name="color", + type="Optional[str]", + required=False, + description="Text color hex code (optional)", + ), + ToolParameter( + name="background_color", + type="Optional[str]", + required=False, + description="Background color hex code (optional)", + ), + ToolParameter( + name="logo_props", + type="Optional[dict]", + required=False, + description="Logo configuration JSON (optional)", + ), + ], + ), + "list": ToolMetadata( + name="stickies_list", + description="List all sticky notes in the workspace", + sdk_method="list_stickies", + parameters=[ + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ], + ), + "retrieve": ToolMetadata( + name="stickies_retrieve", + description="Retrieve a single sticky note by ID", + sdk_method="retrieve_sticky", + parameters=[ + ToolParameter( + name="sticky_id", + type="str", + required=True, + description="Sticky ID (required)", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ], + ), + "update": ToolMetadata( + name="stickies_update", + description="Update sticky note details", + sdk_method="update_sticky", + returns_entity_type="sticky", + pre_handler=_stickies_pre_handler, + parameters=[ + ToolParameter( + name="sticky_id", + type="str", + required=True, + description="Sticky ID (required)", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ToolParameter( + name="name", + type="Optional[str]", + required=False, + description="New sticky note title", + ), + ToolParameter( + name="description", + type="Optional[str]", + required=False, + description="New plain text description", + ), + ToolParameter( + name="description_html", + type="Optional[str]", + required=False, + description="New HTML description", + ), + ToolParameter( + name="color", + type="Optional[str]", + required=False, + description="New text color hex code", + ), + ToolParameter( + name="background_color", + type="Optional[str]", + required=False, + description="New background color hex code", + ), + ToolParameter( + name="logo_props", + type="Optional[dict]", + required=False, + description="New logo configuration JSON", + ), + ], + ), + "delete": ToolMetadata( + name="stickies_delete", + description="Delete a sticky note", + sdk_method="delete_sticky", + parameters=[ + ToolParameter( + name="sticky_id", + type="str", + required=True, + description="Sticky ID (required)", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ], + ), +} + + +# ============================================================================ +# TOOL FACTORY +# ============================================================================ + + +def get_sticky_tools(method_executor, context): + """Return LangChain tools for the stickies category using auto-generation from metadata.""" + return generate_tools_for_category( + category="stickies", + method_executor=method_executor, + context=context, + tool_definitions=STICKY_TOOL_DEFINITIONS, + ) diff --git a/apps/pi/pi/services/actions/tools/teamspaces.py b/apps/pi/pi/services/actions/tools/teamspaces.py new file mode 100644 index 0000000000..84f2660b9e --- /dev/null +++ b/apps/pi/pi/services/actions/tools/teamspaces.py @@ -0,0 +1,324 @@ +# SPDX-FileCopyrightText: 2023-present Plane Software, Inc. +# SPDX-License-Identifier: LicenseRef-Plane-Commercial +# +# Licensed under the Plane Commercial License (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# https://plane.so/legals/eula +# +# DO NOT remove or modify this notice. +# NOTICE: Proprietary and confidential. Unauthorized use or distribution is prohibited. + +""" +Teamspaces API tools for Plane team collaboration operations. +""" + +from typing import Dict + +from pi.services.actions.tool_generator import generate_tools_for_category +from pi.services.actions.tool_metadata import ToolMetadata +from pi.services.actions.tool_metadata import ToolParameter + +# ============================================================================ +# TEAMSPACES TOOL DEFINITIONS +# ============================================================================ + +TEAMSPACE_TOOL_DEFINITIONS: Dict[str, ToolMetadata] = { + "create": ToolMetadata( + name="teamspaces_create", + description="Create a new teamspace for team collaboration", + sdk_method="create_teamspace", + returns_entity_type="teamspace", + parameters=[ + ToolParameter( + name="name", + type="str", + required=True, + description="Teamspace name (required)", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ToolParameter( + name="description_html", + type="Optional[str]", + required=False, + description="HTML description of the teamspace", + ), + ToolParameter( + name="logo_props", + type="Optional[dict]", + required=False, + description="Logo configuration JSON", + ), + ToolParameter( + name="lead", + type="str", + required=False, + description="Team lead user ID (optional)", + ), + ], + ), + "list": ToolMetadata( + name="teamspaces_list", + description="List teamspaces in the workspace", + sdk_method="list_teamspaces", + parameters=[ + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ], + ), + "retrieve": ToolMetadata( + name="teamspaces_retrieve", + description="Retrieve a single teamspace by ID", + sdk_method="retrieve_teamspace", + parameters=[ + ToolParameter( + name="teamspace_id", + type="str", + required=True, + description="Teamspace ID (required)", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ], + ), + "update": ToolMetadata( + name="teamspaces_update", + description="Update teamspace details", + sdk_method="update_teamspace", + returns_entity_type="teamspace", + parameters=[ + ToolParameter( + name="teamspace_id", + type="str", + required=True, + description="Teamspace ID (required)", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ToolParameter( + name="name", + type="Optional[str]", + required=False, + description="New teamspace name", + ), + ToolParameter( + name="description_html", + type="Optional[str]", + required=False, + description="New HTML description", + ), + ToolParameter( + name="logo_props", + type="Optional[dict]", + required=False, + description="New logo configuration JSON", + ), + ToolParameter( + name="lead", + type="str", + required=False, + description="Team lead user ID (use empty string to remove the lead)", + ), + ], + ), + "delete": ToolMetadata( + name="teamspaces_delete", + description="Delete a teamspace", + sdk_method="delete_teamspace", + parameters=[ + ToolParameter( + name="teamspace_id", + type="str", + required=True, + description="Teamspace ID (required)", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ], + ), + "add_members": ToolMetadata( + name="teamspaces_add_members", + description="Add members to a teamspace", + sdk_method="add_teamspace_members", + parameters=[ + ToolParameter( + name="teamspace_id", + type="str", + required=True, + description="Teamspace ID (required)", + ), + ToolParameter( + name="member_ids", + type="List[str]", + required=True, + description="List of member (user) IDs to add (required)", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ], + ), + "list_members": ToolMetadata( + name="teamspaces_list_members", + description="List members in a teamspace", + sdk_method="list_teamspace_members", + parameters=[ + ToolParameter( + name="teamspace_id", + type="str", + required=True, + description="Teamspace ID (required)", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ], + ), + "remove_members": ToolMetadata( + name="teamspaces_remove_members", + description="Remove members from a teamspace", + sdk_method="remove_teamspace_members", + parameters=[ + ToolParameter( + name="teamspace_id", + type="str", + required=True, + description="Teamspace ID (required)", + ), + ToolParameter( + name="member_ids", + type="List[str]", + required=True, + description="List of member (user) IDs to remove (required)", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ], + ), + "add_projects": ToolMetadata( + name="teamspaces_add_projects", + description="Add projects to a teamspace", + sdk_method="add_teamspace_projects", + parameters=[ + ToolParameter( + name="teamspace_id", + type="str", + required=True, + description="Teamspace ID (required)", + ), + ToolParameter( + name="project_ids", + type="List[str]", + required=True, + description="List of project IDs to add (required)", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ], + ), + "list_projects": ToolMetadata( + name="teamspaces_list_projects", + description="List projects in a teamspace", + sdk_method="list_teamspace_projects", + parameters=[ + ToolParameter( + name="teamspace_id", + type="str", + required=True, + description="Teamspace ID (required)", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ], + ), + "remove_projects": ToolMetadata( + name="teamspaces_remove_projects", + description="Remove projects from a teamspace", + sdk_method="remove_teamspace_projects", + parameters=[ + ToolParameter( + name="teamspace_id", + type="str", + required=True, + description="Teamspace ID (required)", + ), + ToolParameter( + name="project_ids", + type="List[str]", + required=True, + description="List of project IDs to remove (required)", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ], + ), +} + + +# ============================================================================ +# TOOL FACTORY +# ============================================================================ + + +def get_teamspace_tools(method_executor, context): + """Return LangChain tools for the teamspaces category using auto-generation from metadata.""" + return generate_tools_for_category( + category="teamspaces", + method_executor=method_executor, + context=context, + tool_definitions=TEAMSPACE_TOOL_DEFINITIONS, + ) diff --git a/apps/pi/pi/services/actions/tools/types.py b/apps/pi/pi/services/actions/tools/types.py index 007a570894..25bde92119 100644 --- a/apps/pi/pi/services/actions/tools/types.py +++ b/apps/pi/pi/services/actions/tools/types.py @@ -13,197 +13,158 @@ Types API tools for Plane issue type management. """ -from typing import Any from typing import Dict -from typing import Optional -from langchain_core.tools import tool +from pi.services.actions.tool_generator import generate_tools_for_category +from pi.services.actions.tool_metadata import ToolMetadata +from pi.services.actions.tool_metadata import ToolParameter -from .base import PlaneToolBase +# ============================================================================ +# TYPES TOOL DEFINITIONS +# ============================================================================ -# Factory wired via CATEGORY_TO_PROVIDER in tools/__init__.py -# Returns LangChain tools implementing type actions +TYPE_TOOL_DEFINITIONS: Dict[str, ToolMetadata] = { + "create": ToolMetadata( + name="types_create", + description="Create a new work item type", + sdk_method="create_issue_type", + parameters=[ + ToolParameter(name="name", type="str", required=True, description="Name of the work item type (required)"), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID (auto-detected from context)", + auto_fill_from_context=True, + ), + ToolParameter(name="description", type="Optional[str]", required=False, description="Optional description of the type"), + ToolParameter( + name="project_ids", type="Optional[List[str]]", required=False, description="List of project IDs to associate with this type" + ), + ToolParameter(name="is_epic", type="Optional[bool]", required=False, description="Flag to mark this type as an epic type"), + ToolParameter(name="is_active", type="Optional[bool]", required=False, description="Activation status of the type"), + ToolParameter( + name="external_source", type="Optional[str]", required=False, description="External integration source (e.g., 'jira', 'github')" + ), + ToolParameter(name="external_id", type="Optional[str]", required=False, description="External system identifier for this type"), + ], + ), + "list": ToolMetadata( + name="types_list", + description="List all work item types", + sdk_method="list_issue_types", + parameters=[ + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID (auto-detected from context)", + auto_fill_from_context=True, + ), + ], + ), + "retrieve": ToolMetadata( + name="types_retrieve", + description="Get a single type by ID", + sdk_method="retrieve_issue_type", + parameters=[ + ToolParameter(name="type_id", type="str", required=True, description="Type ID (required)"), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID (auto-detected from context)", + auto_fill_from_context=True, + ), + ], + ), + "update": ToolMetadata( + name="types_update", + description="Update work item type details", + sdk_method="update_issue_type", + parameters=[ + ToolParameter(name="type_id", type="str", required=True, description="UUID of the work item type to update (required)"), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID (auto-detected from context)", + auto_fill_from_context=True, + ), + ToolParameter(name="name", type="Optional[str]", required=False, description="Updated name of the type"), + ToolParameter(name="description", type="Optional[str]", required=False, description="Updated description"), + ToolParameter( + name="project_ids", type="Optional[list[str]]", required=False, description="Updated list of project IDs to associate with this type" + ), + ToolParameter(name="is_epic", type="Optional[bool]", required=False, description="Updated epic type flag"), + ToolParameter(name="is_active", type="Optional[bool]", required=False, description="Updated activation status"), + ToolParameter(name="external_source", type="Optional[str]", required=False, description="Updated external integration source"), + ToolParameter(name="external_id", type="Optional[str]", required=False, description="Updated external system identifier"), + ], + ), + "delete": ToolMetadata( + name="types_delete", + description="Delete a type", + sdk_method="delete_issue_type", + parameters=[ + ToolParameter(name="type_id", type="str", required=True, description="Type ID (required)"), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID (auto-detected from context)", + auto_fill_from_context=True, + ), + ], + ), +} + + +# ============================================================================ +# TOOL FACTORY +# ============================================================================ def get_type_tools(method_executor, context): - """Return LangChain tools for the types category using method_executor and context.""" - """Get all Types API tools.""" - - @tool - async def types_create( - name: str, - description: Optional[str] = None, - project_ids: Optional[list[str]] = None, - is_epic: Optional[bool] = None, - is_active: Optional[bool] = None, - external_source: Optional[str] = None, - external_id: Optional[str] = None, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Create a new work item type. - - Args: - name: Name of the work item type (required) - description: Optional description of the type - project_ids: List of project IDs to associate with this type - is_epic: Flag to mark this type as an epic type - is_active: Activation status of the type - external_source: External integration source (e.g., 'jira', 'github') - external_id: External system identifier for this type - project_id: UUID of the project (auto-filled from context) - workspace_slug: Workspace slug identifier (auto-filled from context) - """ - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "types", - "create", - name=name, - description=description, - project_ids=project_ids, - is_epic=is_epic, - is_active=is_active, - external_source=external_source, - external_id=external_id, - project_id=project_id, - workspace_slug=workspace_slug, - ) - if result["success"]: - return PlaneToolBase.format_success_payload(f"Successfully created type '{name}'", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to create type", result["error"]) - - @tool - async def types_list(project_id: Optional[str] = None, workspace_slug: Optional[str] = None) -> Dict[str, Any]: - """List all work item types.""" - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute("types", "list", project_id=project_id, workspace_slug=workspace_slug) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully retrieved types list", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to list types", result["error"]) - - @tool - async def types_retrieve( - type_id: str, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Get a single type by ID.""" - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "types", - "retrieve", - type_id=type_id, - project_id=project_id, - workspace_slug=workspace_slug, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully retrieved type", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to retrieve type", result["error"]) - - @tool - async def types_update( - type_id: str, - name: Optional[str] = None, - description: Optional[str] = None, - project_ids: Optional[list[str]] = None, - is_epic: Optional[bool] = None, - is_active: Optional[bool] = None, - external_source: Optional[str] = None, - external_id: Optional[str] = None, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Update work item type details. - - Args: - type_id: UUID of the work item type to update (required) - name: Updated name of the type - description: Updated description - project_ids: Updated list of project IDs to associate with this type - is_epic: Updated epic type flag - is_active: Updated activation status - external_source: Updated external integration source - external_id: Updated external system identifier - project_id: UUID of the project (auto-filled from context) - workspace_slug: Workspace slug identifier (auto-filled from context) - """ - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - # Build update data - update_data: dict[str, Any] = {} - if name is not None: - update_data["name"] = name - if description is not None: - update_data["description"] = description - if project_ids is not None: - update_data["project_ids"] = project_ids - if is_epic is not None: - update_data["is_epic"] = is_epic - if is_active is not None: - update_data["is_active"] = is_active - if external_source is not None: - update_data["external_source"] = external_source - if external_id is not None: - update_data["external_id"] = external_id - - result = await method_executor.execute( - "types", - "update", - type_id=type_id, - project_id=project_id, - workspace_slug=workspace_slug, - **update_data, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully updated type", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to update type", result["error"]) - - @tool - async def types_delete( - type_id: str, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Delete a type.""" - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "types", - "delete", - type_id=type_id, - project_id=project_id, - workspace_slug=workspace_slug, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully deleted type", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to delete type", result["error"]) - - return [types_create, types_list, types_retrieve, types_update, types_delete] + """Return LangChain tools for the types category using auto-generation from metadata.""" + return generate_tools_for_category( + category="types", + method_executor=method_executor, + context=context, + tool_definitions=TYPE_TOOL_DEFINITIONS, + ) diff --git a/apps/pi/pi/services/actions/tools/users.py b/apps/pi/pi/services/actions/tools/users.py index f36bd50d80..2642e10c76 100644 --- a/apps/pi/pi/services/actions/tools/users.py +++ b/apps/pi/pi/services/actions/tools/users.py @@ -11,29 +11,59 @@ """ Users API tools for Plane user management operations. + +MIGRATED TO AUTO-GENERATED TOOLS +Tool metadata defined in this file (USER_TOOL_DEFINITIONS) for modularity. +Old manual definitions kept below for comparison/rollback safety. """ -from typing import Any from typing import Dict -from langchain_core.tools import tool +from pi.services.actions.tool_generator import generate_tools_for_category +from pi.services.actions.tool_metadata import ToolMetadata -from .base import PlaneToolBase - -# Factory wired via CATEGORY_TO_PROVIDER in tools/__init__.py -# Returns LangChain tools implementing user actions +# Tool metadata for users category +USER_TOOL_DEFINITIONS: Dict[str, ToolMetadata] = { + "get_current_user": ToolMetadata( + name="users_get_current", + description="Get current user information", + sdk_method="get_current_user", + parameters=[], + ), +} def get_user_tools(method_executor, context): - """Return LangChain tools for the users category using method_executor and context.""" + """Return LangChain tools for the users category using auto-generation from metadata.""" - @tool - async def users_get_current() -> Dict[str, Any]: - """Get current user information.""" - result = await method_executor.execute("users", "get_current") - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully retrieved current user", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to get current user", result["error"]) + user_tools = generate_tools_for_category( + category="users", + method_executor=method_executor, + context=context, + tool_definitions=USER_TOOL_DEFINITIONS, + ) - return [users_get_current] + return user_tools + + +# ============================================================================ +# OLD MANUAL TOOL DEFINITIONS (COMMENTED OUT - KEPT FOR COMPARISON) +# To rollback: uncomment below and comment out the auto-generation code above +# ============================================================================ + +# from langchain_core.tools import tool +# from .base import PlaneToolBase +# +# def get_user_tools(method_executor, context): +# """Return LangChain tools for the users category using method_executor and context.""" +# +# @tool +# async def users_get_current() -> Dict[str, Any]: +# """Get current user information.""" +# result = await method_executor.execute("users", "get_current") +# if result["success"]: +# return PlaneToolBase.format_success_payload("Successfully retrieved current user", result["data"]) +# else: +# return PlaneToolBase.format_error_payload("Failed to get current user", result["error"]) +# +# return [users_get_current] diff --git a/apps/pi/pi/services/actions/tools/workitems.py b/apps/pi/pi/services/actions/tools/workitems.py index 5b1640b32d..a6f057287d 100644 --- a/apps/pi/pi/services/actions/tools/workitems.py +++ b/apps/pi/pi/services/actions/tools/workitems.py @@ -11,18 +11,22 @@ """ Work Items API tools for Plane issue/task management operations. + +MIGRATED TO AUTO-GENERATED TOOLS +Tool metadata defined in this file. Custom pre/post handlers for complex logic. +Special handling includes: state/type resolution, epic type injection, identifier enrichment, relation validation. +Old manual definitions kept below for comparison/rollback safety. """ import logging import uuid from typing import Any from typing import Dict -from typing import List from typing import Optional -from langchain_core.tools import tool - -from .base import PlaneToolBase +from pi.services.actions.tool_generator import generate_tools_for_category +from pi.services.actions.tool_metadata import ToolMetadata +from pi.services.actions.tool_metadata import ToolParameter log = logging.getLogger(__name__) @@ -38,8 +42,10 @@ RELATION_TYPES = { "finish_after": "finish_after", } -# Factory wired via CATEGORY_TO_PROVIDER in tools/__init__.py -# Returns LangChain tools implementing work-item actions + +# ============================================================================ +# HELPER FUNCTIONS (Preserved from original) +# ============================================================================ async def resolve_state_to_uuid(state: Optional[str], project_id: Optional[str], workspace_slug: Optional[str] = None) -> Optional[str]: @@ -159,84 +165,248 @@ async def get_epic_type_id(method_executor, project_id: str, workspace_slug: str return None -def get_workitem_tools(method_executor, context): - """Return LangChain tools for the workitems category using method_executor and context.""" +# ============================================================================ +# WORKITEMS-SPECIFIC HANDLER FUNCTIONS +# ============================================================================ - @tool - async def workitems_create( - name: str, - project_id: Optional[str] = None, - description_html: Optional[str] = None, - priority: Optional[str] = None, - state: Optional[str] = None, - assignees: Optional[List[str]] = None, - labels: Optional[List[str]] = None, - start_date: Optional[str] = None, - target_date: Optional[str] = None, - type_id: Optional[str] = None, - parent: Optional[str] = None, - external_id: Optional[str] = None, - external_source: Optional[str] = None, - is_draft: Optional[bool] = None, - ) -> Dict[str, Any]: - """Create a new work item/issue. - Args: - name: Work item title (required) - project_id: Project ID (required - provide from conversation context or previous actions) - workspace_slug: Workspace slug (required - provide from conversation context) - description_html: Workitem description in HTML format - priority: Priority level (high, medium, low, urgent, none) - state: State name or UUID for the workitem (e.g., "todo", "in progress", "done") - assignees: List of assignee user IDs - labels: List of label IDs - start_date: Start date (YYYY-MM-DD format) - target_date: Target completion date (YYYY-MM-DD format) - type_id: Workitem type ID (optional). MUST be the 'issue_types_id' (UUID of the issue type definition), NOT the 'project_issue_types_id'. - parent: Parent work-item ID (optional) - external_id: External system identifier (optional) - external_source: External system source name (optional) - is_draft: Create as draft (optional) +# ============================================================================ +# HELPER FUNCTIONS +# ============================================================================ - Note: To add the created work item to a module or cycle, use modules_add_work_items - or cycles_add_work_items after creation. These cannot be set during creation. - """ - # Auto-fill workspace_slug from context (hidden from LLM) - workspace_slug = context.get("workspace_slug") - # Auto-fill project_id from context if not provided - if project_id is None and "project_id" in context: - project_id = context["project_id"] +async def fetch_available_types_for_project(method_executor, project_id: str, workspace_slug: str) -> Optional[str]: + """Fetch available work item types for a project and format them for LLM consumption. - # Resolve state name to UUID if needed - resolved_state = await resolve_state_to_uuid(state, project_id, workspace_slug) + This helper is used to enrich tool descriptions with project-specific type information + during tool generation (at planning time), making types visible to the LLM. - # Resolve type name to UUID if needed - resolved_type_id = await resolve_type_to_uuid(type_id, project_id, workspace_slug) + Args: + method_executor: The method executor to call types API + project_id: Project UUID + workspace_slug: Workspace slug + Returns: + Formatted string of available types, or None if fetch fails + Example: "- Bug (ID: 6e8fbc42...): Defects and regressions\\n- Feature (ID: 104eb637...): New functionality" + """ + if not project_id or not workspace_slug or not method_executor: + return None + + try: result = await method_executor.execute( - "workitems", - "create", - name=name, - description_html=description_html, + "types", + "list", project_id=project_id, workspace_slug=workspace_slug, - priority=priority, - state=resolved_state, - assignees=assignees, - labels=labels, - start_date=start_date, - target_date=target_date, - type_id=resolved_type_id, - parent=parent, - external_id=external_id, - external_source=external_source, - is_draft=is_draft, ) - if result["success"]: - # Enrich response data with missing fields for URL construction - data = result["data"] + if not result or not result.get("success"): + return None + + results = result.get("data", {}).get("results", []) + if not results: + return None + + # Build a human-readable list of types + type_lines = [] + for t in results[:10]: # Limit to 10 types to avoid overwhelming the description + type_name = t.get("name", "Unknown") + type_id = t.get("id", "") + type_desc = t.get("description", "") + + # Format: "- Bug (ID: 6e8fbc42-2c07-4880-9b65-d3ef8258b784): For defects and issues" + line = f"- {type_name}" + if type_id: + line += f" (ID: {type_id})" # Full UUID so LLM can use it directly in tool args + if type_desc: + line += f": {type_desc[:80]}" # Limit description length + type_lines.append(line) + + if type_lines: + formatted = "\\n".join(type_lines) + log.info(f"Fetched {len(results)} types for project {project_id}") + return formatted + + except Exception as e: + log.warning(f"Failed to fetch types for project {project_id}: {e}") + + return None + + +def _sync_fetch_types(method_executor, project_id: str, workspace_slug: str) -> Optional[str]: + """Synchronous wrapper to fetch types from async function. + + Bridges the sync/async boundary by running the async fetch function in the event loop. + """ + import asyncio + + try: + # Check if there's a running event loop + try: + asyncio.get_running_loop() + # We're in a running async context - create a task and wait for it + # Using asyncio.ensure_future + loop methods to avoid blocking + import concurrent.futures + + with concurrent.futures.ThreadPoolExecutor() as pool: + future = pool.submit(asyncio.run, fetch_available_types_for_project(method_executor, project_id, workspace_slug)) + return future.result(timeout=5) # 5 second timeout + except RuntimeError: + # No running loop - safe to use asyncio.run() + return asyncio.run(fetch_available_types_for_project(method_executor, project_id, workspace_slug)) + except Exception as e: + log.warning(f"Failed to fetch types for project {project_id}: {e}") + return None + + +def _enrich_type_id_descriptions(tool_definitions: Dict[str, "ToolMetadata"], types_text: str) -> None: + """Inject available types into type_id parameter descriptions. + + Modifies tool definitions in-place to add project-specific type information. + """ + create_desc = ( + f"Work item type to categorize this work item. Available types in this project:\\n{types_text}\\n" + f"Provide the full type ID (UUID) from the list above. If not specified, project's default type will be used." + ) + + update_desc = ( + f"New work item type to categorize this work item. Available types in this project:\\n{types_text}\\n" + f"Provide the full type ID (UUID) from the list above." + ) + + # Update create tool + if "create" in tool_definitions: + for param in tool_definitions["create"].parameters: + if param.name == "type_id": + param.description = create_desc + break + + # Update update tool + if "update" in tool_definitions: + for param in tool_definitions["update"].parameters: + if param.name == "type_id": + param.description = update_desc + break + + +# ============================================================================ +# PRE/POST HANDLERS +# ============================================================================ + + +async def _workitems_pre_handler( + metadata: ToolMetadata, + kwargs: Dict[str, Any], + context: Dict[str, Any], + category: str, + method_key: str, + method_executor: Any = None, +) -> Dict[str, Any]: + """Pre-processing handler for workitems tools. + + Handles: + - create/update/list: state and type resolution + - create_epic: epic type injection + - create_relation: relation type validation + """ + tool_name = metadata.name + project_id = kwargs.get("project_id") + workspace_slug = kwargs.get("workspace_slug") or context.get("workspace_slug") + + # Handle epic tools: inject epic type_id + if tool_name == "create_epic": + if not project_id: + raise ValueError("Project ID is required for epic creation. Please specify a project.") + + epic_type_id = await get_epic_type_id(method_executor, str(project_id), str(workspace_slug or "")) + if not epic_type_id: + raise ValueError("Could not find epic issue type for this project. Please ensure an epic issue type exists.") + + kwargs["type_id"] = epic_type_id + log.info(f"Injected epic type_id {epic_type_id} for create_epic") + + # State resolution for create/update/list/epic tools + if tool_name in ["workitems_create", "workitems_update", "workitems_list", "create_epic", "update_epic"]: + state = kwargs.get("state") + if state: + resolved_state = await resolve_state_to_uuid(state, project_id, workspace_slug) + if resolved_state: + kwargs["state"] = resolved_state + log.debug(f"Resolved state '{state}' to {resolved_state}") + + # Type resolution for create/update (but NOT epics which handle it themselves) + if tool_name in ["workitems_create", "workitems_update"]: + type_id = kwargs.get("type_id") + if type_id: + resolved_type_id = await resolve_type_to_uuid(type_id, project_id, workspace_slug) + if resolved_type_id: + kwargs["type_id"] = resolved_type_id + log.debug(f"Resolved type_id '{type_id}' to {resolved_type_id}") + + # Relation type validation for create_relation + if tool_name == "workitems_create_relation": + relation_type = kwargs.get("relation_type") + if relation_type not in RELATION_TYPES: + valid_types = ", ".join(RELATION_TYPES.keys()) + raise ValueError(f"Relation type '{relation_type}' is not valid. Valid types are: {valid_types}") + + related_issues = kwargs.get("related_issues") + if not related_issues: + raise ValueError("At least one related issue ID must be provided") + + # The SDK expects 'issues' parameter, not 'related_issues' + kwargs["issues"] = kwargs.pop("related_issues") + + # Fix for list: Pass filter args to SDK (BUG FIX) + if tool_name == "workitems_list": + # Build filter arguments and merge them into kwargs + filter_fields = [ + "priority", + "assignees", + "labels", + "start_date", + "target_date", + "created_by", + "updated_by", + "type_id", + "parent", + "is_draft", + "created_at", + "updated_at", + "completed_at", + "archived_at", + ] + + for field in filter_fields: + if field in kwargs and kwargs[field] is not None: + # These are already in kwargs, just ensure they're passed through + pass + + return kwargs + + +async def _workitems_post_handler( + metadata: ToolMetadata, + result: Dict[str, Any], + kwargs: Dict[str, Any], + context: Dict[str, Any], + method_executor: Any, + category: str, + method_key: str, +) -> Dict[str, Any]: + """Post-processing handler for workitems tools. + + Handles: + - create/update/create_epic/update_epic: identifier enrichment for URL construction + - list: URL construction for each workitem in results + """ + tool_name = metadata.name + + # Identifier enrichment for create/update operations + if tool_name in ["workitems_create", "workitems_update", "create_epic", "update_epic"]: + if result.get("success"): + data = result.get("data") if data and isinstance(data, dict) and data.get("id"): try: from pi.app.api.v1.helpers.plane_sql_queries import get_issue_identifier_for_artifact @@ -250,619 +420,805 @@ def get_workitem_tools(method_executor, context): except Exception as e: log.warning(f"Could not enrich workitem data with identifier info: {e}") - return await PlaneToolBase.format_success_payload_with_url( - f"Successfully created work item '{name}'", - data, - "workitem", - context, - ) - else: - return PlaneToolBase.format_error_payload("Failed to create work item", result.get("error")) - - @tool - async def workitems_update( - issue_id: str, - project_id: Optional[str] = None, - name: Optional[str] = None, - description_html: Optional[str] = None, - priority: Optional[str] = None, - state: Optional[str] = None, - assignees: Optional[List[str]] = None, - labels: Optional[List[str]] = None, - start_date: Optional[str] = None, - target_date: Optional[str] = None, - type_id: Optional[str] = None, - parent: Optional[str] = None, - external_id: Optional[str] = None, - external_source: Optional[str] = None, - is_draft: Optional[bool] = None, - ) -> Dict[str, Any]: - """Update an existing work item/issue. - - Args: - issue_id: Work item ID to update (required) - project_id: Project ID (required - provide from conversation context or previous actions) - workspace_slug: Workspace slug (required - provide from conversation context) - name: New work item title - description_html: New description in HTML format - priority: New priority level (high, medium, low, urgent, none) - state: New state name or UUID (e.g., "todo", "in progress", "done") - assignees: New list of assignee user IDs - labels: New list of label IDs - start_date: New start date (YYYY-MM-DD format) - target_date: New target completion date (YYYY-MM-DD format) - type_id: Workitem type ID (optional). MUST be the 'issue_types_id' (UUID of the issue type definition), NOT the 'project_issue_types_id'. - parent: Parent work-item ID (optional) - external_id: External system identifier (optional) - external_source: External system source name (optional) - is_draft: Mark as draft (optional) - - Note: To add/move the work item to a module or cycle, use modules_add_work_items - or cycles_add_work_items. Module/cycle assignment is not supported via update. - """ - # Auto-fill workspace_slug from context (hidden from LLM) - workspace_slug = context.get("workspace_slug") - - # Auto-fill project_id from context if not provided - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - # Resolve state name to UUID if needed - resolved_state = await resolve_state_to_uuid(state, project_id, workspace_slug) - - # Resolve type name to UUID if needed - resolved_type_id = await resolve_type_to_uuid(type_id, project_id, workspace_slug) - - # Build update data with only non-None values to avoid overwriting existing fields - update_data = { - k: v - for k, v in { - "name": name, - "description_html": description_html, - "priority": priority, - "state": resolved_state, - "assignees": assignees, - "labels": labels, - "start_date": start_date, - "target_date": target_date, - "type_id": resolved_type_id, - "parent": parent, - "external_id": external_id, - "external_source": external_source, - "is_draft": is_draft, - }.items() - if v is not None - } - - result = await method_executor.execute( - "workitems", - "update", - issue_id=issue_id, - project_id=project_id, - workspace_slug=workspace_slug, - **update_data, - ) - - if result["success"]: - # Enrich response data with missing fields for URL construction - data = result["data"] - if data and isinstance(data, dict) and data.get("id"): - try: - from pi.app.api.v1.helpers.plane_sql_queries import get_issue_identifier_for_artifact - - # Get the missing project_identifier and sequence_id - identifier_info = await get_issue_identifier_for_artifact(str(data["id"])) - if identifier_info: - data["project_identifier"] = identifier_info.get("project_identifier") - data["sequence_id"] = identifier_info.get("sequence_id") - log.info(f"Enriched workitem update data with identifier info: {identifier_info.get("identifier")}") - except Exception as e: - log.warning(f"Could not enrich workitem update data with identifier info: {e}") - - return await PlaneToolBase.format_success_payload_with_url("Successfully updated work item", data, "workitem", context) - else: - return PlaneToolBase.format_error_payload("Failed to update work item", result["error"]) - - @tool - async def create_epic( - name: str, - project_id: Optional[str] = None, - description_html: Optional[str] = None, - priority: Optional[str] = None, - state: Optional[str] = None, - assignees: Optional[List[str]] = None, - labels: Optional[List[str]] = None, - start_date: Optional[str] = None, - target_date: Optional[str] = None, - external_id: Optional[str] = None, - external_source: Optional[str] = None, - ) -> Dict[str, Any]: - """Create a new epic work item. - - Args: - name: Epic title (required) - project_id: Project ID (required - provide from conversation context or previous actions) - description_html: Epic description in HTML format - priority: Priority level (high, medium, low, urgent, none) - state: State name or ID for the epic (e.g., "done", "in progress", or UUID) - assignees: List of assignee user IDs - labels: List of label IDs - start_date: Start date (YYYY-MM-DD format) - target_date: Target completion date (YYYY-MM-DD format) - external_id: External system identifier (optional) - external_source: External system source name (optional) - - Note: This tool automatically sets the work item type to 'epic' for the specified project. - To add the created epic to a module or cycle, use modules_add_work_items or cycles_add_work_items after creation. - """ - # Auto-fill workspace_slug from context (hidden from LLM) - workspace_slug = context.get("workspace_slug") - - # Auto-fill project_id from context if not provided - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - # Get the epic type ID for this project - if project_id is None: - return PlaneToolBase.format_error_payload("Failed to create epic", "Project ID is required for epic creation. Please specify a project.") - - epic_type_id = await get_epic_type_id(method_executor, project_id, workspace_slug) - if not epic_type_id: - return PlaneToolBase.format_error_payload( - "Failed to create epic", "Could not find epic issue type for this project. Please ensure an epic issue type exists." - ) - - # Resolve state name to UUID if provided as name - resolved_state = await resolve_state_to_uuid(state, project_id, workspace_slug) - - result = await method_executor.execute( - "workitems", - "create", - name=name, - description_html=description_html, - project_id=project_id, - workspace_slug=workspace_slug, - priority=priority, - state=resolved_state, - assignees=assignees, - labels=labels, - start_date=start_date, - target_date=target_date, - type_id=epic_type_id, # Automatically set to epic type - external_id=external_id, - external_source=external_source, - ) - - if result["success"]: - # Enrich response data with missing fields for URL construction - data = result["data"] - if data and isinstance(data, dict) and data.get("id"): - try: - from pi.app.api.v1.helpers.plane_sql_queries import get_issue_identifier_for_artifact - - # Get the missing project_identifier and sequence_id - identifier_info = await get_issue_identifier_for_artifact(str(data["id"])) - if identifier_info: - data["project_identifier"] = identifier_info.get("project_identifier") - data["sequence_id"] = identifier_info.get("sequence_id") - log.info(f"Enriched epic data with identifier info: {identifier_info.get("identifier")}") - except Exception as e: - log.warning(f"Could not enrich epic data with identifier info: {e}") - - return await PlaneToolBase.format_success_payload_with_url(f"Successfully created epic '{name}'", data, "epic", context) - else: - return PlaneToolBase.format_error_payload("Failed to create epic", result["error"]) - - @tool - async def update_epic( - issue_id: str, - project_id: Optional[str] = None, - name: Optional[str] = None, - description_html: Optional[str] = None, - priority: Optional[str] = None, - state: Optional[str] = None, - assignees: Optional[List[str]] = None, - labels: Optional[List[str]] = None, - start_date: Optional[str] = None, - target_date: Optional[str] = None, - external_id: Optional[str] = None, - external_source: Optional[str] = None, - ) -> Dict[str, Any]: - """Update an existing epic work item. - - Args: - issue_id: Epic ID to update (required) - project_id: Project ID (optional - provide from conversation context) - name: Epic title - description_html: Epic description in HTML format - priority: Priority level (high, medium, low, urgent, none) - state: State ID for the epic - assignees: List of assignee user IDs - labels: List of label IDs - start_date: Start date (YYYY-MM-DD format) - target_date: Target completion date (YYYY-MM-DD format) - external_id: External system identifier (optional) - external_source: External system source name (optional) - - Note: This tool updates an existing epic. It does not change the work item type. - To add/move the epic to a module or cycle, use modules_add_work_items or cycles_add_work_items. - """ - # Auto-fill workspace_slug from context (hidden from LLM) - workspace_slug = context.get("workspace_slug") - - # Auto-fill project_id from context if not provided - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - # Resolve state name to UUID if needed - resolved_state = await resolve_state_to_uuid(state, project_id, workspace_slug) - - # Build update data with only non-None values to avoid overwriting existing fields - # Note: type_id is intentionally omitted to preserve epic type - update_data = { - k: v - for k, v in { - "name": name, - "description_html": description_html, - "priority": priority, - "state": resolved_state, - "assignees": assignees, - "labels": labels, - "start_date": start_date, - "target_date": target_date, - "external_id": external_id, - "external_source": external_source, - }.items() - if v is not None - } - - result = await method_executor.execute( - "workitems", - "update", - issue_id=issue_id, - project_id=project_id, - workspace_slug=workspace_slug, - **update_data, - ) - - if result["success"]: - return await PlaneToolBase.format_success_payload_with_url("Successfully updated epic", result["data"], "epic", context) - else: - return PlaneToolBase.format_error_payload("Failed to update epic", result["error"]) - - @tool - async def workitems_list( - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - cursor: Optional[str] = None, - expand: Optional[str] = None, - external_id: Optional[str] = None, - external_source: Optional[str] = None, - fields: Optional[str] = None, - order_by: Optional[str] = None, - per_page: Optional[int] = 20, - priority: Optional[str] = None, - state: Optional[str] = None, - assignees: Optional[List[str]] = None, - labels: Optional[List[str]] = None, - start_date: Optional[str] = None, - target_date: Optional[str] = None, - created_by: Optional[str] = None, - updated_by: Optional[str] = None, - type_id: Optional[str] = None, - parent: Optional[str] = None, - is_draft: Optional[bool] = None, - created_at: Optional[str] = None, - updated_at: Optional[str] = None, - completed_at: Optional[str] = None, - archived_at: Optional[str] = None, - ) -> Dict[str, Any]: - """List work items with filtering. - - Args: - project_id: Project ID (required - provide from conversation context or previous actions) - workspace_slug: Workspace slug (provide if known, otherwise auto-detected) - cursor: Pagination cursor for next page - expand: Comma-separated list of related fields to expand in response - external_id: External system identifier for filtering or lookup - external_source: External system source name for filtering or lookup - fields: Comma-separated list of fields to include in response - order_by: Field to order results by. Prefix with '-' for descending order - per_page: Number of work items per page (default: 20, max: 100) - priority: Filter by priority (high, medium, low, urgent, none) - state: Filter by state name or UUID - assignees: Filter by assignee user IDs - labels: Filter by label IDs - start_date: Filter by start date - target_date: Filter by target date - created_by: Filter by creator ID - updated_by: Filter by updater ID - type_id: Filter by issue type ID - parent: Filter by parent issue ID - is_draft: Filter by draft status - created_at: Filter by creation time - updated_at: Filter by update time - completed_at: Filter by completion time - archived_at: Filter by archive time - """ - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - # Resolve state name to UUID if needed - resolved_state = await resolve_state_to_uuid(state, project_id, workspace_slug) - - # Build filter arguments - filter_args = { - "priority": priority, - "state": resolved_state, - "assignees": assignees, - "labels": labels, - "start_date": start_date, - "target_date": target_date, - "created_by": created_by, - "updated_by": updated_by, - "type_id": type_id, - "parent": parent, - "is_draft": is_draft, - "created_at": created_at, - "updated_at": updated_at, - "completed_at": completed_at, - "archived_at": archived_at, - } - - # Remove None values - filter_args = {k: v for k, v in filter_args.items() if v is not None} - - result = await method_executor.execute( - "workitems", - "list", - project_id=project_id, - workspace_slug=workspace_slug, - cursor=cursor, - expand=expand, - external_id=external_id, - external_source=external_source, - fields=fields, - order_by=order_by, - per_page=per_page, - ) - - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully retrieved work items list", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to list work items", result["error"]) - - @tool - async def workitems_retrieve( - issue_id: str, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - expand: Optional[str] = None, - external_id: Optional[str] = None, - external_source: Optional[str] = None, - fields: Optional[str] = None, - order_by: Optional[str] = None, - ) -> Dict[str, Any]: - """Retrieve a single work item by ID. - - Args: - issue_id: Work item ID (required) - project_id: Project ID (required - provide from conversation context or previous actions) - workspace_slug: Workspace slug (provide if known, otherwise auto-detected) - expand: Comma-separated list of related fields to expand in response - external_id: External system identifier for filtering or lookup - external_source: External system source name for filtering or lookup - fields: Comma-separated list of fields to include in response - order_by: Field to order results by. Prefix with '-' for descending order - """ - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "workitems", - "retrieve", - issue_id=issue_id, - project_id=project_id, - workspace_slug=workspace_slug, - expand=expand, - external_id=external_id, - external_source=external_source, - fields=fields, - order_by=order_by, - ) - - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully retrieved work item", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to retrieve work item", result["error"]) - - @tool - async def workitems_search( - search: str, - workspace_slug: Optional[str] = None, - limit: Optional[int] = None, - project_id: Optional[str] = None, - workspace_search: Optional[str] = None, - ) -> Dict[str, Any]: - """Search work items by criteria. - - Args: - search: Search query to filter results by name, description, or identifier (required) - workspace_slug: Workspace slug (provide if known, otherwise auto-detected) - limit: Maximum number of results to return - project_id: Project ID for filtering results within a specific project - workspace_search: Whether to search across entire workspace or within specific project - """ - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "workitems", - "search", - search=search, - workspace_slug=workspace_slug, - limit=limit, - project_id=project_id, - workspace_search=workspace_search, - ) - - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully searched work items", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to search work items", result["error"]) - - @tool - async def workitems_get_workspace( - issue_identifier: int, - project_identifier: str, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Get work item across workspace using identifiers. - - Args: - issue_identifier: Issue sequence ID (numeric identifier within project) (required) - project_identifier: Project identifier (unique string within workspace) (required) - workspace_slug: Workspace slug (provide if known, otherwise auto-detected) - """ - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - - result = await method_executor.execute( - "workitems", - "get_workspace", - issue_identifier=issue_identifier, - project_identifier=project_identifier, - workspace_slug=workspace_slug, - ) - - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully retrieved workspace work item", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to retrieve workspace work item", result["error"]) - - @tool - async def workitems_create_relation( - issue_id: str, - relation_type: str, - related_issues: List[str], - project_id: Optional[str] = None, - ) -> Dict[str, Any]: - """Create relationships between work items. - - Args: - issue_id: Source work item ID to create relations from (required) - relation_type: Type of relationship - one of: blocking, blocked_by, duplicate, relates_to, start_before, start_after, finish_before, finish_after (required) - related_issues: List of work item IDs to create relations with (required) - project_id: Project ID (required - provide from conversation context or previous actions) - - Supported relation types: - - blocking: This work item blocks the related work items - - blocked_by: This work item is blocked by the related work items - - duplicate: This work item is a duplicate of the related work items - - relates_to: This work item relates to the related work items - - start_before: This work item should start before the related work items - - start_after: This work item should start after the related work items - - finish_before: This work item should finish before the related work items - - finish_after: This work item should finish after the related work items - - Examples: - - "Make issue A block issue B" = workitems_create_relation(issue_id=A, relation_type="blocking", related_issues=[B]) - - "Mark issue X as duplicate of issue Y" = workitems_create_relation(issue_id=X, relation_type="duplicate", related_issues=[Y]) - - "Issue C relates to issues D and E" = workitems_create_relation(issue_id=C, relation_type="relates_to", related_issues=[D, E]) - """ # noqa: E501 - # Auto-fill workspace_slug from context (hidden from LLM) - workspace_slug = context.get("workspace_slug") - - # Auto-fill project_id from context if not provided - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - # Validate relation type - if relation_type not in RELATION_TYPES: - valid_types = ", ".join(RELATION_TYPES.keys()) - return PlaneToolBase.format_error_payload( - "Invalid relation type", f"Relation type '{relation_type}' is not valid. Valid types are: {valid_types}" - ) - - # Validate required parameters - if not related_issues: - return PlaneToolBase.format_error_payload("Missing related issues", "At least one related issue ID must be provided") - - result = await method_executor.execute( - "workitems", - "create_relation", - issue_id=issue_id, - project_id=project_id, - workspace_slug=workspace_slug, - relation_type=relation_type, - issues=related_issues, - ) - - if result["success"]: - relation_count = len(related_issues) - - # For relations, we need to return entity info for the source work item (issue_id) - # Create a mock work item response with the source issue_id for entity URL generation - source_workitem_data = {"id": issue_id} - - return await PlaneToolBase.format_success_payload_with_url( - f"Successfully created {relation_count} '{relation_type}' relation(s) for work item", source_workitem_data, "workitem", context - ) - else: - return PlaneToolBase.format_error_payload("Failed to create work item relation", result["error"]) - - @tool - async def workitems_delete( - issue_id: str, - project_id: Optional[str] = None, - ) -> Dict[str, Any]: - """Delete a work item/issue. - - Args: - issue_id: Work item ID to delete (required) - project_id: Project ID (required - provide from conversation context or previous actions) - - Warning: This action is permanent and cannot be undone. The work item will be permanently deleted. - """ - # Auto-fill workspace_slug from context (hidden from LLM) - workspace_slug = context.get("workspace_slug") - - # Auto-fill project_id from context if not provided - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "workitems", - "delete", - issue_id=issue_id, - project_id=project_id, - workspace_slug=workspace_slug, - ) - - if result["success"]: - return PlaneToolBase.format_success_payload(f"Successfully deleted work item {issue_id}", {"id": issue_id}) - else: - return PlaneToolBase.format_error_payload("Failed to delete work item", result.get("error")) - - return [ - workitems_create, - workitems_update, - create_epic, - update_epic, - workitems_create_relation, - workitems_delete, - workitems_list, - # workitems_retrieve, - # workitems_search, - # workitems_get_workspace - ] + # URL construction for list operations + elif tool_name == "workitems_list": + if result.get("success"): + data = result.get("data") + if data and isinstance(data, dict): + results = data.get("results", []) + workspace_slug = kwargs.get("workspace_slug") or context.get("workspace_slug") + + if results and isinstance(results, list): + try: + from pi.app.api.v1.helpers.plane_sql_queries import get_issue_identifier_for_artifact + from pi.config import settings + + # Get the base URL for constructing frontend URLs + frontend_url = settings.plane_api.FRONTEND_URL.rstrip("/") + + # Enrich each workitem with identifier and URL + for item in results: + if isinstance(item, dict) and item.get("id"): + try: + identifier_info = await get_issue_identifier_for_artifact(str(item["id"])) + if identifier_info: + item["project_identifier"] = identifier_info.get("project_identifier") + item["sequence_id"] = identifier_info.get("sequence_id") + item["identifier"] = identifier_info.get("identifier") + + # Construct URL using the identifier (PROJECT-123 format) + if workspace_slug and identifier_info.get("identifier"): + item["url"] = f"{frontend_url}/{workspace_slug}/browse/{identifier_info["identifier"]}/" + + log.debug(f"Enriched workitem {item["id"]} with identifier: {identifier_info.get("identifier")}") + except Exception as e: + log.warning(f"Could not enrich workitem {item.get("id")} with identifier info: {e}") + + log.info(f"Enriched {len(results)} workitems with identifiers and URLs") + except Exception as e: + log.warning(f"Error enriching workitems list with identifiers: {e}") + + return result + + +# ============================================================================ +# WORKITEMS TOOL METADATA +# ============================================================================ + +WORKITEMS_TOOL_DEFINITIONS: Dict[str, ToolMetadata] = { + "create": ToolMetadata( + name="workitems_create", + description="Create a new work item/issue", + sdk_method="create_work_item", + returns_entity_type="workitem", + pre_handler=_workitems_pre_handler, + post_handler=_workitems_post_handler, + parameters=[ + ToolParameter(name="name", type="str", required=True, description="Work item title (required)"), + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID (required - provide from conversation context or previous actions)", + auto_fill_from_context=True, + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (required - provide from conversation context)", + auto_fill_from_context=True, + property_transform="skip", + ), + ToolParameter( + name="description_html", + type="Optional[str]", + required=False, + description="Workitem description in HTML format", + ), + ToolParameter( + name="priority", + type="Optional[str]", + required=False, + description="Priority level (high, medium, low, urgent, none)", + ), + ToolParameter( + name="state", + type="Optional[str]", + required=False, + description='State name or UUID for the workitem (e.g., "todo", "in progress", "done")', + ), + ToolParameter( + name="assignees", + type="List[str]", + required=False, + description="List of assignee user IDs", + ), + ToolParameter( + name="labels", + type="List[str]", + required=False, + description="List of label IDs", + ), + ToolParameter( + name="start_date", + type="Optional[str]", + required=False, + description="Start date (YYYY-MM-DD format)", + ), + ToolParameter( + name="target_date", + type="Optional[str]", + required=False, + description="Target completion date (YYYY-MM-DD format)", + ), + ToolParameter( + name="type_id", + type="Optional[str]", + required=False, + description="Workitem type ID (optional). MUST be the 'issue_types_id' (UUID of the issue type definition), " + "NOT the 'project_issue_types_id'.", + ), + ToolParameter( + name="parent", + type="Optional[str]", + required=False, + description="Parent work-item ID (optional)", + ), + ToolParameter( + name="external_id", + type="Optional[str]", + required=False, + description="External system identifier (optional)", + ), + ToolParameter( + name="external_source", + type="Optional[str]", + required=False, + description="External system source name (optional)", + ), + ToolParameter( + name="is_draft", + type="Optional[bool]", + required=False, + description="Create as draft (optional)", + ), + ], + ), + "update": ToolMetadata( + name="workitems_update", + description="Update an existing work item/issue", + sdk_method="update_work_item", + returns_entity_type="workitem", + pre_handler=_workitems_pre_handler, + post_handler=_workitems_post_handler, + parameters=[ + ToolParameter(name="issue_id", type="str", required=True, description="Work item ID to update (required)"), + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID (required - provide from conversation context or previous actions)", + auto_fill_from_context=True, + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (required - provide from conversation context)", + auto_fill_from_context=True, + property_transform="skip", + ), + ToolParameter( + name="name", + type="Optional[str]", + required=False, + description="New work item title", + ), + ToolParameter( + name="description_html", + type="Optional[str]", + required=False, + description="New description in HTML format", + ), + ToolParameter( + name="priority", + type="Optional[str]", + required=False, + description="New priority level (high, medium, low, urgent, none)", + ), + ToolParameter( + name="state", + type="Optional[str]", + required=False, + description='New state name or UUID (e.g., "todo", "in progress", "done")', + ), + ToolParameter( + name="assignees", + type="List[str]", + required=False, + description="New list of assignee user IDs", + ), + ToolParameter( + name="labels", + type="List[str]", + required=False, + description="New list of label IDs", + ), + ToolParameter( + name="start_date", + type="Optional[str]", + required=False, + description="New start date (YYYY-MM-DD format)", + ), + ToolParameter( + name="target_date", + type="Optional[str]", + required=False, + description="New target completion date (YYYY-MM-DD format)", + ), + ToolParameter( + name="type_id", + type="Optional[str]", + required=False, + description="Workitem type ID (optional). MUST be the 'issue_types_id' (UUID of the issue type definition), " + "NOT the 'project_issue_types_id'.", + ), + ToolParameter( + name="parent", + type="Optional[str]", + required=False, + description="Parent work-item ID (optional)", + ), + ToolParameter( + name="external_id", + type="Optional[str]", + required=False, + description="External system identifier (optional)", + ), + ToolParameter( + name="external_source", + type="Optional[str]", + required=False, + description="External system source name (optional)", + ), + ToolParameter( + name="is_draft", + type="Optional[bool]", + required=False, + description="Mark as draft (optional)", + ), + ], + ), + "list": ToolMetadata( + name="workitems_list", + description="List work items with filtering", + sdk_method="list_work_items", + pre_handler=_workitems_pre_handler, + post_handler=_workitems_post_handler, + parameters=[ + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID (required - provide from conversation context or previous actions)", + auto_fill_from_context=True, + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (provide if known, otherwise auto-detected)", + auto_fill_from_context=True, + property_transform="skip", + ), + ToolParameter( + name="cursor", + type="Optional[str]", + required=False, + description="Pagination cursor for next page", + property_transform="skip", + ), + ToolParameter( + name="expand", + type="Optional[str]", + required=False, + description="Comma-separated list of related fields to expand in response", + property_transform="skip", + ), + ToolParameter( + name="external_id", + type="Optional[str]", + required=False, + description="External system identifier for filtering or lookup", + ), + ToolParameter( + name="external_source", + type="Optional[str]", + required=False, + description="External system source name for filtering or lookup", + ), + ToolParameter( + name="fields", + type="Optional[str]", + required=False, + description="Comma-separated list of fields to include in response", + property_transform="skip", + ), + ToolParameter( + name="order_by", + type="Optional[str]", + required=False, + description="Field to order results by. Prefix with '-' for descending order", + property_transform="skip", + ), + ToolParameter( + name="per_page", + type="Optional[int]", + required=False, + description="Number of work items per page (default: 20, max: 100)", + property_transform="skip", + ), + ToolParameter( + name="priority", + type="Optional[str]", + required=False, + description="Filter by priority (high, medium, low, urgent, none)", + ), + ToolParameter( + name="state", + type="Optional[str]", + required=False, + description="Filter by state name or UUID", + ), + ToolParameter( + name="assignees", + type="List[str]", + required=False, + description="Filter by assignee user IDs", + ), + ToolParameter( + name="labels", + type="List[str]", + required=False, + description="Filter by label IDs", + ), + ToolParameter( + name="start_date", + type="Optional[str]", + required=False, + description="Filter by start date", + ), + ToolParameter( + name="target_date", + type="Optional[str]", + required=False, + description="Filter by target date", + ), + ToolParameter( + name="created_by", + type="Optional[str]", + required=False, + description="Filter by creator ID", + ), + ToolParameter( + name="updated_by", + type="Optional[str]", + required=False, + description="Filter by updater ID", + ), + ToolParameter( + name="type_id", + type="Optional[str]", + required=False, + description="Filter by issue type ID", + ), + ToolParameter( + name="parent", + type="Optional[str]", + required=False, + description="Filter by parent issue ID", + ), + ToolParameter( + name="is_draft", + type="Optional[bool]", + required=False, + description="Filter by draft status", + ), + ToolParameter( + name="created_at", + type="Optional[str]", + required=False, + description="Filter by creation time", + ), + ToolParameter( + name="updated_at", + type="Optional[str]", + required=False, + description="Filter by update time", + ), + ToolParameter( + name="completed_at", + type="Optional[str]", + required=False, + description="Filter by completion time", + ), + ToolParameter( + name="archived_at", + type="Optional[str]", + required=False, + description="Filter by archive time", + ), + ], + ), + "retrieve": ToolMetadata( + name="workitems_retrieve", + description="Retrieve a single work item by ID", + sdk_method="retrieve_work_item", + parameters=[ + ToolParameter(name="issue_id", type="str", required=True, description="Work item ID (required)"), + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID (required - provide from conversation context or previous actions)", + auto_fill_from_context=True, + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (provide if known, otherwise auto-detected)", + auto_fill_from_context=True, + property_transform="skip", + ), + ToolParameter( + name="expand", + type="Optional[str]", + required=False, + description="Comma-separated list of related fields to expand in response", + property_transform="skip", + ), + ToolParameter( + name="external_id", + type="Optional[str]", + required=False, + description="External system identifier for filtering or lookup", + ), + ToolParameter( + name="external_source", + type="Optional[str]", + required=False, + description="External system source name for filtering or lookup", + ), + ToolParameter( + name="fields", + type="Optional[str]", + required=False, + description="Comma-separated list of fields to include in response", + property_transform="skip", + ), + ToolParameter( + name="order_by", + type="Optional[str]", + required=False, + description="Field to order results by. Prefix with '-' for descending order", + property_transform="skip", + ), + ], + ), + "delete": ToolMetadata( + name="workitems_delete", + description="Delete a work item/issue", + sdk_method="delete_work_item", + parameters=[ + ToolParameter(name="issue_id", type="str", required=True, description="Work item ID to delete (required)"), + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID (required - provide from conversation context or previous actions)", + auto_fill_from_context=True, + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (provide if known, otherwise auto-detected)", + auto_fill_from_context=True, + property_transform="skip", + ), + ], + ), + "create_relation": ToolMetadata( + name="workitems_create_relation", + description="Create relationships between work items", + sdk_method="create_work_item_relation", + returns_entity_type="workitem", + pre_handler=_workitems_pre_handler, + parameters=[ + ToolParameter(name="issue_id", type="str", required=True, description="Source work item ID to create relations from (required)"), + ToolParameter( + name="relation_type", + type="str", + required=True, + description="Type of relationship - one of: blocking, blocked_by, duplicate, relates_to, start_before, " + "start_after, finish_before, finish_after (required)", + ), + ToolParameter( + name="issues", + type="List[str]", + required=True, + description="List of work item IDs to create relations with (required)", + ), + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID (required - provide from conversation context or previous actions)", + auto_fill_from_context=True, + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (provide if known, otherwise auto-detected)", + auto_fill_from_context=True, + property_transform="skip", + ), + ], + ), + "search": ToolMetadata( + name="workitems_search", + description="Search work items by criteria", + sdk_method="search_work_items", + parameters=[ + ToolParameter( + name="query", + type="str", + required=True, + description="Search query to filter results by name, description, or identifier (required)", + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (provide if known, otherwise auto-detected)", + auto_fill_from_context=True, + property_transform="skip", + ), + ToolParameter( + name="limit", + type="Optional[int]", + required=False, + description="Maximum number of results to return", + ), + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID for filtering results within a specific project", + auto_fill_from_context=True, + ), + ToolParameter( + name="workspace_search", + type="Optional[str]", + required=False, + description="Whether to search across entire workspace or within specific project", + ), + ], + ), + "create_epic": ToolMetadata( + name="create_epic", + description="Create a new epic", + sdk_method="create_work_item", + returns_entity_type="epic", + pre_handler=_workitems_pre_handler, + post_handler=_workitems_post_handler, + parameters=[ + ToolParameter(name="name", type="str", required=True, description="Epic title (required)"), + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID (required - provide from conversation context or previous actions)", + auto_fill_from_context=True, + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (required - provide from conversation context)", + auto_fill_from_context=True, + property_transform="skip", + ), + ToolParameter( + name="description_html", + type="Optional[str]", + required=False, + description="Epic description in HTML format", + ), + ToolParameter( + name="priority", + type="Optional[str]", + required=False, + description="Priority level (high, medium, low, urgent, none)", + ), + ToolParameter( + name="state", + type="Optional[str]", + required=False, + description='State name or ID for the epic (e.g., "done", "in progress", or UUID)', + ), + ToolParameter( + name="assignees", + type="List[str]", + required=False, + description="List of assignee user IDs", + ), + ToolParameter( + name="labels", + type="List[str]", + required=False, + description="List of label IDs", + ), + ToolParameter( + name="start_date", + type="Optional[str]", + required=False, + description="Start date (YYYY-MM-DD format)", + ), + ToolParameter( + name="target_date", + type="Optional[str]", + required=False, + description="Target completion date (YYYY-MM-DD format)", + ), + ToolParameter( + name="external_id", + type="Optional[str]", + required=False, + description="External system identifier (optional)", + ), + ToolParameter( + name="external_source", + type="Optional[str]", + required=False, + description="External system source name (optional)", + ), + ], + ), + "update_epic": ToolMetadata( + name="update_epic", + description="Update an existing epic", + sdk_method="update_work_item", + returns_entity_type="epic", + pre_handler=_workitems_pre_handler, + post_handler=_workitems_post_handler, + parameters=[ + ToolParameter(name="issue_id", type="str", required=True, description="Epic ID to update (required)"), + ToolParameter( + name="project_id", + type="Optional[str]", + required=False, + description="Project ID (optional - provide from conversation context)", + auto_fill_from_context=True, + ), + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (provide if known, otherwise auto-detected)", + auto_fill_from_context=True, + property_transform="skip", + ), + ToolParameter( + name="name", + type="Optional[str]", + required=False, + description="Epic title", + ), + ToolParameter( + name="description_html", + type="Optional[str]", + required=False, + description="Epic description in HTML format", + ), + ToolParameter( + name="priority", + type="Optional[str]", + required=False, + description="Priority level (high, medium, low, urgent, none)", + ), + ToolParameter( + name="state", + type="Optional[str]", + required=False, + description="State ID for the epic", + ), + ToolParameter( + name="assignees", + type="List[str]", + required=False, + description="List of assignee user IDs", + ), + ToolParameter( + name="labels", + type="List[str]", + required=False, + description="List of label IDs", + ), + ToolParameter( + name="start_date", + type="Optional[str]", + required=False, + description="Start date (YYYY-MM-DD format)", + ), + ToolParameter( + name="target_date", + type="Optional[str]", + required=False, + description="Target completion date (YYYY-MM-DD format)", + ), + ToolParameter( + name="external_id", + type="Optional[str]", + required=False, + description="External system identifier (optional)", + ), + ToolParameter( + name="external_source", + type="Optional[str]", + required=False, + description="External system source name (optional)", + ), + ], + ), +} + + +# ============================================================================ +# TOOL FACTORY +# ============================================================================ + + +def get_workitem_tools(method_executor, context): + """Return LangChain tools for the workitems category using auto-generation from metadata. + + Dynamically fetches available work item types for the current project and injects them + into the type_id parameter descriptions, making types visible to the LLM during planning. + """ + import copy + + # Make a deep copy to avoid modifying the global constant + dynamic_tool_definitions = copy.deepcopy(WORKITEMS_TOOL_DEFINITIONS) + + # Fetch and inject available types if we have the necessary context + project_id = context.get("project_id") + workspace_slug = context.get("workspace_slug") + + if project_id and workspace_slug and method_executor: + types_text = _sync_fetch_types(method_executor, project_id, workspace_slug) + if types_text: + _enrich_type_id_descriptions(dynamic_tool_definitions, types_text) + log.info(f"Injected available types into workitem tool descriptions for project {project_id}") + + return generate_tools_for_category( + category="workitems", + method_executor=method_executor, + context=context, + tool_definitions=dynamic_tool_definitions, + ) + + +# ============================================================================ +# OLD MANUAL TOOL DEFINITIONS (COMMENTED OUT - KEPT FOR COMPARISON) +# To rollback: uncomment below and comment out the auto-generation code above +# ============================================================================ + +# from langchain_core.tools import tool +# +# def get_workitem_tools(method_executor, context): +# """Return LangChain tools for the workitems category using method_executor and context.""" +# +# @tool +# async def workitems_create( +# name: str, +# project_id: Optional[str] = None, +# description_html: Optional[str] = None, +# ... [TRUNCATED - See git history for full manual implementations] +# ): +# ... [All manual tool implementations omitted for brevity] +# +# return [ +# workitems_create, +# workitems_update, +# create_epic, +# update_epic, +# workitems_create_relation, +# workitems_delete, +# workitems_list, +# # workitems_retrieve, +# # workitems_search, +# # workitems_get_workspace +# ] diff --git a/apps/pi/pi/services/actions/tools/worklogs.py b/apps/pi/pi/services/actions/tools/worklogs.py index 007eddabe1..4a4da9b73c 100644 --- a/apps/pi/pi/services/actions/tools/worklogs.py +++ b/apps/pi/pi/services/actions/tools/worklogs.py @@ -13,244 +13,156 @@ Worklogs API tools for Plane time tracking operations. """ +import contextlib +import re import uuid from typing import Any from typing import Dict -from typing import Optional -from langchain_core.tools import tool +from pi.services.actions.tool_generator import generate_tools_for_category +from pi.services.actions.tool_metadata import ToolMetadata +from pi.services.actions.tool_metadata import ToolParameter -from .base import PlaneToolBase -# Factory wired via CATEGORY_TO_PROVIDER in tools/__init__.py -# Returns LangChain tools implementing worklog actions +# Pre-handler combining project resolution AND duration parsing +async def _worklog_pre_handler( + metadata: ToolMetadata, + kwargs: Dict[str, Any], + context: Dict[str, Any], + category: str, + method_key: str, + method_executor: Any, +) -> Dict[str, Any]: + """Resolve project_id and parse duration string to minutes.""" + + # 1. Project ID Resolution + issue_id = kwargs.get("issue_id") + project_id = kwargs.get("project_id") + + should_resolve = False + if issue_id and not project_id: + should_resolve = True + elif issue_id and project_id: + try: + uuid.UUID(str(project_id)) + except (ValueError, AttributeError): + should_resolve = True + + if should_resolve: + try: + from pi.app.api.v1.helpers.plane_sql_queries import get_issue_identifier_for_artifact + + issue_info = await get_issue_identifier_for_artifact(str(issue_id)) + if issue_info and issue_info.get("project_id"): + kwargs["project_id"] = issue_info["project_id"] + except Exception: + pass + + # 2. Duration Parsing (e.g., "1h 30m" -> 90) + duration = kwargs.get("duration") + if duration is not None: + if isinstance(duration, str): + # Try to parse string format "Xh Ym" or just "Xm" + total_minutes = 0 + + # Simple regex for parsing + # Matches "1h", "1.5h", "30m", "1h 30m" + hours_match = re.search(r"(\d+(?:\.\d+)?)\s*h", duration.lower()) + minutes_match = re.search(r"(\d+(?:\.\d+)?)\s*m", duration.lower()) + + if hours_match: + with contextlib.suppress(ValueError): + total_minutes += int(float(hours_match.group(1)) * 60) + + if minutes_match: + with contextlib.suppress(ValueError): + total_minutes += int(float(minutes_match.group(1))) + + # If regex matched nothing but it's a digit string, treat as minutes + if not hours_match and not minutes_match: + if duration.isdigit(): + total_minutes = int(duration) + + # If we found something, update kwargs + if total_minutes > 0: + kwargs["duration"] = total_minutes + + # If int/float passed directly, ensure int + elif isinstance(duration, (int, float)): + kwargs["duration"] = int(duration) + + return kwargs + + +WORKLOGS_TOOL_DEFINITIONS = { + "create": ToolMetadata( + name="worklogs_create", + description="Create a new worklog (time entry).", + sdk_method="create_issue_worklog", + parameters=[ + ToolParameter(name="issue_id", description="Issue ID", required=True, type="str"), + ToolParameter(name="description", description="Worklog description/note", required=True, type="str"), + ToolParameter( + name="duration", description="Duration (e.g., '1h 30m' or minutes as int)", required=True, type="Any" + ), # Accepting Any to allow string + ToolParameter( + name="project_id", description="Project ID (optional, auto-filled)", required=False, type="Optional[str]", auto_fill_from_context=True + ), + ToolParameter( + name="workspace_slug", + description="Workspace slug (optional, auto-filled)", + required=False, + type="Optional[str]", + auto_fill_from_context=True, + ), + ], + pre_handler=_worklog_pre_handler, + returns_entity_type="worklog", + ), + "list": ToolMetadata( + name="worklogs_list", + description="List worklogs for an issue.", + sdk_method="list_issue_worklogs", + parameters=[ + ToolParameter(name="issue_id", description="Issue ID", required=True, type="str"), + ToolParameter(name="project_id", description="Project ID", required=False, type="Optional[str]", auto_fill_from_context=True), + ToolParameter(name="workspace_slug", description="Workspace slug", required=False, type="Optional[str]", auto_fill_from_context=True), + ], + pre_handler=_worklog_pre_handler, + ), + "update": ToolMetadata( + name="worklogs_update", + description="Update time entry.", + sdk_method="update_issue_worklog", + parameters=[ + ToolParameter(name="worklog_id", description="Worklog ID", required=True, type="str"), + ToolParameter(name="issue_id", description="Issue ID", required=True, type="str"), + ToolParameter(name="description", description="Worklog description", required=False, type="Optional[str]"), + ToolParameter(name="duration", description="Duration (e.g., '1h 30m')", required=False, type="Any"), + ToolParameter(name="project_id", description="Project ID", required=False, type="Optional[str]", auto_fill_from_context=True), + ToolParameter(name="workspace_slug", description="Workspace slug", required=False, type="Optional[str]", auto_fill_from_context=True), + ToolParameter(name="created_by", description="User ID who created", required=False, type="Optional[str]"), + ToolParameter(name="updated_by", description="User ID who updated", required=False, type="Optional[str]"), + ], + pre_handler=_worklog_pre_handler, + returns_entity_type="worklog", + ), + "delete": ToolMetadata( + name="worklogs_delete", + description="Delete time entry.", + sdk_method="delete_issue_worklog", + parameters=[ + ToolParameter(name="worklog_id", description="Worklog ID", required=True, type="str"), + ToolParameter(name="issue_id", description="Issue ID", required=True, type="str"), + ToolParameter(name="project_id", description="Project ID", required=False, type="Optional[str]", auto_fill_from_context=True), + ToolParameter(name="workspace_slug", description="Workspace slug", required=False, type="Optional[str]", auto_fill_from_context=True), + ], + pre_handler=_worklog_pre_handler, + returns_entity_type="worklog", + ), +} def get_worklog_tools(method_executor, context): """Return LangChain tools for the worklogs category using method_executor and context.""" - - @tool - async def worklogs_create( - issue_id: str, - description: str, - duration: int, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Create a new worklog entry. - - Args: - issue_id: Issue ID (required) - description: Worklog description (required) - duration: Duration in minutes (required) - project_id: Project ID (optional, auto-filled from context or resolved from issue_id) - workspace_slug: Workspace slug (optional, auto-filled from context) - """ - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - # Programmatically resolve project_id from issue_id if missing or invalid (non-UUID) - should_resolve = False - if issue_id and not project_id: - should_resolve = True - elif issue_id and project_id: - try: - uuid.UUID(str(project_id)) - except (ValueError, AttributeError): - should_resolve = True - - if should_resolve: - try: - from pi.app.api.v1.helpers.plane_sql_queries import get_issue_identifier_for_artifact - - issue_info = await get_issue_identifier_for_artifact(str(issue_id)) - if issue_info and issue_info.get("project_id"): - project_id = issue_info["project_id"] - except Exception: - pass - - result = await method_executor.execute( - "worklogs", - "create", - issue_id=issue_id, - description=description, - duration=duration, - project_id=project_id, - workspace_slug=workspace_slug, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully created worklog", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to create worklog", result["error"]) - - @tool - async def worklogs_list( - issue_id: str, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """List worklogs for an issue.""" - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - # Programmatically resolve project_id from issue_id if missing or invalid (non-UUID) - should_resolve = False - if issue_id and not project_id: - should_resolve = True - elif issue_id and project_id: - try: - uuid.UUID(str(project_id)) - except (ValueError, AttributeError): - should_resolve = True - - if should_resolve: - try: - from pi.app.api.v1.helpers.plane_sql_queries import get_issue_identifier_for_artifact - - issue_info = await get_issue_identifier_for_artifact(str(issue_id)) - if issue_info and issue_info.get("project_id"): - project_id = issue_info["project_id"] - except Exception: - pass - - result = await method_executor.execute( - "worklogs", - "list", - issue_id=issue_id, - project_id=project_id, - workspace_slug=workspace_slug, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully retrieved worklogs", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to list worklogs", result["error"]) - - @tool - async def worklogs_get_summary( - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Get project worklog summary.""" - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "worklogs", - "get_summary", - project_id=project_id, - workspace_slug=workspace_slug, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully retrieved worklog summary", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to get worklog summary", result["error"]) - - @tool - async def worklogs_update( - worklog_id: str, - issue_id: str, - description: Optional[str] = None, - duration: Optional[int] = None, - created_by: Optional[str] = None, - updated_by: Optional[str] = None, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Update time entry. - - Args: - worklog_id: Worklog ID (required) - issue_id: Issue ID (required) - description: Worklog description - duration: Duration in minutes - created_by: User ID who created the worklog - updated_by: User ID who updated the worklog - project_id: Project ID (optional, auto-filled from context or resolved from issue_id) - workspace_slug: Workspace slug (optional, auto-filled from context) - """ - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - # Programmatically resolve project_id from issue_id if missing or invalid (non-UUID) - should_resolve = False - if issue_id and not project_id: - should_resolve = True - elif issue_id and project_id: - try: - uuid.UUID(str(project_id)) - except (ValueError, AttributeError): - should_resolve = True - - if should_resolve: - try: - from pi.app.api.v1.helpers.plane_sql_queries import get_issue_identifier_for_artifact - - issue_info = await get_issue_identifier_for_artifact(str(issue_id)) - if issue_info and issue_info.get("project_id"): - project_id = issue_info["project_id"] - except Exception: - pass - - # Build update data - update_data: Dict[str, Any] = {} - if description is not None: - update_data["description"] = description - if duration is not None: - update_data["duration"] = duration - if created_by is not None: - update_data["created_by"] = created_by - if updated_by is not None: - update_data["updated_by"] = updated_by - - result = await method_executor.execute( - "worklogs", - "update", - worklog_id=worklog_id, - issue_id=issue_id, - project_id=project_id, - workspace_slug=workspace_slug, - **update_data, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully updated worklog", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to update worklog", result["error"]) - - @tool - async def worklogs_delete( - worklog_id: str, - project_id: Optional[str] = None, - workspace_slug: Optional[str] = None, - ) -> Dict[str, Any]: - """Delete time entry.""" - # Auto-fill from context if not provided - if workspace_slug is None and "workspace_slug" in context: - workspace_slug = context["workspace_slug"] - if project_id is None and "project_id" in context: - project_id = context["project_id"] - - result = await method_executor.execute( - "worklogs", - "delete", - worklog_id=worklog_id, - project_id=project_id, - workspace_slug=workspace_slug, - ) - if result["success"]: - return PlaneToolBase.format_success_payload("Successfully deleted worklog", result["data"]) - else: - return PlaneToolBase.format_error_payload("Failed to delete worklog", result["error"]) - - return [worklogs_create, worklogs_list, worklogs_get_summary, worklogs_update, worklogs_delete] + return generate_tools_for_category("worklogs", method_executor, context, WORKLOGS_TOOL_DEFINITIONS) diff --git a/apps/pi/pi/services/actions/tools/workspaces.py b/apps/pi/pi/services/actions/tools/workspaces.py new file mode 100644 index 0000000000..b12da1d590 --- /dev/null +++ b/apps/pi/pi/services/actions/tools/workspaces.py @@ -0,0 +1,207 @@ +# SPDX-FileCopyrightText: 2023-present Plane Software, Inc. +# SPDX-License-Identifier: LicenseRef-Plane-Commercial +# +# Licensed under the Plane Commercial License (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# https://plane.so/legals/eula +# +# DO NOT remove or modify this notice. +# NOTICE: Proprietary and confidential. Unauthorized use or distribution is prohibited. + +""" +Workspaces API tools for Plane workspace features management. +""" + +from typing import Any +from typing import Dict + +from pi import logger +from pi.services.actions.tool_generator import generate_tools_for_category +from pi.services.actions.tool_metadata import ToolMetadata +from pi.services.actions.tool_metadata import ToolParameter + +log = logger.getChild("workspaces") + +# All workspace feature fields - SDK requires all fields to be present +WORKSPACE_FEATURE_FIELDS = ["project_grouping", "initiatives", "teams", "customers", "wiki", "pi"] + + +async def _workspaces_pre_handler( + metadata: ToolMetadata, + kwargs: Dict[str, Any], + context: Dict[str, Any], + category: str, + method_key: str, + method_executor: Any = None, +) -> Dict[str, Any]: + """Pre-processing handler for workspace tools. + + Handles: + - update_features: Fetch current features and merge with update (SDK requires all fields) + """ + if method_key == "update_features": + workspace_slug = kwargs.get("workspace_slug") + if not workspace_slug: + log.warning("workspace_slug missing for update_features, cannot fetch current features") + return kwargs + + if not method_executor: + log.warning("method_executor not available, cannot fetch current features") + return kwargs + + # Fetch current features using the existing method_executor + try: + result = await method_executor.execute("workspaces", "get_features", workspace_slug=workspace_slug) + + if result.get("success") and result.get("data"): + features_data = result["data"] + + # Merge: current values as defaults, update with provided values + for field in WORKSPACE_FEATURE_FIELDS: + if field not in kwargs or kwargs[field] is None: + kwargs[field] = features_data.get(field, False) + + log.debug(f"Merged workspace features: {kwargs}") + else: + log.warning(f"Could not fetch current workspace features: {result}") + except Exception as e: + log.error(f"Failed to fetch current workspace features: {e}") + # Don't fail - let SDK validation fail with clear error + + return kwargs + + +async def _workspaces_post_handler( + metadata: ToolMetadata, + result: Dict[str, Any], + kwargs: Dict[str, Any], + context: Dict[str, Any], + method_executor: Any, + category: str, + method_key: str, +) -> Dict[str, Any]: + """Post-processing handler for workspace tools. + + Handles: + - Inject workspace metadata into response for entity URL generation + """ + # For workspace operations, inject workspace info into the result for URL construction + workspace_slug = kwargs.get("workspace_slug") + + if workspace_slug and result.get("success"): + # Get workspace_id from context - try multiple keys + workspace_id = context.get("workspace_id") or context.get("workspace") + + # Ensure the result data has the workspace metadata for URL generation + if "data" in result: + if isinstance(result["data"], dict): + # Inject workspace identifiers if missing + if "id" not in result["data"] and workspace_id: + result["data"]["id"] = str(workspace_id) + if "slug" not in result["data"]: + result["data"]["slug"] = workspace_slug + if "name" not in result["data"]: + # Use slug as a fallback name + result["data"]["name"] = workspace_slug + else: + # Create a minimal data structure for URL generation + result["data"] = { + "id": str(workspace_id) if workspace_id else None, + "slug": workspace_slug, + "name": workspace_slug, + } + + return result + + +# ============================================================================ +# WORKSPACES TOOL DEFINITIONS +# ============================================================================ + +WORKSPACE_TOOL_DEFINITIONS: Dict[str, ToolMetadata] = { + "get_features": ToolMetadata( + name="workspaces_get_features", + description="Get enabled workspace features (initiatives, teams, customers, etc.)", + sdk_method="get_workspace_features", + returns_entity_type="workspace", + post_handler=_workspaces_post_handler, + parameters=[ + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ], + ), + "update_features": ToolMetadata( + name="workspaces_update_features", + description="Enable or disable workspace features", + sdk_method="update_workspace_features", + returns_entity_type="workspace", + pre_handler=_workspaces_pre_handler, + post_handler=_workspaces_post_handler, + parameters=[ + ToolParameter( + name="workspace_slug", + type="Optional[str]", + required=False, + description="Workspace slug (auto-detected from context)", + auto_fill_from_context=True, + ), + ToolParameter( + name="project_grouping", + type="Optional[bool]", + required=False, + description="Enable/disable project grouping feature (optional)", + ), + ToolParameter( + name="initiatives", + type="Optional[bool]", + required=False, + description="Enable/disable initiatives feature (optional)", + ), + ToolParameter( + name="teams", + type="Optional[bool]", + required=False, + description="Enable/disable teams feature (optional)", + ), + ToolParameter( + name="customers", + type="Optional[bool]", + required=False, + description="Enable/disable customers feature (optional)", + ), + ToolParameter( + name="wiki", + type="Optional[bool]", + required=False, + description="Enable/disable wiki feature (optional)", + ), + ToolParameter( + name="pi", + type="Optional[bool]", + required=False, + description="Enable/disable PI (Plane Intelligence) feature (optional)", + ), + ], + ), +} + + +# ============================================================================ +# TOOL FACTORY +# ============================================================================ + + +def get_workspace_tools(method_executor, context): + """Return LangChain tools for the workspaces category using auto-generation from metadata.""" + return generate_tools_for_category( + category="workspaces", + method_executor=method_executor, + context=context, + tool_definitions=WORKSPACE_TOOL_DEFINITIONS, + ) diff --git a/apps/pi/pi/services/chat/action_executor.py b/apps/pi/pi/services/chat/action_executor.py index 79ad54fe51..97c957985e 100644 --- a/apps/pi/pi/services/chat/action_executor.py +++ b/apps/pi/pi/services/chat/action_executor.py @@ -35,6 +35,13 @@ from pi.services.chat.helpers.placeholder_orchestrator import PlaceholderOrchest log = logger.getChild(__name__) +# Mapping of entity_type to tool category +# Some tools have different entity_type than their category (e.g., epic tools are in workitems) +ENTITY_TYPE_TO_CATEGORY = { + "epic": "workitems", # Epic tools are in workitems category + # Add more mappings as needed +} + async def get_execution_context(request, chatbot: PlaneChatBot, user_id, db) -> Tuple[str, Optional[str], bool]: """Extract execution context from request and database.""" @@ -79,7 +86,7 @@ class BuildModeToolExecutor: if not workspace_slug: workspace_slug = await get_workspace_slug(str(workspace_id)) - token, project_id, _ = await get_execution_context(request, self.chatbot, user_id, self.db) + token, project_id, is_project_chat = await get_execution_context(request, self.chatbot, user_id, self.db) # Validate token exists if not token: @@ -101,7 +108,14 @@ class BuildModeToolExecutor: method_executor = MethodExecutor(actions_executor) - context = {"workspace_slug": workspace_slug, "project_id": project_id, "message_id": message_id, "chat_id": chat_id} + context = { + "workspace_slug": workspace_slug, + "workspace_id": str(workspace_id) if workspace_id else None, + "project_id": project_id, + "message_id": message_id, + "chat_id": chat_id, + "is_project_chat": is_project_chat, + } # Execute single action # If single action, execute directly @@ -134,16 +148,25 @@ class BuildModeToolExecutor: args = planned_action["args"] entity_type = planned_action["entity_type"] + # Map entity_type to actual category (e.g., "epic" -> "workitems") + category = ENTITY_TYPE_TO_CATEGORY.get(entity_type, entity_type) + # Build tool - all_category_tools = self.chatbot._build_method_tools(entity_type, method_executor, context) + all_category_tools = self.chatbot._build_method_tools(category, method_executor, context) # get the specific tool we need tool = next((t for t in all_category_tools if t.name == tool_name), None) if not tool: - raise ValueError(f"Tool '{tool_name}' not found in category '{entity_type}'") + raise ValueError(f"Tool '{tool_name}' not found in category '{category}' (entity_type: '{entity_type}')") # Execute the tool - EXPECT structured payload dict - result = await tool.ainvoke(args) + log.info(f"[DEBUG] execute_single_action: About to invoke tool '{tool_name}' with args: {args}") + try: + result = await tool.ainvoke(args) + log.info(f"[DEBUG] execute_single_action: Tool '{tool_name}' returned successfully. Result: {result}") + except Exception as tool_error: + log.error(f"[DEBUG] execute_single_action: Tool '{tool_name}' raised exception: {tool_error}", exc_info=True) + raise if not isinstance(result, dict): raise ValueError(f"Tool '{tool_name}' must return a structured payload dict, got {type(result)}") diff --git a/apps/pi/pi/services/chat/action_planner.py b/apps/pi/pi/services/chat/action_planner.py index 6c12a51f6f..1b635f70ed 100644 --- a/apps/pi/pi/services/chat/action_planner.py +++ b/apps/pi/pi/services/chat/action_planner.py @@ -13,6 +13,7 @@ import contextlib import json +import re from collections.abc import AsyncIterator from typing import Any from typing import Dict @@ -91,7 +92,7 @@ async def _inject_urls_into_entities(entities: list[Dict[str, Any]] | str, pendi # This happens when action tools (not retrieval tools) are used if not url_map: from pi import settings - from pi.agents.sql_agent.tools import construct_entity_urls_from_db + from pi.agents.sql_agent.helpers import construct_entity_urls_from_db # Collect entity IDs by type entity_ids_by_type: Dict[str, List[str]] = {"issues": [], "pages": [], "cycles": [], "modules": [], "projects": []} @@ -446,6 +447,21 @@ async def execute_tools_for_build_mode( _has_tool_calls = hasattr(response, "tool_calls") and bool(getattr(response, "tool_calls", None)) except Exception: _has_tool_calls = False + + # FAILSAFE: Detect if LLM mistakenly put tool_calls in content instead of using API + # This can happen with certain models/prompts - detect and handle gracefully + response_content = str(getattr(response, "content", "") or "").strip() + if not _has_tool_calls and "```tool_calls" in response_content: + log.warning(f"ChatID: {chat_id} - DETECTED: LLM output tool_calls as markdown instead of API. Stripping from content.") + # Strip the tool_calls markdown block from content to avoid showing JSON to user + # Remove ```tool_calls ... ``` blocks from content + cleaned_content = re.sub(r"```tool_calls\s*\n?\[[\s\S]*?\]\s*\n?```", "", response_content) + cleaned_content = cleaned_content.strip() + # Update response content to cleaned version for streaming + if hasattr(response, "content"): + response.content = cleaned_content + log.info(f"ChatID: {chat_id} - Stripped tool_calls markdown. Cleaned content: {cleaned_content[:200]}...") + log.info(f"ChatID: {chat_id} - Has Tool Calls: {_has_tool_calls}") if _has_tool_calls: @@ -872,6 +888,15 @@ async def execute_tools_for_build_mode( # update _has_tool_calls _has_tool_calls = has_more_tool_calls + # FAILSAFE: Detect if LLM mistakenly put tool_calls in content in iterations + if not _has_tool_calls: + iter_content = str(getattr(response, "content", "") or "").strip() + if "```tool_calls" in iter_content: + log.warning(f"ChatID: {chat_id} - DETECTED (iteration {iteration_count}): LLM output tool_calls as markdown. Stripping.") + cleaned_content = re.sub(r"```tool_calls\s*\n?\[[\s\S]*?\]\s*\n?```", "", iter_content).strip() + if hasattr(response, "content"): + response.content = cleaned_content + # Log planner decisions for this iteration try: if _has_tool_calls: diff --git a/apps/pi/pi/services/chat/helpers/action_execution_helpers.py b/apps/pi/pi/services/chat/helpers/action_execution_helpers.py index 23fc276e43..e29df6fd9f 100644 --- a/apps/pi/pi/services/chat/helpers/action_execution_helpers.py +++ b/apps/pi/pi/services/chat/helpers/action_execution_helpers.py @@ -186,6 +186,12 @@ def extract_tool_params_from_artifact_data(artifact_data: Dict[str, Any], entity "epic": {"cycle_id", "module_ids"}, } + # Fields that are auto-generated by SDK and should never be sent to any tool + SDK_AUTO_GENERATED_FIELDS = {"logo_props", "icon_prop", "emoji"} + + # Fields that are project-specific and should not be sent to other entities + PROJECT_ONLY_FIELDS = {"cover_image"} + tool_params = {} unsupported = CREATE_UNSUPPORTED_FIELDS.get(entity_type, set()) if action == "create" else set() @@ -217,23 +223,29 @@ def extract_tool_params_from_artifact_data(artifact_data: Dict[str, Any], entity if key in {"entity_info", "artifact_sub_type"}: continue + # Map artifact field names to tool parameter names FIRST (needed for subsequent checks) + mapped_key = ARTIFACT_TO_TOOL_MAPPING.get(key, key) + + # Skip SDK auto-generated fields (logo_props, icon_prop, emoji) for all entities + if key in SDK_AUTO_GENERATED_FIELDS or mapped_key in SDK_AUTO_GENERATED_FIELDS: + log.debug(f"Skipping SDK auto-generated field '{key}' for {entity_type}") + continue + + # Skip project-only fields for non-project entities + if entity_type != "project" and (key in PROJECT_ONLY_FIELDS or mapped_key in PROJECT_ONLY_FIELDS): + log.debug(f"Skipping project-only field '{key}' for {entity_type}") + continue + # Filter unsupported fields for this entity type and action if key in unsupported: log.warning(f"Field '{key}' cannot be set during {entity_type} {action}, skipping") continue - # Map artifact field names to tool parameter names - mapped_key = ARTIFACT_TO_TOOL_MAPPING.get(key, key) - if mapped_key == "project_lead" and isinstance(value, dict) and value.get("id"): value = value["id"] tool_params[mapped_key] = value - # Project logo/icon compatibility: - if mapped_key == "logo_props" and "icon_prop" not in tool_params: - tool_params["icon_prop"] = value - log.debug(f"Extracted tool params for {entity_type} {action}: {list(tool_params.keys())}") return tool_params @@ -271,22 +283,64 @@ async def load_artifacts(request_data: List[ArtifactData], db: AsyncSession) -> # Transform edited artifact data from frontend schema to tool parameters tool_args = extract_tool_params_from_artifact_data(req_item.action_data or {}, entity_type, action) - # For UPDATE actions, preserve the entity ID from the original artifact + # Get original tool args for preserving context fields + original_tool_args = artifact.data.get("tool_args_raw", {}) + + # PRESERVE CONTEXT FIELDS for all actions (these are never editable but required for execution) + # workspace_slug and project_id are context, not user-editable fields + if "workspace_slug" in original_tool_args and "workspace_slug" not in tool_args: + tool_args["workspace_slug"] = original_tool_args["workspace_slug"] + log.debug(f"Preserved workspace_slug={original_tool_args["workspace_slug"]} for {entity_type} {action}") + + if "project_id" in original_tool_args and "project_id" not in tool_args: + tool_args["project_id"] = original_tool_args["project_id"] + log.debug(f"Preserved project_id={original_tool_args["project_id"]} for {entity_type} {action}") + + # PRESERVE NON-EDITABLE PLANNING PARAMETERS + # These are planning-time decisions that aren't exposed in the edit UI but are critical for execution + NON_EDITABLE_PARAMS = { + # Project feature flags (planning-time decisions) + "cycle_view", + "module_view", + "page_view", + "intake_view", + "is_issue_type_enabled", + "is_time_tracking_enabled", + "issue_views_view", + "guest_view_all_features", + # Project update_features params (must be preserved from plan) + "epics", + "modules", + "cycles", + "views", + "pages", + "intakes", + "work_item_types", + # Other planning parameters + "timezone", + "archive_in", + "close_in", + "external_id", + "external_source", + # User/owner assignments that may be auto-set + "owned_by", + "project_lead", + "default_assignee", + } + + for param in NON_EDITABLE_PARAMS: + if param in original_tool_args and param not in tool_args: + tool_args[param] = original_tool_args[param] + log.debug(f"Preserved non-editable param {param}={original_tool_args[param]} for {entity_type} {action}") + + # For UPDATE actions, also preserve the entity ID being updated # The frontend edits fields but doesn't include the entity ID being updated if action == "update": - original_tool_args = artifact.data.get("tool_args_raw", {}) - # Preserve the entity's ID field (e.g., issue_id, cycle_id, module_id) id_field = ENTITY_ID_FIELD_MAP.get(entity_type) if id_field and id_field in original_tool_args and id_field not in tool_args: tool_args[id_field] = original_tool_args[id_field] log.debug(f"Preserved {id_field}={original_tool_args[id_field]} for {entity_type} update") - - # Also preserve project_id if it's not in the edited data - # (many update tools require it as context even though it's not being changed) - if "project_id" in original_tool_args and "project_id" not in tool_args: - tool_args["project_id"] = original_tool_args["project_id"] - log.info(f"Preserved project_id={original_tool_args["project_id"]} for {entity_type} update") else: # Use original planned tool arguments tool_args = artifact.data.get("tool_args_raw", {}) diff --git a/apps/pi/pi/services/chat/helpers/build_mode_helpers.py b/apps/pi/pi/services/chat/helpers/build_mode_helpers.py index 2668d34d6b..9df1db9e3d 100644 --- a/apps/pi/pi/services/chat/helpers/build_mode_helpers.py +++ b/apps/pi/pi/services/chat/helpers/build_mode_helpers.py @@ -296,6 +296,7 @@ def build_planning_tools( "module", "worklogs", "worklog", + "workitems", # Added to support epic feature checking via projects_retrieve "epics", "epic", "intake", @@ -307,6 +308,15 @@ def build_planning_tools( "pages", "page", ] + workspace_scoped_cats = [ + "initiatives", + "initiative", + "teamspaces", + "teamspace", + "customers", + "customer", + ] + all_method_tools: List[Any] = [] built_categories: List[str] = [] for sel in selections_list: @@ -331,6 +341,14 @@ def build_planning_tools( tools_for_project = [t for t in tools_for_project if getattr(t, "name", "") in ["projects_retrieve", "projects_update"]] all_method_tools.extend(tools_for_project) + if cat in workspace_scoped_cats: + tools_for_workspace = chatbot_instance._build_planning_method_tools("workspaces", method_executor, context) + # remove all tools except workspaces_get_features and workspaces_update_features + tools_for_workspace = [ + t for t in tools_for_workspace if getattr(t, "name", "") in ["workspaces_get_features", "workspaces_update_features"] + ] + all_method_tools.extend(tools_for_workspace) + except Exception as e: log.warning(f"Failed to build tools for category {cat}: {e}") diff --git a/apps/pi/pi/services/chat/helpers/entity_inference.py b/apps/pi/pi/services/chat/helpers/entity_inference.py index f855d503fa..9472874c2c 100644 --- a/apps/pi/pi/services/chat/helpers/entity_inference.py +++ b/apps/pi/pi/services/chat/helpers/entity_inference.py @@ -22,19 +22,54 @@ async def infer_selected_entity(args: Dict[str, Any], context: Dict[str, Any], e """ Generic best-effort entity inference for execute-action results. - Some tools don’t return an `entity` payload even on success. When we can, + Some tools don't return an `entity` payload even on success. When we can, infer the selected entity from request args + context (e.g., issue_id). """ try: workspace_slug = context.get("workspace_slug") + hint = (entity_type_hint or "").strip().lower() + + # Fast-path inference for entities where URL format is fully deterministic from args/context. + # This is especially important for "relationship" tools (e.g. add work-items to cycle) + # where the API response does not include the cycle/module payload. + base = str(settings.plane_api.FRONTEND_URL or "").rstrip("/") + project_id = args.get("project_id") or context.get("project_id") + + cycle_id = args.get("cycle_id") + if workspace_slug and project_id and cycle_id: + return { + "entity_url": f"{base}/{workspace_slug}/projects/{project_id}/cycles/{cycle_id}/", + "entity_name": None, + "entity_type": "cycle" if hint in {"", "cycle"} else hint, + "entity_id": str(cycle_id), + } + + module_id = args.get("module_id") + if workspace_slug and project_id and module_id: + return { + "entity_url": f"{base}/{workspace_slug}/projects/{project_id}/modules/{module_id}/", + "entity_name": None, + "entity_type": "module" if hint in {"", "module"} else hint, + "entity_id": str(module_id), + } + + # Project URL: /{workspace}/projects/{project}/overview/ + if workspace_slug and project_id and hint == "project": + return { + "entity_url": f"{base}/{workspace_slug}/projects/{project_id}/overview/", + "entity_name": None, + "entity_type": "project", + "entity_id": str(project_id), + } + + # Work-item inference (needs identifier resolution for best UX) issue_id = args.get("issue_id") if workspace_slug and issue_id: - from pi.agents.sql_agent.tools import construct_action_entity_url + from pi.agents.sql_agent.helpers import construct_action_entity_url url_info = await construct_action_entity_url({"id": str(issue_id)}, "workitem", str(workspace_slug), settings.plane_api.FRONTEND_URL) if not url_info or not isinstance(url_info, dict): return None - hint = (entity_type_hint or "").strip().lower() subresource_id_fields = { "comment": "comment_id", diff --git a/apps/pi/pi/services/chat/helpers/placeholder_orchestrator.py b/apps/pi/pi/services/chat/helpers/placeholder_orchestrator.py index a001701343..f813160193 100644 --- a/apps/pi/pi/services/chat/helpers/placeholder_orchestrator.py +++ b/apps/pi/pi/services/chat/helpers/placeholder_orchestrator.py @@ -188,7 +188,7 @@ class PlaceholderOrchestrator: remaining.remove(action) except Exception as e: - log.error(f"Failed to execute action {action.get("tool_name")}: {e}") + log.error(f"Failed to execute action {action.get("tool_name")}: {e}", exc_info=True) # Format error message for user-friendly display formatted_error = _format_validation_error(str(e)) # Create failure result @@ -349,15 +349,16 @@ class PlaceholderOrchestrator: if not entity_type or not entity_name: raise ValueError(f"Failed to parse placeholder: {placeholder}") - # Build lookup key - lookup_key = f"{entity_type}:{entity_name}" + # Build lookup key (lowercase for case-insensitive matching) + lookup_key = f"{entity_type}:{entity_name.lower()}" + name_key = entity_name.lower() - # Try exact match first + # Try exact match first (keys are stored lowercase) if lookup_key in self.execution_context: context_entry = self.execution_context[lookup_key] - elif entity_name in self.execution_context: + elif name_key in self.execution_context: # Fallback to name-only lookup - context_entry = self.execution_context[entity_name] + context_entry = self.execution_context[name_key] else: raise ValueError( f"Entity '{entity_name}' (type: {entity_type}) not found in execution context. " @@ -498,11 +499,24 @@ IMPORTANT: # Build tool if not cached if tool_name not in self.tools_cache: - entity_type = action.get("entity_type") - if entity_type: - tools = self.chatbot._build_method_tools(entity_type, self.method_executor, self.context) - for tool in tools: - self.tools_cache[tool.name] = tool + # Special cases where tool name doesn't follow {category}_{method} pattern + SPECIAL_TOOL_CATEGORIES = { + "create_epic": "workitems", + "update_epic": "workitems", + } + + # Extract category from tool name + if tool_name in SPECIAL_TOOL_CATEGORIES: + category = SPECIAL_TOOL_CATEGORIES[tool_name] + else: + # Standard pattern: {category}_{method} + # e.g., "initiatives_create_label" -> "initiatives" + category = tool_name.split("_")[0] if "_" in tool_name else tool_name + + log.info(f"Building tools for category '{category}' (tool: {tool_name})") + tools = self.chatbot._build_method_tools(category, self.method_executor, self.context) + for tool in tools: + self.tools_cache[tool.name] = tool # Get the tool tool = self.tools_cache.get(tool_name) @@ -510,7 +524,13 @@ IMPORTANT: raise ValueError(f"Tool '{tool_name}' not found") # Execute the tool - result = await tool.ainvoke(args) + log.info(f"[DEBUG] About to invoke tool '{tool_name}' with args: {args}") + try: + result = await tool.ainvoke(args) + log.info(f"[DEBUG] Tool '{tool_name}' invocation completed. Result type: {type(result)}") + except Exception as tool_error: + log.error(f"[DEBUG] Tool '{tool_name}' raised exception during ainvoke: {tool_error}", exc_info=True) + raise if not isinstance(result, dict): raise ValueError(f"Tool '{tool_name}' must return a dict, got {type(result)}") @@ -560,20 +580,22 @@ IMPORTANT: return # Get the planned name from action args - planned_name = action.get("args", {}).get("name") + # Check both 'name' and 'display_name' (properties use display_name) + planned_name = action.get("args", {}).get("name") or action.get("args", {}).get("display_name") - # Build all possible lookup keys + # Build all possible lookup keys (use lowercase for case-insensitive matching) keys = [ - f"{entity_type}:{actual_name}", # e.g., "project:Motor Bike47119" - actual_name, # Allow lookup by actual name alone + f"{entity_type}:{actual_name.lower()}", # e.g., "property:severity" + actual_name.lower(), # Allow lookup by actual name alone ] # IMPORTANT: Also store under planned name if different from actual - # This handles SDK name modifications on conflict (409) - if planned_name and planned_name != actual_name: - keys.append(f"{entity_type}:{planned_name}") # e.g., "project:Motor Bike" - keys.append(planned_name) # Allow lookup by planned name - log.info(f"⚠️ Name mismatch: planned='{planned_name}' vs actual='{actual_name}'. " f"Storing under both names for lookup.") + # This handles SDK name modifications on conflict (409) AND case differences + if planned_name: + keys.append(f"{entity_type}:{planned_name.lower()}") # e.g., "property:severity" + keys.append(planned_name.lower()) # Allow lookup by planned name + if planned_name.lower() != actual_name.lower(): + log.info(f"⚠️ Name mismatch: planned='{planned_name}' vs actual='{actual_name}'. " f"Storing under both names for lookup.") # Store under all keys for key in keys: @@ -583,7 +605,7 @@ IMPORTANT: def _can_resolve_from_context(self, entity_type: Optional[str], entity_name: Optional[str]) -> bool: """ - Check if we have this entity in our execution context. + Check if we have this entity in our execution context (case-insensitive). Args: entity_type: Type of entity (e.g., "project") @@ -595,9 +617,10 @@ IMPORTANT: if not entity_type or not entity_name: return False - # Check if we have this entity stored - key = f"{entity_type}:{entity_name}" - return key in self.execution_context or entity_name in self.execution_context + # Check if we have this entity stored (case-insensitive) + key = f"{entity_type}:{entity_name.lower()}" + name_key = entity_name.lower() + return key in self.execution_context or name_key in self.execution_context def _is_placeholder(self, value: Any) -> bool: """Check if value is a placeholder string.""" diff --git a/apps/pi/pi/services/chat/helpers/tool_utils.py b/apps/pi/pi/services/chat/helpers/tool_utils.py index e9aa590f0f..646680b94c 100644 --- a/apps/pi/pi/services/chat/helpers/tool_utils.py +++ b/apps/pi/pi/services/chat/helpers/tool_utils.py @@ -78,11 +78,12 @@ TOOL_NAME_TO_CATEGORY_MAP: Dict[str, Dict[str, str]] = { "pages_create_project_page": {"entity_type": "page", "action_type": "create", "front_facing_name": "Create Project Page"}, "pages_create_workspace_page": {"entity_type": "page", "action_type": "create", "front_facing_name": "Create Workspace Page"}, # Projects - "projects_archive": {"entity_type": "project", "action_type": "archive", "front_facing_name": "Archive Project"}, "projects_create": {"entity_type": "project", "action_type": "create", "front_facing_name": "Create Project"}, - "projects_unarchive": {"entity_type": "project", "action_type": "unarchive", "front_facing_name": "Unarchive Project"}, + "projects_delete": {"entity_type": "project", "action_type": "delete", "front_facing_name": "Delete Project"}, "projects_update": {"entity_type": "project", "action_type": "update", "front_facing_name": "Update Project"}, "projects_retrieve": {"entity_type": "project", "action_type": "retrieve", "front_facing_name": "Retrieve Project"}, + "projects_get_features": {"entity_type": "project", "action_type": "get", "front_facing_name": "Get Project Features"}, + "projects_update_features": {"entity_type": "project", "action_type": "update", "front_facing_name": "Update Project Features"}, # Properties "properties_create": {"entity_type": "property", "action_type": "create", "front_facing_name": "Create Property"}, "properties_create_option": {"entity_type": "property", "action_type": "create_option", "front_facing_name": "Create Property Option"}, @@ -98,6 +99,52 @@ TOOL_NAME_TO_CATEGORY_MAP: Dict[str, Dict[str, str]] = { "types_create": {"entity_type": "type", "action_type": "create", "front_facing_name": "Create Type"}, "types_delete": {"entity_type": "type", "action_type": "delete", "front_facing_name": "Delete Type"}, "types_update": {"entity_type": "type", "action_type": "update", "front_facing_name": "Update Type"}, + # Initiatives (SDK v0.2.1) + "initiatives_create": {"entity_type": "initiative", "action_type": "create", "front_facing_name": "Create Initiative"}, + "initiatives_list": {"entity_type": "initiative", "action_type": "list", "front_facing_name": "List Initiatives"}, + "initiatives_retrieve": {"entity_type": "initiative", "action_type": "retrieve", "front_facing_name": "Retrieve Initiative"}, + "initiatives_update": {"entity_type": "initiative", "action_type": "update", "front_facing_name": "Update Initiative"}, + "initiatives_delete": {"entity_type": "initiative", "action_type": "delete", "front_facing_name": "Delete Initiative"}, + "initiatives_create_label": {"entity_type": "initiative_label", "action_type": "create", "front_facing_name": "Create Initiative Label"}, + "initiatives_list_labels": {"entity_type": "initiative_label", "action_type": "list", "front_facing_name": "List Initiative Labels"}, + "initiatives_retrieve_label": {"entity_type": "initiative_label", "action_type": "retrieve", "front_facing_name": "Retrieve Initiative Label"}, + "initiatives_update_label": {"entity_type": "initiative_label", "action_type": "update", "front_facing_name": "Update Initiative Label"}, + "initiatives_delete_label": {"entity_type": "initiative_label", "action_type": "delete", "front_facing_name": "Delete Initiative Label"}, + "initiatives_add_labels": {"entity_type": "initiative", "action_type": "add", "front_facing_name": "Add Labels to Initiative"}, + "initiatives_remove_labels": {"entity_type": "initiative", "action_type": "remove", "front_facing_name": "Remove Labels from Initiative"}, + "initiatives_add_projects": {"entity_type": "initiative", "action_type": "add", "front_facing_name": "Add Projects to Initiative"}, + "initiatives_list_projects": {"entity_type": "initiative", "action_type": "list", "front_facing_name": "List Initiative Projects"}, + "initiatives_remove_projects": {"entity_type": "initiative", "action_type": "remove", "front_facing_name": "Remove Projects from Initiative"}, + "initiatives_add_epics": {"entity_type": "initiative", "action_type": "add", "front_facing_name": "Add Epics to Initiative"}, + "initiatives_list_epics": {"entity_type": "initiative", "action_type": "list", "front_facing_name": "List Initiative Epics"}, + "initiatives_remove_epics": {"entity_type": "initiative", "action_type": "remove", "front_facing_name": "Remove Epics from Initiative"}, + # Teamspaces (SDK v0.2.1) + "teamspaces_create": {"entity_type": "teamspace", "action_type": "create", "front_facing_name": "Create Teamspace"}, + "teamspaces_list": {"entity_type": "teamspace", "action_type": "list", "front_facing_name": "List Teamspaces"}, + "teamspaces_retrieve": {"entity_type": "teamspace", "action_type": "retrieve", "front_facing_name": "Retrieve Teamspace"}, + "teamspaces_update": {"entity_type": "teamspace", "action_type": "update", "front_facing_name": "Update Teamspace"}, + "teamspaces_delete": {"entity_type": "teamspace", "action_type": "delete", "front_facing_name": "Delete Teamspace"}, + "teamspaces_add_members": {"entity_type": "teamspace", "action_type": "add", "front_facing_name": "Add Members to Teamspace"}, + "teamspaces_list_members": {"entity_type": "teamspace", "action_type": "list", "front_facing_name": "List Teamspace Members"}, + "teamspaces_remove_members": {"entity_type": "teamspace", "action_type": "remove", "front_facing_name": "Remove Members from Teamspace"}, + "teamspaces_add_projects": {"entity_type": "teamspace", "action_type": "add", "front_facing_name": "Add Projects to Teamspace"}, + "teamspaces_list_projects": {"entity_type": "teamspace", "action_type": "list", "front_facing_name": "List Teamspace Projects"}, + "teamspaces_remove_projects": {"entity_type": "teamspace", "action_type": "remove", "front_facing_name": "Remove Projects from Teamspace"}, + # Stickies (SDK v0.2.1) + "stickies_create": {"entity_type": "sticky", "action_type": "create", "front_facing_name": "Create Sticky Note"}, + "stickies_list": {"entity_type": "sticky", "action_type": "list", "front_facing_name": "List Sticky Notes"}, + "stickies_retrieve": {"entity_type": "sticky", "action_type": "retrieve", "front_facing_name": "Retrieve Sticky Note"}, + "stickies_update": {"entity_type": "sticky", "action_type": "update", "front_facing_name": "Update Sticky Note"}, + "stickies_delete": {"entity_type": "sticky", "action_type": "delete", "front_facing_name": "Delete Sticky Note"}, + # Customers (SDK v0.2.1) + "customers_create": {"entity_type": "customer", "action_type": "create", "front_facing_name": "Create Customer"}, + "customers_list": {"entity_type": "customer", "action_type": "list", "front_facing_name": "List Customers"}, + "customers_retrieve": {"entity_type": "customer", "action_type": "retrieve", "front_facing_name": "Retrieve Customer"}, + "customers_update": {"entity_type": "customer", "action_type": "update", "front_facing_name": "Update Customer"}, + "customers_delete": {"entity_type": "customer", "action_type": "delete", "front_facing_name": "Delete Customer"}, + # Workspaces (SDK v0.2.2 - features) + "workspaces_get_features": {"entity_type": "workspace", "action_type": "get", "front_facing_name": "Get Workspace Features"}, + "workspaces_update_features": {"entity_type": "workspace", "action_type": "update", "front_facing_name": "Update Workspace Features"}, # Workitems and Epics "create_epic": {"entity_type": "epic", "action_type": "create", "front_facing_name": "Create Epic"}, "update_epic": {"entity_type": "epic", "action_type": "update", "front_facing_name": "Update Epic"}, @@ -636,7 +683,7 @@ work_tree_instructions_normal_response = """ **IF the user's request is informational/retrieval-only (questions, searches, listing, checking status):** 1. Use retrieval/search tools to gather the requested information 2. Provide a detailed, elaborate, and neatly formatted answer in the content section based on the retrieved data. Do NOT be brief. -3. Do NOT plan any modifying actions - just return tool_calls for retrieval, then answer in your content +3. Do NOT plan any modifying actions - just invoke retrieval tools, then answer in your content 4. **Formatting Requirements**: While formatting the answer in the final content section, use the following rules: - Use "work-item" (not "issue") and "unique key" (not "Issue ID") terminology @@ -649,8 +696,8 @@ work_tree_instructions_normal_response = """ **IF the user's request requires modifying data (create, update, delete, move, assign, etc.):** 1. Use retrieval/search tools to gather necessary information (IDs, etc.) -2. **AND** plan at least one MODIFYING ACTION using tool_calls (create, update, delete, add, remove, move, etc.) -3. You CANNOT stop after just searching/retrieving - you MUST plan the modifying actions with tool_calls +2. **AND** invoke at least one MODIFYING ACTION tool (create, update, delete, add, remove, move, etc.) +3. You CANNOT stop after just searching/retrieving - you MUST invoke the modifying action tools 4. Provide a very brief summary of what you planned in your content 5. **Formatting Requirements**: While formatting the action plan in the final content section, use the following rules: @@ -667,14 +714,14 @@ work_tree_instructions_normal_response = """ - Do NOT create workaround entities (like workitems) to satisfy these requests - Do NOT plan any actions - just provide the explanation in your content -Note: The system uses absence of tool_calls as the signal to stop and deliver your content as the final answer. For modification requests, include at least one write tool_call in your plan. +Note: The system detects when you stop invoking tools and delivers your content as the final answer. For modification requests, you MUST invoke at least one write action tool. """ # noqa E501 work_tree_instructions_app_response = f""" **IF the user's request is informational/retrieval-only (questions, searches, listing, checking status):** 1. Use retrieval/search tools to gather the requested information 2. Provide a detailed, and elaborate answer in PLAIN TEXT ONLY in the 'text' field in the provide_final_answer_for_app tool based on the retrieved data. Do NOT be brief. -3. Do NOT plan any modifying actions - just return tool_calls for retrieval, then call provide_final_answer_for_app +3. Do NOT plan any modifying actions - just invoke retrieval tools, then call provide_final_answer_for_app 4. **Formatting Requirements - CRITICAL FOR EXTERNAL APP (e.g., Slack) RENDERING**: While generating the answer in the 'text' field in the provide_final_answer_for_app tool, use the following rules: - **ABSOLUTELY NO MARKDOWN FORMATTING**: Do not use **bold**, *italic*, headers, or any markdown syntax @@ -697,8 +744,8 @@ work_tree_instructions_app_response = f""" **IF the user's request requires modifying data (create, update, delete, move, assign, etc.):** 1. Use retrieval/search tools to gather necessary information (IDs, etc.) -2. **AND** plan at least one MODIFYING ACTION using tool_calls (create, update, delete, add, remove, move, etc.) -3. You CANNOT stop after just searching/retrieving - you MUST plan the modifying actions with tool_calls +2. **AND** invoke at least one MODIFYING ACTION tool (create, update, delete, add, remove, move, etc.) +3. You CANNOT stop after just searching/retrieving - you MUST invoke the modifying action tools 4. Provide a very brief summary of what you planned in your content 5. **Formatting Requirements**: While formatting the action plan in the final content section, use the following rules: @@ -714,7 +761,7 @@ work_tree_instructions_app_response = f""" - Do NOT create workaround entities (like workitems) to satisfy these requests - Do NOT plan any actions - just provide the explanation in your content -Note: This is a response for consumption by an external app. So, calling provide_final_answer_for_app signals completion for retrieval-only requests. For modification requests, include at least one write tool_call in your plan. +Note: This is a response for consumption by an external app. Calling provide_final_answer_for_app signals completion for retrieval-only requests. For modification requests, you MUST invoke at least one write action tool. """ # noqa E501 @@ -777,6 +824,32 @@ Use retrieval tools to gather information, then plan the modifying actions based - Do not try to execute actions - only plan them - For multi-property updates, resolve all required IDs first, then set all properties in a single tool call +**MANDATORY REASONING AND COMMUNICATION (CRITICAL - REQUIRED FOR EVERY TOOL CALL):** +- **BEFORE EACH TOOL CALL**: You MUST explain your reasoning and intent + - State what information you're trying to gather or what action you're planning + - Explain why this tool is necessary for completing the user's request + - Describe what you expect to get from the tool and how you'll use it + - Example: "The user wants to check workitems assigned to Anil. First, I need to search for the user 'Anil' to get their ID, then I'll use that ID to filter workitems." # noqa: E501 +- **AFTER EACH TOOL CALL**: You MUST provide a brief summary of what you learned + - Summarize key information obtained from the tool + - Explain how this information helps with the next step + - If the tool returned unexpected results, explain how you'll adapt + - Example: "Found user Anil Kumar with ID xyz-123. Now I'll use this ID to search for workitems assigned to them." # noqa: E501 +- **THINKING OUT LOUD**: Express your thought process naturally + - Share your understanding of the user's request + - Explain your strategy for accomplishing the task + - Mention any assumptions you're making +- This reasoning is MANDATORY and helps with debugging and understanding your decision-making process +- NEVER skip the reasoning - it's essential for transparency and troubleshooting + +**CRITICAL: OPTIONAL PARAMETERS POLICY (APPLIES TO ALL TOOLS):** +- Only provide optional parameters that are EXPLICITLY requested by the user or clearly implied by their intent +- DO NOT auto-fill optional fields with "sensible defaults" or inferred values +- **DO NOT ask the user for clarification if optional parameters are missing.** +- **IF an optional parameter is not provided, you MUST leave it empty and let the API use its default.** +- This applies to ALL optional fields across ALL entity types (description, priority, state, assignees, dates, etc.) +- When in doubt, omit the field. + **WORKSPACE-LEVEL QUERIES (EFFICIENCY):** |- When query is related to workitems and spans ALL projects without specifying a particular project or projects | - DO NOT: call `list_member_projects` then query each project with `structured_db_tool` separately @@ -787,28 +860,76 @@ Use retrieval tools to gather information, then plan the modifying actions based |- For project-specific queries, include the specific `project_id` **PROJECT FEATURES CHECK (CRITICAL - MANDATORY BEFORE CREATING PROJECT-SCOPED ENTITIES):** -- Cycles, modules, pages, workitem types, views, intake, and time-tracking (worklogs) are project-level features that are enabled/disabled on a per-project basis. -- **MANDATORY WORKFLOW**: Before creating ANY of these entities (cycles_create, modules_create, pages_create_*, worklogs_create, etc.), you MUST: - 1. First get the project_id (via search_project_by_name or search_project_by_identifier if not already known) - 2. **THEN** call `projects_retrieve` with that project_id to check if the feature is enabled - 3. **AFTER checking**: You MUST plan the required actions using tool_calls: - - If the feature IS enabled: Plan the creation action (e.g., `cycles_create`, `modules_create`, `worklogs_create`) - - If the feature is NOT enabled: Plan BOTH `projects_update` (to enable the feature) AND the creation action (e.g., `cycles_create`, `modules_create`, `worklogs_create`) - 4. **CRITICAL**: After `projects_retrieve` completes, you CANNOT stop - you MUST continue planning the modifying actions. Do NOT return only text - you MUST return tool_calls for the planned actions. - 5. **REMEMBER**: `projects_retrieve` is ONLY for information gathering. The user's actual request (create cycle/module/page/worklog) is NOT complete until you plan the creation action with tool_calls. Do NOT stop after retrieval - the task is incomplete without planning the creation. -- **CRITICAL**: This check is NON-NEGOTIABLE. Never skip the `projects_retrieve` step when creating cycles, modules, pages, or other project-scoped features. -- **CRITICAL**: After retrieving project features, you MUST plan the actions - do NOT stop after retrieval. The user requested a modification (create cycle/module/page/worklog), so you MUST plan it with tool_calls. -- **EXCEPTION (NEW PROJECT IN CURRENT PLAN)**: If the target project is being CREATED in this same plan and does not yet have a real UUID, do NOT call `projects_retrieve` during planning. Use placeholders for downstream actions and defer any feature checks until after execution or when working with an existing project that has a UUID. +- Cycles, modules, pages, workitem types, views, intake, epics (a special workitem type), and time-tracking (worklogs) are project-level features that are enabled/disabled on a per-project basis. +- **MANDATORY WORKFLOW**: Before creating ANY of these entities (cycles_create, create_epic, modules_create, pages_create_*, worklogs_create, intake_create, etc.), you MUST: + 1. First get the project_id (UUID) (via search_project_by_name or search_project_by_identifier (Identifier looks like 'PROJ', 'WEB' etc. It is not a UUID) if not already known) + 2. **THEN** call `projects_retrieve` with that project_id to check if the feature is enabled. + - **WARNING**: Do NOT stop to ask for clarification on optional entity fields (e.g., description, priority) before this check. + - **WARNING**: You must perform this check even if you think you need more information for the creaton. + - **WARNING**: You must perform this check even if you already have all required IDs (issue_id, project_id, etc.). Having IDs does NOT exempt you from checking if the feature is enabled. + 3. **AFTER checking**: You MUST invoke the required action tools: + - If the feature IS enabled: Plan the creation action (e.g., `cycles_create`, `create_epic`, `modules_create`, `types_create`, `worklogs_create`, `intake_create`, etc.) + - If the feature is NOT enabled: Plan BOTH `projects_update` (to enable the feature) AND the creation action (e.g., `cycles_create`, `create_epic`, `modules_create`, `types_create`, `worklogs_create`, `intake_create`, etc.) + 4. **CRITICAL**: After `projects_retrieve` completes, you CANNOT stop - you MUST continue invoking the modifying action tools. Do NOT return only text - you MUST invoke the action tools. +- **CRITICAL**: This check is NON-NEGOTIABLE. Never skip the `projects_retrieve` step when creating cycles, modules, pages, types, intake items, or other project-scoped features. +- **CONSEQUENCE**: Skipping `projects_retrieve` and directly calling creation tools (e.g., worklogs_create, cycles_create, intake_create) WILL result in a 404 error if the feature is disabled. Always check first. +- **MULTI-ACTION REQUESTS**: When handling requests with multiple actions, if ANY action requires a feature check, you MUST call `projects_retrieve` FIRST before planning any of the actions. +- **EXCEPTION (NEW PROJECT IN CURRENT PLAN)**: If the target project is being CREATED in this same plan and does not yet have a real UUID: + - Do NOT call `projects_retrieve` during planning (the project doesn't exist yet to retrieve) + - Instead, you MUST enable the required feature flag during `projects_create` itself + - **Example**: If planning to create a project AND a cycle in the same plan: + 1. Call `projects_create` with `cycle_view=True` (to enable cycles feature) + 2. Call `cycles_create` with `project_id="