# Installation

One-time setup to run ollama-forge and optional components (llama.cpp for finetune/quantize).

---

## Requirements

- **Python 3.10+**
- **[uv](https://docs.astral.sh/uv/)** (recommended) or pip
- **[Ollama](https://ollama.com)** — install and ensure `ollama` is on your PATH

---

## Install ollama-forge

**From the repo (development):**

```bash
uv sync
uv run ollama-forge --help
```

**Install globally (run from anywhere):**

```bash
# With uv (from repo)
uv tool install .

# Or with pip (development install)
pip install -e .
```

Then run `ollama-forge` from any directory.

---

## Verify environment

**Quick check** — see what's installed (ollama, Hugging Face, optional deps, llama.cpp):

```bash
uv run ollama-forge check
```

**Diagnose and fix** — guided diagnosis with optional auto-fix:

```bash
uv run ollama-forge doctor
uv run ollama-forge doctor --fix          # apply safe fixes
uv run ollama-forge doctor --fix --plan   # preview fixes only
uv run ollama-forge doctor --fix-llama-cpp  # also run setup-llama-cpp when finetune/quantize missing
```

Doctor reports:

- **ollama** — must be on PATH
- **huggingface_hub** — required for fetch/fetch-adapter
- **pyyaml** — required for recipes
- **HF_TOKEN** — optional; needed for gated/private Hugging Face repos
- **abliterate deps** — optional; for refusal removal (`uv sync --extra abliterate`)
- **llama.cpp finetune** — optional; for training pipeline
- **llama.cpp quantize** — optional; for `convert --quantize` (accepts `quantize` or `llama-quantize` on PATH)

**Hugging Face downloads** use the fast backend (`hf-transfer`) by default.

---

## Optional: llama.cpp (finetune & quantize)

If you want to:

- **Quantize** a GGUF before creating an Ollama model (`convert --quantize Q4_K_M`)
- **Run the training script** generated by `train --write-script` (finetune step)

then install llama.cpp:

```bash
uv run ollama-forge setup-llama-cpp
```

This clones and builds llama.cpp. **Add the build directory to your PATH** (the command prints the exact path). For example:

```bash
export PATH="/path/to/llama.cpp/build/bin:$PATH"
```

Then run `ollama-forge check` again; finetune and quantize should show as OK.

---

## Gated / private Hugging Face models

Set your token so the tool can download gated or private repos:

```bash
export HF_TOKEN=your_token
# or
export HUGGING_FACE_HUB_TOKEN=your_token
```

Or run `huggingface-cli login`.
