modules/INTEGRATION_GUIDE.md

""" ═══════════════════════════════════════════════════════════════════════ INTEGRATION GUIDE — COMO INTEGRAR NO api.py EXISTENTE ═══════════════════════════════════════════════════════════════════════ Este arquivo mostra:

1. Como modificar o endpoint POST /akira existente
2. Como usar ContextManagerV2
3. Como usar ListenStreamProcessor
4. Exemplos práticos de fluxo

IMPORTANTE: Isso SUBSTITUI o sistema antigo de context, mantendo compatibilidade com code existente. ═══════════════════════════════════════════════════════════════════════ """

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

📦 IMPORTS NECESSÁRIOS

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

from modules.context_manager_v2 import ( ContextManagerV2, get_context_manager, MessageType ) from modules.listen_stream_processor import ( ListenStreamProcessor, get_listen_processor ) from typing import Dict, Any import logging

logger = logging.getLogger(name)

ctx_manager = get_context_manager() listen_processor = get_listen_processor()

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

🔄 NOVO FLUXO DO ENDPOINT /akira

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

""" ANTES (buggy): ──────────────────────────────────────────────────────────────── POST /akira { "usuario": "Isaac", "numero": "202391978787009", "texto": "@AKIRA qual é a capital?" }

→ api.py chama obter_historico() → PROBLEMA: Retorna ALL mensagens, misturando grupos → AKIRA responde sem isolação

DEPOIS (robusto): ──────────────────────────────────────────────────────────────── POST /akira { "usuario": "Isaac", "numero": "202391978787009", "texto": "@AKIRA qual é a capital?", "tipo_conversa": "grupo" | "pv", "grupo_id": "g120363392399993499" (opcional), "referenced_message_author": "AKIRA", (opcional) }

→ listen_processor.processar_mensagem_chegando() → Classifica como DIRECT ou CONTEXTUAL → Adiciona à context_manager isolado por conversation_id

→ Se DIRECT (true): → ctx_manager.obter_historico_direto() → APENAS mensagens direcionadas a AKIRA → Isolado por conversation_id → AKIRA responde

→ Se CONTEXTUAL (false): → Registra mas NÃO processa → AKIRA entende fluxo via obter_contexto_grupo_amplificado() """

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

🔧 MODIFICAÇÃO NO ENDPOINT /akira

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

def novo_akira_endpoint_handler(request_data: Dict[str, Any]) -> Dict[str, Any]: """ Novo handler para POST /akira com isolação de contexto.

Substitui a lógica antiga em api.py:akira_endpoint()
"""

# ─────────────────────────────────────────────────────────────
# PASSO 1: EXTRAI DADOS CHEGANDO
# ─────────────────────────────────────────────────────────────
usuario = request_data.get('usuario', 'desconhecido')
numero = request_data.get('numero', '')
texto = request_data.get('texto', '')
tipo_conversa = request_data.get('tipo_conversa', 'pv')
grupo_id = request_data.get('grupo_id')

# Referência (se é resposta a outra mensagem)
referenced_author = request_data.get('referenced_message_author')
referenced_texto = request_data.get('referenced_message_texto')
referenced_id = request_data.get('referenced_message_id')

logger.info(
    f"📨 Mensagem chegando: {usuario} ({numero}) em {tipo_conversa} | "
    f"Texto: {texto[:50]}..."
)

# ─────────────────────────────────────────────────────────────
# PASSO 2: PROCESSA VIA LISTEN STREAM
# ─────────────────────────────────────────────────────────────
evento = {
    'usuario': usuario,
    'numero': numero,
    'texto': texto,
    'tipo_conversa': tipo_conversa,
    'grupo_id': grupo_id,
    'referenced_message_author': referenced_author,
    'referenced_message_texto': referenced_texto,
    'referenced_message_id': referenced_id,
}

resultado_processamento = listen_processor.processar_mensagem_chegando(evento)

logger.info(
    f"🔍 Classificação: {resultado_processamento['tipo_message']} | "
    f"Deve processar: {resultado_processamento['deve_processar']}"
)

# ─────────────────────────────────────────────────────────────
# PASSO 3: DECIDE SE AKIRA RESPONDE
# ─────────────────────────────────────────────────────────────

if not resultado_processamento['deve_processar']:
    # Mensagem CONTEXTUAL → apenas registra, não responde
    logger.info(f"📚 Mensagem contextual (escuta). Conversão_id: {resultado_processamento['conversation_id']}")
    return {
        'status': 'context_registered',
        'tipo': 'contextual',
        'message': f"Entendi. {usuario} falou sobre isso no grupo.",
        'deve_responder': False,
        'conversation_id': resultado_processamento['conversation_id'],
    }

