Installation

Installation#

💻 Option 2: Local Development (Conda)#

For developers who want to modify the code or run without Docker.

Prerequisites#

  • Miniforge or Anaconda installed

  • Python 3.13 or higher

  • Git installed on your system

  • VS Code (recommended) with Python extension

One-Command Setup#

First, navigate to the project directory:

cd EngiAI

Then follow the manual installation steps below. Automated setup scripts are not currently provided.

Manual Installation#

Step 1: Clone the Repository#

git clone https://github.com/gioelemo/EngiAI.git
cd EngiAI

Step 2: Create Conda Environment#

conda create -n engiai python=3.13 -y

This will create an environment named engiai with Python 3.13.

Step 3: Activate Environment#

conda activate engiai

Step 4: Install Dependencies#

pip install -e ".[dev,test]"

This installs the package in editable mode along with all dependencies from pyproject.toml. The dev extra brings the lint and type-check tooling, test brings the pytest runner; quote the argument so zsh does not glob the brackets.

Note

.[all] is defined as engiai[dev,test,docs], a PEP 508 self-reference, so it needs pip 21.2 or newer (pip install --upgrade pip). uv resolves it too. Any pip recent enough to install this project already qualifies; the note is here only for very old environments.

Step 5: Install Pre-commit Hooks#

pre-commit install

Step 6: Configure VS Code (Optional)#

  1. Open the project in VS Code

  2. Install recommended extensions when prompted:

    • charliermarsh.ruff (Ruff formatter)

    • ms-python.mypy-type-checker (MyPy type checker)

    • ms-python.python (Python support)

  3. Copy template settings:

    • macOS/Linux: Copy .vscode/settings_template.json to .vscode/settings.json

    • Windows: Copy to %APPDATA%\Code\User\settings.json

Verify Installation#

Test your installation:

# Run tests
pytest

# Check code quality tools
ruff check .
mypy .

If all commands run without errors, you’re ready to go! 🎉

Setting Up API Keys#

Create a .env file from the example:

cp .env.example .env

Edit .env and add your API keys. See Configuration for details.

Important for local development: Use SQLite instead of PostgreSQL:

# In .env file
DATABASE_URL=sqlite:///data/conversations.db

🎯 Quick Comparison#

Feature

Docker

Local (Conda)

Setup Time

5 minutes

10-15 minutes

Isolation

✅ Complete

⚠️ Shared environment

Portability

✅ Run anywhere

❌ Needs conda setup

Production Ready

✅ Yes

❌ Development only

Hot Reload

❌ Requires rebuild

✅ Instant changes

Resource Usage

Moderate

Light

Best For

Production, demos

Active development

Troubleshooting#

Docker Issues#

Port already in use#

# Check what's using port 8501
lsof -i :8501

# Stop conflicting service or change port in docker-compose.yml

Container won’t start#

# Check logs
./docker-compose-wrapper.sh logs -f chatbot

# Common causes:
# - Missing API keys in .env
# - Port conflicts
# - Insufficient resources

Permission errors (Linux)#

sudo usermod -aG docker $USER
# Log out and back in

Conda Issues#

Conda environment creation fails#

If you get errors during environment creation:

  1. Update conda: conda update -n base conda

  2. Clear conda cache: conda clean --all

  3. Try creating the environment again

Import errors#

If you get import errors when running Python:

  1. Make sure the environment is activated: conda activate engiai

  2. Verify you’re in the project root directory

  3. Try reinstalling: pip install -e .

Pre-commit hooks fail#

If pre-commit hooks are causing issues:

  1. Update pre-commit: pre-commit autoupdate

  2. Run manually: pre-commit run --all-files

  3. If still failing, temporarily skip: git commit --no-verify

Getting Help#

If you encounter issues not covered here:

  1. Check Troubleshooting Guide

  2. Check existing GitHub Issues

  3. Open a new issue with:

    • Your operating system

    • Python version (python --version) or Docker version

    • Error messages

    • Steps to reproduce

Next Steps#