CHECKLIST_IMPLEMENTACAO.py

"""

═══════════════════════════════════════════════════════════════════════

CHECKLIST DE IMPLEMENTAÇÃO — PASSO A PASSO

═══════════════════════════════════════════════════════════════════════

Guia prático para aplicar a solução no seu ambiente

"""

# ═══════════════════════════════════════════════════════════════════════
# FASE 1: PREPARAÇÃO (30 minutos)
# ═══════════════════════════════════════════════════════════════════════

FASE1 = """



✓ PASSO 1.1: BACKUP DO CÓDIGO EXISTENTE

───────────────────────────────────────────────────────────────

Local: i:\\Isaac Quarenta\\Programação\\AKIRA-SOFTEDGE\\



□ Fazer backup de api.py

  cp modules/api.py modules/api.py.backup.$(date +%Y%m%d_%H%M%S)

  

□ Fazer backup de database.py

  cp modules/database.py modules/database.py.backup.$(date +%Y%m%d_%H%M%S)



□ Fazer backup de todo o diretório modules/

  ls -la modules/ > modules_backup_list.txt





✓ PASSO 1.2: VERIFICAR NOVOS ARQUIVOS

───────────────────────────────────────────────────────────────

□ context_manager_v2.py ✅ EXISTS (já criado)

□ listen_stream_processor.py ✅ EXISTS (já criado)

□ INTEGRATION_GUIDE.md ✅ EXISTS (já criado)

□ API_PATCH_DETAILED.md ✅ EXISTS (já criado)

□ test_context_isolation.py ✅ EXISTS (já criado)

□ SOLUCAO_ESCALAVEL_CONTEXT_ISOLATION.md ✅ EXISTS (já criado)

□ ARQUITETURA_VISUAL.txt ✅ EXISTS (já criado)





✓ PASSO 1.3: VERIFICAR DEPENDÊNCIAS PYTHON

───────────────────────────────────────────────────────────────

Necessários (já devem existir):

□ hashlib (built-in)

□ threading (built-in)

□ dataclasses (built-in)

□ typing (built-in)

□ datetime (built-in)

□ enum (built-in)

□ json (built-in)

□ logging (built-in)

□ re (built-in)

□ time (built-in)



Comandos para verificar:

$ python -c "import hashlib, threading, dataclasses, enum; print('✅ Tudo OK')"





✓ PASSO 1.4: REVISAR DOCUMENTAÇÃO

───────────────────────────────────────────────────────────────

□ Ler ARQUITETURA_VISUAL.txt (compreender fluxo)

□ Ler SOLUCAO_ESCALAVEL_CONTEXT_ISOLATION.md (entender problema/solução)

□ Ler INTEGRATION_GUIDE.md (entender integração)

□ Ler API_PATCH_DETAILED.md (ver modificações específicas)



"""

# ═══════════════════════════════════════════════════════════════════════
# FASE 2: TESTES (20 minutos)
# ═══════════════════════════════════════════════════════════════════════

FASE2 = """



✓ PASSO 2.1: EXECUTAR TESTES ISOLADOS

───────────────────────────────────────────────────────────────

Locação: i:\\Isaac Quarenta\\Programação\\AKIRA-SOFTEDGE\\



□ Execute os testes:

  cd AKIRA-SOFTEDGE

  python test_context_isolation.py



Esperado:

  ✅ TEST 1 PASSED

  ✅ TEST 2 PASSED

  ✅ TEST 3 PASSED

  ✅ TEST 4 PASSED

  ✅ TEST 5 PASSED

  

  🎉 TODOS OS TESTES PASSARAM!



Se falhar:

  - Verificar que context_manager_v2.py existe

  - Verificar que listen_stream_processor.py existe

  - Verificar que ambos estão em modules/

  - Verificar mensagens de erro específicas





✓ PASSO 2.2: TESTAR ISOLADAMENTE CADA MÓDULO

───────────────────────────────────────────────────────────────

□ Testar context_manager_v2:

  python -c "

from modules.context_manager_v2 import get_context_manager

cm = get_context_manager()

print('✅ ContextManagerV2 carregado')

print(f'Stats: {cm.obter_stats()}')

"



□ Testar listen_stream_processor:

  python -c "

from modules.listen_stream_processor import get_listen_processor

lp = get_listen_processor()

print('✅ ListenStreamProcessor carregado')

resultado = lp.processar_mensagem_chegando({

    'usuario': 'teste',

    'numero': '1234567890',

    'texto': '@AKIRA teste',

    'tipo_conversa': 'pv'

})

print(f'Resultado: {resultado}')

"



Se tudo OK → continuar para Fase 3





✓ PASSO 2.3: VALIDAR ISOLAÇÃO

───────────────────────────────────────────────────────────────

□ Executar test_context_isolation.py novamente

□ Verificar que TEST 4 passa (isolação Isaac vs Stefânio)

□ Se TEST 4 falhar, revisar logic em listen_stream_processor.py



"""

