email-tagger 0.2.0

AI Email Contact Tagger — klasyfikacja kontaktów z kontrolą prywatności

email-tagger

AI Email Contact Tagger — enterprise-grade narzędzie do automatycznej klasyfikacji bazy kontaktów e-mailowych z pełną kontrolą prywatności.

pip install email-tagger
email-tagger classify -i kontakty.csv -o otagowane.csv

🧠 Co robi

Czyta CSV z kontaktami, wysyła dane do AI (OpenAI lub lokalny model), i przypisuje tagi w 3 kategoriach:

Kategoria	Tagi
Branża	e-commerce, saas, fintech, agencja, produkcja, edukacja, zdrowie, nieruchomosci, consulting, it_tech, media, nonprofit, handel, inne
Rola	founder, c_level, dyrektor, marketing, sprzedaz, it, hr, operacje, administracja, inne_rola
Intencja	potencjalny_klient, aktywny_prospect, partner, zimny_lead, inwestor, media_kontakt, rekruter, nieokreslona

Wynik: oryginalny CSV + 4 nowe kolumny tag_branza, tag_rola, tag_intencja, tag_pewnosc.

🚀 Szybki start

# Instalacja
pip install email-tagger

# Wymagane: klucz API OpenAI (dla profili cloud)
export OPENAI_API_KEY=sk-proj-...

# Podstawowe użycie
email-tagger classify -i kontakty.csv -o otagowane.csv

# Z pełną kontrolą prywatności i budżetem
email-tagger classify -i kontakty.csv -o out.csv --privacy strict-local --budzet 0.50

# Walidacja pliku bez wysyłania do API
email-tagger validate -i kontakty.csv

# Test na małej próbce
email-tagger sample -i kontakty.csv --size 10

# Szacowanie kosztów przed runem
email-tagger estimate -i kontakty.csv --privacy cloud-minimized

🔒 Profil prywatności

Najważniejsza cecha produktu — kontrola jakie dane opuszczają Twoją maszynę.

strict-local

• Żadne dane nie opuszczają maszyny — używa lokalnego modelu (llama.cpp)
• Email hashowany, PII maskowane
• Idealne dla firm z twardymi wymogami compliance

cloud-minimized (domyślny)

• Tylko niezbędne pola: hash emaila + firma + stanowisko
• Email NIGDY nie jest wysyłany w czystej postaci
• PII w notatkach maskowane przed wysłaniem
• Użytkownik zatwierdza przed runem

enterprise

• Pełne dane, ale z gwarancją zero-data-retention u providera
• Wymaga świadomej zgody użytkownika

email-tagger classify -i kontakty.csv -o out.csv --privacy strict-local
email-tagger classify -i kontakty.csv -o out.csv --privacy cloud-minimized
email-tagger classify -i kontakty.csv -o out.csv --privacy enterprise

💰 Koszty

Model gpt-4o-mini: ~$0.15/1M tokenów input, ~$0.60/1M tokenów output.

Dla 1000 kontaktów (200 znaków każdy): **$0.001-0.005 za całość**.

Zawsze sprawdzaj koszt przed runem:

email-tagger estimate -i kontakty.csv

📦 Artefakty

Po każdym runie generowane są:

• otagowane.csv — główny wynik
• otagowane.report.json — raport z metrykami i dystrybucją tagów
• otagowane.errors.csv — błędy per kontakt

⚙️ Subkomendy CLI

Komenda	Opis
classify	Główne tagowanie kontaktów
validate	Sprawdza CSV bez API
sample	Test na małej próbce
estimate	Szacuje koszt bez wykonywania
cache stats	Statystyki cache
cache clear	Czyszczenie cache

Opcje classify

Flaga	Opis	Domyślnie
-i, --input	Ścieżka do CSV	wymagane
-o, --output	Ścieżka wyjściowa	wymagane
-b, --batch	Rozmiar batcha	10
-m, --model	Model AI	gpt-4o-mini
--provider	Provider (openai, local)	openai
--privacy	Profil prywatności	cloud-minimized
--budzet	Max koszt w USD	0 (brak)
--resume	Wznów przerwany run	—
--no-cache	Wyłącz cache	—
-y, --yes	Automatyczne potwierdzenie	—
--debug	Logowanie debug	—

🏗️ Architektura

src/email_tagger/
├── cli.py               # Interfejs CLI
├── models.py             # Pydantic modele (structured outputs)
├── types.py              # Typy pomocnicze
├── cache.py              # SQLite cache wyników
├── checkpoint.py         # Przyrostowy checkpoint/resume
├── cost_estimator.py     # Szacowanie kosztów
├── metrics.py            # Metryki i raporty
├── classifiers/
│   └── contact_classifier.py  # Główna logika klasyfikacji
├── privacy/
│   ├── redactor.py       # Maskowanie PII
│   ├── payload_builder.py # Budowa bezpiecznego payloadu
│   └── policies.py       # Polityki prywatności
├── providers/
│   ├── base.py           # Abstrakcyjny interfejs providera
│   ├── openai_provider.py # OpenAI API
│   ├── local_provider.py  # Lokalny model (llama.cpp)
│   └── factory.py        # Fabryka providerów
└── io/
    ├── readers.py        # Wczytywanie CSV
    ├── writers.py        # Zapis CSV
    └── artifacts.py      # Artefakty runa

🧪 Testy

pip install email-tagger[dev]
pytest tests/ -v

📄 Licencja

MIT — gotowe do komercyjnego użycia.