Auto Auction Mall — TOP-1 Direct-Buyer
Auction Platform Earns +50K MAU

# WebCoreLab — Auto Auction Mall faceted-navigation classifier
# Decides which filter combinations get indexed vs canonical'd vs noindex'd
from dataclasses import dataclass
from typing import Literal

@dataclass
class FacetCombo:
    facets: dict           # {"make": "ford", "state": "tx", "salvage": True, ...}
    monthly_volume: int    # search volume for this exact combo
    competition: float     # 0..1
    inventory_count: int   # vehicles currently matching the combo

Action = Literal["indexable_static", "canonical_to_pillar", "noindex_follow"]

INDEXABLE_FACET_DEPTH = 3   # max active filters that earn an indexable URL
PILLAR_VOLUME_FLOOR   = 50  # below this — canonical to pillar
INVENTORY_FLOOR       = 20  # below this — noindex (thin page)

def classify(c: FacetCombo, pillar_canonical: str) -> tuple[Action, str]:
    active_facets = sum(1 for v in c.facets.values() if v)

    # Too many filters: never indexable, always canonical to nearest pillar
    if active_facets > INDEXABLE_FACET_DEPTH:
        return "canonical_to_pillar", pillar_canonical

    # Thin inventory: noindex,follow — keep crawl path, drop from index
    if c.inventory_count < INVENTORY_FLOOR:
        return "noindex_follow", ""

    # Real demand + healthy inventory: promote to indexable static landing
    if c.monthly_volume >= PILLAR_VOLUME_FLOOR and c.inventory_count >= INVENTORY_FLOOR:
        return "indexable_static", build_static_url(c.facets)

    # Default: canonical to pillar
    return "canonical_to_pillar", pillar_canonical

def build_static_url(facets: dict) -> str:
    # Stable, slug-friendly URL contract agreed with engineering
    parts = [facets[k] for k in ("make","model","state","auction_type") if facets.get(k)]
    return "/cars/" + "/".join(parts) + "/"

# Applied to 47,200 facet combinations
# Indexable static landings produced: 1,840
# Canonical'd to pillars: 38,260
# Noindex'd thin pages:     7,100
# Crawl budget reclaimed:   ~62% → ~5%

# WebCoreLab — Semantic core clustering for AAM
# 8,400 commercial keywords → 6 hubs + 47 sub-clusters (tf-idf + manual validation)
import numpy as np
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.cluster import AgglomerativeClustering

def cluster_keywords(keywords: list[str], n_hubs: int = 6) -> dict:
    """Cluster commercial keywords into pillar hubs."""
    # tf-idf on character n-grams catches synonyms ("salvage cars" ~ "salvage autos")
    vec = TfidfVectorizer(analyzer="char_wb", ngram_range=(3,5), min_df=2)
    X = vec.fit_transform(keywords)

    # Hierarchical clustering — cosine distance, average linkage
    model = AgglomerativeClustering(
        n_clusters=n_hubs,
        metric="cosine",
        linkage="average",
    )
    labels = model.fit_predict(X.toarray())

    hubs = {i: [] for i in range(n_hubs)}
    for kw, lbl in zip(keywords, labels):
        hubs[lbl].append(kw)
    return hubs

# After tf-idf clustering, hub centroids are reviewed manually
# against US auto-auction buyer intent (transactional vs informational)
# and re-labelled to canonical pillar names:
PILLAR_LABELS = [
    "cars-by-make",
    "cars-by-model",
    "cars-by-state",
    "auction-type",
    "salvage-title",
    "buying-guide",
]

# Output: hub_map.json — every keyword → pillar URL
# Result: 8,400 keywords routed to 6 pillars + 47 sub-cluster pages