# ═══════════════════════════════════════════════════════════════════════
# FASE 3: INTEGRAÇÃO (45 minutos)
# ═══════════════════════════════════════════════════════════════════════

FASE3 = """



✓ PASSO 3.1: ADICIONAR IMPORTS NO api.py

───────────────────────────────────────────────────────────────

Localização: modules/api.py (linha ~10-30)



ANTES:

```python

import json

import hashlib

import logging

from skills_registry import SkillsRegistry

...

```



DEPOIS (ADICIONAR):

```python

import json

import hashlib

import logging

from skills_registry import SkillsRegistry



# ✅ NOVOS IMPORTS PARA CONTEXT V2

from modules.context_manager_v2 import (

    ContextManagerV2,

    get_context_manager,

    MessageType,

    ContextType

)

from modules.listen_stream_processor import (

    ListenStreamProcessor,

    get_listen_processor

)



# Inicializa singletons

ctx_manager = get_context_manager()

listen_processor = get_listen_processor()

...

```



Ação:

□ Abrir modules/api.py

□ Localizar seção de imports

□ Adicionar imports acima

□ SALVAR arquivo





✓ PASSO 3.2: MODIFICAR _get_user_context

───────────────────────────────────────────────────────────────

Localização: modules/api.py::_get_user_context (line ~2311)



AÇÃO: Seguir API_PATCH_DETAILED.md seção "MODIFICATION 2"



□ Abrir api.py

□ Procurar função "_get_user_context"

□ Modificar assinatura (adicionar numero, tipo_conversa, grupo_id)

□ Adicionar lógica de ContextManagerV2

□ SALVAR e TESTAR





✓ PASSO 3.3: INTEGRAR LISTEN STREAM EM akira_endpoint

───────────────────────────────────────────────────────────────

Localização: modules/api.py::akira_endpoint (line ~1224)



AÇÃO: Seguir API_PATCH_DETAILED.md seção "MODIFICATION 3"



Este é o PRINCIPAL passo:



□ Localizar onde se extrai dados (usuario, numero, texto, tipo_conversa)

□ Adicionar extração de novos campos (referenced_message_author, etc)

□ ANTES de processar LLM:

   ├─ Chamar listen_processor.processar_mensagem_chegando(evento)

   ├─ Verificar resultado_processamento['deve_processar']

   ├─ Se False: retornar jsonify com status 'contextual'

   └─ Se True: continuar normalmente

□ Usar listen_processor.obter_contexto_para_resposta() para histórico

□ SALVAR e TESTAR





✓ PASSO 3.4: ACEITAR NOVOS CAMPOS NO PAYLOAD

───────────────────────────────────────────────────────────────

Localização: modules/api.py::akira_endpoint (data extraction)



AÇÃO: Adicionar suporte aos novos campos



```python

# ✅ NOVOS CAMPOS PARA LISTEN STREAM

referenced_message_author = data.get('referenced_message_author', 

                                    data.get('quoted_author_name', ''))

referenced_message_texto = data.get('referenced_message_texto',

                                   data.get('mensagem_citada', ''))

referenced_message_id = data.get('referenced_message_id',

                                data.get('message_id_citada', ''))

```



□ Adicionar após extração de tipo_conversa/grupo_id

□ SALVAR





✓ PASSO 3.5: ATUALIZAR RESPOSTA JSON

───────────────────────────────────────────────────────────────

Localização: modules/api.py::akira_endpoint (return jsonify)



AÇÃO: Adicionar campos de debug



```python

return jsonify({

    'resposta': resposta,

    'modelo_usado': modelo,

    'confidence': confidence,

    'conversation_id': conversation_id,  # ✅ NOVO

    'tipo_message': resultado_processamento['tipo_message'],  # ✅ NOVO

    'participants': participants if tipo_conversa == 'grupo' else [],  # ✅ NOVO

    ...

})

```



□ Localizar primeiro return jsonify em akira_endpoint

□ Adicionar campos acima

□ SALVAR



"""

