README.md

metadata

title: Vex AI
emoji: 🗡️
colorFrom: purple
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false

Vex AI

Vex is the AI assistant for the Vex SMP Minecraft server, built by Xirrik. It runs as a small FastAPI service on Hugging Face Spaces (Docker SDK) and is called from a Paper plugin to answer player questions in chat — including live server context like online players, stats, and economy balances when the plugin includes them in the request.

Powered by Qwen/Qwen2.5-7B-Instruct via the Hugging Face Inference API.

Endpoints

GET /

Health check.

Response

{ "status": "Vex AI is Online" }

POST /chat

Send a message (optionally with server context prepended) and get a reply.

Request

{ "message": "Online players: Xirrik, Steve\n\nQuestion: who's online?" }

Response

{ "reply": "Right now it's just Xirrik and Steve holding down the fort." }

If the underlying model is still spinning up, /chat returns a friendly "waking up, try again in 10 seconds" reply instead of erroring out, so the Minecraft plugin can just relay reply straight to chat either way.

POST /chat/stream

Same request body as /chat, but streams the reply as newline-delimited JSON (application/x-ndjson) instead of waiting for the full response.

Request

{ "message": "Question: tell me a fun fact about Vex SMP" }

Response body (streamed, one JSON object per line)

{"token": "Did"}
{"token": " you"}
{"token": " know"}
...
{"done": true}

On failure, a single {"error": "..."} line is sent instead.

This is mainly useful if you build a web dashboard or want lower time-to-first-token over HTTP. Vanilla Minecraft chat has no typing indicator, so for the Paper plugin itself, plain /chat is usually simpler — use /chat/stream only if you specifically want to render partial text (e.g. an action bar or bossbar that updates as tokens arrive).

Setup

1. Create a new Space on Hugging Face → SDK: Docker.
2. Upload app.py, requirements.txt, Dockerfile, and this README.md.
3. In the Space's Settings → Repository secrets, add:
   • HF_TOKEN — a Hugging Face access token with Inference API permissions.
4. The Space builds automatically and serves on port 7860.
5. Your public endpoint will be: https://<your-username>-vex-ai.hf.space/chat

Notes

• The service is stateless — it has no memory between requests. If you want Vex to "remember" a conversation, the calling plugin must include prior turns as part of message.
• CORS is wide open (*) so it can be called from anywhere, including directly from a Paper server's backend HTTP client.
• To change Vex's personality, edit SYSTEM_PROMPT in app.py.