## What The Client Understands

They give a niche Restaurants, dentists, chiropractors, HVAC, lawyers, or vets, plus the city or region they want.
The agent researches Hermes searches Google Maps, visits websites, and collects public business contact information.
The agent checks quality Bad, duplicate, incomplete, or low-confidence records are rejected or retried.
The client receives leads The final output is a clean CSV/report with the fields needed for outreach and appointment setting.

## End-To-End Workflow

1

### Client Input

The client gives the business category, location, number of leads, and any exclusions.

What Hermes does Converts vague input into a structured job: niche, geography, target count, required fields, and delivery format.
Why this matters The agent cannot scrape correctly if the target is unclear. This step prevents wasted runs.
2

### Maps Discovery

Hermes searches Google Maps for the target businesses using Google-Maps-Scrapper.

What gets collected Business name, phone, address, website, rating, hours, category, and raw Maps result data.
Self-correction If results are weak, Hermes changes the query pattern, splits by city, or retries with a narrower keyword.
3

### Website Enrichment

Hermes uses Scrapling to visit each business website and extract deeper information.

What gets checked Contact page, about page, team page, service pages, footer, email links, and visible owner signals.
Self-correction If a site is dynamic or blocked, Hermes changes Scrapling fetch mode instead of failing immediately.
4

### Lead Extraction

The agent turns raw scraped text into a clean lead record.

Final fields Business name, phone, website, email, owner name if available, industry, location, and evidence source.
Important rule Hermes must never guess owner names or emails. Missing fields are marked clearly.
5

### Quality Gate

Every lead is checked before it reaches the client.

Checks Required field coverage, valid phone format, duplicate business detection, working website, and confidence score.
Client value The client receives fewer useless leads and more records that are ready for outreach.
6

### Delivery

Hermes exports the cleaned result and explains what happened during the run.

Files Clean CSV, raw JSONL evidence, enrichment log, and a short run report.
Report includes Total found, accepted, rejected, duplicates, failures, retries, and next recommendations.

## Hermes Skill Architecture

Hermes should run as one agent with a skill bundle. Each skill has a narrow responsibility, which makes the workflow easier to test, improve, and explain to clients.

- `lead-intake` normalizes client input.
- `maps-discovery` handles Google Maps search and raw place data.
- `website-enrichment` handles Scrapling website crawling.
- `lead-extractor` converts messy evidence into structured records.
- `quality-gate` validates, scores, dedupes, and rejects weak records.
- `skill-evolver` records proven fixes and updates the failing skill.

### Planner

Decides the next action and keeps the job moving without mixing all logic into one prompt.

### Discovery

Uses Google-Maps-Scrapper as the first source of business candidates.

### Enrichment

Uses Scrapling to read websites and contact pages when Maps data is not enough.

### Extraction

Converts public evidence into strict lead fields.

### Verification

Protects the client from bad, duplicate, or guessed data.

### Learning

Saves only useful fixes that improve the next run.

## Self-Evolving Control Loop

Detect Hermes catches empty results, blocked pages, missing emails, duplicate spikes, invalid phones, and low lead quality.
Classify The failure is labeled as query issue, tool issue, parser issue, website issue, schema issue, or client-input issue.
Retry Hermes changes only one variable at a time: query, location split, fetch mode, timeout, page list, or selector.
Evolve If the retry works, Hermes proposes a skill update so the same problem is handled better next time.
Resume Hermes reruns the failed step only, preserving the good data already collected.

## Tool Decision Rules

### Google-Maps-Scrapper

- Use first for local business discovery.
- Run by niche and city, not one broad query.
- Save raw output before cleaning.
- Retry with alternate query forms when coverage is low.

### Scrapling

- Use second for website enrichment.
- Start with simple fetch mode for speed.
- Use dynamic fetch mode for JavaScript-heavy sites.
- Use stealth or slower settings only when normal crawling fails and policy allows it.

### Human Approval

- Required before outbound client messaging.
- Required before using aggressive scraping settings.
- Required when the agent wants to promote a skill update.
- Required when quality thresholds are not met.

## Lead Data Contract

Field | Required | Primary Source | Client-Friendly Explanation
--- | --- | --- | ---
Business Name | Yes | Google Maps | The official visible name of the business.
Phone | Yes | Google Maps and website | The number the outreach agent can call.
Website | Preferred | Google Maps | The business site used for enrichment and proof.
Email | Preferred | Scrapling website crawl | A public business email, preferably from the company domain.
Owner Name | No | About/team pages | Included only when found directly. The agent does not guess.
Industry | Yes | Client keyword and Maps category | Restaurants, dentists, chiropractors, HVAC, lawyers, or vets.
Location | Yes | Google Maps | Address, city, state, and country when available.
Quality Score | Yes | Hermes quality gate | A 0 to 100 score showing how usable the lead is.

## Client Proof Points

### Clean Output

The client receives `clean_leads.csv` plus a short report instead of messy scraper output.

### Evidence Trail

Each enriched field should keep a source URL or extraction note so the result can be audited.

### Improving Runs

Failures are not just logged. They become proposed skill improvements after validation.

## Hermes Build Prompt

    Use /local-lead-engine.

    Client input:
      niche: {{restaurants | dentists | chiropractors | HVAC | lawyers | vets}}
      location: {{city_or_region}}
      target_leads: {{number}}
      exclusions: {{optional}}

    Workflow:
      1. Normalize the client input.
      2. Use Google-Maps-Scrapper to find business candidates.
      3. Save raw Maps results before cleaning.
      4. Use Scrapling to crawl each available website.
      5. Extract business_name, phone, website, email, owner_name_if_available, industry, location.
      6. Validate and dedupe records.
      7. Score each lead from 0 to 100.
      8. Export clean_leads.csv, raw evidence files, and run_report.md.

    Self-evolving rule:
      If a step fails, classify the failure, retry with one changed variable, and propose a skill update only when the retry improves the validation result.

    Safety rule:
      Never guess unavailable owner names or emails. Mark unknown fields clearly.
      Do not send outbound messages without human approval.

## Build Phases

### Phase 1: Single City

Test one niche in one city. Confirm Maps scraping, raw output, and basic CSV delivery.

### Phase 2: Enrichment

Add website crawling and evidence tracking. Confirm email and owner extraction quality.

### Phase 3: Quality Gate

Add scoring, dedupe, rejection reasons, and run reports.

### Phase 4: Self-Evolve

Add failure classification, retry rules, and skill patch proposals.

### Phase 5: Client Delivery

Package CSV, report, and evidence files for review.

### Phase 6: Scale

Run multiple niches and locations with controlled rate limits and reporting.

## Important Boundaries

This workflow should use public business data only, obey the client agreement, respect rate limits, avoid guessing personal data, and require human approval before outbound sales activity. The agent can improve its skills, but skill changes should be reviewed before promotion in production.