Entity resolution#

kg_resolve (one record, MCP or wdkg resolve) and wdkg resolve-batch (a corpus) take an identity envelope: whatever you already know about the entity. Only name is required.

{"name": "Fox Theatre", "kind": "place", "city": "Atlanta", "country": "US",
 "official_url": "https://www.foxtheatre.org"}

Supported fields: name, kind (person, organization, place, event, event_series, work, other), city, country, latitude + longitude, address, official_url, aliases, venue, event_date, organizer, role, occupation, affiliation, creator, year, existing_wikidata_qid, existing_google_kg_id and lang. The CLI and JSONL also accept source_id, and two fields that assert human review, existing_id_trusted and official_url_reviewed, which the MCP tool deliberately does not accept: a model calling a tool cannot vouch for a human review. Missing fields stay missing; nothing is inferred.

Decisions#

reasons explains the decision in a closed vocabulary (NO_LOCAL_ANCHOR, MULTIPLE_ANCHORED_CANDIDATES, AUTO_KIND_RULE_PASSED, ...). candidate_ids lists the viable identities; it is not a selection. There are no confidence percentages.

Local anchors#

A local anchor is a fact you supplied that the candidate's Wikidata statements confirm:

The kind rules for AUTO_MATCH, in short:

• place: official host, coordinates or address. Geography alone never resolves a generic name such as "Sala Gran".
• organization: official host only, because organizations share buildings and addresses.
• person: only a reviewed official site. Name, role, occupation and provider agreement never auto-match a person.
• event (a dated occurrence): date plus venue, organizer or coordinates. A festival series item is an EVENT_GRAIN_CONFLICT.
• event_series: official host, or city plus organizer or venue. A dated edition is an EVENT_GRAIN_CONFLICT.
• work: creator (and year when you give one).
• other or no kind: never automatic.

An existing QID is never silently replaced: a different deterministic match is CONFLICT.

Worked example: the same name, three answers#

These are real outputs of v0.2.1 against live Wikidata, without Google (full transcript).

Name and city only. Wikidata has many items labelled "Fox Theatre"; for this input two of them remain viable.

wdkg resolve "Fox Theatre" --kind place --city Atlanta

{"decision": "HOLD", "reasons": ["NO_LOCAL_ANCHOR"],
 "candidate_ids": ["Q1440190", "Q3080199"], "local_anchor_evidence": ["CITY_MATCH"]}

A city is not a local anchor for a place, so the resolver refuses to choose.

Add the official website.

wdkg resolve "Fox Theatre" --kind place --city Atlanta --url https://www.foxtheatre.org --explain

{"decision": "AUTO_MATCH", "wikidata_qid": "Q1440190",
 "local_anchor_evidence": ["CITY_MATCH", "OFFICIAL_HOST_EXACT"]}

--explain shows why the others lost: the Detroit theatre (Q3080199) has CITY_CONFLICT and OFFICIAL_HOST_CONFLICT, and a third item with the same label (Q1440189) has a KIND_CONFLICT.

Coordinates that fit two things. With v0.1.0 against live Wikidata, Tate Modern plus its coordinates returned AMBIGUOUS (MULTIPLE_ANCHORED_CANDIDATES) with both the gallery (Q193375) and Bankside Power Station (Q806832), the building that houses it. Both are legitimately "at" those coordinates. An official URL settles it; a guess would not.

Provider concordance is not identity#

With a Google Knowledge Graph key, the resolver can also look at Google. Google ids join to Wikidata by exact string equality: kg:/m/... to P646 (Freebase id) and kg:/g/... to P2671. Those joins produce provider concordance codes:

Concordance says that Google and Wikidata describe the same thing. It says nothing about whether that thing is your Fox Theatre. In a v0.1.0 run with Google enabled, the name-and-city query above found exact Google–Wikidata agreement (EXTERNAL_ID_EXACT and WIKIPEDIA_EXACT) on four different Fox Theatres, and the decision stayed HOLD. If agreement between two providers were treated as evidence, any of the four could have been "confirmed".

So the two kinds of evidence are kept in separate fields, provider_concordance and local_anchor_evidence, and only local anchors can produce AUTO_MATCH. Google's resultScore is passed through as result_score_raw for display and never used in a decision.

Every candidate pair, selected or not, is recorded in candidate_pairs with its join methods, so you can audit both kinds of agreement later (Batch and evidence).

Events and series#

"Primavera Sound" is both a recurring festival (the series) and a set of dated editions. The resolver never links one to the other:

wdkg resolve "Primavera Sound" --kind event --date 2019-05-30 --city Barcelona
# v0.1.0, live: NO_CANDIDATE, with EVENT_GRAIN_CONFLICT on Q2439480 (the festival series)

wdkg resolve "Primavera Sound" --kind event_series --city Barcelona --url https://www.primaverasound.com
# v0.1.0, live: AUTO_MATCH Q2439480, local anchors CITY_MATCH + OFFICIAL_HOST_EXACT

What the resolver never does#

• invent or recall a QID, Google id, website or coordinate;
• turn search rank or Google's score into a probability of identity;
• merge an organization with its building, or an occurrence with its series;
• write anything to Wikidata, Google or your data.

The complete rules, including geo thresholds, official-host normalization and the retention basis for Google fields, are in resolution.md.