naeural-client 2.6.24__py3-none-any.whl → 2.6.26__py3-none-any.whl

naeural_client/_ver.py

@@ -1,4 +1,4 @@
-__VER__ = "2.6.24"
+__VER__ = "2.6.26"
 
 if __name__ == "__main__":
   with open("pyproject.toml", "rt") as fd:

naeural_client/base/generic_session.py

@@ -2664,6 +2664,7 @@ class GenericSession(BaseDecentrAIObject):
       df_only=False,
       debug=False,
       eth=False,
+      all_info=False,
     ):
       """
       This function will return a Pandas dataframe  known nodes in the network based on
@@ -2698,6 +2699,9 @@ class GenericSession(BaseDecentrAIObject):
       eth: bool, optional
           If True, will use the nodes eth addresses instead of internal. Defaults to False.
           
+      all_info: bool, optional
+          If True, will return all the information. Defaults to False.
+          
       Returns
       -------
       
@@ -2723,11 +2727,19 @@ class GenericSession(BaseDecentrAIObject):
         'Oracle' : PAYLOAD_DATA.NETMON_IS_SUPERVISOR,
         'Peered' : PAYLOAD_DATA.NETMON_WHITELIST,
       })
-      reverse_mapping = {v: k for k, v in mapping.items()}
+      if all_info:
+        mapping = OrderedDict({
+          # we assign dummy integer values to the computed columns 
+          # and we will fillter them 
+          'ETH Address': 1,
+          **mapping
+        })
       res = OrderedDict()
       for k in mapping:
         res[k] = []
 
+      reverse_mapping = {v: k for k, v in mapping.items()}
+
       result, elapsed = self.__wait_for_supervisors_net_mon_data(
         supervisor=supervisor,
         timeout=timeout,
@@ -2759,6 +2771,8 @@ class GenericSession(BaseDecentrAIObject):
           if supervisors_only and not is_supervisor:
             continue
           for key, column in reverse_mapping.items():
+            if isinstance(key, int):
+              continue
             val = node_info.get(key, None)
             if key == PAYLOAD_DATA.NETMON_LAST_REMOTE_TIME:
               # val hols a string '2024-12-23 23:50:16.462155' and must be converted to a datetime
@@ -2772,7 +2786,10 @@ class GenericSession(BaseDecentrAIObject):
                 # again self.get_node_name(best_super) might not work if using the hb data
                 best_super_alias = node_info.get(PAYLOAD_DATA.NETMON_EEID, None)
               val = self.bc_engine._add_prefix(val)
-              if eth:
+              if all_info:
+                val_eth = self.bc_engine.node_address_to_eth_address(val)
+                res['ETH Address'].append(val_eth)
+              elif eth:
                 val = self.bc_engine.node_address_to_eth_address(val)
             elif key == PAYLOAD_DATA.NETMON_WHITELIST:
               val = client_is_allowed

naeural_client/bc/base.py

@@ -621,6 +621,7 @@ class BaseBlockEngine:
     address = self._remove_prefix(address)
     address = BCct.ADDR_PREFIX + address  
     return address
+  
 
   
   def _pk_to_address(self, public_key):
@@ -915,6 +916,23 @@ class BaseBlockEngine:
       the address without the prefix.
     """
     return self._remove_prefix(address)  
+  
+
+  def maybe_add_prefix(self, address):
+    """
+    Adds the prefix to the address
+
+    Parameters
+    ----------
+    address : str
+      the text address.
+
+    Returns
+    -------
+    address : str
+      the address with the prefix.
+    """
+    return self._add_prefix(address)
     
   
   def dict_digest(self, dct_data, return_str=True):
@@ -1235,6 +1253,52 @@ class BaseBlockEngine:
   def eth_account(self):
     return self.__eth_account
   
+  @staticmethod
+  def is_valid_evm_address(address: str) -> bool:
+    """
+    Check if the input string is a valid Ethereum (EVM) address using basic heuristics.
+
+    Parameters
+    ----------
+    address : str
+        The address string to verify.
+
+    Returns
+    -------
+    bool
+        True if `address` meets the basic criteria for an EVM address, False otherwise.
+    """
+    # Basic checks:
+    # A) Must start with '0x'
+    # B) Must be exactly 42 characters in total
+    # C) All remaining characters must be valid hexadecimal digits
+    if not address.startswith("0x"):
+      return False
+    if len(address) != 42:
+      return False
+    
+    hex_part = address[2:]
+    # Ensure all characters in the hex part are valid hex digits
+    return all(c in "0123456789abcdefABCDEF" for c in hex_part)
+  
+  @staticmethod
+  def is_valid_eth_address(address: str) -> bool:
+    """
+    Check if the input string is a valid Ethereum (EVM) address using basic heuristics.
+
+    Parameters
+    ----------
+    address : str
+        The address string to verify.
+
+    Returns
+    -------
+    bool
+        True if `address` meets the basic criteria for an EVM address, False otherwise.
+    """
+    return BaseBlockEngine.is_valid_evm_address(address)
+  
+  
   ### end Ethereum
 
 

naeural_client/cli/cli_commands.py

@@ -1,7 +1,8 @@
 from naeural_client.cli.nodes import (
   get_nodes, get_supervisors, 
-  restart_node, shutdown_node
+  restart_node, shutdown_node,
 )
+from naeural_client.cli.oracles import get_availability
 from naeural_client.utils.config import show_config, reset_config, show_address
 
 
@@ -17,12 +18,25 @@ CLI_COMMANDS = {
               "--online" : "Get only online nodes as seen by a active supervisor (flag)", # DONE
               "--peered": "Get only peered nodes - ie nodes that can be used by current client address (flag)",  # DONE
               "--supervisor" : "Use a specific supervisor node",
-              "--eth": "Use a specific node (flag)",              
+              "--eth" : "Use a specific node (flag)",
+              "--wide" : "Display all available information (flag)",
             }
         },
         "supervisors": {
             "func": get_supervisors, # DONE
         },
