pygeai 0.1.51b3__py3-none-any.whl → 0.6.0b15__py3-none-any.whl

pygeai/migration/tools.py

@@ -1,13 +1,180 @@
+from typing import List, Dict, Optional
+from dataclasses import dataclass, field
+
+from pygeai import logger
 from pygeai.migration.strategies import MigrationStrategy
+from pygeai.core.utils.console import Console
 
 
 class MigrationTool:
+    """
+    Orchestrates migration operations using configurable strategies.
+    
+    This class provides a flexible way to execute migrations with support for:
+    - Batch migrations of multiple resources
+    - Dependency ordering
+    - Progress tracking
+    - Dry-run mode
+    - Rollback capabilities
+    """
 
     def __init__(self, strategy: MigrationStrategy):
-        self.strategy = strategy
+        self._strategy = strategy
 
     def set_strategy(self, strategy: MigrationStrategy):
-        self.strategy = strategy
+        """
+        Update the migration strategy.
+        
+        :param strategy: The new migration strategy to use
+        """
+        self._strategy = strategy
 
     def run_migration(self):
-        self.strategy.migrate()
+        """
+        Execute the configured migration strategy.
+        
+        :return: The result from the migration strategy (if any)
+        :raises ValueError: If migration fails
+        """
+        logger.info(f"Starting migration with strategy: {self._strategy.__class__.__name__}")
+        return self._strategy.migrate()
+
+
+@dataclass
+class MigrationPlan:
+    """
+    Defines a migration plan with multiple strategies and execution order.
+    
+    :param strategies: List of migration strategies to execute
+    :param dependencies: Map of strategy index to list of dependent strategy indices
+    :param dry_run: If True, validate without executing migrations
+    :param stop_on_error: If True, stop execution on first error
+    """
+    strategies: List[MigrationStrategy]
+    dependencies: Dict[int, List[int]] = field(default_factory=dict)
+    dry_run: bool = False
+    stop_on_error: bool = True
+
+
+class MigrationOrchestrator:
+    """
+    Advanced orchestration for complex migration scenarios.
+    
+    Handles batch migrations, dependency resolution, progress tracking,
+    and rollback on failure.
+    """
+
+    def __init__(self, plan: MigrationPlan):
+        self._plan = plan
+        self._completed: List[int] = []
+        self._failed: List[int] = []
+
+    def execute(self) -> Dict[str, any]:
+        """
+        Execute the migration plan respecting dependencies.
+        
+        :return: Summary of migration results
+        :raises ValueError: If migration fails and stop_on_error is True
+        """
+        logger.info(f"Executing migration plan with {len(self._plan.strategies)} strategies")
+        
+        if self._plan.dry_run:
+            return self._validate_plan()
+
+        execution_order = self._resolve_dependencies()
+        total_strategies = len(execution_order)
+        
+        Console.write_stdout("")
+        Console.write_stdout("=" * 60)
+        Console.write_stdout(f"Migration Progress: 0/{total_strategies} completed")
+        Console.write_stdout("=" * 60)
+        
+        for position, idx in enumerate(execution_order, 1):
+            strategy = self._plan.strategies[idx]
+            display_info = strategy.get_display_info()
+            
+            Console.write_stdout(f"\n[{position}/{total_strategies}] Migrating {display_info}...")
+            
+            try:
+                logger.info(f"Executing strategy {idx + 1}/{len(self._plan.strategies)}: {strategy.__class__.__name__}")
+                strategy.migrate()
+                self._completed.append(idx)
+                Console.write_stdout(f"✓ Successfully migrated {display_info}")
+            except Exception as e:
+                logger.error(f"Strategy {idx} failed: {e}")
+                self._failed.append(idx)
+                Console.write_stdout(f"✗ Failed to migrate {display_info}: {e}")
+                if self._plan.stop_on_error:
+                    raise ValueError(f"Migration failed at strategy {idx}: {e}") from e
+        
+        Console.write_stdout("")
+        Console.write_stdout("=" * 60)
+        Console.write_stdout(f"Migration Complete: {len(self._completed)}/{total_strategies} successful")
+        Console.write_stdout("=" * 60)
+
+        return self._generate_summary()
+
+    def _resolve_dependencies(self) -> List[int]:
+        """
+        Resolve strategy execution order based on dependencies.
+        
+        :return: Ordered list of strategy indices
+        :raises ValueError: If circular dependencies detected
+        """
+        visited = set()
+        order = []
+
+        def visit(idx: int, path: set):
+            if idx in path:
+                raise ValueError(f"Circular dependency detected at strategy {idx}")
+            if idx in visited:
+                return
+
+            path.add(idx)
+            for dep_idx in self._plan.dependencies.get(idx, []):
+                visit(dep_idx, path)
+            path.remove(idx)
+
+            visited.add(idx)
+            order.append(idx)
+
+        for idx in range(len(self._plan.strategies)):
+            visit(idx, set())
+
+        return order
+
+    def _validate_plan(self) -> Dict[str, any]:
+        """
+        Validate the migration plan without executing.
+        
+        :return: Validation results
+        """
+        logger.info("Validating migration plan (dry-run mode)")
+        try:
+            execution_order = self._resolve_dependencies()
+            return {
+                "valid": True,
+                "execution_order": execution_order,
+                "total_strategies": len(self._plan.strategies)
+            }
+        except Exception as e:
+            logger.error(f"Validation failed: {e}")
+            return {
+                "valid": False,
+                "error": str(e)
+            }
+
+    def _generate_summary(self) -> Dict[str, any]:
+        """
+        Generate a summary of migration results.
+        
+        :return: Summary dictionary with completed, failed, and pending migrations
+        """
+        return {
+            "total": len(self._plan.strategies),
+            "completed": len(self._completed),
+            "failed": len(self._failed),
+            "success_rate": len(self._completed) / len(self._plan.strategies) if self._plan.strategies else 0,
+            "completed_indices": self._completed,
+            "failed_indices": self._failed
+        }

