---
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 |