File size: 2,773 Bytes
19f0c1b f8983c1 19f0c1b 7befb8f 19f0c1b f8983c1 7befb8f f8983c1 7befb8f f8983c1 7befb8f f8983c1 7befb8f f8983c1 7befb8f f8983c1 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 | ---
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`.
|