MetacouplingLLM 0.2.1__tar.gz → 0.2.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (173) hide show
  1. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/CHANGELOG.md +726 -0
  2. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/INTRODUCTION.md +11 -8
  3. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/MANUAL.md +212 -50
  4. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/PKG-INFO +12 -9
  5. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/README.md +2 -1
  6. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/docs/METHODS_adjacency.md +55 -6
  7. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/docs/REPRODUCING.md +1 -1
  8. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/docs/adm1_aliases_audit.csv +118 -7
  9. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/pyproject.toml +1 -1
  10. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/validate_adm1_aliases.py +263 -22
  11. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/__init__.py +3 -1
  12. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/core.py +132 -61
  13. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/data/PROVENANCE.md +1 -1
  14. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/data/adm1_aliases.csv +118 -7
  15. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/knowledge/adm1_pericoupling.py +508 -9
  16. metacouplingllm-0.2.2/src/metacouplingllm/knowledge/countries.py +1237 -0
  17. metacouplingllm-0.2.2/src/metacouplingllm/knowledge/examples.py +1020 -0
  18. metacouplingllm-0.2.2/src/metacouplingllm/knowledge/places.py +292 -0
  19. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/knowledge/rag.py +55 -37
  20. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/knowledge/websearch.py +12 -11
  21. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/llm/client.py +38 -6
  22. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/llm/parser.py +222 -39
  23. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/output/formatter.py +30 -11
  24. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/prompts/builder.py +110 -46
  25. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/prompts/templates.py +3 -2
  26. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/visualization/__init__.py +37 -0
  27. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/visualization/adm1_map.py +10 -1
  28. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/visualization/worldmap.py +67 -10
  29. metacouplingllm-0.2.2/tests/test_adjacency_settings.py +561 -0
  30. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_adm1_name_matching_regression.py +44 -2
  31. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_adm1_pericoupling.py +895 -11
  32. metacouplingllm-0.2.2/tests/test_anthropic_sdk.py +195 -0
  33. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_builder.py +198 -0
  34. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_client.py +126 -0
  35. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_core.py +373 -0
  36. metacouplingllm-0.2.2/tests/test_countries.py +689 -0
  37. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_docs_examples.py +47 -0
  38. metacouplingllm-0.2.2/tests/test_examples.py +248 -0
  39. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_formatter.py +29 -1
  40. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_parser.py +630 -0
  41. metacouplingllm-0.2.2/tests/test_place_readings.py +179 -0
  42. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_rag.py +145 -1
  43. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_relabel_sliver_corridors.py +2 -1
  44. metacouplingllm-0.2.2/tests/test_validation_notes.py +559 -0
  45. metacouplingllm-0.2.2/tests/test_visualization_wrappers.py +71 -0
  46. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_websearch.py +82 -0
  47. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_worldmap.py +111 -0
  48. metacouplingllm-0.2.1/src/metacouplingllm/knowledge/countries.py +0 -725
  49. metacouplingllm-0.2.1/src/metacouplingllm/knowledge/examples.py +0 -713
  50. metacouplingllm-0.2.1/tests/test_countries.py +0 -204
  51. metacouplingllm-0.2.1/tests/test_examples.py +0 -208
  52. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/.github/workflows/test.yml +0 -0
  53. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/.gitignore +0 -0
  54. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/LICENSE +0 -0
  55. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/build_data/arc_and_combined_screens/SPEC_ba1_border_arc_and_screens.md +0 -0
  56. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/build_data/build_record/relabel_RESULTS.md +0 -0
  57. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/build_data/geodesic_distances/SPEC_gd1_geodesic_distances.md +0 -0
  58. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/build_data/ndlsa_ne/SPEC_da1_defacto_administrators.md +0 -0
  59. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/build_data/stage_order/SPEC_st1_stages.md +0 -0
  60. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/build_data/water_screen_rebuild/corridor_census_exact/SPEC_cc1_corridor_census.md +0 -0
  61. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/build_data/water_screen_rebuild/crossing_adjudication/SPEC_ca1_crossing_adjudication.md +0 -0
  62. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/build_data/water_screen_rebuild/crossing_width/SPEC_cw1_crossing_width.md +0 -0
  63. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/build_data/water_screen_rebuild/july_rejections/SPEC_jr1_july_rejections.md +0 -0
  64. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/build_data/water_screen_rebuild/rule_rejections/SPEC_mr1_rule_rejections.md +0 -0
  65. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/build_data/water_screen_rebuild/uniform_acceptance/SPEC_ua1_uniform_acceptance.md +0 -0
  66. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/docs/BRIDGE_CLASSIFICATION_METHODOLOGY.md +0 -0
  67. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/docs/FUTURE_EDGE_AUDITS.md +0 -0
  68. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/docs/FUTURE_WORK.md +0 -0
  69. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/docs/VALIDATION_SAMPLING_PLAN.md +0 -0
  70. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/docs/VALIDATION_STUDY.md +0 -0
  71. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/docs/ndlsa_tract_audit.csv +0 -0
  72. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/examples/brazil_soybean_adjacency.csv +0 -0
  73. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/examples/brazil_soybean_flows.csv +0 -0
  74. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/examples/fishing_eez/.gitignore +0 -0
  75. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/examples/fishing_eez/00_build_edge_table.py +0 -0
  76. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/examples/fishing_eez/01_build_region_map.py +0 -0
  77. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/examples/fishing_eez/02_compute_indicators.py +0 -0
  78. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/examples/fishing_eez/03_analysis.py +0 -0
  79. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/examples/fishing_eez/README.md +0 -0
  80. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/examples/fishing_eez/data/eez_region.json +0 -0
  81. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/examples/fishing_eez/data/fishing_edge_table.csv +0 -0
  82. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/examples/fishing_eez/data/s16_country_region.json +0 -0
  83. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/examples/fishing_eez/outputs/global_totals.csv +0 -0
  84. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/examples/fishing_eez/outputs/indicators_by_eez.csv +0 -0
  85. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/examples/fishing_eez/outputs/regional_catch.csv +0 -0
  86. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/examples/fishing_eez/outputs/regional_indicators.csv +0 -0
  87. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/examples/fishing_eez/outputs/telecoupled_share_timeseries.csv +0 -0
  88. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/examples/fishing_eez/run_all.py +0 -0
  89. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/apply_check_keywords.py +0 -0
  90. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/apply_overlays.py +0 -0
  91. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/audit_unreplaced.py +0 -0
  92. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/build_adm1_aliases.py +0 -0
  93. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/build_all.py +0 -0
  94. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/build_embeddings.py +0 -0
  95. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/build_paper_metadata_table.py +0 -0
  96. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/build_pericoupling_db.py +0 -0
  97. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/build_rag.py +0 -0
  98. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/check_no_stale_metacoupling.py +0 -0
  99. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/check_oa_status.py +0 -0
  100. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/copyright_audit.py +0 -0
  101. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/diagnose_anthropic_web_search.py +0 -0
  102. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/draw_validation_sample.py +0 -0
  103. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/extract_keywords.py +0 -0
  104. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/integrate_keywords.py +0 -0
  105. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/match_references.py +0 -0
  106. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/organize_pdfs.py +0 -0
  107. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/organize_pdfs_v2.py +0 -0
  108. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/organize_pdfs_v3.py +0 -0
  109. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/patch_doi_inventory.py +0 -0
  110. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/rebuild_rag_corpus.py +0 -0
  111. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/regenerate_paper_metadata.py +0 -0
  112. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/relabel_sliver_corridors.py +0 -0
  113. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/strategy_b_decision.py +0 -0
  114. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/trace_pipeline.py +0 -0
  115. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/scripts/verify_papers_vs_bib.py +0 -0
  116. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/data/Papers.zip +0 -0
  117. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/data/PeriTelecoupling_clean.csv +0 -0
  118. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/data/PeriTelecoupling_subset.csv +0 -0
  119. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/data/chunk_embeddings.manifest.json +0 -0
  120. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/data/chunk_embeddings.npy +0 -0
  121. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/data/denylist_pairs.csv +0 -0
  122. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/data/disputed_overlay_pairs.csv +0 -0
  123. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/data/land_gap_overlay_pairs.csv +0 -0
  124. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/data/pericoupled_adm1_edge_list.csv +0 -0
  125. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/data/sliver_corridor_relabel.csv +0 -0
  126. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/data/telecoupling_literature.bib +0 -0
  127. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/data/water_classification_pairs.csv +0 -0
  128. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/data/water_separated_pairs.csv +0 -0
  129. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/indicators/__init__.py +0 -0
  130. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/indicators/_math.py +0 -0
  131. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/indicators/_prompts.py +0 -0
  132. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/indicators/_schemas.py +0 -0
  133. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/indicators/adjacency.py +0 -0
  134. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/indicators/classify.py +0 -0
  135. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/indicators/core.py +0 -0
  136. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/indicators/llm.py +0 -0
  137. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/knowledge/__init__.py +0 -0
  138. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/knowledge/citations.py +0 -0
  139. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/knowledge/framework.py +0 -0
  140. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/knowledge/literature.py +0 -0
  141. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/knowledge/pericoupling.py +0 -0
  142. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/knowledge/references.py +0 -0
  143. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/llm/__init__.py +0 -0
  144. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/output/__init__.py +0 -0
  145. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/output/export.py +0 -0
  146. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/prompts/__init__.py +0 -0
  147. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/src/metacouplingllm/tracing.py +0 -0
  148. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/__init__.py +0 -0
  149. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/_helpers.py +0 -0
  150. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/conftest.py +0 -0
  151. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/data/adm1_resolve_golden.json +0 -0
  152. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/data/avocado_main_analysis_response.md +0 -0
  153. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_adm1_map.py +0 -0
  154. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_apply_overlays.py +0 -0
  155. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_build_pericoupling_db.py +0 -0
  156. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_citations.py +0 -0
  157. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_coupling_first.py +0 -0
  158. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_data_csvs.py +0 -0
  159. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_docs_capabilities.py +0 -0
  160. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_framework.py +0 -0
  161. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_gemini_grok_support.py +0 -0
  162. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_indicators.py +0 -0
  163. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_indicators_llm.py +0 -0
  164. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_integration.py +0 -0
  165. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_literature.py +0 -0
  166. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_openai_integration.py +0 -0
  167. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_output.py +0 -0
  168. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_pericoupling.py +0 -0
  169. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_rag_only_mode.py +0 -0
  170. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_rag_pipeline.py +0 -0
  171. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_structured_extraction.py +0 -0
  172. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_templates.py +0 -0
  173. {metacouplingllm-0.2.1 → metacouplingllm-0.2.2}/tests/test_tracing.py +0 -0
