# ⚡ QUICK START - LSTM MEMORY SYSTEM

**Para:** Desenvolvedores que querem acionar o LSTM agora  
**Tempo:** 30 minutos  
**Resultado:** Akira com contexto completo e invisível

---

## 📋 PRÉ-REQUISITOS

```bash
# 1. Arquivo criado?
✅ /modules/lstm_memory_system.py (600 linhas)

# 2. Banco de dados preparado?
python migrate_lstm_tables.py    # Cria as tabelas

# 3. Imports disponíveis?
from modules.lstm_memory_system import get_lstm_memory_system
```

---

## 🎯 3 MUDANÇAS ESSENCIAIS

### 1️⃣ Em `reply_context_handler.py`

Adicione **2 linhas** para disparar LSTM ao processar mensagens:

```python
# ===== NO TOPO DO ARQUIVO =====
from modules.lstm_memory_system import get_lstm_memory_system

class ReplyContextHandler:
    def __init__(self, db, llm_client):
        self.db = db
        self.llm_client = llm_client
        self.lstm = get_lstm_memory_system(db)  # ← ADICIONE
    
    def handle_user_message(self, numero_usuario, message):
        """Processa mensagem do usuário."""
        
        context_id = self._get_context_id(numero_usuario)
        
        # Processar short-term (existente)
        short_memory = self.short_term_memory.add_message(...)
        
        # ✅ ADICIONE ISTO (1 linha):
        self.lstm.process_message_async(context_id, numero_usuario, message, 'user')
        
        # Resto do código...
        response = self.generate_response(context_id, message)
        
        # ✅ ADICIONE ISTO TAMBÉM (1 linha):
        self.lstm.process_message_async(context_id, numero_usuario, response, 'assistant')
        
        return response
```

**Pronto! Agora o LSTM processa cada mensagem automaticamente.**

---

### 2️⃣ Em `context_builder.py`

Adicione LSTM context ao construir o contexto:

```python
# ===== NO TOPO =====
from modules.lstm_memory_system import get_lstm_memory_system

def build_context(self, numero_usuario, context_id):
    """Constrói contexto para o modelo."""
    
    # Recuperar short-term (existente)
    short_memory = self.short_term_memory.get(context_id)
    
    # ✅ ADICIONE ISTO (2 linhas):
    lstm_context = None
    if self.lstm:
        lstm_context = self.lstm.get_lstm_context_for_model(context_id, numero_usuario)
    
    # Retornar com LSTM adicionado
    return {
        'short_term': short_memory,
        'lstm_context': lstm_context,  # ← Agora tem contexto mental!
    }
```

---

### 3️⃣ Em `api.py`

Use contexto LSTM no system prompt:

```python
# ===== NO MÉTODO generate() =====

def generate(self, user_message, context_history, context_data):
    """Gera resposta."""
    
    # ✅ Preparar system prompt com LSTM
    system_prompt = self.config.SYSTEM_PROMPT
    
    if context_data and context_data.get('lstm_context'):
        lstm = context_data['lstm_context']
        
        # Injetar contexto mental
        if lstm.get('topic_principal'):
            system_prompt += f"""
            
## 🧠 Contexto Atual
Tema principal: {lstm['topic_principal']}
Perguntas pendentes: {', '.join(lstm.get('unanswered_questions', [])[:2])}

Nota: Use este contexto para conectar tópicos naturalmente.
            """
    
    # Chamar modelo com system prompt enriquecido
    messages = [
        {"role": "system", "content": system_prompt},
        *context_history,
        {"role": "user", "content": user_message}
    ]
    
    response = self._call_llm(messages)
    return response
```

---

## ✅ VERIFICAÇÃO RÁPIDA

### Está funcionando?

```bash
# 1. Rodar uma conversa no bot
# Msg: "Fale sobre anemia falciforme"
# Msg: "cura?"

# 2. Verificar if LSTM salvou contexto:
python -c "
from modules.lstm_memory_system import get_lstm_memory_system
from modules.database import Database

db = Database('database.db')
lstm = get_lstm_memory_system(db)

# Ver contexto de um usuário
context = lstm.get_lstm_context_for_model('usuario:None:pv', 'usuario')
print('Topic:', context.get('topic_principal'))
print('Perguntas pendentes:', context.get('unanswered_questions'))
"

# 3. Se ver:
# Topic: anemia falciforme
# Perguntas pendentes: ['cura', 'tratamento']
# ✅ FUNCIONANDO!
```

