---
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`.