Agent lambda development
========================

Here is *agent* lambda development description.

More information about lambda types and differences of
*agent* and others available at `lambda types description <./lambda_types.html#standalone>`_.

More information about LUNA videoanalytics, in particular, *luna-video-manager*, *video-agents* and their interaction
see its' developers manuals.


Agent lambda requirements
-------------------------

Agent lambda has several requirements to addition with `basic requirements <./lambda_requirements.html#lunaservicesrequirements>`_:

- `Luna Video Manager` available by credentials from `Luna-Configurator`

- `Luna Licenses` available by credentials from `Luna-Configurator`

- `Luna Events` available by credentials from `Luna-Configurator`; it can be disabled using
  *ADDITIONAL_SERVICES_USAGE* setting and it this case *lambda* should provide for work without `Luna-Events` usage

- `Luna Sender` available by credentials from `Luna-Configurator`; it can be disabled using
  *ADDITIONAL_SERVICES_USAGE* setting and it this case *lambda* should provide for work without `Luna-Sender` usage

- `Luna Faces/Images Samples Store` available by credentials from `Luna-Configurator`; it can be disabled using
  *ADDITIONAL_SERVICES_USAGE* setting and it this case *lambda* should provide for work without `Luna-Image-Store` usage


Agent lambda configuration
--------------------------

The agent lambda required several settings from *luna-configurator*, whose can be separated to several groups:

- *LUNA_LAMBDA_AGENT_UNIT_LOGGER* - lambda logger settings

- luna-services addresses and timeouts settings (for example, *LUNA_EVENTS_ADDRESS* and *LUNA_EVENTS_TIMEOUTS* will
  be used by lambda to make requests to *luna-events* service)

- *ADDITIONAL_SERVICES_USAGE* setting will be used to determine which *luna-services* can be used by the lambda
  (the lambda will not check connection to disabled services and will raise an error if user try to make request
  to such service)

- *LUNA_LAMBDA_AGENT_UNIT_ANALYTICS_SETTINGS* - lambda analytics-specific settings, for example, settings of which
  device must be used by one or another analytics - CPU or GPU

- *LUNA_LAMBDA_AGENT_UNIT_VIDEO_SETTINGS*/*LUNA_LAMBDA_AGENT_UNIT_RUNTIME_SETTINGS* - lambda video processing settings

.. note::

    Take into account that *video-agents* can be internal and external (see *Luna-Video-Manager*/*Luna-Video-Agent*)
    developers documentation for details. The lambda video-agent represents internal video-agent at the moment, this
    behaviour can be changed in the future releases.


Agent lambda development
------------------------

Lambda agent works with analytics, each lambda agent must have at least one video analytics.

It is possible to specify video analytics as separate package which will installed as lambda dependency or
include analytics as module into lambda. The `lambda_main.py` and other configuration files will not differ in this
cases.

The description below describes the case when analytics represents itself separate package, for description in the
case of analytics is a module in lambda see `analytics development chapter <./agent.html#agent-video-analytics-development>`_.

The agent lambda development in the easiest way consists of it's configuration by specifying several parameters in
*lambda_main.py* file.

.. warning::

    The names of analytics, features, etc. listed below are fictitious and have nothing in common with the names of
    real analytics, etc.


The only required variable which must be specified is a list of available analytics, which also must be specified
as lambda requirements, for example:

.. code-block::
    :caption: lambda_main.py

        #: list of analytics for agent lambda
        AVAILABLE_ANALYTICS = ["people"]

.. code-block::
    :caption: requirements.txt

        people_analytics==1.2.0

There are some more parameters which can also be relevant:

The `ANALYTICS_LICENSE_FEATURES` is a map with analytics and their licensing feature names. If analytics not required
licensing, it must not be included into this map. If no one analytics must depends on licensing, this map must be empty
or may not be included in `lambda_main.py`.

The `ESTIMATORS_TO_INITIALIZE` and `ESTIMATORS_TARGETS` are lists of SDK estimators and their targets which must
initialized before analytics usage. If no one analytics not required SDK estimators usage, this lists must be empty
or may not be included in `lambda_main.py`.

.. note::

    In this example lambda has *people_analytics* package of version 1.2.0 as requirement, which represents video
    analytics package with analytics named *people*. The usage of this analytics is regulated by license feature
    named *people_feature*. It is requires the estimator from *luna-sdkloop* package named *people* and the *people*
    target estimator to be initialized before lambda starts.

.. code-block::
    :caption: lambda_main.py

        from sdk_loop.enums import Estimators, LoopEstimations

        #: list of analytics for agent lambda
        AVAILABLE_ANALYTICS = ["people"]
        #: map with analytics and their license features
        ANALYTICS_LICENSE_FEATURES = {"people": "people_feature"}
        #: list of estimators for initialization
        ESTIMATORS_TO_INITIALIZE = [Estimators.people]
        #: list of estimators targets for initialization
        ESTIMATORS_TARGETS = [LoopEstimations.people]

