README.md

---
title: HiveTrace Leaderboard
emoji: 🛡️
colorFrom: green
colorTo: indigo
sdk: docker
app_port: 5173
pinned: true
short_description: HiveTrace leaderboard frontend
tags:
  - leaderboard
  - sveltekit
  - docker
---

# HiveTrace Leaderboard frontend

## Overview

HiveTrace Leaderboard is a SvelteKit frontend for browsing guardrail benchmark results from
a private Hugging Face bucket.

The app uses:

- [SvelteKit](https://svelte.dev/)
- [pnpm](https://pnpm.io/) `11.9.0`
- [shadcn-svelte](https://www.shadcn-svelte.com/) and
  [shadcn-svelte-extras](https://www.shadcn-svelte-extras.com/)
- [Tailwind CSS](https://tailwindcss.com/)
- [Paraglide JS](https://inlang.com/m/gerre34r/library-inlang-paraglideJs) for localization

## Requirements

- Node.js `20.19.5` or newer
- pnpm `11.9.0`

## Setup

From the project root:

```bash
pnpm install
```

Create a local `.env` file from the example:

```bash
cp .env.example .env
```

Then configure a read token with access to the private Hugging Face bucket.

Required server-only environment variables:

```env
HF_TOKEN=hf_...
HF_BUCKET_ID=...
HF_BUCKET_PREFIX=latest
```

Do not rename `HF_TOKEN` to `PUBLIC_HF_TOKEN`. The token is used only on the SvelteKit server.
In production, pass it as a runtime secret, not as a Docker build argument.

## Public exports

The Space exposes stable export URLs for automation and pipelines. These URLs are public and can
be fetched with `curl` without passing a token:

```bash
curl -L "https://<space-domain>/exports/ranking.csv"
curl -L "https://<space-domain>/exports/ranking.json"
curl -L "https://<space-domain>/exports/details-matrix.csv"
curl -L "https://<space-domain>/exports/details-matrix.json"
curl -L "https://<space-domain>/exports/tools.csv"
curl -L "https://<space-domain>/exports/tools.json"
```

The exports are generated by the SvelteKit server from the same server-side bucket access used by
the Ranking, Details, and Visualizations pages. The private Hugging Face bucket is not downloaded
directly by clients, and `HF_TOKEN` remains server-only.

The ranking export uses the default leaderboard view: all benchmarks, all models, and
`integral` descending sort. The details matrix export uses the default matrix view: `score`
metric, all groups, all models, and `integral` descending sort. The tools export uses all models
and all benchmark groups with data. Its CSV is built with the same formatter as the
Visualizations page `Export CSV` button when all models and groups are selected.

## Development

```bash
pnpm dev
```

## Validation

Before pushing, format the code, run linting, run Svelte/TypeScript checks, and verify the
production build.

Format:

```bash
pnpm format
```

Lint:

```bash
pnpm lint
```

Check Tailwind utility classes:

```bash
pnpm tailwind:check
```

Check SvelteKit, TypeScript, and Svelte components:

```bash
pnpm check
```

Build:

```bash
pnpm build
```