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

pygeai/lab/processes/clients.py

@@ -1,20 +1,21 @@
-import json
-from json import JSONDecodeError
-from typing import Any, Union, List
+from typing import List
 
-from pygeai.core.base.clients import BaseClient
+from pygeai import logger
+from pygeai.core.common.exceptions import InvalidAPIResponseException
+from pygeai.core.utils.validators import validate_status_code
+from pygeai.core.utils.parsers import parse_json_response
 from pygeai.lab.processes.endpoints import CREATE_PROCESS_V2, UPDATE_PROCESS_V2, UPSERT_PROCESS_V2, GET_PROCESS_V2, \
     LIST_PROCESSES_V2, LIST_PROCESS_INSTANCES_V2, DELETE_PROCESS_V2, PUBLISH_PROCESS_REVISION_V2, CREATE_TASK_V2, \
     UPDATE_TASK_V2, UPSERT_TASK_V2, GET_TASK_V2, LIST_TASKS_V2, DELETE_TASK_V2, PUBLISH_TASK_REVISION_V2, \
     START_INSTANCE_V2, ABORT_INSTANCE_V2, GET_INSTANCE_V2, GET_INSTANCE_HISTORY_V2, GET_THREAD_INFORMATION_V2, \
     SEND_USER_SIGNAL_V2, CREATE_KB_V1, GET_KB_V1, LIST_KBS_V1, DELETE_KB_V1, LIST_JOBS_V1
+from pygeai.lab.clients import AILabClient
 
 
-class AgenticProcessClient(BaseClient):
+class AgenticProcessClient(AILabClient):
 
     def create_process(
             self,
-            project_id: str,
             key: str,
             name: str,
             description: str = None,
@@ -27,14 +28,13 @@ class AgenticProcessClient(BaseClient):
             sequence_flows: list = None,
             variables: list = None,
             automatic_publish: bool = False
-    ):
+    ) -> dict:
         """
         Creates a new process in the specified project.
 
-        :param project_id: str - Unique identifier of the project.
-        :param key: str - Unique key for the process.
+        :param key: str - Unique key for the process within the project.
         :param name: str - Name of the process.
-        :param description: str, optional - Description of the process.
+        :param description: str, optional - Description of the process purpose.
         :param kb: dict, optional - Knowledge base configuration.
         :param agentic_activities: list, optional - List of agentic activity definitions.
         :param artifact_signals: list, optional - List of artifact signal definitions.
@@ -42,9 +42,10 @@ class AgenticProcessClient(BaseClient):
         :param start_event: dict, optional - Start event definition.
         :param end_event: dict, optional - End event definition.
         :param sequence_flows: list, optional - List of sequence flow definitions.
-        :param variables: list, optional - Updated list of variables.
-        :param automatic_publish: bool - Whether to publish the process after creation. Defaults to False.
-        :return: dict or str - JSON response with the created process details if successful, otherwise raw text.
+        :param variables: list, optional - List of variables used in the process.
+        :param automatic_publish: bool, optional - Publish the process after creation (default: False).
+        :return: dict or str - Created process details or error message.
+        :raises InvalidAPIResponseException: If an error occurs during creation.
         """
         endpoint = CREATE_PROCESS_V2
         if automatic_publish:
@@ -52,7 +53,7 @@ class AgenticProcessClient(BaseClient):
 
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id,
+            "ProjectId": self.project_id,
             "Content-Type": "application/json",
             "Accept": "application/json"
         }
@@ -81,17 +82,15 @@ class AgenticProcessClient(BaseClient):
         if variables:
             data["processDefinition"]["variables"] = variables
 
+        logger.debug(f"Creating agentic process with data: {data}")
+
         response = self.api_service.post(endpoint=endpoint, headers=headers, data=data)
-        try:
-            result = response.json()
-        except JSONDecodeError:
-            result = response.text
+        validate_status_code(response)
+        return parse_json_response(response, f"create process for project {self.project_id}")
 
-        return result
 
     def update_process(
             self,
-            project_id: str,
             process_id: str = None,
             name: str = None,
             key: str = None,
@@ -106,13 +105,12 @@ class AgenticProcessClient(BaseClient):
             variables: list = None,
             automatic_publish: bool = False,
             upsert: bool = False
-    ):
+    ) -> dict:
         """
-        Updates an existing process in the specified project or upserts it if specified.
+        Updates an existing process or creates it if upsert is enabled.
 
-        :param project_id: str - Unique identifier of the project.
         :param process_id: str, optional - Unique identifier of the process to update.
-        :param name: str, optional - Name of the process to update (used if process_id is not provided).
+        :param name: str, optional - Name of the process to update or create.
         :param key: str, optional - Updated unique key for the process.
         :param description: str, optional - Updated description of the process.
         :param kb: dict, optional - Updated knowledge base configuration.
@@ -123,10 +121,11 @@ class AgenticProcessClient(BaseClient):
         :param end_event: dict, optional - Updated end event definition.
         :param sequence_flows: list, optional - Updated list of sequence flow definitions.
         :param variables: list, optional - Updated list of variables.
-        :param automatic_publish: bool - Whether to publish the process after updating. Defaults to False.
-        :param upsert: bool - Whether to insert the process if it does not exist. Defaults to False.
-        :return: dict or str - JSON response with the updated process details if successful, otherwise raw text.
+        :param automatic_publish: bool, optional - Publish the process after updating (default: False).
+        :param upsert: bool, optional - Create the process if it does not exist (default: False).
+        :return: dict or str - Updated or created process details or error message.
         :raises ValueError: If neither process_id nor name is provided.
+        :raises InvalidAPIResponseException: If an error occurs during the update.
         """
         if not (process_id or name):
             raise ValueError("Either process_id or name must be provided.")
@@ -140,7 +139,7 @@ class AgenticProcessClient(BaseClient):
 
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id,
+            "ProjectId": self.project_id,
             "Content-Type": "application/json",
             "Accept": "application/json"
         }
@@ -171,49 +170,50 @@ class AgenticProcessClient(BaseClient):
             data["processDefinition"]["variables"] = variables
 
         if kb is None and not upsert:
