pyxecm 2.0.4__py3-none-any.whl → 3.0.1__py3-none-any.whl

pyxecm/otca.py

@@ -45,6 +45,16 @@ REQUEST_MAX_RETRIES = 2
 
 default_logger = logging.getLogger(MODULE_NAME)
 
+try:
+    from pyvis.network import Network
+
+    pyvis_installed = True
+except ModuleNotFoundError:
+    default_logger.warning(
+        "Module pyvis is not installed. Customizer will not support graph visualization.",
+    )
+    pyvis_installed = False
+
 
 class OTCA:
     """Interact with Content Aviator REST API."""
@@ -55,15 +65,19 @@ class OTCA:
     _context = ""
     _embed_token: str | None = None
     _chat_token: str | None = None
+    _chat_token_hashed: str | None = None
+    _node_dictionary: dict = {}
 
     def __init__(
         self,
         chat_url: str,
         embed_url: str,
+        studio_url: str,
         otds_url: str,
         client_id: str,
         client_secret: str,
-        otcs_object: OTCS,
+        content_system: dict | None = None,
+        otcs_object: OTCS | None = None,
         synonyms: list | None = None,
         inline_citation: bool = True,
         logger: logging.Logger = default_logger,
@@ -75,14 +89,18 @@ class OTCA:
                 The Content Aviator base URL for chat.
             embed_url (str):
                 The Content Aviator base URL for embedding.
+            studio_url (str):
+                The base URL of Content Aviator Studio.
             otds_url (str):
                 The OTDS URL.
             client_id (str):
                 The Core Share Client ID.
             client_secret (str):
                 The Core Share client secret.
+            content_system (dict | None):
+                The Content System configuration for the services which control the authentication.
             otcs_object (OTCS):
-                The OTCS object.
+                The OTCS object..
             synonyms (list):
                 List of synonyms that are used to generate a better response to the user.
             inline_citation (bool):
@@ -102,6 +120,13 @@ class OTCA:
         otca_config["chatUrl"] = chat_url + "/v1/chat"
         otca_config["searchUrl"] = chat_url + "/v1/context"
         otca_config["embedUrl"] = embed_url + "/v1/embeddings"
+        otca_config["studioGraphsUrl"] = studio_url + "/studio/v1/graphs"
+        otca_config["studioAgentsUrl"] = studio_url + "/studio/v1/agents"
+        otca_config["studioToolsUrl"] = studio_url + "/studio/v1/tools"
+        otca_config["studioRulesUrl"] = studio_url + "/studio/v1/rules"
+        otca_config["studioModelsUrl"] = studio_url + "/studio/v1/api/models"
+
+        otca_config["content_system"] = content_system if content_system else {"chat": "xecm", "embed": "xecm"}
         otca_config["clientId"] = client_id
         otca_config["clientSecret"] = client_secret
         otca_config["otdsUrl"] = otds_url
@@ -196,10 +221,24 @@ class OTCA:
         if content_type:
             request_header["Content-Type"] = content_type
 
-        if service_type == "chat" and self._chat_token is not None:
-            request_header["Authorization"] = "Bearer {}".format(self._chat_token)
+        # Configure default Content System
+        content_system = self.config()["content_system"].get(service_type, "none")
+
+        if content_system == "none":
+            return request_header
 
-        elif service_type == "embed" and self._embed_token is not None:
+        if service_type == "chat":
+            if self._chat_token is None:
+                self.authenticate_chat()
+
+            if content_system == "xecm":
+                request_header["Authorization"] = "Bearer {}".format(self._chat_token_hashed)
+            elif content_system == "xecm-direct":
+                request_header["otcsticket"] = self._chat_token
+
+        elif service_type == "embed":
+            if self._embed_token is None:
+                self.authenticate_embed()
             request_header["Authorization"] = "Bearer {}".format(self._embed_token)
 
         return request_header
@@ -220,6 +259,7 @@ class OTCA:
         success_message: str = "",
         max_retries: int = REQUEST_MAX_RETRIES,
         retry_forever: bool = False,
+        parse_request_response: bool = True,
     ) -> dict | None:
         """Call an Content Aviator REST API in a safe way.
 
@@ -251,6 +291,9 @@ class OTCA:
                 Number of retries on connection errors. Defaults to REQUEST_MAX_RETRIES.
             retry_forever (bool, optional):
                 Whether to wait forever without timeout. Defaults to False.
+            parse_request_response (bool, optional):
+                Whether the response text should be interpreted as JSON and loaded
+                into a dictionary. Defaults to True.
 
         Returns:
             dict | None:
@@ -261,6 +304,17 @@ class OTCA:
         retries = 0
         while True:
             try:
+                self.logger.debug(
+                    "Sending %s request ->\nurl: %s\nheaders: %s\ndata: %s\njson: %s\nfiles: %s\ntimeout: %s",
+                    method,
+                    url,
+                    json.dumps(headers, indent=2),
+                    json.dumps(data, indent=2),
+                    json.dumps(json_data, indent=2),
+                    files,
+                    timeout,
+                )
+
                 response = requests.request(
                     method=method,
                     url=url,
@@ -274,7 +328,10 @@ class OTCA:
                 if response.ok:
                     if success_message:
                         self.logger.debug(success_message)
-                    return self.parse_request_response(response)
+                    if parse_request_response:
+                        return self.parse_request_response(response, show_error=show_error)
+                    else:
+                        return response
                 # Check if Session has expired - then re-authenticate and try once more
                 elif response.status_code == 401 and retries == 0:
                     self.logger.debug("Session has expired - try to re-authenticate...")
@@ -404,7 +461,7 @@ class OTCA:
 
     # end method definition
 
-    def authenticate_chat(self) -> str | None:
+    def authenticate_chat(self) -> str:
         """Authenticate for Chat service at Content Aviator / CSAI.
 
         Returns:
@@ -413,11 +470,20 @@ class OTCA:
 
         """
 
+        if self.otcs_object is None:
+            msg = "OTCS Object is not defined, authentication failed."
+            raise AttributeError(msg)
+
         token = self.otcs_object.otcs_ticket() or self.otcs_object.authenticate()
 
-        if token and "otcsticket" in token:
+        if isinstance(token, dict) and "otcsticket" in token:
+            token = token["otcsticket"]
+
+        if token:
+            self._chat_token = token
+
             # Encode the input string before hashing
-            encoded_string = token["otcsticket"].encode("utf-8")
+            encoded_string = token.encode("utf-8")
 
             # Create a new SHA-512 hash object
             sha512 = hashlib.sha512()
@@ -428,11 +494,14 @@ class OTCA:
             # Get the hexadecimal representation of the hash
             hashed_output = sha512.hexdigest()
 
-            self._chat_token = hashed_output
+            self._chat_token_hashed = hashed_output
 
             return self._chat_token
 
-        return None
+        else:
+            self.logger.error("Authentication failed. Token not found.")
+
+            return None
 
     # end method definition
 
@@ -591,7 +660,7 @@ class OTCA:
     ) -> dict:
         """Semantic search for text chunks.
 
-        Search requests are meant to be called as end-users.  This should involve
+        Search requests are meant to be called as end-users. This should involve
         passing the end-user's access token via the Authorization HTTP header.
         The chat service use OTDS's token endpoint to ensure that the token is valid.
 
@@ -683,18 +752,19 @@ class OTCA:
 
         Args:
             content (str | None):
-                Content to be embedded. Can be empty for "delete" operations.
+                Content to be embedded. This is a document chunk. Can be empty for "delete" operations.
             operation (str):
                 This can be either "add", "update" or "delete".
             document_id (int):
-                The ID of the document the content originates from.
+                The ID of the document the content originates from. This becmes metadata in the vector store.
             workspace_id (int):
-                The ID of the workspace the content originates from.
+                The ID of the workspace the content originates from. This becomes metadata in the vector store.
             additional_metadata (dict | None):
                 Dictionary with additional metadata.
 
         Returns:
