Fase 2.1: Modificar método preparar() com parâmetros opcionais

[bdcdo]

🚀 Fase 2.1: Modificar Método preparar() com Parâmetros Opcionais

📝 Descrição

Integrar funcionalidades de stemming/lemmatization ao método preparar() mantendo compatibilidade total.

🎯 Objetivos

• Adicionar parâmetros opcionais ao método preparar()
• Integrar pipeline de pré-processamento antes do TF-IDF
• Manter compatibilidade 100% retroativa
• Implementar lógica de fallback
• Documentação completa da nova API

🔧 Implementação Técnica

Nova assinatura do método:

def preparar(self, 
            coluna_textos: str, 
            limite_k: int = 10, 
            n_init: str | int = 'auto', 
            plotar_cotovelo: bool = True,
            # NOVOS PARÂMETROS
            usar_lemmatization: bool = False,
            usar_stemming: bool = False,
            cache_lemmas: bool = True,
            preservar_entidades: bool = False,
            fallback_stemming: bool = True,
            **tfidf_kwargs) -> None:

Pipeline integrado:

# 1. Carregar textos (atual)
textos_processados = df_para_preparar[coluna_textos].fillna('').astype(str).str.lower()

# 2. NOVO: Pré-processamento opcional
if usar_lemmatization or usar_stemming:
    textos_processados = self._aplicar_preprocessamento(
        textos_processados, 
        usar_lemmatization, 
        usar_stemming,
        cache_lemmas,
        preservar_entidades,
        fallback_stemming
    )

# 3. TF-IDF (atual)
self._vectorizer = TfidfVectorizer(**final_tfidf_kwargs)
self.X = self._vectorizer.fit_transform(textos_processados)

Validações e tratamentos:

• Exclusão mútua: usar_lemmatization e usar_stemming não podem ser True simultaneamente
• Dependências: Verificar se spaCy está instalado quando necessário
• Fallback inteligente: lemmatization → stemming → original
• Cache automático: Ativado por padrão para lemmatization

✅ Critérios de Aceitação

• Compatibilidade 100% retroativa (código existente funciona)
• Novos parâmetros funcionam corretamente
• Pipeline integrado ao TF-IDF existente
• Validações robustas implementadas
• Fallback funciona em todos os cenários
• Performance aceitável
• Testes passam para código antigo e novo

🔗 Relacionado

• Issue principal: Adicionar stemming/lemmatization #13
• Anterior: Fase 1.3: Implementar classe LemmatizerPT com spaCy #21 (LemmatizerPT)
• Próxima: Pipeline de pré-processamento

⏱️ Estimativa

6 horas - Integração delicada com código existente

🧪 Testes

• Compatibilidade: código sem parâmetros novos funciona
• Funcionalidade: lemmatization/stemming aplicados corretamente
• Performance: overhead aceitável
• Fallback: funciona quando spaCy não disponível
• Edge cases: textos vazios, muito longos, etc.

📖 Exemplos de uso

# Uso atual (sem mudanças)
cf.preparar(coluna_textos='texto')

# Com lemmatization
cf.preparar(coluna_textos='texto', usar_lemmatization=True)

# Com configurações avançadas
cf.preparar(
    coluna_textos='texto',
    usar_lemmatization=True,
    cache_lemmas=True,
    preservar_entidades=True,
    fallback_stemming=True
)