# Identity Resolution Normalizer CLI (Click + Pandas)

## PURPOSE
A command-line tool that takes a raw customer table (e.g. the third-party ticket
reseller CSV from the demo) and produces both a raw view and a normalized view, exactly
like the side-by-side preview Genie generates in the Fan 360 walkthrough. It tags email,
phone, name and billing-address columns, standardizes phone numbers, and writes a
cleaned CSV ready for identity resolution.

## WHY THIS MATTERS
The video's onboarding step is not the matching algorithm itself — it is the automated
tagging and cleanup that happens first. Every downstream match depends on records being
canonical. This CLI teaches that preprocessing is a first-class, testable, scriptable
stage you run in a pipeline, not something buried in a notebook cell.

## HOW TO BUILD
1. `pip install click pandas phonenumbers`
2. Use `click.group()` to create `tag`, `normalize`, and `preview` subcommands.
3. `tag` prints detected semantic tags per column as a small table.
4. `normalize` applies phone/email/name rules and writes `*.normalized.csv`.
5. `preview` prints the raw and normalized frames side by side to stdout.

Key snippet:
```python
@cli.command()
@click.argument("path", type=click.Path(exists=True))
@click.option("--out", default="normalized.csv")
def normalize(path, out):
    df = pd.read_csv(path)
    tags = detect_tags(df)
    for col, tag in tags.items():
        if tag == "phone":
            df[col] = df[col].map(normalize_phone)
    df.to_csv(out, index=False)
```

## WHEN TO USE IN PRODUCTION
Ideal for batch onboarding of new reseller or partner feeds, for backfilling historical
tables before a matching run, and for data-audit jobs where you must show raw vs cleaned
output. Prefer a streaming/service design when sources arrive continuously; this CLI is
best for scheduled batch runs.

## HOW IT HELPS STUDENTS
Students learn Click command design, vectorized Pandas transformations, and the habit of
emitting both raw and normalized artifacts for auditability — a pattern every data
engineer needs when integrating messy third-party data.

## STARTER CODE
`starter/main.py` is a runnable Click app with `detect_tags`, `normalize_phone`, and the
`tag`/`normalize`/`preview` commands. The tag detector includes a `# TODO` to swap in an
LLM-based semantic tagger.
