# Screen Leads

Turn a browser tab you have open on a profile into a structured lead. The tool
screenshots the screen, scrolls, runs the images through Claude vision, and
saves normalised leads to a database you browse and control from a dashboard.

Screen-capture only: it reads pixels a human already chose to display and never
touches the target site's servers or DOM. LinkedIn is the first supported site;
new sites drop in as recipes.

## How it works

```
Start (dashboard) → detect front tab → [stop unless it's an enabled
site's target page, e.g. a LinkedIn profile] → scroll + screenshot loop →
Claude vision extraction → normalise to canonical Lead → SQLite → dashboard
```

- **Guard** — runs only when the front tab is an enabled recipe's *target* page
  (a LinkedIn `/in/` profile). On anything else it stops (set
  `SCREEN_LEADS_ON_INVALID_PAGE=wait` to poll instead).
- **Detection** — reads your own browser's URL where possible (macOS reliably),
  otherwise the AI reads the address bar from the screenshot. Both are passive.
- **Contact info** — name/headline/company come from the profile page. Email &
  phone live behind LinkedIn's **Contact info** panel: open it yourself before
  capture and the tool will read whatever is shown. Often it simply isn't there.
- **Funnel** — every lead is normalised to one schema and advances
  `NEW → ENRICHED → CONTACT_FOUND → EXPORTED` as data completeness grows.

## Setup

```bash
# 1. Get the code
git clone https://git.thecaoffice.com/OpenSource/screen-leads-app.git
cd screen-leads-app

# 2. One-time setup — venv, dependencies, and prompts for your API key
./setup.sh          # Windows: setup.bat

# 3. Run it
./run.sh            # Windows: run.bat
```

`setup.sh` creates the virtualenv, installs dependencies, and writes your
`ANTHROPIC_API_KEY` to `.env`. `run.sh` launches the dashboard — open
http://127.0.0.1:8000 and use **Start / Pause / Stop**.

<details><summary>Manual steps (no scripts)</summary>

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-ant-...
python main.py
```
</details>

### OS permissions (grant once)

| OS | Needs |
|----|-------|
| macOS | System Settings → Privacy & Security → **Screen Recording** and **Accessibility** for your terminal/app. Automation permission for the browser enables exact URL detection. |
| Windows | Usually none. `pip install uiautomation` enables native URL detection. |
| Linux | Use an **X11** session. Wayland can't capture/scroll via `mss`/`pyautogui` — switch to X11 or use the desktop screenshot portal. |

## Usage

1. Open a LinkedIn profile in your normal browser (optionally open **Contact info**).
2. Click **Start** on the dashboard.
3. The tool scrolls, captures, extracts, and saves the lead; it then waits for
   you to open the next profile. Navigating away from a profile stops the run
   (default) so it never runs on non-target pages.

## Project layout

```
screen-leads/
  agent/          capture loop pieces: screenshot, scroll, detection
    platform/     native URL helpers (mac / windows / linux)
  ai/             Claude vision extraction + per-site recipes
    recipes/      base.py, linkedin.py, registry (__init__.py)
  core/           canonical models + capture controller (state machine)
  db/             SQLite persistence (leads + runs)
  api/            FastAPI: /api/start /pause /resume /stop /status /leads
  dashboard/      single-file web UI
  config.py  main.py
```

## Adding a new site

1. Add `ai/recipes/<site>.py` implementing `SiteRecipe` (`matches`,
   `extraction_schema`, `extraction_prompt`, `to_canonical`).
2. Register it in `ai/recipes/__init__.py`.

Nothing in the capture loop changes — the guard and pipeline are recipe-driven.

## Compliance note

Automated *scraping* of LinkedIn violates its Terms of Service. This tool is
built for low-volume, human-in-the-loop use on profiles you manually open and
are allowed to view. Keep pacing conservative and use it accordingly.