# Fan 360 Source Onboarding API (FastAPI)

## PURPOSE
This project rebuilds the first half of the Databricks "Fan 360" demo as a standalone
FastAPI service: register a new data source (like the third-party ticket reseller table
seen in the video), auto-detect its semantic tags (email, phone, full name), apply
normalization rules, and expose a raw-vs-normalized preview before the source is marked
"ready" for identity resolution.

## WHY THIS MATTERS
The transcript shows a Customer 360 / Fan 360 profile agent onboarding a new Unity table
and letting Genie automatically produce semantic tags and cleanup rules. The core lesson
is that identity resolution only works when incoming records are first tagged and
normalized (the video's example: every phone number standardized to one format). This
service encodes that "prepare the data set" stage as HTTP endpoints so it can run in any
pipeline.

## HOW TO BUILD
1. `pip install fastapi uvicorn pydantic phonenumbers`
2. Define Pydantic models for a `Source`, its detected `SemanticTag`s, and a
   `NormalizedRow`.
3. Implement `detect_tags()` by regex/heuristics on column names and sample values.
4. Implement `normalize_row()` (phone via `phonenumbers`, names lowercased/trimmed).
5. Expose `POST /sources/{source_id}/preview` returning both raw and normalized rows.
6. Add `POST /sources/{source_id}/ready` to flip status, mirroring "mark as ready".

Key snippet:
```python
@app.post("/sources/{source_id}/preview")
def preview(source_id: str, rows: list[dict]):
    tags = detect_tags(rows)
    return {"tags": tags,
            "raw": rows,
            "normalized": [normalize_row(r, tags) for r in rows]}
```

## WHEN TO USE IN PRODUCTION
Use it whenever multiple upstream systems feed one customer profile: CRM, ticketing,
loyalty, reseller feeds. Great as the ingestion microservice that guarantees every
record is tagged and canonicalized before it reaches the matcher. Do **not** use it as
the identity-resolution engine itself, and avoid it for one-off analysis where a
notebook is faster.

## HOW IT HELPS STUDENTS
Students practice real API design, schema validation, data normalization with a
third-party library, and the architectural habit of splitting "prepare" from "resolve".
They learn why raw previews matter for building trust in automated cleanup.

## STARTER CODE
See `starter/main.py` for a runnable FastAPI skeleton with `detect_tags`,
`normalize_row`, and the preview/ready endpoints. A deterministic stub stands in for
any LLM-based tag suggestion.
