| --- |
| library_name: sklearn |
| language: pt |
| license: mit |
| pipeline_tag: text-classification |
| tags: |
| - text-classification |
| - intent-classification |
| - lead-scoring |
| - tf-idf |
| - logistic-regression |
| - portuguese |
| --- |
| |
| # LeadForge Intent Classifier |
|
|
| Classificador de **intenção de prospecção** (`hot` / `warm` / `cold`) a partir do texto do lead, em português. Pipeline TF-IDF (word n-grams + char_wb n-grams) + Logistic Regression balanceada — sem API paga, sem GPU, determinístico (`random_state=42`). |
|
|
| Faz parte do pipeline do [LeadForge](https://github.com/ranzouu/leadforge). Código completo, CLI e testes: [github.com/ranzouu/leadforge-intent-classifier](https://github.com/ranzouu/leadforge-intent-classifier). |
|
|
| ## Métricas — avaliação honesta (out-of-fold) |
|
|
| **StratifiedKFold (5 folds) com tuning de `C` aninhado dentro do fold de treino.** Os números são pooled out-of-fold: toda amostra foi classificada por um modelo que nunca a viu no treino. |
|
|
| | Métrica (média ± desvio entre folds) | Valor | |
| |---|---| |
| | Accuracy | 0.633 ± 0.192 | |
| | Precision (weighted) | 0.634 ± 0.197 | |
| | Recall (weighted) | 0.633 ± 0.192 | |
| | F1 (weighted) | 0.630 ± 0.189 | |
| | F1 (macro) | 0.633 | |
|
|
| | Classe | Precision | Recall | F1 | Suporte | |
| |---|---|---|---|---| |
| | cold | 0.700 | 0.700 | 0.700 | 20 | |
| | hot | 0.750 | 0.750 | 0.750 | 20 | |
| | warm | 0.450 | 0.450 | 0.450 | 20 | |
|
|
| > Nota de integridade: uma versão anterior deste projeto publicava "accuracy 1.0" medida no mesmo conjunto usado no treino (avaliação in-sample — inflação). Esse número foi removido e substituído pela validação cruzada acima. Detalhes por fold em `runs/cv_folds.csv` e por classe em `runs/class_report.csv`. |
|
|
| ## Uso |
|
|
| ```python |
| import joblib |
| |
| vectorizer = joblib.load("vectorizer.pkl") |
| clf = joblib.load("model.pkl") |
| |
| frases = [ |
| "Quero fechar um plano hoje para minha barbearia", # hot |
| "Pode me explicar melhor como funciona?", # warm |
| "Só estou olhando por curiosidade", # cold |
| ] |
| print(clf.predict(vectorizer.transform([f.lower() for f in frases]))) |
| ``` |
|
|
| ## Limitações (leia com atenção) |
|
|
| - **Dataset de demonstração**: 60 amostras (20 por classe) escritas para exercitar o pipeline — não são leads reais de produção. Em produção, treinar com dados reais e revalidar antes de confiar. |
| - **`warm` é a fronteira difícil** (F1 0.45): separar "interesse" de "só curiosidade" é tênue até em leitura humana. |
| - Modelo linha de base (TF-IDF + LR); com dados reais e volume maior, comparar com alternativas (LinearSVC, gradient boosting, LLM zero-shot) antes de escolher. |
|
|
| ## Reproduzir |
|
|
| ```bash |
| pip install -e . # do repositório |
| python -m leadforge_intent_classifier |
| # runs/summary.csv, runs/cv_folds.csv, runs/class_report.csv, runs/latest.csv |
| ``` |
|
|
| ## Arquivos |
|
|
| | Arquivo | Conteúdo | |
| |---|---| |
| | `model.pkl` | Logistic Regression final (treinada nos 60 samples, `C=4.0`) | |
| | `vectorizer.pkl` | FeatureUnion word(1,2) + char_wb(2,4), `sublinear_tf` | |
| | `experiment.py` | código-fonte do pipeline (treino, nested CV, exportação) | |
| | `data/sample_leads.json` | dataset de demo (60 amostras) | |
| | `runs/*.csv` | métricas por fold, por classe e predições out-of-fold | |
| | `LICENSE` | MIT | |
|
|
