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

# 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:

# ===== 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:

# ===== 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:

# ===== 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?

# 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:

# 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:

python migrate_lstm_tables.py

Problema: "LSTM context é None"

Solução:

# 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:

# 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:

# 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:

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

Para Testar:

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