# atharvak-2209/amazon-ml-challenge-26 architecture

> Architecture diagram of the GitHub repository atharvak-2209/amazon-ml-challenge-26, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/atharvak-2209/amazon-ml-challenge-26
- Repository: https://github.com/atharvak-2209/amazon-ml-challenge-26

## Overview

This repository implements business-entity resolution: it normalizes business records, retrieves candidate pairs, engineers pairwise evidence, scores likely matches, and produces entity-level submission results including non-matches. The main runtime route is explicit in `src/pipeline.py`; the README also describes training, evaluation, and phased experimentation. Several phase modules are unsampled, so their internal connections are omitted rather than inferred.

Main entry points: [`src/pipeline.py`](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/pipeline.py) (End-to-end pipeline), [`src/phase8/pipeline.py`](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/phase8/pipeline.py) (Final submission pipeline), [`src/features/pair_features.py`](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/features/pair_features.py) (Pair feature assembly), [`src/preprocessing/normalize.py`](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/preprocessing/normalize.py) (Normalization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Record preparation"]
  node_normalize["Normalization<br/>[normalize.py]"]
  node_address["Address parsing<br/>[address_parser.py]"]
end

subgraph group_matching["Candidate matching"]
  node_tfidf["TF-IDF blocking<br/>[tfidf_blocking.py]"]
  node_exact["Exact blocking<br/>[exact_blocking.py]"]
  node_neighborhood["Neighborhood blocking<br/>[token_blocking.py]"]
  node_faiss["Dense ANN blocking<br/>[faiss_blocking.py]"]
  node_pairfeatures["Pair feature assembly<br/>[pair_features.py]"]
  node_namefeatures["Name features<br/>[name_features.py]"]
  node_addressfeatures["Address features"]
end

subgraph group_decision["Scoring and decisions"]
  node_training["Model training<br/>[train_xgb.py]"]
  node_prediction["Pair prediction<br/>[predict.py]"]
  node_engine["Decision engine<br/>[decision_engine.py]"]
  node_submission["Submission assembly"]
  node_singletons["Singleton filling<br/>[singleton.py]"]
  node_evaluation["F0.5 evaluation<br/>[evaluate_f05.py]"]
end

subgraph group_workflow["Pipelines and experiments"]
  node_orchestrator["End-to-end pipeline<br/>[pipeline.py]"]
  node_phase3["Blocking experiments<br/>[pipeline.py]"]
  node_phase4["Feature pipeline<br/>[phase4_pipeline.py]"]
  node_phase6["Decision pipeline<br/>[pipeline.py]"]
  node_phase7["Experiment runners<br/>[combined_runner.py]"]
  node_phase8["Final submission pipeline<br/>[pipeline.py]"]
end

node_user(("Pipeline user"))
node_records["Entity records"]
node_results["Matching and candidate files"]

node_user -->|"runs"| node_orchestrator
node_records -->|"loads"| node_orchestrator
node_orchestrator -->|"normalizes"| node_normalize
node_orchestrator -->|"generates candidates"| node_tfidf
node_orchestrator -->|"generates candidates"| node_exact
node_orchestrator -->|"generates candidates"| node_neighborhood
node_orchestrator -->|"builds features"| node_pairfeatures
node_pairfeatures -->|"extracts name signals"| node_namefeatures
node_pairfeatures -->|"extracts address signals"| node_addressfeatures
node_orchestrator -->|"scores pairs"| node_prediction
node_orchestrator -->|"fills unmatched entities"| node_singletons
node_orchestrator -->|"writes outputs"| node_results
node_training -.->|"produces model"| node_prediction
node_phase3 -->|"uses normalization"| node_normalize
node_phase3 -->|"uses features"| node_pairfeatures
node_phase4 -->|"uses normalization"| node_normalize
node_phase4 -->|"builds features"| node_pairfeatures
node_phase6 -->|"applies decisions"| node_engine
node_phase6 -.->|"evaluates results"| node_evaluation
node_engine -->|"evaluates decisions"| node_evaluation
node_submission -->|"fills singletons"| node_singletons
node_phase7 -.->|"experiments with models"| node_training
node_phase8 -->|"normalizes records"| node_normalize
node_phase8 -->|"generates candidates"| node_tfidf
node_phase8 -->|"generates candidates"| node_exact
node_phase8 -->|"generates candidates"| node_neighborhood
node_phase8 -->|"builds features"| node_pairfeatures
node_phase8 -->|"scores pairs"| node_prediction
node_phase8 -->|"applies decisions"| node_engine
node_phase8 -.->|"writes submission files"| node_results
node_orchestrator -.->|"parses addresses"| node_address
node_faiss -.->|"retrieves candidates"| node_records

click node_normalize "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/preprocessing/normalize.py"
click node_address "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/preprocessing/address_parser.py"
click node_tfidf "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/blocking/tfidf_blocking.py"
click node_exact "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/blocking/exact_blocking.py"
click node_neighborhood "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/blocking/token_blocking.py"
click node_faiss "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/blocking/faiss_blocking.py"
click node_pairfeatures "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/features/pair_features.py"
click node_namefeatures "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/features/name_features.py"
click node_addressfeatures "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/features/address_features.py"
click node_training "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/models/train_xgb.py"
click node_prediction "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/models/predict.py"
click node_engine "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/decision/decision_engine.py"
click node_submission "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/decision/submission_pipeline.py"
click node_singletons "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/decision/singleton.py"
click node_evaluation "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/evaluation/evaluate_f05.py"
click node_orchestrator "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/pipeline.py"
click node_phase3 "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/phase3/pipeline.py"
click node_phase4 "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/features/phase4_pipeline.py"
click node_phase6 "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/phase6/pipeline.py"
click node_phase7 "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/phase7/combined_runner.py"
click node_phase8 "https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/phase8/pipeline.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_normalize,node_address,node_user toneBlue
class node_tfidf,node_exact,node_neighborhood,node_faiss,node_pairfeatures,node_namefeatures,node_addressfeatures toneAmber
class node_training,node_prediction,node_engine,node_submission,node_singletons,node_evaluation toneMint
class node_orchestrator,node_phase3,node_phase4,node_phase6,node_phase7,node_phase8 toneRose
class node_records,node_results toneIndigo
```

## Components

### Record preparation

- [Normalization](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/preprocessing/normalize.py): `src/preprocessing/normalize.py`
- [Address parsing](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/preprocessing/address_parser.py): `src/preprocessing/address_parser.py`

### Candidate matching

- [TF-IDF blocking](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/blocking/tfidf_blocking.py): `src/blocking/tfidf_blocking.py`
- [Exact blocking](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/blocking/exact_blocking.py): `src/blocking/exact_blocking.py`
- [Neighborhood blocking](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/blocking/token_blocking.py): `src/blocking/token_blocking.py`
- [Dense ANN blocking](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/blocking/faiss_blocking.py): `src/blocking/faiss_blocking.py`
- [Pair feature assembly](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/features/pair_features.py): `src/features/pair_features.py`
- [Name features](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/features/name_features.py): `src/features/name_features.py`
- [Address features](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/features/address_features.py): `src/features/address_features.py`

### Scoring and decisions

- [Model training](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/models/train_xgb.py): `src/models/train_xgb.py`
- [Pair prediction](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/models/predict.py): `src/models/predict.py`
- [Decision engine](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/decision/decision_engine.py): `src/decision/decision_engine.py`
- [Submission assembly](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/decision/submission_pipeline.py): `src/decision/submission_pipeline.py`
- [Singleton filling](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/decision/singleton.py): `src/decision/singleton.py`
- [F0.5 evaluation](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/evaluation/evaluate_f05.py): `src/evaluation/evaluate_f05.py`

### Pipelines and experiments

- [End-to-end pipeline](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/pipeline.py): `src/pipeline.py`
- [Blocking experiments](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/phase3/pipeline.py): `src/phase3/pipeline.py`
- [Feature pipeline](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/features/phase4_pipeline.py): `src/features/phase4_pipeline.py`
- [Decision pipeline](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/phase6/pipeline.py): `src/phase6/pipeline.py`
- [Experiment runners](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/phase7/combined_runner.py): `src/phase7/combined_runner.py`
- [Final submission pipeline](https://github.com/atharvak-2209/amazon-ml-challenge-26/blob/main/src/phase8/pipeline.py): `src/phase8/pipeline.py`

### Other components

- **Pipeline user**
- **Entity records**
- **Matching and candidate files**

## Connections

- Pipeline user → End-to-end pipeline: runs (evidence: `src/pipeline.py`)
- Entity records → End-to-end pipeline: loads (evidence: `src/pipeline.py`)
- End-to-end pipeline → Normalization: normalizes (evidence: `src/pipeline.py`)
- End-to-end pipeline → TF-IDF blocking: generates candidates (evidence: `src/pipeline.py`)
- End-to-end pipeline → Exact blocking: generates candidates (evidence: `src/pipeline.py`)
- End-to-end pipeline → Neighborhood blocking: generates candidates (evidence: `src/pipeline.py`)
- End-to-end pipeline → Pair feature assembly: builds features (evidence: `src/pipeline.py`)
- Pair feature assembly → Name features: extracts name signals (evidence: `src/features/pair_features.py`)
- Pair feature assembly → Address features: extracts address signals (evidence: `src/features/pair_features.py`)
- End-to-end pipeline → Pair prediction: scores pairs (evidence: `src/pipeline.py`)
- End-to-end pipeline → Singleton filling: fills unmatched entities (evidence: `src/pipeline.py`)
- End-to-end pipeline → Matching and candidate files: writes outputs (evidence: `src/pipeline.py`)
- Model training → Pair prediction: produces model (evidence: `README.md`)
- Blocking experiments → Normalization: uses normalization (evidence: `src/phase3/pipeline.py`)
- Blocking experiments → Pair feature assembly: uses features (evidence: `src/phase3/pipeline.py`)
- Feature pipeline → Normalization: uses normalization (evidence: `src/features/phase4_pipeline.py`)
- Feature pipeline → Pair feature assembly: builds features (evidence: `src/features/phase4_pipeline.py`)
- Decision pipeline → Decision engine: applies decisions (evidence: `src/phase6/pipeline.py`)
- Decision pipeline → F0.5 evaluation: evaluates results
- Decision engine → F0.5 evaluation: evaluates decisions (evidence: `src/decision/decision_engine.py`)
- Submission assembly → Singleton filling: fills singletons (evidence: `src/decision/submission_pipeline.py`)
- Experiment runners → Model training: experiments with models
- Final submission pipeline → Normalization: normalizes records (evidence: `src/phase8/pipeline.py`)
- Final submission pipeline → TF-IDF blocking: generates candidates (evidence: `src/phase8/pipeline.py`)
- Final submission pipeline → Exact blocking: generates candidates (evidence: `src/phase8/pipeline.py`)
- Final submission pipeline → Neighborhood blocking: generates candidates (evidence: `src/phase8/pipeline.py`)
- Final submission pipeline → Pair feature assembly: builds features (evidence: `src/phase8/pipeline.py`)
- Final submission pipeline → Pair prediction: scores pairs (evidence: `src/phase8/pipeline.py`)
- Final submission pipeline → Decision engine: applies decisions (evidence: `src/phase8/pipeline.py`)
- Final submission pipeline → Matching and candidate files: writes submission files
- End-to-end pipeline → Address parsing: parses addresses (evidence: `src/pipeline.py`)
- Dense ANN blocking → Entity records: retrieves candidates
