Skip to main content

Kia Pipeline Implementation

The raw and transformed tiers live in the ai_public code location (the raw sources of ai_public_api.kia, ai_public.sources.kia.registry); ai_kia holds the consolidated tier and reads the transformed tables through the public Iceberg IO manager. This page contains parsing, extraction, asset, and relationship notes. Keep public endpoint behavior, headers, request parameters, and response structures in Public API Sources.

Raw Components​

ComponentSource/resourceUpstream
PublicApiRawComponent (ai_public_api.kia.models:VEHICLE_MODELS)vehicle_models/modelsNone
PublicApiRawComponent (ai_public_api.kia.inventory:INVENTORY)inventory_bnp/inventorykia/us/raw/vehicle_models_models
PublicApiRawComponent (ai_public_api.kia.configurator:CONFIGURATOR)configurator/vehicleskia/us/raw/vehicle_models_models
PublicApiRawComponent (ai_public_api.kia.dealers:DEALERS)dealers/dealersNone
PublicApiRawComponent (ai_public_api.kia.offers:OFFERS)offers/offerskia/us/raw/vehicle_models_models

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/resourceEntityExtractorKey fields
vehicle_models/modelsmodelsextract_modelsmodel_code, model_year
configurator/vehiclesfeaturesextract_accessoriesfeature_type, option_code, model_code, model_year
configurator/vehiclesmodelsextract_modelsmodel_code, model_year
inventory_bnp/inventoryinventoryextract_inventoryvin
dealers/dealersdealersextract_dealersdealer_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 fieldFeature refNotes
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_public_api.kia.common:

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

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

Model Sources​

The consolidated models asset merges two source groups on (model_code, model_year):

PrioritySourceRows
1vehicle_models_models (allSeries catalog)One per trim name, keyed by the trim's baseModel code
2configurator_models (bnpVehicle tree)One per trim node of the tree, so one per engine, drivetrain and transmission variant

In the configurator, a trim sold in more than one drivetrain has one modelCode per drivetrain. The allSeries catalog lists only the trim's baseModel, which is usually the FWD code. For example, Seltos 2027 LX is KAC2225 (FWD) in both sources and KAC2425 (AWD) only in the configurator. Configurator features reference both codes, so the configurator source group supplies the model rows the catalog omits. Only the configurator source group has drivetrain, engine and transmission columns.

The configurator raw asset fans out over the (seriesId, year) pairs in the allSeries catalog, so it covers only the series and years that catalog lists.

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​

AssetKey
Vehicle models sourcekia/us/sources/vehicle_models_models
Vehicle models rawkia/us/raw/vehicle_models_models
Inventory sourcekia/us/sources/inventory_bnp_inventory
Inventory rawkia/us/raw/inventory_bnp_inventory
Dealer sourcekia/us/sources/dealers_dealers
Dealer rawkia/us/raw/dealers_dealers
Configurator sourcekia/us/sources/configurator_vehicles
Configurator rawkia/us/raw/configurator_vehicles
Transformed modelskia/us/transformed/vehicle_models_models
Transformed inventorykia/us/transformed/inventory_bnp_inventory
Transformed dealerskia/us/transformed/dealers_dealers
Transformed featureskia/us/transformed/configurator_features
Transformed configurator modelskia/us/transformed/configurator_models
Consolidated dealerskia/us/consolidated/dealers
Consolidated modelskia/us/consolidated/models
Consolidated featureskia/us/consolidated/features
Consolidated inventorykia/us/consolidated/inventory