HeavyIQ - Natural Language Interface for HeavyDB

HeavyIQ is a python module that serves as a natural language interface to interact with HeavyDB. The application uses LangChain and Large Language Models to process user’s natural language questions and provide corresponding answers based on the data in the database. The module provides a simple REST API for querying the database using natural language questions. The application also provides a CLI interface for quick interactions with the HeavyIQ agent.

Build and Run with Docker Compose

Before buiding the HeavyIQ containers, please make sure to make necessay configurations on config.toml and config.test.toml files.

1. Build the Docker image for HeavyIQ API and HeavyIQ test containers:

   docker-compose build

2. Run HeavyIQ API container:

   docker-compose up heavyiq-api

3. Run tests.

   docker-compose up --abort-on-container-exit heavyiq-test

Setup

1. If you don’t have Python >=3.10 installed, install it from here.

2. Clone this repository.

3. Navigate into the project directory:

$ cd heavyiq

4. Create a new virtual environment:

$ python3.10 -m venv venv
$ . venv/bin/activate

5. Install the requirements:

$ pip install -r requirements.txt -r requirements-dev.txt
# it may be necessary to `export HNSWLIB_NO_NATIVE=1` to install chromadb on Mac

6. Make a copy of the example config file:

$ cp config.example.toml config.toml

7. Add your API key and HeavyDB Credentials to the newly created config.toml file.

8. Run the app:

$ uvicorn app:app --reload

You should now be able to access the API Documentation at http://localhost:5000!

Using the CLI

$ python cli.py --help

Integration Tests

# App must be running locally
$ python -m unittest discover

or

Use pytest

# runs testcases specific to fastapi
$ pytest tests/fastapi --disable-warnings

Always run the testcases in sequential order by explicitly specifying the -n=0 option, or otherwise we might endup with errors.

pytest tests/api/test_lcel.py  -rs --config-path config.test.toml -n 0 --maxfail=1 --disable-warnings

Deployment

Create Production Build

bash scripts/build_prod.sh

The generated dist.tgz contains the HeavyIQ application and its authoritative requirements.txt. It does not contain an offline dependency manifest or Python wheels by default. The deployment environment must be able to resolve the declared dependencies from its configured Python package indexes; air-gapped installation is not supported.

HeavyDB can explicitly supply a selected pyheavydb wheel as the sole packaged exception. The wheel is stored under packages/ without modifying requirements.txt:

bash scripts/build_prod.sh \
  --pyheavydb-wheel=/absolute/path/to/pyheavydb-10.0.0-py3-none-any.whl

Extract the application and install its dependencies into a virtual environment:

mkdir heavyiq-dist
tar -xzf dist.tgz -C heavyiq-dist
cd heavyiq-dist
python3.10 -m venv venv
. venv/bin/activate
# For artifacts built with --pyheavydb-wheel:
python -m pip install --no-deps packages/pyheavydb-*.whl
python -m pip install -r requirements.txt

Run Production Server Process

$ gunicorn -w 4 -k uvicorn.workers.UvicornWorker 'heavyiq.api:create_app("./path/to/heavy.conf")' --preload

Port can be specified in above command with command line flag -b :8080

Security

Warning

Do not report security vulnerabilities through public GitHub issues!

NVIDIA takes security seriously. If you discover a vulnerability in useWhisper, DO NOT open a public issue. Use one of the private reporting channels described in SECURITY.md.

Support

Join the HeavyAI GitHub Discussions to ask questions, share feedback, and report issues. HeavyAI maintainers review issues, discussions, and pull requests on a best effort basis without guaranteed response timelines.

License

Apache 2.0. See LICENSE.