✨ Getting Started

Overview

This guide provides detailed instructions on how to get started with Etendo Copilot, an API that allows interaction with a bot capable of selecting the appropriate tools to respond to user queries. It includes the necessary requirements, instructions for adding dependencies, environment variable configurations, and steps to run Copilot on an Etendo Classic project. Additionally, it covers optional configurations to customize Copilot's behavior and provides links to detailed installation guides for required software.

Requirements

Install Etendo Classic. For this, follow the Etendo Installation Guide.
This project depends on the following tools:
- Docker: version 26.0.0 or higher.
- Docker Compose: version 2.26.0 or higher.
- Python 3 version 3.10or higher.

Info

The Docker Management module, included as a dependency allows for the distribution of the infrastructure within Etendo modules, which include Docker containers for each service.

Installation

Etendo Copilot is distributed within the Copilot Extensions bundle, which in addition to including the Copilot Core functionality and infrastructure, includes default assistants and tools that can be used directly or compose their use in new wizards.

Info

To be able to include this functionality, the Copilot Extensions Bundle must be installed. To do that, follow the instructions from the marketplace: Copilot Extensions Bundle. For more information about the available versions, core compatibility and new features, visit Copilot Extensions - Release notes.

Running Etendo Copilot

The simplest configuration we are going to follow as an example is to mount Copilot Dockerized and Tomcat running as a local service. Other configurations are detailed in the section, Advanced Configurations.

In gradle.properties file is necessary to add some environment variables as a mandatory requirement

gradle.properties

OPENAI_API_KEY= ****
ETENDO_HOST=https://<Etendo URL>/<Context Path>
ETENDO_HOST_DOCKER=http://host.docker.internal:<Tomcat Port>/<Context Path>
COPILOT_HOST=<Copilot URL>
COPILOT_PORT=<Copilot Port>

docker_com.etendoerp.copilot=true

Environment Variable	Default	Info
OPENAI_API_KEY	`***********************`	Required You can use an OPEN AI API Key of your own, or you can contact the Etendo support team to obtain one.
ETENDO_HOST		Required The URL of the Etendo system, this is where copilot will send the requests to communicate with the Etendo system. E.g: https://demo.etendo.cloud/etendo or http://localhost:8080/etendo
ETENDO_HOST_DOCKER		Required The URL of the Etendo system, this is where copilot will send the requests to communicate with the Etendo system. This variable is used when the copilot is running in a docker container and the Etendo Instance is not accessible from a domain.
COPILOT_HOST	`localhost`	Required The copilot host can be defined by the user. By default use `localhost`
COPILOT_PORT	`5005`	Required The copilot port can be defined by the user. By default use `5005`
docker_com.etendoerp.copilot	`true`	Required Configuration variable for the Etendo Copilot container to be launched.

Info

The ETENDO_HOST_DOCKER variable is used when the copilot is running in a docker container and the Etendo Instance is not accessible from a domain. This is important because the copilot needs to communicate with the Etendo system to perform the necessary actions. For example, if Copilot is running into a docker container and the Etendo Instance is running locally, the ETENDO_HOST variable should be http://localhost:8080/etendo and the ETENDO_HOST_DOCKER variable should be http://host.docker.internal:8080/etendo. Its recommended to access to the Docker Container shell and check the network configuration to get the correct IP address.

Once the Copilot Extensions Bundle dependency was added and the variables configurated, in the terminal execute the following command to apply the changes:
Terminal
```
./gradlew setup
```
Then, the copilot container needs to be created:
Terminal
```
./gradlew resources.up
```
And then recomplile the environment:
Terminal
```
./gradlew update.database compile.complete smartbuild --info
```
To start the copilot Docker image, execute:
Terminal
```
./gradlew resources.up
```
To stop the Copilot container you can run:
Terminal
```
./gradlew resources.stop
```
Everytime a new tool is added or the enviorement variables change, it's necessary to delete and create the Copilot container again. Execute the following command to delete the container:
Terminal
```
./gradlew resources.down
```
Warning

Be aware that resources.stop and resources.down will also affect other services configured in the etendo container
Try Copilot in your Etendo instance. To configure an assistant to use Etendo Copilot, follow the Copilot Setup and Usage guide.

Advanced Configurations

Copilot & Tomcat DockerizedCopilot locally (for developing copilot only)

The com.etendoerp.tomcat module enables the Dockerization of Tomcat within Etendo Classic. This module modifies Gradle tasks to automatically deploy the WAR file into the container when executing the smartbuild task. Follow the Dockerized Tomcat Service documentation to learn how to configure it.

When using both services in docker, the enviorement variables should look like this:

gradle.properties

OPENAI_API_KEY= ****
ETENDO_HOST=http://tomcat:<Docker Tomcat Port>/<Context Path>
ETENDO_HOST_DOCKER=http://host.docker.internal:<Docker Tomcat Port>/<Context Path>
COPILOT_HOST=copilot
COPILOT_PORT=<Docker Copilot Port>

docker_com.etendoerp.copilot=true
docker_com.etendoerp.tomcat=true
docker_com.etendoerp.tomcat_port=<Docker Tomcat Port>

Requirements:

Python 3.10 or 3.11
Poetry

We recommend usign PyCharm to run copilot locally. Download and install here PyCharm Community Edition

Open PyCharm, search for the copilot module and open it.
Open the Run.py file, then add a new interpreter.
Add a new configuration file and select Python
Select the interpreter created before, in the script field select the run.py file and .env field select the gradle.properties
Once done, open the PyCharm terminal and execute the following commands:
terminal
```
source venv/bin/activate
poetry install
```
Execute Run.py from PyCharm

Developer Environment Variables

In addition, there are other optional variables to configure certain aspects of the copilot. If not specified, default values are used.

Environment Variable	Options	Default	Info
CONFIGURED_TOOLS_FILENAME	`JSON File name`	`tools_config.json`	Optional The name of the file that contains the configuration of the enabled tools.
DEPENDENCIES_TOOLS_FILENAME	`TOML File name`	`tools_deps.toml`	Optional The name of the file that contains the configuration of the dependencies of the tools.
COPILOT_PULL_IMAGE	`Boolean`	`true`	Optional If true, the copilot docker image will be pulled from docker hub. If false, gradle will try to use the local image with the tag specified in COPILOT_IMAGE_TAG, but if it does not exist, it will be pulled from docker hub.
COPILOT_IMAGE_TAG	`String`	`master`	Optional The tag of the copilot docker image that will be used.
COPILOT_DEBUG	`Boolean`	`false`	Optional If true, copilot will log additional messages in the console.
COPILOT_PORT_DEBUG	`String`	`5100`	Optional The copilot debug port can be defined by the user.