> ## Documentation Index
> Fetch the complete documentation index at: https://fairforge.alquimia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install Fair Forge and its dependencies

# Installation

Fair Forge uses a modular dependency system, allowing you to install only the components you need.

## Requirements

* Python 3.10 or higher
* [uv](https://docs.astral.sh/uv/) (recommended) or pip

## Basic Installation

<CodeGroup>
  ```bash uv (Recommended) theme={null}
  uv add alquimia-fair-forge
  ```

  ```bash pip theme={null}
  pip install alquimia-fair-forge
  ```
</CodeGroup>

## Optional Dependencies

Fair Forge provides optional dependency groups for each metric and feature:

### Metrics

| Extra            | Description                      | Dependencies                               |
| ---------------- | -------------------------------- | ------------------------------------------ |
| `toxicity`       | Toxicity metric with clustering  | sentence-transformers, hdbscan, umap-learn |
| `bias`           | Bias metric with guardian models | openai, transformers                       |
| `context`        | Context metric with LLM judge    | langchain-core                             |
| `conversational` | Conversational metric            | langchain-core                             |
| `humanity`       | Humanity metric with NRC lexicon | (included in core)                         |
| `bestof`         | BestOf tournament metric         | langchain-core                             |

### Features

| Extra                 | Description                      | Dependencies                 |
| --------------------- | -------------------------------- | ---------------------------- |
| `generators`          | Synthetic dataset generation     | langchain-core, transformers |
| `generators-alquimia` | Generators with Alquimia support | langchain-core, transformers |
| `runners`             | Test execution runners           | httpx, asyncio               |
| `cloud`               | Cloud storage backends           | lakefs-sdk                   |

### Combined Extras

| Extra | Description                                   |
| ----- | --------------------------------------------- |
| `all` | All metrics and features                      |
| `dev` | Development dependencies (pytest, ruff, mypy) |

## Installation Examples

<CodeGroup>
  ```bash Single Metric theme={null}
  # Install with toxicity metric support
  uv add "alquimia-fair-forge[toxicity]"
  ```

  ```bash Multiple Metrics theme={null}
  # Install multiple metrics
  uv add "alquimia-fair-forge[toxicity,bias,context]"
  ```

  ```bash Full Installation theme={null}
  # Install everything
  uv add "alquimia-fair-forge[all]"
  ```

  ```bash Generators + Runners theme={null}
  # Install for test generation and execution
  uv add "alquimia-fair-forge[generators,runners]"
  ```
</CodeGroup>

## LLM Provider Dependencies

Several metrics require LangChain-compatible chat models. Install your preferred provider:

<CodeGroup>
  ```bash Groq (Fast & Free Tier) theme={null}
  uv add langchain-groq
  ```

  ```bash OpenAI theme={null}
  uv add langchain-openai
  ```

  ```bash Google Gemini theme={null}
  uv add langchain-google-genai
  ```

  ```bash Anthropic theme={null}
  uv add langchain-anthropic
  ```

  ```bash Ollama (Local) theme={null}
  uv add langchain-ollama
  ```
</CodeGroup>

## Development Installation

For contributing to Fair Forge:

```bash theme={null}
# Clone the repository
git clone https://github.com/Alquimia-ai/fair-forge.git
cd fair-forge

# Install with development dependencies
uv sync

# Run tests
uv run pytest

# Run linting
uv run ruff check .
uv run ruff format .

# Run type checking
uv run mypy fair_forge
```

## Verifying Installation

```python theme={null}
import fair_forge

# Check version
print(f"Fair Forge version: {fair_forge.__version__}")

# Verify imports
from fair_forge.metrics.toxicity import Toxicity
from fair_forge.core.retriever import Retriever
from fair_forge.schemas.common import Dataset, Batch

print("Installation successful!")
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="ImportError: No module named 'sentence_transformers'">
    Install the toxicity extras:

    ```bash theme={null}
    uv add "alquimia-fair-forge[toxicity]"
    ```
  </Accordion>

  <Accordion title="ImportError: No module named 'langchain_groq'">
    Install your preferred LLM provider:

    ```bash theme={null}
    uv add langchain-groq
    ```
  </Accordion>

  <Accordion title="CUDA/GPU issues with sentence-transformers">
    For CPU-only installation:

    ```bash theme={null}
    uv add torch --index-url https://download.pytorch.org/whl/cpu
    uv add "alquimia-fair-forge[toxicity]"
    ```
  </Accordion>

  <Accordion title="Python version incompatibility">
    Ensure you're using Python 3.10+:

    ```bash theme={null}
    python --version
    # If needed, use pyenv to install a compatible version
    pyenv install 3.11.0
    pyenv local 3.11.0
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Run your first evaluation
  </Card>

  <Card title="Core Concepts" icon="lightbulb" href="/core-concepts/architecture">
    Understand the architecture
  </Card>
</CardGroup>