convez.ai
Agente
WiseGitter

buyer-agent

WiseGitter/buyer-agent

Ver no GitHub
InicialPluginScore · de 0 a 100

A small Python pipeline that uses Claude, the Wikipedia/Wikidata APIs, and a SQLite event log to discover, score, enrich, and draft outreach for European B2B sales leads.

Instalação

$npx convez-ai WiseGitter/buyer-agent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Buyer Agent

A small autonomous pipeline that discovers, scores, and enriches European B2B sales leads — built originally to find truck and trailer manufacturers in Germany and Poland for an import-export business from India.

The interesting part isn't the LLM; it's the scaffolding around it. This repo is a worked example of how to wrap an LLM into a real, observable, idempotent system.

What it does

A single python main.py runs the full pipeline:

  1. Discover candidate manufacturers via the Wikipedia and Wikidata APIs (Wikidata's P856 property gives curated official-website URLs — far more reliable than scraping Wikipedia HTML).
  2. Score each company against a product catalog using Claude (Haiku for cost-effective scoring; Sonnet for higher-quality drafting). The scoring step uses forced tool-use to guarantee structured output — no JSON parsing, no markdown fences.
  3. Enrich each scored company by crawling its own website for published procurement emails. Multilingual keyword detection (EN / DE / PL) finds contact, imprint, and supplier pages. A heuristic ranker picks the best email and down-weights GDPR / DPO addresses.
  4. Draft personalized outreach for the strongest matches, with the scoring step's reasoning piped forward as the email's hook.
  5. Sync to a Notion CRM via the Notion REST API. Subsequent runs update existing pages (create-or-update / upsert pattern) rather than creating duplicates.

A human approval gate in Notion sits between drafted outreach and anything that actually reaches a real inbox. Nothing sends automatically.

Architecture

┌──────────┐   ┌──────┐   ┌────────┐   ┌──────┐   ┌────────┐
│ Discover │──▶│Score │──▶│Enrich  │──▶│Draft │──▶│ Sync   │
│          │   │      │   │contact │   │      │   │ Notion │
└──────────┘   └──────┘   └────────┘   └──────┘   └────────┘
      │            │           │           │           │
      └────────────┴───────────┴───────────┴───────────┘
                              │
                              ▼
                ┌──────────────────────────┐
                │  SQLite source of truth  │
                │   (state + event log)    │
                └──────────────────────────┘
                              │
                              ▼
                ┌──────────────────────────┐
                │  Streamlit dashboard     │
                │ (analytical surface)     │
                └──────────────────────────┘
  • SQLite is the canonical state. Two tables: companies (mutable per-row state) and events (immutable append-only log of every API call — model, tokens, cost in USD, latency, errors).
  • Notion is the operational surface — where you work the leads.
  • Streamlit is the analytical surface — KPI cards, funnel chart, fit-score histogram, cumulative cost over time, recent activity.
  • The pipeline is idempotent — re-runs pick up where they left off, never re-process, never double-charge.

Stack

Python · Anthropic API (Claude Haiku + Sonnet, forced tool-use) · Wikipedia + Wikidata APIs · Notion API · BeautifulSoup · SQLite · Streamlit · Tenacity (retries with exponential backoff).

Sample result

First run on 26 manufacturers in Germany and Poland:

  • Working procurement emails extracted for ~75% of companies.
  • Failures were almost all JS-rendered sites that would need a headless browser to crawl.
  • Total LLM cost: under $0.20.

Run it yourself

Heads up: running this uses your own Anthropic and Notion API keys. Expect roughly $0.20 per 26-company batch. The repo ships with no credentials.

  1. Clone the repo and create a Python virtualenv.
  2. pip install -r requirements.txt
  3. Get an Anthropic API key and a Notion integration token.
  4. Create a Notion database with the right schema (see buyer_agent/storage.py for the expected property names) and share it with your integration.
  5. Create a .env file at the project root:
   ANTHROPIC_API_KEY=sk-ant-...
   NOTION_API_KEY=ntn_...
  1. Update DATA_SOURCE_ID in config.py with your Notion data-source ID.
  2. Create your product catalog by copying the example:
   cp buyer_agent/catalog.py.example buyer_agent/catalog.py

Then edit buyer_agent/catalog.py to describe what your business sells. The catalog is the reference frame Claude uses to score companies. 8. Run: python main.py 9. View the dashboard: streamlit run dashboard.py

Project layout

.
├── main.py                         # orchestrator + CLI
├── dashboard.py                    # Streamlit analytics dashboard
├── config.py                       # settings + secrets loader
├── requirements.txt
└── buyer_agent/
    ├── catalog.py                  # product catalog (what we sell)
    ├── discovery.py                # candidate-discovery interface
    ├── scoring.py                  # Claude scoring (forced tool-use)
    ├── drafting.py                 # Claude outreach drafting
    ├── storage.py                  # Notion REST API (create + update)
    ├── database.py                 # SQLite layer (schema as code)
    └── scrapers/
        ├── wikipedia.py            # Wikipedia + Wikidata discovery
        └── contacts.py             # company-website email scraper

What's next

  • Playwright-based scraper for the IAA Transportation exhibitor directory (JavaScript-rendered SPA — needs a headless browser).
  • Second enrichment pass using the LLM to infer company size and procurement structure from the Wikipedia summary.
  • Scheduled runs (cron / GitHub Actions) so discovery picks up newly-published companies over time.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados