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.

# Sets API credentials
$ aiviro-cli config login --client-id <client-id> --api-key <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.

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.

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.

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.

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 Generate Images section.

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 emit_image_logger_buffer() or for generating GIF 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 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.

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 WebRobot.

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

class aiviro.core.utils.configuration.user_config.UserConfig

It creates a way for user to change various configuration options of the Robot. It can be accessed as aiviro.user_config.

property text_similarity_threshold: float | None

Custom text similarity threshold value.

Getter:

Returns value of the threshold

Setter:

Sets value of the threshold, it must be float number between 0 and 1, or None to use default value

Example:

>>> import aiviro
>>> r = aiviro.create_desktop_robot()
>>> aiviro.user_config.text_similarity_threshold = 0.8
>>> r.see(aiviro.Text("X12GP-WR34", aiviro.find_method.SIMILAR))
>>> aiviro.user_config.text_similarity_threshold = None
property text_normalization: Callable[[str], str] | None

Custom normalization method to change the detected OCR text in any way.

Getter:

Returns normalization method

Setter:

Sets normalization method, it must be a callable object with one input argument (str) and returns (str)

Example:

>>> import aiviro
>>> aiviro.user_config.text_normalization = lambda x: x.replace("O", "0")
>>> r = aiviro.create_desktop_robot()
>>> r.see(
...     aiviro.Text(
...         r"\d+",
...         aiviro.find_method.REGEX.USER_NORMALIZATION,
...     )
... )
property implicit_wait: int

Number of seconds to wait for every search-object to appear on the screen. Functionality of implicit wait is similar as calling wait_for() command. But implicit wait works for every command that needs to process some search-object.

Warning

This parameter does not apply for get(), wait_for() & wait_until_disappear() commands.

Getter:

Returns value of implicit wait

Setter:

Sets timeout of implicit wait, it must be <int> number. To disable implicit wait set it to None or 0.

Example:

>>> import aiviro
>>> aiviro.user_config.implicit_wait = 5
>>> r = aiviro.create_desktop_robot()
>>> r.type_text(aiviro.Input("Password"), "*******", sensitive_data=True)
>>> r.click(aiviro.Button("Submit"))

>>> # the example above could be rewritten without implicit-wait
>>> import aiviro
>>> r = aiviro.create_desktop_robot()
>>> input_box = r.wait_for(aiviro.Input("Password"), timeout=5)
>>> r.type_text(input_box, "*******", sensitive_data=True)
>>> r.click(aiviro.Button("Submit"))
property text_find_strategy: list[FindMethod]

List of find methods that are used to find elements with text on the screen. Enables to set several find methods to try in case the previous did not find the element.

Getter:

Returns list of find methods

Setter:

Sets list of find methods, it must be a list of FindMethod

Example:

>>> import aiviro
>>> aiviro.user_config.text_find_strategy = [
...     aiviro.find_method.SIMILAR,
...     aiviro.find_method.EQUAL,
... ]
>>> r = aiviro.create_desktop_robot()
>>> r.see(aiviro.Text("X12GP-WR34", find_method=aiviro.find_method.AUTO)