# ─────────────────────────────────────────────────────────────
# PASSO 4: AKIRA RESPONDE (mensagem é DIRETA)
# ─────────────────────────────────────────────────────────────

conversation_id = resultado_processamento['conversation_id']

# Obtém contexto ISOLADO
contexto = listen_processor.obter_contexto_para_resposta(
    numero=numero,
    tipo_conversa=tipo_conversa,
    grupo_id=grupo_id,
    include_contextual=True
)

logger.info(
    f"📖 Contexto obtido: {contexto['total_direct']} mensagens diretas | "
    f"Participantes: {contexto.get('participants', [])}"
)

# ─────────────────────────────────────────────────────────────
# PASSO 5: ENRIQUECER COM CONTEXTO DE GRUPO
# ─────────────────────────────────────────────────────────────

contexto_grupo_info = contexto.get('grupo_flow', {})
participants = contexto.get('participants', [])

# Monta prompt para AKIRA
prompt_system = f"""

Você é AKIRA, assistente IA em um grupo. Contexto:

• Participantes do grupo: {', '.join(participants) if participants else 'Desconhecido'}
• Tópicos recentes: {', '.join(contexto.get('topics', [])) if contexto.get('topics') else 'Vários'}
• Sua conversa com {usuario}: {len(contexto['direct_messages'])} mensagens anteriores

IMPORTANTE: Responda APENAS sobre o que foi perguntado a você. NÃO comente sobre outras conversas do grupo (escuta sem falar). """

# Histórico ISOLADO
mensagens_anteriores = [
    {
        'usuario': m['usuario'],
        'texto': m['texto'],
        'timestamp': m['timestamp']
    }
    for m in contexto['direct_messages']
]

# ─────────────────────────────────────────────────────────────
# PASSO 6: CHAMA LLM (seu código existente)
# ─────────────────────────────────────────────────────────────

# Isso seria integrado com seu chain LLM existente:
# resposta = gerar_resposta_llm(
#     sistema=prompt_system,
#     historico=mensagens_anteriores,
#     mensagem_atual=texto,
#     usuario=usuario
# )

resposta = f"[RESPOSTA DE AKIRA] Você perguntou: {texto[:100]}"  # Placeholder

# ─────────────────────────────────────────────────────────────
# PASSO 7: RETORNA
# ─────────────────────────────────────────────────────────────

return {
    'status': 'success',
    'tipo': 'direct',
    'resposta': resposta,
    'deve_responder': True,
    'conversation_id': conversation_id,
    'usuario': usuario,
    'contexto_info': {
        'num_direct_messages': contexto['total_direct'],
        'participants': participants,
        'topics': contexto.get('topics', []),
    }
}

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

📝 ALTERAÇÕES NECESSÁRIAS NO api.py

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