---

## 🎯 RESULTADO ESPERADO

### Antes (Sem LSTM):
```
User: "cura? tratamento?"
Akira: "De quê?" ❌
```

### Depois (Com LSTM):
```
User: "cura? tratamento?"
[LSTM Background: topic = "anemia falciforme"]
Akira: "Para anemia falciforme, os tratamentos incluem..." ✅
```

---

## 📊 PROGRESSO

| Tarefa | Status | Tempo |
|--------|--------|-------|
| LSTM System criado | ✅ | 0 min |
| Tabelas DB criadas | ✅ | 5 min |
| Implantação em reply_context_handler | 🔄 | 5 min |
| Implantação em context_builder | 🔄 | 5 min |
| Implantação em api.py | 🔄 | 10 min |
| Teste de integração | 🔄 | 5 min |
| **TOTAL** | | **30 min** |

---

## 🆘 TROUBLESHOOTING

### Problema: "ModuleNotFoundError: No module named 'lstm_memory_system'"

**Solução:**
```python
# Verificar se arquivo existe:
import os
assert os.path.exists('modules/lstm_memory_system.py')

# Se não, recuperar do AKIRA-SOFTEDGE/
```

### Problema: "lstm_contexto table doesn't exist"

**Solução:**
```bash
python migrate_lstm_tables.py
```

### Problema: "LSTM context é None"

**Solução:**
```python
# 1. Verificar se `process_message_async()` foi chamado
# 2. Verificar logs: "LSTM summary salvo"
# 3. Se novo usuário, contexto pode ser vazio no início ✅
```

### Problema: "Context isolation violated!"

**Solução:**
```python
# Verificar context_id format:
context_id = f"{numero_usuario}:{grupo_id}:{tipo}"
# Deve ser "usuario123:None:pv" ou "isaac:grupo_123:group"
```

---

## 📝 CHECKLIST DE IMPLEMENTAÇÃO

- [ ] `migrate_lstm_tables.py` executado
- [ ] Import adicionado em `reply_context_handler.py`
- [ ] 2 calls para `process_message_async()` adicionados
- [ ] LSTM context recuperado em `context_builder.py`
- [ ] System prompt enriquecido em `api.py`
- [ ] Primeira conversa testada
- [ ] "cura?" retorna resposta com contexto correto
- [ ] Logs mostram "LSTM context retrieved"
- [ ] Diferentes usuários não veem contextos um do outro
- [ ] Performance normal (sem bloqueios)

---

## 🚀 PRÓXIMO PASSO DEPOIS

Após LSTM básico funcionando:

1. **Persona Tracker** - Usar LSTM para melhor análise de persona
2. **Web Search** - Usar topic_principal para buscas mais específicas
3. **Conversation Recovery** - Recuperar conversa anterior de usuário
4. **Metrics** - Monitorer contexto usage e performance

---

## 💡 DICAS RÁPIDAS

### Para Debug:
```python
# Ver último contexto salvo
context = lstm.get_lstm_context_for_model(context_id, numero_usuario)
print(json.dumps(context, indent=2, ensure_ascii=False))

# Ver se está processando
# Procurar no log: "LSTM summary saved"
```

### Para Melhorar:
```python
# Se quiser adicionar mais análise:
1. Modificar `_extract_topic()` 
2. Adicionar novo campo em `LSTMContextSummary`
3. Atualizar database schema
```

### Para Testar:
```bash
# Teste manual de 3 mensagens:
1. "Fale sobre [tópico]"
2. "Explique mais sobre [sub-tópico]"
3. "[palavra ambígua]?"

# Esperado: Bot entende tópico em msg 3
```

---

**Status:** 🎯 Pronto para integração em 30 minutos  
**Complexidade:** ⭐ (Simples - apenas 6 linhas de código!)  
**Impacto:** 🚀 ENORME (contexto completo)