-            dict: _description_
+            dict:
+                REST API response or None in case of an error.
 
         """
 
@@ -733,3 +803,1273 @@ class OTCA:
         )
 
     # end method definition
+
+    def get_graphs(self) -> list | None:
+        """Get all graphs.
+
+        Returns:
+            list:
+                A list of all graphs.
+
+        Example:
+        [
+            {
+                'id': '60fa6f74-a0a6-4f95-abf4-80a3ae19913c',
+                'name': 'supervisor',
+                'description': None,
+                'attributes': None,
+                'createdAt': '2025-07-01T09:06:28.123Z',
+                'updatedAt': '2025-07-01T09:06:28.123Z',
+                'tenantId': '010bae82-7b31-4e52-9db4-00bde19aa398'
+            },
+            {
+                'id': 'f287ef5e-0acf-47cf-91cb-64b3195ceeb8',
+                'name': 'breakdown',
+                'description': None,
+                'attributes': None,
+                'createdAt': '2025-07-01T09:06:28.123Z',
+                'updatedAt': '2025-07-01T09:06:28.123Z',
+                'tenantId': '010bae82-7b31-4e52-9db4-00bde19aa398'
+            },
+            {
+                'id': '378a6369-6f78-4ccc-a1f1-8b070973be24',
+                'name': 'root',
+                'description': None,
+                'attributes': None,
+                'createdAt': '2025-07-01T09:06:28.123Z',
+                'updatedAt': '2025-07-01T09:06:28.123Z',
+                'tenantId': '010bae82-7b31-4e52-9db4-00bde19aa398'
+            },
+            {
+                'id': '6925e805-eaea-4054-a07f-e3e48c7bab15',
+                'name': 'answer',
+                'description': None,
+                'attributes': None,
+                'createdAt': '2025-07-01T09:06:28.123Z',
+                'updatedAt': '2025-07-01T09:06:28.123Z',
+                'tenantId': '010bae82-7b31-4e52-9db4-00bde19aa398'
+            }
+        ]
+
+        """
+
+        request_url = self.config()["studioGraphsUrl"]
+        request_header = self.request_header(service_type="studio")
+
+        response = self.do_request(
+            url=request_url,
+            method="GET",
+            headers=request_header,
+            timeout=None,
+            show_error=True,
+            failure_message="Failed get graphs",
+        )
+
+        if response is None:
+            return None
+
+        return response.get("results", [])
+
+    # end method definition
+
+    def get_graphs_iterator(self) -> iter:
+        """Get an iterator object that can be used to traverse graphs.
+
+        Returns:
+            iter:
+                A generator yielding one graph per iteration.
+                If the REST API fails, returns no value.
+
+        Yields:
+            Iterator[iter]:
+                One graph at a time.
+
+        """
+
+        graphs: list = self.get_graphs()
+
+        yield from graphs
+
+    # end method definition
+
+    def get_graph(self, graph_id: str) -> dict | None:
+        """Get a graph by its ID.
+
+        Args:
+            graph_id (str):
+                The ID of the graph.
+
+        Returns:
+            dict | None:
+                Graph data or none in case of an error.
+
+        Example:
+        {
+            'id': 'a245ddcb-2df0-465a-abab-b21222245ba9',
+            'name': 'supervisor',
+            'description': None,
+            'attributes': None,
+            'createdAt': '2025-07-01T16:51:56.703Z',
+            'updatedAt': '2025-07-01T16:51:56.703Z',
+            'tenantId': '05f43f12-5865-46cd-8954-1af3dc575e88'
+        }
+
+        """
+
+        request_url = self.config()["studioGraphsUrl"] + "/" + graph_id
+        request_header = self.request_header(service_type="studio")
+
+        return self.do_request(
+            url=request_url,
+            method="GET",
+            headers=request_header,
+            timeout=None,
+            show_error=True,
+            failure_message="Failed get graphs",
+        )
+
+    # end method definition
+
+    def get_graph_nodes(self, graph_id: str) -> list | None:
+        """Get all nodes of a graph.
+
+        Args:
+            graph_id (str):
+                The ID of the Graph to retrieve the nodes for.
+
+        Returns:
+            list | None:
+                A list of all nodes of the graph.
+
+        Example:
+        [
+            {
+                'id': '1b99d09f-9e36-4da9-8fe0-8ebe0652fef3',
+                'name': 'decision',
+                'description': None,
+                'discriminator': 1,
+                'createdAt': '2025-07-01T09:06:28.140Z',
+                'updatedAt': '2025-07-01T09:06:28.140Z',
+                'version': 0,
+                'status': 0,
+                'graphId': '60fa6f74-a0a6-4f95-abf4-80a3ae19913c',
+                'attributes': {
+                    'studio': 'routerAgent'
+                },
+                'klassId': '20470453-2179-4392-aa0e-bc46ae3f3e80'
+            }
+        ]
+
+        """
+
+        request_url = self.config()["studioGraphsUrl"] + "/" + graph_id + "/nodes"
+        request_header = self.request_header(service_type="studio")
+
+        response = self.do_request(
+            url=request_url,
+            method="GET",
+            headers=request_header,
+            timeout=None,
+            show_error=True,
+            failure_message="Failed get list of graph nodes!",
+        )
+
+        if response is None:
+            return None
+
+        return response.get("results", [])
+
+    # end method definition
+
+    def get_graph_nodes_iterator(self, graph_id: str) -> iter:
+        """Get an iterator object that can be used to traverse graph nodes.
+
+        Returns:
+            iter:
+                A generator yielding one node per iteration.
+                If the REST API fails, returns no value.
+
+        Yields:
+            Iterator[iter]:
+                One node at a time.
+
+        """
+
+        nodes: list = self.get_graph_nodes(graph_id=graph_id)
+
+        yield from nodes
+
+    # end method definition
+
+    def get_graph_nodes_by_name(self, name: str) -> list | None:
+        """Get all nodes of a graph by name.
+
+        Args:
+            name (str):
+                The Name of the Graph to retrieve the nodes for.
+
+        Returns:
+            list | None:
+                A list of all nodes of the graph.
+
+        """
+
+        graphs = self.get_graphs()
+
+        if graphs is None:
+            return None
+
+        graph = next((g for g in graphs if g["name"] == name), None)
+
+        if graph is None:
+            self.logger.error("Graph -> '%s' not found!", name)
+            return None
+
+        request_url = self.config()["studioGraphsUrl"] + "/" + graph["id"] + "/nodes"
+        request_header = self.request_header(service_type="studio")
+
+        response = self.do_request(
+            url=request_url,
+            method="GET",
+            headers=request_header,
+            timeout=None,
+            show_error=True,
+            failure_message="Failed get list of graphs!",
+        )
+
+        if response is None:
+            return None
+
+        return response.get("results", [])
+
+    # end method definition
+
+    def get_graph_edges(self, graph_id: str) -> list | None:
+        """Get all edges of a graph.
+
+        Args:
+            graph_id (str):
+                The ID of the Graph to retrieve the edges for.
+
+        Returns:
+            list | None:
+                A list of all edges of the graph.
+
+        Example:
+        [
+            {
+                'id': '420610ae-68d0-47d2-9807-6e5a5f75a02d',
+                'sourceId': '8cec788a-23eb-4480-a004-1f3c7edd1054',
+                'targetId': '233db9e1-1f5a-4fb6-8f70-fca46199c224',
+                'type': 0,
+                'graphId': '60fa6f74-a0a6-4f95-abf4-80a3ae19913c',
+                'createdAt': '2025-07-01T09:06:28.192Z',
+                'updatedAt': '2025-07-01T09:06:28.192Z',
+                'version': 0,
+                'status': 0,
+                'attributes': None
+            }
+        ]
+
+        """
+
+        request_url = self.config()["studioGraphsUrl"] + "/" + graph_id + "/edges"
+        request_header = self.request_header(service_type="studio")
+
+        response = self.do_request(
+            url=request_url,
+            method="GET",
+            headers=request_header,
+            timeout=None,
+            show_error=True,
+            failure_message="Failed get list of graph edges!",
+        )
+
+        if response is None:
+            return None
+
+        return response.get("results", [])
+
+    # end method definition
+
+    def get_graph_edges_iterator(self, graph_id: str) -> iter:
+        """Get an iterator object that can be used to traverse graph edges.
+
+        Returns:
+            iter:
+                A generator yielding one edge per iteration.
+                If the REST API fails, returns no value.
+
+        Yields:
+            Iterator[iter]:
+                One edge at a time.
+
+        """
+
+        edges: list = self.get_graph_edges(graph_id=graph_id)
+
+        yield from edges
+
+    # end method definition
+
+    def visualize_graph(self, graph_id: str) -> str:
+        """Visualize a graph.
+
+        Args:
+            graph_id (str):
+                The ID of the graph.
+
+        Returns:
+            str: Filename of the generated html file
+
+        """
+
+        if not pyvis_installed:
+            self.logger.warning("Cannot visualize graph. Python module pyvis not installed!")
+            return None
+
+        graph = self.get_graph(graph_id=graph_id)
+        graph_id = graph["id"]
+        graph_name = graph["name"]
+        net = Network(notebook=False, directed=True, height="1000px", width="100%", filter_menu=True, select_menu=True)
+        net.heading = f"Aviator Studio graph: {graph_name}"
+        nodes = self.get_graph_nodes_iterator(graph_id=graph_id)
+        for node in nodes:
+            node_id = node["id"]
+            node_name = node["name"]
+            node_attributes = node["attributes"]
+            self._node_dictionary[(graph_id, node_id)] = node_name
+            if node_attributes and "APISchema" in node_attributes:
+                net.add_node(n_id=node_id, label=node_name, title=json.dumps(node, indent=2), color="green")
+            else:
+                net.add_node(n_id=node_id, label=node_name, title=json.dumps(node, indent=2))
+            relationships = self.get_graph_node_relationships_iterator(
+                graph_id=graph_id, node_id=node_id, relation_type="rules"
+            )
+            for relationship in relationships:
+                for rule in relationship["rules"] or []:
+                    net.add_node(
+                        n_id=rule["id"], label=rule["name"], title=json.dumps(rule, indent=2), shape="box", color="red"
+                    )
+                    net.add_edge(source=node_id, to=rule["id"])
+            relationships = self.get_graph_node_relationships_iterator(
+                graph_id=graph_id, node_id=node_id, relation_type="prompts"
+            )
+            for relationship in relationships:
+                for prompt in relationship["prompts"] or []:
+                    net.add_node(
+                        n_id=prompt["id"],
+                        label=prompt["name"],
+                        title=json.dumps(prompt, indent=2),
+                        shape="oval",
+                        color="green",
+                    )
+                    net.add_edge(source=node_id, to=prompt["id"])
+        edges = self.get_graph_edges_iterator(graph_id=graph_id)
+        for edge in edges:
+            edge_source_id = edge["sourceId"]
+            edge_target_id = edge["targetId"]
+            net.add_edge(source=edge_source_id, to=edge_target_id)
+
+        html_file = "{}.html".format(graph_name)
+        net.save_graph(html_file)
+        self.logger.info("Graph visualization saved to -> %s", html_file)
+
+        return html_file
+
+    # end method definition
+
+    def get_model_types(self) -> list:
+        """Get a list of all model types. Hardcoded.
+
+        Returns:
+            list:
+                Model types.
+
+        """
+
+        return ["tenants", "graphs", "nodes", "edges", "actions", "tools", "prompts", "rules", "klasses"]
+
+    # end method definition
+
+    def get_models(self, model_type: str) -> list | None:
+        """Get all model details by type.
+
+        Args:
+            model_type (str):
+                The type of the model. Possible model types:
+                * tenants
+                * graphs
+                * nodes
+                * edges
+                * actions
+                * tools
+                * prompts
+                * rules
+                * klasses
+
+        Returns:
+            list | None:
+                A list of all models of a given type.
+
+        """
+
+        request_url = self.config()["studioModelsUrl"] + "/" + model_type
+        request_header = self.request_header(service_type="studio")
+
+        response = self.do_request(
+            url=request_url,
+            method="GET",
+            headers=request_header,
+            timeout=None,
+            show_error=True,
+            failure_message="Failed to get list of models!",
+        )
+
+        if response is None:
+            return None
+
+        return response.get("results", [])
+
+    # end method definition
+
+    def get_models_iterator(self, model_type: str) -> iter:
+        """Get an iterator object that can be used to traverse models.
+
+        Returns:
+            iter:
+                A generator yielding one model per iteration.
+                If the REST API fails, returns no value.
+
+        Yields:
+            Iterator[iter]:
+                One edge at a time.
+
+        """
+
+        models: list = self.get_models(model_type=model_type)
+
+        yield from models
+
+    # end method definition
+
+    def get_model(self, model_type: str, model_id: str) -> dict | None:
+        """Get a specific model based on its type and ID.
+
+        Args:
+            model_type (str):
+                The type of the model. Possible model types:
+                * tenants
+                * graphs
+                * nodes
+                * edges
+                * actions
+                * tools
+                * prompts
+                * rules
+                * klasses
+            model_id (str):
+                The ID of the model.
+
+        Returns:
+            dict | None:
+                The model data.
+
+        """
+
+        request_url = self.config()["studioModelsUrl"] + "/" + model_type + "/" + model_id
+        request_header = self.request_header(service_type="studio")
+
+        return self.do_request(
+            url=request_url,
+            method="GET",
+            headers=request_header,
+            timeout=None,
+            show_error=True,
+            failure_message="Failed to get models with type -> '{}' and ID -> {}!".format(model_type, model_id),
+        )
+
+    # end method definition
+
+    def get_model_by_type_and_name(self, model_type: str, name: str) -> dict | None:
+        """Get model details by model type and name.
+
+        Args:
+            model_type (str):
+                The type of the model.
+            name (str):
+                The name of the model.
+
+        Returns:
+            dict:
+                Model details or None in case of an error.
+
+        """
+
+        models = self.get_models(model_type=model_type)
+        if models:
+            return next((model for model in models if model["name"] == name), None)
+
+        return None
+
+    # end method definition
+
+    # end method definition
+
+    def delete_model(self, model_type: str, model_id: str) -> dict | None:
+        """Delete a model by type and id.
+
+        Args:
+            model_type (str):
+                The type of the model.
+            model_id (str):
+                The model name.
+
+        Returns:
+            dict | None:
+                Dict with the model details
+
+        """
+
+        self.logger.info("Deleting existing model -> '%s' (%s)", model_type, model_id)
+
+        request_header = self.request_header(service_type="studio")
+        request_url = self.config()["studioModelsUrl"] + "/" + model_type + "/" + model_id
+        return self.do_request(
+            url=request_url,
+            method="DELETE",
+            headers=request_header,
+            timeout=None,
+            show_error=True,
+            failure_message="Failed to delete model -> '{}' ({})!".format(model_type, model_id),
+        )
+
+    # end method definition
+
+    def update_model(self, model_type: str, model_id: str, request_body: dict) -> dict | None:
+        """Update a model with a given type and ID.
+
+        Args:
+            model_type (str):
+                The type of the model.
+            model_id (str):
+                The ID of the model.
+            request_body (dict):
+                Data to update the model.
+
+        Returns:
+            dict | None:
+                Dict with the model details or None in case of an error.
+
+        """
+
+        self.logger.info("Updating existing model -> '%s' (%s)", model_type, model_id)
+
+        request_header = self.request_header(service_type="studio")
+        request_url = self.config()["studioModelsUrl"] + "/" + model_type + "/" + model_id
+        return self.do_request(
+            url=request_url,
+            method="PUT",
+            headers=request_header,
+            json_data=request_body,
+            timeout=None,
+            show_error=True,
+            failure_message="Failed to update model -> '{}' ({}).".format(model_type, model_id),
+        )
+
+    # end method definition
+
+    def get_tools(self) -> list | None:
+        """Get all tools.
+
+        Returns:
+            list:
+                A list of all tools.
+
+        Example:
+        [
+            {
+                'id': '305353d8-7391-497e-9f3f-8a1fe11ceac0',
+                'attributes': {
+                    'conditions': [{'messageLength': 2}],
+                    'maxHistory': -1,
+                    'showInContext': True
+                },
+                'klassId': 'b033b1d5-8182-4883-ba8a-16f0048b01b0',
+                'name': 'rephrase_search',
+                'description': 'Used for creating a standalone search query for retrieving documents. Input should be a dependent user message',
+                'discriminator': 0,
+                'createdAt': '2025-07-01T22:57:13.135Z',
+                'updatedAt': '2025-07-01T22:57:13.135Z',
+                'version': 0,
+                'status': 0,
+                'graphId': '93897862-d999-4fe0-82fc-3f9d03474545'
+            }
+        ]
+
+        """
+
+        return self.get_models(model_type="tools")
+
+    # end method definition
+
+    def get_tools_iterator(self) -> iter:
+        """Get an iterator object that can be used to traverse tools.
+
+        Returns:
+            iter:
+                A generator yielding one tool per iteration.
+                If the REST API fails, returns no value.
+
+        Yields:
+            Iterator[iter]:
+                One tool at a time.
+
+        """
+
+        tools: list = self.get_models(model_type="tools")
+
+        yield from tools
+
+    # end method definition
+
+    def get_tool(self, tool_id: str) -> dict | None:
+        r"""Get a tool by its ID.
+
+        Args:
+            tool_id (str):
+                The ID of the tool.
+
+        Returns:
+            dict | None:
+                Tool data or none in case of an error.
+
+        Example:
+        {
+            'id': '49e230ef-024a-4dd8-beeb-70210cec0564',
+            'attributes': {'APISchema': {...}},
+            'klassId': '275843d9-c39f-43e2-ad00-b02ac42b5dd6',
+            'name': 'otcm_workspace_agent_lookup_workspace',
+            'description': 'Lookup a workspace based on its type and a value of one of the workspace attributes.\n\nUse this tool if the workspace name is _not_ specified but the user asks for a specific\nworkspace attribute value like cities, products, or other attributes.\n\nReturn the workspace data if it is found. If it is not found confirm with the user if the workspace should be created or not.\nIf it should be created call the tool: otcm_workspace_agent_create_workspace',
+            'discriminator': 0,
+            'createdAt': '2025-07-01T22:57:13.535Z',
+            'updatedAt': '2025-07-01T22:57:13.535Z',
+            'version': 0,
+            'status': 0,
+            'graphId': '93897862-d999-4fe0-82fc-3f9d03474545'
+        }
+
+        """
+
+        tool = self.get_model(model_type="tools", model_id=tool_id)
+
+        return tool
+
+    # end method definition
+
+    def register_tool(
+        self,
+        request_body: dict,
+    ) -> dict:
+        r"""Register a Tool in Content Aviator.
+
+        Requests are meant to be called as a service user. This would involve passing a service user's access token
+        (token from a particular OAuth confidential client, using client credentials grant).
+
+        Args:
+            request_body (dict):
+                Body for the request. Needs to look like:
+                example:
+                    {
+                        "name": "tool name",
+                        "description": "description of the tool",
+                        "APISchema": {} # dict of the APISchema, compliant with openapi 3.0.0
+                        "requestTemplate": {
+                            "data": {
+                                "context": {
+                                    "where": "memory.input.where",
+                                    "query": "memory.input.query"
+                                }
+                            },
+                        },
+                        "responseTemplate": {},
+                        "agents": ["retrieverAgent"],
+                    }
+
+        Returns:
+            dict: Tool details or None in case of an error.
+
+        Example:
+            {
+                'id': '27ce608f-41ea-4128-aff9-91facc66bcfa',
+                'attributes': {
+                    'APISchema': {
+                        'openapi': '3.0.0',
+                        'info': {
+                            'title': 'otcm_workspace_agent_find_workspace',
+                            'version': '0.0.0'
+                        },
+                        'servers': [{'url': 'http://customizer:8000'}],
+                        'paths': {
+                            '/agents/otcm_workspace_agent/find_workspace': {
+                                'post': {
+                                    'tags': [...],
+                                    'summary': 'Find the markdown link to a workspace by workspace name and workspace type and display the link.',
+                                    'description': 'Find a workspace by workspace name and workspace type.\n\nThe returned workspace is an OTCS workspace object. Show the markdown link in the chat response, sothat the user can click on it.',
+                                    'operationId': 'otcm_workspace_agent_find_workspace_agents_otcm_workspace_agent_find_workspace_post',
+                                    'requestBody': {...},
+                                    'responses': {
+                                        '200': {
+                                            'description': 'Workspace found',
+                                            'content': {
+                                                'application/json': {
+                                                    'schema': {'$ref': '#/components/schemas/WorkspaceModel'}
+                                                }
+                                            }
+                                        },
+                                        '403': {
+                                            'description': 'Invalid credentials'
+                                        },
+                                        '404': {
+                                            'description': 'Workspace not found'
+                                        },
+                                        '422': {
+                                            'description': 'Validation Error',
+                                            'content': {...}
+                                        }
+                                    },
+                                    'security': [...]
+                                }
+                            }
+                        },
+                        'components': {
+                            'schemas': {
+                                'Body_otcm_workspace_agent_find_workspace_agents_otcm_workspace_agent_find_workspace_post': {
+                                    'properties': {...},
+                                    'type': 'object',
+                                    'required': [...],
+                                    'title': 'Body_otcm_workspace_agent_find_workspace_agents_otcm_workspace_agent_find_workspace_post'
+                                },
+                                'Context': {
+                                    'properties': {...},
+                                    'type': 'object',
+                                    'required': [...],
+                                    'title': 'Context',
+                                    'description': 'Define Model that is used to provide static context information for tools.'
+                                },
+                                'HTTPValidationError': {
+                                    'properties': {...},
+                                    'type': 'object',
+                                    'title': 'HTTPValidationError'
+                                },
+                                'ValidationError': {
+                                    'properties': {...},
+                                    'type': 'object',
+                                    'required': [...],
+                                    'title': 'ValidationError'
+                                },
+                                'WorkspaceModel': {
+                                    'properties': {...},
+                                    'type': 'object',
+                                    'title': 'WorkspaceModel',
+                                    'description': 'Defines Model for describing workspaces in OTCM (Opentext Content Management).\n\nTo display an instance of this model, please display the link.'
+                                }
+                            },
+                            'securitySchemes': {...}
+                        }
+                    },
+                    'showInContext': True,
+                    'responseFormat': 'content_and_artifact',
+                    'requestTemplate': {
+                        'data': {
+                            'context': {
+                                'query': 'memory.input.query',
+                                'where': 'memory.input.where'
+                            }
+                        }
+                    },
+                    'responseTemplate': {}
+                },
+                'klassId': '1d8dbd52-5dee-4645-841d-2889fac74b13',
+                'name': 'otcm_workspace_agent_find_workspace',
+                'description': 'Find a workspace by workspace name and workspace type.\n\nThe returned workspace is an OTCS workspace object. Show the markdown link in the chat response, sothat the user can click on it.',
+                'discriminator': 0,
+                'createdAt': '2025-07-09T12:35:26.464Z',
+                'updatedAt': '2025-07-09T12:35:26.464Z',
+                'version': 0,
+                'status': 0,
+                'graphId': '440aae89-8942-4bb0-8107-291227f8ad92'
+            }
+
+        """
+
+        # Validations:
+        for key in ["name", "description", "APISchema", "agents"]:
+            if key not in request_body:
+                self.logger.error("%s is missing in provided request body for tool registration!", key)
+                return None
+
+        # Check if the tool already exists and need to be updated only:
+        self.logger.debug("Check if tool -> '%s' already exists...", request_body["name"])
+        model = self.get_model_by_type_and_name(model_type="tools", name=request_body["name"])
+        if model:
+            self.logger.info("Updating existing tool -> '%s'...", request_body["name"])
+
+            update_body = {
+                "description": request_body["description"],
+                "attributes": {**model.get("attributes", {}), "APISchema": request_body["APISchema"]},
+            }
+            response = self.update_model(model_type="tools", model_id=model["id"], request_body=update_body)
+            if not response:
+                self.logger.error("Failed to update model -> '%s' (%s)", request_body["name"], model["id"])
+        else:
+            self.logger.info("Registering new tool -> '%s'...", request_body["name"])
+            request_header = self.request_header(service_type="studio")
+            request_url = self.config()["studioToolsUrl"]
+            response = self.do_request(
+                url=request_url,
+                method="POST",
+                headers=request_header,
+                json_data=request_body,
+                timeout=None,
+                show_error=True,
+                failure_message="Failed to register tool -> '{}'!".format(request_body["name"]),
+            )
+
+        return response
+
+    # end method definition
+
+    def get_rules(self) -> list | None:
+        r"""Get all rules.
+
+        Returns:
+            list:
+                A list of all rules.
+
+        Example:
+        [
+            {
+                'id': '4d089d1e-205d-4ff4-8128-7c2a83bd2462',
+                'name': 'evaluateLastToolResult',
+                'description': 'Equivalent of previous "toolResult" check. Evaluates the result of last tool executed and compares it with a given string. Returns `true` or `false`. This is the equivalent of \n ```const lastTool = memory.response.called[memory.response.called.length - 1];\nreturn lastTool?.result === (andConditions[condition]);```',
+                'createdAt': '2025-07-01T16:51:56.703Z',
+                'updatedAt': '2025-07-01T16:51:56.703Z',
+                'rule': {
+                    '===': [
+                        '<<nodeResult>>',
+                        {
+                            'get': [
+                                {...}, 'result'
+                            ]
+                        }
+                    ]
+                },
+                'status': 0,
+                'tenantId': '05f43f12-5865-46cd-8954-1af3dc575e88'
+            }
+        ]
+
+        """
+
+        request_url = self.config()["studioRulesUrl"]
+        request_header = self.request_header(service_type="studio")
+
+        response = self.do_request(
+            url=request_url,
+            method="GET",
+            headers=request_header,
+            timeout=None,
+            show_error=True,
+            failure_message="Failed get rules!",
+        )
+
+        if response is None:
+            return None
+
+        return response.get("results", [])
+
+    # end method definition
+
+    def get_rules_iterator(self) -> iter:
+        """Get an iterator object that can be used to traverse rules.
+
+        Returns:
+            iter:
+                A generator yielding one rule per iteration.
+                If the REST API fails, returns no value.
+
+        Yields:
+            Iterator[iter]:
+                One rule at a time.
+
+        """
+
+        rules: list = self.get_rules()
+
+        yield from rules
+
+    # end method definition
+
+    def get_rule(self, rule_id: str) -> dict | None:
+        r"""Get a rule by its ID.
+
+        Args:
+            rule_id (str):
+                The ID of the rule.
+
+        Returns:
+            dict | None:
+                Rule data or none in case of an error.
+
+        Example:
+        {
+            'id': '4d089d1e-205d-4ff4-8128-7c2a83bd2462',
+            'name': 'evaluateLastToolResult',
+            'description': 'Equivalent of previous "toolResult" check. Evaluates the result of last tool executed and compares it with a given string. Returns `true` or `false`. This is the equivalent of \n ```const lastTool = memory.response.called[memory.response.called.length - 1];\nreturn lastTool?.result === (andConditions[condition]);```',
+            'createdAt': '2025-07-01T16:51:56.703Z',
+            'updatedAt': '2025-07-01T16:51:56.703Z',
+            'rule': {
+                '===': [
+                    '<<nodeResult>>',
+                    {
+                        'get': [
+                            {...}, 'result'
+                        ]
+                    }
+                ]
+            },
+            'status': 0,
+            'tenantId': '05f43f12-5865-46cd-8954-1af3dc575e88'
+        }
+
+        """
+
+        rule = self.get_model(model_type="rules", model_id=rule_id)
+
+        return rule
+
+    # end method definition
+
+    def get_prompts(self) -> list | None:
+        r"""Get all prompts.
+
+        Returns:
+            list:
+                A list of all prompts.
+
+        Example:
+        [
+            {
+                'id': '1aeb9fa1-cb26-4b07-a736-20d25a4ab939',
+                'name': 'general_system',
+                'template': "Your name is Aviator and you are a friendly chatbot assisting users with their queries about documents. The DOCUMENTS contains text of tool calls, arguments and their responses in the following format:\n Tool '[test]' called with arguments '[args]' and returned: [tool response]. \n When responding: \n 1. If one or more tool responses are present, answer directly using the information in the tool response. Do not refer to the tool call or tool response explicitly. \n 2. If no tool response is present, reply that you do not know. \n 3. If the information is out of the scope of the document or you are unsure of the answer, reply that you do not know.  If the user explicitly requests to provide, show, display, generate a specific output format like a table, a list or a code block, please prioritize that format, when providing an answer. \nDOCUMENTS: {context}",
+                'type': 0,
+                'createdAt': '2025-07-01T16:51:56.703Z',
+                'updatedAt': '2025-07-01T16:51:56.703Z',
+                'version': None,
+                'status': 0,
+                'tenantId': '05f43f12-5865-46cd-8954-1af3dc575e88',
+                'attributes': None,
+                'description': None
+            },
+            ...
+        ]
+
+        """
+
+        return self.get_models(model_type="prompts")
+
+    # end method definition
+
+    def get_prompts_iterator(self) -> iter:
+        """Get an iterator object that can be used to traverse prompts.
+
+        Returns:
+            iter:
+                A generator yielding one prompt per iteration.
+                If the REST API fails, returns no value.
+
+        Yields:
+            Iterator[iter]:
+                One tool at a time.
+
+        """
+
+        prompts: list = self.get_models(model_type="prompts")
+
+        yield from prompts
+
+    # end method definition
+
+    def get_prompt(self, prompt_id: str) -> dict | None:
+        r"""Get a rule by its ID.
+
+        Args:
+            prompt_id (str):
+                The ID of the prompt.
+
+        Returns:
+            dict | None:
+                Prompt data or none in case of an error.
+
+        Example:
+        {
+            'id': '1aeb9fa1-cb26-4b07-a736-20d25a4ab939',
+            'name': 'general_system',
+            'template': "Your name is Aviator and you are a friendly chatbot assisting users with their queries about documents. The DOCUMENTS contains text of tool calls, arguments and their responses in the following format:\n Tool '[test]' called with arguments '[args]' and returned: [tool response]. \n When responding: \n 1. If one or more tool responses are present, answer directly using the information in the tool response. Do not refer to the tool call or tool response explicitly. \n 2. If no tool response is present, reply that you do not know. \n 3. If the information is out of the scope of the document or you are unsure of the answer, reply that you do not know.  If the user explicitly requests to provide, show, display, generate a specific output format like a table, a list or a code block, please prioritize that format, when providing an answer. \nDOCUMENTS: {context}",
+            'type': 0,
+            'createdAt': '2025-07-01T16:51:56.703Z',
+            'updatedAt': '2025-07-01T16:51:56.703Z',
+            'version': None,
+            'status': 0,
+            'tenantId': '05f43f12-5865-46cd-8954-1af3dc575e88',
+            'attributes': None,
+            'description': None
+        },
+
+        """
+
+        prompt = self.get_model(model_type="prompts", model_id=prompt_id)
+
+        return prompt
+
+    # end method definition
+
+    def get_actions(self) -> list | None:
+        r"""Get all actions.
+
+        Returns:
+            list:
+                A list of all actions.
+
+        Example:
+        [
+            {
+                'id': '98dec337-8284-4d30-8a6d-0da099aa025a',
+                'attributes': {'studio': 'routerAgent'},
+                'klassId': '3d2d2500-483a-4af6-9103-79da80994852',
+                'name': 'decision',
+                'description': None,
+                'discriminator': 1,
+                'createdAt': '2025-07-02T06:45:04.117Z',
+                'updatedAt': '2025-07-02T06:45:04.117Z',
+                'version': 0,
+                'status': 0,
+                'graphId': '02a6ae86-dbf5-4007-ad66-090a145bc81a'
+            },
+            ...
+        ]
+
+        """
+
+        return self.get_models(model_type="actions")
+
+    # end method definition
+
+    def get_actions_iterator(self) -> iter:
+        """Get an iterator object that can be used to traverse actions.
+
+        Returns:
+            iter:
+                A generator yielding one action per iteration.
+                If the REST API fails, returns no value.
+
+        Yields:
+            Iterator[iter]:
+                One action at a time.
+
+        """
+
+        actions: list = self.get_models(model_type="actions")
+
+        yield from actions
+
+    # end method definition
+
+    def get_action(self, action_id: str) -> dict | None:
+        r"""Get a action by its ID.
+
+        Args:
+            action_id (str):
+                The ID of the action.
+
+        Returns:
+            dict | None:
+                Action data or none in case of an error.
+
+        Example:
+        {
+            'id': '98dec337-8284-4d30-8a6d-0da099aa025a',
+            'attributes': {'studio': 'routerAgent'},
+            'klassId': '3d2d2500-483a-4af6-9103-79da80994852',
+            'name': 'decision',
+            'description': None,
+            'discriminator': 1,
+            'createdAt': '2025-07-02T06:45:04.117Z',
+            'updatedAt': '2025-07-02T06:45:04.117Z',
+            'version': 0,
+            'status': 0,
+            'graphId': '02a6ae86-dbf5-4007-ad66-090a145bc81a'
+        },
+
+        """
+
+        action = self.get_model(model_type="actions", model_id=action_id)
+
+        return action
+
+    # end method definition
+
+    def get_klasses(self) -> list | None:
+        r"""Get all klasses.
+
+        Returns:
+            list:
+                A list of all klasses.
+
+        Example:
+        [
+            {
+                'id': '20cfe232-cf03-4b77-a4e6-bc9339371a37',
+                'name': 'RephraseSearch',
+                'tenantId': 'eb6fee1e-da08-4046-9867-e96ac0ec5bdf',
+                'path': '../langchain_tools/tools/rephraseSearch',
+                'type': 8,
+                'createdAt': '2025-07-02T06:45:04.099Z',
+                'updatedAt': '2025-07-02T06:45:04.099Z',
+                'description': None
+            },
+            ...
+        ]
+
+        """
+
+        return self.get_models(model_type="klasses")
+
+    # end method definition
+
+    def get_klasses_iterator(self) -> iter:
+        """Get an iterator object that can be used to traverse klasses.
+
+        Returns:
+            iter:
+                A generator yielding one klass per iteration.
+                If the REST API fails, returns no value.
+
+        Yields:
+            Iterator[iter]:
+                One klass at a time.
+
+        """
+
+        klasses: list = self.get_models(model_type="klasses")
+
+        yield from klasses
+
+    # end method definition
+
+    def get_klass(self, klass_id: str) -> dict | None:
+        r"""Get a klass by its ID.
+
+        Args:
+            klass_id (str):
+                The ID of the klass.
+
+        Returns:
+            dict | None:
+                Klass data or none in case of an error.
+
+        Example:
+        {
+            'id': '20cfe232-cf03-4b77-a4e6-bc9339371a37',
+            'name': 'RephraseSearch',
+            'tenantId': 'eb6fee1e-da08-4046-9867-e96ac0ec5bdf',
+            'path': '../langchain_tools/tools/rephraseSearch',
+            'type': 8,
+            'createdAt': '2025-07-02T06:45:04.099Z',
+            'updatedAt': '2025-07-02T06:45:04.099Z',
+            'description': None
+        }
+
+        """
+
+        klass = self.get_model(model_type="klasses", model_id=klass_id)
+
+        return klass
+
+    # end method definition
+
+    def get_graph_node_relationships(self, graph_id: str, node_id: str, relation_type: str) -> list | None:
+        """Get all relations to prompts or rules for a graph node.
+
+        Args:
+            graph_id (str):
+                The ID of the Graph to retrieve the relationships for.
+            node_id (str):
+                The ID of the Graph node to retrieve the relationships for.
+            relation_type (str):
+                This can either be "prompts" or "rules".
+
+        Returns:
+            list | None:
+                A list of relationships for the node.
+
+        Example:
+        [
+        ]
+
+        """
+
+        request_url = self.config()["studioGraphsUrl"] + "/" + graph_id + "/nodes/" + node_id + "/" + relation_type
+        request_header = self.request_header(service_type="studio")
+
+        response = self.do_request(
+            url=request_url,
+            method="GET",
+            headers=request_header,
+            timeout=None,
+            show_error=True,
+            failure_message="Failed get list of graph node relationships!",
+        )
+
+        if response is None:
+            return None
+
+        return response.get("results", [])
+
+    # end method definition
+
+    def get_graph_node_relationships_iterator(
+        self, graph_id: str, node_id: str, relation_type: str | list = "prompts"
+    ) -> iter:
+        """Get an iterator object that can be used to traverse prompts.
+
+        Args:
+            graph_id (str):
+                The ID of the Graph to retrieve the relationships for.
+            node_id (str):
+                The ID of the Graph node to retrieve the relationships for.
+            relation_type (str):
+                This can either be "prompts" or "rules".
+
+        Returns:
+            iter:
+                A generator yielding one relationship per iteration.
+                If the REST API fails, returns no value.
+
+        Yields:
+            Iterator[iter]:
+                One relationship at a time.
+
+        """
+
+        relationships: list = self.get_graph_node_relationships(
+            graph_id=graph_id, node_id=node_id, relation_type=relation_type
+        )
+        if not relationships:
+            return
+
+        yield from relationships
+
+    # end method definition