elgarde

Elgarde — open inspection data and tools

Open pieces of Elgarde, a structured pre-purchase used-car inspection: the inspection data itself, the scoring specification, the API contract, and every tool that runs on somebody else's machine.

The mobile app, the marketing site and the backend service are not here — see PUBLIC_BOUNDARY.md for what belongs in this repository and why.

What's inside

Path	What it is	Status
inspection-core/	The canon: checklist content in five languages, curated model-specific defect rules, the scoring specification, and the conformance vectors every implementation must pass	✅
openapi/	The published contract of the free /v1 API	✅
packages/	Ports of the core for Dart, Python, JS and PHP	✅
mcp/	MCP server — ask an assistant what to check on a given car	✅
plugins/wordpress/	WordPress plugin embedding the inspection checklist	planned
extension/	Browser extension surfacing known defects on used-car listings	planned

The free API

No key, no sign-up, CORS open, rate-limited per IP:

curl "https://api.elgarde.com/api/v1/checklist?fuel=diesel&make=Volkswagen&model=Golf&lang=en"
curl "https://api.elgarde.com/api/v1/defects?make=Peugeot&model=208"

Reference: https://elgarde.com/api/ · spec: https://api.elgarde.com/api/openapi.json (a snapshot is committed at openapi/elgarde-api.json).

The canon

inspection-core/ is the single source of truth. The Elgarde app, the API and every language port are thin wrappers over it, and each runs the same conformance/vectors.json in CI — so a score computed in the app and a score computed through the API are the same number.

• 25 base checklist items plus 10 across four fuel modules, authored in English, Portuguese, Russian, Ukrainian and French
• 8 ordered make/model match rules covering 25 curated known defects — the DQ200 dry clutch, the PureTech wet belt, the N47 timing chain
• spec/SCORING.md: group rollups (average, weighted, worst-case) and the critical clamp that stops one failed safety item from averaging away

A group holds child groups or items:

{
  "id": "ext.body",
  "order": 0,
  "title": { "en": "Body & paint", "pt": "Carroçaria e pintura", "…": "…" },
  "aggregation": "average",
  "items": [
    {
      "id": "ext.body.rust",
      "order": 2,
      "prompt": { "en": "No rust or corrosion", "…": "…" },
      "critical": true
    }
  ]
}

A defect rule matches when any of its clauses matches — the make contains one of makeAny, and, when present, the model contains one of modelAny. Rules are ordered, the first match wins, and at most one defect group is ever appended:

{
  "id": "ford-known-issues",
  "label": { "en": "Ford known issues", "pt": "Problemas conhecidos Ford" },
  "match": [{ "makeAny": ["ford"], "modelAny": ["focus", "fiesta", "ecosport", "puma"] }],
  "defects": [
    {
      "id": "ecoboost.coolant",
      "critical": true,
      "text": {
        "en": "1.0 EcoBoost coolant/overheating (degas hose, head) — check history",
        "pt": "1.0 EcoBoost sobreaquecimento/líquido — verificar histórico"
      }
    }
  ]
}

Item ids are permanent — they are what makes an inspection comparable over time. JSON Schemas for both files are in inspection-core/data/schema/.

Self-check, before you rely on any of it:

python3 inspection-core/tools/check.py     # schemas, structure, all 32 vectors

Known defects v3 (dossiers)

inspection-core/data/v3/ holds sourced dossiers for individual known defects, next to the v2 rule file, which is unchanged (data/defects.json, format 2). Schemas are in inspection-core/data/schema/v3/; the release manifest, with counts, changelog and source licences, is data/v3/release.json.

Release 2026.10.1: 15 published dossiers backed by 90 evidence records and 28 prevalence records. 11 of the 25 v2 defect ids did not clear the evidence threshold and are kept as deprecated records (a reason in five languages, no texts); one of them, m271.balanceshaft, was renamed, so it is listed in the aliases of m271.timingchain and its replacedBy names that dossier. Every v2 id still exists in v3, so stored defect.<id> answers keep working.

The packages (1.2.0) bundle vehicles.json and defects.json and resolve facts offline (resolveDefects, assembleV3, servedId); evidence and prevalence are not bundled and are served by the API.

File	Holds
defects.json	one dossier per defect: component, mechanism, applicability, severity, symptoms, inspection steps, repair, ids of evidence and prevalence
evidence.json	the sources behind each claim: type, tier, scope, publisher, link, licence, note
prevalence.json	how common a defect is: a measured figure, a partial one such as a recall scope, or an explicit "no reliable figure"
vehicles.json	makes, models, engines and gearboxes used to resolve what a caller knows about a car
disclaimer.json, release.json	the wording that goes with the data, and the release manifest

Applicability is decided per defect from the facts you supply (model, engine or gearbox code, production date and so on), with three outcomes:

• applies: the supplied facts satisfy the defect's conditions.
• possible: the model matches but a fact needed to decide is missing (for example the engine code); the answer lists what to ask for.
• not_applicable: the model is not covered, or a supplied fact rules it out (for example a different engine code, or a production date outside the affected range).

reviewStatus on evidence (review.status in the files) says how far a record has been checked. source_verified means an automated check against the source as opened on the stated date: claims, dates and figures were compared with it. It is not a human sign-off. approved is reserved for records a named person has reviewed.

Some evidence derives from RappelConso under the Licence Ouverte 2.0; see LICENSE-DATA. The v3 dossiers are served by GET /v1/defects/{defect_id} and GET /v1/catalog, and GET /v1/defects accepts fact-based matching (see openapi/).

Porting the core

1. Load inspection-core/data/checklist.json and inspection-core/data/defects.json.
2. Implement spec/SCORING.md.
3. Run all four sections of conformance/vectors.json in your test suite — scoring, assembly, matching, canonScoring. Compare floats with a tolerance of 1e-9.
4. For known defects v3, load data/v3/vehicles.json and data/v3/defects.json and run the resolveV3, resolveDefect, v3Names, v3ServedIds and assembleV3 sections (the notes in the file say what each one compares). They are generated from the implementation that serves /v1/defects, so a port that passes them agrees with the API.

Honest limits

Elgarde is a self-service checklist. It is not a certified, mechanical or legal inspection, not professional advice, and not a vehicle-history or title service. A defect entry describes a known weak point on a model — something worth checking — and is never a claim about any individual car. An empty defect result means nothing is curated for that model yet, not that the model is trouble-free.

Licence

• Data (inspection-core/data/, inspection-core/conformance/) — CC-BY-4.0. Commercial use is fine; keep the attribution to https://elgarde.com/.
• Code and tooling — MIT.

Corrections and additional model defects are welcome — open an issue or a pull request. Elgarde is made in Porto, Portugal by TransparentCaprice, Lda. (NIPC 517840642).