# Plan: AI Multi-Personalities, Judite (SAC), Dynamic Tags, Persistent Memory & Event Expansion

## 1. Architecture & Component Design

```
                     ┌───────────────────────────┐
                     │    CanalhandiaCommand     │
                     │  (/ia, /iap, /ia persona) │
                     └─────────────┬─────────────┘
                                   │
                                   ▼
┌─────────────────┐         ┌──────────────┐         ┌────────────────────────┐
│  PlayerMemory   │◄───────►│      Ai      │◄───────►│      Tools / Wiki      │
│ (ia-memoria.yml)│         │(Orchestrator)│         │ (lugares_jogador, etc.)│
└─────────────────┘         └──────┬───────┘         └────────────────────────┘
                                   │
                     ┌─────────────┴─────────────┐
                     │          MiniMax          │
                     │  (HTTP / Tools / Chat)    │
                     └───────────────────────────┘
```

### Components:
1. **`Persona.java` (Enum Enhancement):**
   - Add `JUDITE` (SAC/Telemarketing persona) and `NARRADOR` (Fantasy narrator).
   - Add `displayTag()` (e.g. "Judite", "Zoeiro", "Amigão") and `tagColor()` (Adventure `NamedTextColor`).
   - Add persona-specific system prompts while maintaining the security invariant (`GUARD`).

2. **`PlayerMemory.java` (New Persistent Service):**
   - Manages `plugins/Canalhandia/ia-memoria.yml`.
   - Thread-safe, cached in-memory with disk persistence.
   - Stores per-player:
     - Selected persona (`judite`, `zoeiro`, etc.) or `null` (inherit server default).
     - Persistent compressed summary of past conversations.
     - List of key facts learned about the player (e.g., base coordinates, preferred building materials, fear of mobs).
   - Provides sliding-window compression: auto-condenses turns when memory exceeds thresholds.

3. **`Tools.java` (Expanded Function Calling):**
   - Add `lugares_jogador` function: fetches recent deaths from `DeathLog`, saved coordinates from `Notes`, and current biome/world.
   - Update definitions JSON to make the tool discoverable to the LLM.

4. **`Ai.java` (Orchestrator Updates):**
   - Integrate `PlayerMemory`.
   - Resolve effective persona per player (`playerMemory.persona(player)` -> fallback `settings.aiPersona()`).
   - In `compose()`: inject effective persona tone + `playerMemory.formatContext(player)` + location summary.
   - In `deliver()` and `style()`: render dynamic tag `Msg.tag(persona.displayTag(), persona.tagColor())` instead of fixed `[IA]`.
   - Update `saySomething()` to support persona-specific spontaneous events.

5. **`CanalhandiaCommand.java` (CLI & Interaction):**
   - Enhance `/ia persona [nome]` to set per-player persona or list available personas with descriptions and click-to-select suggestions.
   - Add `/ia persona padrao` to reset preference.
   - Add `/ia status` and `/ia esquecer`.

6. **`Canalhandia.java` & Event Hooks (Event Expansion):**
   - Wire expanded event triggers into `saySomething()`:
     - Player joins (`aiWelcome`)
     - Player death streaks / notable deaths (`onDeath`)
     - Milestones & custom achievements (`onMilestone`)
     - Raid and boss victories (`onBossDefeat`)

---

## 2. File Touches

1. `src/main/java/dev/marcospaulo/canalhandia/Persona.java` — Add `JUDITE`, `NARRADOR`, tags, colors, and prompts.
2. `src/main/java/dev/marcospaulo/canalhandia/PlayerMemory.java` — New class for persistent per-player memory & compression.
3. `src/main/java/dev/marcospaulo/canalhandia/Tools.java` — Add `lugares_jogador` tool and integration with `DeathLog` & `Notes`.
4. `src/main/java/dev/marcospaulo/canalhandia/Ai.java` — Integrate `PlayerMemory`, dynamic persona tags, prompt composition.
5. `src/main/java/dev/marcospaulo/canalhandia/CanalhandiaCommand.java` — Subcommands for `/ia persona`, `/ia status`, `/ia esquecer`.
6. `src/main/java/dev/marcospaulo/canalhandia/Canalhandia.java` — Wire `PlayerMemory` lifecycle, expand event hooks.
7. `src/test/java/dev/marcospaulo/canalhandia/PersonaTest.java` — Unit tests for personas, tags, and system prompts.
8. `src/test/java/dev/marcospaulo/canalhandia/PlayerMemoryTest.java` — Unit tests for YAML storage, compression, and per-player state.
9. `src/test/java/dev/marcospaulo/canalhandia/ToolsTest.java` — Unit tests for `lugares_jogador` and tool execution.

---

## 3. Risks & Mitigations

- **Risk:** Token context blowup from memory/chat history.
  - *Mitigation:* Hard-cap memory summary length (max 300 chars) and max facts (max 5 items) per player.
- **Risk:** Thread safety when reading player memory in async AI tasks.
  - *Mitigation:* Synchronize all `PlayerMemory` reads/writes under monitor; snapshot memory context as immutable strings on main thread before async dispatch.
- **Risk:** API costs from spontaneous event comments.
  - *Mitigation:* All events remain strictly governed by `Budget` with cooldown windows and hourly/daily spend limits.