-            current_process = self.get_process(project_id=project_id, process_id=process_id, process_name=name)
+            current_process = self.get_process(process_id=process_id, process_name=name)
             if isinstance(current_process, dict) and "processDefinition" in current_process:
                 kb = current_process["processDefinition"].get("kb")
 
         if agentic_activities is None and not upsert:
-            current_process = self.get_process(project_id=project_id, process_id=process_id, process_name=name)
+            current_process = self.get_process(process_id=process_id, process_name=name)
             if isinstance(current_process, dict) and "processDefinition" in current_process:
                 agentic_activities = current_process["processDefinition"].get("agenticActivities")
         if agentic_activities is not None:
             data["processDefinition"]["agenticActivities"] = agentic_activities
 
+        if process_id:
+            logger.debug(f"Updating agentic process with ID {process_id} with data: {data}")
+        else:
+            logger.debug(f"Updating agentic process with name{name} with data: {data}")
+
         response = self.api_service.put(
             endpoint=endpoint,
             headers=headers,
             data=data
         )
-        try:
-            result = response.json()
-        except JSONDecodeError:
-            result = response.text
+        validate_status_code(response)
+        return parse_json_response(response, f"update process {process_id or name} in project {self.project_id}")
 
-        return result
 
     def get_process(
             self,
-            project_id: str,
             process_id: str = None,
             process_name: str = None,
             revision: str = "0",
             version: int = 0,
             allow_drafts: bool = True
-    ):
+    ) -> dict:
         """
-        Retrieves details of a specific process in the specified project, identified by either its ID or name.
-
-        :param project_id: str - Unique identifier of the project.
-        :param process_id: str, optional - Unique identifier of the process to retrieve. Defaults to None.
-        :param process_name: str, optional - Name of the process to retrieve. Defaults to None.
-        :param revision: str - Revision of the process to retrieve. Defaults to '0' (latest revision).
-        :param version: int - Version of the process to retrieve. Defaults to 0 (latest version).
-        :param allow_drafts: bool - Whether to include draft processes in the retrieval. Defaults to True.
-        :return: dict or str - JSON response containing the process details if successful, otherwise the raw response text.
+        Retrieves details of a specific process by its ID or name.
+
+        :param process_id: str, optional - Unique identifier of the process.
+        :param process_name: str, optional - Name of the process.
+        :param revision: str, optional - Revision of the process (default: '0').
+        :param version: int, optional - Version of the process (default: 0).
+        :param allow_drafts: bool, optional - Include draft processes (default: True).
+        :return: dict or str - Process details or error message.
         :raises ValueError: If neither process_id nor process_name is provided.
+        :raises InvalidAPIResponseException: If an error occurs during retrieval.
         """
         if not (process_id or process_name):
             raise ValueError("Either process_id or process_name must be provided.")
@@ -223,7 +223,7 @@ class AgenticProcessClient(BaseClient):
 
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id
+            "ProjectId": self.project_id
         }
         params = {
             "revision": revision,
@@ -231,44 +231,45 @@ class AgenticProcessClient(BaseClient):
             "allowDrafts": allow_drafts
         }
 
+        if process_id:
+            logger.debug(f"Retrieving agentic process detail with ID {process_id}")
+        else:
+            logger.debug(f"Retrieving agentic process detail with name '{process_name}'")
+
         response = self.api_service.get(
             endpoint=endpoint,
             headers=headers,
             params=params
         )
-        try:
-            result = response.json()
-        except JSONDecodeError:
-            result = response.text
+        validate_status_code(response)
+        return parse_json_response(response, f"retrieve process {process_id or process_name} for project {self.project_id}")
 
-        return result
 
     def list_processes(
             self,
-            project_id: str,
             id: str = None,
             name: str = None,
             status: str = None,
             start: str = "0",
             count: str = "100",
             allow_draft: bool = True
-    ):
+    ) -> dict:
         """
-        Retrieves a list of processes in the specified project, filtered by the provided criteria.
-
-        :param project_id: str - Unique identifier of the project.
-        :param id: str, optional - ID of the process to filter by. Defaults to None.
-        :param name: str, optional - Name of the process to filter by. Defaults to None.
-        :param status: str, optional - Status of the processes to filter by (e.g., 'active', 'inactive'). Defaults to None.
-        :param start: str - Starting index for pagination. Defaults to '0'.
-        :param count: str - Number of processes to retrieve. Defaults to '100'.
-        :param allow_draft: bool - Whether to include draft processes in the list. Defaults to True.
-        :return: dict or str - JSON response containing the list of processes if successful, otherwise the raw response text.
+        Retrieves a list of processes in the specified project.
+
+        :param id: str, optional - ID of the process to filter by.
+        :param name: str, optional - Name of the process to filter by.
+        :param status: str, optional - Status of the processes (e.g., 'active', 'inactive').
+        :param start: str, optional - Starting index for pagination (default: '0').
+        :param count: str, optional - Number of processes to retrieve (default: '100').
+        :param allow_draft: bool, optional - Include draft processes (default: True).
+        :return: dict or str - List of processes or error message.
+        :raises InvalidAPIResponseException: If an error occurs during retrieval.
         """
         endpoint = LIST_PROCESSES_V2
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id
+            "ProjectId": self.project_id
         }
         params = {
             "start": start,
@@ -282,36 +283,34 @@ class AgenticProcessClient(BaseClient):
         if status:
             params["status"] = status
 
+        logger.debug(f"Listing agentic processes for project with ID {self.project_id}")
+
         response = self.api_service.get(
             endpoint=endpoint,
             headers=headers,
             params=params
         )
-        try:
-            result = response.json()
-        except JSONDecodeError:
-            result = response.text
+        validate_status_code(response)
+        return parse_json_response(response, f"list processes for project {self.project_id}")
 
-        return result
 
     def list_process_instances(
             self,
-            project_id: str,
             process_id: str,
             is_active: bool = True,
             start: str = "0",
             count: str = "10"
-    ):
+    ) -> dict:
         """
-        Retrieves a list of process instances for a specific process in the specified project.
-
-        :param project_id: str - Unique identifier of the project.
-        :param process_id: str - Unique identifier of the process to list instances for.
-        :param is_active: bool - Whether to list only active process instances. Defaults to True.
-        :param start: str - Starting index for pagination. Defaults to '0'.
-        :param count: str - Number of process instances to retrieve. Defaults to '10'.
-        :return: dict or str - JSON response containing the list of process instances if successful, otherwise the raw response text.
+        Retrieves a list of process instances for a specific process.
+
+        :param process_id: str - Unique identifier of the process.
+        :param is_active: bool, optional - List only active instances (default: True).
+        :param start: str, optional - Starting index for pagination (default: '0').
+        :param count: str, optional - Number of instances to retrieve (default: '10').
+        :return: dict or str - List of process instances or error message.
         :raises ValueError: If process_id is not provided.
+        :raises InvalidAPIResponseException: If an error occurs during retrieval.
         """
         if not process_id:
             raise ValueError("Process ID must be provided.")
