naeural-client 2.0.3__tar.gz → 2.1.0__tar.gz

{naeural_client-2.0.3 → naeural_client-2.1.0}/PKG-INFO

@@ -1,11 +1,10 @@
 Metadata-Version: 2.3
 Name: naeural_client
-Version: 2.0.3
+Version: 2.1.0
 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/Naeural Edge ProtocolEdgeProtocol/naeural_client
 Project-URL: Bug Tracker, https://github.com/Naeural Edge ProtocolEdgeProtocol/naeural_client/issues
 Author-email: Stefan Saraev <saraevstefan@gmail.com>, Andrei Ionut Damian <andrei.damian@me.com>, Cristan Bleotiu <cristibleotiu@gmail.com>
-License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3

{naeural_client-2.0.3 → naeural_client-2.1.0}/__init__.py

@@ -9,3 +9,6 @@ from .naeural_client import load_dotenv
 from .naeural_client import __version__
 from .naeural_client import BaseDecentrAIObject, _PluginsManagerMixin, Logger
 from .naeural_client import BaseCodeChecker
+from .naeural_client import PLUGIN_SIGNATURES
+from .naeural_client import PLUGIN_TYPES
+

{naeural_client-2.0.3 → naeural_client-2.1.0}/naeural_client/__init__.py

@@ -11,3 +11,5 @@ from .base_decentra_object import BaseDecentrAIObject
 from .plugins_manager_mixin import _PluginsManagerMixin
 from .logging import Logger
 from .code_cheker import BaseCodeChecker
+from .const import PLUGIN_SIGNATURES
+from .default.instance import PLUGIN_TYPES

{naeural_client-2.0.3 → naeural_client-2.1.0}/naeural_client/_ver.py

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

{naeural_client-2.0.3 → naeural_client-2.1.0}/naeural_client/base/generic_session.py

@@ -9,7 +9,7 @@ from time import time as tm
 
 from ..base_decentra_object import BaseDecentrAIObject
 from ..bc import DefaultBlockEngine
-from ..const import COMMANDS, ENVIRONMENT, HB, PAYLOAD_DATA, STATUS_TYPE
+from ..const import COMMANDS, ENVIRONMENT, HB, PAYLOAD_DATA, STATUS_TYPE, PLUGIN_SIGNATURES
 from ..const import comms as comm_ct
 from ..io_formatter import IOFormatterWrapper
 from ..logging import Logger
@@ -1396,7 +1396,7 @@ class GenericSession(BaseDecentrAIObject):
     def create_or_attach_to_pipeline(self, *,
                                      node,
                                      name,
-                                     data_source,
+                                     data_source="Void",
                                      config={},
                                      plugins=[],
                                      on_data=None,
@@ -1410,15 +1410,21 @@ class GenericSession(BaseDecentrAIObject):
       ----------
       node : str
           Address or Name of the Naeural Edge Protocol edge node that will handle this pipeline.
+          
       name : str
           Name of the pipeline. This is good to be kept unique, as it allows multiple parties to overwrite each others configurations.
+          
       data_source : str
           This is the name of the DCT plugin, which resembles the desired functionality of the acquisition.
+          Defaults to "Void" - no actual data acquisition.
+          
       config : dict, optional
           This is the dictionary that contains the configuration of the acquisition source, by default {}
+          
       plugins : list
           List of dictionaries which contain the configurations of each plugin instance that is desired to run on the box. 
           Defaults to []. Should be left [], and instances should be created with the api.
+          
       on_data : Callable[[Pipeline, str, str, dict], None], optional
           Callback that handles messages received from any plugin instance. 
           As arguments, it has a reference to this Pipeline object, the signature and the instance of the plugin
@@ -1426,15 +1432,18 @@ class GenericSession(BaseDecentrAIObject):
           This callback acts as a default payload processor and will be called even if for a given instance
           the user has defined a specific callback.
           Defaults to None.
+          
       on_notification : Callable[[Pipeline, dict], None], optional
           Callback that handles notifications received from any plugin instance. 
           As arguments, it has a reference to this Pipeline object, along with the payload itself. 
           This callback acts as a default payload processor and will be called even if for a given instance
           the user has defined a specific callback.
           Defaults to None.
+          
       max_wait_time : int, optional
           The maximum time to busy-wait, allowing the Session object to listen to node heartbeats
           and to check if the desired node is online in the network, by default 0.
+          
       **kwargs :
           The user can provide the configuration of the acquisition source directly as kwargs.
 
@@ -1651,15 +1660,39 @@ class GenericSession(BaseDecentrAIObject):
       *,
       node,
       name,
-      signature="CUSTOM_CODE_FASTAPI_01",
+      signature=PLUGIN_SIGNATURES.CUSTOM_WEB_APP_01,
       endpoints=None,
       use_ngrok=True,
       **kwargs
     ):
