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:

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

Download the complete private snapshot:

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:

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

With a standard virtual environment:

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:

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:

cp .env.example .env
chmod 600 .env

Set OPENROUTER_API_KEY inside .env, then run:

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

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:

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.