Reply Pilot Wholesale Scout

Tahle stranka popisuje batch modul reply-pilot-wholesale-scout/ pro discovery, overovani a prvni kvalifikaci velkoobchodnich dodavatelu.

Proc je to rozdelene do vice kroku

Jednim promptem na kategorii sice rychle dostaneme hruby seznam firem, ale pro prakticke obchodni pouziti to nestaci. Potrebujeme oddelit:

  1. discovery: kandidatni seznam firem pro kategorii
  2. enrichment: overeni webu, B2B portalu, kontaktu a feed moznosti
  3. scoring: strojove shortlistovani pred rucnim rozhodnutim
  4. outreach: generace prvniho osloveni az po schvaleni leadu

Tohle je spravnejsi pristup nez jeden velky prompt, protoze:

  • snizuje halucinace u obchodnich faktu
  • umoznuje levne ladit discovery na male sadě a az pak prepnout na Batch API
  • drzi auditni stopu po kategoriich i po kandidátech
  • dovoluje menit scoring nebo outreach bez znovuskenovani internetu

Modulovy layout

reply-pilot-wholesale-scout/ obsahuje:

  • reply_pilot_wholesale_scout/: vlastni Python balicek a CLI
  • scripts/*.py: tenke wrappery pro jednotlive kroky pipeline
  • conf/category-query.example.sql: vzor SQL dotazu do CmD DB
  • conf/existing-suppliers-query.sql: lookup dotaz pro porovnani proti CME
  • conf/company-profile.example.md: vstup pro outreach generaci
  • data/runs/<run-name>/: artefakty jednotlivych batch behu

Skripty V Repozitari

V repozitari jsou dva typy skriptu:

  • wrapper skripty v scripts/*.py, ktere jen predavaji argumenty do jednotneho CLI
  • pomocny scripts/test.sh, ktery sklada bezny lokalni postup z nekolika commandu

Pro lokalni praci je dulezite, ze commandy jako scout, result-print, scout-finalize nebo deduplication_cme jsou casto volane prave pres reply-pilot-wholesale-scout/scripts/test.sh, ne nutne rucne po jednom.

Aktualni skripty:

  • scripts/scout.py: hlavni vstupni bod. Pousti vsechny subcommandy modulu.
  • scripts/export_categories.py: zkratka pro export-categories.
  • scripts/result-print.py: zkratka pro result-print.
  • scripts/test.sh: lokalni smoke-test helper. Neni to produkcni pipeline; jen shell funkce nad castymi kroky.

Aktualni helpery v scripts/test.sh:

  • categories() -> python3 scripts/scout.py export-categories ...
  • prompt_scout() -> python3 scripts/scout.py scout ...
  • result_print() -> python3 scripts/scout.py result-print ...
  • scout_finalize() -> python3 scripts/scout.py scout-finalize ...
  • deduplication_cme() -> python3 scripts/scout.py deduplication_cme ...
  • enrichment() -> python3 scripts/scout.py prepare-enrichment-batch --input ... a pak run-local-enrichment --dry-run false

Co Delaji Jednotlive Commandy

export-categories:

  • nacte SQL z --query, --query-file nebo conf/category-query.sql
  • pripoji se do CmD/CME DB
  • vrati seznam kategorii pro dalsi zpracovani

prepare-discovery-batch:

  • z exportovanych kategorii pripravi Batch API requesty pro discovery
  • vysledkem je discovery.requests.jsonl

run-local-stage:

  • umi stejny stage pustit lokalne bez Batch API
  • hodi se na ladeni promptu a schema nad malym vzorkem

run-local-enrichment:

  • specializovana lokalni varianta pro enrichment
  • bere explicitni input/output soubory
  • defaultne bezi v dry-run rezimu; pro skutecne API volani pouzij --dry-run false

submit-batch:

  • odesle pripraveny *.requests.jsonl do OpenAI Batch API

collect-batch:

  • stahne vysledky batch jobu
  • normalizuje je do *.records.jsonl, aby se s nimi dalo dal pracovat

prepare-enrichment-batch:

  • vezme discovery kandidaty
  • nebo explicitni deduplikovany supplier vstup pres --input
  • deduplikuje je v ramci discovery
  • pripravi detailnejsi overovaci request pro kazdou firmu
  • vraci striktni JSON s homepage, company_identifiers, electronic_communication a contact_people pro konkretni B2B role

score-leads:

  • vyhodnoti enrichment vystup
  • prida heuristicke score a rozhodnuti, jestli lead kontaktovat, zrevidovat nebo zahodit

prepare-outreach-batch:

  • ze schvalenych leadu pripravi prvni osloveni

scout:

  • je oddeleny od batch pipeline
  • slouzi pro lokalni prompt experimenty nad CSV kategorii
  • vystupem je scout-results.jsonl

result-print:

  • nacte scout-results.jsonl
  • po variant vypise statistiky, prompt changes, summary a supplier tabulky

scout-finalize:

  • z scout-results.jsonl vytahne supplier polozky
  • zapise je do CSV se sloupci supplier_name, website, why_relevant, b2b_signal
  • duplicity ponechava

deduplication_cme:

  • nacte supplier vstup z CSV nebo JSONL
  • nacte CME lookup pres conf/existing-suppliers-query.sql
  • duplicity proti CME vypise do konzole
  • ne-duplicitni radky zapise do CSV

Jak Vyhodnocujeme Spolupraci S Firmou

V praxi dnes nepouzivame cernobile pravidlo spolupracujeme nebo nespolupracujeme. Pouzivame opatrnejsi vyklad:

  • firma uz je v CME vedena
  • firma uz je v CME technicky napojena
  • firma je uz v CME rozpracovana

To znamena, ze deduplication_cme dnes odpovida hlavne na otazku:

  • uz tu firmu v CME nejak mame?

Neodpovida jeste presne na otazku:

  • je to nas aktivni a bezici obchodni partner?

Jak To Cist Obchodne

Z CME dnes rozlisujeme tri prakticke situace:

  • supplier_integrated: velmi silny signal, ze firmu uz realne pouzivame nebo jsme ji meli napojenou
  • dodavatel_only: firma je u nas vedena jako dodavatel, ale nemusi to znamenat aktivni spolupraci prave ted
  • onboarding_only: firma je u nas uz rozpracovana, ale jeste nemusi byt finalne zavedena

Pro scouting se vsechny tri situace dnes berou jako:

  • tuhle firmu uz zname a nechceme ji znovu nabizet jako novy lead

To je zamer. Cilem je, aby scout znovu nevracel firmy, ktere uz CME nekde ma, resi nebo zavadi.

Jak Se Rozhoduje, Ze Jde O Stejnou Firmu

Rozhodnuti nestoji jen na nazvu firmy. Nejvetsi vahu ma:

  • firemni web nebo domena
  • dalsi identifikatory jako IČO, DIČ nebo kontaktni e-mail
  • az potom samotny nazev firmy

Prakticky to znamena:

  • kdyz sedi web nebo domena, je to silny signal, ze jde o stejnou firmu
  • kdyz web chybi, muzeme se oprit o presny a ocisteny nazev firmy
  • kdyz je firma jen v onboarding datech, porad ji radeji bereme jako uz resenou

Co Je Dnes Konzervativni Pravidlo

Dnes plati jednoduche business pravidlo:

  • pokud firma vypada, ze uz je v CME evidovana nebo rozpracovana, vyhodime ji ze seznamu novych leadu

To je schvalne prisnejsi. Je lepsi poslat k rucni kontrole jednu firmu navic, nez znovu otevrit firmu, kterou uz nekdo v CME davno zna.

Kdybychom Chteli Prisnejsi Vyklad "Spolupracujeme"

Pokud bychom chteli opravdu jen aktivni partnery, museli bychom pravidlo zprisnit tak, aby za skutecnou spolupraci povazovalo jen firmy, ktere:

  • jsou v hlavni evidenci dodavatel
  • jsou aktivni
  • a idealne jsou i technicky integrovane

Pak by cast dnesnich duplicit uz nebyla aktivni spoluprace, ale jen:

  • firmu uz zname
  • firmu uz nekdo rozpracoval

Workflow

  1. export_categories.py Nacte kategorie z CmD DB pres konfigurovatelny SQL dotaz. Aktualni default dotaz cte leaf kategorie z kategorie/kategorie_nazev/jazyk, filtruje je pres --language a umi zapis jak categories.jsonl, tak CSV pres --output. Podporuje i --limit a --offset.
  2. prepare_discovery_batch.py Pro kazdou kategorii pripravi validni Batch API request do /v1/responses s web_search toolem a JSON schema vystupem.
  3. run_local_stage.py Stejne requesty umi pustit lokalne po jednom. To je urcene pro ladeni promptu a schema bez cekani na Batch API.
  4. submit_batch.py a collect_batch.py Odeslou pripraveny .jsonl soubor do OpenAI Batch API a pozdeji stahnou vysledky.
  5. prepare_enrichment_batch.py Rozlozi discovery vysledky na jednotlive firmy a pripravi detailnejsi overovaci batch.
  6. score_leads.py Doda prvni heuristicke obchodni score z overenych dat.
  7. prepare_outreach_batch.py Z vybranych leadu pripravi batch pro prvni oslovovaci e-maily.

Datovy kontrakt

Kazda stage zapisuje strukturovane artefakty:

  • *.requests.jsonl: Batch API vstup
  • *.raw-results.jsonl: surova API odpoved
  • *.records.jsonl: normalizovana odpoved s parsed, parse_error a web_sources

To je dulezite pro dalsi automaticke zpracovani i pro rucni audit.

Otevrene body k doplneni

Aktualni kostra zamerne nechava par veci konfigurovatelnych, protoze zatim nejsou v repozitari zadane:

  • konkretni CmD DB engine a driver
  • presny SQL dotaz pro seznam kategorii
  • obchodni scoring pravidla nad realnymi prioritami firmy
  • finalni ton a obsah prvniho oslovení

Vazba na OpenAI API

Navrh stoji na Responses API, protoze umi kombinovat:

  • web_search pro aktualni internetove zdroje
  • text.format = json_schema pro striktni strukturovany vystup
  • Batch API pro levnejsi offline zpracovani pripravenych requestu

Relevantni oficialni dokumentace:

Doporuceni k dalsimu kroku

Nejdriv doved:

  1. realny export kategorii z CmD DB
  2. jednu nebo dve kategorie pres run_local_stage.py
  3. upravu discovery a enrichment promptu podle realnych vysledku

Az potom ma smysl pustit plny Batch API beh nad vsemi kategoriemi.