How to register Your Artificial Gladiator

A step-by-step guide to registering your Artificial Gladiator (AG) to the Artificial Gladiator League (AGL) platform — from bringing to life your AG to gladiating with your AG in games and tournaments.

1
Bringing to life Your AG
2
Create Repos
3
Prove Ownership
4
Register
5
Compete
1

Bringing to life your AG

Your AG is a Python brain that receives a board position and returns a legal move string. The logic inside is entirely up to you — Monte Carlo Vector Search (MCVS), random play, minimax, MCTS, a neural network, or anything else. The recommended integration is a Gradio Space hosted on Hugging Face: easy to deploy, easy to debug, and no server to manage on your end.

Interface 1 — Gradio Space (Recommended)

Deploy a Gradio app on Hugging Face Spaces. The platform calls your Space's get_move function over HTTP on every move — no server to manage on your end. Your function receives the board position and the active player, and returns a move string.

# app.py — in your Gradio Space repo
import gradio as gr
# The platform sends the board position (and optionally the active player).
# Return your chosen move as a string in the format the game expects.
def get_move(position: str, player: str) -> str:
# ---- your AI logic here ----
# minimax, MCTS, neural net, opening table — whatever you like
return "e2e4" # return a valid move string
gr.Interface(
fn=get_move,
inputs=["text", "text"],
outputs="text",
api_name="get_move", # ← required
).launch()
# requirements.txt — Space root
gradio
torch # add any framework you need
numpy
  • ✓api_name="get_move" is required — the platform posts to /gradio_api/call/get_move
  • ✓The Space must remain Public and running while your matches are scheduled
  • ✓You choose the hardware tier — upgrade for heavier models (GPU Spaces supported)
Advanced option — Direct Python Handler: For lower-latency scenarios or when you need tight control over the local runtime, the platform also supports a class-based EndpointHandler interface executed directly in a sandboxed environment without a Gradio Space. Full documentation for this interface will be published separately.
Any algorithm is welcome. Monte Carlo Vector Search (MCVS), Minimax, alpha-beta pruning, MCTS, policy networks, value networks, reinforcement learning, opening books, endgame tablebases, hybrid approaches — if it returns a valid move string within the time limit, it qualifies.
2

Create Your Hugging Face Repositories

You need up to three resources on Hugging Face — a model code repo, a data repo, and (for the Gradio interface) a Space. Each has a different visibility requirement explained below.

Repo 1 — Model Repository (HF Model repo)

Contains your Artificial Gladiator code files and a config_model.json that lists all Python files and the entry-point module.

🔒 Strongly recommended: Gated (Access Requests). A Gated repo requires visitors to request access before downloading any files — protecting your Artificial Gladiator code from being copied. The platform only checks the public file listing during ownership verification; it never downloads your source for Gradio-interface bots. Go to your repo's Settings → Access Control → Gated to enable it.

Important: once Gated, you must grant access to the platform's Hugging Face account ArtificialGladiatorLeague so it can read your file listing during verification. Without this grant, ownership checks will fail even if the verification code is correct.
Suggested layout:
your-username/my-bot/
├── config_model.json ← required
├── my_model.py ← your AI code (EndpointHandler class goes here)
├── utils.py ← optional helper modules
├── requirements.txt ← pip dependencies (EndpointHandler only)
└── AGL_VERIFY.txt ← added in Step 3
config_model.json
{
"files": ["my_model.py", "utils.py"],
"main": "my_model"
}

main is the module filename without .py — this is the module that contains your EndpointHandler class. If using the Gradio interface, only the file listing is read during ownership verification; your code is never downloaded.

Repo 2 — Data Repository (HF Dataset repo)

Optional, but required if your Artificial Gladiator uses runtime data files — opening books, precomputed tables, trained weights, zone databases, etc.

⚠️ Must be fully Public — no exceptions. The platform's servers pull your data files using anonymous HTTP requests with no user token. A private, gated, or restricted repo will return a 401/403 error and your Artificial Gladiator will be unable to gladiate any matches.
Example layout:
your-username/my-bot-data/
├── config_data.json ← required
├── weights.pt ← trained model weights
└── openings.npz ← precomputed lookup table
config_data.json
{
"files": ["weights.pt", "openings.npz"]
}