pygeai/organization/clients.py

@@ -1,9 +1,14 @@
-import json
-from json import JSONDecodeError
 
+from pygeai import logger
+from pygeai.core.common.exceptions import InvalidAPIResponseException
 from pygeai.organization.endpoints import GET_ASSISTANT_LIST_V1, GET_PROJECT_LIST_V1, GET_PROJECT_V1, \
-    CREATE_PROJECT_V1, UPDATE_PROJECT_V1, DELETE_PROJECT_V1, GET_PROJECT_TOKENS_V1, GET_REQUEST_DATA_V1
+    CREATE_PROJECT_V1, UPDATE_PROJECT_V1, DELETE_PROJECT_V1, GET_PROJECT_TOKENS_V1, GET_REQUEST_DATA_V1, \
+    GET_MEMBERSHIPS_V2, GET_PROJECT_MEMBERSHIPS_V2, GET_PROJECT_ROLES_V2, GET_PROJECT_MEMBERS_V2, \
+    GET_ORGANIZATION_MEMBERS_V2, ADD_PROJECT_MEMBER_V2, CREATE_ORGANIZATION_V2, GET_ORGANIZATION_LIST_V2, \
+    DELETE_ORGANIZATION_V2
 from pygeai.core.base.clients import BaseClient
+from pygeai.core.utils.validators import validate_status_code
+from pygeai.core.utils.parsers import parse_json_response
 
 
 class OrganizationClient(BaseClient):
