Kia Pipeline Implementation

This page contains ai_kia parsing, extraction, asset, and relationship notes. Keep public endpoint behavior, headers, request parameters, and response shapes in Public API Sources.

Raw Components

All Kia raw components start on 2026-06-08.

Component	Source/resource	Upstream	Schedule
KiaVehicleModelsRawComponent	vehicle_models/models	None	0 6 * * *
KiaInventoryBnpRawComponent	inventory_bnp/inventory	kia/us/raw/vehicle_models_models	0 7 * * *
KiaConfiguratorRawComponent	configurator/vehicles	kia/us/raw/vehicle_models_models	0 8 * * *
KiaDealerRawComponent	dealers/dealers	None	0 9 * * *
KiaOffersRawComponent	offers/offers	kia/us/raw/vehicle_models_models	0 10 * * *

The inventory raw response is retained as the full API envelope so vehicles and response metadata remain available to downstream components. Dealer raw requests use the dealer locator request directly and do not depend on inventory.

Extractor Registry

Source/resource	Entity	Extractor	Key fields
vehicle_models/models	models	extract_models	model_code
configurator/vehicles	features	extract_accessories	feature_type, option_code, model_code
inventory_bnp/inventory	inventory	extract_inventory	vin
dealers/dealers	dealers	extract_dealers	dealer_code

Inventory Extraction

extract_inventory reads the vehicles array from the raw inventory API envelope. It skips records without a VIN and maps the inventory modelCode field to canonical model_code so inventory rows can resolve to model and feature rows at trim granularity.

The extractor emits feature_refs as list-of-struct values:

[
  {"feature_type": "exterior", "option_code": "RSL"},
  {"feature_type": "interior", "option_code": "sorento_2026_still_lx_black_cloth-v2"}
]

Inventory source field	Feature ref	Notes
exteriorColor.code	{feature_type: "exterior", option_code: <code>}	Direct deterministic code field. Some live values differ from configurator codes for the same color name, e.g. RSL vs ISG for Ivory Silver and PML vs P2M for Panthera Metal.
interiorColor.images.interiorProfile	{feature_type: "interior", option_code: <image filename stem>}	Uses interior_profile_to_code, the same helper used by configurator interior extraction.
packs[].code	{feature_type: "package", option_code: <code>}	Packages are sourced only from structured packs; optionPackageCode is intentionally ignored.

Not mapped:

• inventory.options[] values are human-readable names, not configurator option codes. Mapping them would require a separate title-to-code lookup.
• optionPackageCode is ignored because it is redundant with packs when structured package data exists.
• interiorColor.code values such as WK and GYT are not used as feature refs because configurator interior rows do not expose those codes.
• Package refs may remain unresolved when configurator payloads do not expose matching discriminator="package" feature rows.

Configurator Feature Extraction

extract_accessories walks the bnpVehicle tree and emits feature rows for:

• options[] entries with feature_type="option" and option_code from options[].code.
• colors[].exterior entries with feature_type="exterior" and option_code from colors[].exterior.code.
• colors[].interior entries with feature_type="interior" and option_code derived from the interiorProfile image filename stem.
• packages[] entries if Kia populates them.

interior_profile_to_code(str) -> str lives in ai_kia.sources.common and preserves the original configurator behavior:

interior_profile.split("/")[-1].split(".")[0]

Configurator feature rows are keyed by (feature_type, option_code, model_code). MSC applicability is retained in transformed features by collecting msc_code and msc_description into msc_codes and msc_descriptions.

Consolidated Relationships

inventory -- dealer_code --------------------------------------> dealers
inventory -- model_code ---------------------------------------> models
inventory -- model_code + feature_refs.feature_type
             + feature_refs.option_code -----------------------> features
features  -- model_code ---------------------------------------> models

feature_type is part of the feature key because Kia option codes are not guaranteed unique across configurator discriminators.

Asset Keys

Asset	Key
Vehicle models source	kia/us/sources/vehicle_models_models
Vehicle models raw	kia/us/raw/vehicle_models_models
Inventory source	kia/us/sources/inventory_bnp_inventory
Inventory raw	kia/us/raw/inventory_bnp_inventory
Dealer source	kia/us/sources/dealers_dealers
Dealer raw	kia/us/raw/dealers_dealers
Configurator source	kia/us/sources/configurator_vehicles
Configurator raw	kia/us/raw/configurator_vehicles
Transformed models	kia/us/transformed/vehicle_models_models
Transformed inventory	kia/us/transformed/inventory_bnp_inventory
Transformed dealers	kia/us/transformed/dealers_dealers
Transformed features	kia/us/transformed/configurator_features
Consolidated dealers	kia/us/consolidated/dealers
Consolidated models	kia/us/consolidated/models
Consolidated features	kia/us/consolidated/features
Consolidated inventory	kia/us/consolidated/inventory