Identity audit and discovery#

identity candidate != approved public sameAs. This package returns evidence for a consuming application's review policy. It never publishes structured data or approves public identity links. Provider concordance is not local identity proof: Google and Wikidata can agree about an external entity while that entity is the wrong local person, organization or place.

The older kg_search, kg_entity, kg_related, kg_resolve, kg_status and CLI workflows remain available with their original decision vocabulary. The identity operations add the conservative contract on this page. Ordinary runs need zero Google credentials and no model API.

Audit an existing QID#

An audit fetches the supplied QID first and checks its own facts. It never silently replaces that QID with a preferred search result. Missing statements do not prove a wrong identity.

wdkg audit-identity "Fox Theatre" --kind place --qid Q1440190 \
  --city Atlanta --country US --lat 33.7725 --lon -84.3857 \
  --url https://www.foxtheatre.org/ --wikidata-only

MCP:

{"envelope":{"local_id":"venue-001","canonical_name":"Fox Theatre","kind":"place",
 "existing_qid":"Q1440190","city":"Atlanta","country":"US",
 "official_url":"https://www.foxtheatre.org/","latitude":33.7725,"longitude":-84.3857}}

Pass this object to kg_audit_identity. The public fixture passes a deterministic rule and returns DETERMINISTIC_CONFIRM. Live data may change; the fixture is not an independent gold label. Without reviewed provenance this operation never returns VERIFIED_EXISTING.

To demonstrate a known kind contradiction using the same public fixture:

wdkg audit-identity "Fox Theatre" --kind person --qid Q1440190 --wikidata-only

The item is a theatre, so the fixture returns WRONG_IDENTITY with KIND_CONFLICT and KNOWN_ID_CONTRADICTED. The QID remains the audited QID. Another plausible candidate alone would not justify this verdict.

Find missing identities#

wdkg discover-identity "Fox Theatre" --kind place --city Atlanta \
  --url https://www.foxtheatre.org/ --lat 33.7725 --lon -84.3857 --max-candidates 3 --no-google
wdkg discover-identity "Fox Theatre" --kind place --max-candidates 5
wdkg discover-identity "Ada Lovelace" --kind person --wikidata-only

The second call lacks a local anchor and exposes namesake uncertainty. The last call supplies only a person's name, which cannot confirm a person. A single viable person yields INSUFFICIENT_EVIDENCE; multiple viable people yield AMBIGUOUS. Discovery returns at most 3 candidates by default, hard maximum 5, including bounded evidence for rejected alternatives. No score is interpreted as an identity probability.

Input and evidence#

The generic input supports local_id, canonical_name, aliases, existing_qid, kind, city, country, official_url, latitude, longitude, address, contextual_relations, roles, occupation, affiliation, venue, organizer, creator, year, event_date and lang. Legacy name, source_id, existing_wikidata_qid and role spellings are supported. Only known facts should be supplied. Names are required; an audit also requires an existing QID.

contextual_relations maps named relation fields (affiliation, venue, organizer, creator, part_of, operator) to known labels. Relations are supporting evidence, not instructions to expand a graph.

Outputs separate local matches, Wikidata identity facts, provider concordance and contradictions. They include source URLs, retrieval time, policy version, input fingerprint, candidate facts and explicit review-only sameAs candidates. Provider observations answer what a source returned; policy decisions answer what that observation supports about the local input.

VERIFIED_EXISTING requires explicit existing_id_trusted: true and reviewed provenance:

{"canonical_name":"Fox Theatre","kind":"place","existing_qid":"Q1440190",
 "existing_id_trusted":true,
 "existing_id_provenance":{"reviewed":true,"source":"caller_reviewed_registry"}}

In the CLI --trusted-id explicitly supplies the caller's review assertion. Only use it for an actual prior review. MCP rejects review assertions so an agent cannot self-certify human review. Contradictions still override trusted provenance. --reviewed-url asserts prior URL review; it is distinct from existing-QID provenance.

Closed verdicts#

Provider failure is reported in status, reasons, warnings and error metadata. It is never a successful empty search. A namesake or missing field remains uncertain; no confidence float hides it.

Kind-specific policy#

• Place: a name/type match and an official site, precise coordinates or address can anchor selection. A generic name plus coordinates alone fails closed. City/country support selection.
• Venue: preserve the physical venue grain. A theatre company, sports team, operator or owner is not the venue. Mixed place/organization types require coordinate or address evidence for physical selection.
• Person/author: names alone never confirm. Authors use person policy with role evidence. Prior reviewed identifiers or reviewed dedicated official profiles can anchor; generic social profiles and shared hosts do not automatically qualify. Roles and affiliations support review.
• Organization: distinguish parent, branch, subsidiary and team. Shared corporate roots, directory profiles and partial URL paths do not establish ownership of the local identity. Incomplete grain evidence fails closed.