List every file you need downloaded. For EndpointHandler bots, they are placed in a local cache directory whose path is passed to __init__(self, path). For Gradio Artificial Gladiators, load them yourself inside your Space (e.g. from the HF Hub using huggingface_hub.hf_hub_download).

Repo 3 — Gradio Space (HF Space — required for Interface 1)

The platform calls your Artificial Gladiator over HTTP using the Gradio 4 SSE API. On each move it posts to /gradio_api/call/get_move on your Space's subdomain and streams the response.

⚠️ Must be fully Public — no exceptions. The platform posts to your Space's HTTP API with no authentication token. A private or sleeping Space will cause the move request to fail or time out, forfeiting the turn.
Required layout:
your-username/my-bot-space/
├── app.py ← Gradio app exposing get_move()
└── requirements.txt ← gradio + all dependencies

After deploying, copy the Space's public subdomain (e.g. your-username-my-bot-space.hf.space) and paste it as the HF Space Link when registering your Artificial Gladiator.

Example:

Create and publish your three Hugging Face repositories here: Model repo , Data repo

The Model repo is based on the paper, Graph Game Theory: An Algebraic Approach for General Game Playing .

After deploying, copy the Space’s public subdomain and paste it as the HF Space Link when registering your AG.

3

Prove Ownership & SHA Pinning

Before your AG can gladiate, you must prove you own the repository. The platform also pins the commit SHA to detect any changes during tournaments.

Ownership Verification (one-time per repo)

  1. 1 Register your repo on the AG Champion page. The platform generates a unique 32-character verification code.
  2. 2 Create a file named AGL_VERIFY.txt at the root of your HF model repo containing exactly the verification code — no trailing whitespace or extra characters.
  3. 3 Click "Verify Ownership". The platform downloads and checks the file. Once confirmed, you're cleared to gladiate.

SHA Pinning (ongoing)

  • ▸At tournament registration — the exact commit SHA of your model repo is recorded.
  • ▸During each round — the SHA is re-checked dozens of times. Any commit since registration triggers automatic disqualification.
⚠️ Do not push changes to your AG Champion repo after joining a tournament. SHA mismatch = automatic disqualification.
✅ No Hugging Face token required. All checks use public repo access — no credentials needed from you.
4

Register Your AG Champion in the Platform

Go to Profile → AG Champions and fill in the repo details for each game type you want to gladiate.

Fields per game type
  • ▸AG Champion Repo ID — username/my-AG — your Artificial Gladiator code repository
  • ▸Data Repo ID — username/my-AG-data — your data repository (leave blank if not used)
  • ▸HF Space Link — username-my-AG-space.hf.space — your Gradio Space subdomain (Gradio interface only)
⚠️ After registering, you need 30 rated games to gladiate with your AG Champion before you can enter tournaments. Changing your repo IDs resets this counter.
5

Compete in Games & Tournaments

Quick Matches

Head to the Lobby, challenge another player. Your AG Champion plays automatically in real time. Results update your Elo.

Tournaments

Browse open tournaments, register, play 30 rated games to qualify, mark yourself Ready. The system schedules and runs all matches automatically.

How a move is generated
Board FEN sent → Gradio Space get_move called → Move validated → Game state updated

Each call has a strict time limit. Exceeding it forfeits the move. Keep inference fast.

Best Practices

Pre-load at startup

Load models, weights, and opening books in __init__ (EndpointHandler) or at module level (Gradio Space). Never load files inside get_move — cold load time counts against your move clock.

⏱ Respect the time limit

The platform enforces a per-move timeout. Budget your search depth or inference time accordingly. Returning a random legal move as a fallback avoids timeouts that would forfeit the game entirely.

Avoid cold starts

Hugging Face Spaces can go to sleep after inactivity. Use the Always On option if available on your plan, or periodically ping your Space to keep it warm and prevent the first move from timing out.

Pin your dependencies

Use exact version pins in requirements.txt (e.g. torch==2.2.0) to prevent breakage from upstream updates between tournament rounds.

Validate move format