@@ -319,7 +318,7 @@ class AgenticProcessClient(BaseClient):
         endpoint = LIST_PROCESS_INSTANCES_V2.format(processId=process_id)
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id
+            "ProjectId": self.project_id
         }
         params = {
             "isActive": is_active,
@@ -327,32 +326,30 @@ class AgenticProcessClient(BaseClient):
             "count": count
         }
 
+        logger.debug(f"Listing instances for agentic process with ID {process_id}")
+
         response = self.api_service.get(
             endpoint=endpoint,
             headers=headers,
             params=params
         )
-        try:
-            result = response.json()
-        except JSONDecodeError:
-            result = response.text
+        validate_status_code(response)
+        return parse_json_response(response, f"list process instances for process {process_id} in project {self.project_id}")
 
-        return result
 
     def delete_process(
             self,
-            project_id: str,
             process_id: str = None,
             process_name: str = None
-    ):
+    ) -> dict:
         """
-        Deletes a specific process in the specified project, identified by either its ID or name.
+        Deletes a specific process by its ID or name.
 
-        :param project_id: str - Unique identifier of the project.
-        :param process_id: str, optional - Unique identifier of the process to delete. Defaults to None.
-        :param process_name: str, optional - Name of the process to delete. Defaults to None.
-        :return: dict or str - JSON response confirming the deletion if successful, otherwise the raw response text.
+        :param process_id: str, optional - Unique identifier of the process.
+        :param process_name: str, optional - Name of the process.
+        :return: dict or str - Confirmation of deletion or error message.
         :raises ValueError: If neither process_id nor process_name is provided.
+        :raises InvalidAPIResponseException: If an error occurs during deletion.
         """
         if not (process_id or process_name):
             raise ValueError("Either process_id or process_name must be provided.")
@@ -362,36 +359,37 @@ class AgenticProcessClient(BaseClient):
 
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id
+            "ProjectId": self.project_id
         }
 
+        logger.debug(f"Deleting agentic process with ID {process_id}")
+
         response = self.api_service.delete(
             endpoint=endpoint,
             headers=headers
         )
-        try:
-            result = response.json()
-        except JSONDecodeError:
-            result = response.text
 
-        return result
+        if response.status_code != 204:
+            logger.error(f"Unable to delete process {process_id or process_name} from project {self.project_id}: JSON parsing error (status {response.status_code}). Response: {response.text}")
+            raise InvalidAPIResponseException(f"Unable to delete process {process_id or process_name} from project {self.project_id}: {response.text}")
+        else:
+            return {}
 
     def publish_process_revision(
             self,
-            project_id: str,
             process_id: str = None,
             process_name: str = None,
             revision: str = None
-    ):
+    ) -> dict:
         """
-        Publishes a specific revision of a process in the specified project.
+        Publishes a specific revision of a process.
 
-        :param project_id: str - Unique identifier of the project.
-        :param process_id: str, optional - Unique identifier of the process to publish. Defaults to None.
-        :param process_name: str, optional - Name of the process to publish. Defaults to None.
-        :param revision: str - Revision of the process to publish.
-        :return: dict or str - JSON response containing the result of the publish operation if successful, otherwise the raw response text.
+        :param process_id: str, optional - Unique identifier of the process.
+        :param process_name: str, optional - Name of the process.
+        :param revision: str, optional - Revision of the process to publish.
+        :return: dict or str - Result of the publish operation or error message.
         :raises ValueError: If neither process_id nor process_name is provided, or if revision is not specified.
+        :raises InvalidAPIResponseException: If an error occurs during publishing.
         """
         if not (process_id or process_name):
             raise ValueError("Either process_id or process_name must be provided.")
@@ -403,9 +401,14 @@ class AgenticProcessClient(BaseClient):
 
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id
+            "ProjectId": self.project_id
         }
 
+        if process_id:
+            logger.debug(f"Publishing revision {revision} for agentic process with ID {process_id}")
+        else:
+            logger.debug(f"Publishing revision {revision} for agentic process with name '{process_name}'")
+
         response = self.api_service.post(
             endpoint=endpoint,
             headers=headers,
@@ -413,16 +416,12 @@ class AgenticProcessClient(BaseClient):
                 "revision": revision
             }
         )
-        try:
-            result = response.json()
-        except JSONDecodeError:
-            result = response.text
+        validate_status_code(response)
+        return parse_json_response(response, f"publish revision {revision} for process {process_id or process_name} in project {self.project_id}")
 