.. code-block::
    :caption: requirements.txt

        people_analytics==1.2.0


There are some more settings which can be used for *agent* lambda in *lambda_main.py* file:


.. code-block::
    :caption: lambda_main.py

        # count of video-agent registration attempt in *luna-video-manager*
        REGISTRATION_ATTEMPT_COUNT = 5
        # delay between registration attempts
        REGISTRATION_ATTEMPT_DELAY = 1
        # max size of feedback which can be sent to *luna-video-manager* at one time
        FEEDBACK_MAX_BATCH_COUNT = 1000
        # the code of response for ws-connections when agent shutdown
        WSCODE_GOING_AWAY = 1001
        # the name of lambda video-agent which will be registered in *luna-video-manager*
        AGENT_NAME = "luna-lambda-great-video-agent"
        # the description of lambda video-agent which will be registered in *luna-video-manager*
        AGENT_DESCRIPTION = "luna-lambda-greatest-video-agent"


The are many other possibilities to modify such lambda agent behavior, it's interaction with analytics and so on, which
can be realized in the same way as regular *luna-video-agent*, for more information, see *luna-video-agent* developers
manual.


Agent video analytics development
---------------------------------

It is possible to specify video analytics as separate package which will installed as lambda dependency or
include analytics as module into lambda. The description below describes analytics module, which can then be included
as a module or package.


.. note::

    The complete for user video analytics development guide is in development and will be included in future releases.


In presented example(s) the `poetry <https://python-poetry.org/>`_ tool using for dependencies management, so
the *pyproject.toml* file is filled by user and the *poetry.lock* file must be generated using *poetry* tool.

The example of video analytics which detect suits on video/streams and generate events if suits appears.


.. note::

    The example below uses image classification model (`"resnet50-v2-7.onnx" <https://github.com/onnx/models/raw/refs/heads/main/validated/vision/classification/resnet/model/resnet50-v2-7.onnx?download=>`_)
    and json file (`"imagenet-simple-labels.json" <https://raw.githubusercontent.com/anishathalye/imagenet-simple-labels/master/imagenet-simple-labels.json>`_) from
    `github <https://github.com/onnx/onnx-docker/blob/master/onnx-ecosystem/inference_demos/resnet50_modelzoo_onnxruntime_inference.ipynb>`_.
    To make this example works it needs to get this files from github and place into *data* folder of lambda agent archive.


.. code-block::
    :caption: Suit analytics example file structure itself

      ├──__init__.py
      ├──analytics.py
      ├──classes.py
      ├──common.py
      ├──models.py
      ├──spec.html
      ├──spec.yml
      └──data
         ├──resnet50-v2-7.onnx
         └──imagenet-simple-labels.json
      └──suit_nodes
         ├──__init__.py
         ├──events.py
         ├──suit_estimator.py
         └──suid_nodes.py


.. note::

    The video analytics requires some dependencies which are available on `visionlabs pypi <http://pypi.visionlabs.ru/root/public>`_
    for local run. All provided examples use visionlabs pypi specification at `tool.poetry.source` section of
    *pyproject.toml* file which make possible to install dependencies from the above source.
    It is also required HASP license provided by VisionLabs. For agent lambda creation, all
    required video analytics dependencies already included in base image (which is using for agent lambda building).


If it needs to build this analytics as separate package, it must include its' dependencies for example using
pyproject.toml/poetry.lock files:

.. literalinclude:: examples/200/agent_lambda_suit/lambda/suit_analytics/pyproject.toml
   :caption: pyproject.toml
   :language: toml


After dependencies resolving it must be built into a packages (for example, using `poetry build`).


.. raw:: html

    <details>
    <summary><a>The *__init__.py* module must contains all presented imported objects and classes to make analytics works.</a></summary>

.. literalinclude:: examples/200/agent_lambda_suit/lambda/suit_analytics/__init__.py
   :caption: __init__.py
   :language: python

.. raw:: html

    </details>


.. raw:: html

    <details>
    <summary><a>The *analytics.py* module contains analytics initialization, frame and analytics contexts.</a></summary>

.. literalinclude:: examples/200/agent_lambda_suit/lambda/suit_analytics/analytics.py
   :caption: analytics.py
   :language: python

.. raw:: html

    </details>


.. raw:: html

    <details>
    <summary><a>The *classes.py* module contains frame and analytics results containers description.</a></summary>

.. literalinclude:: examples/200/agent_lambda_suit/lambda/suit_analytics/classes.py
   :caption: classes.py
   :language: python

.. raw:: html

    </details>