""" LOCAIS ESPECÍFICOS A MODIFICAR EM api.py:

1️⃣ IMPORT SECTION (top do arquivo) ──────────────────────────────────────────────────────────────── Adicionar:

from modules.context_manager_v2 import get_context_manager
from modules.listen_stream_processor import get_listen_processor

ctx_manager = get_context_manager()
listen_processor = get_listen_processor()

2️⃣ FUNÇÃO akira_endpoint() - SUBSTITUIR INTEIRA ──────────────────────────────────────────────────────────────── Localização: api.py::akira_endpoint() (aproximadamente linha 950)

Ação: SUBSTITUIR todo o corpo da função pelo code do
novo_akira_endpoint_handler() acima.

O que muda:
✅ Remove: data = contexto.obter_historico()  (BUGGY - sem filtro)
✅ Adiciona: resultado_processamento = listen_processor.processar_mensagem_chegando()
✅ Adiciona: if not resultado_processamento['deve_processar']: return (skip contextual)
✅ Adiciona: contexto = listen_processor.obter_contexto_para_resposta() (ISOLADO)

3️⃣ FUNÇÃO _get_user_context() - MODIFICAR ──────────────────────────────────────────────────────────────── Localização: api.py::_get_user_context() (aproximadamente linha 1000)

ANTES:
def _get_user_context(numero, usuario):
    historico = contexto.obter_historico()  # ❌ SEM FILTRO
    return {
        'historico': historico,
        'usuario': usuario
    }

DEPOIS:
def _get_user_context(numero, usuario, tipo_conversa='pv', grupo_id=None):
    # Usa novo context manager ISOLADO
    historico = ctx_manager.obter_historico_direto(
        numero=numero,
        tipo_conversa=tipo_conversa,
        grupo_id=grupo_id,
        limit=50
    )
    contexto_grupo = ctx_manager.obter_contexto_grupo_amplificado(
        numero=numero,
        tipo_conversa=tipo_conversa,
        grupo_id=grupo_id
    ) if tipo_conversa == "grupo" else None
    
    return {
        'historico': [m.to_dict() for m in historico],
        'usuario': usuario,
        'contexto_grupo': contexto_grupo,
        'conversation_id': historico[0].conversation_id if historico else None
    }

4️⃣ FUNÇÃO obter_historico() - DEPRECAR OU SUBSTITUIR ──────────────────────────────────────────────────────────────── Localização: database.py ou modules/database.py

ANTES:
def obter_historico():
    return db.query(Mensagem).all()  # ❌ RETORNA TUDO

DEPOIS:
def obter_historico(conversation_id: str, msg_type: str = 'all'):
    # msg_type: 'direct', 'contextual', 'all'
    query = db.query(Mensagem).filter(
        Mensagem.conversation_id == conversation_id
    )
    if msg_type == 'direct':
        query = query.filter(Mensagem.tipo == 'direct')
    elif msg_type == 'contextual':
        query = query.filter(Mensagem.tipo == 'contextual')
    return query.order_by(Mensagem.timestamp.desc()).limit(100).all()

5️⃣ SUPORTE AO PAYLOAD NOVO ──────────────────────────────────────────────────────────────── O endpoint POST /akira AGORA ACEITA:

{
    "usuario": "Isaac",
    "numero": "202391978787009",
    "texto": "@AKIRA qual é a capital?",
    "tipo_conversa": "grupo",  ← NOVO
    "grupo_id": "g120363392399993499",  ← NOVO (opcional)
    "referenced_message_author": "Stefânio",  ← NOVO (opcional)
    "referenced_message_texto": "Oi",  ← NOVO (opcional)
    "referenced_message_id": "msg_123"  ← NOVO (opcional)
}

Os campos 'tipo_conversa', 'grupo_id', 'referenced_*' são opcionais
e vêm do discord-ts quando disponíveis. Se não vierem, valor default
é 'pv' (conversa privada).

"""

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

📊 EXEMPLO DE USO COMPLETO

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

""" CENÁRIO: Isaac e Stefânio em grupo

1️⃣ ISAAC envia: "@AKIRA qual é a capital de Portugal?" grupo: "g120363392399993499"

→ listen_processor classifica como DIRECT (menciona @AKIRA)
→ ctx_manager.adicionar_message_direta() com conversation_id único
→ AKIRA responde: "A capital é Lisboa"

2️⃣ STEFÂNIO responde (sem @AKIRA): "Bacano, eu não sabia"

→ listen_processor classifica como CONTEXTUAL
→ ctx_manager.adicionar_message_contextual()
→ AKIRA NÃO responde (não foi direcionada a ela)
→ Mas AKIRA "entende" que Stefânio achou legal

3️⃣ STEFÂNIO envia: "Qual é a capital da França?" (sem @AKIRA)

→ listen_processor classifica como CONTEXTUAL
→ AKIRA não responde

4️⃣ ISAAC responde: "@AKIRA? Já que perguntou, qual é?"

→ listen_processor classifica como DIRECT (menciona @AKIRA)
→ Obtém contexto ISOLADO (só conversas diretas com Isaac)
→ AKIRA NÃO vê a pergunta de Stefânio (contextual)
→ AKIRA responde baseada só no que Isaac perguntou

RESULTADO: ✅ AKIRA entende quem fala o quê ✅ Não mistura contextos ✅ Responde apenas quando direcionada ✅ Escuta o fluxo sem contaminar """

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

🎯 PRÓXIMOS PASSOS

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

""" TAREFAS PARA IMPLEMENTAR:

1. ✅ Criar context_manager_v2.py (FEITO)
2. ✅ Criar listen_stream_processor.py (FEITO)
3. 🔄 Modificar api.py:
   • Importar novos módulos
   • Reescrever akira_endpoint()
   • Atualizar _get_user_context()
4. 🔄 Modificar database.py:
   • Adicionar suporte a conversation_id na query
   • Adicionar campo 'tipo' na tabela Mensagem
5. 🔄 Testar com fluxo real:
   • Isaac + Stefânio em grupo
   • Verificar isolamento
6. 🔄 Integrar com discord-ts:
   • discord-ts deve enviar 'tipo_conversa' e 'grupo_id'
   • Enviar 'referenced_message_author' quando é reply """

all = [ 'novo_akira_endpoint_handler', 'ctx_manager', 'listen_processor', ]