-        return result
 
     def create_task(
             self,
-            project_id: str,
             name: str,
             description: str = None,
             title_template: str = None,
@@ -430,19 +429,19 @@ class AgenticProcessClient(BaseClient):
             prompt_data: dict = None,
             artifact_types: List[dict] = None,
             automatic_publish: bool = False
-    ):
+    ) -> dict:
         """
         Creates a new task in the specified project.
 
-        :param project_id: str - Unique identifier of the project where the task will be created.
-        :param name: str - Required name of the task, must be unique within the project and exclude ':' or '/'.
-        :param description: str, optional - Description of what the task does, for user understanding (not used by agents).
-        :param title_template: str, optional - Template for naming task instances (e.g., 'specs for {{issue}}'), with variables replaced during execution.
-        :param id: str, optional - Custom identifier for the task; if provided, overrides system-assigned ID in insert mode.
-        :param prompt_data: dict, optional - Prompt configuration (same as AgentData prompt), combined with agent prompt during execution.
-        :param artifact_types: List[dict], optional - List of artifact types associated with the task, each with 'name', 'description', 'isRequired', 'usageType', and 'artifactVariableKey'.
-        :param automatic_publish: bool - Whether to publish the task after creation. Defaults to False.
-        :return: dict or str - JSON response with the created task details if successful, otherwise raw text.
+        :param name: str - Name of the task, unique within the project, excluding ':' or '/'.
+        :param description: str, optional - Description of the task purpose.
+        :param title_template: str, optional - Template for task instance names (e.g., 'specs for {{issue}}').
+        :param id: str, optional - Custom identifier for the task.
+        :param prompt_data: dict, optional - Prompt configuration for task execution.
+        :param artifact_types: List[dict], optional - List of artifact types with 'name', 'description', 'isRequired', 'usageType', and 'artifactVariableKey'.
+        :param automatic_publish: bool, optional - Publish the task after creation (default: False).
+        :return: dict or str - Created task details or error message.
+        :raises InvalidAPIResponseException: If an error occurs during creation.
         """
         endpoint = CREATE_TASK_V2
         if automatic_publish:
@@ -450,7 +449,7 @@ class AgenticProcessClient(BaseClient):
 
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id,
+            "ProjectId": self.project_id,
             "Content-Type": "application/json",
             "Accept": "application/json"
         }
@@ -470,26 +469,24 @@ class AgenticProcessClient(BaseClient):
         if artifact_types:
             data["taskDefinition"]["artifactTypes"] = artifact_types
 
-        response = self.api_service.post(endpoint=endpoint, headers=headers, data=data)
-        try:
-            return response.json()
-        except JSONDecodeError:
-            return response.text
+        logger.debug(f"Creating task with data: {data}")
 
+        response = self.api_service.post(endpoint=endpoint, headers=headers, data=data)
+        validate_status_code(response)
+        return parse_json_response(response, f"create task for project {self.project_id}")
     def get_task(
             self,
-            project_id: str,
             task_id: str,
             task_name: str = None
-    ):
+    ) -> dict:
         """
-        Retrieves details of a specific task in the specified project.
+        Retrieves details of a specific task by its ID or name.
 
-        :param project_id: str - Unique identifier of the project.
-        :param task_id: str, optional - Unique identifier of the task to retrieve.
-        :param task_name: str, optional - Name of the task to retrieve.
-        :return: dict or str - JSON response containing the task details if successful, otherwise raw text.
+        :param task_id: str, optional - Unique identifier of the task.
+        :param task_name: str, optional - Name of the task.
+        :return: dict or str - Task details or error message.
         :raises ValueError: If neither task_id nor task_name is provided.
+        :raises InvalidAPIResponseException: If an error occurs during retrieval.
         """
         if not (task_id or task_name):
             raise ValueError("Either task_id or task_name must be provided.")
@@ -498,37 +495,38 @@ class AgenticProcessClient(BaseClient):
         endpoint = GET_TASK_V2.format(taskId=identifier)
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id
+            "ProjectId": self.project_id
         }
 
-        response = self.api_service.get(endpoint=endpoint, headers=headers)
-        try:
-            return response.json()
-        except JSONDecodeError:
-            return response.text
+        if task_id:
+            logger.debug(f"Retrieving task detail with ID {task_id}")
+        else:
+            logger.debug(f"Retrieving task detail with name {task_name}")
 
+        response = self.api_service.get(endpoint=endpoint, headers=headers)
+        validate_status_code(response)
+        return parse_json_response(response, f"retrieve task {task_id or task_name} for project {self.project_id}")
     def list_tasks(
             self,
-            project_id: str,
             id: str = None,
             start: str = "0",
             count: str = "100",
             allow_drafts: bool = True
-    ):
+    ) -> dict:
         """
         Retrieves a list of tasks in the specified project.
 
-        :param project_id: str - Unique identifier of the project.
         :param id: str, optional - ID of the task to filter by.
-        :param start: str - Starting index for pagination. Defaults to '0'.
-        :param count: str - Number of tasks to retrieve. Defaults to '100'.
-        :param allow_drafts: bool - Whether to include draft tasks in the list. Defaults to True.
-        :return: dict or str - JSON response containing the list of tasks if successful, otherwise raw text.
+        :param start: str, optional - Starting index for pagination (default: '0').
+        :param count: str, optional - Number of tasks to retrieve (default: '100').
+        :param allow_drafts: bool, optional - Include draft tasks (default: True).
+        :return: dict or str - List of tasks or error message.
+        :raises InvalidAPIResponseException: If an error occurs during retrieval.
         """
         endpoint = LIST_TASKS_V2
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id
+            "ProjectId": self.project_id
         }
         params = {
             "start": start,
@@ -538,15 +536,13 @@ class AgenticProcessClient(BaseClient):
         if id:
             params["id"] = id
 
-        response = self.api_service.get(endpoint=endpoint, headers=headers, params=params)
-        try:
-            return response.json()
-        except JSONDecodeError:
-            return response.text
+        logger.debug(f"Listing tasks for project with ID {self.project_id}")
 
+        response = self.api_service.get(endpoint=endpoint, headers=headers, params=params)
+        validate_status_code(response)
+        return parse_json_response(response, f"list tasks for project {self.project_id}")
     def update_task(
             self,
-            project_id: str,
             task_id: str,
             name: str = None,
             description: str = None,
@@ -556,22 +552,22 @@ class AgenticProcessClient(BaseClient):
             artifact_types: List[dict] = None,
             automatic_publish: bool = False,
             upsert: bool = False
-    ):
+    ) -> dict:
         """
-        Updates an existing task in the specified project or upserts it if specified.
+        Updates an existing task or creates it if upsert is enabled.
 
-        :param project_id: str - Unique identifier of the project where the task resides.
         :param task_id: str - Unique identifier of the task to update.
-        :param name: str, optional - Updated name of the task, must be unique within the project and exclude ':' or '/' if provided.
-        :param description: str, optional - Updated description of what the task does, for user understanding (not used by agents).
-        :param title_template: str, optional - Updated template for naming task instances (e.g., 'specs for {{issue}}'), with variables replaced during execution.
-        :param id: str, optional - Custom identifier for the task; only used in upsert mode to set the ID if creating a new task.
-        :param prompt_data: dict, optional - Updated prompt configuration (same as AgentData prompt), combined with agent prompt during execution.
-        :param artifact_types: List[dict], optional - Updated list of artifact types associated with the task, each with 'name', 'description', 'isRequired', 'usageType', and 'artifactVariableKey'.
-        :param automatic_publish: bool - Whether to publish the task after updating. Defaults to False.
-        :param upsert: bool - Whether to insert the task if it does not exist. Defaults to False.
-        :return: dict or str - JSON response with the updated task details if successful, otherwise raw text.
+        :param name: str, optional - Updated name of the task, unique within the project, excluding ':' or '/'.
+        :param description: str, optional - Updated description of the task purpose.
+        :param title_template: str, optional - Updated template for task instance names (e.g., 'specs for {{issue}}').
+        :param id: str, optional - Custom identifier for the task (used in upsert mode).
+        :param prompt_data: dict, optional - Updated prompt configuration for task execution.
+        :param artifact_types: List[dict], optional - Updated list of artifact types with 'name', 'description', 'isRequired', 'usageType', and 'artifactVariableKey'.
+        :param automatic_publish: bool, optional - Publish the task after updating (default: False).
+        :param upsert: bool, optional - Create the task if it does not exist (default: False).
+        :return: dict or str - Updated or created task details or error message.
         :raises ValueError: If task_id is not provided.
+        :raises InvalidAPIResponseException: If an error occurs during the update.
         """
         if not task_id:
             raise ValueError("Task ID must be provided.")
