01_business_understanding

from pathlib import Path
import pandas as pd

pd.set_option('display.max_colwidth', None)                     # Não limitar a largura da coluna
pd.set_option('display.width', None)                            # Expandir a largura da exibição (evitar quebra de linha horizontal)

PROJECT_ROOT = Path.cwd().resolve().parents[0]
DATA_DIR = PROJECT_ROOT / "data"
DOCS_DIR = PROJECT_ROOT / "docs"
ARTIFACTS_DIR = PROJECT_ROOT / "artifacts"

print("PROJECT_ROOT:", PROJECT_ROOT)
print("DATA_DIR:", DATA_DIR)
print("DOCS_DIR:", DOCS_DIR)
print("ARTIFACTS_DIR:", ARTIFACTS_DIR)

project_charter = {
    "project_name": "NLP Triagem Inteligente Financeira",
    "problem_type": "Classificação textual com apoio à priorização e encaminhamento",
    "primary_input": "Texto livre de reclamação, chamado ou manifestação",
    "primary_output": "Categoria da demanda",
    "secondary_output": "Prioridade da demanda (opcional no MVP)",
    "methodology": "CRISP-DM+ Lean",
    "business_goal": "Apoiar automação da triagem textual no setor financeiro",
    "technical_goal": "Construir pipeline end-to-end com baseline, transformer, API e monitoramento inicial"
}

pd.DataFrame([project_charter]).T.rename(columns={0: "valor"})

success_metrics = pd.DataFrame(
    [
        ["Negócio", "Tempo médio de triagem", "Redução do tempo operacional"],
        ["Negócio", "Consistência de classificação", "Menor variabilidade entre atendentes/processos"],
        ["Analítico", "Macro F1", "Avaliar desempenho geral entre classes"],
        ["Analítico", "Recall em classes críticas", "Reduzir perda de casos sensíveis"],
        ["Operacional", "Latência de inferência", "Viabilidade de uso em fluxo real"],
        ["Operacional", "Logging de predição", "Rastreabilidade inicial do uso do modelo"],
    ],
    columns=["dimensao", "metrica", "objetivo"]
)

success_metrics

ontology_entities = pd.DataFrame(
    [
        ["Cliente", "Pessoa que origina a manifestação, reclamação ou solicitação"],
        ["Demanda", "Texto livre contendo a necessidade, problema ou dúvida"],
        ["Produto", "Serviço ou produto financeiro ao qual a demanda se refere"],
        ["Canal", "Origem da demanda, como app, telefone, e-mail ou chat"],
        ["Categoria", "Classe principal atribuída à demanda"],
        ["Prioridade", "Nível de urgência operacional da demanda"],
        ["Atendimento", "Fluxo humano ou automatizado de tratamento da demanda"],
        ["Encaminhamento", "Destino operacional responsável pela tratativa"],
    ],
    columns=["entidade", "descricao"]
)

ontology_relations = pd.DataFrame(
    [
        ["Cliente", "abre", "Demanda"],
        ["Demanda", "refere-se a", "Produto"],
        ["Demanda", "chega por", "Canal"],
        ["Demanda", "recebe", "Categoria"],
        ["Demanda", "recebe", "Prioridade"],
        ["Demanda", "é tratada em", "Atendimento"],
        ["Demanda", "é encaminhada para", "Encaminhamento"],
    ],
    columns=["origem", "relacao", "destino"]
)

print("Entidades da ontologia:")
display(ontology_entities)

print("\nRelações da ontologia:")
display(ontology_relations)

blm_glossary = pd.DataFrame(
    [
        ["fatura", "Documento de cobrança relacionado ao produto financeiro"],
        ["limite", "Valor disponível ou teto operacional do produto"],
        ["contestação", "Pedido de revisão de cobrança, compra ou transação"],
        ["fraude", "Indício de uso indevido, transação não reconhecida ou comportamento suspeito"],
        ["bloqueio", "Impedimento temporário ou definitivo de uso do produto ou conta"],
        ["cobrança indevida", "Valor cobrado que o cliente considera incorreto"],
        ["renegociação", "Pedido de revisão de condições de pagamento ou dívida"],
        ["atraso", "Situação de não pagamento dentro do prazo esperado"],
        ["atendimento", "Interação operacional com canal, agente ou processo"],
        ["cancelamento", "Solicitação de encerramento de produto, serviço ou operação"],
    ],
    columns=["termo", "significado_de_negocio"]
)

blm_glossary

semantic_hypotheses = pd.DataFrame(
    [
        ["H1", "Termos relacionados a cobrança, fatura e vencimento tendem a formar grupos semânticos próximos."],
        ["H2", "Mensagens de fraude e transação não reconhecida devem apresentar vocabulário distintivo."],
        ["H3", "Categorias operacionais podem ter sobreposição semântica parcial, exigindo revisão de labels."],
        ["H4", "Mensagens muito curtas podem reduzir a capacidade discriminativa do modelo."],
        ["H5", "Há potencial para priorização adicional com base em palavras de urgência e contexto de risco."],
    ],
    columns=["hipotese", "descricao"]
)

semantic_hypotheses

risk_register = pd.DataFrame(
    [
        ["Classes sobrepostas", "Alta", "Alta", "Revisar labels e agrupar categorias quando necessário"],
        ["Desbalanceamento severo", "Alta", "Média", "Monitorar distribuição e usar métricas adequadas"],
        ["Texto muito curto", "Média", "Média", "Inspecionar comprimento e avaliar impacto por classe"],
        ["Baixa qualidade de rótulo", "Média", "Alta", "Criar amostra de revisão manual"],
        ["Escopo excessivo", "Alta", "Alta", "Manter foco em classificação principal no MVP"],
    ],
    columns=["risco", "probabilidade", "impacto", "mitigacao"]
)

risk_register

DOCS_DIR.mkdir(parents=True, exist_ok=True)

ontology_entities.to_csv(DOCS_DIR / "ontology_entities.csv", index=False)
ontology_relations.to_csv(DOCS_DIR / "ontology_relations.csv", index=False)
blm_glossary.to_csv(DOCS_DIR / "blm_glossary.csv", index=False)
semantic_hypotheses.to_csv(DOCS_DIR / "semantic_hypotheses.csv", index=False)
risk_register.to_csv(DOCS_DIR / "risk_register.csv", index=False)

print("Arquivos auxiliares exportados para a pasta docs/.")

#!uv pip install nbconvert -U -q
!jupyter nbconvert --to html --template-file my-template-html-v10.tpl 01_business_understanding.ipynb