# ═══════════════════════════════════════════════════════════════════════
# FASE 4: ATUALIZAR discord-ts (15 minutos)
# ═══════════════════════════════════════════════════════════════════════

FASE4 = """



✓ PASSO 4.1: ATUALIZAR APIClient.ts

───────────────────────────────────────────────────────────────

Localização: discord-ts/index/modules/APIClient.ts



Adicionar ao payload enviado:



□ tipo_conversa: "pv" | "grupo"

  └─ Se é conversa privada ou grupo



□ grupo_id: string | null

  └─ ID do grupo (se aplicável)



□ referenced_message_author: string | null

  └─ Nome de quem foi mencionado/citado



□ referenced_message_texto: string | null

  └─ Texto da mensagem citada



Exemplo de novo payload:

```typescript

const payload = {

    usuario: msg.author.username,

    numero: msg.author.id,

    texto: msg.content,

    tipo_conversa: msg.channel.isDMBased() ? 'pv' : 'grupo',

    grupo_id: !msg.channel.isDMBased() ? msg.channelId : null,

    referenced_message_author: msg.reference?.author?.username || null,

    referenced_message_texto: msg.reference?.content || null,

    // ... resto dos campos

};

```



□ Modificar APIClient.ts

□ TESTAR com Discord





✓ PASSO 4.2: VERIFICAR BAILEYS (WhatsApp)

───────────────────────────────────────────────────────────────

Localização: discord-ts/index/modules/BotCore.ts ou similar



Verificar se:

□ tipo_conversa é capturado corretamente

□ grupo_id é enviado quando em grupo

□ quoted messages são extraídas



Se não estão:

□ Adicionar lógica similar ao Discord

□ TESTAR com WhatsApp



"""

# ═══════════════════════════════════════════════════════════════════════
# FASE 5: TESTES DE INTEGRAÇÃO (30 minutos)
# ═══════════════════════════════════════════════════════════════════════

FASE5 = """



✓ PASSO 5.1: TESTE BÁSICO - CONVERSA PRIVADA

───────────────────────────────────────────────────────────────

□ Enviar via POST /akira em conversa privada

  

Payload:

{

    "usuario": "IsaacTest",

    "numero": "test_123",

    "texto": "Oi AKIRA",

    "tipo_conversa": "pv"

}



Esperado:

✅ deve_processar: true

✅ tipo_message: "direct"

✅ resposta: [alguma resposta]

✅ conversation_id: [hash único]





✓ PASSO 5.2: TESTE COM MENÇÃO EM GRUPO

───────────────────────────────────────────────────────────────

□ Enviar em grupo COM @AKIRA



Payload:

{

    "usuario": "IsaacTest",

    "numero": "test_123",

    "texto": "@AKIRA qual é a capital?",

    "tipo_conversa": "grupo",

    "grupo_id": "test_group_123"

}



Esperado:

✅ deve_processar: true

✅ tipo_message: "direct"

✅ resposta: [resposta da pergunta]





✓ PASSO 5.3: TESTE SEM MENÇÃO EM GRUPO

───────────────────────────────────────────────────────────────

□ Enviar em grupo SEM @AKIRA



Payload:

{

    "usuario": "StefanioTest",

    "numero": "test_456",

    "texto": "Bacano",

    "tipo_conversa": "grupo",

    "grupo_id": "test_group_123"

}



Esperado:

✅ deve_processar: false

✅ tipo_message: "contextual"

✅ resposta: "" (vazia)

✅ status: "context_registered"





✓ PASSO 5.4: TESTE DE ISOLAÇÃO

───────────────────────────────────────────────────────────────

□ Executar sequência em grupo:



1. Isaac: "@AKIRA qual é capital de PT?" (responde)

2. Stefânio: "Bacano" (contextual, não responde)

3. Isaac: "@AKIRA e da FR?" (responde)



Validação:

□ AKIRA respondeu em 1 e 3 (ambas Isaac)

□ AKIRA não respondeu em 2

□ Logs mostram "🔍 Classificação Listen: direct/contextual"

□ conversation_id de Isaac mantém isolado





✓ PASSO 5.5: MONITORAR LOGS

───────────────────────────────────────────────────────────────

Observar no logs:

□ "📨 Mensagem chegando: ..."

□ "🔍 Classificação Listen: ..."

□ "✓ Mensagem contextual (escuta). Não respondendo." (quando aplicável)

□ "📖 Contexto obtido: X mensagens diretas"



Se tudo OK → Fase 6



"""