@@ -584,7 +580,7 @@ class AgenticProcessClient(BaseClient):
 
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id,
+            "ProjectId": self.project_id,
             "Content-Type": "application/json",
             "Accept": "application/json"
         }
@@ -604,26 +600,24 @@ class AgenticProcessClient(BaseClient):
         if artifact_types is not None:
             data["taskDefinition"]["artifactTypes"] = artifact_types
 
-        response = self.api_service.put(endpoint=endpoint, headers=headers, data=data)
-        try:
-            return response.json()
-        except JSONDecodeError:
-            return response.text
+        logger.debug(f"Updating task with ID {task_id} with data: {data}")
 
+        response = self.api_service.put(endpoint=endpoint, headers=headers, data=data)
+        validate_status_code(response)
+        return parse_json_response(response, f"update task {task_id} in project {self.project_id}")
     def delete_task(
             self,
-            project_id: str,
             task_id: str,
             task_name: str = None
-    ):
+    ) -> dict:
         """
-        Deletes a specific task in the specified project.
+        Deletes a specific task by its ID or name.
 
-        :param project_id: str - Unique identifier of the project.
-        :param task_id: str, optional - Unique identifier of the task to delete.
-        :param task_name: str, optional - Name of the task to delete.
-        :return: dict or str - JSON response confirming deletion if successful, otherwise raw text.
+        :param task_id: str, optional - Unique identifier of the task.
+        :param task_name: str, optional - Name of the task.
+        :return: dict or str - Confirmation of deletion or error message.
         :raises ValueError: If neither task_id nor task_name is provided.
+        :raises InvalidAPIResponseException: If an error occurs during deletion.
         """
         if not (task_id or task_name):
             raise ValueError("Either task_id or task_name must be provided.")
@@ -632,31 +626,37 @@ class AgenticProcessClient(BaseClient):
         endpoint = DELETE_TASK_V2.format(taskId=identifier)
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id
+            "ProjectId": self.project_id
         }
 
+        if task_id:
+            logger.debug(f"Deleting task with ID {task_id}")
+        else:
+            logger.debug(f"Deleting task with name {task_name}")
+
         response = self.api_service.delete(endpoint=endpoint, headers=headers)
-        try:
-            return response.json()
-        except JSONDecodeError:
-            return response.text
+
+        if response.status_code != 204:
+            logger.error(f"Unable to delete task {task_id or task_name} from project {self.project_id}: JSON parsing error (status {response.status_code}). Response: {response.text}")
+            raise InvalidAPIResponseException(f"Unable to delete task {task_id or task_name} from project {self.project_id}: {response.text}")
+        else:
+            return {}
 
     def publish_task_revision(
             self,
-            project_id: str,
             task_id: str,
             task_name: str = None,
             revision: str = None
-    ):
+    ) -> dict:
         """
-        Publishes a specific revision of a task in the specified project.
+        Publishes a specific revision of a task.
 
-        :param project_id: str - Unique identifier of the project.
-        :param task_id: str, optional - Unique identifier of the task to publish.
-        :param task_name: str, optional - Name of the task to publish.
-        :param revision: str - Revision of the task to publish.
-        :return: dict or str - JSON response containing the result of the publish operation if successful, otherwise raw text.
+        :param task_id: str, optional - Unique identifier of the task.
+        :param task_name: str, optional - Name of the task.
+        :param revision: str, optional - Revision of the task to publish.
+        :return: dict or str - Result of the publish operation or error message.
         :raises ValueError: If neither task_id nor task_name is provided, or if revision is not specified.
+        :raises InvalidAPIResponseException: If an error occurs during publishing.
         """
         if not (task_id or task_name):
             raise ValueError("Either task_id or task_name must be provided.")
@@ -667,7 +667,7 @@ class AgenticProcessClient(BaseClient):
         endpoint = PUBLISH_TASK_REVISION_V2.format(taskId=identifier)
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id,
+            "ProjectId": self.project_id,
             "Content-Type": "application/json",
             "Accept": "application/json"
         }
@@ -675,32 +675,33 @@ class AgenticProcessClient(BaseClient):
             "revision": revision
         }
 
-        response = self.api_service.post(endpoint=endpoint, headers=headers, data=data)
-        try:
-            return response.json()
-        except JSONDecodeError:
-            return response.text
+        if task_id:
+            logger.debug(f"Publishing revision {revision} for task with ID {task_id}")
+        else:
+            logger.debug(f"Publishing revision {revision} for task with name {task_name}")
 
