QUICK_START_LSTM.md

# ⚡ 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)