Download Python 

Download and install Python, currently version 3.11.6,

• For Windows 64bit version
  

  Note
  title Compatibility Issue
  Windows currently has issues with xmlsec library, And it only supports Python 3.9.x Update: in GAIA version 2.0, we removed the library which required the xmlsec library, so higher versions of pyhton can be used, starting from GAIA version 2.x

• For Linux

• For macOs

Note
title Disable the path length
Disable the path length limit to prevent issues in windows environment

Setup Environment

Clone and Set The Branch

1. Clone the project from the repository

   Code Block
   git clone https://source.digital.accenture.com/scm/st/gaia-api.git

2. Verify the current brach executing the command below, it should be main

   Code Block
   git branch

   1. If the branch wasn't main, checkout the main branch:

      Code Block
      git checkout main

3. Create a branch to work on, using the branch folder assigned <branch_folder>/develop (we recommend using develop as your working branch)

   Code Block
   git checkout -b <branch_folder>/develop

Create & Use A Virtual Environment

We recommend the creation of a virtual environment to prevent python dependencies conflicts, is also helpful if you have multiple versions of python in the same machine

python -m venv {name_of_your_venv}

python3 -m venv {name_of_your_venv}

If you want to name you virtual environment test then the command would look like this

python -m venv test

python3 -m venv test

Activate Virtual Environment

To use your virtual environment you need to activated, the activation command changes depending on your OS

• For Windows

  Code Block
  {name_of_your_venv}\Scripts\activate.bat

• For Unix or macOS, run:

  Code Block
  source {name_of_your_venv}/bin/activate

  Note
  title Using Bash on Windows
  If using a bash console on Windows, then you have to execute Code Block source {name_of_your_venv}/Scripts/activate

Following the example of the venv named test, the commands would look like this:

• Windows

  Code Block
  test\Scripts\activate.bat

• Unix or macOS:

  Code Block
  source test/bin/activate

Install PyQPL local library

After the installation is successful, proceed to install PyQPL

pip install lib/pyqpl-VERSION_IN_PROJECT-py3-none-any.whl

Why Use PyQPL?

PyQPL is our proprietary dependency, is a versatile scripting language that simplifies the construction of complex queries. It offers engine agnosticism, query parsing, manual query building, query translation, Saga coupling for advanced processing, synonym expansion, and support for custom operators. With PyQPL, you can write standardized queries irrespective of the underlying search engine, making it flexible and efficient for query processing tasks.

Is already seamlessly integrated into the Query Stage, and can be enable or disabled as need it, probably if you are working or had work with GAIA API previously, have used PyQPL without notice.

Uninstall PyQPL local library

In case you need to upgrade the version of pyqpl, we recommend to uninstall the current library using the command

pip uninstall pyqpl

Delete the whl file and replace it with the new one, and use the same command as above to install the new one

Install GAIA Core local library

What is the GAIA Core?

In the latest update to Version 3.0, significant architectural changes have been made to the GAIA API. The core functionalities of the GAIA API, including APIs, stages, and engines, have been migrated to a new, external library named GAIA Core. This strategic restructuring aims to segregate the foundational code from specialized implementations within the GAIA API.

Key Changes

• Separation of Core and Specialized Code: The base code, comprising APIs, stages, and engines, has now been relocated to the GAIA Core library. Consequently, the GAIA API retains only the specialized code, tailored to specific applications and functionalities.

• Benefits:

  • Enhanced Troubleshooting and Debugging: By isolating the core functionalities into a separate library, we streamline the process of identifying and resolving issues within the GAIA API ecosystem.
  • Simplified Migration: Upgrading to future versions of the GAIA API is now more straightforward. The upgrade process primarily involves reinstalling a single wheel file. In instances where modifications to specialized code are necessary, updates can be applied more efficiently and with minimal disruption.

To install GAIA Core execute:

pip install lib/gaia_core-VERSION_IN_PROJECT-py3-none-any.whl

There are other optional dependencies, you can install depending on your necessities

• If you want to use LDAP authentication

  Code Block
  pip install "lib/gaia_core-VERSION_IN_PROJECT-py3-none-any.whl[ldap]"

• If you want to use sentence splitter capabilities

  Code Block
  pip install "lib/gaia_core-VERSION_IN_PROJECT-py3-none-any.whl[nltk]"

• If you want to use genai and vectorization capabilities

  Code Block
  pip install "lib/gaia_core-VERSION_IN_PROJECT-py3-none-any.whl[genai]"

• If you want to use the unit testing

  Code Block
  pip install "lib/gaia_core-VERSION_IN_PROJECT-py3-none-any.whl[test]"

• If you want to install all required and optional dependencies

  Code Block
  pip install "lib/gaia_core-VERSION_IN_PROJECT-py3-none-any.whl[all]"

Uninstall GAIA Core local library

In case you need to upgrade the version of gaia_core, we recommend to uninstall the current library using the command

pip uninstall gaia_core

Delete the whl file and replace it with the new one, and use the same command as above to install the new one

Install Python Dependencies

If you are working on Windows you may need to download Build Tools for Visual Studio and install the Universal Windows Platform build tools (Probably will require Admin rights). Unix bases OS should have any issues

Once the virtual environment is activated (if you did one, otherwise is the same process), install the dependencies stored in the pyproject.toml. To install them execute the following command:

pip install -e .

This will install the bare minimum necessary dependencies in order to run GAIA API

There are other optional dependencies, you can install depending on your necessities

• If you want to use LDAP authentication

  Code Block
  pip install -e ".[ldap]"

  Note
  Not applicable for versions 3.0 or higher

• If you want to use genai and vectorization capabilities

  Code Block
  pip install -e ".[genai]"

  Note
  Not applicable for versions 3.0 or higher

• If you want to use the unit testing

  Code Block
  pip install -e ".[test]"

• If you want to install all required and optional dependencies

  Code Block
  pip install -e ".[all]"

If that didn't work try

python -m pip install -e .

python3 -m pip install -e .

If none of the previous commands worked, try looking at this troubleshooting article.

Install with Development Dependencies

Same as above, but additionally it will install development dependencies necessary for testing a server mocking

pip install -e ".[test]"

Startup The Server

In root folder execute

python uvicorn_server.py 

python3 uvicorn_server.py