Metadata-Version: 2.4
Name: email-tagger
Version: 0.2.0
Summary: AI Email Contact Tagger — klasyfikacja kontaktów z kontrolą prywatności
Author-email: email-tagger team <dev@email-tagger.example>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: pandas>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: tenacity>=8.0
Requires-Dist: python-dotenv>=1.0
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: local
Requires-Dist: llama-cpp-python>=0.2; extra == "local"
Provides-Extra: all
Requires-Dist: email-tagger[local,openai]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# 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

```bash
# 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:
```bash
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

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

## 📄 Licencja

MIT — gotowe do komercyjnego użycia.
