MetacouplingLLM 0.2.2__tar.gz → 0.3.0__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 (187) hide show
  1. metacouplingllm-0.3.0/.gitattributes +3 -0
  2. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/CHANGELOG.md +436 -0
  3. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/INTRODUCTION.md +11 -8
  4. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/MANUAL.md +292 -101
  5. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/PKG-INFO +12 -9
  6. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/README.md +12 -1
  7. metacouplingllm-0.3.0/build_data/marine_regions/README.md +23 -0
  8. metacouplingllm-0.3.0/build_data/marine_regions/mr_eez_boundaries_v12.csv +2350 -0
  9. metacouplingllm-0.3.0/build_data/marine_regions/mr_eez_v12.csv +286 -0
  10. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/docs/BRIDGE_CLASSIFICATION_METHODOLOGY.md +2 -0
  11. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/docs/METHODS_adjacency.md +106 -8
  12. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/docs/REPRODUCING.md +50 -6
  13. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/docs/VALIDATION_STUDY.md +1 -1
  14. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/examples/fishing_eez/00_build_edge_table.py +55 -32
  15. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/examples/fishing_eez/01_build_region_map.py +24 -9
  16. metacouplingllm-0.3.0/examples/fishing_eez/02_compute_indicators.py +135 -0
  17. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/examples/fishing_eez/03_analysis.py +47 -54
  18. metacouplingllm-0.3.0/examples/fishing_eez/README.md +241 -0
  19. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/examples/fishing_eez/data/eez_region.json +8 -8
  20. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/examples/fishing_eez/data/fishing_edge_table.csv +1 -6
  21. metacouplingllm-0.3.0/examples/fishing_eez/data/sau_country_codes.csv +334 -0
  22. metacouplingllm-0.3.0/examples/fishing_eez/outputs/carlson_comparison.csv +8 -0
  23. metacouplingllm-0.3.0/examples/fishing_eez/outputs/classified_edges.csv +5765 -0
  24. metacouplingllm-0.3.0/examples/fishing_eez/outputs/global_totals.csv +13 -0
  25. metacouplingllm-0.3.0/examples/fishing_eez/outputs/indicators_by_eez.csv +281 -0
  26. metacouplingllm-0.3.0/examples/fishing_eez/outputs/regional_catch.csv +12 -0
  27. metacouplingllm-0.3.0/examples/fishing_eez/outputs/regional_indicators.csv +12 -0
  28. metacouplingllm-0.3.0/examples/fishing_eez/outputs/telecoupled_share_timeseries.csv +66 -0
  29. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/pyproject.toml +1 -1
  30. metacouplingllm-0.3.0/scripts/build_maritime_adjacency.py +229 -0
  31. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/trace_pipeline.py +21 -8
  32. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/__init__.py +1 -1
  33. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/core.py +510 -99
  34. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/data/PROVENANCE.md +61 -2
  35. metacouplingllm-0.3.0/src/metacouplingllm/data/maritime_adjacency_pairs.csv +388 -0
  36. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/indicators/_prompts.py +2 -2
  37. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/indicators/adjacency.py +11 -1
  38. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/indicators/core.py +6 -7
  39. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/knowledge/adm1_pericoupling.py +4 -4
  40. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/knowledge/countries.py +160 -1
  41. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/knowledge/pericoupling.py +80 -14
  42. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/knowledge/websearch.py +29 -7
  43. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/llm/client.py +154 -1
  44. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/output/export.py +11 -2
  45. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/prompts/builder.py +51 -9
  46. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/tracing.py +8 -1
  47. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/visualization/__init__.py +7 -3
  48. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/visualization/adm1_map.py +1 -1
  49. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/visualization/worldmap.py +80 -60
  50. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_adjacency_settings.py +23 -15
  51. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_adm1_name_matching_regression.py +13 -5
  52. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_adm1_pericoupling.py +3 -3
  53. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_core.py +1100 -7
  54. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_countries.py +131 -0
  55. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_docs_examples.py +34 -4
  56. metacouplingllm-0.3.0/tests/test_gpt6_reasoning.py +339 -0
  57. metacouplingllm-0.3.0/tests/test_maritime_adjacency.py +327 -0
  58. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_output.py +28 -0
  59. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_pericoupling.py +4 -4
  60. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_validation_notes.py +446 -29
  61. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_worldmap.py +148 -0
  62. metacouplingllm-0.2.2/examples/fishing_eez/02_compute_indicators.py +0 -60
  63. metacouplingllm-0.2.2/examples/fishing_eez/README.md +0 -160
  64. metacouplingllm-0.2.2/examples/fishing_eez/outputs/global_totals.csv +0 -10
  65. metacouplingllm-0.2.2/examples/fishing_eez/outputs/indicators_by_eez.csv +0 -281
  66. metacouplingllm-0.2.2/examples/fishing_eez/outputs/regional_catch.csv +0 -12
  67. metacouplingllm-0.2.2/examples/fishing_eez/outputs/regional_indicators.csv +0 -12
  68. metacouplingllm-0.2.2/examples/fishing_eez/outputs/telecoupled_share_timeseries.csv +0 -66
  69. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/.github/workflows/test.yml +0 -0
  70. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/.gitignore +0 -0
  71. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/LICENSE +0 -0
  72. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/build_data/arc_and_combined_screens/SPEC_ba1_border_arc_and_screens.md +0 -0
  73. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/build_data/build_record/relabel_RESULTS.md +0 -0
  74. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/build_data/geodesic_distances/SPEC_gd1_geodesic_distances.md +0 -0
  75. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/build_data/ndlsa_ne/SPEC_da1_defacto_administrators.md +0 -0
  76. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/build_data/stage_order/SPEC_st1_stages.md +0 -0
  77. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/build_data/water_screen_rebuild/corridor_census_exact/SPEC_cc1_corridor_census.md +0 -0
  78. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/build_data/water_screen_rebuild/crossing_adjudication/SPEC_ca1_crossing_adjudication.md +0 -0
  79. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/build_data/water_screen_rebuild/crossing_width/SPEC_cw1_crossing_width.md +0 -0
  80. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/build_data/water_screen_rebuild/july_rejections/SPEC_jr1_july_rejections.md +0 -0
  81. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/build_data/water_screen_rebuild/rule_rejections/SPEC_mr1_rule_rejections.md +0 -0
  82. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/build_data/water_screen_rebuild/uniform_acceptance/SPEC_ua1_uniform_acceptance.md +0 -0
  83. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/docs/FUTURE_EDGE_AUDITS.md +0 -0
  84. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/docs/FUTURE_WORK.md +0 -0
  85. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/docs/VALIDATION_SAMPLING_PLAN.md +0 -0
  86. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/docs/adm1_aliases_audit.csv +0 -0
  87. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/docs/ndlsa_tract_audit.csv +0 -0
  88. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/examples/brazil_soybean_adjacency.csv +0 -0
  89. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/examples/brazil_soybean_flows.csv +0 -0
  90. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/examples/fishing_eez/.gitignore +0 -0
  91. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/examples/fishing_eez/data/s16_country_region.json +0 -0
  92. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/examples/fishing_eez/run_all.py +0 -0
  93. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/apply_check_keywords.py +0 -0
  94. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/apply_overlays.py +0 -0
  95. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/audit_unreplaced.py +0 -0
  96. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/build_adm1_aliases.py +0 -0
  97. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/build_all.py +0 -0
  98. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/build_embeddings.py +0 -0
  99. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/build_paper_metadata_table.py +0 -0
  100. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/build_pericoupling_db.py +0 -0
  101. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/build_rag.py +0 -0
  102. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/check_no_stale_metacoupling.py +0 -0
  103. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/check_oa_status.py +0 -0
  104. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/copyright_audit.py +0 -0
  105. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/diagnose_anthropic_web_search.py +0 -0
  106. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/draw_validation_sample.py +0 -0
  107. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/extract_keywords.py +0 -0
  108. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/integrate_keywords.py +0 -0
  109. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/match_references.py +0 -0
  110. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/organize_pdfs.py +0 -0
  111. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/organize_pdfs_v2.py +0 -0
  112. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/organize_pdfs_v3.py +0 -0
  113. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/patch_doi_inventory.py +0 -0
  114. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/rebuild_rag_corpus.py +0 -0
  115. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/regenerate_paper_metadata.py +0 -0
  116. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/relabel_sliver_corridors.py +0 -0
  117. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/strategy_b_decision.py +0 -0
  118. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/validate_adm1_aliases.py +0 -0
  119. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/scripts/verify_papers_vs_bib.py +0 -0
  120. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/data/Papers.zip +0 -0
  121. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/data/PeriTelecoupling_clean.csv +0 -0
  122. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/data/PeriTelecoupling_subset.csv +0 -0
  123. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/data/adm1_aliases.csv +0 -0
  124. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/data/chunk_embeddings.manifest.json +0 -0
  125. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/data/chunk_embeddings.npy +0 -0
  126. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/data/denylist_pairs.csv +0 -0
  127. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/data/disputed_overlay_pairs.csv +0 -0
  128. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/data/land_gap_overlay_pairs.csv +0 -0
  129. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/data/pericoupled_adm1_edge_list.csv +0 -0
  130. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/data/sliver_corridor_relabel.csv +0 -0
  131. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/data/telecoupling_literature.bib +0 -0
  132. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/data/water_classification_pairs.csv +0 -0
  133. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/data/water_separated_pairs.csv +0 -0
  134. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/indicators/__init__.py +0 -0
  135. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/indicators/_math.py +0 -0
  136. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/indicators/_schemas.py +0 -0
  137. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/indicators/classify.py +0 -0
  138. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/indicators/llm.py +0 -0
  139. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/knowledge/__init__.py +0 -0
  140. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/knowledge/citations.py +0 -0
  141. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/knowledge/examples.py +0 -0
  142. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/knowledge/framework.py +0 -0
  143. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/knowledge/literature.py +0 -0
  144. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/knowledge/places.py +0 -0
  145. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/knowledge/rag.py +0 -0
  146. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/knowledge/references.py +0 -0
  147. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/llm/__init__.py +0 -0
  148. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/llm/parser.py +0 -0
  149. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/output/__init__.py +0 -0
  150. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/output/formatter.py +0 -0
  151. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/prompts/__init__.py +0 -0
  152. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/src/metacouplingllm/prompts/templates.py +0 -0
  153. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/__init__.py +0 -0
  154. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/_helpers.py +0 -0
  155. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/conftest.py +0 -0
  156. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/data/adm1_resolve_golden.json +0 -0
  157. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/data/avocado_main_analysis_response.md +0 -0
  158. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_adm1_map.py +0 -0
  159. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_anthropic_sdk.py +0 -0
  160. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_apply_overlays.py +0 -0
  161. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_build_pericoupling_db.py +0 -0
  162. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_builder.py +0 -0
  163. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_citations.py +0 -0
  164. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_client.py +0 -0
  165. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_coupling_first.py +0 -0
  166. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_data_csvs.py +0 -0
  167. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_docs_capabilities.py +0 -0
  168. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_examples.py +0 -0
  169. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_formatter.py +0 -0
  170. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_framework.py +0 -0
  171. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_gemini_grok_support.py +0 -0
  172. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_indicators.py +0 -0
  173. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_indicators_llm.py +0 -0
  174. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_integration.py +0 -0
  175. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_literature.py +0 -0
  176. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_openai_integration.py +0 -0
  177. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_parser.py +0 -0
  178. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_place_readings.py +0 -0
  179. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_rag.py +0 -0
  180. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_rag_only_mode.py +0 -0
  181. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_rag_pipeline.py +0 -0
  182. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_relabel_sliver_corridors.py +0 -0
  183. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_structured_extraction.py +0 -0
  184. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_templates.py +0 -0
  185. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_tracing.py +0 -0
  186. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_visualization_wrappers.py +0 -0
  187. {metacouplingllm-0.2.2 → metacouplingllm-0.3.0}/tests/test_websearch.py +0 -0
