[matbrgz]

O que muda

Spec 004 (docs/specs/004-wikidata/), com os ADRs 0008 acesso ao Wikidata e 0009 ligações entre variantes.

• Fonte wikidata (CC0, conferido em https://www.wikidata.org/wiki/Wikidata:Licensing), attested, sem país. O adaptador src/namescommons/adapters/wikidata.py lê 15 páginas de consultas SPARQL ao QLever (prenomes Q202444, sobrenomes Q101352, P460, P1533, P1560, P5278, P1889, P2440), paginadas com LIMIT 200000 e URLs fixas, então fetch e --offline funcionam como nas outras fontes.
• Observações: o nome vem do rótulo nativo (P1705). O gênero vem da classe do item: unissex gera F e M, e uma linha sem gênero é omitida quando o mesmo nome tem gênero informado por outro item (para cumprir a R1.5 da spec 002). Rótulos que não são nomes (Q34147, Ritwik (given name), Felbert,von, valor desconhecido) são pulados. script continua sendo a escrita detectada no nome; a P282 não é usada (R3.7).
• variant_links: tabela nova e opcional no contrato (RawLink, links(files)). As relações são same_item, said_to_be_the_same, family_name_identical, other_gender, different_from e transliteration. ingest --links e build --links a levam até a release, e run grava variant_links.parquet. Não há agrupamento: o group_id fica para a spec 005. SCHEMA_VERSION passa a 1.1.0, porque a release ganha um arquivo.
• Issue Spec 004: regra de primary em fontes attested (pendência da 001) #3: a regra de "exatamente uma primary" passa a valer só para births e population. A spec 001 (R2) recebeu uma nota.
• Amostra: tests/fixtures/wikidata/ tem 16 KB de respostas reais do QLever restritas a 25 itens, geradas por tools/amostra_wikidata.py. A CI roda o Wikidata no passo das fontes de sources.yaml e confere variant_links.parquet.

Status da spec: Em implementação (passa a Implementada depois do merge).

Critérios de aceite e como foram verificados

1. A fonte está em sources.yaml e load_sources a aceita: test_fonte_registrada, test_amostra_e_atribuicao[wikidata].
2. parse produz os registros escritos à mão (Andrea F/M de três itens, Letha sem a linha vazia, 李 sem gênero, rótulos inválidos pulados): test_parse_da_amostra_real, test_genero_vazio_cede_ao_informado.
3. links produz as ligações escritas à mão (Иванов other_gender Иванова, Мария transliteration Mariya, sem auto-ligação): test_links_da_amostra_real, test_transliteracoes_da_amostra_real.
4. R2.3 (última página cheia, página com linhas depois de página incompleta, cabeçalho inesperado): testes de mesmo nome em tests/test_wikidata.py.
5. run --offline grava variant_links.parquet e o manifesto traz 1.1.0 com as linhas do arquivo: tests/test_cli_links.py.
6. Duas fontes attested sem primary são aceitas, e duas births sem primary continuam recusadas: test_attested_nao_exige_primary, test_contagem_continua_exigindo_uma_primary.
7. CI: uv sync, uv run pytest -q (592 passed localmente) e os dois passos run --offline, exercitados por tests/test_ci.py.
8. R8 com os arquivos reais (Apple M4, 24 GB). fetch wikidata baixou 15 arquivos, 216 MB, em 54 s. run --offline só com o Wikidata gerou 816.771 observações e 436.971 ligações em 60 s, com pico de 2,01 GB. Num único run --offline com as 3 milhões de observações sintéticas do tools/bench_pipeline.py mais o Wikidata: 3.816.771 observações em 99 s, com pico de 3,43 GB (dentro dos 4 GB, com margem pequena: Margem de memória do R8 com o Wikidata (3,43 GB de 4 GB) #31).
9. Closes #3.

Decisões que tomei sozinho (e o custo se estiverem erradas)

• QLever em vez de WDQS ou do dump (ADR 0008). O WDQS estourou o tempo nas consultas de sobrenome (700 mil itens), e o dump tem mais de 100 GB. Custo se estiver errada: o pipeline depende de um serviço acadêmico sem acordo de nível de serviço. As consultas usam SPARQL padrão e a alternativa ficou na Wikidata: ingestão do dump completo e endpoint alternativo ao QLever #29.
• Páginas fixas de 200.000 linhas, com falha alta quando a última vem cheia. Custo: quando o Wikidata crescer, alguém precisa mudar um número no módulo. Uma linha pode faltar na fronteira entre páginas se o índice mudar entre os downloads; isso não é detectável hoje (Wikidata: ingestão do dump completo e endpoint alternativo ao QLever #29).
• Unissex vira F e M; a linha sem gênero cede à com gênero. Custo: female_share não é afetado (não há contagem), mas quem filtra os nomes "femininos atestados" no Wikidata vê também os unissex.
• country sempre vazio. A P495 aparece em 0,3% dos itens. Custo: nenhum país vem do Wikidata. O nome entra no índice mundial com country_count 0.
• Só o rótulo nativo (P1705). Ficam fora 6.569 prenomes e 43.195 sobrenomes sem P1705 (Wikidata: itens de nome sem rótulo nativo (P1705) #30).
• Filtro de rótulos (algarismos e pontuação como ( ) / , _). Pula 90 prenomes, 84 sobrenomes e 2.130 transliterações (quase todas com tom numérico). Custo: um nome legítimo com esses caracteres seria perdido; não encontrei nenhum na amostra medida.
• P5279 descartada. A propriedade é "hyphenation", não transliteração.
• Tabela de ligações com a direção publicada e sem auto-ligações por name_key. Custo: Andrea M P1889 Andrea F some, porque é o mesmo nome. A spec 005 trabalha com name_key e não perde nada com isso.
• SCHEMA_VERSION 1.1.0 pelo arquivo novo na release.
• ADRs numerados 0008 e 0009, porque 0004 a 0007 foram ocupados pelas specs 003b, 003d e 003e durante este trabalho. A branch recebeu um merge de origin/master (spec 003e). Ela não conflita com a master atual (PR Endurece o leitor de XLSX contra DTD nos membros XML #33).

Issues

• Fecha: Spec 004: regra de primary em fontes attested (pendência da 001) #3
• Criadas: Wikidata: ingestão do dump completo e endpoint alternativo ao QLever #29 (dump e endpoint alternativo), Wikidata: itens de nome sem rótulo nativo (P1705) #30 (itens sem P1705), Margem de memória do R8 com o Wikidata (3,43 GB de 4 GB) #31 (margem de memória do R8)

Closes #3

🤖 Generated with Claude Code