iflow-mcp-m507_ai-soc-agent 1.0.0__py3-none-any.whl

src/orchestrator/tools_eng.py

@@ -0,0 +1,378 @@
+"""
+Orchestrator tools for Engineering integrations (Trello, ClickUp, GitHub).
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Any, Optional, Union
+
+from ..integrations.eng.trello.trello_client import TrelloClient
+from ..integrations.eng.clickup.clickup_client import ClickUpClient
+from ..integrations.eng.github.github_client import GitHubClient
+
+
+def create_fine_tuning_recommendation(
+    title: str,
+    description: str,
+    list_name: Optional[str] = None,
+    labels: Optional[list[str]] = None,
+    status: Optional[str] = None,
+    tags: Optional[list[str]] = None,
+    client: Optional[Union[TrelloClient, ClickUpClient, GitHubClient]] = None,
+) -> Dict[str, Any]:
+    """
+    Create a fine-tuning recommendation on the fine-tuning board.
+    
+    Supports Trello (cards), ClickUp (tasks), and GitHub (project items).
+    
+    Args:
+        title: Task/card title
+        description: Task/card description
+        list_name: Optional list name (Trello only, defaults to first list on board)
+        labels: Optional list of label names (Trello only)
+        status: Optional status name (ClickUp only, defaults to first status in list)
+        tags: Optional list of tag names (ClickUp only)
+        client: TrelloClient, ClickUpClient, or GitHubClient instance (required)
+    
+    Returns:
+        Dictionary with task/card/project item information
+    """
+    if not client:
+        raise ValueError("Engineering client (TrelloClient, ClickUpClient, or GitHubClient) is required")
+    
+    if isinstance(client, TrelloClient):
+        result = client.create_fine_tuning_recommendation(
+            title=title,
+            description=description,
+            list_name=list_name,
+            labels=labels,
+        )
+        return {
+            "success": True,
+            "provider": "trello",
+            "card": {
+                "id": result.get("id"),
+                "name": result.get("name"),
+                "url": result.get("url"),
+                "board_id": result.get("idBoard"),
+            },
+        }
+    elif isinstance(client, ClickUpClient):
+        result = client.create_fine_tuning_recommendation(
+            title=title,
+            description=description,
+            status=status,
+            tags=tags,
+        )
+        return {
+            "success": True,
+            "provider": "clickup",
+            "task": {
+                "id": result.get("id"),
+                "name": result.get("name"),
+                "url": result.get("url"),
+                "list_id": result.get("list", {}).get("id") if isinstance(result.get("list"), dict) else None,
+            },
+        }
+    elif isinstance(client, GitHubClient):
+        result = client.create_fine_tuning_recommendation(
+            title=title,
+            description=description,
+        )
+        return {
+            "success": True,
+            "provider": "github",
+            "project_item": {
+                "id": result.get("id"),
+                "note": result.get("note"),
+                "url": result.get("url"),
+                "project_id": result.get("project_id"),
+            },
+        }
+    else:
+        raise ValueError(f"Unsupported client type: {type(client)}")
+
+
+def create_visibility_recommendation(
+    title: str,
+    description: str,
+    list_name: Optional[str] = None,
+    labels: Optional[list[str]] = None,
+    status: Optional[str] = None,
+    tags: Optional[list[str]] = None,
+    client: Optional[Union[TrelloClient, ClickUpClient, GitHubClient]] = None,
+) -> Dict[str, Any]:
+    """
+    Create a visibility/engineering recommendation on the engineering board.
+    
+    Supports Trello (cards), ClickUp (tasks), and GitHub (project items).
+    
+    Args:
+        title: Task/card title
+        description: Task/card description
+        list_name: Optional list name (Trello only, defaults to first list on board)
+        labels: Optional list of label names (Trello only)
+        status: Optional status name (ClickUp only, defaults to first status in list)
+        tags: Optional list of tag names (ClickUp only)
+        client: TrelloClient, ClickUpClient, or GitHubClient instance (required)
+    
+    Returns:
+        Dictionary with task/card/project item information
+    """
+    if not client:
+        raise ValueError("Engineering client (TrelloClient, ClickUpClient, or GitHubClient) is required")
+    
+    if isinstance(client, TrelloClient):
+        result = client.create_visibility_recommendation(
+            title=title,
+            description=description,
+            list_name=list_name,
+            labels=labels,
+        )
+        return {
+            "success": True,
+            "provider": "trello",
+            "card": {
+                "id": result.get("id"),
+                "name": result.get("name"),
+                "url": result.get("url"),
+                "board_id": result.get("idBoard"),
+            },
+        }
+    elif isinstance(client, ClickUpClient):
+        result = client.create_visibility_recommendation(
+            title=title,
+            description=description,
+            status=status,
+            tags=tags,
+        )
+        return {
+            "success": True,
+            "provider": "clickup",
+            "task": {
+                "id": result.get("id"),
+                "name": result.get("name"),
+                "url": result.get("url"),
+                "list_id": result.get("list", {}).get("id") if isinstance(result.get("list"), dict) else None,
+            },
+        }
+    elif isinstance(client, GitHubClient):
+        result = client.create_visibility_recommendation(
+            title=title,
+            description=description,
+        )
+        return {
+            "success": True,
+            "provider": "github",
+            "project_item": {
+                "id": result.get("id"),
+                "note": result.get("note"),
+                "url": result.get("url"),
+                "project_id": result.get("project_id"),
+            },
+        }
+    else:
+        raise ValueError(f"Unsupported client type: {type(client)}")
+
+
+
+def list_fine_tuning_recommendations(
+    archived: bool = False,
+    include_closed: bool = True,
+    order_by: Optional[str] = None,
+    reverse: bool = False,
+    subtasks: bool = False,
+    statuses: Optional[list[str]] = None,
+    include_markdown_description: bool = False,
+    client: Optional[Union[TrelloClient, ClickUpClient, GitHubClient]] = None,
+) -> Dict[str, Any]:
+    """
+    List all fine-tuning recommendations.
+    
+    Currently only supports ClickUp. Trello and GitHub support can be added later.
+    
+    Args:
+        archived: Include archived tasks (ClickUp only, default: False)
+        include_closed: Include closed tasks (ClickUp only, default: True)
+        order_by: Order tasks by field (ClickUp only)
+        reverse: Reverse the order (ClickUp only, default: False)
+        subtasks: Include subtasks (ClickUp only, default: False)
+        statuses: Filter by status names (ClickUp only)
+        include_markdown_description: Include markdown in descriptions (ClickUp only, default: False)
+        client: TrelloClient, ClickUpClient, or GitHubClient instance (required)
+    
+    Returns:
+        Dictionary with list of recommendations
+    """
+    if not client:
+        raise ValueError("Engineering client (TrelloClient, ClickUpClient, or GitHubClient) is required")
+    
+    if isinstance(client, ClickUpClient):
+        tasks = client.list_fine_tuning_recommendations(
+            archived=archived,
+            include_closed=include_closed,
+            order_by=order_by,
+            reverse=reverse,
+            subtasks=subtasks,
+            statuses=statuses,
+            include_markdown_description=include_markdown_description,
+        )
+        return {
+            "success": True,
+            "provider": "clickup",
+            "count": len(tasks),
+            "tasks": [
+                {
+                    "id": task.get("id"),
+                    "name": task.get("name"),
+                    "url": task.get("url"),
+                    "status": task.get("status", {}).get("status") if isinstance(task.get("status"), dict) else None,
+                    "description": task.get("description", ""),
+                }
+                for task in tasks
+            ],
+        }
+    else:
+        raise ValueError(f"list_fine_tuning_recommendations is not supported for client type: {type(client)}")
+
+
+def list_visibility_recommendations(
+    archived: bool = False,
+    include_closed: bool = True,
+    order_by: Optional[str] = None,
+    reverse: bool = False,
+    subtasks: bool = False,
+    statuses: Optional[list[str]] = None,
+    include_markdown_description: bool = False,
+    client: Optional[Union[TrelloClient, ClickUpClient, GitHubClient]] = None,
+) -> Dict[str, Any]:
+    """
+    List all visibility/engineering recommendations.
+    
+    Currently only supports ClickUp. Trello and GitHub support can be added later.
+    
+    Args:
+        archived: Include archived tasks (ClickUp only, default: False)
+        include_closed: Include closed tasks (ClickUp only, default: True)
+        order_by: Order tasks by field (ClickUp only)
+        reverse: Reverse the order (ClickUp only, default: False)
+        subtasks: Include subtasks (ClickUp only, default: False)
+        statuses: Filter by status names (ClickUp only)
+        include_markdown_description: Include markdown in descriptions (ClickUp only, default: False)
+        client: TrelloClient, ClickUpClient, or GitHubClient instance (required)
+    
+    Returns:
+        Dictionary with list of recommendations
+    """
+    if not client:
+        raise ValueError("Engineering client (TrelloClient, ClickUpClient, or GitHubClient) is required")
+    
+    if isinstance(client, ClickUpClient):
+        tasks = client.list_visibility_recommendations(
+            archived=archived,
+            include_closed=include_closed,
+            order_by=order_by,
+            reverse=reverse,
+            subtasks=subtasks,
+            statuses=statuses,
+            include_markdown_description=include_markdown_description,
+        )
+        return {
+            "success": True,
+            "provider": "clickup",
+            "count": len(tasks),
+            "tasks": [
+                {
+                    "id": task.get("id"),
+                    "name": task.get("name"),
+                    "url": task.get("url"),
+                    "status": task.get("status", {}).get("status") if isinstance(task.get("status"), dict) else None,
+                    "description": task.get("description", ""),
+                }
+                for task in tasks
+            ],
+        }
+    else:
+        raise ValueError(f"list_visibility_recommendations is not supported for client type: {type(client)}")
+
+
+def add_comment_to_fine_tuning_recommendation(
+    task_id: str,
+    comment_text: str,
+    client: Optional[Union[TrelloClient, ClickUpClient, GitHubClient]] = None,
+) -> Dict[str, Any]:
+    """
+    Add a comment to a fine-tuning recommendation task.
+    
+    Currently only supports ClickUp. Trello and GitHub support can be added later.
+    
+    Args:
+        task_id: Task ID
+        comment_text: Comment text/content
+        client: TrelloClient, ClickUpClient, or GitHubClient instance (required)
+    
+    Returns:
+        Dictionary with comment information
+    """
+    if not client:
+        raise ValueError("Engineering client (TrelloClient, ClickUpClient, or GitHubClient) is required")
+    
+    if isinstance(client, ClickUpClient):
+        comment = client.add_comment_to_fine_tuning_recommendation(
+            task_id=task_id,
+            comment_text=comment_text,
+        )
+        return {
+            "success": True,
+            "provider": "clickup",
+            "comment": {
+                "id": comment.get("id"),
+                "comment_text": comment.get("comment", [{}])[0].get("text") if isinstance(comment.get("comment"), list) and comment.get("comment") else comment.get("comment_text", ""),
+                "user": comment.get("user", {}).get("username") if isinstance(comment.get("user"), dict) else None,
+            },
+            "task_id": task_id,
+            "message": f"Comment added to fine-tuning recommendation task {task_id}",
+        }
+    else:
+        raise ValueError(f"add_comment_to_fine_tuning_recommendation is not supported for client type: {type(client)}")
+
+
+def add_comment_to_visibility_recommendation(
+    task_id: str,
+    comment_text: str,
+    client: Optional[Union[TrelloClient, ClickUpClient, GitHubClient]] = None,
+) -> Dict[str, Any]:
+    """
+    Add a comment to a visibility/engineering recommendation task.
+    
+    Currently only supports ClickUp. Trello and GitHub support can be added later.
+    
+    Args:
+        task_id: Task ID
+        comment_text: Comment text/content
+        client: TrelloClient, ClickUpClient, or GitHubClient instance (required)
+    
+    Returns:
+        Dictionary with comment information
+    """
+    if not client:
+        raise ValueError("Engineering client (TrelloClient, ClickUpClient, or GitHubClient) is required")
+    
+    if isinstance(client, ClickUpClient):
+        comment = client.add_comment_to_visibility_recommendation(
+            task_id=task_id,
+            comment_text=comment_text,
+        )
+        return {
+            "success": True,
+            "provider": "clickup",
+            "comment": {
+                "id": comment.get("id"),
+                "comment_text": comment.get("comment", [{}])[0].get("text") if isinstance(comment.get("comment"), list) and comment.get("comment") else comment.get("comment_text", ""),
+                "user": comment.get("user", {}).get("username") if isinstance(comment.get("user"), dict) else None,
+            },
+            "task_id": task_id,
+            "message": f"Comment added to visibility recommendation task {task_id}",
+        }
+    else:
+        raise ValueError(f"add_comment_to_visibility_recommendation is not supported for client type: {type(client)}")

src/orchestrator/tools_kb.py

@@ -0,0 +1,156 @@
+"""
+LLM-callable tools for client infrastructure knowledge base (KB) operations.
+
+These functions wrap the KBClient interface and provide LLM-friendly error
+handling and return values, reading from ``client_env/*`` on the filesystem.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from ..api.kb import KBClient
+from ..core.errors import IntegrationError
+
+
+def list_kb_clients(
+    client: KBClient = None,  # type: ignore
+) -> Dict[str, Any]:
+    """
+    List available client environments.
+
+    Tool schema:
+    - name: kb_list_clients
+    - description: List available client environments based on folders under client_env/*.
+    - parameters: none
+
+    Args:
+        client: The KB client.
+
+    Returns:
+        Dictionary containing list of clients.
+
+    Raises:
+        IntegrationError: If KB client is not provided.
+    """
+    if client is None:
+        raise IntegrationError("KB client not provided")
+
+    try:
+        clients = client.list_clients()
+        return {
+            "success": True,
+            "count": len(clients),
+            "clients": clients,
+        }
+    except Exception as e:
+        raise IntegrationError(f"Failed to list KB clients: {str(e)}") from e
+
+
+def get_client_infra(
+    client_name: str,
+    client: KBClient = None,  # type: ignore
+) -> Dict[str, Any]:
+    """
+    Get an aggregated view of a client's infrastructure.
+
+    Tool schema:
+    - name: kb_get_client_infra
+    - description: Load and summarize client infrastructure (subnets, servers, users, naming schemas, env rules) from client_env/*.
+    - parameters:
+      - client_name (str, required): Name of the client environment (e.g., "acme_corp_client" or "acme_corp").
+
+    Args:
+        client_name: Client identifier.
+        client: The KB client.
+
+    Returns:
+        Dictionary with normalized infrastructure data and a concise summary.
+
+    Raises:
+        IntegrationError: If KB client is not provided or loading fails.
+    """
+    if client is None:
+        raise IntegrationError("KB client not provided")
+
+    try:
+        infra = client.get_client_infra(client_name)
+
+        return {
+            "success": True,
+            "client_name": infra.client_name,
+            "summary": infra.summary,
+            "subnets": [
+                {
+                    "name": s.name,
+                    "cidr": s.cidr,
+                    "network_type": s.network_type,
+                    "access_method": s.access_method,
+                    "description": s.description,
+                    "tags": s.tags or [],
+                }
+                for s in infra.subnets
+            ],
+            "servers": [
+                {
+                    "hostname": srv.hostname,
+                    "ip_address": srv.ip_address,
+                    "role": srv.role,
+                    "environment": srv.environment,
+                    "os": srv.os,
+                    "description": srv.description,
+                    "criticality": srv.criticality,
+                    "tags": srv.tags or [],
+                }
+                for srv in infra.servers
+            ],
+            "users": [
+                {
+                    "username": u.username,
+                    "display_name": u.display_name,
+                    "account_type": u.account_type,
+                    "department": u.department,
+                    "privilege_level": u.privilege_level,
+                    "description": u.description,
+                    "tags": u.tags or [],
+                }
+                for u in infra.users
+            ],
+            "device_schemas": [
+                {
+                    "pattern": d.pattern,
+                    "pattern_style": d.pattern_style,
+                    "device_type": d.device_type,
+                    "example": d.example,
+                    "description": d.description,
+                    "tags": d.tags or [],
+                }
+                for d in infra.device_schemas
+            ],
+            "user_schemas": [
+                {
+                    "pattern": us.pattern,
+                    "pattern_style": us.pattern_style,
+                    "user_type": us.user_type,
+                    "example": us.example,
+                    "description": us.description,
+                    "tags": us.tags or [],
+                }
+                for us in infra.user_schemas
+            ],
+            "env_rules": {
+                "version": infra.env_rules.version if infra.env_rules else None,
+                "environment_types": infra.env_rules.environment_types if infra.env_rules else None,
+                "network_classification": infra.env_rules.network_classification if infra.env_rules else None,
+                "user_categories": infra.env_rules.user_categories if infra.env_rules else None,
+                "general_rules": infra.env_rules.general_rules if infra.env_rules else None,
+            }
+            if infra.env_rules
+            else None,
+        }
+    except Exception as e:
+        raise IntegrationError(
+            f"Failed to load infrastructure for client '{client_name}': {str(e)}"
+        ) from e
+
+