# TrapGPT Guide

TrapGPT est un programme TrapOS qui ecoute le chat Minecraft avec une Chat Box Advanced Peripherals, envoie les nouveaux messages a `opencode serve`, puis repond tres brievement dans le chat.

## Prerequis

- Une Chat Box Advanced Peripherals connectee au computer.
- TrapOS installe. Le package complet `trapos` inclut `trapos-ai`; sinon installe `trapos-ai` separement.
- Un serveur `opencode serve` accessible depuis ComputerCraft HTTP.
- HTTP active cote serveur Minecraft/ComputerCraft.

Voir aussi [`opencode_server_guide.md`](opencode_server_guide.md) pour lancer `opencode serve`.

## Configuration In-Game

Dans le computer qui porte la chatbox, configure l'URL du serveur opencode:

```lua
set opencc.server_url http://host:port
set opencc.username opencode
```

Si ton serveur opencode demande un mot de passe Basic Auth:

```lua
set opencc.password ton_mot_de_passe
```

TrapGPT utilise les memes settings `opencc.*` que le programme `ai`. Il profite aussi de `opencc.provider_id` et `opencc.model_id`; quand ils sont configures, `libai` utilise l'endpoint async de opencode et evite mieux les timeouts HTTP longs.

```lua
set opencc.provider_id anthropic
set opencc.model_id claude-opus-4-7
```

Settings optionnels pour TrapGPT:

```lua
set trapgpt.throttle_seconds 5
set trapgpt.max_reply_chars 160
set trapgpt.prefix TrapGPT
```

## Lancement

Depuis le shell CraftOS:

```lua
trapgpt
```

Le programme affiche:

```text
trapgpt listening
```

Ensuite, parle normalement dans le chat Minecraft. TrapGPT collecte les messages, attend le throttle, envoie les nouveaux messages au LLM, puis poste une reponse courte dans le chat.

## Comportement

- TrapGPT ecoute pour l'instant seulement les messages joueur `chat`.
- Les morts et connexions seront ajoutes plus tard.
- Les messages caches, vides, ou envoyes avec le meme nom que `trapgpt.prefix` sont ignores.
- Quand `messageUtf8` est fourni par l'evenement `chat`, TrapGPT l'utilise a la place de `message`.
- Il ne lance jamais deux appels LLM en meme temps.
- Les messages recus pendant un appel opencode sont gardes en queue.
- Si plusieurs messages sont en queue, ils sont envoyes ensemble au batch suivant.
- Si l'appel opencode echoue, la queue est conservee pour un prochain essai.
- La session opencode est separee du programme `ai`: elle utilise `trapgpt.opencc.session_id` et le titre de session `trapgpt`.
- Si le LLM repond exactement `SILENCE`, rien n'est envoye dans le chat.
- Les reponses sont tronquees a `trapgpt.max_reply_chars` caracteres.

## Redemarrer Une Session TrapGPT

Si tu veux repartir avec une nouvelle conversation opencode pour TrapGPT:

```lua
lua
require('/apis/libai')().clearSession({ sessionSettingKey = 'trapgpt.opencc.session_id' })
exit()
```

Puis relance:

```lua
trapgpt
```

## Depannage

Si `chat_box peripheral not found` apparait:

- Verifie que la Chat Box est bien collee/connectee au computer.
- En 1.21.1+, le nom de peripheral attendu est souvent `chat_box`.
- Sur anciennes versions, TrapGPT tente aussi `chatBox`.

Si TrapGPT ne repond pas:

- Verifie `opencc.server_url`.
- Verifie que `opencode serve` tourne.
- Verifie que HTTP est autorise dans la config ComputerCraft.
- Attends au moins `trapgpt.throttle_seconds` secondes.
- Le LLM peut aussi avoir repondu `SILENCE`, donc rien n'est poste.

Pour voir la version installee:

```lua
trapgpt --version
```

Pour afficher l'aide:

```lua
trapgpt --help
```