AIAG codes and K1–K5 grading

When damage mode is on, every verification gets two rollups computed automatically from the raw damage_findings list:

aiag_codes — stable, alphabetically sorted body codes used in North American finished-vehicle logistics.
k_grade — a single letter-and-digit code (K1..K5) used in European leasing returns.

Both rollups are deterministic pure functions in lib/verify-ai/damage/grading.ts. They take DamageFinding[] and a JSON table (aiag-table.json, k-grade-thresholds.json) and return the rollups synchronously — no I/O, no LLM call.

AIAG body codes

The AIAG (Automotive Industry Action Group) finished-vehicle convention encodes each damage spot as a three-part code:

plaintext

<AREA>-<TYPE>-<SEV>

| Part | Source | Example | | ------ | ------------------------------------------------------------------------- | ------------------------ | | AREA | 2- or 3-letter body-area code derived from finding.panel. | DFL (door front left). | | TYPE | 2-letter damage-type code derived from finding.damage_type. | DN (dent). | | SEV | Severity rank: 1 = light, 2 = medium, 3 = severe. | 2. |

So a medium dent on the front-left door becomes DFL-DN-2.

The table

The lookup table lives in lib/verify-ai/damage/aiag-table.json and is a flat JSON object — easy to extend without code changes. The current v1 codes:

| Panel (finding.panel) | Code | | ----------------------- | ----- | | car_hood | HD | | car_roof | RF | | car_trunk | TR | | car_front_bumper | BF | | car_rear_bumper | BR | | car_door_fl | DFL | | car_door_fr | DFR | | car_door_rl | DRL | | car_door_rr | DRR | | car_fender_fl | FFL | | car_fender_fr | FFR | | car_quarter_rl | QRL | | car_quarter_rr | QRR | | car_rocker | RK | | car_mirror | MR |

Damage types: scratch=SC, dent=DN, paint_chip=PC, crack=CR, broken=BR, missing=MS, rust=RU, tear=TR, stain=ST, glass_damage=GL, other=OT.

Unknown panels or types fall back to OT — codes are stable and lookups never miss.

Computing codes from findings

The transform is toAiagCodes(findings: DamageFinding[]): string[]:

import { toAiagCodes } from "@/lib/verify-ai/damage/grading";
 
const codes = toAiagCodes([
  { panel: "car_door_fl", damage_type: "dent",    severity: "medium", /* ... */ },
  { panel: "car_front_bumper", damage_type: "scratch", severity: "light", /* ... */ },
  { panel: "car_door_fl", damage_type: "dent",    severity: "medium", /* dup */ },
]);
// → ["BF-SC-1", "DFL-DN-2"]

Notes:

severity: "none" is excluded. No-damage findings never produce a code.
Deduplicated. Two identical findings on the same panel produce one code.
Sorted. Output is alphabetically sorted for stable diffs and spreadsheet imports.

Codes are persisted in the aiag_codes JSONB column on verify_ai_verifications, ready for export to a TMS, a yard-management system, or an audit spreadsheet.

bash

curl https://verify.switchlabs.dev/api/v1/verify \
  -H "X-API-Key: vai_your_api_key" \
  -F "image=@intake.jpg" \
  -F "policy=pol_fleet_damage" \
  -F 'metadata={"vin":"1FAFP404X1F123456"}'

json

{
  "id": "ver_8x92m4k9",
  "is_compliant": false,
  "aiag_codes": ["BF-SC-1", "DFL-DN-2", "HD-PC-1"],
  "k_grade": "K3"
}

K1–K5 grades

K-grades collapse the full findings list to a single bucket — useful for European leasing returns where the contract pegs the residual value to a discrete condition grade.

| Grade | Label | Rule (any clause matches) | | ----- | ------------------------------------------- | ---------------------------------------------------------------------- | | K1 | Showroom condition | Zero findings. | | K2 | Minor damage — cosmetic only | At least one light finding (and not enough to escalate). | | K3 | Moderate damage — repair recommended | At least one medium finding, OR five-plus light findings. | | K4 | Major damage — requires repair before delivery | At least one severe finding, OR four-plus medium findings. | | K5 | Not deliverable | Two-plus severe findings, OR four-plus findings with a severe max. |

The rule table is evaluated top-down — first match wins — in k-grade-thresholds.json:

json

{
  "grades": [
    { "grade": "K5", "rule": { "any": [
      { "n_severe_gte": 2 },
      { "severity_max_eq": "severe", "n_total_gte": 4 }
    ]}},
    { "grade": "K4", "rule": { "any": [
      { "n_severe_gte": 1 },
      { "severity_max_eq": "medium", "n_total_gte": 4 }
    ]}},
    /* K3, K2, K1 ... */
  ]
}

The transform is toKGrade(findings: DamageFinding[]): KGrade:

import { toKGrade, toOverallSeverity, gradeFindings } from "@/lib/verify-ai/damage/grading";
 
toKGrade([]);                                  // → "K1"
toKGrade([f("car_door_fl", "scratch", "light")]); // → "K2"
toKGrade([f("car_door_fl", "dent",    "medium")]); // → "K3"
toKGrade([f("car_door_fl", "crack",   "severe")]); // → "K4"
toKGrade([
  f("car_door_fl", "crack",  "severe"),
  f("car_door_fr", "broken", "severe"),
]); // → "K5"
 
// Convenience: get all three at once.
gradeFindings(findings); // { aiag_codes, k_grade, overall_severity }

toOverallSeverity() is the same family of pure helper — it returns the highest severity across all findings ("none" | "light" | "medium" | "severe").

When to use AIAG vs K-grade

Both rollups are computed on every damage-mode verification — you don't pick one ahead of time. Use the one that fits the downstream system:

| Use case | Use | | ----------------------------------------------------------------- | ----------- | | North American finished-vehicle logistics (rail, port, drayage). | aiag_codes | | Insurance claims systems / DRP integrations. | aiag_codes | | European OEM leasing returns and residual-value calculations. | k_grade | | Single-number dashboards or contract thresholds. | k_grade | | Engineering / drift analysis (per-panel histograms). | Raw damage_findings |

Two systems, same source — you don't need to keep two pipelines in sync. Bumping a threshold (e.g. demoting "five light findings" from K3 to K2) is a one-line JSON edit in k-grade-thresholds.json.

Versioning

Both lookup tables carry a version field ("1.0.0" in v1). Changing the rules should bump the version so downstream consumers can detect grade-drift across deployments. The grades themselves are stored as plain strings in verify_ai_verifications.k_grade — there's no FK constraint, so you can backfill historical rows by re-running the transform against the stored damage_findings.

What's next

Detecting and grading damage — how the raw findings get produced in the first place.
Before/after rental inspection delta — apply the same grading transforms to "new damage only".

Get in Touch