@@ -7,6 +7,732 @@ file. The format is loosely based on
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.2.2] — 2026-10-24
11
+
12
+ A maintenance release: the Claude adapter works with anthropic 2.x, two
13
+ copies of the package no longer clash over the paper cache, place names are
14
+ read as texts write them, analyses are parsed in more of the forms models
15
+ write, and the adjacency settings reach the prompt and the maps. No
16
+ documented API is removed or renamed; `AnthropicAdapter`'s default model is
17
+ now `claude-sonnet-5-5`.
18
+
19
+ Highlights:
20
+
21
+ - **The Claude adapter works with anthropic 2.x**: anthropic 2.0.0
22
+ (2026-10-21) targets API version 2026-10-21, which has no `temperature`,
23
+ so on a fresh install every `AnthropicAdapter` call raised `TypeError`
24
+ except with `claude-opus-4-7` (0.2.1 too). The adapter now sends
25
+ `temperature` only to SDKs and models that take it (not anthropic 2.x,
26
+ not Claude 4.7 and later), and its default model is `claude-sonnet-5-5`;
27
+ the old default reached its end-of-life on 2026-06-15. New tests run the
28
+ adapter and Claude web search through the installed SDK.
29
+ - **The paper cache is safe across installs**: two copies of the package
30
+ on one machine (a checkout and a venv, say) re-extracted the bundled
31
+ papers over each other, so a copy reading them could see part of the
32
+ corpus and fall back to TF-IDF. Each corpus now has its own folder, named
33
+ after the zip's contents and filled before it is put in place.
34
+ - **Framework examples checked against the corpus**: the five bundled
35
+ examples were replaced; each now summarises one paper in the literature
36
+ corpus, is laid out coupling-first and gives each system's role per flow.
37
+ The constants of the four retired cases (`SOYBEAN_TRADE`, `PANDA_SDGS`,
38
+ `RIFA_INVASION`, `BEIJING_WATER`) are gone from
39
+ `metacouplingllm.knowledge.examples`.
40
+ - **Country and region names read as texts write them**: region names with
41
+ their type ("Narok County"), with a country's name inside ("New South
42
+ Wales") or with other separators, letters or apostrophes resolve; free
43
+ text no longer finds Wales in "New South Wales" or Andorra in "and"; the
44
+ ADM1 alias table grows from 1,145 to 1,256 entries (863 → 922 regions,
45
+ 136 → 140 countries); `find_country_codes` is exported from the package.
46
+ - **The adjacency settings reach the prompt and the maps**:
47
+ `de_facto_borders` and `coupling_standard` now also apply to the
48
+ pericoupling hint in the system prompt and to the maps, and the
49
+ `metacouplingllm.visualization` map functions take every keyword of the
50
+ functions they wrap.
51
+ - **Parsing**: a §6 Research Gaps written as a numbered list or as
52
+ paragraphs, a system scope after a dash and a colon inside a bold label
53
+ are parsed, and a flow whose heading names two categories gets the same
54
+ category in every run.
55
+ - **Validation and hints**: a validation note calls the classification
56
+ consistent only when its check classified a pair; the prompt's ADM1 hint
57
+ names a region the description writes; the automatic map's text fallback
58
+ follows the query's framing.
59
+
60
+ ### Changed
61
+
62
+ - **The five bundled framework examples were replaced.** Each now summarises
63
+ one paper in the literature corpus and was checked against it: Wolong Nature
64
+ Reserve (Liu 2017), South American food trade (Herzberger et al. 2019),
65
+ global marine fishing (Carlson et al. 2020), groundwater bottling and Michigan
66
+ trout streams (Carlson, Taylor and Hughes 2020) and transatlantic wood pellets
67
+ (Parish et al. 2018). The old set misstated some sources, for example the
68
+ fire-ant case cited Liu et al. (2013) for a USA-to-China invasion the paper
69
+ does not describe. Examples are now laid out coupling-first like the analysis
70
+ they model, give each system's role per flow, and use the template's
71
+ cross-coupling vocabulary; tests check that every source paper is in the
72
+ bundled corpus and that country pericouplings match the adjacency data.
73
+ - **`AnthropicAdapter`'s default model is `claude-sonnet-5-5`.** The old
74
+ default, `claude-sonnet-4-20250514`, reached its end-of-life on
75
+ 2026-06-15 according to the anthropic SDK's deprecation table, so an
76
+ adapter built without `model=` called a retired model. The MANUAL and
77
+ INTRODUCTION examples name the new default.
78
+
79
+ ### Fixed
80
+
81
+ - **Region names written with their type resolve: "Narok County",
82
+ "Kagoshima Prefecture", "Rangpur Division".** `resolve_adm1_code` returned
83
+ `None` for many names as researchers write them, so adjacency validation
84
+ never engaged for those regions: with the country hint, "Narok County" gave
85
+ `None` while "Narok" gave `KEN033`, and "Rajshahi Division" resolved only
86
+ because the alias table happened to list it, while "Rangpur Division" did
87
+ not. When no strategy matches, the resolver now removes one trailing
88
+ designator and resolves the rest. Region, province, state and oblast count
89
+ in any country, as they already did after a canonical name; county,
90
+ prefecture, division, department, district, governorate and voivodeship
91
+ count only in the countries whose World Bank first-level units carry them,
92
+ so "Washington County" does not become the State of Washington, nor
93
+ "Khulna District" the Khulna Division. The result is refused when the rest
94
+ also names another unit of the same country ("Almaty Province": "Almaty"
95
+ is Almaty City) or matches several regions ("La Paz Department" without a
96
+ country). A name that resolved before is unchanged: of the 183,917
97
+ queries recorded before the change (each World Bank name and alias with
98
+ and without its country hint, alone and followed by a designator, and the
99
+ recorded name-matching queries), none of the 43,883 that resolved gives a
100
+ different code. The alias table gains 18 curated entries, each checked
101
+ against the source its basis cites (1,145 → 1,163 entries, 863 → 872
102
+ regions):
103
+ "Mexico City", "Silesian Voivodeship", "North-West District" (Ngamiland),
104
+ "Barisal", the English names of five more Polish voivodeships and two
105
+ Chilean regions, the full official names of three Chilean regions that the
106
+ World Bank names shorten ("Libertador General Bernardo O'Higgins" for
107
+ "Libertador Gral. Bernardo O'Higgins"), and four spellings the World Bank
108
+ names get wrong ("Lubelskie" for "Lubeiskie", "Małopolskie" for
109
+ "Malopolske", "Arica y Parinacota" for "Arica y Painacota",
110
+ "Zachodniopomorskie" for "Zachodnio-Pomorskie").
111
+ `scripts/validate_adm1_aliases.py` holds the curated list and still
112
+ reproduces the other 1,145 entries byte for byte. Tests +108 (suite
113
+ 1,623).
114
+ - **Region names that contain a country's name resolve without a country
115
+ hint: "New South Wales", "British Columbia", "Mexico City".** Without a
116
+ hint, `resolve_adm1_code` returned `None` for every name in which
117
+ `resolve_country_code` found a country, so 52 of the 3,374 regions did not
118
+ resolve under their own World Bank names, some read as another country:
119
+ "New South Wales" and "East New Britain" as the United Kingdom, "Northern
120
+ Ireland" as Ireland, "Port Of Spain" as Spain, "New Jersey" as Jersey,
121
+ "Thai Binh" as Thailand. It now refuses only a name that is a country's ISO
122
+ code, name or alias (what `resolve_country_code` tests with the new
123
+ `substring=False`), alone or among the connector and administrative words
124
+ its matcher ignores ("of Mexico", "State of Mexico", "Niger State");
125
+ without that last part, n-grams of running text such as "region of
126
+ Mexico" (from "the Michoacán region of Mexico") would resolve to the State
127
+ of México. The 33 names with another word besides a country's name
128
+ resolve to their own regions, as do the curated aliases "Mexico City",
129
+ "Lesser Poland", "Greater Poland" and "Magallanes and the Chilean
130
+ Antarctica"; the 19 that are a country's name ("Georgia", "Niger",
131
+ "Wales", "Est", which is Estonia's ISO code) still need the hint, and so
132
+ now do "México" and "Panamá" (next entry). A research description naming
133
+ such a region ("Wool exports from New South Wales") now counts as
134
+ subnational for the validator and the map. Of the 14,421 recorded
135
+ name-matching queries, eight give a different result, each listed with
136
+ its reason in the regression test: "British Columbia", "Western
137
+ Australia", "Ile-de-France", "Île-de-France", "Ciudad de Mexico" and
138
+ "Mexico City" resolve without a hint, and "México" and "Estado de México"
139
+ no longer do. Of the 124,013 phrases with a
140
+ country's name in them among the one- to four-word phrases and capitalised
141
+ word groups of the 421 corpus papers and the avocado run, 23 resolve
142
+ differently without a hint: 22 to the region they name (New Jersey,
143
+ Western Australia, New South Wales and others) and "México" to `None`.
144
+ - **The alias table takes English names that contain a country's name:
145
+ "Upper Austria", "Inner Mongolia", "North Holland", "East Azerbaijan"
146
+ (1,163 → 1,201 entries, 872 → 897 regions, 136 → 138 countries).**
147
+ Validation rule G of `scripts/validate_adm1_aliases.py` dropped every
148
+ generated alias in which `resolve_country_code` found a country, 64 of
149
+ them, because the resolver read such names as the country without a hint
150
+ (entry above). It now drops only a key that is a country's code, name or
151
+ alias, 4 of them ("hong kong", "kuwait", "french guiana", "saint
152
+ martin"). Of the 50 aliases this admitted, each checked against
153
+ Wikipedia's lists of the countries' divisions and the units' own
154
+ articles, 38 ship and 12 went on the review denylist: the capital-city
155
+ namesakes "kuwait city", "luxembourg city" and "panama city"; "french
156
+ riviera", the coast of Provence-Alpes-Côte d'Azur; generic labels that
157
+ span several units, "northern", "eastern" and "western kazakhstan",
158
+ "north lebanon" (also Akkar), "south lebanon" (also Nabatieh) and
159
+ "southwest ethiopia" (the RAG corpus's "southwestern Ethiopia" studies lie
160
+ in Jimma Zone, Oromia); the former name "lower congo" (Bas-Congo, renamed
161
+ Kongo Central in 2015); and the calque "isle of france", once the name of
162
+ colonial Mauritius. Seven others are now redundant (rule R1): with the
163
+ country hint they resolve without an alias ("british columbia", "port of
164
+ spain"). Deduplication (rule D0) now keeps the curated record when a
165
+ generated alias has the same key and code, so "mexico city", "lesser
166
+ poland" and "greater poland", which the generation run had also
167
+ proposed, keep their cited sources in the audit table. The 14,421
168
+ recorded name-matching results are unchanged.
169
+ - **`resolve_country_code` ignores accents and reads the World Bank's
170
+ country names.** "México", "Perú", "Panamá", "Curaçao" and "Réunion"
171
+ returned `None`, as did "España", "Brasil", "Bangladeshi", "Kyrgyz
172
+ Republic", "Slovak Republic" and "Lao People's Democratic Republic", and
173
+ the World Bank's "Congo, Dem. Rep." and "Korea, Dem. People's Rep." gave
174
+ the Republic of the Congo and South Korea. Case, accents, curly
175
+ apostrophes and repeated spaces are now ignored, and a leading "the" when
176
+ the text is a whole name ("the Gambia"). New aliases add the two names in
177
+ the country's own language, "Bangladeshi", and the World Bank's names that
178
+ resolved to `None` or to another country. In its country list
179
+ (api.worldbank.org, read 2026-10-16) 12 of the 217 economies did, and 11
180
+ now resolve, among them "St. Lucia", "Virgin Islands (U.S.)" (read as the
181
+ United States), "St. Martin (French part)" (as France) and "Puerto Rico
182
+ (US)" (next entry); the Channel Islands have no ISO code. In the
183
+ boundary data behind the ADM1 database, "Democratic Republic of Congo" and
184
+ "D. P. R. of Korea" gave COG and KOR, so for their regions web search
185
+ wrote the Republic of the Congo and South Korea into its queries. Tests
186
+ +78 with the two entries above (suite 1,701).
187
+ - **"Puerto Rico" resolves to Puerto Rico, not the United States.** The
188
+ alias table listed "puerto rico" twice, as PRI and further down as USA,
189
+ and the later key wins, so `resolve_country_code` read Puerto Rico as the
190
+ United States, although the country pericoupling table, the ADM1 database
191
+ and the World Bank boundaries of both maps give it its own code, PRI. A
192
+ map with Puerto Rico as its focal country showed the United States, with
193
+ Canada and Mexico pericoupled, and arrows from Puerto Rico started in the
194
+ middle of the contiguous United States; `lookup_pericoupling` called
195
+ Puerto Rico and Mexico pericoupled, and the database hint for a research
196
+ description naming only Puerto Rico gave the United States as its focal
197
+ country, with Canada and Mexico as neighbours. With the country hint
198
+ "Puerto Rico", `resolve_adm1_code` found none of the island's eight regions
199
+ ("San Juan" gave `None`, "Montana" the US state), nor did the map's
200
+ region scan of an analysis about Puerto Rico, and web search named their
201
+ country the United States ("Ponce, United States"). "Puerto Rico", the
202
+ World Bank's "Puerto Rico (US)" and its boundary data's "Puerto Rico
203
+ (U.S.)" now resolve to PRI, which the pericoupling table gives no
204
+ pericoupled neighbour. A new test fails on a repeated alias key; the two
205
+ other repeats in the table gave the same code twice.
206
+ - **ISO 3166 names written inverted resolve to their own country.** In
207
+ Debian's iso-codes data (the names pycountry gives) and Wikipedia's table
208
+ of ISO 3166-1, "Korea, Democratic People's Republic of" gave South Korea,
209
+ "Congo, The Democratic Republic of the" and "Congo, Democratic Republic
210
+ of the" the Republic of the Congo, "Virgin Islands, British" and "Virgin
211
+ Islands (British)" the United Kingdom, and "Virgin Islands, U.S." and the
212
+ official name "Virgin Islands of the United States" the United States,
213
+ each through a shorter name inside it. Seven aliases add them. Of the 433
214
+ names of the 249 entries in iso-codes (short, official and common), all
215
+ now give their own code except "Pitcairn" and the official names of
216
+ Gabon, Greece, Rwanda and Togo ("Gabonese Republic"), which give `None`,
217
+ and the names of three places the package has no code for: Antarctica
218
+ gives `None`, British Indian Ocean Territory the United Kingdom and South
219
+ Georgia and the South Sandwich Islands Georgia. Tests +10 with the
220
+ previous entry (suite 1,711).
221
+ - **A word that only begins a region's name no longer resolves to that
222
+ region: "other" is not Other Territories, nor "Puerto" Puerto Plata.**
223
+ Without a country hint, `resolve_adm1_code` took a single word that began
224
+ a longer World Bank name, or that a slash or an accented letter set off
225
+ inside one, for that region. The prompt's ADM1 hint, web search and the
226
+ map's region scans try each word of a description on its own, so "How
227
+ does soybean trade between Brazil and China affect other countries?" got
228
+ Other Territories (Australia) as its focal region, "the European Union"
229
+ La Unión (El Salvador), "Federal subsidies" Distrito Federal (Brazil),
230
+ "the lower Mekong" Lower River (The Gambia), "Coffee exports from Puerto
231
+ Rico" Puerto Plata (Dominican Republic) and "San Juan, Puerto Rico" San
232
+ Juan/Laventille (Trinidad and Tobago), and web search wrote these regions
233
+ into its queries. Of the 51,848 distinct words, as written, of the 421
234
+ corpus papers, 648 resolved without a hint and 177 of them no longer do:
235
+ "other", "area", "under", "long", "cross", "sector", "River", parts of
236
+ longer names ("Minas", "Addis") and given names and surnames ("María",
237
+ "Khan", "John"). A single word now resolves without a hint only as a
238
+ whole name, name variant or alias; with a hint it may still begin a
239
+ longer name ("Badakhshan" with "TJK"). The short names that are a
240
+ region's own resolve through 48 new aliases ("Beijing", "Shanghai",
241
+ "Xinjiang", "Michoacan", "Veracruz", "Madrid", "Tbilisi"): rule R1 of the
242
+ alias build no longer drops as redundant a one-word key that the resolver
243
+ found only as the start of a longer name, which admitted 50 generated
244
+ aliases, and the common English words "northwest", "oriental" and "udon"
245
+ went on the review denylist; "Brussels" is curated. Names written with
246
+ spaces for their hyphens now match ("Schleswig Holstein", "Baden
247
+ Württemberg"), which text scans need, as they split words at hyphens;
248
+ seven aliases this makes redundant are gone ("dar es salaam"). The table
249
+ goes from 1,201 to 1,242 entries (897 → 920 regions, 138 → 140
250
+ countries), and rule C1 caps only a region's generated aliases at three,
251
+ so Magallanes keeps its two curated ones. Of the 14,421 recorded
252
+ name-matching queries, ten change, each listed in the regression test:
253
+ eight words no longer resolve ("other", "Union", "federal") and "Ile de
254
+ France" and "KwaZulu Natal" now do. Tests +30 (suite 1,741).
255
+ - **Region names written with other separators, letters or apostrophes
256
+ resolve: "Trans-Nzoia", "Skåne", "Murang’a".** `resolve_adm1_code` returned
257
+ `None`, even with the country hint, for names that differ from a World Bank
258
+ name or alias only in how their words are joined or spelled: a hyphen, en
259
+ dash or nothing where the World Bank writes something else ("Trans-Nzoia"
260
+ for "Trans Nzoia", "Taita–Taveta", "Bío Bío" for "Biobio", Botswana's
261
+ "North-East District" for "North East"), a curly, other or no apostrophe
262
+ ("Murang’a" for "Murang'a", "Valle d’Aosta", "Hawkes Bay" for "Hawke's
263
+ Bay"), and the å, ä, ö, ø and ü that the World Bank spells out in Swedish,
264
+ Norwegian and some German names ("Skåne" for "Skaane Laen", "Thüringen" for
265
+ "Thueringen"). With the hint, the World Bank's multi-word names returned
266
+ `None` when written with hyphens in 769 of 1,038 cases, with en dashes in
267
+ 1,209 of 1,211 and with no separator in 1,205 of 1,211, and its 57 names
268
+ with an apostrophe or grave accent in 266 of 280 variants written with ’, ‘,
269
+ ʼ, `` ` `` or none; all now resolve, except names that two units of a
270
+ country share. When neither the strategies nor the designator retry resolve
271
+ a name, the resolver compares it with every name and alias by a spelling key
272
+ that drops spaces, hyphens, dashes and apostrophes and takes those letters
273
+ both as written and spelled out; failing that, it repeats the designator
274
+ retry with the rest compared the same way ("Trans-Nzoia County"). A key must
275
+ identify one region, in the hinted country when a hint is given, so "Nord
276
+ Ouest" without a hint (Haiti's Nord-Ouest and Cameroon's "Nord - Ouest")
277
+ stays `None`, and without a hint a name that is a country's is refused as by
278
+ the strategies. On the 200 research descriptions of the MetacouplingChat
279
+ set, the prompt builder now finds the labelled focal region of "The cherry
280
+ boom in O'Higgins, Chile", where it found none; the other 199, the
281
+ subnational-scope check on all 200 and the validator's ADM1 and flow-map
282
+ results on 63 saved analyses are unchanged. A name that resolved before is
283
+ unchanged: of the 1,440,634 queries recorded on main before the change (each
284
+ World Bank name, name-index key, alias key and alias display with and
285
+ without its country hint, alone and followed by each designator; the
286
+ recorded name-matching queries; and 1,177,308 separator, spelled-letter and
287
+ apostrophe variants of the same names), none of the 213,720 that resolved
288
+ gives a different code. Of the 359,366 that now resolve, 359,356 are
289
+ variants resolving to the region they were made from, and the other 10, dash
290
+ and joined forms of "North West District", are Botswana's North-West
291
+ District. The alias table gains 14 curated entries, each checked against the
292
+ source its basis cites (now 1,256 entries for 922 regions): the Swedish
293
+ counties Halland, Kronoberg, Jönköping, Gävleborg, Örebro and Skåne by name
294
+ alone (the World Bank names keep the Swedish genitive, "Hallands Laen", and
295
+ spell out the letters, so the unaccented "Orebro" missed "Oerebro Laen";
296
+ Stockholm is left out because in research text it mostly means the Stockholm
297
+ Resilience Centre or Convention), the Danish names of the five Danish
298
+ regions ("Region Midtjylland"), "Fryslân", "Hamadan" and "Khanty-Mansi
299
+ Autonomous Okrug". Tests +126 (suite 2,017).
300
+ - **Free text names a country only where it names the country: "New South
301
+ Wales" is not Wales, "South America" not the United States, "and" not
302
+ Andorra.** `resolve_country_code` returns the country of the longest name
303
+ or alias it finds in a text, so the callers that read countries out of
304
+ free text read a place named after a country as that country, and a word
305
+ that is a country code as that country. On the 421 papers of the RAG
306
+ corpus, read as each caller other than web search splits text, 162 to 182
307
+ papers per caller had the first kind of misread:
308
+ - continents: "South America" and "Latin American" as the United States;
309
+ - regions of other countries: "Inner Mongolia" as Mongolia in 30 papers,
310
+ "British Columbia", "New Mexico", "New England";
311
+ - seas and basins: "Indian Ocean", "Gulf of Mexico", "Congo Basin".
312
+
313
+ As web-search queries, 129 of the 421 paper titles took Andorra as their
314
+ national focus through the word "and", and 14 searched for a wrong
315
+ country's exports ("Andorra ... export destinations"). The pronoun "us"
316
+ read as the United States in 83 to 89 papers for each caller that reads
317
+ lower-case words.
318
+
319
+ The new `free_text=True` skips a country's name or alias found only inside
320
+ the name of another place. The other places are the ADM1 database's
321
+ region names and aliases that hold another country's name, and a list of
322
+ continents, seas, lakes, rivers, basins and regions. A code, and the alias
323
+ "us", count only when written in capitals. These callers now read with it:
324
+ - the map's market and partner chunks, the focal-country pick, the system
325
+ roles, and the country after a comma in a region's name ("Sydney, New
326
+ South Wales") in `core`;
327
+ - both world map extractors.
328
+
329
+ The country mentions of an analysis, the prompt's country hint and web
330
+ search's national focus read with `find_country_codes`, which applies the
331
+ same rules (see its entry below).
332
+
333
+ New aliases cover names a shorter alias read as another country: "North
334
+ Korean" and "DPR Korea" (South Korea), "South Sudanese" (Sudan) and
335
+ "Guinea Bissau" (Guinea). "Lao" is added too: free text now reads the code
336
+ LAO only in capitals. With it, Vietnam's "Lao Cai" holds a country's name,
337
+ like "Thai Binh"; it still resolves to its own region with or without a
338
+ hint.
339
+
340
+ On the same papers, no chunk caller loses a correct reading, and the
341
+ country mentions' wrong countries summed over papers fall from 266 to 12.
342
+ In the committed avocado run, "Central American receiving markets" no
343
+ longer reads as the United States, and no output changes. Of the 14 title
344
+ queries, none now names a wrong country. Still read as countries:
345
+ - homonyms (Chad Wong, Panama disease, "Indian" for Indigenous peoples);
346
+ - acronyms written as codes (LCA).
347
+
348
+ The alias build still reproduces both alias tables byte for byte. Tests
349
+ +73 (suite 1,814).
350
+ - **A §6 Research Gaps written as a numbered list is parsed.**
351
+ `parse_analysis` read §6 with the bullet extractor, which takes only dash,
352
+ asterisk and `•` items, so a §6 written as `1. **Label**: ...` gave an empty
353
+ `research_gaps`: the full report and the Markdown and Word exports left §6
354
+ out, the summary, comparison and component views reported no gaps, and the
355
+ countries and terms it named were missing from every scan of the analysis
356
+ text (the maps' text-scan fallback, ADM1 resolution, `recommend_papers()`).
357
+ §6 now also takes numbered items (`1.` or `1)`); the other sections still
358
+ take bullets only, since a numbered line there can be a heading such as
359
+ `1. **Matter Flow**`. Of 31 gpt-5.5 analyses saved on 2026-10-15, 7 wrote §6
360
+ as a numbered list; each now yields its 6 to 8 gaps, and the other 24 parse
361
+ exactly as before. Tests +4 (suite 1,454; the 1,441 in REPRODUCING predated
362
+ the nine tests #167 added).
363
+ - **A system whose scope follows a dash is parsed.** `parse_analysis` read a
364
+ system's scope only in parentheses, as the output template writes it
365
+ (`**Receiving System (distant)**: Nigeria`), so a heading such as
366
+ `**Receiving System — distant**: Nigeria` was not read as one: the system was
367
+ lost, its lines dropped or, after another system's heading in the same block,
368
+ merged into that system, overwriting its fields. The full report and the
369
+ Markdown and Word exports left it out, the maps' sending, receiving and
370
+ adjacent country lists and the country-level pericoupling check against the
371
+ coupling database missed its countries, and its text was missing from the
372
+ scans of the parsed analysis (ADM1 resolution, `recommend_papers()`). System
373
+ headings, and the flat-bullet fallback, now also take a scope after an em
374
+ dash, en dash or hyphen when it starts with `adjacent` or `distant`, and read
375
+ it as a scope in parentheses is read. Of 31 gpt-5.5 analyses saved on
376
+ 2026-10-15, 4 wrote 18 such headings, each ahead of any other system heading
377
+ in its block; each of the 4 now gains its 3 to 6 systems, and everything else
378
+ in the 31 parses exactly as before. Tests +9 (suite 1,463).
379
+ - **A §6 Research Gaps written as paragraphs is parsed.** `parse_analysis`
380
+ took only §6's list items (dash, asterisk, `•` or numbered), so a §6 written
381
+ as plain paragraphs or as `**1. Label**` lines gave an empty
382
+ `research_gaps`: the full report and the Markdown and Word exports left §6
383
+ out without notice, and the scans of the analysis text (the maps' text-scan
384
+ fallback, ADM1 resolution, `recommend_papers()`) missed it. A §6 without
385
+ list items is now read as paragraphs: each paragraph is a gap, a paragraph
386
+ that is only a bold label or a heading opens the paragraph after it, a
387
+ number at the start of a bold label is dropped as a list marker is, and
388
+ rules (`---`, `═══`) are skipped. A §6 with list items still yields only
389
+ them, except that a spaced rule such as `- - -`, which read as a dash item,
390
+ no longer does. None of the 31 gpt-5.5 analyses saved on 2026-10-15 writes
391
+ §6 without list items, and all 31 yield the same gaps as before.
392
+ - **A system scope that says more than "adjacent" or "distant" is read as
393
+ that word.** `parse_analysis` stored a qualifier such as `(adjacent
394
+ interaction)` whole as the system's `system_scope`, which `core.py` and the
395
+ maps compare with "adjacent", so a system headed `**Sending System (adjacent
396
+ interaction)**: Mexico` was not treated as adjacent: the maps put Mexico in
397
+ the sending role, and a flow from "neighboring producers" got no map arrow.
398
+ The scope is now the qualifier's leading "adjacent" or "distant", and a
399
+ qualifier that says more is kept whole as `system_scope_qualifier`, which
400
+ the report's system label shows as before (`Sending System (adjacent
401
+ interaction)`); a qualifier that starts with neither word ("regional", "not
402
+ adjacent") is the scope as written. Of the 31 saved analyses, 4 head 8
403
+ systems with such a qualifier, 7 distant (`distant coal importer`) and 1
404
+ adjacent (`adjacent interaction`); their scopes now read "distant" or
405
+ "adjacent", and their reports, exports, map roles, map arrows, coupling
406
+ checks and paper-search terms are unchanged (old/D12_r0's Mexico, the
407
+ adjacent case, was already adjacent on its maps through another system).
408
+ - **A label with its colon inside the bold is parsed.** `**Focal System:**
409
+ Michigan` gave the system name `** Michigan`, and `- **Human subsystem:**
410
+ Farmers` under it the value `** Farmers`. A flow heading such as `**Matter
411
+ Flow:**` was not read as one, so its flow lost its category and split in
412
+ two, and `- **Direction:** Brazil → China` gave the direction `** Brazil →
413
+ China`. An agent written `[Individuals / households] **Farmers:** ...` got
414
+ the name `**Farmers` and a description starting with `**`, and a cause or
415
+ effect heading `**Economic:**` opened a category `economic:` apart from
416
+ `economic`. System headings and the lines under them, the flat-bullet
417
+ systems fallback, flow headings and their `Direction` and `Description`
418
+ lines, the one-line flow bullets (`[Matter] **Brazil → China:** ...`,
419
+ `**Category:** Matter | **Direction:** ...`), agents, and cause and effect
420
+ headings now read the same with the colon inside the bold as after it.
421
+ Free text keeps its colons as written, such as an effect item `**Mexico:**
422
+ ...`. None of the 31 saved analyses writes a colon inside the bold. Tests
423
+ +52 with the two entries above (suite 2,069).
424
+ - **The adjacency settings reach the prompt hint and the maps.**
425
+ `MetacouplingAssistant` passed `de_facto_borders` and `coupling_standard`
426
+ only to the post-LLM validation; the pericoupling-database hint in the
427
+ system prompt and the automatic map called the adjacency lookups with the
428
+ defaults, so with other settings the hint could contradict the validation.
429
+ With `coupling_standard="lenient"`, a description of acid rain from Ohio
430
+ falling on Ontario got a hint listing only Ohio's five US neighbours, while
431
+ the validation counted Ontario, across Lake Erie, as a cross-border
432
+ neighbour. `PromptBuilder`, `plot_focal_country_map`, `plot_analysis_map`
433
+ and `plot_focal_adm1_map` (and their `metacouplingllm.visualization`
434
+ wrappers) now take both settings as keyword arguments, and the assistant
435
+ passes its own to the hint, the map and the map's same-country flow arrows.
436
+ The defaults are the lookups' own: with them, the system prompt for each of
437
+ 212 research descriptions (built directly and by a default assistant) and
438
+ the map classifications for every country (249, both country maps) and
439
+ every ADM1 region (3,374) are byte-identical to before. Tests +43 (suite
440
+ 1,506).
441
+ - **The `metacouplingllm.visualization` map functions take every keyword of
442
+ the functions they wrap.** These wrappers of `visualization.worldmap` and
443
+ `visualization.adm1_map` listed only some of their keywords and raised
444
+ `TypeError` on the rest: `adm0_shapefile` and `mentioned_countries` for
445
+ `plot_focal_country_map`; `adm0_shapefile`, `extra_mentioned_countries`,
446
+ `mentioned_countries_override`, `focal_code_override` and `flows` for
447
+ `plot_analysis_map`; `mentioned_countries`, `mentioned_adm1_codes` and
448
+ `flows` for `plot_focal_adm1_map`. The top-level `metacouplingllm.plot_*`
449
+ functions pass `**kwargs` through and were not affected, nor were MANUAL's
450
+ examples, which import those or the implementations. The wrappers now have
451
+ the signatures of the functions they wrap; tests compare the two and check
452
+ that every keyword reaches the implementation unchanged through both
453
+ wrappers. Tests +9 (suite 1,515).
454
+ - **The pericoupling hint finds every country a research description names, in
455
+ the order it names them.** When no ADM1 region is found, the system prompt's
456
+ pericoupling lookup pairs the first country the description names (the focal
457
+ country) with each other one, or lists its neighbours when it is the only one
458
+ (`PromptBuilder._build_coupling_hint`). It read the description in
459
+ consecutive chunks of up to four words, one country per chunk, so a name
460
+ across two chunks was missed ("Coffee production in Costa Rica" gave no
461
+ hint), a second name in a chunk was dropped ("Mexico and Canada avocado
462
+ trade" gave Canada alone, as the focal country), names with a hyphen,
463
+ apostrophe or diacritic did not match (Guinea-Bissau gave Guinea), and a word
464
+ alone in its chunk could be read as an ISO code ("between 2000 and 2024" gave
465
+ Andorra). The scan now takes, at each word, the longest run of words that is
466
+ exactly a country's name or alias, then goes on after it: names are read
467
+ whole, without the shorter names inside them ("Papua New Guinea" gives no
468
+ Guinea), names such as "Côte d’Ivoire", Türkiye and "U.S." match, and
469
+ countries keep the order of first mention. "US" counts only in capitals, and
470
+ a three-letter code only in capitals and set apart by punctuation, as in
471
+ "(BRA)", so the pronoun "us", acronyms such as LCA and words such as "and"
472
+ are not read as countries. The scan is `find_country_codes` (next entry),
473
+ which also reads the names of other places, such as "South America", as no
474
+ country. On 200 research descriptions written for testing, 55 countries the
475
+ descriptions name are added and 31 misreads dropped: 13 words read as
476
+ codes, mostly "and", 14 regions of other countries such as British Columbia
477
+ and New Jersey. The first country found is the labelled focal country in
478
+ 107 of the 196 labelled descriptions, against 101. On the 9,713
479
+ non-overlapping chunks of up to 250 words that the retrieval chunker cuts
480
+ from the 421 bundled papers:
481
+ - 495 countries the chunks name are added;
482
+ - 2,855 misreads are dropped: words read as codes 2,209 (mostly "and"),
483
+ continents 301, the pronoun "us" 164, regions of other countries 105,
484
+ seas and basins 45, and 31 cut names, homonyms and names without an
485
+ alias of their own;
486
+ - so are three acronyms LCA (Saint Lucia's code), and one Puerto Rico,
487
+ which the old alias read as the United States;
488
+ - three added readings are a given name: "Germán" read as German.
489
+
490
+ Tests +29 (suite 1,843).
491
+ - **`find_country_codes` reads every country a text names; web search's
492
+ national focus and an analysis's country mentions use it too.** The scan of
493
+ the entry above moved to `knowledge/countries.py` as
494
+ `find_country_codes(text, *, capitals=False)`, exported from the package.
495
+ It applies the free-text rules of `resolve_country_code`:
496
+ - the name of another place uses up its words and names only the place's
497
+ own country: "South America", "the Gulf of Mexico", "New South Wales",
498
+ "the Congo basin" and the pau-brasil tree name none, "Inner Mongolia,
499
+ China" names China;
500
+ - names are compared as `resolve_country_code` compares them, so accents
501
+ fold ("México", "Perú");
502
+ - up to three punctuation marks may complete a name ("U.S.", "Virgin
503
+ Islands (U.S.)").
504
+
505
+ Scanned alone, each country name, alias and place name gives what
506
+ `resolve_country_code(..., free_text=True)` gives.
507
+
508
+ Web search's national focus is now the first country a query names. It
509
+ was read from four-word phrases of the query, then shorter ones down to
510
+ single words, which took:
511
+ - the longest name in the first phrase holding one ("Mexico and Canada
512
+ avocado trade" focused on Canada);
513
+ - pieces of other places' names ("Soybean exports from South America" on
514
+ the United States, "Salmon bound for British Columbia ports" on the
515
+ United Kingdom).
516
+
517
+ On the 200 research descriptions the focus is wrong for none, against 12,
518
+ and is the labelled focal country for 107 of 196, against 104. On the 421
519
+ paper titles as queries it is wrong for none, against 8.
520
+
521
+ An analysis's country mentions are read with `capitals=True`, a name
522
+ counting only where it starts with a capital letter. They serve the ADM1
523
+ relevance guard, the country set of the region scan and the ADM1 code list
524
+ of the map-extraction prompt. They were capitalised word groups, which a
525
+ lower-case word, a hyphen or an apostrophe ended: "Trinidad and Tobago",
526
+ "Côte d'Ivoire" and "Timor-Leste" named no country, "the Congo basin" named
527
+ the Republic of the Congo and "North-American" the United States. On the
528
+ 421 papers, 92 countries the text names are added, and misread countries
529
+ fall from 10 to 6, all homonyms such as "Panama disease". The avocado run's
530
+ mentions are unchanged.
531
+
532
+ Tests +35 (suite 1,878).
533
+ - **A system's scope that opens with its country's name reads as the
534
+ country, not as the country's namesake region.** To find a focal region in
535
+ an analysis, `_resolve_adm1_from_analysis` reads each system's scope as
536
+ "region, …, country", the last comma part giving the country hint. When
537
+ the first part was the hinted country itself, it resolved to the region of
538
+ that name: "Mexico, especially Michoacán and Jalisco, Mexico" gave the
539
+ State of México (MEX015), and scopes opening with Guatemala, Panama or
540
+ Luxembourg gave their namesake regions. Thirteen countries' names resolve
541
+ to one of their own regions when the country is the hint. The first part
542
+ is no longer read as a region when it is only the hinted country's name.
543
+ "Michoacán, Mexico", "State of Mexico, Mexico", "Panamá Province, Panama"
544
+ and "Georgia, United States" resolve as before; a namesake region written
545
+ by its bare name with its country ("Panamá, Panama") no longer does.
546
+
547
+ The committed avocado run's focal scope opens "Mexico, especially the
548
+ Michoacán Avocado Belt" and ends "while Data México reports … US$3.525
549
+ billion". That last part used to read as the United States (from "US$"),
550
+ so the scope gave no region; since `resolve_country_code` ignores accents
551
+ (above), it reads Mexico, which made the scope the State of México. It now
552
+ gives no region, and the run's callers of the country and region resolvers
553
+ return what they did before this release's country changes. Tests +10
554
+ (suite 1,888).
555
+ - **The automatic map's text fallback follows the query's framing.** When the
556
+ map-data extraction fails or returns no focal country, `_generate_map`
557
+ reads the map from the analysis text, and its first attempt drew an ADM1
558
+ map whenever it could resolve a region there. A query about a country
559
+ ("Impact of avocado production and trade in Mexico on sustainability")
560
+ whose analysis gives the scope "Michoacán, Mexico" got a map of Michoacán,
561
+ while with map data the same query gets the country map. The attempt now
562
+ drops the region when the query names none, as the map-data path does and
563
+ as MANUAL §10 describes. A query that names a region ("Avocado production
564
+ in Michoacán, Mexico") still gets the ADM1 map, and so does a direct
565
+ `_generate_map` call made without a query. Tests +3 (suite 1,891).
566
+ - **A pericoupling validation note no longer calls the classification
567
+ consistent when its check classified no pair.** After each analysis the
568
+ country check and, when the research description names a subnational
569
+ region, the ADM1 check compare the classification (§1) with the pairs
570
+ they look up in the adjacency databases, and each writes a note. A check
571
+ that looked up no pair still noted that the classification was
572
+ consistent with its database. With Thailand as the sending system and
573
+ "Nigeria and China" as the spillover system, the country check skips
574
+ both partners, since spillover partners are not checked, and its note
575
+ read "LLM classification is consistent with the coupling database." An
576
+ analysis of acid rain from Ohio falling on Ontario that names Ontario
577
+ only in a system's name and scope, which the region scan skips, got two
578
+ notes that contradict each other under the default
579
+ `coupling_standard="moderate"`: the country check's "Ohio (USA036) ↔
580
+ Canada (CAN): TELECOUPLED … Consider revising." and the ADM1 check's
581
+ "LLM classification is consistent with the ADM1 pericoupling database.",
582
+ although it had classified no region (under `"lenient"` the two notes
583
+ agreed, and the ADM1 one was just as unchecked). A check that looked up
584
+ no pair now notes that nothing was checked: "No partner country was
585
+ checked against the coupling database (partners in the spillover role
586
+ are not checked)." or "No subnational region other than the focal region
587
+ was checked against the ADM1 pericoupling database." The report
588
+ (`result.formatted`) prints such a note only when it lists no pair, so it
589
+ never joins the line that calls the classification consistent with both
590
+ databases. The note of a check that looked up a pair is unchanged; MANUAL
591
+ §7 and §8 say when each note appears. On the 31 gpt-5.5 analyses saved on
592
+ 2026-10-15 and the committed avocado run, each validated under the three
593
+ coupling standards and both `de_facto_borders` settings (192 reports),
594
+ every check that looked up a pair keeps its note and 180 validation
595
+ blocks are byte-identical. The other 12 come from the two analyses of
596
+ Indonesia's coal exports to China and India, whose ADM1 check finds no
597
+ region besides East Kalimantan: their Note now reads "LLM classification
598
+ is consistent with the coupling database." instead of claiming
599
+ consistency with "the coupling databases (country adjacency + ADM1
600
+ adjacency)". Tests +35 (suite 2,104).
601
+ - **A flow whose heading names two categories gets the same category in
602
+ every run.** `parse_analysis` reads a flow's category from its heading
603
+ (`**Matter Flow**`), its bracket tag (`[Matter]`), its `category:` field
604
+ or, failing those, the bullet itself. The six category names were kept in
605
+ a set and the first one found in the set's order won, so when the text
606
+ named two, the category depended on the hash seed, which Python draws
607
+ anew for each process unless `PYTHONHASHSEED` is set. In one of the 31
608
+ gpt-5.5 analyses saved on 2026-10-15 (Germany's electricity imports from
609
+ France and Poland and LNG from the USA), the flow headed
610
+ `**Energy and Matter Flow**` was energy under 11 of 16 seeds and matter
611
+ under the other 5. The category labels the flow in the report
612
+ (`[Energy]`), files it under the Markdown and Word exports' per-category
613
+ Flows subsections, colours its arrow on maps drawn from the parsed flows
614
+ and enters the map-extraction prompt. A category's own name now counts
615
+ before a word that only suggests one (goods, money, power …), and among
616
+ several the one the text names first wins: "Energy and Matter Flow" is
617
+ energy, "Matter and Energy Flow" matter. Among the words that only
618
+ suggest a category, the first named also wins where the alias table's
619
+ order decided before ("Labour and money" was capital and is now people).
620
+ On the 31 analyses and the committed avocado run (531 flows, all under
621
+ bold headings), each parsed under 16 seeds, every parse is now the same
622
+ under all 16 and matches the old parse field for field, except that one
623
+ flow under the 5 seeds that read it as matter; none of the 16 distinct
624
+ flow headings names two categories through such words alone. Tests +13
625
+ (suite 2,117).
626
+ - **The prompt's ADM1 hint names a region the description writes, not one
627
+ that a common word or another place's name happens to match.**
628
+ `PromptBuilder._build_adm1_pericoupling_hint` took as the focal region the
629
+ first run of up to five words that `resolve_adm1_code` resolved, in any
630
+ case and without a country, and listed that region's neighbours. Common
631
+ words, pieces of country names and the names of lakes, rivers and bays
632
+ matched regions elsewhere: "has" gave Has (Albania), "forest" Forest
633
+ (Guernsey), "New Zealand" Zealand (Denmark), "Guinea-Bissau" the Sector
634
+ Autonomo De Bissau, "Mutsu Bay" Bay (Somalia), "Okavango Delta" Delta
635
+ (Nigeria), "Lake Tanganyika" Tanganyika province (DR Congo), "Mary River
636
+ mine" Mary (Turkmenistan) and "Southeast Alaska" Southeast (North
637
+ Macedonia); Ghana's "Western Region" gave Bahrain's, and a town, "Santa
638
+ Rosa", in a description of Ecuador gave Guatemala's department. As the
639
+ ADM1 hint takes the place of the country hint, such a match also dropped
640
+ the country-pair reference. A run of words now names a region only when it
641
+ is written as a name (capitalised, with lower-case connectors such as "do"
642
+ or "es" inside and a unit word such as "oblast" at the end), is not part of
643
+ a country's name or of a feature's ("Ohio River", "Lake Tanganyika", "Gulf
644
+ of California"), and, for a lone compass or feature word ("Bay", "West",
645
+ "Delta"), when the text names the region's country. A name several regions
646
+ share is read in the countries the text names, then in those of the other
647
+ regions it names ("Central Region" in Ghana, "Punjab" beside Kerala), and
648
+ Vietnamese letters are read ("Bình Phước"). The focal region is the first
649
+ one named whose country the text names, another named region shares, or
650
+ borders one of those, so a region of an unrelated country, usually a
651
+ namesake, is passed over. A country's name that a region elsewhere also
652
+ has is read as the one the rest of the text supports more: "Georgia" is the
653
+ US state in "Georgia, United States" or beside Alabama or Florida (which
654
+ Uruguay also has), and the country beside Tbilisi, Russia or Armenia;
655
+ "Gaza" is Mozambique's province beside Maputo and Palestine beside Egypt. A
656
+ tie keeps the country, and the country hint leaves out a name read as a
657
+ region: until now "Georgia, United States" got the hint for the country
658
+ Georgia. On 200 research descriptions with known focal units, the hint
659
+ names the right region for 116 of the 127 about a province (99 before), a
660
+ wrong one for 9 (26) and none for 2 (2), England and Scotland, which are
661
+ read as the United Kingdom; the 9 are regions the text names before its
662
+ focal one (Bogotá before Cundinamarca). Of the 73 descriptions about a
663
+ country or another place, 33 get a regional hint (47 before), each for a
664
+ region the text names. Tests +25 (suite 2,142).
665
+ - **A country's name that a region elsewhere also has is read as the run
666
+ reads it, in the validation, the report and the maps.** The prompt hint
667
+ read "Georgia" as the US state where the description supported it, but
668
+ the rest of a run resolved each system name on its own, so "Georgia" was
669
+ always the country. For a description of broiler chicken production in
670
+ Georgia, United States, with an answer naming Georgia, Alabama, Iowa and
671
+ China, the country check took Georgia (GEO) as the focal country and
672
+ checked Georgia (GEO) ↔ China, the ADM1 check checked nothing, and a map
673
+ drawn from the analysis centred on the Caucasus. Inside a
674
+ `knowledge.countries.read_names_as_regions(readings)` block, each name in
675
+ *readings* now reads as a region elsewhere: `resolve_country_code` and
676
+ `find_country_codes` give the region's country, `resolve_adm1_code` the
677
+ region; outside a block nothing changes. `knowledge.places.place_readings`
678
+ gives those readings for a text by the hint's rule, and `read_places`,
679
+ which moved there from the prompt builder, the countries and regions the
680
+ text names. `MetacouplingAssistant` builds each result inside a block read
681
+ from the research description and the answer and runs web search inside
682
+ one read from the description, and `plot_analysis_map` called on its own
683
+ reads the analysis's text. In the example the country check now takes the
684
+ United States as the focal country, the ADM1 check takes Georgia (USA011),
685
+ with Alabama pericoupled and Iowa telecoupled, and the map's focal country
686
+ is the United States; a description of wine exports from Georgia to Russia
687
+ keeps the country. Built through `analyze()` with a stub client, the
688
+ reports of the 31 gpt-5.5 analyses saved on 2026-10-15 and of the
689
+ committed avocado run are byte-identical to main's: none names such a
690
+ country. Tests +14 (suite 2,156).
691
+ - **The Claude adapter works with anthropic 2.x.** anthropic 2.0.0
692
+ (2026-10-21) targets API version 2026-10-21, which removed `temperature`,
693
+ `top_p` and `top_k`: a request that sends one gets a 400 on every model,
694
+ and the SDK's `messages.create` and `messages.stream` no longer take them.
695
+ `AnthropicAdapter` sent `temperature` for every model but
696
+ `claude-opus-4-7`, so with anthropic 2.x every `chat` call raised
697
+ `TypeError`. The adapter now sends `temperature` only when the installed
698
+ SDK's `messages.create` takes it, and never for Claude 4.7 and later
699
+ models, which accept only the default under the older API version as
700
+ well (`claude-opus-4-8` and the Claude 5 models join `claude-opus-4-7`).
701
+ With anthropic 2.x a Claude request samples at the API's defaults
702
+ (temperature 1.0), so `temperature=` has no effect on Claude. The
703
+ web-search backend never sent `temperature` and was not affected. The
704
+ other Anthropic tests use stand-in clients, so none of them noticed; new
705
+ tests drive the adapter and the web-search backend through the installed
706
+ SDK over a mock HTTP transport (no network, no key), and they fail on the
707
+ old adapter with anthropic 2.3.0. Tests +10 (suite 2,166).
708
+ - **Two copies of the package no longer clash over the paper cache.**
709
+ Every copy on a machine (a checkout, a worktree, an installed wheel)
710
+ extracts the bundled `Papers.zip` into `<tempdir>/metacoupling_rag_cache`.
711
+ The extraction counted as current only while its stamp matched the zip's
712
+ mtime, and each copy's zip has its own, so a second copy deleted the
713
+ folder and extracted it again in place, under any copy reading it. In a
714
+ fresh venv run beside a test suite, the RAG engine found 324 of the 421
715
+ papers (8,193 chunks), so the precomputed embeddings no longer matched
716
+ and it fell back to TF-IDF. The extraction now goes to a folder named
717
+ after the zip's SHA-256, so copies whose zips have the same contents
718
+ share it and a different zip gets its own; a new extraction is written
719
+ to a private staging folder and renamed into place only when complete,
720
+ and when another process gets there first, its folder is used. A folder
721
+ that has lost files is replaced, not repaired in place. The `Papers`
722
+ folder and stamp of earlier versions are left alone, so an older install
723
+ keeps working beside a new one. Tests +6 (suite 2,172).
724
+
725
+ ### Docs
726
+
727
+ - **`plot_analysis_map`'s docstring documents `mentioned_countries_override`
728
+ and `focal_code_override`.** The two work only together: given both, the
729
+ map's focal country and colored countries are the ISO codes passed, used
730
+ as given, instead of those found in the parsed analysis, and `focal_role`
731
+ and `extra_mentioned_countries` are ignored; the automatic map passes both.
732
+ The docstring also gives the default title as
733
+ `"Metacoupling Analysis Map: {Country Name}"`, not
734
+ `"Metacoupling Analysis Map"`. No code change.
735
+
10
736
  ## [0.2.1] — 2026-10-12
11
737
 
12
738
  A maintenance release after the documentation audit of 0.2.0.