Always return a valid move string. Invalid or empty responses are treated as illegal moves and may result in a forfeited turn. Check the expected move format for the game type in the Lobby.

Test before tournaments

Gladiate several quick matches in the Lobby to confirm your AG Champion responds correctly at game speed before entering a tournament. The 30-game qualification window is the ideal calibration period.

Troubleshooting

Move timed out / AG forfeited the turn
  • ▸Your Space may have been sleeping — enable Always On or warm it up before matches start.
  • ▸Inference is too slow — reduce search depth, switch to a lighter model, or pre-cache results.
  • ▸Check the Space logs on Hugging Face for Python errors or out-of-memory crashes.
Ownership verification failed
  • ▸Ensure AGL_VERIFY.txt is at the root of your model repo — not inside a subfolder.
  • ▸The file content must match exactly — no trailing newline, no extra spaces.
  • ▸The model repo must be Public or Gated — if Gated, you must have granted access to ArtificialGladiatorLeague on Hugging Face.
Disqualified — SHA mismatch
  • ▸You pushed a commit to your AG Champion repo after registering for the tournament.
  • ▸Even trivial changes (README edits, whitespace) produce a new SHA. Freeze the repo once registered.
Invalid move returned
  • ▸Confirm your move string matches the expected format for the game (UCI for Chess, coordinate string for Breakthrough).
  • ▸Make sure you return a plain string — not a list, not a JSON object, not {"move": "..."}.
Data files not loading
  • ▸Confirm your data repo is fully Public on Hugging Face — gated or private repos cannot be downloaded by the platform.
  • ▸Check that filenames in config_data.json match exactly (case-sensitive) the filenames in your repo.

Frequently Asked Questions

Can I use PyTorch, TensorFlow, JAX, scikit-learn, or any other ML framework?

Yes. List all pip packages in requirements.txt. They are installed in your Gradio Space (or local sandbox for EndpointHandler AG Champions) before your code runs.

What game types are supported?

Currently Chess and Breakthrough. Each game is registered independently, so you can enter different AG Champions for each.

Do I need a Hugging Face account?

Yes — to create repos and deploy a Space. No HF API token is required by the platform; all access is anonymous via public resources.

Can I update my AG Champion between games (outside tournaments)?

Yes, you can update your AG Champion or change your repository links outside of tournaments. However, any change to your AG Champion's Repo, Data Repo, or HF Space Link will reset your rated games counter. You will need to play another 30 rated games before you can enter tournaments again.

Should my AG Champion's model repo be Gated?

Yes. Gated (Access Requests) is recommended to protect your AG Champion from misusing it by other human users. The platform only reads the file listing for verification — it does not download your source files for Gradio-interface AG Champions. However, you must grant access to the ArtificialGladiatorLeague Hugging Face account so the platform can read that listing; without this, ownership verification will fail.

Why must the data repo and Space be fully Public?

The platform's servers make anonymous HTTP requests to both. No user token is passed. Private or gated access on these resources will cause failures at match time.

Which interface should I choose — Gradio Space or EndpointHandler?

Start with the Gradio Space. It's easier to deploy, easier to debug (logs are visible on HF), and you control the hardware tier. Use EndpointHandler only if you need sandbox-level control or have specific platform-integration requirements.

Why do I need 30 rated games before entering tournaments?

It establishes a meaningful Elo rating and confirms your AG Champion is stable and reliably responsive before entering structured competition.

How strict is the per-move time limit?

Exceeding the limit forfeits the move. The exact time depends on the game and match settings — check the Lobby or tournament details. Always implement a fast fallback (e.g. a random legal move) so your bot never times out completely.

What ranking titles are used on the AGL platform?

AGL titles are based on the FIDE Elo scale. Your AG Champion earns a title automatically as its Elo rating climbs — separately for Chess and Breakthrough.

Title Elo range
Super GM2700+
Grandmaster2500–2699
Intl. Master2400–2499
FIDE Master2300–2399
Cand. Master2200–2299
Expert2000–2199
Class A1800–1999
Class B1600–1799
Class C1400–1599
Class D1200–1399
Beginner< 1200

Ready to enter the arena?

Go to AG Champions Go to Lobby