@@ -21,12 +26,8 @@ class OrganizationClient(BaseClient):
         :return: AssistantListResponse - The API response containing the list of assistants and the project.
         """
         response = self.api_service.get(endpoint=GET_ASSISTANT_LIST_V1, params={"detail": detail})
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
-
-        return result
+        validate_status_code(response)
+        return parse_json_response(response, "get assistant list")
 
     def get_project_list(
             self,
@@ -57,12 +58,8 @@ class OrganizationClient(BaseClient):
                     "detail": detail
                 }
             )
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
-
-        return result
+        validate_status_code(response)
+        return parse_json_response(response, "get project list")
 
     def get_project_data(
             self,
@@ -78,12 +75,8 @@ class OrganizationClient(BaseClient):
         response = self.api_service.get(
             endpoint=endpoint
         )
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
-
-        return result
+        validate_status_code(response)
+        return parse_json_response(response, "get project data for ID", project_id=project_id)
 
     def create_project(
             self,
@@ -120,12 +113,8 @@ class OrganizationClient(BaseClient):
                     "description": description
                 }
             )
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
-
-        return result
+        validate_status_code(response)
+        return parse_json_response(response, "create project with name", name=name)
 
     def update_project(
             self,
@@ -149,12 +138,8 @@ class OrganizationClient(BaseClient):
                 "description": description
             }
         )
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
-
-        return result
+        validate_status_code(response)
+        return parse_json_response(response, "update project with ID", project_id=project_id)
 
     def delete_project(
             self,
@@ -168,12 +153,8 @@ class OrganizationClient(BaseClient):
         """
         endpoint = DELETE_PROJECT_V1.format(id=project_id)
         response = self.api_service.delete(endpoint=endpoint)
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
-
-        return result
+        validate_status_code(response)
+        return parse_json_response(response, "delete project with ID", project_id=project_id)
 
     def get_project_tokens(
             self,
@@ -187,12 +168,8 @@ class OrganizationClient(BaseClient):
         """
         endpoint = GET_PROJECT_TOKENS_V1.format(id=project_id)
         response = self.api_service.get(endpoint=endpoint)
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
-
-        return result
+        validate_status_code(response)
+        return parse_json_response(response, "get tokens for project with ID", project_id=project_id)
 
     def export_request_data(
             self,
@@ -219,9 +196,227 @@ class OrganizationClient(BaseClient):
                 "count": count
             }
         )
-        try:
-            result = response.json()
-        except JSONDecodeError as e:
-            result = response.text
+        validate_status_code(response)
+        return parse_json_response(response, "export request data")
+
+    def get_memberships(
+            self,
+            email: str = None,
+            start_page: int = 1,
+            page_size: int = 20,
+            order_key: str = None,
+            order_direction: str = "desc",
+            role_types: str = None
+    ) -> dict:
+        """
+        Retrieves a list of Organizations and Projects a user belongs to with their Roles.
+
+        :param email: str - The email address of the user to search for (optional, case-insensitive).
+        :param start_page: int - The page number for pagination (default is 1).
+        :param page_size: int - The number of items per page (default is 20).
+        :param order_key: str - Field for sorting. Only 'organizationName' is supported (optional).
+        :param order_direction: str - Sort direction: 'asc' or 'desc' (default is 'desc').
+        :param role_types: str - Comma-separated list of role types: 'backend', 'frontend' (optional, case-insensitive).
+        :return: dict - The API response containing the list of organizations and projects with roles, in JSON format.
+        """
+        params = {
+            "startPage": start_page,
+            "pageSize": page_size,
+            "orderDirection": order_direction
+        }
+        if email:
+            params["email"] = email
+        if order_key:
+            params["orderKey"] = order_key
+        if role_types:
+            params["roleTypes"] = role_types
+
+        response = self.api_service.get(endpoint=GET_MEMBERSHIPS_V2, params=params)
+        validate_status_code(response)
+        return parse_json_response(response, "get memberships")
+
+    def get_project_memberships(
+            self,
+            email: str = None,
+            start_page: int = 1,
+            page_size: int = 20,
+            order_key: str = None,
+            order_direction: str = "desc",
+            role_types: str = None
+    ) -> dict:
+        """
+        Retrieves a list of Projects and Roles for a user within a specific Organization.
+
+        :param email: str - The email address of the user to search for (optional, case-insensitive).
+        :param start_page: int - The page number for pagination (default is 1).
+        :param page_size: int - The number of items per page (default is 20).
+        :param order_key: str - Field for sorting. Only 'projectName' is supported (optional).
+        :param order_direction: str - Sort direction: 'asc' or 'desc' (default is 'desc').
+        :param role_types: str - Comma-separated list of role types: 'backend', 'frontend' (optional, case-insensitive).
+        :return: dict - The API response containing the list of projects with roles, in JSON format.
+        """
+        params = {
+            "startPage": start_page,
+            "pageSize": page_size,
+            "orderDirection": order_direction
+        }
+        if email:
+            params["email"] = email
+        if order_key:
+            params["orderKey"] = order_key
+        if role_types:
+            params["roleTypes"] = role_types
+
+        response = self.api_service.get(endpoint=GET_PROJECT_MEMBERSHIPS_V2, params=params)
+        validate_status_code(response)
+        return parse_json_response(response, "get project memberships")
+
+    def get_project_roles(
+            self,
+            project_id: str
+    ) -> dict:
+        """
+        Retrieves all Roles supported by a specific Project.
+
+        :param project_id: str - The unique identifier (GUID) of the project (required).
+        :return: dict - The API response containing the list of roles for the project, in JSON format.
+        """
+        response = self.api_service.get(endpoint=GET_PROJECT_ROLES_V2, params={"projectId": project_id})
+        validate_status_code(response)
+        return parse_json_response(response, "get project roles for project", project_id=project_id)
+
+    def get_project_members(
+            self,
+            project_id: str
+    ) -> dict:
+        """
+        Retrieves all members and their Roles for a specific Project.
+
+        :param project_id: str - The unique identifier (GUID) of the project (required).
+        :return: dict - The API response containing the list of members with their roles, in JSON format.
+        """
+        response = self.api_service.get(endpoint=GET_PROJECT_MEMBERS_V2, params={"projectId": project_id})
+        validate_status_code(response)
+        return parse_json_response(response, "get project members for project", project_id=project_id)
+
+    def get_organization_members(
+            self,
+            organization_id: str
+    ) -> dict:
+        """
+        Retrieves all members and their Roles for a specific Organization.
+
+        :param organization_id: str - The unique identifier (GUID) of the organization (required).
+        :return: dict - The API response containing the list of members with their roles, in JSON format.
+        """
+        response = self.api_service.get(endpoint=GET_ORGANIZATION_MEMBERS_V2, params={"organizationId": organization_id})
+        validate_status_code(response)
+        return parse_json_response(response, "get organization members for organization", organization_id=organization_id)
+
+    def add_project_member(
+            self,
+            project_id: str,
+            user_email: str,
+            roles: list
+    ) -> dict:
+        """
+        Adds a user to a project by sending an invitation with the specified roles.
+
+        :param project_id: str - The unique identifier (GUID) of the project (required). Will be sent as header.
+        :param user_email: str - The email address of the user to invite (required).
+        :param roles: list - A list of role names or GUIDs to assign to the user (required).
+        :return: dict - The API response confirming the invitation was sent, in JSON format.
+        """
+        headers = {"project-id": project_id}
+        data = {
+            "userEmail": user_email,
+            "roles": roles
+        }
+        response = self.api_service.post(
+            endpoint=ADD_PROJECT_MEMBER_V2,
+            data=data,
+            headers=headers
+        )
+        validate_status_code(response)
+        return parse_json_response(response, "add project member", user_email=user_email)
+
+    def create_organization(
+            self,
+            name: str,
+            administrator_user_email: str
+    ) -> dict:
+        """
+        Creates a new organization with the provided details.
+
+        This endpoint requires an OAuth access token from the System Administrator role.
+
+        :param name: str - The name of the new organization (required).
+        :param administrator_user_email: str - The email address of the organization administrator (required).
+        :return: dict - The API response with details of the created organization in JSON format.
+        """
+        response = self.api_service.post(
+            endpoint=CREATE_ORGANIZATION_V2,
+            data={
+                "name": name,
+                "administratorUserEmail": administrator_user_email
+            }
+        )
+        validate_status_code(response)
+        return parse_json_response(response, "create organization with name", name=name)
+
+    def get_organization_list(
+            self,
+            start_page: int = None,
+            page_size: int = None,
+            order_key: str = None,
+            order_direction: str = "desc",
+            filter_key: str = None,
+            filter_value: str = None
+    ) -> dict:
+        """
+        Retrieves a list of organizations based on the specified search criteria.
 
-        return result
+        This endpoint requires an OAuth access token from the System Administrator role.
+
+        :param start_page: int - The page number for pagination (optional).
+        :param page_size: int - The number of items per page (optional).
+        :param order_key: str - Field for sorting. Only 'name' is supported (optional).
+        :param order_direction: str - Sort direction: 'asc' or 'desc' (default is 'desc').
+        :param filter_key: str - Field for filtering. Only 'name' is supported (optional).
+        :param filter_value: str - Value to filter by (optional).
+        :return: dict - The API response containing the list of organizations in JSON format.
+        """
+        params = {
+            "orderDirection": order_direction
+        }
+        if start_page is not None:
+            params["startPage"] = start_page
+        if page_size is not None:
+            params["pageSize"] = page_size
+        if order_key:
+            params["orderKey"] = order_key
+        if filter_key:
+            params["filterKey"] = filter_key
+        if filter_value:
+            params["filterValue"] = filter_value
+
+        response = self.api_service.get(endpoint=GET_ORGANIZATION_LIST_V2, params=params)
+        validate_status_code(response)
+        return parse_json_response(response, "get organization list")
+
+    def delete_organization(
+            self,
+            organization_id: str
+    ) -> dict:
+        """
+        Deletes an existing organization using its unique identifier.
+
+        This endpoint requires an OAuth access token from the System Administrator role.
+
+        :param organization_id: str - The unique identifier (GUID) of the organization to delete (required).
+        :return: dict - The API response confirming the deletion of the organization, in JSON format.
+        """
+        endpoint = DELETE_ORGANIZATION_V2.format(organizationId=organization_id)
+        response = self.api_service.delete(endpoint=endpoint)
+        validate_status_code(response)
+        return parse_json_response(response, "delete organization with ID", organization_id=organization_id)

pygeai/organization/endpoints.py

@@ -1,8 +1,17 @@
-GET_ASSISTANT_LIST_V1 = "v1/organization/assistants"                # GET – Gets the list of assistants
-GET_PROJECT_LIST_V1 = "v1/organization/projects"	                # GET - Gets the list of projects
-GET_PROJECT_V1 = "v1/organization/project/{id}"	                    # GET - Gets project details
-CREATE_PROJECT_V1 = "v1/organization/project"	                    # POST - Creates a project
-UPDATE_PROJECT_V1 = "v1/organization/project/{id}"	                # PUT - Updates a project
-DELETE_PROJECT_V1 = "v1/organization/project/{id}"	                # DELETE - Deletes a project
-GET_PROJECT_TOKENS_V1 = "v1/organization/project/{id}/tokens"	    # GET - Gets the list of Tokens for the project
-GET_REQUEST_DATA_V1 = "v1/organization/request/export"	            # GET - Exports request data
+GET_ASSISTANT_LIST_V1 = "v1/organization/assistants"                # GET - Gets the list of assistants
+GET_PROJECT_LIST_V1 = "v1/organization/projects"                        # GET - Gets the list of projects
+GET_PROJECT_V1 = "v1/organization/project/{id}"                     # GET - Gets project details
+CREATE_PROJECT_V1 = "v1/organization/project"                       # POST - Creates a project
+UPDATE_PROJECT_V1 = "v1/organization/project/{id}"                      # PUT - Updates a project
+DELETE_PROJECT_V1 = "v1/organization/project/{id}"                      # DELETE - Deletes a project
+GET_PROJECT_TOKENS_V1 = "v1/organization/project/{id}/tokens"       # GET - Gets the list of Tokens for the project
+GET_REQUEST_DATA_V1 = "v1/organization/request/export"              # GET - Exports request data
+GET_MEMBERSHIPS_V2 = "v2/accessControl/memberships"                # GET - Lists Organizations and Projects a user belongs to with their Roles
+GET_PROJECT_MEMBERSHIPS_V2 = "v2/accessControl/projects/memberships"   # GET - Lists Projects and Roles for a user within a specific Organization
+GET_PROJECT_ROLES_V2 = "v2/accessControl/projects/roles"           # GET - Lists all Roles supported by a specific Project
+GET_PROJECT_MEMBERS_V2 = "v2/accessControl/projects/members"       # GET - Lists all members and their Roles for a specific Project
+GET_ORGANIZATION_MEMBERS_V2 = "v2/accessControl/organizations/members"  # GET - Lists all members and their Roles for a specific Organization
+ADD_PROJECT_MEMBER_V2 = "v2/accessControl/projects/members"        # POST - Adds a member to a project by sending an invitation
+CREATE_ORGANIZATION_V2 = "v2/admin/organizations"                  # POST - Creates a new Organization
+GET_ORGANIZATION_LIST_V2 = "v2/admin/organizations"                # GET - Retrieves all the organizations available based on a given search criteria
+DELETE_ORGANIZATION_V2 = "v2/admin/organizations/{organizationId}"  # DELETE - Deletes the created Organization