+        response = self.api_service.post(endpoint=endpoint, headers=headers, data=data)
+        validate_status_code(response)
+        return parse_json_response(response, f"publish revision {revision} for task {task_id or task_name} in project {self.project_id}")
     def start_instance(
             self,
-            project_id: str,
             process_name: str,
             subject: str = None,
             variables: list = None
-    ):
+    ) -> dict:
         """
-        Starts a new process instance in the specified project.
+        Starts a new process instance.
 
-        :param project_id: str - Unique identifier of the project.
-        :param process_name: str - Name of the process to start an instance for.
+        :param process_name: str - Name of the process to start.
         :param subject: str, optional - Subject of the process instance.
-        :param variables: list, optional - List of variables for the instance (e.g., [{"key": "location", "value": "Paris"}]).
-        :return: dict or str - JSON response with the started instance details if successful, otherwise raw text.
+        :param variables: list, optional - List of variables (e.g., [{"key": "location", "value": "Paris"}]).
+        :return: dict or str - Started instance details or error message.
+        :raises InvalidAPIResponseException: If an error occurs during instance creation.
         """
         endpoint = START_INSTANCE_V2
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id,
+            "ProjectId": self.project_id,
             "Content-Type": "application/json",
             "Accept": "application/json"
         }
@@ -714,24 +715,22 @@ class AgenticProcessClient(BaseClient):
         if variables:
             data["instanceDefinition"]["variables"] = variables
 
-        response = self.api_service.post(endpoint=endpoint, headers=headers, data=data)
-        try:
-            return response.json()
-        except JSONDecodeError:
-            return response.text
+        logger.info(f"Starting instance for process with name '{process_name}'")
 
+        response = self.api_service.post(endpoint=endpoint, headers=headers, data=data)
+        validate_status_code(response)
+        return parse_json_response(response, f"start instance for process {process_name} in project {self.project_id}")
     def abort_instance(
             self,
-            project_id: str,
             instance_id: str
-    ):
+    ) -> dict:
         """
-        Aborts a specific process instance in the specified project.
+        Aborts a specific process instance.
 
-        :param project_id: str - Unique identifier of the project.
         :param instance_id: str - Unique identifier of the instance to abort.
-        :return: dict or str - JSON response confirming the abort operation if successful, otherwise raw text.
+        :return: dict or str - Confirmation of abort operation or error message.
         :raises ValueError: If instance_id is not provided.
+        :raises InvalidAPIResponseException: If an error occurs during the abort.
         """
         if not instance_id:
             raise ValueError("Instance ID must be provided.")
@@ -739,29 +738,27 @@ class AgenticProcessClient(BaseClient):
         endpoint = ABORT_INSTANCE_V2.format(instanceId=instance_id)
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id,
+            "ProjectId": self.project_id,
             "Content-Type": "application/json",
             "Accept": "application/json"
         }
 
-        response = self.api_service.post(endpoint=endpoint, headers=headers, data={})
-        try:
-            return response.json()
-        except JSONDecodeError:
-            return response.text
+        logger.info(f"Aborting instance with ID '{instance_id}'")
 
+        response = self.api_service.post(endpoint=endpoint, headers=headers, data={})
+        validate_status_code(response)
+        return parse_json_response(response, f"abort instance {instance_id} in project {self.project_id}")
     def get_instance(
             self,
-            project_id: str,
             instance_id: str
-    ):
+    ) -> dict:
         """
-        Retrieves details of a specific process instance in the specified project.
+        Retrieves details of a specific process instance.
 
-        :param project_id: str - Unique identifier of the project.
-        :param instance_id: str - Unique identifier of the instance to retrieve.
-        :return: dict or str - JSON response containing the instance details if successful, otherwise raw text.
+        :param instance_id: str - Unique identifier of the instance.
+        :return: dict or str - Instance details or error message.
         :raises ValueError: If instance_id is not provided.
+        :raises InvalidAPIResponseException: If an error occurs during retrieval.
         """
         if not instance_id:
             raise ValueError("Instance ID must be provided.")
@@ -769,27 +766,25 @@ class AgenticProcessClient(BaseClient):
         endpoint = GET_INSTANCE_V2.format(instanceId=instance_id)
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id
+            "ProjectId": self.project_id
         }
 
-        response = self.api_service.get(endpoint=endpoint, headers=headers)
-        try:
-            return response.json()
-        except JSONDecodeError:
-            return response.text
+        logger.info(f"Retrieving instance detail with ID '{instance_id}'")
 
+        response = self.api_service.get(endpoint=endpoint, headers=headers)
+        validate_status_code(response)
+        return parse_json_response(response, f"retrieve instance {instance_id} for project {self.project_id}")
     def get_instance_history(
             self,
-            project_id: str,
             instance_id: str
-    ):
+    ) -> dict:
         """
-        Retrieves the history (trace) of a specific process instance in the specified project.
+        Retrieves the history of a specific process instance.
 
-        :param project_id: str - Unique identifier of the project.
-        :param instance_id: str - Unique identifier of the instance to retrieve history for.
-        :return: dict or str - JSON response containing the instance history if successful, otherwise raw text.
+        :param instance_id: str - Unique identifier of the instance.
+        :return: dict or str - Instance history or error message.
         :raises ValueError: If instance_id is not provided.
+        :raises InvalidAPIResponseException: If an error occurs during retrieval.
         """
         if not instance_id:
             raise ValueError("Instance ID must be provided.")
@@ -797,27 +792,25 @@ class AgenticProcessClient(BaseClient):
         endpoint = GET_INSTANCE_HISTORY_V2.format(instanceId=instance_id)
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id
+            "ProjectId": self.project_id
         }
 
-        response = self.api_service.get(endpoint=endpoint, headers=headers)
-        try:
-            return response.json()
-        except JSONDecodeError:
-            return response.text
+        logger.info(f"Retrieving instance history with ID '{instance_id}'")
 
