# Muse Lead Intake API

## PURPOSE
MetaMuse can mine Facebook groups, Marketplace and Instagram and return a raw list of service providers — e.g. night nurses in Montreal at "$30 Canadian an hour". That list is messy: duplicate names, missing prices, no trust signal. This project builds a FastAPI service that ingests scraped provider records from a Muse run, deduplicates them, scores each lead's quality, and stores a clean, queryable repository — the "owned asset" the video calls Level 2 of the framework.

## WHY THIS MATTERS
Greg Isenberg's core claim is that the arbitrage is not the scraping; it is owning a cleaned, priced, trusted list you can reuse and eventually sell. MetaMuse does the "mining", and this API does the "cleaning" that turns dirty public posts into a compounding data asset. The video frames this as "there's no value in that... you own the asset".

## HOW TO BUILD
1. Define Pydantic models `RawLead` and `CleanLead`.
2. On `POST /ingest`, normalize names, floor prices and dedupe on `(name, city)`.
3. Compute a trust score from source, price presence and bio richness.
4. Persist to an in-memory dict (swap for SQLAlchemy later).
5. Expose `GET /leads` with city/trust filters and `GET /stats`.

```python
@app.post("/ingest")
def ingest(leads: list[RawLead]) -> dict:
    kept, dropped = [], 0
    for raw in leads:
        clean = to_clean(raw)          # TODO: fuzzy name match
        if clean.key in STORE:
            dropped += 1
            continue
        STORE[clean.key] = clean
        kept.append(clean.key)
    return {"kept": len(kept), "duplicates": dropped}
```

## WHEN TO USE IN PRODUCTION
Use it as the write layer behind any Muse-driven agency: night nurses in Tampa, plumbers in Phoenix, furniture in Austin. It fits when you mine repeatedly across niches and cities and need one canonical list. Do NOT use it for a single manual scrape, and never for sources whose terms of service forbid automated collection — the video explicitly warns to check Facebook's ToS before buying or crawling groups.

## HOW IT HELPS STUDENTS
Students practice typed API design, idempotent ingestion and domain scoring — the plumbing behind the "owned data asset" business model, and a clean bridge from a scraped Muse output to a real service.

## STARTER CODE
See `starter/main.py`: a runnable FastAPI app with an in-memory store, a deterministic `score_trust` stub, and a mock `run_muse_mine` standing in for the agent call (marked `# TODO` to swap in the real Muse endpoint).
