email-tagger 0.2.0__tar.gz

email_tagger-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 email-tagger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

email_tagger-0.2.0/PKG-INFO

@@ -0,0 +1,181 @@
+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.

email_tagger-0.2.0/README.md

@@ -0,0 +1,154 @@
+# 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.

email_tagger-0.2.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "email-tagger"
+version = "0.2.0"
+description = "AI Email Contact Tagger — klasyfikacja kontaktów z kontrolą prywatności"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "email-tagger team", email = "dev@email-tagger.example"},
+]
+
+dependencies = [
+    "pydantic>=2.0",
+    "pandas>=2.0",
+    "rich>=13.0",
+    "tenacity>=8.0",
+    "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+openai = [
+    "openai>=1.0",
+]
+local = [
+    "llama-cpp-python>=0.2",
+]
+all = [
+    "email-tagger[openai,local]",
+]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1",
+    "mypy>=1.0",
+]
+
+[project.scripts]
+email-tagger = "email_tagger.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["email_tagger*"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

email_tagger-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

email_tagger-0.2.0/src/email_tagger/cache.py

@@ -0,0 +1,97 @@
+"""
+email_tagger.cache — Lokalny cache wyników klasyfikacji.
+
+Unika wielokrotnego wysyłania tych samych danych do API.
+Klucz cache: hash znormalizowanych danych wejściowych.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import sqlite3
+from pathlib import Path
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class ClassificationCache:
+    """
+    SQLite-based cache dla wyników klasyfikacji.
+
+    Przechowuje hash payloadu -> wynik TagResult jako JSON.
+    Domyślnie w ~/.email-tagger/cache.db z TTL 30 dni.
+    """
+
+    def __init__(self, sciezka: Optional[Path] = None) -> None:
+        if sciezka is None:
+            sciezka = Path.home() / ".email-tagger" / "cache.db"
+        self.sciezka = sciezka
+        self.sciezka.parent.mkdir(parents=True, exist_ok=True)
+        self._conn: Optional[sqlite3.Connection] = None
+
+    @property
+    def conn(self) -> sqlite3.Connection:
+        if self._conn is None:
+            self._conn = sqlite3.connect(str(self.sciezka))
+            self._conn.execute(
+                """CREATE TABLE IF NOT EXISTS cache (
+                    klucz TEXT PRIMARY KEY,
+                    wynik TEXT NOT NULL,
+                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+                )"""
+            )
+            self._conn.execute("CREATE INDEX IF NOT EXISTS idx_cache_created ON cache(created_at)")
+            self._conn.commit()
+        return self._conn
+
+    def klucz(self, payload: dict[str, Any]) -> str:
+        """Generuje klucz cache z payloadu."""
+        raw = json.dumps(payload, sort_keys=True, ensure_ascii=False)
+        return hashlib.sha256(raw.encode()).hexdigest()
+
+    def pobierz(self, payload: dict[str, Any]) -> Optional[dict[str, Any]]:
+        """Próbuje pobrać wynik z cache."""
+        k = self.klucz(payload)
+        row = self.conn.execute("SELECT wynik FROM cache WHERE klucz = ?", (k,)).fetchone()
+        if row:
+            logger.debug("Cache HIT: %s", k[:12])
+            return json.loads(row[0])
+        logger.debug("Cache MISS: %s", k[:12])
+        return None
+
+    def zapisz(self, payload: dict[str, Any], wynik: dict[str, Any]) -> None:
+        """Zapisuje wynik do cache."""
+        k = self.klucz(payload)
+        self.conn.execute(
+            "INSERT OR REPLACE INTO cache (klucz, wynik) VALUES (?, ?)",
+            (k, json.dumps(wynik, ensure_ascii=False)),
+        )
+        self.conn.commit()
+
+    def czysc_stare(self, dni: int = 30) -> int:
+        """Usuwa wpisy starsze niż N dni. Zwraca liczbę usuniętych."""
+        usuniete = self.conn.execute(
+            "DELETE FROM cache WHERE created_at < datetime('now', ?)",
+            (f"-{dni} days",),
+        ).rowcount
+        self.conn.commit()
+        if usuniete:
+            logger.info("Wyczyszczono %d starych wpisów cache", usuniete)
+        return usuniete
+
+    def statystyki(self) -> dict:
+        """Zwraca statystyki cache."""
+        total = self.conn.execute("SELECT COUNT(*) FROM cache").fetchone()[0]
+        return {
+            "sciezka": str(self.sciezka),
+            "wpisy": total,
+            "rozmiar_mb": round(self.sciezka.stat().st_size / 1_000_000, 2) if self.sciezka.exists() else 0,
+        }
+
+    def zamknij(self) -> None:
+        if self._conn:
+            self._conn.close()
+            self._conn = None

email_tagger-0.2.0/src/email_tagger/checkpoint.py

@@ -0,0 +1,71 @@
+"""
+email_tagger.checkpoint — Przyrostowy checkpoint i resume.
+
+Zapisuje postęp po każdym batchu, pozwala wznowić po przerwaniu.
+Krytyczne dla produkcyjnego użycia — bez tego każdy crash = strata całej pracy.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class Checkpoint:
+    """
+    Checkpoint dla przyrostowego przetwarzania batchy.
+
+    Zapisuje do pliku JSON:
+    - indeks ostatniego przetworzonego wiersza
+    - całkowitą liczbę wierszy
+    - timestamp i model
+    """
+
+    def __init__(self, sciezka: Path) -> None:
+        self.sciezka = sciezka
+        self._dane: dict[str, Any] = {}
+
+    def wczytaj(self) -> Optional[dict[str, Any]]:
+        """Wczytuje checkpoint z pliku. Zwraca None jeśli nie istnieje."""
+        if not self.sciezka.exists():
+            return None
+        try:
+            with open(self.sciezka) as f:
+                self._dane = json.load(f)
+            logger.info("Wczytano checkpoint: %s", self.sciezka)
+            return self._dane
+        except (json.JSONDecodeError, OSError) as e:
+            logger.warning("Nie można wczytać checkpointu: %s", e)
+            return None
+
+    def zapisz(self, indeks: int, ogolem: int, **extra) -> None:
+        """Zapisuje checkpoint."""
+        self._dane = {
+            "indeks": indeks,
+            "ogolem": ogolem,
+            "procent": round(indeks / ogolem * 100, 1) if ogolem > 0 else 0,
+            **extra,
+        }
+        self.sciezka.parent.mkdir(parents=True, exist_ok=True)
+        with open(self.sciezka, "w") as f:
+            json.dump(self._dane, f, indent=2, ensure_ascii=False)
+        logger.info("Checkpoint: %d/%d (%.1f%%)", indeks, ogolem, self._dane["procent"])
+
+    @property
+    def ostatni_indeks(self) -> int:
+        """Zwraca indeks ostatniego przetworzonego wiersza."""
+        return self._dane.get("indeks", -1)
+
+    @property
+    def czy_istnieje(self) -> bool:
+        return self.sciezka.exists()
+
+    def usun(self) -> None:
+        """Usuwa plik checkpointu — po zakończonym runie."""
+        if self.sciezka.exists():
+            self.sciezka.unlink()
+            logger.info("Usunięto checkpoint: %s", self.sciezka)