+        response = self.api_service.get(endpoint=endpoint, headers=headers)
+        validate_status_code(response)
+        return parse_json_response(response, f"retrieve history for instance {instance_id} in project {self.project_id}")
     def get_thread_information(
             self,
-            project_id: str,
             thread_id: str
-    ):
+    ) -> dict:
         """
-        Retrieves information about a specific thread in the specified project.
+        Retrieves information about a specific thread.
 
-        :param project_id: str - Unique identifier of the project.
-        :param thread_id: str - Unique identifier of the thread to retrieve information for.
-        :return: dict or str - JSON response containing the thread information if successful, otherwise raw text.
+        :param thread_id: str - Unique identifier of the thread.
+        :return: dict or str - Thread information or error message.
         :raises ValueError: If thread_id is not provided.
+        :raises InvalidAPIResponseException: If an error occurs during retrieval.
         """
         if not thread_id:
             raise ValueError("Thread ID must be provided.")
@@ -825,29 +818,27 @@ class AgenticProcessClient(BaseClient):
         endpoint = GET_THREAD_INFORMATION_V2.format(threadId=thread_id)
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id
+            "ProjectId": self.project_id
         }
 
-        response = self.api_service.get(endpoint=endpoint, headers=headers)
-        try:
-            return response.json()
-        except JSONDecodeError:
-            return response.text
+        logger.debug(f"Retrieving information about thread with ID {thread_id}")
 
+        response = self.api_service.get(endpoint=endpoint, headers=headers)
+        validate_status_code(response)
+        return parse_json_response(response, f"retrieve thread information for thread {thread_id} in project {self.project_id}")
     def send_user_signal(
             self,
-            project_id: str,
             instance_id: str,
             signal_name: str
-    ):
+    ) -> dict:
         """
-        Sends a user signal to a specific process instance in the specified project.
+        Sends a user signal to a specific process instance.
 
-        :param project_id: str - Unique identifier of the project.
-        :param instance_id: str - Unique identifier of the instance to send the signal to.
-        :param signal_name: str - Name of the user signal to send (e.g., 'approval').
-        :return: dict or str - JSON response confirming the signal operation if successful, otherwise raw text.
+        :param instance_id: str - Unique identifier of the instance.
+        :param signal_name: str - Name of the user signal (e.g., 'approval').
+        :return: dict or str - Confirmation of signal operation or error message.
         :raises ValueError: If instance_id or signal_name is not provided.
+        :raises InvalidAPIResponseException: If an error occurs during signal sending.
         """
         if not instance_id:
             raise ValueError("Instance ID must be provided.")
@@ -857,7 +848,7 @@ class AgenticProcessClient(BaseClient):
         endpoint = SEND_USER_SIGNAL_V2.format(instanceId=instance_id)
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id,
+            "ProjectId": self.project_id,
             "Content-Type": "application/json",
             "Accept": "application/json"
         }
@@ -865,32 +856,30 @@ class AgenticProcessClient(BaseClient):
             "name": signal_name
         }
 
-        response = self.api_service.post(endpoint=endpoint, headers=headers, data=data)
-        try:
-            return response.json()
-        except JSONDecodeError:
-            return response.text
+        logger.debug(f"Sending user signal to process instance with ID {instance_id} with data: {data}")
 
+        response = self.api_service.post(endpoint=endpoint, headers=headers, data=data)
+        validate_status_code(response)
+        return parse_json_response(response, f"send user signal {signal_name} to instance {instance_id} in project {self.project_id}")
     def create_kb(
             self,
-            project_id: str,
             name: str,
             artifacts: List[str] = None,
             metadata: List[str] = None
-    ):
+    ) -> dict:
         """
         Creates a new knowledge base (KB) in the specified project.
 
-        :param project_id: str - Unique identifier of the project.
         :param name: str - Name of the knowledge base.
         :param artifacts: List[str], optional - List of artifact names associated with the KB.
         :param metadata: List[str], optional - List of metadata fields for the KB.
-        :return: dict or str - JSON response with the created KB details if successful, otherwise raw text.
+        :return: dict or str - Created KB details or error message.
+        :raises InvalidAPIResponseException: If an error occurs during creation.
         """
         endpoint = CREATE_KB_V1
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id,
+            "ProjectId": self.project_id,
             "Content-Type": "application/json",
             "Accept": "application/json"
         }
@@ -904,30 +893,28 @@ class AgenticProcessClient(BaseClient):
         if metadata:
             data["KBDefinition"]["metadata"] = metadata
 
+        logger.debug(f"Creating KB with data: {data}")
+
         response = self.api_service.post(
             endpoint=endpoint,
             headers=headers,
             data=data
         )
-        try:
-            return response.json()
-        except JSONDecodeError:
-            return response.text
-
+        validate_status_code(response)
+        return parse_json_response(response, f"create knowledge base for project {self.project_id}")
     def get_kb(
             self,
-            project_id: str,
             kb_id: str = None,
             kb_name: str = None
-    ):
+    ) -> dict:
         """
-        Retrieves details of a specific knowledge base (KB) in the specified project.
+        Retrieves details of a specific knowledge base (KB) by its ID or name.
 
-        :param project_id: str - Unique identifier of the project.
-        :param kb_id: str, optional - Unique identifier of the KB to retrieve.
-        :param kb_name: str, optional - Name of the KB to retrieve.
-        :return: dict or str - JSON response containing the KB details if successful, otherwise raw text.
+        :param kb_id: str, optional - Unique identifier of the KB.
+        :param kb_name: str, optional - Name of the KB.
+        :return: dict or str - KB details or error message.
         :raises ValueError: If neither kb_id nor kb_name is provided.
+        :raises InvalidAPIResponseException: If an error occurs during retrieval.
         """
         if not (kb_id or kb_name):
             raise ValueError("Either kb_id or kb_name must be provided.")
@@ -936,35 +923,37 @@ class AgenticProcessClient(BaseClient):
         endpoint = GET_KB_V1.format(kbId=identifier)
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id
+            "ProjectId": self.project_id
         }
 