+        "avail": {    
+          "func": get_availability,
+          "params": {      
+            ### use "(flag)" at the end of the description to indicate a boolean flag
+            ### otherwise it will be treated as a str parameter      
+            "node": "The ETH address of the node to be checked via the oracle network.",
+            "--start": "The start epoch number to check the availability from",      
+            "--end": "The end epoch number to check the availability to",
+            "--json": "Enable full JSON oracle network output (flag)",
+            "--rounds": "The number of rounds to check the availability for testing purposes (default=1)",
+            }
+          }
     },
     "config": {
         "show": {

naeural_client/cli/nodes.py

@@ -11,6 +11,7 @@ def _get_netstats(
   supervisors_only=False,
   return_session=False,
   eth=False,
+  all_info=False
 ):
   t1 = time()
   from naeural_client import Session
@@ -19,6 +20,7 @@ def _get_netstats(
     online_only=online_only, allowed_only=allowed_only, supervisor=supervisor,
     supervisors_only=supervisors_only,
     eth=eth,
+    all_info=all_info, 
   )
   df = dct_info[SESSION_CT.NETSTATS_REPORT]
   supervisor = dct_info[SESSION_CT.NETSTATS_REPORTER]
@@ -31,6 +33,7 @@ def _get_netstats(
   return df, supervisor, super_alias, nr_supers, elapsed
 
 
+
 def get_nodes(args):
   """
   This function is used to get the information about the nodes and it will perform the following:
@@ -40,7 +43,8 @@ def get_nodes(args):
   3. Wait for the second net mon message via Session and show progress.  
   4. Get the active nodes union via Session and display the nodes marking those peered vs non-peered.
   """
-  supervisor_addr = args.supervisor  
+  supervisor_addr = args.supervisor
+  wide = args.wide
   if args.verbose:
     log_with_color(f"Getting nodes from supervisor <{supervisor_addr}>...", color='b')
 
@@ -50,6 +54,7 @@ def get_nodes(args):
     allowed_only=args.peered,
     supervisor=supervisor_addr,
     eth=args.eth,
+    all_info=wide,
   )
   df, supervisor, super_alias, nr_supers, elapsed = res
   if args.online:
@@ -150,4 +155,5 @@ def shutdown_node(args):
   node = args.node
   log_with_color(f"Attempting to shutdown node <{node}>", color='b')
   _send_command_to_node(args, COMMANDS.SHUTDOWN)
-  return
+  return
+

naeural_client/cli/oracles.py

@@ -0,0 +1,165 @@
+"""
+
+
+NOTE: if any of oracles return  data["result"]["oracle"]["manager"]["valid"] != True then
+  - ommit that oracle from the list of oracles shown
+  - display red warning containing the issue and the "certainty" 
+
+>nepctl get avail 0x693369781001bAC65F653856d0C00fA62129F407 --start 4 --end 6 --rounds 8
+
+Availability of node <0x693369781001bAC65F653856d0C00fA62129F407> from epoch 4 to epoch 6 on 8 rounds:
+  Oracle #1:
+    Address:   0xai_AleLPKqUHV-iPc-76-rUvDkRWW4dFMIGKW1xFVcy65nH
+    ETH Addr:  0xE486F0d594e9F26931fC10c29E6409AEBb7b5144
+    Alias:     nen-aid01
+    Responses: 3
+    Epochs:    [   4,    5,    6]
+    Avails:    [   3,  254,  127]
+    Cartainty: [0.99, 0.99, 0.99]
+  Oracle #2:
+    Address:   0xai_Amfnbt3N-qg2-qGtywZIPQBTVlAnoADVRmSAsdDhlQ-6
+    ETH Addr:  0x129a21A78EBBA79aE78B8f11d5B57102950c1Fc0
+    Alias:     nen-2
+    Responses: 2
+    Epochs:    [   4,    5,    6]
+    Avails:    [   3,  254,  127]
+    Cartainty: [0.99, 0.99, 0.99]
+  Oracle #3: [RED due to not data["result"]["oracle"]["manager"]["valid"]]
+    WARNING:   Oracle returned invalid data due to uncertainity
+    Address:   0xai_A-Bn9grkqH1GUMTZUqHNzpX5DA6PqducH9_JKAlBx6YL
+    ETH Addr:  0x93B04EF1152D81A0847C2272860a8a5C70280E14
+    Alias:     nen-aid02
+    Responses: 3
+    Epochs:    [   4,    5,    6]
+    Avails:    [   3,    0,  127]
+    Cartainty: [0.99, 0.41, 0.99]
+
+
+>nepctl get avail 0x693369781001bAC65F653856d0C00fA62129F407 --start 4 --end 6 --rounds 8
+
+Availability of node <0x693369781001bAC65F653856d0C00fA62129F407> from epoch 4 to epoch 6 on 8 rounds:
+  Oracle #1:
+    Address:   0xai_AleLPKqUHV-iPc-76-rUvDkRWW4dFMIGKW1xFVcy65nH
+    ETH Addr:  0xE486F0d594e9F26931fC10c29E6409AEBb7b5144
+    Alias:     nen-aid01
+    Responses: 3
+    Avails:    [3, 254, 127]
+  Oracle #2:
+    Address:   0xai_Amfnbt3N-qg2-qGtywZIPQBTVlAnoADVRmSAsdDhlQ-6
+    ETH Addr:  0x129a21A78EBBA79aE78B8f11d5B57102950c1Fc0
+    Alias:     nen-2
+    Responses: 3
+    Avails:    [3, 254, 127]
+  Oracle #3:
+    Address:   0xai_A-Bn9grkqH1GUMTZUqHNzpX5DA6PqducH9_JKAlBx6YL
+    ETH Addr:  0x93B04EF1152D81A0847C2272860a8a5C70280E14
+    Alias:     nen-aid02
+    Responses: 3
+    Avails:    [3, 254, 127]
+
+
+
+>nepctl get avail 0x693369781001bAC65F653856d0C00fA62129F407 --start 4 --end 6 --rounds 8
+[if same oracle returns different avail dump the two confligting json with RED and stop command]    
+
+>nepctl get avail 0x693369781001bAC65F653856d0C00fA62129F407 --start 4 --end 6 --full
+[just dump json]
+
+
+>nepctl get avail 0x693369781001bAC65F653856d0C00fA62129F407 --start 4 --end 6 
+Availability of node <0x693369781001bAC65F653856d0C00fA62129F407> from epoch 4 to epoch 6:
+Oracle address: 0xE486F0d594e9F26931fC10c29E6409AEBb7b5144
+Oracle alias:   nen-aid01
+Oracle report:
+  - Epoch #4: 127 ( 50%)
+  - Epoch #5: 254 (100%)
+  - Epoch #6:   3 (  1%)
+  
+>nepctl get avail 0x693369781001bAC65F653856d0C00fA62129F407 # assuming current epoch is 10
+Availability of node <0x693369781001bAC65F653856d0C00fA62129F407> from epoch 1 to epoch 9:
+Oracle address: 0xE486F0d594e9F26931fC10c29E6409AEBb7b5144
+Oracle alias:   nen-aid01
+Oracle report:
+  - Epoch #1: 127 ( 50%)
+  - Epoch #2: 127 ( 50%)
+  - Epoch #3: 127 ( 50%)
+  - Epoch #4: 127 ( 50%)
+  - Epoch #5: 254 (100%)
+  - Epoch #6:   3 (  1%)
+  - Epoch #7:  64 ( 25%)
+  - Epoch #8:  33 ( 13%)
+  - Epoch #9: 254 (100%)  
+  
+  
+TODO: (future)
+  - check ETH signature of the oracle data
+
+"""
+import requests
+
+from naeural_client.utils.config import log_with_color
+from naeural_client import Logger
+from naeural_client.bc import DefaultBlockEngine
+from naeural_client.utils.oracle_sync.multiple_requests import oracle_tester_init, handle_command_results
+
+"""
+TODOs:
+  - test NEPCTL command in CLI too
+  - check ETH signature of the oracle data
+"""
+
+
+def _check_response(data):
+  res = True
+  log = Logger("NEPCTL", base_folder=".", app_folder="_local_cache", silent=True)
+  bc = DefaultBlockEngine(name='test', log=log)
+  print(bc.address)
+  return res
+
+def get_availability(args):
+  """
+  This function is used to get the availability of the node.
+  
+  Parameters
+  ----------
+  args : argparse.Namespace
+      Arguments passed to the function.
+  """
+  
+  node = args.node
+  start = args.start or 1
+  end = args.end
+  full = args.json
+  rounds = args.rounds or 1
+  if str(rounds).isnumeric() and int(rounds) > 0:
+    rounds = int(rounds)
+  else:
+    log_with_color("`rounds` must be a positive integer. Setting rounds to 1.", color='r')
+    rounds = 1
+  # endif rounds
+
+  if isinstance(rounds, int) and rounds > 10:
+    log_with_color("Rounds exceed the maximum limit of 10. Setting rounds to 10.", color='r')
+    rounds = min(rounds, 10)
+
+  if full:
+    if rounds > 1:
+      log_with_color("Cannot generate full JSON oracle network output in 'rounds' mode.", color='r')
+      full = False
+  # endif full
+
+  tester = oracle_tester_init()
+  log_with_color("Checking {}availability of node <{}> from {} to {}.".format(
+    "(DEBUG MODE) " if rounds > 1 else "", node, start,
+    end if end else "last epoch"
+    ), color='b'
+  )
+  res = tester.execute_command(
+    node_eth_addr=node,
+    start=start,
+    end=end,
+    rounds=rounds,
+    debug=full
+  )
+  handle_command_results(res)
+  return

naeural_client/utils/oracle_sync/multiple_requests.py

@@ -0,0 +1,585 @@
+"""
+TODO: add signature check for the oracle data
+
+"""
+
+import requests
+import time
+import json
+from collections import defaultdict
+
+from naeural_client import Logger
+from naeural_client.bc import DefaultBlockEngine
+from naeural_client.utils.config import log_with_color
+
+
+class OracleTesterConstants:
+  BASE_URL = "https://naeural-oracle.ngrok.app"
+  TEST_ENDPOINT = "/node_epochs_range"
+  CURRENT_EPOCH_ENDPOINT = "/current_epoch"
+  ACTIVE_NODES_ENDPOINT = "/active_nodes_list"
+  DEFAULT_INTERVAL_SECONDS = 5
+  DEFAULT_COMMAND_INTERVAL_SECONDS = 1
+  MAX_REQUEST_ROUNDS = 10
+  FREQUENCY = "frequency"
+  ORACLE_DATA = "oracle_data"
+
+
+ct = OracleTesterConstants
+
+
+class OracleTester:
+  def __init__(
+      self, bce, log,
+      max_requests_rounds=ct.MAX_REQUEST_ROUNDS,
+      interval_seconds=ct.DEFAULT_INTERVAL_SECONDS
+  ):
+    self.bc = bce
+    self.log = log
+    self.BASE_URL = ct.BASE_URL
+    self.TEST_ENDPOINT = ct.TEST_ENDPOINT
+    self.CURRENT_EPOCH_ENDPOINT = ct.CURRENT_EPOCH_ENDPOINT
+    self.ACTIVE_NODES_ENDPOINT = ct.ACTIVE_NODES_ENDPOINT
+    self.request_rounds = 0
+    self.max_request_rounds = max_requests_rounds
+    self.interval_seconds = interval_seconds
+
+    self.node_addr_to_alias = {}
+    self.alias_to_node_addr = {}
+    self.node_eth_addr_to_alias = {}
+    self.alias_to_node_eth_addr = {}
+    self.node_addr_to_node_eth_addr = {}
+    self.node_eth_addr_to_node_addr = {}
+    return
+
+  """UTILS"""
+  if True:
+    def maybe_register_node(self, node_addr: str, eth_address: str, alias: str = None):
+      if node_addr is None:
+        return
+      self.node_addr_to_alias[node_addr] = alias
+      self.node_eth_addr_to_alias[eth_address] = alias
+
+      self.node_addr_to_node_eth_addr[node_addr] = eth_address
+      self.node_eth_addr_to_node_addr[eth_address] = node_addr
+
+      if alias is None:
+        return
+
+      self.alias_to_node_addr[alias] = node_addr
+      self.alias_to_node_eth_addr[alias] = eth_address
+      return
+
+    def make_request(self, request_url, request_kwargs=None, debug=False):
+      request_kwargs = request_kwargs or {}
+      try:
+        if debug:
+          self.P(f"Making request to {request_url} with kwargs: {request_kwargs}")
+        response = requests.get(request_url, params=request_kwargs)
+        response.raise_for_status()  # Raise an HTTPError if the status is not 2xx
+        return response.json()  # Assuming the response is JSON
+      except requests.RequestException as e:
+        self.P(f"Request failed: {e}")
+        return None
+
+    def done(self, rounds=None):
+      if rounds is not None:
+        return self.request_rounds >= rounds
+      return self.request_rounds >= self.max_request_rounds
+
+    def P(self, msg, **kwargs):
+      self.log.P(msg, **kwargs)
+      return
+
+    def frequency_dict_to_str(self, freq_dict):
+      return '\n'.join([
+        f"\t{self.node_addr_to_alias.get(node_addr)} ({node_addr}): {freq}"
+        for node_addr, freq in freq_dict.items()
+      ])
+  """END UTILS"""
+
+  """RESPONSE HANDLING"""
+  if True:
+    def compute_epochs_availability_and_certainty(self, result: dict):
+      """
+      Compute the availability and certainty for a given result extracted from the response.
+      Parameters
+      ----------
+      result : dict
+          The result extracted from the response.
+
+      Returns
+      -------
+      tuple
+          A tuple containing the availability and certainty values.
+      """
+      epoch_ids = result.get("epochs")
+      epoch_vals = result.get("epochs_vals")
+      dict_certainty = result.get("oracle", {}).get("manager", {}).get("certainty", {})
+      is_valid = result.get("oracle", {}).get("manager", {}).get("valid", False)
+
+      current_epochs, current_avails, current_cert = [], [], []
+      for epoch_id, epoch_val in zip(epoch_ids, epoch_vals):
+        current_epochs.append(epoch_id)
+        current_avails.append(epoch_val)
+        current_cert.append(dict_certainty.get(str(epoch_id), 0))
+      # endfor epochs
+      return current_epochs, current_avails, current_cert, is_valid
+
+    def handle_server_data(
+        self, oracle_stats_dict: dict,
+        sender: str, sender_eth_addr: str, sender_node_alias: str,
+        result: dict
+    ):
+      """
+      Handle the data received from the oracle server.
+
+      Parameters
+      ----------
+      oracle_stats_dict : dict
+          The dictionary containing the oracle data received so far.
+      sender : str
+          The address of the sender.
+      sender_eth_addr : str
+          The ETH address of the sender.
+      sender_node_alias : str
+          The alias of the sender.
+      result : dict
+          The result extracted from the response.
+      """
+      if sender not in oracle_stats_dict:
+        oracle_stats_dict[sender] = {
+          'addr': sender,
+          'eth_addr': sender_eth_addr,
+          'alias': sender_node_alias,
+          'errors': []
+        }
+      # endif first time for this sender
+      current_stats = oracle_stats_dict[sender]
+      current_epochs, current_avails, current_certs, is_valid = self.compute_epochs_availability_and_certainty(result)
+      stats_epochs = current_stats.get("epochs", None)
+      stats_avails = current_stats.get("avails", None)
+      stats_certs = current_stats.get("certs", None)
+      stats_is_valid = current_stats.get("is_valid", None)
+      mismatches = []
+      if stats_epochs is not None and current_epochs != stats_epochs:
+        mismatches.append(f"epochs: {current_epochs} != {stats_epochs}")
+      # endif check for mismatch
+      if stats_avails is not None and current_avails != stats_avails:
+        mismatches.append(f"avails: {current_avails} != {stats_avails}")
+      # endif check for mismatch
+      if stats_certs is not None and current_certs != stats_certs:
+        mismatches.append(f"certainty: {current_certs} != {stats_certs}")
+      # endif check for mismatch
+      if stats_is_valid is not None and is_valid != stats_is_valid:
+        mismatches.append(f"validity: {is_valid} != {stats_is_valid}")
+      # endif check for mismatch
+
+      if len(mismatches) > 0:
+        current_stats["errors"].append(f"Round {self.request_rounds}: {', '.join(mismatches)}")
+      else:
+        # Valid data received
+        if stats_epochs is None:
+          current_stats["epochs"] = current_epochs
+        if stats_avails is None:
+          current_stats["avails"] = current_avails
+        if stats_certs is None:
+          current_stats["certs"] = current_certs
+        if stats_is_valid is None:
+          current_stats["is_valid"] = is_valid
+      # endif valid data received
+      return
+
+    def add_to_stats(
+        self,
+        stats_dict: dict,
+        response: dict,
+        node_data: dict,
+        debug=False
+    ):
+      node_eth_addr = node_data["eth_address"]
+      node_addr = node_data.get("address")
+      node_alias = node_data.get("alias")
+      self.maybe_register_node(node_addr=node_addr, eth_address=node_eth_addr, alias=node_alias)
+      result = response.get("result")
+      if not result:
+        return
+      sender = result.get("EE_SENDER")
+      sender_eth_addr = result.get("EE_ETH_SENDER")
+      sender_node_alias = result.get("server_alias")
+      self.maybe_register_node(node_addr=sender, eth_address=sender_eth_addr, alias=sender_node_alias)
+      if node_eth_addr not in stats_dict:
+        stats_dict[node_eth_addr] = {
+          **node_data,
+          ct.FREQUENCY: {},
+          ct.ORACLE_DATA: {}
+        }
+      # endif first time for this node
+      stats_dict[node_eth_addr][ct.FREQUENCY][sender] = stats_dict[node_eth_addr][ct.FREQUENCY].get(sender, 0) + 1
+
+      self.handle_server_data(
+        oracle_stats_dict=stats_dict[node_eth_addr][ct.ORACLE_DATA],
+        sender=sender,
+        sender_eth_addr=sender_eth_addr,
+        sender_node_alias=sender_node_alias,
+        result=result
+      )
+
+      return stats_dict
+  """END RESPONSE HANDLING"""
+
+  def gather(self, nodes, request_kwargs=None, debug=False, rounds=None):
+    """
+    Gather data from the oracle server for the given nodes.
+
+    Parameters
+    ----------
+    nodes : list[dict] or list[str]
+        The list of nodes for which to gather data. Each node can be a dictionary containing the
+        address, eth_address, and alias of the node or a string containing the eth_address of the node.
+        Either way, the eth_address is required.
+    request_kwargs : dict
+        The request kwargs to be used for the request. Default None.
+    debug : bool
+        Whether to enable debug mode or not. If enabled the function will exit after one request round.
+
+    Returns
+    -------
+    tuple
+        A tuple containing the responses and the stats dictionary.
+    """
+    responses = []
+    request_kwargs = request_kwargs or {}
+    stats_dict = {}
+    self.request_rounds = 0
+    while not self.done(rounds):
+      try:
+        self.P(f'Starting request round {self.request_rounds + 1} for {len(nodes)} nodes...')
+        current_url = self.BASE_URL + self.TEST_ENDPOINT
+        # TODO: maybe shuffle the nodes list in order to avoid
+        #  the same order of requests in each round
+        #  relevant if the number of nodes is divisible by the number of oracles.
+        for node_data in nodes:
+          if isinstance(node_data, str):
+            node_data = {"eth_address": node_data}
+          # endif only eth address provided
+          eth_addr = node_data.get("eth_address", "N/A")
+          node_alias = node_data.get("alias", eth_addr)
+          node_addr = node_data.get("address", eth_addr)
+          self.P(f'\tRequesting data for {node_alias}...')
+          current_kwargs = {
+            "eth_node_addr": eth_addr,
+            **request_kwargs
+          }
+          response = self.make_request(current_url, request_kwargs=current_kwargs, debug=debug)
+          if response:
+            responses.append(response)
+            str_sender = response.get("node_addr")
+            self.P(f"Received response from {str_sender} with keys: {response.get('result').keys()}")
+            stats_dict = self.add_to_stats(
+              stats_dict=stats_dict,
+              response=response,
+              node_data=node_data,
+              debug=debug
+            )
+            if debug:
+              self.P(f'Full response: {response}')
+          else:
+            self.P(f"Request failed for {node_data['alias']}")
+        # endfor nodes
+      except Exception as e:
+        self.P(f"Request failed: {e}")
+      self.request_rounds += 1
+      if debug:
+        self.P(f'Debug mode was enabled. Exiting after one request round.')
+        break
+      time.sleep(self.interval_seconds)
+    # endwhile
+    self.P(f'Finished gathering data for {len(nodes)} nodes and {self.max_request_rounds}.')
+    return responses, stats_dict
+
+  def get_current_epoch(self):
+    epoch_url = self.BASE_URL + self.CURRENT_EPOCH_ENDPOINT
+    response = self.make_request(epoch_url)
+    if response:
+      return response.get("result", {}).get("current_epoch", 1)
+    return None
+
+  def get_active_nodes(self):
+    active_nodes_url = self.BASE_URL + self.ACTIVE_NODES_ENDPOINT
+    response = self.make_request(active_nodes_url)
+    result = []
+    if response:
+      nodes = response.get("result", {}).get("nodes", {})
+      for node_addr, node_data in nodes.items():
+        eth_addr = node_data.get("eth_addr", None)
+        alias = node_data.get("alias", None)
+        if eth_addr is not None:
+          result.append({
+            "address": node_addr,
+            "eth_address": eth_addr,
+            "alias": alias
+          })
+        # endif eth address is not None
+      # endfor each node
+    # endif response
+    return result
+
+  """LOGGING"""
+  if True:
+    def check_data(self, oracle_data: dict, node_eth_addr: str):
+      valid, msg = True, ""
+      if oracle_data is None:
+        # If oracle_data is None, either the address was invalid or the servers are down.
+        # Will attempt request for current epoch to check the servers status.
+        current_epoch = self.get_current_epoch()
+        valid = False
+        if current_epoch is None:
+          msg = f"Failed to get the current epoch. No oracle available. Please try again later."
+        else:
+          msg = f"No data available for {node_eth_addr}. Please check the address or contact support."
+        # endif servers available
+      # endif oracle_data is None
+      return valid, msg
+
+    def get_availability_str_for_one_round(
+        self, node_eth_addr: str, start: int, end: int, stats_dict: dict
+    ):
+      oracle_data = stats_dict.get(node_eth_addr, {}).get(ct.ORACLE_DATA, None)
+      valid, msg = self.check_data(oracle_data, node_eth_addr)
+      if not valid:
+        return msg
+
+      msg = f'Availability for <{node_eth_addr}> from epoch {start} to epoch {end}:\n'      
+      sender_addr = list(oracle_data.keys())[0]
+      sender_data = oracle_data[sender_addr]
+      oracle_addr = sender_data.get("addr", None)
+      oracle_addr_eth = sender_data.get("eth_addr", None)
+      oracle_alias = sender_data.get("alias", None)
+      msg += f'  Oracle address:  {oracle_addr}\n'
+      msg += f'  Oracle ETH addr: {oracle_addr_eth}\n'
+      msg += f'  Oracle alias:    {oracle_alias}\n'
+      msg += f'  Oracle responses:\n'
+      epochs = sender_data.get("epochs", None)
+      avails = sender_data.get("avails", None)
+      certs = sender_data.get("certs", None)
+      if epochs is None or avails is None or certs is None:
+        msg = f"No data available for {node_eth_addr}. Please check the address or contact support."
+      else:
+        for epoch, avail, cert in zip(epochs, avails, certs):
+          msg += f"   - Epoch {f'#{epoch}':>4}: {avail:3} ({cert * 100:5.1f}%)\n"
+      # endif data available
+      return msg
+
+    def get_availability_str_for_multiple_rounds(
+        self,
+        node_eth_addr: str, start: int, end: int, stats_dict: dict, rounds: int
+    ):
+      oracle_data = stats_dict.get(node_eth_addr, {}).get(ct.ORACLE_DATA, None)
+      valid, msg = self.check_data(oracle_data, node_eth_addr)
+      if not valid:
+        return [msg]
+      msg_list = [f'Availability for <{node_eth_addr}> from epoch {start} to epoch {end} on {rounds} rounds:\n']
+      frequencies = stats_dict.get(node_eth_addr, {}).get(ct.FREQUENCY, {})
+      it = 0
+      for sender, sender_data in oracle_data.items():
+        curr_msg = f'\tOracle #{it + 1}:\n'
+        is_valid = sender_data.get("is_valid", False)
+        if len(sender_data["errors"]) > 0:
+          is_valid = False
+          curr_msg += f'\t\t Error!! Same oracle returned different data in different rounds:\n'
+          for error in sender_data["errors"]:
+            curr_msg += f'\t\t\t {error}\n'
+          # endfor errors
+        else:
+          # No errors
+          if not is_valid:
+            curr_msg += '\t\t WARNING:   Oracle returned invalid data due to uncertainity\n'
+          # endif uncertainty
+        # endif errors
+        color = None if is_valid else 'r'
+        str_epochs = '  '.join([f'{epoch:4}' for epoch in sender_data["epochs"]])
+        str_avails = '  '.join([f'{avail:4}' for avail in sender_data["avails"]])
+        str_certs  = '  '.join([f'{cert:4.2f}' for cert in sender_data["certs"]])
+        curr_msg += f'\t\t Address:   {sender_data["addr"]}\n'
+        curr_msg += f'\t\t ETH Addr:  {sender_data["eth_addr"]}\n'
+        curr_msg += f'\t\t Alias:     {sender_data["alias"]}\n'
+        curr_msg += f'\t\t Responses: {frequencies.get(sender, 0)}\n'
+        curr_msg += f'\t\t Epochs:    {str_epochs}\n'
+        curr_msg += f'\t\t Avails:    {str_avails}\n'
+        curr_msg += f'\t\t Certainty: {str_certs}\n'
+        msg_list.append((curr_msg, color))
+        it += 1
+      # endfor oracles
+      return msg_list
+  """END LOGGING"""
+
+  def execute_command(
+      self, node_eth_addr: str, start: int = 1,
+      end: int = None, debug: bool = False,
+      rounds: int = 1
+  ):
+    """
+    Execute the command to get the availability of the node on a given epochs interval.
+    This can also be used to get the JSON response from the server(with the use of debug=True).
+    In case of debug mode, the rounds parameter is ignored(will default to 1).
+    In case of multiple rounds, a delay of interval_seconds will be added between each request.
+    Parameters
+    ----------
+    node_eth_addr : str
+        The ETH address of the node for which the command will be executed.
+    start : int
+        The starting epoch for the request.
+    end : int
+        The ending epoch for the request. If None, the current epoch will be used.
+    debug : bool
+        Whether to enable debug mode or not. If enabled the rounds parameter is ignored and the
+        function will return the JSON response from the server.
+    rounds : int
+        The number of rounds to be executed. Default 1.
+
+    Returns
+    -------
+    dict:
+        The JSON response from the server if in debug mode.
+        The stats summary if not in debug mode.
+    """
+    rounds = min(rounds, self.max_request_rounds)
+    if end is None:
+      current_epoch = self.get_current_epoch()
+      if current_epoch is None:
+        self.P(f"Failed to get the current epoch. No oracle available. Please try again later.", show=True)
+        return
+      self.P(f'No end epoch provided. Using current epoch: {current_epoch}', show=True)
+      end = self.get_current_epoch() - 1
+    # endif end is None
+    request_kwargs = {
+      "start_epoch": start,
+      "end_epoch": end
+    }
+    responses, stats = self.gather(
+      nodes=[node_eth_addr],
+      request_kwargs=request_kwargs,
+      rounds=1 if debug else rounds,
+    )
+    if debug:
+      return responses[0]
+    if rounds > 1:
+      return self.get_availability_str_for_multiple_rounds(
+        node_eth_addr=node_eth_addr, start=start, end=end, stats_dict=stats, rounds=rounds
+      )
+
+    return self.get_availability_str_for_one_round(
+      node_eth_addr=node_eth_addr, start=start, end=end, stats_dict=stats
+    )
+
+# endclass OracleTester
+
+def handle_command_results(res):
+  if isinstance(res, dict):
+    log_with_color(json.dumps(res, indent=2), color='w')
+  elif isinstance(res, list):
+    for msg_data in res:
+      if isinstance(msg_data, tuple):
+        log_with_color(msg_data[0], color=msg_data[1])
+      else:
+        log_with_color(msg_data, color='w')
+    # endfor each message
+  else:
+    log_with_color(res, color='w')
+  return
+
+def oracle_tester_init(silent=True, **kwargs):
+  log = Logger("R1CTL", base_folder=".", app_folder="_local_cache", silent=silent)
+  bc = DefaultBlockEngine(name='R1CTL', log=log)
+  tester = OracleTester(
+    bce=bc,
+    log=log,
+    **kwargs
+  )
+  return tester
+
+def test_commands():
+  tester = oracle_tester_init()
+  start = 78
+  end = 85
+  node_eth_addr = "<node_eth_address>"
+
+  # Single round
+  tester.P(f'Test single round: Epochs {start} to {end}', show=True)
+  res = tester.execute_command(node_eth_addr=node_eth_addr, start=start, end=end)
+  handle_command_results(res)
+
+  # Multiple rounds
+  tester.P(f'Test multiple rounds: Epochs {start} to {end}', show=True)
+  res = tester.execute_command(node_eth_addr=node_eth_addr, start=start, end=end, rounds=5)
+  handle_command_results(res)
+
+  # Debug mode
+  tester.P(f'Test debug mode: Epochs {start} to {end}', show=True)
+  res = tester.execute_command(node_eth_addr=node_eth_addr, start=80, end=85, debug=True)
+  handle_command_results(res)
+  return
+
+def oracle_test(N=10):
+  import random
+
+  random.seed(42)
+
+  tester = oracle_tester_init(
+    silent=True,
+    interval_seconds=0.2,
+  )
+  current_epoch = tester.get_current_epoch()
+  if current_epoch is None:
+    current_epoch = 96
+  nodes = tester.get_active_nodes()
+  rounds = 5
+  max_epochs = 10
+  max_nodes = 5
+
+  for i in range(N):
+    node_list = random.sample(nodes, min(len(nodes), max_nodes))
+    start = random.randint(1, current_epoch - 1)
+    end = random.randint(start, current_epoch - 1)
+    end = min(end, start + max_epochs - 1)
+
+    tester.P(f'Test {i + 1}/{N}: Epochs {start} to {end} with {rounds} rounds:', show=True)
+    res = tester.gather(
+      nodes=node_list,
+      request_kwargs={
+        "start_epoch": start,
+        "end_epoch": end
+      },
+      rounds=rounds
+    )
+
+    for node_data in node_list:
+      msg_list = tester.get_availability_str_for_multiple_rounds(
+        node_eth_addr=node_data['eth_address'], start=start, end=end, stats_dict=res[1], rounds=rounds
+      )
+      for msg_data in msg_list:
+        if isinstance(msg_data, tuple):
+          tester.P(msg_data[0], color=msg_data[1], show=True)
+        else:
+          tester.P(msg_data, show=True)
+      # endfor each message
+    # endfor each node
+    tester.P(f'Finished test {i + 1}/{N}', show=True)
+  # endfor each test
+  return
+
+# Main loop
+def main():
+  TEST_COMMANDS = False
+  TEST_ORACLE = True
+  if TEST_COMMANDS:
+    test_commands()
+
+  if TEST_ORACLE:
+    oracle_test(5)
+  return
+
+
+if __name__ == "__main__":
+  main()

{naeural_client-2.6.24.dist-info → naeural_client-2.6.26.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: naeural_client
-Version: 2.6.24
+Version: 2.6.26
 Summary: `naeural_client` is the Python SDK required for client app development for the Naeural Edge Protocol Edge Protocol framework
 Project-URL: Homepage, https://github.com/NaeuralEdgeProtocol/naeural_client
 Project-URL: Bug Tracker, https://github.com/NaeuralEdgeProtocol/naeural_client/issues
@@ -38,6 +38,12 @@ Key functionalities of the Ratio1 SDK include:
 
 Unlike the Ratio1 Core Packages, which are intended solely for protocol and ecosystem enhancements and are not meant for standalone installation, the Ratio1 SDK is designed for both client-side development and sending workloads to Ratio1 Edge Nodes, making it an indispensable tool for developers within the ecosystem.
 
+## The `nepctl` CLI Tool
+
+Our SDK has a CLI tool called `nepctl` that allows you to interact with the Ratio1 network. You can use it to query nodes, configure the client, and manage nodes directly from the terminal. The `nepctl` tool is a powerful utility that simplifies network interactions and provides a seamless experience for developers.
+
+For more information on the `nepctl` CLI tool, please refer to the [nepctl](nepctl.md) documentation.
+
 ## Dependencies
 
 The Ratio1 SDK relies on several key packages to function effectively. These dependencies are automatically managed when installing the SDK via pip:

{naeural_client-2.6.24.dist-info → naeural_client-2.6.26.dist-info}/RECORD

@@ -1,10 +1,10 @@
 naeural_client/__init__.py,sha256=YimqgDbjLuywsf8zCWE0EaUXH4MBUrqLxt0TDV558hQ,632
-naeural_client/_ver.py,sha256=sWoUittCitgXSrjKA9XzssfGD3VSmC7d_xj1j4vyhww,331
+naeural_client/_ver.py,sha256=v41SsIkuU8mwgkOit-MvKm8l1U2wH1sGEPmEk-6Qf6Q,331
 naeural_client/base_decentra_object.py,sha256=C4iwZTkhKNBS4VHlJs5DfElRYLo4Q9l1V1DNVSk1fyQ,4412
 naeural_client/plugins_manager_mixin.py,sha256=X1JdGLDz0gN1rPnTN_5mJXR8JmqoBFQISJXmPR9yvCo,11106
 naeural_client/base/__init__.py,sha256=hACh83_cIv7-PwYMM3bQm2IBmNqiHw-3PAfDfAEKz9A,259
 naeural_client/base/distributed_custom_code_presets.py,sha256=cvz5R88P6Z5V61Ce1vHVVh8bOkgXd6gve_vdESDNAsg,2544
-naeural_client/base/generic_session.py,sha256=IrZqKNGrlyuNnncKzJkCzvreSFwRgalMH-LpLHZ-54Q,104513
+naeural_client/base/generic_session.py,sha256=joF01ZoIt6QCSg7hDkg5M8ZCmKubpbQVh-plqi6GA9E,105079
 naeural_client/base/instance.py,sha256=kcZJmjLBtx8Bjj_ysIOx1JmLA-qSpG7E28j5rq6IYus,20444
 naeural_client/base/pipeline.py,sha256=b4uNHrEIOlAtw4PGUx20dxwBhDck5__SrVXaHcSi8ZA,58251
 naeural_client/base/plugin_template.py,sha256=qGaXByd_JZFpjvH9GXNbT7KaitRxIJB6-1IhbKrZjq4,138123
@@ -14,15 +14,16 @@ naeural_client/base/webapp_pipeline.py,sha256=QmPLVmhP0CPdi0YuvbZEH4APYz2Amtw3gy
 naeural_client/base/payload/__init__.py,sha256=y8fBI8tG2ObNfaXFWjyWZXwu878FRYj_I8GIbHT4GKE,29
 naeural_client/base/payload/payload.py,sha256=x-au7l67Z_vfn_4R2C_pjZCaFuUVXHngJiGOfIAYVdE,2690
 naeural_client/bc/__init__.py,sha256=FQj23D1PrY06NUOARiKQi4cdj0-VxnoYgYDEht8lpr8,158
-naeural_client/bc/base.py,sha256=hiKibexlNpZWYfFjKH-Jdwe79p4rM6j4e0M3AYPZCNs,36169
+naeural_client/bc/base.py,sha256=NafeKetxDoG86-gNls3FPN1M09nzRUP9unCUzEcXlrk,37706
 naeural_client/bc/chain.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 naeural_client/bc/ec.py,sha256=qI8l7YqiS4MNftlx-tF7IZUswrSeQc7KMn5OZ0fEaJs,23370
 naeural_client/certs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 naeural_client/certs/r9092118.ala.eu-central-1.emqxsl.com.crt,sha256=y-6io0tseyx9-a4Pmde1z1gPULtJNSYUpG_YFkYaMKU,1337
 naeural_client/cli/README.md,sha256=WPdI_EjzAbUW1aPyj1sSR8rLydcJKZtoiaEtklQrjHo,74
 naeural_client/cli/cli.py,sha256=c0ZavVwArQEGv8tueTnz3aGKTuUe6Sqmm5oTUFUVIUE,3816
-naeural_client/cli/cli_commands.py,sha256=rORdskjcuWkoJ0VJH8Ednfp-b2_SX-xZ6B-cO6KLAPQ,2012
-naeural_client/cli/nodes.py,sha256=SYWe58F7ygxr2EpEJjh6b_VDvEEEnxwiw7SmAqQggn8,4829
+naeural_client/cli/cli_commands.py,sha256=Gfims_TqaBi2QWM-6yxd_B_CETF8mmt7oEDPTg59lcI,2821
+naeural_client/cli/nodes.py,sha256=QXSniYy3Phr6buoVV-HUDRYuF5YQDUgf6nT6EzDyMJw,4909
+naeural_client/cli/oracles.py,sha256=g8h8kl3Mu6gU7JCs4a6WSDpvuVDGJgTHJbYJy7Iriw0,5210
 naeural_client/code_cheker/__init__.py,sha256=pwkdeZGVL16ZA4Qf2mRahEhoOvKhL7FyuQbMFLr1E5M,33
 naeural_client/code_cheker/base.py,sha256=lT5DRIFO5rqzsMNCmdMRfkAeevmezozehyfgmhnKpuI,19074
 naeural_client/code_cheker/checker.py,sha256=QWupeM7ToancVIq1tRUxRNUrI8B5l5eoY0kDU4-O5aE,7365
@@ -81,8 +82,9 @@ naeural_client/utils/__init__.py,sha256=mAnke3-MeRzz3nhQvhuHqLnpaaCSmDxicd7Ck9uw
 naeural_client/utils/comm_utils.py,sha256=4cS9llRr_pK_3rNgDcRMCQwYPO0kcNU7AdWy_LtMyCY,1072
 naeural_client/utils/config.py,sha256=v7xHikr6Z5Sbvf3opYeMhYzGWD2pe0HlRwa-aGJzUh8,6323
 naeural_client/utils/dotenv.py,sha256=_AgSo35n7EnQv5yDyu7C7i0kHragLJoCGydHjvOkrYY,2008
-naeural_client-2.6.24.dist-info/METADATA,sha256=-GGBISabxTk3Z4p7zbfqAlYRm4K7eAmqa-9q5tl7q6U,11906
-naeural_client-2.6.24.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-naeural_client-2.6.24.dist-info/entry_points.txt,sha256=PNdyotDaQBAslZREx5luVyj0kqpQnwNACwkFNTPIHU4,55
-naeural_client-2.6.24.dist-info/licenses/LICENSE,sha256=cvOsJVslde4oIaTCadabXnPqZmzcBO2f2zwXZRmJEbE,11311
-naeural_client-2.6.24.dist-info/RECORD,,
+naeural_client/utils/oracle_sync/multiple_requests.py,sha256=GLzROGZ0gI4d1PVWgW_JBUYZjEL4LqZvHvwelxDiPW4,20892
+naeural_client-2.6.26.dist-info/METADATA,sha256=jvfB6kdLKoCkEHGyjhFJnTfmrH9Ya8J4fu4Z68ldclE,12354
+naeural_client-2.6.26.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+naeural_client-2.6.26.dist-info/entry_points.txt,sha256=PNdyotDaQBAslZREx5luVyj0kqpQnwNACwkFNTPIHU4,55
+naeural_client-2.6.26.dist-info/licenses/LICENSE,sha256=cvOsJVslde4oIaTCadabXnPqZmzcBO2f2zwXZRmJEbE,11311
+naeural_client-2.6.26.dist-info/RECORD,,