===================== Robot's Configuration ===================== Aiviro Configuration ==================== In the Aiviro config-file, you can modify different aspects of the robot's behavior. .. note:: Every configurable value is described as "``value-name`` - data-type [*default value*], value description". And it can be setup using an ``aiviro-cli config set`` command in your terminal, which modifies the *Backend configuration* file. .. code-block:: # Sets API credentials $ aiviro-cli config login --client-id --api-key # Sets any value in the config file, e.g. setting value "{"cache": "enable": false}" $ aiviro-cli config set --key cache --key enable --value false # Prints current configuration $ aiviro-cli config print # Show paths to configuration files $ aiviro-cli config paths Aiviro's configuration is automatically loaded and merged from three locations in the following order (e.g., user configuration overwrites backend configuration): 1. **Default configuration**: Stored within the Aiviro python package 2. **Backend configuration**: The default path can be overridden by the ``AIVIRO__BACKEND_CONFIG_PATH`` environment variable. Default paths are: * MacOS - `~/Library/Application Support/aiviro/config.yml` * Linux - `~/.config/aiviro/config.yml` * Windows - `AppData/aiviro/config.yml` 3. **User configuration**: Loaded from `./config.yml` in the current working directory, or from the path specified in the ``AIVIRO__USER_CONFIG_PATH`` environment variable. Credentials ----------- Aiviro requires access to our servers to recognize text and elements on the screen. For this, you need a valid ``client_id`` and ``api_key``. .. code-block:: yaml credentials: client_id: "your-client-id" api_key: "super-secret-api-key" * ``client_id`` - str, Your client ID. * ``api_key`` - str, Your API key. It must be either 171 characters long. Vision Server ------------- This defines the communication protocol and address for the OCR and Element detection servers. .. code-block:: yaml vision_server: hostname: https://api.aiviro.com/ ocr_model: stable ouir_model: stable max_cache: 5 * ``hostname`` - HttpUrl [https://api.aiviro.com/] The host URL for the detection server. The previous field `api_url` is deprecated but still supported for backward compatibility. * ``ocr_model`` - str [*stable* or *latest*], The model version for OCR recognition. * ``ouir_model`` - str [*stable* or *latest*], The model version for element recognition. * ``max_cache`` - int [*5*], The number of recent predictions to store in a local cache for faster recognition. Cache ----- When enabled, Aiviro stores found elements locally. If the same element needs to be found again, Aiviro uses the cached data instead of sending a new request to the server, resulting in faster processing. .. code-block:: yaml cache: enable: true folder: logs/ * ``enabled`` - boolean [*True*], Defines if the cache is enabled. The previous field `enable` is deprecated. * ``folder`` - str [*logs/*], The path to the folder where cache files are stored. Relative or absolute paths are supported. .. _configuration logging: Logging ------- Aiviro collects local text and image logs during each script run to provide insight into its operations and to help diagnose issues. Logs can be split into two types: * **text logs** - contain information, e.g. which texts were compared during a search for the element or which commands were called, * **image logs** - contain screenshots which Aiviro used with a corresponding elements' bound-boxes, further about this in :ref:`Generate Images` section. .. code-block:: yaml logger: logging_levels: aiviro: DEBUG log_folder: logs/ log_to_file: true log_images: true log_compression: false max_disk_size: "0B" max_number_of_logs: 0 buffer: image_enabled: true image_limit: 10 text_enabled: true text_limit: 200 generate_images: enabled: true last_n_images: 20 stats: retention_days: 90 retention_disk_size: "0B" upload_server: hostname: http://localhost:6400 * ``logging_levels`` - dict[*{}*], Sets logging levels for specified loggers. * ``log_folder`` - str [*logs/*], The folder path for storing all logs. * ``log_to_file`` - boolean [*True*], Defines if text logs are stored * ``log_images`` - boolean [*True*], Defines if image logs are stored. * ``log_compression`` - boolean [*False*], Defines if logs should be compressed into a single *.zip* file. * ``max_disk_size`` - int/string [*0*], Sets the maximum size of the log folder (e.g., "20GB"). If set to 0, the check is disabled. * ``max_number_of_logs`` - int [*0*], The maximum number of logs to keep. If set to 0, the check is disabled. Buffer ~~~~~~ The buffer keeps the last N debug images and text logs in memory. Data from the image buffer are used by :meth:`~.BaseRobot.emit_image_logger_buffer` or for generating GIF :meth:`~.BaseRobot.create_gif_from_buffer`. * ``image_enabled`` - boolean [*True*], Enables or disables the image buffer. The previous field `image_enable` is deprecated. * ``image_limit`` - int [*20*], The maximum number of images stored in the buffer. * ``text_enabled`` - boolean [*True*], Enables or disables the text log buffer. The previous field `text_enable` is deprecated. * ``text_limit`` - int [*200*], The maximum number of text logs stored in the buffer. Generate Images ~~~~~~~~~~~~~~~ This feature generates human-readable images from raw image logs and metadata. * ``enabled`` - boolean [*True* on local, *False* in Docker*], Defines if automatic image generation is enabled. The previous field `enable` is deprecated. * ``last_n_images`` - int [*None* on local, *20* in Docker], The number of last images to generate. If set to 0, all images are generated. .. warning:: | In longer aiviro-scripts it can take significant time to generate image-logs! | We recommend to set-up ``last_n_images`` option in the config-file. Generating image-logs can be done also manually, after running aiviro-scripts, by using *aiviro-cli*. For further information see :ref:`Process Metadata Logs` section. Stats ~~~~~ Configuration for statistics retention. * ``retention_days`` - int [*90*], The number of days to keep statistics. * ``retention_disk_size`` - int/str [*0*], The maximum disk size for statistics. Streaming --------- Any robot can stream what it sees, which is useful for headless operations. The streaming URL is printed to stdout when the script starts. .. code-block:: yaml streaming: enabled: true ip_address: localhost port: null print_port: null access_token: "auto-generated-token" pause_until_client: false pause_timeout: 60 * ``enabled`` - boolean [*True*], Defines if streaming is enabled. The previous field `enable` is deprecated. * ``ip_address`` - str [*localhost*], The IP address for the streaming URL. * ``port`` - int | None [*None*], The port for streaming. A random free port is used if not set. * ``print_port`` - int| None [*None*], If set, this port is used in the URL printed to the console. * ``access_token`` - str [*auto-generated*], A token required to access the stream. * ``pause_until_client`` - boolean [*False*], Pauses the script until a client connects to the stream. * ``pause_timeout`` - int [*60*], The timeout in seconds to wait for a client connection when `pause_until_client` is true. .. note:: The video stream can be open in any browser and the URL is printed into stdout at the start of the script. Be aware that *port* and *access_token* are always selected randomly, every run of the script has a different URL. For testing purposes, this can be overridden in the configuration file, as shown above. Here is an example of streaming URL based on the configuration above: ``http://localhost:6262/?access_token=super-secret-token``. Here is without specifying the ``print_port``: ``http://localhost:12345/?access_token=super-secret-token``. Webdriver --------- .. warning:: Setting the webdriver path in the configuration file is deprecated. Please add the webdriver's path to the `PATH` environment variable or specify it when creating a `WebRobot`. This configuration specifies the path to the webdriver executable required by :class:`~.WebRobot`. .. code-block:: yaml webdriver: linux: /usr/bin/chromedriver windows: path/to/chromedriver.exe * ``webdriver`` - dict, A dictionary where the key is the platform name (linux, windows, darwin) and the value is the path to the webdriver executable. User Configuration ================== .. automodule:: aiviro.core.utils.configuration.user_config :members: UserConfig