# ═══════════════════════════════════════════════════════════════════════
# FASE 6: VALIDAÇÃO FINAL (15 minutos)
# ═══════════════════════════════════════════════════════════════════════

FASE6 = """



✓ PASSO 6.1: VERIFICAR STATS

───────────────────────────────────────────────────────────────

□ Chamar ctx_manager.obter_stats()



Esperado:

{

    'total_contexts': N,

    'total_messages': M,

    'average_msgs_per_context': M/N,

    'cache_size': X,

    'memory_estimate_mb': Y

}



Validar:

□ memory_estimate_mb < 100MB (escalável)

□ total_contexts growing mas não explosivo





✓ PASSO 6.2: VERIFICAR ISOLAÇÃO REAL

───────────────────────────────────────────────────────────────

□ Fazer teste completo com 2+ usuários em grupo real

□ Verificar que mensagens de um não contamina outro

□ Verificar que AKIRA responde apenas quando mencionada



Exemplo:

- Isaac: "@AKIRA Python é melhor que Java?"

- Você em outro grupo: "@AKIRA Qual é o melhor framework?"

- Isaac: "@AKIRA Ok valeu"

✓ Confirm: Cada um tem seu próprio contexto isolado





✓ PASSO 6.3: PERFORMANCE

───────────────────────────────────────────────────────────────

□ Medir tempo de resposta com novo sistema

□ Comparar com antes (deve ser ~5-10% mais rápido)

□ Verificar que não há memory leaks após 1 hora de uso





✓ PASSO 6.4: ROLLBACK PLAN

───────────────────────────────────────────────────────────────

Se algo der errado:



□ Restaurar api.py do backup:

  cp modules/api.py.backup.* modules/api.py

  

□ Remover imports dos novos módulos



□ Reiniciar servidor



□ Verificar que volta ao estado anterior



□ Documentar problema encontrado para debug



"""

# ═══════════════════════════════════════════════════════════════════════
# FASE 7: DEPLOY (5 minutos)
# ═══════════════════════════════════════════════════════════════════════

FASE7 = """



✓ PASSO 7.1: DEPLOY EM STAGING

───────────────────────────────────────────────────────────────

□ Deploy do novo código em staging

□ Rodar Fase 5 (testes de integração) em staging

□ Monitorar por 2-4 horas

□ Verificar que não há errors no log





✓ PASSO 7.2: DEPLOY EM PRODUÇÃO

───────────────────────────────────────────────────────────────

□ Fazer último backup do api.py em produção

□ Deploy da solução

□ Monitorar logs continuamente

□ Se problema: executar rollback plan





✓ PASSO 7.3: MONITORAMENTO PÓS-DEPLOY

───────────────────────────────────────────────────────────────

□ Primeira hora: Verificar a cada 5 minutos

□ Primeiras 24h: Verificar a cada 30 minutos

□ Após 24h: Verificar diariamente



Métricas a monitorar:

├─ Taxa de erro (deve ser < 0.1%)

├─ Tempo médio de resposta (deve ser < 2s)

├─ Memory usage (deve ser estável)

├─ Context isolation (validar com teste manual diário)

└─ User complaints (deve ser zero sobre context mix)



"""

# ═══════════════════════════════════════════════════════════════════════
# RESUMO DE TEMPO ESTIMADO
# ═══════════════════════════════════════════════════════════════════════

