# EOZ — End of Zusammenarbeit
**Projekt:** Lead Engine — B2B Lead-Enrichment-Engine
**Datum:** 2026-05-08

---

## PROJEKTZIEL

Automatisierte B2B-Lead-Enrichment-Engine. Liest rohe Kontaktdaten (Name, Website, Email), recherchiert via Multi-Source-Discovery und reichert mit LLM-Router an.

**Kein Email-Versand. Kein Agent. Nur Datenanreicherung.**

**Erste Zielkampagne:** 88 Portier EU Kiosk Leads (Mario's Liste, source_id 1–132)

---

## TECHNIK-STACK

| Komponente | Technologie |
|-----------|------------|
| Sprache | Python 3.13 (keine venv, direkt installiert) |
| LLM Router | OpenAI: gpt-5-nano (L1) → gpt-5-mini (L2) → gpt-5.2 (L3) |
| Discovery | DuckDuckGo HTML + BeautifulSoup (7 Queries/Kontakt) |
| Datenbank | SQLite (`email_agent.db` — Umbenennung zu `leads.db` steht aus!) |
| Dashboard | Streamlit (`dashboard.py`, Port 8501) |
| Excel Export | `excel_exporter.py` mit Farbkodierung |

---

## DATEISTRUKTUR

```
lead_engine/
├── contact_enricher.py         ← Haupt-Enricher (2-Phase Prompt)
├── multi_source_enricher.py    ← Mit Discovery Layer
├── icp_classifier.py           ← ICP-Klassifikation (Portier vs. LP)
├── cold_outreach_db.py         ← SQLite Wrapper
├── excel_exporter.py           ← Excel mit Farbkodierung
├── excel_importer.py           ← Import aus Mario's Excel-Liste
├── dashboard.py                ← Streamlit UI
├── outreach_generator.py       ← Email-Text Generierung
├── outreach_orchestrator.py    ← Outreach-Ablauf
├── review_cli.py               ← CLI Review vor dem Senden
├── email_agent.db              ← ⚠️ NICHT LÖSCHEN — aktive Datenbank
├── .env                        ← ⚠️ NICHT COMMITTEN — API Keys
├── llm/
│   ├── router.py               ← 3-Level Router + Cost Guard (25k Token-Budget/Kontakt)
│   ├── validator.py            ← Staged Validation (CRITICAL/IMPORTANT/OPTIONAL)
│   ├── logger.py               ← Audit Log
│   ├── openai_provider.py      ← OpenAI API
│   └── base.py                 ← Abstract Provider
└── discovery/
    ├── orchestrator.py         ← Discovery koordinieren
    ├── query_builder.py        ← 7 Search-Queries pro Firma
    ├── search.py               ← DuckDuckGo HTML Suche
    ├── scraper.py              ← URL-Scraping
    └── parser.py               ← Text-Extraktion + Location-Parsing
```

---

## KAMPAGNEN-STATUS (Kampagne 6 — Portier EU Kiosk)

| Status | Anzahl |
|--------|--------|
| enriched | 54 |
| raw (noch anreichern) | 27 |
| low_data_lead | 6 |
| needs_manual | 1 |
| **Gesamt** | **88** |

**Enrichment gestoppt** — manuell neu starten wenn nötig.

---

## KRITISCHE REGELN

1. **DB heißt noch `email_agent.db`** — Umbenennung zu `leads.db` steht aus, erst nach Pfad-Fix
2. **dotenv-Pfad immer absolut:** `load_dotenv(Path(__file__).parent / '.env', override=True)`
3. **gpt-5-nano/mini sind Reasoning Models** → `max_completion_tokens` statt `max_tokens`, kein `temperature`, kein `response_format`
4. **source_id = Mario's original list_index (1–132)** — NIEMALS verändern (Traceability)
5. **email_agent.db NIEMALS löschen** ohne laufenden Beweis des Nachfolgesystems
6. **.env NIEMALS lesen oder ausgeben** — API Keys bleiben privat

---

## STARTEN

```bash
cd lead_engine

# Dashboard:
streamlit run dashboard.py

# Enrichment (alle raw Kontakte):
python multi_source_enricher.py --campaign 6

# Excel-Export:
python excel_exporter.py
```

---

## OFFENE AUFGABEN

1. Hardcoded Pfade fixen — alle `email_agent.db` Referenzen → `leads.db`
2. 27 raw Kontakte enrichen
3. 6 low_data_lead — Handelsregister.de / Northdata.de als Quelle prüfen
4. Dashboard UI — kompaktes Kartenlayout (Spec vorhanden, noch nicht umgesetzt)
5. Auto-Refresh Fix — `streamlit-autorefresh` statt meta-http-refresh

---

## VERBINDUNGEN

- **Portier:** `K:\Projekte-AG\portier\` — Lead-Quelldaten (Excel-Exports dort)
- **Email-Agent:** `K:\Projekte-AG\agents\email_agent\` — Outreach nach Enrichment
- **Mario:** Liefert Lead-Listen als Excel