@@ -0,0 +1,3 @@
1
+ # The Marine Regions input tables are pinned by SHA-256 (scripts/build_maritime_adjacency.py):
2
+ # keep their bytes exact, with no line-ending conversion on any platform.
3
+ build_data/marine_regions/*.csv -text
@@ -7,6 +7,442 @@ file. The format is loosely based on
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.3.0] — 2026-11-18
11
+
12
+ A feature release: countries can be adjacent at sea, every administrative
13
+ border counts as adjacency by default, OpenAI models reason at a chosen
14
+ effort, and the validation block, the automatic map and the printed report
15
+ follow the analysis more closely. The default `coupling_standard` changes
16
+ from `"moderate"` to `"lenient"`; no documented API is removed or renamed.
17
+
18
+ Highlights:
19
+
20
+ - **Maritime adjacency for countries**: with `maritime_adjacency=True`
21
+ (default `False`), two countries are also adjacent when their waters
22
+ share a boundary in the Marine Regions Maritime Boundaries Geodatabase
23
+ (version 12; CC BY 4.0): 387 country pairs, 257 of them not adjacent on
24
+ land. The country lookups and maps, `build_adjacency(level="adm0")`, the
25
+ prompt hint and the validation block take the toggle, and the hint and
26
+ the block say when a pair is adjacent only at sea.
27
+ - **Every administrative border counts by default**: the default
28
+ `coupling_standard` is `"lenient"`, so units that meet only across a
29
+ river or lake are pericoupled whether or not a bridge links them, and
30
+ the default views are the full databases (8,462 ADM1 pairs and 326
31
+ country pairs; 8,026 and 321 under the former `"moderate"` default).
32
+ `"moderate"` and `"stringent"` are unchanged.
33
+ - **OpenAI reasoning effort and GPT-6 models**:
34
+ `OpenAIAdapter(..., reasoning_effort=...)` sets the effort of every call,
35
+ native web search included, through the Responses API, which takes
36
+ gpt-6.1-sol's `"max"`; these requests run in background mode, so the
37
+ SDK's 10-minute read timeout does not cut off a long one. Run traces
38
+ record the effort and the adjacency settings.
39
+ - **The validation block follows the analysis**: it anchors on the focal
40
+ system's country, names a partner placed only in the coupling section
41
+ its database verdict contradicts, compares its verdicts with the
42
+ coupling sections the analysis holds (in the country and the ADM1
43
+ notes), finds a bloc named before a spaced dash, says when it finds no
44
+ country besides the focal one, and reads the adjectives of small states
45
+ ("Sri Lankan", "Bahamian", "Fijian").
46
+ - **The automatic map draws what the analysis says**: the map-data
47
+ extraction reads every system and flow (it kept the first two systems
48
+ of each role and the first eight flows), a flow from a supranational
49
+ bloc such as the EU's payments to Indonesia is drawn, and the map
50
+ follows the analysis's focal country and partners.
51
+ - **Inline web markers are the model's own citations**: the printed report
52
+ no longer adds a web source's marker to lines that only share keywords
53
+ with its summary.
54
+ - **Examples and documentation**: the committed example run is an
55
+ Indonesian palm-oil analysis by gpt-6.1-sol at `"max"` effort under the
56
+ lenient standard; the fishing example labels every flow with the
57
+ package's country database (Carlson et al.'s label for 97.3% of their
58
+ adjacent and distant flows) and places all 280 EEZs in a region; MANUAL
59
+ §16 writes the indicator formulas in the paper's notation.
60
+
61
+ ### Added
62
+
63
+ - **The validation block names a partner placed in the wrong coupling
64
+ section.** The country check compared coupling types only: it warned
65
+ when the database found an adjacent partner but the analysis had no
66
+ pericoupling section, or found only distant partners but the analysis
67
+ had no telecoupling section. A partner in the wrong section passed
68
+ whenever the other section existed, so an Indonesia analysis naming
69
+ India only under telecoupling, with Malaysia under pericoupling, was
70
+ reported consistent. The check now also reads which sections' systems
71
+ (spillover systems aside) name each partner country or bloc. A partner
72
+ named only in the section its database verdict contradicts gets a
73
+ sentence in the Note, after the coupling-type warning when that fires
74
+ too, and the Note ends with "Consider revising.": "The analysis places
75
+ Indonesia (IDN) ↔ India (IND) (at sea) only in its telecoupling
76
+ section, but the database classifies the pair as pericoupled." A
77
+ partner named in both sections is not judged, and the
78
+ subnational check, which finds regions anywhere in the text, still
79
+ compares coupling types only. Across 60 saved analyses (29 traced runs
80
+ and 31 A/B examples) the check reads 171 partners: 166 are named only
81
+ in the section their verdict implies, 5 in both sections and none only
82
+ in the other one, so no Note changes. Eight new tests (suite
83
+ 2,336).
84
+ - **`OpenAIAdapter(..., reasoning_effort=...)` and GPT-6 models.** The
85
+ effort applies to every call the assistant makes, its native OpenAI web
86
+ search included. With an effort, the adapter sends its requests through
87
+ the Responses API, which takes every effort a model offers: Chat
88
+ Completions accepts gpt-6.1-sol's efforts only up to `"xhigh"`, Responses
89
+ takes `"max"`. While a model reasons, no `temperature` is sent (the API
90
+ rejects it), and none of the package's output limits, which are sized
91
+ for the visible answer (8,192 tokens for the structured web extraction
92
+ and the map extraction, 4,096 for the abstract, 1,000 per web result
93
+ with a 12,000 floor): OpenAI counts reasoning tokens against them, so
94
+ the model's own maximum applies (128,000 tokens for gpt-6.1-sol). From
95
+ `"high"` effort up, the web search sets `return_token_budget` to
96
+ `"unlimited"`, as OpenAI's web search guide advises for high-effort
97
+ research that reads many pages, and a response that ends incomplete is
98
+ logged as a warning.
99
+ These requests, the web search's included, run in OpenAI's background
100
+ mode, polled until they finish, so a long one (a `"max"` effort, a
101
+ 25-result web search) is not cut off by the openai SDK's 10-minute read
102
+ timeout, which resends the whole request; a response that fails on a
103
+ rate limit is retried, since the SDK's own retries see only HTTP 429s,
104
+ and an interrupted wait cancels the response. Without an effort, Chat Completions is used as before;
105
+ GPT-6 models, which reason by default, get neither `temperature` nor a
106
+ cap there, and their web search sends no ceiling. Run traces
107
+ record the reasoning effort and the adjacency settings
108
+ (`de_facto_borders`, `coupling_standard`, `maritime_adjacency`), and
109
+ `scripts/trace_pipeline.py` takes the effort and the adjacency settings as
110
+ constants. Twenty-five new tests in `tests/test_gpt6_reasoning.py`, and
111
+ the docs check compiles one more MANUAL example (suite 2,300).
112
+ - **Maritime adjacency for countries (`maritime_adjacency`, default
113
+ `False`).** The country lookups (`lookup_pericoupling`, `is_pericoupled`,
114
+ `get_pericoupled_neighbors`), the two country map functions,
115
+ `build_adjacency(level="adm0")`, `PromptBuilder` and
116
+ `MetacouplingAssistant` (its country hint, country validation and country
117
+ map) take a new toggle: with `True`, two countries are also adjacent when
118
+ their waters share a maritime boundary in the Maritime Boundaries
119
+ Geodatabase of the Flanders Marine Institute (Marine Regions, version 12;
120
+ CC BY 4.0). The new table `data/maritime_adjacency_pairs.csv` holds 387
121
+ country pairs, 257 of them not adjacent on land, so the default country
122
+ view grows from 326 to 583 pairs (578 with `de_facto_borders=False`,
123
+ which drops the three pairs joined only through a disputed tract's
124
+ waters). Every boundary line counts, whatever its legal status; an area
125
+ that several countries claim, or manage jointly, borders each of them;
126
+ territories count as the units of the ADM0 database (a claim coded by its
127
+ claimant's country as the unit the World Bank draws the claimed island
128
+ in), and disputed tracts as the administrators the land database assigns
129
+ them. The default is
130
+ `False` because most metacoupling studies define adjacency on land. With
131
+ it on, the prompt hint and the validation block say when a pair is
132
+ adjacent only at sea ("adjacent at sea: their waters share a maritime
133
+ boundary" in the hint, "(at sea)" after a neighbour or partner). The
134
+ ADM1 functions do not take the toggle, and
135
+ `build_adjacency(level="adm1", maritime_adjacency=True)` raises a
136
+ `ValueError`. Built by `scripts/build_maritime_adjacency.py` from two
137
+ SHA-256-pinned attribute tables, which ship unmodified in
138
+ `build_data/marine_regions/` (`.gitattributes` keeps their bytes exact),
139
+ so `python scripts/build_maritime_adjacency.py --check` reproduces the
140
+ table offline; see `docs/METHODS_adjacency.md` §11.
141
+ New tests in `tests/test_maritime_adjacency.py` (suite 2,198).
142
+
143
+ ### Changed
144
+
145
+ - **The MANUAL writes the indicator formulas in the paper's notation.**
146
+ §16 put the coupling type in a subscript (`F_{ic}`, `HHI_{ic}`,
147
+ `n_{ic}`) everywhere except the partner flow `f_{ij}^{c}`, and wrote MFE
148
+ with shares `s_c` that it defined only as one of IFS, PFS and TFS. It now
149
+ puts the type in a superscript throughout, as the paper does (`F_i^c`,
150
+ `HHI_i^c`, `MFCI_i^c`, `ENP_i^c`, `n_i^c`), defines the flow share
151
+ `MFS_i^c = F_i^c / F_i` with `IFS_i = MFS_i^I` and so on, names the
152
+ coupling types I, P and T, maps the symbols to the output columns, and
153
+ states that ENP, like MFCI, is NaN when a coupling type has no flow. The
154
+ flow-share and MFCI docstrings in `indicators/core.py` and the indicator
155
+ helper's prompt use the same symbols. On GitHub the MFE sum also lost
156
+ its braces and showed commas for its thin spaces, because Markdown
157
+ removes a backslash before punctuation such as `{` or `,` before the math
158
+ is rendered; the set is now written with `\lbrace` and `\rbrace`. GitHub
159
+ also left `type-$c$` unrendered, dollar signs included, because math
160
+ that follows a hyphen is not recognised; it now reads `type-*c*`. No
161
+ computed value changes.
162
+ - **The printed report's inline web markers are the model's own
163
+ citations.** `result.formatted` also received markers from
164
+ `annotate_web_citations`, which appends a web source's `[T1:Wn]` to any
165
+ line sharing at least three keywords with the source's title and summary,
166
+ if they make up at least a quarter of the line's keywords, without
167
+ reading what the line claims. In the committed Indonesia run it added 435
168
+ of the 493 web markers in the report body: 22 on one heading, "Indonesia —
169
+ palm oil", and every marker of the five sources the model did not cite,
170
+ none of whose findings the analysis uses. The report no longer calls it.
171
+ Replayed through the pipeline, that run's recorded response now gives the
172
+ report body the model's 58 markers, citing 20 of the 25 sources, and the
173
+ `WEB SOURCES` block still lists all 25. The Markdown and Word exports read
174
+ the parsed analysis and never carried the added markers.
175
+ `annotate_web_citations` stays exported. New test in `tests/test_core.py`
176
+ (suite 2,337).
177
+ - **The fishing example places all 280 EEZs in a region.** Its regions come
178
+ from Carlson et al.'s Table S16, which lists only the 168 nations with World
179
+ Bank GDP values because it held their GDP correlations. Four EEZs whose
180
+ nation it lacks (27.11 Mt, 0.47% of the catch) therefore had no region and
181
+ were left out of the regional tables, the paper's Tables 4 and 5, although
182
+ the tables use none of the GDP values. `01_build_region_map.py` now places
183
+ them the way the example places other EEZs: an overseas territory takes its
184
+ administering country's region, the others the region of their location.
185
+ Asia, Africa (West), Oceania and Europe (North) each gain one EEZ. Table 4's
186
+ totals and shares change for those four regions; at two decimals, six cells
187
+ of Table 5 change (Asia's PFCI, TFCI and ENP_T, Africa (West)'s ENP_T,
188
+ Oceania's TFCI and ENP_T), while IFS, PFS, TFS and MFE and the order of the
189
+ regions stay the same.
190
+ - **The committed example run uses the lenient coupling standard and the
191
+ map extraction that reads the whole analysis.**
192
+ `runs/indonesia_palm_oil_2026-11-16_gpt-6.1-sol_max_lenient_full-extraction/`
193
+ replaces `runs/indonesia_palm_oil_2026-11-14_gpt-6.1-sol_max_builtin-trace/`
194
+ (kept in git history) as the run the paper describes, and
195
+ `scripts/trace_pipeline.py` sets `coupling_standard="lenient"`, the
196
+ package default. The query, model, effort and every other setting are
197
+ unchanged. The run's trace records commit b7f2eff, where the map-data
198
+ extraction already received every system and flow of the analysis: 8 of
199
+ 8 sending systems, 8 of 8 receiving systems and 15 of 15 flows. Its map
200
+ draws 18 arrows, the exports, payments and information flows between
201
+ Indonesia and India, China, the European Union, the United States,
202
+ Pakistan and Switzerland, among them the EU's payments to Indonesia.
203
+ The replaced run's map had 13 arrows and no information flows. The
204
+ coupling standard changes nothing for Indonesia, which has the same 11
205
+ neighbours under all three standards; the different partners come from
206
+ the model's sampling and the live web search.
207
+ - **The committed example run is an Indonesian palm-oil analysis by
208
+ gpt-6.1-sol at `"max"` reasoning effort.**
209
+ `runs/indonesia_palm_oil_2026-11-14_gpt-6.1-sol_max_builtin-trace/`
210
+ replaces `runs/avocado_2026-06-16_gpt-5.5_builtin-trace/` (kept in git
211
+ history) as the run the paper describes. It answers "Impact of palm oil
212
+ production and exports in Indonesia on sustainability" with sea borders
213
+ (`maritime_adjacency=True`), de facto borders and the `"moderate"`
214
+ coupling standard, and its trace records commit 6a46d75.
215
+ `scripts/trace_pipeline.py` now runs that query with that model, effort
216
+ and adjacency settings.
217
+ - **The default `coupling_standard` is `"lenient"`: every administrative
218
+ border counts as adjacency.** Units that meet only across a river or lake
219
+ are now pericoupled under the default settings whether or not a bridge
220
+ links them, so the default views are the full databases: 8,462 ADM1 pairs
221
+ and 326 country pairs (8,026 and 321 under the former `"moderate"`
222
+ default). Whether a fixed crossing exists does not reflect how connected
223
+ the two sides of a river or lake are, so the crossing rule is no longer
224
+ applied by default. `"moderate"` (a water-only pair needs a completed fixed
225
+ crossing) and `"stringent"` (no water-only pair counts) are unchanged; pass
226
+ either to `MetacouplingAssistant`, `PromptBuilder`, the lookups, the map
227
+ functions or `build_adjacency`. Kinshasa and Brazzaville, DR Congo and the
228
+ Central African Republic, and Ohio and Ontario across Lake Erie are now
229
+ pericoupled by default, so the prompt hint, the validation block and the
230
+ automatic map treat them as neighbours. Tests follow the new default
231
+ (suite 2,172).
232
+ - **The fishing example labels every flow with the package's country
233
+ database.** `examples/fishing_eez/` took its intracoupled, pericoupled and
234
+ telecoupled labels from the tables of Carlson et al. (2020). Step 02 now
235
+ gives each EEZ and fishing nation its country (`data/sau_country_codes.csv`)
236
+ and labels each flow with `build_adjacency(level="adm0",
237
+ maritime_adjacency=True)` and `classify_coupling`, counting borders on land
238
+ and at sea. The database gives Carlson's label to 97.3% of their 5,486
239
+ adjacent and distant flows, holding 97.4% of their catch
240
+ (`outputs/carlson_comparison.csv`). Tables 4 and 5, the global figures and
241
+ the yearly series are recomputed: the own and adjacent share of the catch
242
+ is 88.4% (88.1% with Carlson's labels), and the telecoupled share peaks at
243
+ 0.203 in 1972 (0.216). The parser also leaves out five 2013 rows of Table
244
+ S8's Clipperton Island block, which hold a number where the fishing
245
+ nation's name belongs (2,315 t); they had entered the edge table as five
246
+ fishing nations named by numbers.
247
+
248
+ ### Fixed
249
+
250
+ - **The validation block finds a bloc named before a spaced dash.**
251
+ Analyses name a system as "European Union — palm products"; the bloc
252
+ detector behind the block's bloc line split names only at commas,
253
+ semicolons, slashes, parentheses, "and" and arrows, so an analysis
254
+ that names the EU only that way got no "↔ European Union" line. A dash
255
+ with spaces around it (—, – or -) now splits the name too; a hyphen
256
+ inside a word ("non-EU") does not. Four new tests (suite 2,328).
257
+ - **The map-data extraction reads every system and flow of the
258
+ analysis.** Its summary of the analysis kept only the first two
259
+ systems of each role and the first eight flows. An analysis lists its
260
+ intracoupling and pericoupling systems and flows before its
261
+ telecoupling ones, so the distant partners never reached the call: in
262
+ the committed Indonesia run it saw 2 of 9 sending systems, 2 of 9
263
+ receiving systems and 8 of 13 flows, none of them telecoupling. That
264
+ summary named none of China, Pakistan, Bangladesh and the United
265
+ States, and the EU only once, in the Malaysia spillover system's text,
266
+ so the map's arrows to those partners rested on the web-result
267
+ summaries, and the telecoupling information flow from foreign
268
+ policymakers and buyers to Indonesian agencies and suppliers was never
269
+ seen. The summary now sends every system and flow, each still capped
270
+ in length (800 characters per system, 500 per flow description); for
271
+ that run's analysis the call's request, not counting the web results,
272
+ grows from 12,252 to 17,439 characters. One new test.
273
+ - **A flow from a supranational bloc is drawn on the map.** The map-data
274
+ extraction prompt asks for each capital flow in reverse, from a
275
+ receiving system to the focal country (rule 6), and lets the model name
276
+ a union as a flow's target (rule 12), so a payment from the EU comes
277
+ back as "European Union → Indonesia". The extraction kept a bloc only as
278
+ a flow's target, so it dropped that payment, and the renderer could not
279
+ start an arrow at a bloc, so the same flow from the web search drew
280
+ nothing. The extraction now keeps a bloc as a flow's source under the
281
+ guards a bloc target has (no member named on its own, the other
282
+ endpoint not a member), and drops a flow from a bloc that holds the
283
+ focal country or that it lists whole as a spillover system. On the map,
284
+ such a flow starts at the bloc's anchor and is drawn only when the bloc
285
+ is a partner and the flow ends at a country on the map or at another
286
+ partner bloc. A bloc is a partner when the focal country or a
287
+ receiving country sends a flow to it (a two-way flow counts in both
288
+ directions) or the extraction kept a flow from it to the focal
289
+ country, unless it holds the focal country, one of its members is a
290
+ receiving country in its own right, or the extraction listed it as a
291
+ spillover system; the map data records such blocs as
292
+ `spillover_blocs`. Maps drawn from the analysis text,
293
+ which have no map data to say which blocs are partners, give a
294
+ web-sourced flow from a bloc no arrow. Each bloc on the map now gets its
295
+ own fill, so a bloc with a member bordering the focal country no longer
296
+ recolours another bloc, and the flows table of the Markdown and Word
297
+ exports names a bloc endpoint instead of printing "None". Replaying the
298
+ committed Indonesia run's map-data response through the fixed
299
+ extraction gives 14 flows, its 13 and the EU's capital flow to
300
+ Indonesia, and draws 14 arrows. Twenty-three new tests in
301
+ `tests/test_core.py`, `tests/test_worldmap.py` and `tests/test_output.py`.
302
+ - **A country's name is no longer read as its namesake region.** The
303
+ subnational-region scan behind the validation block's "Core subnational
304
+ regions" line (also the fallback for the map data's
305
+ `mentioned_adm1_regions`) resolves short phrases with the focal country
306
+ as a hint, and with that hint the ADM1 resolver reads a country's own
307
+ name or adjective as its namesake region: a bare "Mexico" listed the
308
+ State of México, and "Australian" in a study of Australian lithium the
309
+ Australian Capital Territory. The scan now skips a phrase that is exactly
310
+ a name or adjective of the region's own country, as the focal-region
311
+ resolver already did; "State of Mexico" is still read as the region,
312
+ and a US state named like a country (Georgia) still reaches the state.
313
+ Across 55 saved analyses, 9 change, each by losing such a region: the
314
+ State of México in 8, among them the committed 2026-06-16 avocado run,
315
+ and the Australian Capital Territory in 1; an analysis that names
316
+ Temascaltepec in the State of Mexico keeps it. Four new tests.
317
+ - **The automatic map follows the analysis's focal country and partners.**
318
+ The map-data extraction call names the primary sending country as the
319
+ focal country, so a study whose focal country receives the flows was
320
+ mapped around the sender: "Impact of haze pollution on public health and
321
+ sustainability in Singapore" drew a map of Indonesia, and an Italian
322
+ study of irregular migration one of Libya. The map's focal country is now
323
+ the one the coupling database validation reads, the extracted one joining
324
+ the partners. The own country of every other system except spillover
325
+ systems joins the partners too, so partners the call left out are drawn
326
+ with their flows (Norway, Belgium and Denmark in a study of the United
327
+ Kingdom's electricity interconnectors); a country a system only mentions
328
+ is not added. Replaying the saved map-extraction responses of 19 traced
329
+ runs, 5 change (those three, and two avocado runs gain the Netherlands, a
330
+ system of their analyses) and 14 do not, among them the committed
331
+ 2026-06-16 avocado run. Six new tests.
332
+ - **The validation block anchors on the focal system's country.** The
333
+ country check took its focal country from the first sending system, and
334
+ from the `[Focal System]` only when the analysis had no sending system,
335
+ and it resolved a name that names two countries to the longer country
336
+ name. The first sending system can be a partner's, and "Mexico — avocado
337
+ exports to the United States" resolves to the United States, so a
338
+ gpt-6-luna analysis of Mexico's avocado trade printed "Focal System:
339
+ United States (USA)" and checked "United States (USA) ↔ Mexico (MEX)".
340
+ The check now takes the country the `[Focal System]` names, in its name
341
+ or else its geographic scope, then the first sending system's, and in a
342
+ name of the form `<country> — <what flows>` the country before the dash.
343
+ Of the 31 gpt-5.5 analyses saved on 2026-10-15, 8 anchored on a partner
344
+ and now anchor on the country their description is about: southern
345
+ Chile's salmon aquaculture had anchored on Peru, Germany's electricity
346
+ imports on France (so the block checked France ↔ Poland, TELECOUPLED,
347
+ where it now checks Germany ↔ Poland, PERICOUPLED), Kenya's exports on
348
+ Tanzania and Rwanda's gorilla tourism on the Democratic Republic of the
349
+ Congo. The validation blocks of the other 23 and of the committed avocado
350
+ run are unchanged. Tests +3 (suite 2,201).
351
+ - **Free text reads the adjectives of small states: "Sri Lankan",
352
+ "Bahamian", "Fijian".** `resolve_country_code(..., free_text=True)` and
353
+ `find_country_codes` read a country's adjective only from the alias
354
+ table, and a country's name inside its adjective does not count, since a
355
+ letter follows it. The table lacked "Sri Lankan" and the adjectives of
356
+ most small states, among them the island states the `maritime_adjacency`
357
+ layer gives neighbours at sea. A gpt-6.1-sol analysis of Indian bottom
358
+ trawling in the Palk Bay named Sri Lanka in its systems only as "Sri
359
+ Lankan" ("Northern Sri Lankan coastal fisheries"), so the country
360
+ validation found India alone and left its block out. The table gains 124
361
+ adjectives of 117 units of the country database, and the block reads
362
+ "Sri Lanka (LKA) ↔ India (IND) (at sea)" with `maritime_adjacency=True`
363
+ (telecoupled without it). Left out: adjectives that several units share or that also
364
+ name a wider region (Congolese, Guinean, Micronesian, Macedonian,
365
+ Papuan), two that are region names of the ADM1 database (Kazakh in
366
+ Azerbaijan, Somali in Ethiopia), names of peoples who live in large
367
+ numbers across a border (Tajik, Uzbek, Turkmen, Swazi, Basotho,
368
+ Batswana), and Georgian, which is also the US state's. Fourteen names of
369
+ other places, plurals included, keep the new adjectives from naming a
370
+ country inside the name of a region, steppe, sea or insect: "Inner
371
+ Mongolian", "East" and "West Azerbaijani", "West Timorese", the
372
+ Mongolian Plateau and steppe, the Libyan Sea, the Mongolian locust, and
373
+ the Senegalese grasshopper and locust; "Kosovo Albanian" and "Kosovar
374
+ Albanian" read as Kosovo. For a text that names two countries,
375
+ `resolve_country_code` still gives the country of the longer name, which
376
+ can now be an adjective: "Indian trawlers in Sri Lankan waters" gives Sri
377
+ Lanka (`find_country_codes` gives both). Of 44 saved analyses
378
+ (the 31 gpt-5.5 analyses saved on 2026-10-15 and 13 traced runs), only
379
+ the Palk Bay analysis's validation changes, with `maritime_adjacency` on
380
+ or off. Of the 362 sentences of the RAG corpus and those analyses that
381
+ hold a new word, 139 now name the adjective's country where they named
382
+ none, and 39 that name two countries now resolve to the adjective's.
383
+ The ADM1 alias tables rebuild byte for byte. Tests +48 (suite 2,249).
384
+ - **The validation block says when it finds no country besides the focal
385
+ one.** The country check left its block out when the systems named no
386
+ country besides the focal one, so a partner named in words the resolver
387
+ does not read disappeared without a trace: before the adjectives above,
388
+ the Palk Bay analysis printed no block at all. An analysis with adjacent
389
+ or distant systems (an entry of its pericoupling or telecoupling section
390
+ other than a focal system) now gets the block with its focal system and
391
+ a note: "No country other than India (IND) was found in the systems, so
392
+ no country pair was checked against the coupling database." For an
393
+ analysis without such systems the country check still prints nothing.
394
+ Like the other notes of a check that looked up no pair, the report
395
+ prints this one only when it lists no pair. Of the 44 saved analyses,
396
+ the note appears for the Palk Bay analysis alone on the code before the
397
+ adjectives above, and for none with them. Tests +7 (suite 2,256).
398
+ - **The country validation note compares the database's verdicts with the
399
+ coupling sections the analysis holds.** The note asked for a revision
400
+ only when the database found a pericoupled pair and the classification
401
+ text never contained "pericoupl", or found only telecoupled pairs and it
402
+ never contained "telecoupl", so a classification that named a coupling
403
+ type only to deny it passed as consistent. A gpt-6.1-sol analysis of
404
+ Indian bottom trawling in the Palk Bay calls the interaction
405
+ "pericoupling—not telecoupling" and has no telecoupling section; with
406
+ `maritime_adjacency` off (the default) its block lists "Sri Lanka (LKA)
407
+ ↔ India (IND)" as telecoupled, and the note said "LLM classification is
408
+ consistent with the coupling database." The analysis now claims the
409
+ coupling types whose sections it holds, since the prompt has the model
410
+ leave out the section of a type it finds absent, so this note asks for a
411
+ revision. The note texts are unchanged, and the subnational (ADM1) check
412
+ still reads the classification text. The 44 saved analyses were replayed
413
+ under the default settings and, for the 12 runs that record their
414
+ settings, under those (`coupling_standard="moderate"`), each with
415
+ `maritime_adjacency` off and on: all 112 notes called the classification
416
+ consistent, and 8 now ask for a revision, those of the analyses of the
417
+ Palk Bay, cruise tourism from the United States in the Bahamas,
418
+ migration from Libya to Italy and the North Sea Link with the toggle
419
+ off. Each of the four denies telecoupling, holds no telecoupling section
420
+ and has one partner country, which the database finds telecoupled
421
+ without maritime adjacency and adjacent at sea with it. Tests +4
422
+ (suite 2,260).
423
+ - **The subnational (ADM1) validation note reads the coupling sections
424
+ the analysis holds too.** Like the country note above, it asked for a
425
+ revision only when the classification text never contained "pericoupl"
426
+ or "telecoupl", so a classification that named a coupling type only to
427
+ deny it passed as consistent, and the two notes of one report could
428
+ disagree. For acid rain from Ohio on Ontario under
429
+ `coupling_standard="moderate"`, which makes the two telecoupled, an
430
+ analysis that calls the study "pericoupling, not telecoupling" and holds
431
+ only a pericoupling section got "Consider revising" from the country
432
+ note and "consistent" from the ADM1 note; both now ask for a revision.
433
+ The check compares the focal region with the other regions it finds in
434
+ the analysis, including one the analysis keeps inside its own focal
435
+ system, so an analysis whose focal system spans two adjacent regions
436
+ gets the note unless it has a pericoupling section, whatever its
437
+ classification says (before, only when the classification never named
438
+ pericoupling). None of the 112 replays of the 44 saved analyses
439
+ changes. Eight print an ADM1 block: the two analyses of avocado
440
+ expansion in Michoacán and its effects on neighbouring Jalisco, which
441
+ hold a pericoupling section, and the two of Indonesia's coal exports
442
+ from East Kalimantan, in which the check finds no region besides the
443
+ focal one, each with `maritime_adjacency` off and on. Tests +4
444
+ (suite 2,264).
445
+
10
446
  ## [0.2.2] — 2026-10-24
11
447
 
12
448
  A maintenance release: the Claude adapter works with anthropic 2.x, two
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## 1. Overview
4
4
 
5
- **MetacouplingLLM** (import name `metacouplingllm`) is a Python package (v0.2.2) that helps researchers apply the telecoupling and metacoupling frameworks (Liu et al., 2013; Liu, 2017) to their own research topics using Large Language Models (LLMs). Given a natural-language research description, the package produces a structured, framework-compliant analysis that identifies coupled human and natural systems, classifies coupling types, maps flows, agents, causes, and effects, and grounds the output in both a curated literature database and real-time web search results.
5
+ **MetacouplingLLM** (import name `metacouplingllm`) is a Python package (v0.3.0) that helps researchers apply the telecoupling and metacoupling frameworks (Liu et al., 2013; Liu, 2017) to their own research topics using Large Language Models (LLMs). Given a natural-language research description, the package produces a structured, framework-compliant analysis that identifies coupled human and natural systems, classifies coupling types, maps flows, agents, causes, and effects, and grounds the output in both a curated literature database and real-time web search results.
6
6
 
7
7
  **Key capabilities:**
8
8
 
@@ -13,7 +13,7 @@
13
13
  - Literature recommendation from a curated BibTeX database
14
14
  - Real-time web search grounding with native backends for OpenAI, Anthropic, Gemini, and Grok (DuckDuckGo fallback for custom clients and whenever a native backend fails or returns nothing)
15
15
  - `evidence_coverage_note`: the model's closing self-assessment (§7 Evidence Coverage, requested in every framework-mode analysis) of how well the retrieved literature passages and, when web search is on, the web results support each group of claims
16
- - Pericoupling validation against two geographic databases (country-level and subnational ADM1) with mode-aware presentation: region-scale adjacency for subnational queries, country-scale for national queries; spillover pairs filtered (left to the framework systems analysis)
16
+ - Pericoupling validation against two geographic databases (country-level and subnational ADM1) with mode-aware presentation: region-scale adjacency for subnational queries, country-scale for national queries; spillover pairs filtered (left to the framework systems analysis); optional maritime adjacency for countries (`maritime_adjacency=True`) also counts countries whose waters share a maritime boundary
17
17
  - Automated map generation at both country and subnational levels, including supranational-union dissolution (EU / ASEAN / USMCA)
18
18
  - Support for OpenAI, Anthropic, **Google Gemini**, **xAI Grok** (each adapter auto-wires its native web search), or any custom LLM backend (web search falls back to DuckDuckGo)
19
19
  - **Scholar-ready export**: `result.abstract`, `result.to_markdown()`, `result.to_docx()` for manuscript-ready output
@@ -288,7 +288,7 @@ Web search injects current, real-world context (trade data, policies, recent eve
288
288
  - Results cited as `[Tk:W1]`, `[Tk:W2]`, ... -- the `W` prefix distinguishes web sources from literature `[Tk:1]`, `[Tk:2]`. `k` is the turn index, so prior-turn web references stay stable across `refine()` calls.
289
289
  - On by default (`web_structured_extraction=True`): a second LLM pass (strict JSON / tool-output across all four providers) over the web results and validates map-ready countries and flows before using them in auto-maps.
290
290
  - `evidence_coverage_note` is the model's 2-5 paragraph closing self-assessment (§7), requested in every framework-mode analysis, of how well the retrieved literature passages and web sources support each group of claims and which claims rest on inference — surfaced on `result.parsed.evidence_coverage_note` and `result.evidence_coverage_note`.
291
- - Supranational unions (EU / ASEAN / USMCA / NAFTA) are handled end-to-end: the map-data extraction prompt lets the model name a union as a flow target and the package expands it to its member states, web-result summaries are passed to the map-data extraction call up to 2,500 characters each, and the map renderer dissolves union borders and draws the bloc as one region, filled as pericoupling if any member borders the focal country and as telecoupling otherwise.
291
+ - Supranational unions (EU / ASEAN / USMCA / NAFTA) are handled end-to-end: the map-data extraction prompt lets the model name a union as a flow target and the package expands it to its member states (a union named as a flow's source, such as the EU paying for exports, is kept the same way), web-result summaries are passed to the map-data extraction call up to 2,500 characters each, and the map renderer dissolves union borders and draws each bloc as one region, filled as pericoupling when one of its members on the map borders the focal country and as telecoupling otherwise; on a map drawn from the extracted map data, each flow to or from a bloc is one arrow, and a flow from a bloc is drawn only when the bloc is a partner (MANUAL §14).
292
292
 
293
293
  ### 4.5 Pericoupling Databases
294
294
 
@@ -297,14 +297,16 @@ Two geographic adjacency databases validate LLM coupling classifications:
297
297
  | Database | Scope | Coverage |
298
298
  |---|---|---|
299
299
  | Country-level | Countries and territories | Full global (ISO alpha-3) |
300
- | ADM1 (subnational) | First-level administrative regions | 3,374 regions, 8,462 shared-border pairs (8,026 under the default `moderate` coupling standard), 196 countries |
300
+ | ADM1 (subnational) | First-level administrative regions | 3,374 regions, 8,462 shared-border pairs (8,026 under the `moderate` coupling standard), 196 countries |
301
301
 
302
302
  Functions: `is_pericoupled()`, `get_pericoupled_neighbors()`, `lookup_adm1_pericoupling()`, etc.
303
303
 
304
- Both levels accept two orthogonal toggles: **`de_facto_borders`** (default `True`; fold disputed land into its de-facto administrator, vs the strict WB standard layer) and **`coupling_standard`** (`stringent` / `moderate` / `lenient`, default `moderate`) — for pairs sharing **only** a river/lake border, `moderate` requires a completed fixed crossing (road or railway bridge, causeway, dam-top road or tunnel; ferries and crossings under construction do not count, while a finished bridge on a politically closed border or a disused railway bridge with its track in place does), `stringent` drops all water-only pairs, and `lenient` keeps them. Each fixed-crossing flag was adjudicated by the same two-model design as the water-only status (an OpenStreetMap screen, GPT-5.6 Sol research, Sonnet-5 adversarial judgment, a location test and maintainer map rulings); see `docs/METHODS_adjacency.md` §8.
304
+ Both levels accept two orthogonal toggles: **`de_facto_borders`** (default `True`; fold disputed land into its de-facto administrator, vs the strict WB standard layer) and **`coupling_standard`** (`stringent` / `moderate` / `lenient`, default `lenient`) — for pairs sharing **only** a river/lake border, `lenient` keeps them, so by default every administrative border counts; `moderate` requires a completed fixed crossing (road or railway bridge, causeway, dam-top road or tunnel; ferries and crossings under construction do not count, while a finished bridge on a politically closed border or a disused railway bridge with its track in place does), and `stringent` drops all water-only pairs. Each fixed-crossing flag was adjudicated by the same two-model design as the water-only status (an OpenStreetMap screen, GPT-5.6 Sol research, Sonnet-5 adversarial judgment, a location test and maintainer map rulings); see `docs/METHODS_adjacency.md` §8.
305
305
 
306
306
  `MetacouplingAssistant` takes the same two settings and applies them to every adjacency lookup it makes: the pericoupling-database hint in the system prompt, the validation block and the automatic map. The three map functions accept them as well.
307
307
 
308
+ At the country level a third toggle, **`maritime_adjacency`** (default `False`, because most metacoupling studies define adjacency on land), also counts two countries as adjacent when their waters share a maritime boundary in the Maritime Boundaries Geodatabase of the Flanders Marine Institute (Marine Regions, version 12): 387 country pairs, 257 of them not adjacent on land, so the default country view grows from 326 to 583 pairs. Every boundary line counts, whatever its legal status; an area that several countries claim, or manage jointly, borders each of them; and a disputed tract's waters go to the administrator the land database assigns the tract. `MetacouplingAssistant` applies it to its country-level hint, validation and map, and the two country map functions and `build_adjacency(level="adm0")` accept it; see `docs/METHODS_adjacency.md` §11.
309
+
308
310
  Region names are resolved to ADM1 codes by `resolve_adm1_code`, which—beyond unaccented forms and native-script letters that NFKD cannot decompose—consults a bundled, deterministically-validated **English-exonym alias table** (1,256 aliases; e.g. Bavaria→Bayern, Tuscany→Toscana), removes a trailing administrative designator when the full name fails ("Narok County"→Narok, kept only where the designator names first-level units), ignores hyphens, dashes, spaces, apostrophes and the World Bank's aa/ae/oe spellings when nothing else matches ("Trans-Nzoia"→"Trans Nzoia", "Murang’a"→"Murang'a", "Skåne"→"Skaane Laen"), and returns `None` rather than guessing on an ambiguous or padded name, or on a single word that only begins a longer name ("Puerto" is not Puerto Plata) unless a country is given. (The prompt-hint scanner and the validator's text cleaner additionally strip possessive suffixes, e.g. "Michigan's"→"Michigan", and split hyphenated compounds, e.g. "Michoacán-Jalisco", in free text before calling it; `resolve_adm1_code` itself does neither — `resolve_adm1_code("Michigan's")` returns `None` even though `resolve_adm1_code("Michigan")` returns `"USA023"`.)
309
311
 
310
312
  ### 4.6 Literature Recommendations
@@ -370,7 +372,7 @@ The `metacouplingllm.indicators` submodule computes deterministic metacoupling i
370
372
  | Function | What it does |
371
373
  |---|---|
372
374
  | `classify_coupling(edges, focal_id, adjacency, ...)` | Add `coupling_type` (I / P / T) to an edge table using a user-supplied adjacency table (or one generated by `build_adjacency`). |
373
- | `build_adjacency(pairs, level="adm0", ...)` | Fill the `adjacent` flag (1 / 0 / `<NA>` when a name cannot be resolved) from the bundled country (`"adm0"`) or ADM1 (`"adm1"`) pericoupling database, with the same `de_facto_borders` / `coupling_standard` options; pass the result to `classify_coupling`. |
375
+ | `build_adjacency(pairs, level="adm0", ...)` | Fill the `adjacent` flag (1 / 0 / `<NA>` when a name cannot be resolved) from the bundled country (`"adm0"`) or ADM1 (`"adm1"`) pericoupling database, with the same `de_facto_borders` / `coupling_standard` options (and, at `"adm0"`, `maritime_adjacency`); pass the result to `classify_coupling`. |
374
376
  | `compute_flow_shares(data, ...)` | Intracoupled / Pericoupled / Telecoupled Flow Shares (IFS / PFS / TFS) per focal system. |
375
377
  | `compute_mfe(data, ...)` | Metacoupled Flow Evenness — normalised Shannon entropy across coupling types; `data` must be the shares table returned by `compute_flow_shares` (columns `IFS` / `PFS` / `TFS`, set by `share_cols`), not the raw edge table. |
376
378
  | `compute_mfci(data, ...)` | Metacoupled Flow Concentration Index — normalised HHI (IFCI / PFCI / TFCI) within each coupling type. |
@@ -579,9 +581,10 @@ The same tables feed the optional LLM-assisted helpers (natural-language study s
579
581
  | ADM1 alias table (CSV) | 1,256 English exonyms / alternative spellings for 922 ADM1 regions in 140 countries (e.g. Bavaria→Bayern, Tuscany→Toscana), so `resolve_adm1_code` matches common English names; deterministically validated (see `data/PROVENANCE.md`) |
580
582
  | Water-only border files (CSV) | `water_separated_pairs.csv`: the 843 water-only pairs (824 ADM1 + 19 ADM0 roll-ups), each with a `has_bridge` fixed-crossing flag (ADM1: 388 with a crossing, 436 without), read by `coupling_standard`; `water_classification_pairs.csv`: the 824 ADM1 rows with their adjudication evidence |
581
583
  | Disputed-territory overlay and edge-correction files (CSV) | `disputed_overlay_pairs.csv`: 19 pairs (16 ADM1 + 3 ADM0), read by `de_facto_borders`; `sliver_corridor_relabel.csv` (11 rows), `land_gap_overlay_pairs.csv` (5 pairs) and `denylist_pairs.csv` (7 pairs): the reviewed corrections behind the ADM1 edge list (see `data/PROVENANCE.md`) |
584
+ | Maritime boundary pairs (CSV) | `maritime_adjacency_pairs.csv`: 387 country pairs whose waters share a boundary in the Marine Regions Maritime Boundaries Geodatabase v12 (Flanders Marine Institute, 2023; CC BY 4.0), read by `maritime_adjacency` (see `data/PROVENANCE.md`) |
582
585
  | Framework examples | Five case studies from the literature corpus (Wolong Nature Reserve, South American food trade, global marine fishing, Michigan groundwater and trout streams, transatlantic wood pellets), laid out coupling-first; the best matches (`max_examples`, default 2) are injected into the prompt |
583
586
 
584
- *Counts above are as of v0.2.2. Call `get_database_info()` for the live BibTeX count and `len(zipfile.ZipFile(pathlib.Path(metacouplingllm.__file__).parent / "data" / "Papers.zip").namelist())` (after `import zipfile, pathlib, metacouplingllm`) for the live paper count if the corpus drifts.*
587
+ *Counts above are as of v0.3.0. Call `get_database_info()` for the live BibTeX count and `len(zipfile.ZipFile(pathlib.Path(metacouplingllm.__file__).parent / "data" / "Papers.zip").namelist())` (after `import zipfile, pathlib, metacouplingllm`) for the live paper count if the corpus drifts.*
585
588
 
586
589
  ---
587
590
 
@@ -590,7 +593,7 @@ The same tables feed the optional LLM-assisted helpers (natural-language study s
590
593
  - **Lean dependencies** -- Core analysis works with only `numpy`, `fastembed`, and an LLM client; visualization, web search, quantitative indicators, and scholar export are optional extras
591
594
  - **Graceful degradation** -- Each optional feature (RAG, web search, maps, literature, indicators, export) can be independently enabled or disabled; RAG transparently falls back from embeddings to TF-IDF when `fastembed` is unavailable
592
595
  - **Protocol-based extensibility** -- Any object with a `chat()` method works as an LLM client
593
- - **Pre-LLM knowledge injection, post-LLM validation** -- Web search, example selection, and the pericoupling-database hint happen before the LLM call; pericoupling validation of the LLM's stated classification runs post-LLM on the parsed output and flags, in the COUPLING DATABASE VALIDATION block of `result.formatted`, a coupling-type mismatch between the LLM's stated classification and the database adjacency for analyst review ("Consider revising."); it never edits the LLM's text
596
+ - **Pre-LLM knowledge injection, post-LLM validation** -- Web search, example selection, and the pericoupling-database hint happen before the LLM call; pericoupling validation of the LLM's stated classification runs post-LLM on the parsed output and flags, in the COUPLING DATABASE VALIDATION block of `result.formatted`, a coupling-type mismatch between the LLM's stated classification and the database adjacency, or a partner country placed only in the coupling section its database verdict contradicts, for analyst review ("Consider revising."); it never edits the LLM's text
594
597
  - **Semantic RAG** -- Pre-computed BGE-base embeddings shipped with the package; semantic matching catches synonyms and paraphrases that TF-IDF misses. TF-IDF remains available as a fallback.
595
598
  - **Colab-compatible** -- Web search includes a zero-dependency stdlib fallback for restricted environments
596
599
  - **Deterministic-first for quantitative analysis** -- The `metacouplingllm.indicators` math never calls an LLM; numbers are reproducible from the input DataFrame alone. The five LLM-assisted helpers are scoped to natural-language and judgment tasks (study setup, input validation, ambiguous-edge classification, interpretation, methods drafting) and always pair their output with an `LLMTrace` record. The classification helper is instructed to return `"unknown"` when it cannot decide, and an `"unknown"` leaves the row `NaN`; when `classify_coupling(llm_client=...)` merges its suggestions, every other label (including low-confidence ones) is written into `coupling_type`, so review them using the `confidence` and `needs_user_confirmation` columns of `classify_ambiguous_edges()`; no helper changes flow values.