+      """
+      Create a new web app on a node.
+      
+      Parameters
+      ----------
+      
+      node : str
+          Address or Name of the Naeural Edge Protocol edge node that will handle this web app.
+          
+      name : str
+          Name of the web app.
+          
+      signature : str, optional
+          The signature of the plugin that will be used. Defaults to PLUGIN_SIGNATURES.CUSTOM_WEB_APP_01.
+          
+      endpoints : list[dict], optional
+          A list of dictionaries defining the endpoint configuration. Defaults to None.
+          
+      use_ngrok : bool, optional
+          If True, will use ngrok to expose the web app. Defaults to True.
+          
+      
+      """
 
       pipeline: Pipeline = self.create_pipeline(
         node=node,
         name=name,
+        # default TYPE is "Void"
       )
 
       instance = pipeline.create_plugin_instance(
@@ -1677,6 +1710,43 @@ class GenericSession(BaseDecentrAIObject):
       # end if we have endpoints defined in the call
 
       return pipeline, instance
+    
+
+    def create_telegram_simple_bot(
+      self,
+      *,
+      node,
+      name,
+      signature=PLUGIN_SIGNATURES.CUSTOM_WEB_APP_01,
+      message_handler=None,
+      telegram_bot_token=None,
+      telegram_bot_token_env_key=ENVIRONMENT.TELEGRAM_BOT_TOKEN_ENV_KEY,
+      **kwargs
+    ):
+      
+      if telegram_bot_token is None:
+        telegram_bot_token = os.getenv(telegram_bot_token_env_key)
+        if telegram_bot_token is None:
+          message = f"Warning! No Telegram bot token provided as via env {ENVIRONMENT.TELEGRAM_BOT_TOKEN_ENV_KEY} or explicitly as `telegram_bot_token` param."
+          raise ValueError(message)
+      
+      b64code = self._get_base64_code(message_handler)
+
+      pipeline: Pipeline = self.create_pipeline(
+        node=node,
+        name=name,
+        # default TYPE is "Void"
+      )
+
+      instance = pipeline.create_plugin_instance(
+        signature=signature,
+        instance_id=self.log.get_unique_id(),
+        telegram_bot_token=telegram_bot_token,
+        message_handler=b64code,
+        **kwargs
+      )      
+      return pipeline, instance
+    
 
     def broadcast_instance_command_and_wait_for_response_payload(
       self,

{naeural_client-2.0.3 → naeural_client-2.1.0}/naeural_client/const/__init__.py

@@ -7,3 +7,4 @@ from .payload import STATUS_TYPE, PAYLOAD_DATA, COMMANDS, NOTIFICATION_CODES
 from .base import CONFIG_STREAM, BIZ_PLUGIN_DATA, PLUGIN_INFO
 from . import heartbeat as HB
 from .environment import ENVIRONMENT
+from .apps import PLUGIN_SIGNATURES

naeural_client-2.1.0/naeural_client/const/apps.py

@@ -0,0 +1,11 @@
+class PLUGIN_SIGNATURES:
+  """
+  This class is used to store the plugin signatures for the different plugins.
+  It is complementary to the PLUGIN_TYPES class.
+  """
+  NET_MON_01 = 'NET_MON_01'
+  VIEW_SCENE_01 = 'VIEW_SCENE_01'
+  CUSTOM_WEB_APP_01 = 'CUSTOM_CODE_FASTAPI_01'
+  CHAIN_DIST_CUSTOM_JOB_01 = 'PROCESS_REAL_TIME_COLLECTED_DATA_CUSTOM_EXEC_CHAIN_DIST'
+  BASIC_TELEGRAM_BOT_01 = 'BASIC_TELEGRAM_BOT_01'  
+  # INSERT_NEW_PLUGIN_HERE

{naeural_client-2.0.3 → naeural_client-2.1.0}/naeural_client/const/environment.py

@@ -28,3 +28,5 @@ class ENVIRONMENT:
 
   EE_SECURED = 'EE_SECURED'
   AIXP_SECURED = 'AIXP_SECURED'
+  
+  TELEGRAM_BOT_TOKEN_ENV_KEY = 'TELEGRAM_BOT_TOKEN'

naeural_client-2.1.0/naeural_client/default/instance/__init__.py

@@ -0,0 +1,16 @@
+from .net_mon_01_plugin import NetMon01
+from .view_scene_01_plugin import ViewScene01
+from .custom_web_app_01_plugin import CustomWebApp01
+from .chain_dist_custom_job_01_plugin import ChainDistCustomJob01
+from .basic_telegram_bot_01_plugin import BasicTelegramBot01
+
+
+class PLUGIN_TYPES:
+  """
+  The plugin types that are available in the default instance
+  """
+  NET_MON_01 = NetMon01
+  VIEW_SCENE_01 = ViewScene01
+  CUSTOM_WEB_APP_01 = CustomWebApp01
+  CHAIN_DIST_CUSTOM_JOB_01 = ChainDistCustomJob01
+  BASIC_TELEGRAM_BOT_01 = BasicTelegramBot01

naeural_client-2.1.0/naeural_client/default/instance/basic_telegram_bot_01_plugin.py

@@ -0,0 +1,5 @@
+from ...base import Instance
+from ...const import PLUGIN_SIGNATURES
+
+class BasicTelegramBot01(Instance):
+  signature = PLUGIN_SIGNATURES.BASIC_TELEGRAM_BOT_01

{naeural_client-2.0.3 → naeural_client-2.1.0}/naeural_client/default/instance/chain_dist_custom_job_01_plugin.py

@@ -1,8 +1,9 @@
 from ...base import Instance
+from ...const import PLUGIN_SIGNATURES
 
 
 class ChainDistCustomJob01(Instance):
-  signature = "PROCESS_REAL_TIME_COLLECTED_DATA_CUSTOM_EXEC_CHAIN_DIST"
+  signature = PLUGIN_SIGNATURES.CHAIN_DIST_CUSTOM_JOB_01
 
   def add_custom_code_callbacks(
       self,

{naeural_client-2.0.3 → naeural_client-2.1.0}/naeural_client/default/instance/custom_web_app_01_plugin.py

@@ -1,8 +1,8 @@
 from ...base import Instance, Pipeline
-
+from ...const import PLUGIN_SIGNATURES
 
 class CustomWebApp01(Instance):
-  signature = "CUSTOM_CODE_FASTAPI_01"
+  signature = PLUGIN_SIGNATURES.CUSTOM_WEB_APP_01
 
   def get_proposed_endpoints(self):
     from copy import deepcopy

{naeural_client-2.0.3 → naeural_client-2.1.0}/naeural_client/default/instance/net_mon_01_plugin.py

@@ -1,8 +1,8 @@
 from ...base import Instance
-
+from ...const import PLUGIN_SIGNATURES
 
 class NetMon01(Instance):
-  signature = "NET_MON_01"
+  signature = PLUGIN_SIGNATURES.NET_MON_01
 
   def get_node_history(self, node_id=None, node_addr=None, time_window_hours=1, steps=20):
     """

{naeural_client-2.0.3 → naeural_client-2.1.0}/naeural_client/default/instance/view_scene_01_plugin.py

@@ -1,8 +1,8 @@
 from ...base import Instance
-
+from ...const import PLUGIN_SIGNATURES
 
 class ViewScene01(Instance):
-  signature = "VIEW_SCENE_01"
+  signature = PLUGIN_SIGNATURES.VIEW_SCENE_01
 
   def get_last_witness(self, response_params_key="COMMAND_PARAMS"):
     """

{naeural_client-2.0.3 → naeural_client-2.1.0}/naeural_client/logging/base_logger.py

@@ -180,11 +180,12 @@ class BaseLogger(object):
     if lib_ver == "":
       lib_ver = __VER__
     ver = "v{}".format(lib_ver) if lib_ver != "" else ""
-    self.verbose_log(
-      "SDK [{} {}] initialized on machine [{}][{}].".format(
-        self.__lib__, ver, self.MACHINE_NAME, self.get_processor_platform(),
+    self.P(
+      "NSDK {} initialized on [{}][{}].".format(
+        ver, self.MACHINE_NAME, self.get_processor_platform(),
       ),
-      color='green'
+      color='green',
+      boxed=True,
     )
     self.verbose_log("  Timezone: {}.".format(self.timezone),color='green')
 

{naeural_client-2.0.3 → naeural_client-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "naeural_client"
-version = "2.0.3"
+version = "2.1.0"
 authors = [
   { name="Stefan Saraev", email="saraevstefan@gmail.com" },
   { name="Andrei Ionut Damian", email="andrei.damian@me.com" },

naeural_client-2.1.0/tutorials/ex01_part1_connect.py

@@ -0,0 +1,61 @@
+"""
+This is a simple example of how to use the naeural_client SDK.
+
+In this example, we connect to the network, listen for heartbeats from 
+  Naeural Edge Protocol edge nodes and print the CPU of each node.
+"""
+import json
+
+from naeural_client import Session, Payload
+
+
+class MessageHandler:  
+  def shorten_address(self, address):
+    """
+    This method is used to shorten the address of the edge node.
+    """
+    return address[:8] + "..." + address[-6:]
+  
+  def on_heartbeat(self, session: Session, node_addr: str, heartbeat: dict):
+    """
+    This method is called when a heartbeat is received from an edge node.
+    
+    Parameters
+    ----------
+    session : Session
+        The session object that received the heartbeat.
+        
+    node_addr : str
+        The address of the edge node that sent the heartbeat.
+        
+    heartbeat : dict
+        The heartbeat received from the edge node.        
+    """
+    session.P("{} ({}) has a {}".format(
+      heartbeat['EE_ID'], 
+      self.shorten_address(node_addr), 
+      heartbeat["CPU"])
+    )
+    return
+
+
+
+if __name__ == '__main__':
+  # create a naive message handler   
+  filterer = MessageHandler()
+  
+  # create a session
+  # the network credentials are read from the .env file automatically
+  session = Session(
+      on_heartbeat=filterer.on_heartbeat,
+  )
+
+
+  # Observation:
+  #   next code is not mandatory - it is used to keep the session open and cleanup the resources
+  #   in production, you would not need this code as the script can close after the pipeline will be sent
+  session.run(
+    wait=30, # wait for the user to stop the execution or a given time
+    close_pipelines=True # when the user stops the execution, the remote edge-node pipelines will be closed
+  )
+  session.P("Main thread exiting...")

naeural_client-2.0.3/tutorials/ex1_connect_to_network.py → naeural_client-2.1.0/tutorials/ex01_part2_filter.py

@@ -1,8 +1,10 @@
 """
 This is a simple example of how to use the naeural_client SDK.
 
-In this example, we connect to the network, listen for heartbeats from 
-  Naeural Edge Protocol edge nodes and print the CPU of each node.
+In this example:
+  - we connect to the network
+  - listen for heartbeats from Naeural Edge Protocol edge nodes and print the CPU of each node.
+  - listen for payloads from Naeural Edge Protocol edge nodes and print the data of each payload.
 """
 import json
 
@@ -13,6 +15,10 @@ class MessageHandler:
   def __init__(self, signature_filter: str = None):
     """
     This class is used to handle the messages received from the edge nodes.
+    
+    In this class we are defining two callback methods:
+      - on_heartbeat: this method is called when a heartbeat is received from an edge node.
+      - on_data: this method is called when a payload is received from an edge node.
     """
     self.signature_filter = signature_filter.upper() if isinstance(signature_filter, str) else None
     self.last_data = None # some variable to store the last data received for debugging purposes
@@ -39,7 +45,7 @@ class MessageHandler:
     heartbeat : dict
         The heartbeat received from the edge node.        
     """
-    session.P("{} ({}) has a {}".format(
+    session.P("{} ({}) has {}".format(
       heartbeat['EE_ID'], 
       self.shorten_address(node_addr), 
       heartbeat["CPU"])
@@ -83,14 +89,14 @@ class MessageHandler:
     
     if self.signature_filter is not None and plugin_signature.upper() != self.signature_filter:
       # we are not interested in this data but we still want to log it
-      message = "Received data from <{}::{}::{}::{}>".format(
+      message = "Recv from <{}::{}::{}::{}>".format(
         addr, pipeline_name, plugin_signature, plugin_instance
       )
       color = 'dark'
     else:
       # we are interested in this data
-      message = "Received target data from <{}::{}::{}::{}>\n".format(
-        node_addr, pipeline_name, plugin_signature, plugin_instance
+      message = "Recv data from <{}::{}::{}::{}>\n".format(
+        addr, pipeline_name, plugin_signature, plugin_instance
       )
       # the actual data is stored in the data.data attribute of the Payload UserDict object
       # now we just copy some data as a naive example

naeural_client-2.0.3/tutorials/ex7_custom_code_on_multiple_remotes__example_2.py → naeural_client-2.1.0/tutorials/ex07_custom_code_on_multiple_remotes__example_2.py

@@ -150,7 +150,6 @@ if __name__ == "__main__":
   p = s.create_or_attach_to_pipeline(
     node=node,
     name="run_distributed",
-    data_source="Void"
   )
 
   p.create_chain_dist_custom_plugin_instance(

naeural_client-2.0.3/tutorials/ex8_custom_web_app.py → naeural_client-2.1.0/tutorials/ex08_custom_web_app.py

@@ -1,5 +1,4 @@
-from naeural_client import CustomPluginTemplate, Session
-from naeural_client.default.instance import CustomWebApp01
+from naeural_client import CustomPluginTemplate, Session, PLUGIN_TYPES
 
 # this tutorial can be run only on the local edge node
 # because it uses ngrok to expose the fastapi server
@@ -48,7 +47,7 @@ if __name__ == "__main__":
   node = "INSERT_YOUR_NODE_ADDRESS_HERE"
   session.wait_for_node(node)
 
-  instance: CustomWebApp01
+  instance: PLUGIN_TYPES.CUSTOM_WEB_APP_01
   pipeline, instance = session.create_web_app(
     node=node,
     name="naeural_predict_app",    

naeural_client-2.0.3/tutorials/ex9_code_sandbox_from_scratch.py → naeural_client-2.1.0/tutorials/ex09_code_sandbox_from_scratch.py

@@ -1,5 +1,4 @@
-from naeural_client import CustomPluginTemplate, Session
-from naeural_client.default.instance import CustomWebApp01
+from naeural_client import CustomPluginTemplate, Session, PLUGIN_TYPES
 
 # this tutorial can be run only on the local edge node
 # because it uses ngrok to expose the fastapi server
@@ -22,11 +21,11 @@ if __name__ == "__main__":
   node = "0xai_At8N0Qgz78sBLgPtMgifmCabJGkgEzgkEP-1laDggXVM"
   session.wait_for_node(node)
 
-  instance: CustomWebApp01
+  instance: PLUGIN_TYPES.CUSTOM_WEB_APP_01
   pipeline, instance = session.create_web_app(
     node=node,
     name="naeural_code_sandbox_copycat_app",
-    signature=CustomWebApp01,
+    signature=PLUGIN_TYPES.CUSTOM_WEB_APP_01, # not mandatory as it is the default value
 
     ngrok_edge_label="edghts_2jSQ4nm5TuzGgHh8I0wlfDz3Vr0",  # https://naeural-001.ngrok.app
     use_ngrok=True,

naeural_client-2.1.0/tutorials/ex10_telegram_echo_bot.py

@@ -0,0 +1,48 @@
+import os
+
+from naeural_client import Session, CustomPluginTemplate, PLUGIN_TYPES
+
+
+def reply(plugin: CustomPluginTemplate, message: str, user: str):
+  """
+  This function is used to reply to a message.
+  """
+  # for each user message we increase a counter
+  plugin.int_cache[user] += 1 # int_cache is a default dict that allows persistence in the plugin
+  plugin.P(f"Replying to the {plugin.int_cache[user]} msg of '{user}' on message '{message}'")
+  result = f"The answer to your {plugin.int_cache[user]} question is in the question itself: {message}"
+  return result
+
+if __name__ == "__main__":
+  TELEGRAM_BOT_TOKEN_ENV_KEY = "TELEGRAM_BOT_TOKEN"
+  MY_NODE = None # we can specify a node here, if we want to connect to a specific
+    
+  session = Session() # assume .env is available and will be used for the connection and tokens
+  
+  if MY_NODE:
+    node = MY_NODE
+  else:
+    session.wait_for_any_node() # we wait for any node to present itself as active
+    node = session.get_active_nodes()[0] # we get the first active node
+  
+      
+  # now we create a telegram bot pipeline & plugin instance
+  # we can chose to use the token directly or use the environment key
+  instance: PLUGIN_TYPES.BASIC_TELEGRAM_BOT_01
+  pipeline, instance = session.create_telegram_simple_bot(
+    node=node,
+    name="telegram_bot_echo",
+    telegram_bot_token_env_key=TELEGRAM_BOT_TOKEN_ENV_KEY,
+    reply_function=reply,
+  )
+  
+  pipeline.deploy() # we deploy the pipeline
+
+  # Observation:
+  #   next code is not mandatory - it is used to keep the session open and cleanup the resources
+  #   in production, you would not need this code as the script can close after the pipeline will be sent  
+  session.run(
+    wait=60,  # we run the session for 60 seconds
+    close_pipelines=True,  # we close the pipelines after the session
+    close_session=True,  # we close the session after the session
+  )

naeural_client-2.0.3/naeural_client/default/instance/__init__.py

@@ -1,4 +0,0 @@
-from .net_mon_01_plugin import NetMon01
-from .view_scene_01_plugin import ViewScene01
-from .custom_web_app_01_plugin import CustomWebApp01
-from .chain_dist_custom_job_01_plugin import ChainDistCustomJob01