{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreifwnhpdrb5qzna7cqca2ueu6xbuwhu3rkhgnbze46vst6bmiazlmq",
    "uri": "at://did:plc:pgryn3ephfd2xgft23qokfzt/app.bsky.feed.post/3midbre3tbjo2"
  },
  "path": "/t/artificial-gladiator-league-a-platform-where-anyone-can-compete-with-their-hf-models-in-chess-and-breakthrough/174822#post_2",
  "publishedAt": "2026-03-31T01:09:37.000Z",
  "site": "https://discuss.huggingface.co",
  "tags": [
    "encounter 429 errors",
    "OAuth",
    "Hugging Face"
  ],
  "textContent": "> Feedback on how we are using the HF Hub API — are there better approaches? Things I should know?\n\nYou’re likely to encounter 429 errors when making frequent API calls or polling repositories. There are also some nuances regarding authentication (if applicable, I recommend using OAuth with a Read or Fine-grained token).\n\n* * *\n\nYour current approach is **directionally good** , but I would change the design in a few important ways.\n\n## What you are getting right\n\nUsing the Hub as a **provenance layer** is the right instinct. Hugging Face repos are Git-backed repositories, and the Hub API exposes the pieces you need to reason about a submission as a concrete artifact: repo metadata, refs, commits, and revision-pinned downloads. That is a strong foundation for a competition platform. (Hugging Face)\n\nYour idea of tying a competitor to a specific Hub repo and refusing to treat silent model changes as “the same entrant” is also sound. The main improvement is to move from **change detection** to **exact revision execution**. HF supports loading by `revision`, and that revision can be a branch, tag, or full commit hash. (Hugging Face)\n\n## The first thing I would change\n\nStop making **daily token pasting** the main user ritual.\n\nHugging Face supports **OAuth / OpenID Connect** for “Sign in with Hugging Face,” including **public OAuth apps without a client secret**. It also exposes scopes such as `openid`, `profile`, `read-repos`, `gated-repos`, and `webhooks`, and the docs explicitly say to follow least privilege and request only the scopes you actually need. (Hugging Face)\n\nSo the better pattern is:\n\n  * use **HF OAuth** for login and identity\n  * request `read-repos` only if you need access to personal repos\n  * request `gated-repos` only if you want to support public gated repos the user already has access to\n  * request `webhooks` only if your app will manage HF webhooks on the user’s behalf. (Hugging Face)\n\n\n\nThat gives you a much better user experience and a cleaner security story than repeated raw-token entry. (Hugging Face)\n\n## The second thing I would change\n\nDo not anchor the system only to a “baseline SHA.” Store a fuller submission identity:\n\n  * `repo_id`\n  * `repo_type`\n  * `submitted_ref` such as a release tag or competition branch\n  * `approved_full_sha`\n  * `submitted_by_user`\n  * `pinned_at`\n  * `runtime_profile`\n\n\n\nThe reason is simple. Branches and tags are useful for human workflow. The **full SHA** is useful for immutability. HF’s `list_repo_refs()` returns branches and tags with their `target_commit`, and `snapshot_download()` supports loading the exact revision you approved. (Hugging Face)\n\n## The third thing I would change\n\nTreat every rated submission as a **pinned release artifact** , not as “whatever is currently in the repo.”\n\nA stronger flow is:\n\n  1. user links a repo\n  2. user selects a release tag or competition branch\n  3. you resolve that to an exact full SHA\n  4. every rated match runs from that exact revision\n  5. if the repo changes later, that creates a **new revision candidate** , not a silent modification of the old one. (Hugging Face)\n\n\n\nThat makes your fairness claim much stronger. Instead of saying “we check if the model changed,” you can say “this match was run from this exact immutable revision.” (Hugging Face)\n\n## The specific HF API calls I would use\n\nFor repo access validation, use **`auth_check()`** first. It is built for exactly this and distinguishes between a repo that is missing or inaccessible and a gated repo the user is not authorized to access. That is much cleaner than building custom guesswork around 404s. (Hugging Face)\n\nFor resolving tags and branches, use **`list_repo_refs()`**. It returns both branches and tags, and each ref includes a `target_commit`. That is the cleanest way to turn a human-readable release marker into a concrete SHA. (Hugging Face)\n\nFor revision history, use **`list_repo_commits()`**. It returns commit objects, supports a `revision` argument, and is useful for audit trails, “what changed since last approved revision,” and moderation tooling. (Hugging Face)\n\nFor repo metadata at a specific revision, use **`model_info(repo_id, revision=..., securityStatus=True)`**. That gives you per-revision metadata and lets you ask for security status information. (Hugging Face)\n\nFor materializing the exact artifact for rated play, use **`snapshot_download(repo_id, revision=approved_full_sha, ...)`** or `hf_hub_download()` for specific files. That is the point where your competition layer becomes reproducible. (Hugging Face)\n\n## One terminology fix\n\nI would stop calling it an **API key** and call it a **User Access Token**. That is HF’s terminology, and the token docs are explicit that user access tokens are the preferred way to authenticate an application or notebook to Hugging Face services. They also distinguish `fine-grained`, `read`, and `write` tokens. (Hugging Face)\n\nFor your use case, the default should be **fine-grained** or **read-only** , not broad write access. HF explicitly says fine-grained tokens are useful in production environments, and `read` tokens are for reading Hub content such as private repos or inference. (Hugging Face)\n\n## What to do about gated and private repos\n\nSupport them carefully.\n\nHF’s gated-model docs say gated access is granted to **individual users** , not whole organizations by default. That means your system should treat access as something the competitor personally proves, not something your platform broadly inherits. (Hugging Face)\n\nSo the clean rule is:\n\n  * the user authenticates\n  * you validate that **this user** can access **this repo**\n  * you run only what that user is entitled to submit\n  * you do not silently assume org-wide access semantics. (Hugging Face)\n\n\n\n## Use webhooks instead of aggressive polling\n\nIf you are currently thinking in terms of repeated checks before every interaction, I would reduce that and move to **event-driven change detection**.\n\nHF webhooks are publicly available and are meant to react to changes in user or organization repos. For AGL, that is a better fit than constant polling. (Hugging Face)\n\nA better pattern is:\n\n  * check once when the repo is linked\n  * pin the approved revision\n  * subscribe to repo-change events\n  * mark the linked agent as “dirty” or “new revision available” when the repo changes\n  * re-check right before a rated match starts. (Hugging Face)\n\n\n\nThat also helps operationally because HF documents Hub rate limits and recommends replacing Hub API calls with Resolver calls where possible, since resolver rate limits are higher and better optimized. The `huggingface_hub` library also has retry handling for 429s. (Hugging Face)\n\n## Separate the person from the model revision\n\nThis is a product suggestion, but it matters technically.\n\nYou should model:\n\n  * **user**\n  * **agent**\n  * **agent revision**\n\n\n\nThat way, when the repo changes, you are not saying “the player is suspended.” You are saying “revision A is historical, revision B is provisional until requalified.” That is cleaner for ratings, clearer for users, and a better match for Git-style repo history. (Hugging Face)\n\n## Require stronger metadata\n\nI would make **model cards** part of the competition contract.\n\nHF’s docs are explicit that model cards are essential for discoverability, reproducibility, and sharing, and that they should describe the model, intended uses, and limitations. (Hugging Face)\n\nFor AGL, every official submission should have at least:\n\n  * game supported\n  * interface version\n  * intended use\n  * limitations\n  * training method\n  * release notes for this revision. (Hugging Face)\n\n\n\nThat will make the platform look much more serious to technical users.\n\n## Add a benchmark layer early\n\nHF’s **Evaluation Results** feature is useful for your case. HF describes it as a decentralized system where benchmark datasets host leaderboards and model repos store evaluation scores in `.eval_results/`, which then appear on both the model page and the benchmark leaderboard. HF also notes that this feature is still a work in progress. (Hugging Face)\n\nThat suggests a good split for AGL:\n\n  * **live ladder** for excitement\n  * **benchmark suite** for reproducibility\n\n\n\nThat combination is much stronger than a live ladder alone. (Hugging Face)\n\n## My blunt suggestion on the integrity claim\n\nDo not say the entire integrity guarantee comes from commit SHAs alone.\n\nSay this instead, in substance:\n\n  * Hugging Face gives you the **version identity**\n  * AGL enforces the **competition identity**\n  * rated results are tied to an exact approved revision\n  * execution happens under your own fixed competition rules\n\n\n\nThat is a more accurate and more defensible claim. The Hub gives you strong repo and revision primitives. Your platform still has to supply the rules, runtime control, and rating logic. (Hugging Face)\n\n## My recommended final architecture\n\nI would implement the flow like this:\n\n  1. **Sign in with HF** via OAuth. Request only `openid`, `profile`, and the minimum repo scopes you actually need. (Hugging Face)\n  2. On repo link, call **`auth_check()`** and then **`model_info()`**. (Hugging Face)\n  3. Resolve the user’s chosen release tag or branch with **`list_repo_refs()`** and store the resulting **full SHA**. (Hugging Face)\n  4. Run every rated match from **`snapshot_download(... revision=approved_full_sha)`**. (Hugging Face)\n  5. Use **webhooks** to detect upstream changes and mark the agent as having a new revision candidate. (Hugging Face)\n  6. Require a **model card** and later add **evaluation results** for benchmark visibility. (Hugging Face)\n\n\n\n## Bottom line\n\nMy answer is:\n\n**Yes, your HF Hub API usage is based on the right idea.**\nThe biggest improvements are:\n\n  * switch from repeated raw-token entry to **OAuth + minimal scopes**\n  * switch from “baseline SHA check” to **exact revision pinning**\n  * use **`auth_check()`** , **`list_repo_refs()`** , **`list_repo_commits()`** , **`model_info()`** , and **`snapshot_download()`** as the core API set\n  * use **webhooks** for repo-change detection\n  * require **model cards**\n  * add **benchmark publishing** alongside the live ladder. (Hugging Face)\n\n\n\nThe single most important conceptual upgrade is this:\n\n**Do not rate “a repo.”\nRate an exact approved revision of a repo.** (Hugging Face)",
  "title": "Artificial Gladiator League — a platform where anyone can compete with their HF models in Chess and Breakthrough"
}