docs/HUGGING_FACE.md

# Use the Private Hugging Face Repository

Repository: `tahsinsoyak/fugu-lite`

The Hub repository is private. An account must be granted access and authenticate before it
can download the project. The Hugging Face token and the OpenRouter API key are separate
credentials and must never be committed.

## Download on a server

Install the Hugging Face CLI and sign in with a read token:

```bash
python -m pip install --upgrade huggingface_hub
hf auth login
```

Download the complete private snapshot:

```bash
hf download tahsinsoyak/fugu-lite \
  --repo-type model \
  --local-dir fugu-lite
cd fugu-lite
```

For an automated server, store `HF_TOKEN` in the server's secret manager or protected
environment instead of placing it in a script or repository.

## Install

Fugu-Lite supports Python 3.10-3.13. Python 3.12 is the recommended environment used for
the verified V1 workflow.

With `uv`:

```bash
uv sync --frozen --extra dev --python 3.12
uv run fugu-lite doctor
uv run pytest -q
```

With a standard virtual environment:

```bash
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'
fugu-lite doctor
pytest -q
```

## Route without an OpenRouter call

The saved ES checkpoint can select a worker without sending the prompt to a worker API:

```bash
uv run fugu-lite route \
  --checkpoint artifacts/router-es-real-v1 \
  --domain reasoning \
  --prompt "Explain the likely cause of this failure."
```

The checkpoint contains only the trained routing head and tokenizer. The first run may also
download the public `Qwen/Qwen3-0.6B` backbone referenced by its router configuration.

## Route and call a worker

Create a protected local environment file:

```bash
cp .env.example .env
chmod 600 .env
```

Set `OPENROUTER_API_KEY` inside `.env`, then run:

```bash
uv run fugu-lite ask \
  --checkpoint artifacts/router-es-real-v1 \
  --workers configs/workers.real-cheap.yaml \
  --domain code \
  --prompt "Find the bug in this Python function."
```

The configured OpenRouter model IDs describe the V1 experiment. Check current provider
availability before starting a new paid data-generation run.

## Download from Python

```python
from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="tahsinsoyak/fugu-lite",
    repo_type="model",
    local_dir="fugu-lite",
    token=True,
)
```

`token=True` uses the token already saved by `hf auth login`.

## Update the private repository

From the project root, after authenticating with a write token:

```bash
hf upload tahsinsoyak/fugu-lite . . \
  --repo-type model \
  --private \
  --exclude ".git/*" ".venv/*" ".env" ".pytest_cache/*" ".ruff_cache/*" \
  --commit-message "Update Fugu-Lite snapshot"
```

Keep the repository private because the saved V1 reward file includes benchmark prompts,
complete worker responses, generation IDs, costs, latency, and token-usage records. Review
benchmark and tokenizer redistribution terms before changing its visibility.