From c1a6b9730f3b75ab01612cb757bca3207cabf280 Mon Sep 17 00:00:00 2001 From: marcos Date: Thu, 6 Aug 2026 03:56:58 +0000 Subject: [PATCH] docs: document the IA module README: add ia to the modules table, the four ia permissions, and a full IA section covering commands, profile switching, operator corrections, memory/context, and the key + rate-limit model. Notes the safety boundary (no tools, reply never executed, leading slashes stripped) and which config values are baked vs live. Co-Authored-By: Claude --- README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/README.md b/README.md index d2919d3..db29467 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ All player-facing text is Portuguese (pt-BR). | `enquete` | `/enquete Pergunta \| A \| B` — clickable voting with a live tally on the boss bar. | | `ranking` | `/ranking mineracao` and friends. Covers **offline players too**. | | `marcos` | Announces round milestones — 100 km walked, 24 hours played — the first time someone crosses one. | +| `ia` | `/ia ` asks an OpenAI-compatible model in chat. Optional wiki grounding, per-player memory, operator corrections. | Toggle any of them: `/canalhandia modulo ` @@ -184,6 +185,10 @@ survive a restart. | `canalhandia.forcar` | op | trigger curiosities and guess rounds | | `canalhandia.admin` | op | change modules and all settings | | `canalhandia.isento` | nobody | never be the subject | +| `canalhandia.ia` | op | `/ia` (public question, broadcast to chat) | +| `canalhandia.ia.privado` | op | `/iap` (private question, answer only to the asker) | +| `canalhandia.ia.corrigir` | op | `/ia corrigir ` — register a correction for the last answer | +| `canalhandia.ia.perfil` | op | `/ia perfil ` — switch profile live | Permissions are **declared explicitly** in `plugin.yml`. An undeclared Bukkit permission falls back to op-only, which would silently stop normal players from @@ -191,6 +196,79 @@ reacting. --- +## IA (`/ia`) + +Chat Q&A backed by an OpenAI-compatible endpoint (default MiniMax). Gated to +operator + LuckPerms-permitted players; both `/ia` and `/iap` default to op and +are granted independently, so an operator can let someone ask privately without +letting them broadcast. + +**The model can only ever produce chat text.** No tool/function definitions are +sent in the request, the reply is passed to `sendMessage` and nowhere else, and +`AiText.sanitise` strips leading slashes so a reply cannot be mistaken for a +command. A player asking it to "run `/op me`" gets a string back, not an +executed command. + +### Commands + +| Command | What it does | +|---|---| +| `/ia ` | Asks the model. Public by default — the question and answer broadcast. Needs `canalhandia.ia`. | +| `/iap ` | Asks privately — the answer goes only to the asker. Needs `canalhandia.ia.privado`. | +| `/ia perfil ` | Switches profile live. `ECONOMICO` skips the wiki (fast); `PRECISO` consults the Minecraft Wiki (slower, grounded). Needs `canalhandia.ia.perfil`. | +| `/ia corrigir ` | Records a correction for the last answered question. Future similar questions get it as context — the cheap alternative to fine-tuning. Needs `canalhandia.ia.corrigir`. | +| `/ia feedback ruim` | Flags the last answer wrong (in-memory counter shown in `/canalhandia status`). | +| `/errado` | The `[ERRADO]` reaction to the last message — the typed-twin of the reaction button, for Bedrock players. | + +Subcommands only hijack when their second token is one they act on (a known +profile key, or `ruim`), so `/ia perfil do servidor` falls through and is asked. +`corrigir` stays greedy — a correction always reads the rest of the line. + +### Profile + +`ECONOMICO` skips the wiki round trip — fast, ungrounded. `PRECISO` runs a +forced tool call to pick a wiki term, looks it up on pt.minecraft.wiki, and +injects the article as context. Switch live with `/ia perfil`; the choice is +read per-question, so it takes effect immediately. + +### Operator corrections + +`/ia corrigir ` appends to `plugins/Canalhandia/correcoes.yml`. When a +new question shares at least one significant word (length > 4) with a recorded +correction, the correction is injected as system context. Pure string matching, +no model round trip. + +### Memory and context + +- **Per-player memory**: the last `memoria-perguntas` exchanges within + `memoria-minutos` are replayed, for follow-ups like "e no nether?". Forgotten + on quit. Baked at construction; not hot-swappable. +- **Server context**: the `contexto:` list in `config.yml` is facts the model + would never know (server name, Bedrock prefix, installed mods). Sent on every + question. +- **Recipes**: `RecipeBook` snapshots `Bukkit.recipeIterator()` at enable (main + thread) and answers recipe questions from that snapshot — `explaintext` drops + tables, so the wiki cannot supply them. + +### Keys and limits + +The API key never lives in `config.yml` (committed to git). Read from the +`MINIMAX_API_KEY` env var, or `plugins/Canalhandia/minimax.key` (one line, +printable ASCII only — control chars are stripped so a stray newline can't +land the key in a server-log header exception). + +Per-player cooldown (`cooldown-segundos`), a server-wide daily cap +(`limite-diario`), and a one-question-at-a-time guard per player keep the +token spend bounded. `canalhandia.admin` skips the cooldown. + +The four values `url`, `wiki-caracteres`, `memoria-perguntas` and +`memoria-minutos` are baked at construction. Everything else — `modelo`, +`max-tokens`, `temperatura`, `instrucoes`, `perfil`, `contexto`, the limits — +is read live, so operators can hot-swap them with `/canalhandia reload` or the +`/ia perfil` command without a restart. + +--- + ## Building Requires **JDK 25**. Paper 26.2's API ships Java 25 class files, and JDK 21 fails