RESUMO_TEMPO = """



FASE 1 (Preparação): 30 minutos

├─ Backup

├─ Verificar novos arquivos

├─ Verificar dependências

└─ Revisar documentação



FASE 2 (Testes Isolados): 20 minutos

├─ Executar test_context_isolation.py

├─ Testar cada módulo

└─ Validar isolação



FASE 3 (Integração): 45 minutos

├─ Adicionar imports

├─ Modificar _get_user_context

├─ Integrar listen stream

├─ Aceitar novos campos

└─ Atualizar resposta JSON



FASE 4 (Atualizar discord-ts): 15 minutos

├─ Atualizar APIClient.ts

└─ Verificar Baileys



FASE 5 (Testes de Integração): 30 minutos

├─ Teste PV

├─ Teste menção em grupo

├─ Teste sem menção

├─ Teste isolação

└─ Monitorar logs



FASE 6 (Validação): 15 minutos

├─ Verificar stats

├─ Verificar isolação real

├─ Performance check

└─ Rollback plan



FASE 7 (Deploy): 5 minutos

├─ Deploy staging

├─ Deploy produção

└─ Monitoramento inicial



────────────────────────────────────────────────────────────────

TOTAL: ~2 horas 50 minutos (primeira vez)

PRÓXIMAS IMPLEMENTAÇÕES: ~30 minutos (depois de entender)

────────────────────────────────────────────────────────────────



"""

# ═══════════════════════════════════════════════════════════════════════
# TROUBLESHOOTING RÁPIDO
# ═══════════════════════════════════════════════════════════════════════

TROUBLESHOOTING = """



PROBLEMA: "ModuleNotFoundError: No module named 'context_manager_v2'"

SOLUÇÃO:

  □ Verificar que context_manager_v2.py está em modules/

  □ Verificar que __init__.py existe em modules/

  □ Adicionar modules/ ao PYTHONPATH se necessário





PROBLEMA: "NameError: name 'ctx_manager' is not defined"

SOLUÇÃO:

  □ Verificar que imports estão no top do api.py

  □ Verificar que get_context_manager() foi chamado

  □ Verificar que listen_processor também foi inicializado





PROBLEMA: "AKIRA ainda está respondendo mensagens contextuais"

SOLUÇÃO:

  □ Verificar que listen_processor.processar_mensagem_chegando() é chamado

  □ Verificar que if not resultado_processamento['deve_processar']: é respeitado

  □ Verificar logs: ver se 🔍 Classificação está correto

  □ Se classifica como CONTEXTUAL mas processa, debugar lógica





PROBLEMA: "Contextos ainda estão misturando"

SOLUÇÃO:

  □ Verificar que conversation_id é único por usuário/grupo

  □ Rodar test_context_isolation.py especialmente TEST 4

  □ Debugar _gerar_conversation_id() em ContextManagerV2

  □ Verificar que ctx_manager.obter_historico_direto() está sendo usado





PROBLEMA: "Performance degradada após integração"

SOLUÇÃO:

  □ Verificar ctx_manager.obter_stats() para memory estimate

  □ Se > 100MB: implementar cleanup mais agressivo

  □ Verificar número de contextos: se > 10k, há problema

  □ Revisar TTL do cache (atualmente 300s, pode reduzir)





PROBLEMA: "Mensagens antigas não aparecem"

SOLUÇÃO:

  □ Verificar TTL: contextos com last_access > 7 dias são deletados

  □ Se precisa histórico mais longo: modificar max_age_days em cleanup

  □ Ou implementar persistência em DB (fora do escopo atual)



"""

print(FASE1)
print("\n" + "="*70 + "\n")
print(FASE2)
print("\n" + "="*70 + "\n")
print(FASE3)
print("\n" + "="*70 + "\n")
print(FASE4)
print("\n" + "="*70 + "\n")
print(FASE5)
print("\n" + "="*70 + "\n")
print(FASE6)
print("\n" + "="*70 + "\n")
print(FASE7)
print("\n" + "="*70 + "\n")
print(RESUMO_TEMPO)
print("\n" + "="*70 + "\n")
print(TROUBLESHOOTING)

__all__ = ['FASE1', 'FASE2', 'FASE3', 'FASE4', 'FASE5', 'FASE6', 'FASE7', 'RESUMO_TEMPO', 'TROUBLESHOOTING']