naeural-client 2.6.24__tar.gz → 2.6.26__tar.gz

{naeural_client-2.6.24 → naeural_client-2.6.26}/PKG-INFO

@@ -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 → naeural_client-2.6.26}/README.md

@@ -15,6 +15,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 → naeural_client-2.6.26}/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-2.6.24 → naeural_client-2.6.26}/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-2.6.24 → naeural_client-2.6.26}/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-2.6.24 → naeural_client-2.6.26}/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-2.6.24 → naeural_client-2.6.26}/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-2.6.26/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