Company Scout — Dokumentation

Die Pipeline im Überblick

Company Scout findet Vertical-Software-Anbieter in D/AT/CH, bewertet sie 0–100 und zeigt nur die besten als Leads. Der Weg eines Kandidaten:

Discovery — Websuche je Vertical (Brave → SerpAPI → Tavily → DuckDuckGo als Fallback-Kette) findet Kandidaten und legt sie in die Analyse-Queue. Alternativ: manueller Import einer Firmenliste.
Analyse — pro Kandidat: Website laden → Inhalt aufbereiten → Vendor-Gate (ist es überhaupt ein Software-Anbieter?) → Datenextraktion → Geo-Gate (D/AT/CH?) → Anreicherung aus externen Quellen → Alters-Gate (Mindest-Firmenalter) → Ausschlussprüfung (z. B. AG/SE als Börsen-Indiz, kürzlich verkauft) → Nachfolge-Signale → CEO-Alter.
Scoring — aus allen Signalen entsteht ein Score 0–100 mit Begründung. Zwei Bänder: 🟢 TOP und 🟡 Qualified; alles darunter wird verworfen (mit Grund im Precheck-Archiv).
Regel-Review — automatische Plausibilitätsregeln markieren Leads ggf. mit „manuell prüfen".
LLM-Review (optional) — ein Sprachmodell liest gute Leads gegen, Details unter LLM-Review.
Staging → Production — Leads entstehen zuerst in Staging; erst der bewusst bestätigte Sync übernimmt sie nach Production.

Alle externen Quellen sind „best effort": Ausfälle führen zu „unbekannt", nie zum Abbruch der Pipeline.

Jobs & Scheduler

Die WebApp bringt einen eingebauten Scheduler mit, der im Hintergrund automatisch läuft (Ein/Aus über ops.scheduler_enabled):

🔍 Discovery — automatisch, Intervall ops.discovery_interval_minutes (Default alle 10 Min.)
🧪 Analyse — automatisch, Intervall ops.analysis_interval_minutes (Default alle 30 Min.)
🎯 Optimizer — automatisch, Intervall ops.optimizer_interval_minutes (Default alle 60 Min.); justiert die Suchstrategie anhand der Trefferquoten.
♻️ Re-Scoring, 🤖 LLM-Review und ✍️ Import — nur manuell (Pipeline-Tab) oder per CLI/Cron.
🔄 Komplette Re-Analyse — nur manuell (Pipeline-Tab). Reiht alle je in der Discovery gefundenen Firmen erneut ein und lässt die Analyse-Pipeline sie mit der aktuellen Config komplett neu bewerten (umgeht das Re-Analyse-Skip-Fenster). Läuft im Hintergrund und kann je nach Menge Stunden dauern; verursacht LLM-Kosten. Anders als ♻️ Re-Scoring (das nur vorhandene Leads aus gespeicherten Signalen neu rechnet) crawlt/extrahiert die Re-Analyse jede Firma frisch und kann so neue Leads erzeugen.

Die Karten unter „Automatik & Jobs" im Pipeline-Tab zeigen je Job: ob er automatisch läuft, den letzten Lauf ( erfolgreich / fehlgeschlagen — Fehlertext per Mouseover), ob gerade ein Lauf aktiv ist und die ungefähre Zeit des nächsten automatischen Laufs. Die Historie steht unter „Letzte Läufe" (dauerhaft gespeichert, überlebt Neustarts).

Jeder Schritt ist zusätzlich per CLI auslösbar (companyscout discover|analyze|optimize|rescore|llm-review), z. B. für eigene Cron-/systemd-Timer.

Schwellen & Scoring

thresholds.qualified — Qualified-Schwelle: Mindest-Score (0–100), ab dem ein Kandidat als 🟡 Qualified-Lead aufgenommen wird. Darunter wird er verworfen.
thresholds.top — TOP-Schwelle: Mindest-Score für das 🟢 TOP-Band — die vielversprechendsten Targets.
thresholds.min_company_age_years — Mindest-Firmenalter: Firmen, die jünger sind (in Jahren), fallen am Alters-Gate raus — junge Startups sind keine Nachfolge-Targets.
thresholds.lock_in_min_points_for_top — Lock-in-Minimum für TOP: Ohne diese Mindestpunktzahl an Lock-in-Signalen (Wechselkosten der Kunden: Datenhaltung, Integrationen, Branchenstandard …) bleibt ein Lead trotz hohem Score unter TOP gedeckelt.
exclusion.recently_sold_window_years — Verkaufs-Zeitfenster: Wurde die Firma innerhalb dieses Zeitfensters (Jahre) laut News-Suche bereits verkauft/übernommen, wird sie ausgeschlossen.

