Skip to content

Installation Guide

This guide provides comprehensive installation instructions for GAICo, including optional dependencies, Jupyter setup, and developer installation. Use the table of contents in the left sidebar to navigate.

Basic Installation

GAICo can be installed using pip.

Create and activate a virtual environment:

python3 -m venv gaico-env
source gaico-env/bin/activate  # On macOS/Linux
# gaico-env\Scripts\activate   # On Windows

Install GAICo:

pip install gaico

This installs the core GAICo library with essential metrics.

Optional Dependencies

Optional dependencies for specialized metrics:

pip install 'gaico[audio]'                       # Audio metrics
pip install 'gaico[bertscore]'                   # BERTScore metric
pip install 'gaico[cosine]'                      # Cosine similarity
pip install 'gaico[jsd]'                         # JS Divergence
pip install 'gaico[audio,bertscore,cosine,jsd]'  # All features

Using GAICo with Jupyter Notebooks/Lab

If you plan to use GAICo within Jupyter Notebooks or JupyterLab (recommended for exploring examples and interactive analysis), install them into the same activated virtual environment:

# (Ensure your 'gaico-env' is active)
pip install notebook  # For Jupyter Notebook
# OR
# pip install jupyterlab # For JupyterLab

Then, launch Jupyter from the same terminal where your virtual environment is active:

# (Ensure your 'gaico-env' is active)
jupyter notebook
# OR
# jupyter lab

New notebooks created in this session should automatically use the gaico-env Python environment.

Troubleshooting Jupyter Kernels

If your notebooks don't recognize the GAICo installation:

  1. Install ipykernel in your virtual environment: 

    pip install ipykernel

  2. Register the environment as a Jupyter kernel: 

    python -m ipykernel install --user --name=gaico-env --display-name "Python (gaico-env)"

  3. Select the kernel in Jupyter:

  4. In Jupyter Notebook: Kernel → Change Kernel → Python (gaico-env)
  5. In JupyterLab: Click the kernel name in the top-right corner and select Python (gaico-env)

For more troubleshooting, see our FAQ.

Installation Size Comparison

The following table provides an estimated overview of the relative disk space impact of different installation options. Actual sizes may vary depending on your operating system, Python version, and existing packages. These are primarily to illustrate the relative impact of optional dependencies.

Note: Core dependencies include: levenshtein, matplotlib, numpy, pandas, rouge-score, and seaborn.

Installation Command Dependencies Estimated Total Size Impact
pip install gaico Core 215 MB
pip install 'gaico[audio]' Core + scipy, soundfile 330 MB
pip install 'gaico[bertscore]' Core + bert-score (includes torch, transformers, etc.) 800 MB
pip install 'gaico[cosine]' Core + scikit-learn 360 MB
pip install 'gaico[jsd]' Core + scipy, nltk 310 MB
pip install 'gaico[audio,jsd,cosine,bertscore]' Core + all dependencies from above 1.0 GB

Managing Installation Size

If disk space is a concern, install only the optional dependencies you need. You can always add more later using pip install 'gaico[feature]'.

Developer Installation

If you want to contribute to GAICo or install it from source for development:

  1. Clone the repository:

    git clone https://github.com/ai4society/GenAIResultsComparator.git
cd GenAIResultsComparator

  2. Set up a virtual environment and install dependencies:

    We recommend using UV for fast environment and dependency management.

    # Create a virtual environment (Python 3.10-3.12 recommended)
uv venv
# Activate the environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
# Install in editable mode with all development dependencies
uv pip install -e ".[dev]"

    # Create a virtual environment (Python 3.10-3.12 recommended)
python3 -m venv .venv
# Activate the environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
# Install the package in editable mode with development extras
pip install -e ".[dev]"

    The dev extra installs GAICo with all optional features, plus dependencies for testing, linting, and documentation.

  3. Set up pre-commit hooks (recommended for contributors):

    Pre-commit hooks help maintain code quality by running checks automatically before you commit.

    pre-commit install

For more information on development workflows, see our Developer Guide.

Common Installation Issues

Import Errors After Installation

If you get import errors after installing GAICo:

  1. Verify installation: pip list | grep gaico
  2. Check you're in the correct virtual environment
  3. Try reinstalling: pip install --force-reinstall gaico

Dependency Conflicts

If you encounter dependency conflicts:

  1. Create a fresh virtual environment
  2. Install GAICo first before other packages
  3. If conflicts persist, see our FAQ for potential solutions

Platform-Specific Issues

  • Windows: Use gaico-env\Scripts\activate to activate the virtual environment
  • macOS/Linux: Use source gaico-env/bin/activate
  • M1/M2 Macs: Some dependencies may need Rosetta. See FAQ for details.

Next Steps