.. raw:: html

    <details>
    <summary><a>The *common.py* module contains analytics target, mandatory nodes and `getDocumentation` function
                which returns raw html analytics documentation for user.</a></summary>

.. literalinclude:: examples/200/agent_lambda_suit/lambda/suit_analytics/common.py
   :caption: common.py
   :language: python

.. raw:: html

    </details>


.. raw:: html

    <details>
    <summary><a>The *models.py* module contains analytics parameters models.</a></summary>

.. literalinclude:: examples/200/agent_lambda_suit/lambda/suit_analytics/models.py
   :caption: models.py
   :language: python

.. raw:: html

    </details>


.. raw:: html

    <details>
    <summary><a>The *spec.yml* file contains openapi documentation with analytics parameters description in yaml format.</a></summary>

.. literalinclude:: examples/200/agent_lambda_suit/lambda/suit_analytics/spec.yml
   :caption: spec.yml
   :language: yaml

.. raw:: html

    </details>


.. raw:: html

    <details>
    <summary><a>The *spec.html* file contains openapi documentation with analytics parameters description in html format.</a></summary>

.. literalinclude:: examples/200/agent_lambda_suit/lambda/suit_analytics/spec.html
   :caption: spec.html
   :language: html

.. raw:: html

    </details>


.. raw:: html

    <details>
    <summary><a>The *__init__.py* module in *suit_nodes* path is empty.</a></summary>

.. literalinclude:: examples/200/agent_lambda_suit/lambda/suit_analytics/suit_nodes/__init__.py
   :caption: __init__.py
   :language: python

.. raw:: html

    </details>


.. raw:: html

    <details>
    <summary><a>The *events.py* module in *suit_nodes* path contains events and track structures.</a></summary>

.. literalinclude:: examples/200/agent_lambda_suit/lambda/suit_analytics/suit_nodes/events.py
   :caption: events.py
   :language: python

.. raw:: html

    </details>


.. raw:: html

    <details>
    <summary><a>The *suit_estimator.py* module in *suit_nodes* path contains suit estimator responsible
                for image preprocessing, processing and neural model results postprocessing.</a></summary>

.. literalinclude:: examples/200/agent_lambda_suit/lambda/suit_analytics/suit_nodes/suit_estimator.py
   :caption: suit_estimator.py
   :language: python

.. raw:: html

    </details>


.. raw:: html

    <details>
    <summary><a>The *suit_nodes.py* module in *suit_nodes* path contains suit nodes structures.</a></summary>

.. literalinclude:: examples/200/agent_lambda_suit/lambda/suit_analytics/suit_nodes/suit_nodes.py
   :caption: suit_nodes.py
   :language: python

.. raw:: html

    </details>

|


Agent lambda examples
---------------------

- Here is an example of agent lambda with suit video analytics:

    To include video analytics presented in previous chapter into lambda agent as package it needs the following lambda
    archive file structure:

    .. code-block::
        :caption: Lambda agent with suit analytics example file structure (the case when analytics includes in lambda as package)

          ├──pyproject.toml
          ├──poetry.lock
          └──lambda_main.py

    The `lambda_main.py` module:


    .. literalinclude:: examples/200/agent_lambda_suit/lambda/lambda_main.py
       :caption: lambda_main.py
       :language: python

    It this case, the dependencies of lambda agent must include only analytics as dependency, not analytics dependencies:


    .. raw:: html

        <details>
        <summary><a>*pyproject.toml*</a></summary>

    .. literalinclude:: examples/200/agent_lambda_suit/lambda/pyproject_minimal.toml
       :caption: pyproject.toml
       :language: toml

    .. raw:: html

        </details>

    |



    To include presented analytics into lambda agent as module it needs the following lambda archive file structure:

    .. code-block::
        :caption: Lambda agent with suit analytics example file structure (the case when analytics includes in lambda as module)

          ├──pyproject.toml
          ├──poetry.lock
          ├──lambda_main.py
          └──suit_analytics
              ├──__init__.py
              ├──analytics.py
              ├──classes.py
              ├──common.py
              ├──models.py
              ├──spec.html
              ├──spec.yml
              └──data
                 ├──resnet50-v2-7.onnx
                 └──imagenet-simple-labels.json
              └──suit_nodes
                 ├──__init__.py
                 ├──events.py
                 ├──suit_estimator.py
                 └──suid_nodes.py


    |

    In this case, the analytics dependencies must be included into lambda dependencies. The lambda dependencies described
    as *pyproject.toml* file:

    .. raw:: html

        <details>
        <summary><a>*pyproject.toml*</a></summary>

    .. literalinclude:: examples/200/agent_lambda_suit/lambda/pyproject.toml
       :caption: pyproject.toml
       :language: toml

    .. raw:: html

        </details>

    |