| --- |
| 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** |
| ```json |
| { "status": "Vex AI is Online" } |
| ``` |
|
|
| ### `POST /chat` |
| Send a message (optionally with server context prepended) and get a reply. |
|
|
| **Request** |
| ```json |
| { "message": "Online players: Xirrik, Steve\n\nQuestion: who's online?" } |
| ``` |
|
|
| **Response** |
| ```json |
| { "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** |
| ```json |
| { "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`. |
|
|
