Skip to content

HiBuddy

A speech bot for your daily needs build during advanced software engineering at DHBW Stuttgart.


This project was built by a team of 5 students during the advanced software engineering course at DHBW Stuttgart. The goal was to create a bot that can interact using speech-to-text and text-to-speech with the user and perform tasks like a morning briefing, a helper for planning trips and events, and also to provide information about current sports events.

🚀 Requirements & Usage

⬆ Python 3.10 is required

Following dependencies are listed which are required to either run or contribute to this project.

  1. Install portaudio for speech recognition:
    • On Windows: Everything should be installed by default
    • On macOS: brew install portaudio
    • On Linux: sudo apt install python3-pyaudio
  2. Install Poetry
    • Poetry is a dependency manager for Python used in this project
    • (Optional) Setup poetry to use the local .venv folder by running poetry config virtualenvs.in-project true
  3. Run poetry install to install all dependencies - Afterwards, run poetry shell to activate the virtual environment
  4. Install the pre-commit hooks with poetry run pre-commit install

⚠ Note: If you are using Poetry it is recommended to use poetry run <command> to run commands. This ensures that the .env file is loaded and the virtual environment is activated.


After the setup is complete, use the following commands to run the agent. Note that you need to be in the root directory of the project.

# If want to run the agent with the default settings
poetry run python aswe/core/agent.py main

# With this you can trigger a specific proactivity
poetry run python aswe/core/agent.py main --test_proactivity 4

# If you want to get the microphone input
poetry run python aswe/core/agent.py main -- --get_mic

# If you want to trigger a specific proactivity and get the microphone input
poetry run python aswe/core/agent.py main --test_proactivity 3 --get_mic

🔑 API Tokens

For Google Calendar you need to create the calendar_credentials.json file in the root folder. You can retrieve this file under the following link:

For the other APIs you need to create a .env file in the root folder. This needs to contain the following variables:

WEATHER_API_KEY = ...
EVENT_API_KEY = ...
GOOGLE_MAPS_API_KEY = ...
SOCCER_API_KEY = ...
NEWS_API_KEY = ...
SPORTS_API_KEY = ...
FINANCE_API_KEY_1 = ...
FINANCE_API_KEY_2 = ...

To retrieve the API keys, you need to create an account on the following websites:

  • Visual Crossing - Checks the weather forecast (WEATHER_API_KEY)
  • Ticketmaster - Returns information about events and concerts (EVENT_API_KEY)
  • Google Maps - Returns information about locations and navigation (GOOGLE_MAPS_API_KEY)
  • Football Data - Returns information about football matches (SOCCER_API_KEY)
  • News API - Returns information about news articles (NEWS_API_KEY)
  • API-Sports - Returns information about basketball and handball matches (SPORTS_API_KEY)
  • Financial Modeling Prep - Returns information about stock prices (FINANCE_API_KEY_1)
  • Alpha Vantage - Returns information about stock news sentiment (FINANCE_API_KEY_2)

💬 Concept

In the following section we will go into detail about the concept of the agent. The agent is divided into three main parts: the speech and text conversion, the agent, the use cases, and the API layer.

Concept

🔁 CI/CD

This project uses pre-commit to ensure a consistent code style before committing. This pipeline runs primarily before committing, but will also be triggered as CI/CD pipeline on GitHub using pre-commit.ci. The related files is named .pre-commit-config.yaml. This includes the following checks:

  1. Lock project dependencies and export requirements.txt
  2. Check common hooks (e.g., yaml, merge conflicts, case conflicts)
  3. Sort imports with isort
  4. Format code with black and flake8
  5. Check typing with mypy
  6. Format markdown and yaml files with prettier
  7. Check for correct and new python styling with [pyupgrade](

After committing, the GitHub actions CI/CD pipeline will be triggered. The related files can be found in the .github/workflows folder. This includes the following checks:

  1. Run tests with pytest
  2. Calculates code coverage with pytest-cov and uploads it to Codecov
  3. Builds and deploys the MkDocs documentation (see here)
  4. Checks code quality and security with CodeQL

📝 License

This project is licensed under MIT.