The selected comparisons, thresholds and exact closed codes are in Identity reason codes. Legacy resolver rules remain documented in Entity resolution.

Resolve a JSONL corpus#

Create 100 public-example audit inputs without private data:

python - <<'PY'
import json
with open('audit100.jsonl', 'w') as out:
    for i in range(100):
        out.write(json.dumps({'local_id': f'example-{i}', 'canonical_name': 'Fox Theatre',
          'kind': 'place', 'existing_qid': 'Q1440190', 'city': 'Atlanta',
          'latitude': 33.7725, 'longitude': -84.3857,
          'official_url': 'https://www.foxtheatre.org/'}) + '\n')
PY
wdkg identity-batch audit100.jsonl --out audit100.out.jsonl --existing-id-audit \
  --jsonl --wikidata-only --concurrency 4 --max-provider-calls 30
wdkg identity-batch audit100.jsonl --out audit100.out.jsonl --existing-id-audit \
  --jsonl --wikidata-only --concurrency 4 --max-provider-calls 0

The second command resumes the complete checkpoint with zero provider calls. For a warm-cache re-decision into a new file, use the same input and a new --out with --max-provider-calls 0. For missing identities use --discover-missing; mixed corpora automatically audit rows that have QIDs and discover rows without them. --kind supplies an explicit default for missing kinds.

The output is streaming JSONL in input order, with per-row errors. Memory is bounded by --chunk (default 25, maximum 200). A prefix checkpoint binds the input file hash, configuration and policy; changed inputs/configuration require a new output file. Torn final lines are recomputed. Budget resume and --retry-errors recompute the failed row and later suffix using reusable observations. Use --evidence-out audit100.evidence.jsonl for a separate inspectable evidence export. It includes local input and rejected candidates even for AMBIGUOUS, WRONG_IDENTITY and insufficient-evidence rows. Use the same evidence file when resuming; it must match the completed decision prefix.

The receipt reports confirmed, wrong_existing, strong_candidate, ambiguous, no_candidate and provider_error (plus insufficient_evidence where applicable), actual HTTP attempts, throughput and policy. Strong candidates remain review-only. Retries count against the total --max-provider-calls cap. Rate gates and bounded concurrency apply to provider requests.

Compact bulk QID lookup#

wdkg lookup-qids Q1440190 Q193375 --fields labels,classes,websites,coordinates --wikidata-only
printf '"Q1440190"\n"Q193375"\n' > qids.jsonl
wdkg lookup-qids --input qids.jsonl --out facts.jsonl --max-provider-calls 30

Wikidata's wbgetentities is batched up to 50 QIDs per request. Lookup returns selected compact normalized facts, source and retrieval metadata; it does not confirm local identity. Use --fields to narrow the answer. The MCP hard limit is 10 QIDs and its output remains byte bounded. An oversized request is rejected with guidance to the CLI, rather than pushing a corpus into context.

Optional Google cross-check and cache#

wdkg audit-identity "Fox Theatre" --kind place --qid Q1440190 \
  --url https://www.foxtheatre.org/ --google-crosscheck
wdkg audit-identity "Fox Theatre" --kind place --qid Q1440190 \
  --url https://www.foxtheatre.org/ --no-google
wdkg audit-identity "Fox Theatre" --kind place --qid Q1440190 \
  --url https://www.foxtheatre.org/ --wikidata-only --max-provider-calls 0

Only explicit cross-check mode may use GOOGLE_KNOWLEDGE_GRAPH_API_KEY. Google is queried through exact observed P646/P2671 identifiers, never as the sole confirmation source. Missing credentials are explicit. The key is never printed. Google names, scores, websites, Wikipedia URLs and raw bodies are not placed into identity decision/evidence records. Existing short-lived cache policy remains governed by provider response cache headers; see Privacy.

Wikidata observations and decisions share existing bounded persistent storage, with separate cache identities. A policy change can re-decide from unexpired provider observations. --refresh or --no-cache bypasses reuse; a fresh batch must use a new output file. Determinism applies to fixed input, policy, observations and configuration. Changed live provider data can change output.

Inspect verdicts and contradictory evidence before proposing any public sameAs change. The consuming application is responsible for acceptance, publication, privacy and subsequent review.