Alle Punktwerte und Gewichte stehen in der Tuning-Config (Konfigurations-Tab → „Gesamte Tuning-Config"). Nach Änderungen an Scoring-Parametern: „Speichern + Re-Scoring" — das bewertet vorhandene Leads aus ihren gespeicherten Rohsignalen neu, ohne neue Analysen zu starten.

Discovery

discovery.searches_per_run — Suchen pro Lauf: Wie viele Suchanfragen ein Discovery-Lauf absetzt. Höher = mehr Kandidaten pro Lauf, aber mehr API-Quota-Verbrauch bei den Such-Backends.

Analyse

analysis.batch_size — Batch-Größe: Wie viele Kandidaten ein Analyse-Lauf aus der Queue abarbeitet.
analysis.reanalyze_after_days — Re-Analyse nach Tagen: Nach so vielen Tagen wird eine bereits analysierte Firma erneut vollständig analysiert (Website und Signale können sich ändern).

Anreicherungsquellen

Externe Quellen (z. B. Handelsregister-Daten, OpenCorporates, Northdata), die fehlende Felder wie Gründungsjahr, Geschäftsführer oder Mitarbeiterzahl ergänzen. Jede Quelle lässt sich einzeln ein-/ausschalten (sources.<name>). Fällt eine Quelle aus, bleibt das Feld „unbekannt" — die Pipeline läuft weiter. Jeder übernommene Wert wird mit seiner Quelle als Evidence am Lead gespeichert.

sources.subpages — Website-Unterseiten: Ruft typische Unterseiten der Firmen-Website ab (/team, /über-uns, /historie, /presse …) und gewinnt so zusätzlichen Text für die Signal-Extraktion (Gründungsjahr, Geschäftsführer, Nachfolge-Hinweise). Keine externe API, keine Kosten.
sources.press — Presse & News (Websuche): Sucht per Web-Suche nach Meldungen zu Nachfolge, Firmenjubiläum, Ruhestand des Inhabers sowie zeitlich eingegrenzten Verkaufs-/ Übernahme-Meldungen. Verbraucht Such-API-Quota.
sources.wikidata — Wikidata / Wikipedia: Fragt die offene Wikidata-API nach Gründungsjahr und CEO-Geburtsjahr (daraus wird das Alter berechnet). Kostenlos, kein API-Key nötig; trifft vor allem bei bekannteren Firmen.
sources.opencorporates — OpenCorporates: Gründungsdatum und Officer-/Geschäftsführer-Daten aus dem internationalen Firmenregister-Aggregator. Läuft nur mit gesetztem OPENCORPORATES_API_KEY, sonst wird die Quelle übersprungen.
sources.gleif — GLEIF (LEI-Register): Rechtsform-Code und Sitz über die offene LEI-API des GLEIF-Registers — dient als Indiz für Börsennotierung oder PE-Besitz (Ausschlusskriterien). Kostenlos, kein Key nötig.
sources.register — Handelsregister (Websuche): Sucht Geschäftsführer-Angaben über öffentliche Snippets von unternehmensregister.de und northdata.de (best-effort, kein Registerabruf). Verbraucht Such-API-Quota.
sources.social — LinkedIn/Xing (Websuche): Sucht öffentliche LinkedIn-/Xing-Profile des CEO (ohne Login) für den Namens- und Altersabgleich. Verbraucht Such-API-Quota und ist nie ein Ablehnungsgrund.

LLM (Sprachmodell)

llm.provider — Provider: claude (Anthropic) oder openai — bestimmt, welcher API-Key und welches Modell genutzt wird.
llm.models.claude / llm.models.openai: Modellname je Provider (z. B. ein Claude- bzw. GPT-Modell).
llm.extraction_enabled — LLM-Extraktion: Nutzt das LLM zusätzlich zur regelbasierten Extraktion, um Felder (Produkt, Vertical, Gründungsjahr …) aus dem Website-Text zu lesen. Bessere Datenqualität, kostet aber API-Tokens pro analysierter Firma.

LLM-Review — was passiert da genau?

Der LLM-Review ist eine optionale Qualitätskontrolle nach dem Scoring: Ein Sprachmodell (Provider/Modell aus LLM) liest jeden Qualified-/TOP-Lead gegen und prüft, ob die extrahierten Signale plausibel zusammenpassen — z. B. ob das „Nachfolge-Signal" wirklich eine Nachfolge-Situation beschreibt oder nur ein missverstandener Newsartikel ist.

Geprüft werden nur Leads ab llm.review_min_score (spart Tokens: schwache Leads lohnen den Review nicht).
Das Modell liefert eine Entscheidung (bestätigt / Zweifel), eine Begründung und darf den Score anpassen — aber höchstens um ±llm.max_score_adjustment Punkte. Es kann einen Lead also nicht eigenmächtig von 40 auf 90 heben.
Ergebnis, Begründung und Anpassung stehen sichtbar in der Lead-Karte („LLM-Review"). Rohsignale werden nie verändert.
Jeder Lead wird pro Stand nur einmal reviewt (merkt sich die App); der Lauf startet manuell im Pipeline-Tab oder per CLI. Ohne passenden API-Key wird der Lauf übersprungen.

llm.review_enabled — LLM-Review aktiv: Schaltet den Review insgesamt ein/aus. Aus = Leads zeigen „deaktiviert".
llm.review_min_score — Review ab Score: Nur Leads mit mindestens diesem Score werden dem LLM vorgelegt.
llm.max_score_adjustment — Max. Score-Adjustment: Obergrenze (±Punkte), um die das LLM den Score verschieben darf.

Test/Benchmark — Scoring gegen bekannte Fälle prüfen

Der Test-Tab schickt eine gelabelte Firmenliste (Ground Truth: Positiv-Beispiele, die als Lead gefunden werden sollen, und Negativ-Beispiele, die aussortiert werden sollen) durch die echte Analyse-Pipeline. So lässt sich nach jeder Scoring-/Gate-Änderung schnell prüfen, ob die Kalibrierung noch stimmt.

Sandbox: Der Lauf nutzt ein temporäres Datenverzeichnis — Queue, Analysiert-Index und Leads der Installation bleiben unberührt. Nur das Ergebnis wird gespeichert.
PASS/FAIL: PASS heißt, das tatsächliche Ergebnis entspricht der Erwartung (lead bzw. reject). Ist ein erwarteter Ablehnungsgrund hinterlegt (z. B. company-too-young), muss auch der Grund passen.
Dauer/Kosten: Jede Firma wird wirklich abgerufen und angereichert (Websuche, ggf. LLM) — ein Lauf dauert einige Minuten und verbraucht Such-Quota. Er läuft im Hintergrund; der Fortschritt ist im Tab und in der Jobs-Übersicht sichtbar.
Liste bearbeiten: Die Liste liegt editierbar im Datenverzeichnis (benchmark.json, beim ersten Zugriff aus config/benchmark.example.json initialisiert) und wird auch vom CLI-Lauf companyscout benchmark genutzt.

Betrieb

ops.scheduler_enabled — Eingebauter Scheduler: Ein/Aus für die automatischen Hintergrund-Jobs (siehe Jobs & Scheduler). Aus = alles nur noch manuell/CLI.
ops.*_interval_minutes — Intervalle: Minuten-Abstand der automatischen Discovery-/Analyse-/Optimizer-Läufe. Kürzer = schnellerer Durchsatz, aber mehr API-Verbrauch.
ops.production_sync_requires_confirmation — Production-Sync-Gate: Wenn aktiv, verlangt der Staging→Production-Sync eine explizite Bestätigung — Schutz davor, ungeprüfte Daten zu veröffentlichen.

API-Keys

Keys werden aus Sicherheitsgründen nicht über die WebApp gesetzt oder angezeigt — nur der maskierte Status ist sichtbar. Gepflegt werden sie ausschließlich auf dem Server:

Datei config/keys.env (Vorlage: config/keys.example.env; im Docker-Deploy read-only in den Container gemountet), oder
Umgebungsvariablen — sie haben Vorrang vor der Datei.

Verwendete Keys: BRAVE_API_KEY, SERPAPI_KEY, TAVILY_API_KEY (Websuche) · ANTHROPIC_API_KEY / OPENAI_API_KEY (LLM) · OPENCORPORATES_API_KEY (Anreicherung) · DASHBOARD_PASSWORD, DASHBOARD_API_TOKEN (Login/API-Zugriff). Fehlt ein Key, wird die betreffende Quelle einfach übersprungen. Nach Änderungen an keys.env: App bzw. Container neu starten.