-        response = self.api_service.get(endpoint=endpoint, headers=headers)
-        try:
-            return response.json()
-        except JSONDecodeError:
-            return response.text
+        if kb_id:
+            logger.debug(f"Retrieving KB detail with ID {kb_id}")
+        else:
+            logger.debug(f"Retrieving KB detail with name {kb_name}")
 
+        response = self.api_service.get(endpoint=endpoint, headers=headers)
+        kb_identifier = kb_id or kb_name
+        validate_status_code(response)
+        return parse_json_response(response, f"retrieve knowledge base {kb_identifier} for project {self.project_id}")
     def list_kbs(
             self,
-            project_id: str,
             name: str = None,
             start: str = "0",
             count: str = "100"
-    ):
+    ) -> dict:
         """
-        Retrieves a list of knowledge bases (KBs) in the specified project, filtered by the provided criteria.
+        Retrieves a list of knowledge bases (KBs) in the specified project.
 
-        :param project_id: str - Unique identifier of the project.
-        :param name: str, optional - Name of the KB to filter by. Defaults to None.
-        :param start: str - Starting index for pagination. Defaults to '0'.
-        :param count: str - Number of KBs to retrieve. Defaults to '100'.
-        :return: dict or str - JSON response containing the list of KBs if successful, otherwise raw text.
+        :param name: str, optional - Name of the KB to filter by.
+        :param start: str, optional - Starting index for pagination (default: '0').
+        :param count: str, optional - Number of KBs to retrieve (default: '100').
+        :return: dict or str - List of KBs or error message.
+        :raises InvalidAPIResponseException: If an error occurs during retrieval.
         """
         endpoint = LIST_KBS_V1
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id
+            "ProjectId": self.project_id
         }
         params = {
             "start": start,
@@ -973,26 +962,24 @@ class AgenticProcessClient(BaseClient):
         if name:
             params["name"] = name
 
-        response = self.api_service.get(endpoint=endpoint, headers=headers, params=params)
-        try:
-            return response.json()
-        except JSONDecodeError:
-            return response.text
+        logger.debug(f"Listing tasks in project with ID {self.project_id}")
 
+        response = self.api_service.get(endpoint=endpoint, headers=headers, params=params)
+        validate_status_code(response)
+        return parse_json_response(response, f"list knowledge bases for project {self.project_id}")
     def delete_kb(
             self,
-            project_id: str,
             kb_id: str = None,
             kb_name: str = None
-    ):
+    ) -> dict:
         """
-        Deletes a specific knowledge base (KB) in the specified project.
+        Deletes a specific knowledge base (KB) by its ID or name.
 
-        :param project_id: str - Unique identifier of the project.
-        :param kb_id: str, optional - Unique identifier of the KB to delete.
-        :param kb_name: str, optional - Name of the KB to delete.
-        :return: dict or str - JSON response confirming deletion if successful, otherwise raw text.
+        :param kb_id: str, optional - Unique identifier of the KB.
+        :param kb_name: str, optional - Name of the KB.
+        :return: dict or str - Confirmation of deletion or error message.
         :raises ValueError: If neither kb_id nor kb_name is provided.
+        :raises InvalidAPIResponseException: If an error occurs during deletion.
         """
         if not (kb_id or kb_name):
             raise ValueError("Either kb_id or kb_name must be provided.")
@@ -1001,39 +988,45 @@ class AgenticProcessClient(BaseClient):
         endpoint = DELETE_KB_V1.format(kbId=identifier)
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id
+            "ProjectId": self.project_id
         }
 
+        if kb_id:
+            logger.debug(f"Deleting KB with ID {kb_id}")
+        else:
+            logger.debug(f"Deleting KB with name {kb_name}")
+
         response = self.api_service.delete(endpoint=endpoint, headers=headers)
-        try:
-            return response.json()
-        except JSONDecodeError:
-            return response.text
+
+        if response.status_code != 204:
+            logger.error(f"Unable to delete knowledge base {kb_id or kb_name} from project {self.project_id}: JSONDecodeError parsing error (status {response.status_code}). Response: {response.text}")
+            raise InvalidAPIResponseException(f"Unable to delete knowledge base {kb_id or kb_name} from project {self.project_id}: {response.text}")
+        else:
+            return {}
 
     def list_jobs(
             self,
-            project_id: str,
             start: str = "0",
             count: str = "100",
             topic: str = None,
             token: str = None,
             name: str = None
-    ):
+    ) -> dict:
         """
-        Retrieves a list of jobs in the specified project, filtered by the provided criteria.
-
-        :param project_id: str - Unique identifier of the project.
-        :param start: str - Starting index for pagination. Defaults to '0'.
-        :param count: str - Number of jobs to retrieve. Defaults to '100'.
-        :param topic: str, optional - Topic of the jobs to filter by. Defaults to None.
-        :param token: str, optional - Token of the jobs to filter by. Defaults to None.
-        :param name: str, optional - Name of the jobs to filter by. Defaults to None.
-        :return: dict or str - JSON response containing the list of jobs if successful, otherwise the raw response text.
+        Retrieves a specific list of jobs in the specified project.
+
+        :param start: str, optional - Starting index for pagination (default: '0').
+        :param count: str, optional - Number of jobs to retrieve (default: '100').
+        :param topic: str - optional - Topiccollege of the jobs to filter by.
+        :param token: str, optional - Token of the jobs to filter by.
+        :param name: str, optional - Name of the jobs to filter by.
+        :return: dict or str - List of jobs or error message.
+        :raises InvalidAPIResponseException: If an error occurs during retrieval.
         """
         endpoint = LIST_JOBS_V1
         headers = {
             "Authorization": self.api_service.token,
-            "ProjectId": project_id
+            "ProjectId": self.project_id
         }
         params = {
             "start": start,
@@ -1046,14 +1039,13 @@ class AgenticProcessClient(BaseClient):
         if name:
             params["name"] = name
 
+        logger.debug(f"Listing jobs for project with ID {self.project_id}")
+
         response = self.api_service.get(
             endpoint=endpoint,
             headers=headers,
             params=params
         )
-        try:
-            result = response.json()
-        except JSONDecodeError:
-            result = response.text
+        validate_status_code(response)
+        return parse_json_response(response, f"list jobs for project {self.project_id}")
 
-        return result