MetacouplingLLM 0.2.0__tar.gz → 0.2.1__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 (165) hide show
  1. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/.github/workflows/test.yml +1 -6
  2. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/CHANGELOG.md +45 -0
  3. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/INTRODUCTION.md +117 -81
  4. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/MANUAL.md +740 -321
  5. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/PKG-INFO +118 -82
  6. metacouplingllm-0.2.1/README.md +190 -0
  7. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/FUTURE_EDGE_AUDITS.md +1 -1
  8. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/FUTURE_WORK.md +19 -14
  9. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/METHODS_adjacency.md +6 -4
  10. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/REPRODUCING.md +121 -62
  11. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/VALIDATION_STUDY.md +45 -19
  12. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/pyproject.toml +1 -1
  13. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/build_embeddings.py +7 -4
  14. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/build_pericoupling_db.py +5 -4
  15. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/draw_validation_sample.py +6 -2
  16. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/strategy_b_decision.py +14 -7
  17. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/__init__.py +7 -7
  18. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/core.py +29 -28
  19. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/PROVENANCE.md +6 -4
  20. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/Papers.zip +0 -0
  21. metacouplingllm-0.2.1/src/metacouplingllm/data/chunk_embeddings.manifest.json +11 -0
  22. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/chunk_embeddings.npy +0 -0
  23. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/denylist_pairs.csv +1 -1
  24. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/indicators/__init__.py +5 -5
  25. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/indicators/_math.py +5 -5
  26. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/indicators/_prompts.py +2 -2
  27. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/indicators/classify.py +16 -11
  28. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/indicators/core.py +16 -17
  29. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/indicators/llm.py +45 -19
  30. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/adm1_pericoupling.py +7 -5
  31. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/literature.py +9 -4
  32. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/websearch.py +86 -36
  33. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/llm/client.py +2 -1
  34. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/output/formatter.py +4 -1
  35. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/prompts/templates.py +3 -3
  36. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/visualization/__init__.py +4 -4
  37. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/visualization/adm1_map.py +2 -2
  38. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/visualization/worldmap.py +2 -2
  39. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_core.py +69 -0
  40. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_docs_capabilities.py +14 -4
  41. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_docs_examples.py +1 -1
  42. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_indicators.py +4 -4
  43. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_indicators_llm.py +110 -1
  44. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_literature.py +26 -0
  45. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_rag.py +3 -3
  46. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_websearch.py +119 -12
  47. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_worldmap.py +20 -0
  48. metacouplingllm-0.2.0/README.md +0 -140
  49. metacouplingllm-0.2.0/src/metacouplingllm/data/chunk_embeddings.manifest.json +0 -11
  50. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/.gitignore +0 -0
  51. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/LICENSE +0 -0
  52. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/arc_and_combined_screens/SPEC_ba1_border_arc_and_screens.md +0 -0
  53. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/build_record/relabel_RESULTS.md +0 -0
  54. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/geodesic_distances/SPEC_gd1_geodesic_distances.md +0 -0
  55. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/ndlsa_ne/SPEC_da1_defacto_administrators.md +0 -0
  56. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/stage_order/SPEC_st1_stages.md +0 -0
  57. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/water_screen_rebuild/corridor_census_exact/SPEC_cc1_corridor_census.md +0 -0
  58. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/water_screen_rebuild/crossing_adjudication/SPEC_ca1_crossing_adjudication.md +0 -0
  59. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/water_screen_rebuild/crossing_width/SPEC_cw1_crossing_width.md +0 -0
  60. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/water_screen_rebuild/july_rejections/SPEC_jr1_july_rejections.md +0 -0
  61. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/water_screen_rebuild/rule_rejections/SPEC_mr1_rule_rejections.md +0 -0
  62. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/water_screen_rebuild/uniform_acceptance/SPEC_ua1_uniform_acceptance.md +0 -0
  63. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/BRIDGE_CLASSIFICATION_METHODOLOGY.md +0 -0
  64. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/VALIDATION_SAMPLING_PLAN.md +0 -0
  65. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/adm1_aliases_audit.csv +0 -0
  66. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/ndlsa_tract_audit.csv +0 -0
  67. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/brazil_soybean_adjacency.csv +0 -0
  68. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/brazil_soybean_flows.csv +0 -0
  69. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/.gitignore +0 -0
  70. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/00_build_edge_table.py +0 -0
  71. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/01_build_region_map.py +0 -0
  72. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/02_compute_indicators.py +0 -0
  73. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/03_analysis.py +0 -0
  74. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/README.md +0 -0
  75. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/data/eez_region.json +0 -0
  76. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/data/fishing_edge_table.csv +0 -0
  77. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/data/s16_country_region.json +0 -0
  78. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/outputs/global_totals.csv +0 -0
  79. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/outputs/indicators_by_eez.csv +0 -0
  80. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/outputs/regional_catch.csv +0 -0
  81. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/outputs/regional_indicators.csv +0 -0
  82. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/outputs/telecoupled_share_timeseries.csv +0 -0
  83. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/run_all.py +0 -0
  84. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/apply_check_keywords.py +0 -0
  85. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/apply_overlays.py +0 -0
  86. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/audit_unreplaced.py +0 -0
  87. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/build_adm1_aliases.py +0 -0
  88. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/build_all.py +0 -0
  89. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/build_paper_metadata_table.py +0 -0
  90. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/build_rag.py +0 -0
  91. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/check_no_stale_metacoupling.py +0 -0
  92. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/check_oa_status.py +0 -0
  93. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/copyright_audit.py +0 -0
  94. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/diagnose_anthropic_web_search.py +0 -0
  95. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/extract_keywords.py +0 -0
  96. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/integrate_keywords.py +0 -0
  97. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/match_references.py +0 -0
  98. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/organize_pdfs.py +0 -0
  99. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/organize_pdfs_v2.py +0 -0
  100. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/organize_pdfs_v3.py +0 -0
  101. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/patch_doi_inventory.py +0 -0
  102. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/rebuild_rag_corpus.py +0 -0
  103. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/regenerate_paper_metadata.py +0 -0
  104. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/relabel_sliver_corridors.py +0 -0
  105. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/trace_pipeline.py +0 -0
  106. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/validate_adm1_aliases.py +0 -0
  107. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/verify_papers_vs_bib.py +0 -0
  108. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/PeriTelecoupling_clean.csv +0 -0
  109. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/PeriTelecoupling_subset.csv +0 -0
  110. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/adm1_aliases.csv +0 -0
  111. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/disputed_overlay_pairs.csv +0 -0
  112. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/land_gap_overlay_pairs.csv +0 -0
  113. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/pericoupled_adm1_edge_list.csv +0 -0
  114. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/sliver_corridor_relabel.csv +0 -0
  115. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/telecoupling_literature.bib +0 -0
  116. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/water_classification_pairs.csv +0 -0
  117. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/water_separated_pairs.csv +0 -0
  118. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/indicators/_schemas.py +0 -0
  119. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/indicators/adjacency.py +0 -0
  120. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/__init__.py +0 -0
  121. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/citations.py +0 -0
  122. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/countries.py +0 -0
  123. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/examples.py +0 -0
  124. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/framework.py +0 -0
  125. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/pericoupling.py +0 -0
  126. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/rag.py +0 -0
  127. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/references.py +0 -0
  128. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/llm/__init__.py +0 -0
  129. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/llm/parser.py +0 -0
  130. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/output/__init__.py +0 -0
  131. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/output/export.py +0 -0
  132. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/prompts/__init__.py +0 -0
  133. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/prompts/builder.py +0 -0
  134. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/tracing.py +0 -0
  135. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/__init__.py +0 -0
  136. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/_helpers.py +0 -0
  137. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/conftest.py +0 -0
  138. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/data/adm1_resolve_golden.json +0 -0
  139. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/data/avocado_main_analysis_response.md +0 -0
  140. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_adm1_map.py +0 -0
  141. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_adm1_name_matching_regression.py +0 -0
  142. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_adm1_pericoupling.py +0 -0
  143. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_apply_overlays.py +0 -0
  144. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_build_pericoupling_db.py +0 -0
  145. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_builder.py +0 -0
  146. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_citations.py +0 -0
  147. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_client.py +0 -0
  148. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_countries.py +0 -0
  149. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_coupling_first.py +0 -0
  150. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_data_csvs.py +0 -0
  151. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_examples.py +0 -0
  152. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_formatter.py +0 -0
  153. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_framework.py +0 -0
  154. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_gemini_grok_support.py +0 -0
  155. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_integration.py +0 -0
  156. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_openai_integration.py +0 -0
  157. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_output.py +0 -0
  158. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_parser.py +0 -0
  159. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_pericoupling.py +0 -0
  160. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_rag_only_mode.py +0 -0
  161. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_rag_pipeline.py +0 -0
  162. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_relabel_sliver_corridors.py +0 -0
  163. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_structured_extraction.py +0 -0
  164. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_templates.py +0 -0
  165. {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_tracing.py +0 -0
@@ -72,9 +72,4 @@ jobs:
72
72
  fastembed-model-
73
73
 
74
74
  - name: Run pytest
75
- # test_rag.py has a pre-existing 768-vs-384 embedding dimension
76
- # mismatch in TestEmbeddingRetriever::test_query_returns_results_with_precomputed
77
- # that is unrelated to current work. Excluded here until that
78
- # specific test is fixed; the rest of the RAG surface is exercised
79
- # by test_rag_pipeline.py and test_rag_only_mode.py.
80
- run: pytest tests/ --ignore=tests/test_rag.py -q
75
+ run: pytest tests/ -q
@@ -7,6 +7,51 @@ file. The format is loosely based on
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.2.1] — 2026-10-12
11
+
12
+ A maintenance release after the documentation audit of 0.2.0.
13
+
14
+ Highlights:
15
+
16
+ - **The RAG corpus checked paper by paper**: 421 papers, 219 indexed as full
17
+ text and 202 as paraphrased summaries, each licence traced to the paper or
18
+ its publisher; nine author labels corrected, Newig et al. 2020 added, and
19
+ the embeddings rebuilt. The README states the bundled papers' licences.
20
+ - **Grok web search works**: its request now takes the Responses-API shapes
21
+ xAI documents, so Grok runs search natively instead of falling back to
22
+ DuckDuckGo.
23
+ - **Indicator LLM helpers** run on the model passed as `model=`, and their
24
+ trace records Anthropic's answer.
25
+ - **Citations**: a refined result lists its web sources as turn 1's, and the
26
+ citation sanitizer also runs without a literature corpus.
27
+ - **Smaller fixes**: bibliography keywords split on semicolons, install hints
28
+ name `metacouplingllm[viz]`, CI runs the RAG tests, and the documentation
29
+ and docstrings were checked against the code, the data and the paper.
30
+
31
+ ### Fixed
32
+
33
+ - **Grok web search works: the backend's request was rejected by the openai SDK, so every Grok run fell back to DuckDuckGo.** `GrokWebSearchBackend` passed `max_turns`, `reasoning_effort` and a chat-style `response_format` as top-level arguments to `client.responses.create`; the openai SDK (2.30.0) has none of them and raised TypeError before sending anything, the backend caught it and returned no results, and `search_web` fell back to DuckDuckGo. The request now takes the Responses-API shapes xAI documents: the strict JSON schema in `text.format`, `reasoning={"effort": ...}`, the xAI-only `max_turns` in `extra_body`, and the domain list in the `web_search` tool's `filters`; an `allowed_domains` list replaces the default `excluded_domains`, as xAI accepts only one of the two. The diagnostic web-search count now reads `usage.server_side_tool_usage_details.web_search_calls`, and the citation fallback also reads the `url_citation` annotations the openai SDK returns. Verified live on 2026-10-11: grok-4.7 and grok-4.6 each returned 5 sourced results with 200-400-word summaries (Nature, Ambio, Yale e360, the CRI report), and a full `MetacouplingAssistant` analysis through `GrokAdapter` on grok-4.7 searched natively (10 sources), its structured web extraction accepted 1 receiving system and 2 flows, and the report and abstract completed. The MANUAL's caveat about the defect is removed, and `GrokAdapter`'s docstring no longer names the retired Live Search API. Tests +5, among them a check that the request binds to the real `Responses.create` signature, which the old request fails (suite 1,430; the 1,422 in INTRODUCTION and REPRODUCING predates the three MANUAL examples #159 added).
34
+ - **The indicator LLM helpers run on the model passed as `model=` instead of raising TypeError.** Every helper (`define_study`, `check_inputs`, `classify_ambiguous_edges`, `interpret_results`, `write_methods`, and `classify_coupling`'s LLM fallback) added `model=` to `llm_client.chat()`, which the four built-in adapters reject. A built-in adapter is now copied with the requested model (a shallow copy: other settings such as Anthropic's extended thinking carry over, and the caller's adapter is unchanged), and the trace records the model the call ran on; a custom client still receives `model=` on `chat()`. INTRODUCTION and MANUAL describe the keyword as it works. Tests +3.
35
+ - **Bibliography keywords are split on the semicolons the entries use.** All 249 keyword fields separate keywords with semicolons (three have a comma inside a keyword), but the parser split on commas, so each paper held its whole field as one keyword; `Paper.keywords` now holds the separate keywords (median 5 per paper, at least 2). `recommend_papers()` rankings barely move, because the scorer's substring test also matched inside the whole field: on three test queries the top 8 kept 8/8, 8/8 and 7/8 papers. Tests +2.
36
+ - **CI runs `tests/test_rag.py` again**, including `TestBundledManifestIntegrity`, the check that the bundled embeddings manifest matches the corpus chunks. It was excluded in #4 (2026-05-13) for one failing test that has since been fixed. The docs-capability guard now requires each keyword word to start a word in the docs: the substring test let "RAG" pass on "coverage" while the README never described the RAG corpus. RELEASE_CHECKLIST and INTRODUCTION no longer say CI skips the file. Test +1.
37
+ - **Install hints name the package on PyPI**: `pip install metacouplingllm[viz]`, not the pre-rename `metacoupling[viz]`, in the two visualization error messages and 12 docstrings and comments. Test +2 (suite 1,438).
38
+ - **A refined result lists the web sources as turn 1's.** Web search runs only in `analyze()`, but the result builder labelled its hits with the current turn: a `refine()` result listed them under `WEB SOURCES (turn 2)` as `[T2:Wn]`, and the keyword annotation appended `[T2:Wn]` tokens, while turn 2 records no web sources and the answer cites them as `[T1:Wn]`. Both now use turn 1. Test +1.
39
+ - **The citation sanitizer runs without a literature corpus too.** `sanitize_turn_citations` ran only when a RAG corpus was set, so a web-only or plain run kept out-of-range `[Tk:Wn]` / `[Tk:N]` tokens and the bare `[N]` / `[W1]` ones that the citation rules (always in the prompt) say are stripped. It now runs on every turn, so `result.raw` is the sanitized response in every run, as `AnalysisResult`'s docstring and MANUAL now say. Test +1.
40
+ - **`LLMTrace.raw_response` records Anthropic's answer.** With `AnthropicAdapter`, the strict-JSON helpers (`define_study`, `check_inputs` and `classify_ambiguous_edges`, which `classify_coupling`'s LLM fallback calls) read the answer from a forced tool call, and `response.content` holds no text, so the trace recorded an empty response. It now records the tool input as JSON; MANUAL's `classify_coupling` example no longer documents the gap. Test +1 (suite 1,441).
41
+ - **`scripts/build_embeddings.py` takes its `--model` default from `DEFAULT_EMBEDDING_MODEL`**, so a plain rebuild after the constant changes encodes the corpus with the new model; RELEASE_CHECKLIST no longer asks for `--model` by hand.
42
+ - **The La Paz-Callao denylist row gives the right distance**: the World Bank polygon named Callao has its largest part at Lake Titicaca about 1,000 km from its three coastal parts, not 900 (1,003-1,008 km, measured on the pinned Admin 1 GeoPackage), as `docs/FUTURE_EDGE_AUDITS.md` #14 says. Evidence text only; the edge lists do not change.
43
+
44
+ ### Changed
45
+
46
+ - **The RAG corpus was checked paper by paper: 421 papers, 219 indexed as full text and 202 as summaries (was 420: 192 / 228).** The April 2026 split rested on Unpaywall's licence data, which proved unreliable; each paper's licence is now traced to its own licence line, the publisher's Crossref deposit or the journal's page or policy. Now full text: three papers whose DOIs had been cut short when read from the PDF (Guo et al. 2021, Kapsar et al. 2022, Laroche et al. 2022); five that Unpaywall misread (Creutzig et al. 2019, Dem et al. 2024, Öhlinger and Lehner 2025, Roux et al. 2023, Tromboni et al. 2021); Wu et al. 2025 (CC BY, not ND); and 18 CC BY-NC-ND papers verified on the published version, which the corpus now ships unaltered (back matter left out) for non-commercial use, as the PMC Open Access Subset distributes such articles. Now a summary: Tang et al. 2026, a paywalled article Unpaywall listed as CC BY. Added: Newig et al. 2020, "Governing global telecoupling toward environmental sustainability" (Ecology and Society, CC BY-NC). Nine papers without a bibliography entry, labelled from their file names, now carry their authors as their bylines print them (the file named "Newig et al. 2020" is Sonderegger et al. 2020; "Chuanglin et al." is Fang et al.); three summaries carry corrected DOIs. `Papers.zip` changed in 40 entries (the other 381 byte-identical); the embeddings were rebuilt (10,970 chunks, from 10,039). The README states the papers' licences: 55 of the 219 full texts are non-commercial only. `scripts/strategy_b_decision.py` ships ND licences; tests pin 421 papers.
47
+ - **Citation rule 5 no longer calls the bare grammar "pre-2026".** The bare `[N]` / `[W1]` grammar was replaced in 0.1.3 (2026-05-13); the rule now reads "A token without the `Tk:` prefix is invalid and will be silently stripped by the post-LLM sanitizer". This is prompt text the model sees; the instruction is unchanged.
48
+
49
+ ### Docs
50
+
51
+ - **Documentation audit at v0.2.0 (#157 README and the release checklist, #158 INTRODUCTION, #159 MANUAL, #160 REPRODUCING, VALIDATION_STUDY and FUTURE_WORK).** The seven documents were checked line by line against the code, the bundled data and the EMS paper draft; each finding was reported by one Claude Sonnet 5.5 agent and upheld by an independent re-check (235 upheld, 1 refuted), the fixes were applied by Sonnet 5.5 agents, and each diff was reviewed by a separate agent and by Claude Opus 5.5. The main corrections: run tracing records the model calls made through the assistant's client, and the two web-stage calls bypass it; the evidence coverage note closes every framework report, not only web-search runs; Grok is described by its `/responses` `web_search` tool; the LLM helpers' real inputs and examples that run as written; the token-usage keys per provider; partners for MFCI / ENP are read from `destination_id` (inbound flows need `partner_col="origin_id"`); the release checklist's manifest behaviour (a stale manifest silently falls back to TF-IDF) and smoke test (the built wheel); REPRODUCING's account of human review (561 of 824 water rows carry a maintainer ruling, 263 rest on two-model agreement) and of toolchain reproducibility. Version-history narratives and PR-number change records left the current-state documents. No code, test or data change. Found by the audit and left for a code change: CI runs `pytest --ignore=tests/test_rag.py`; the docs-capability guard matches "RAG" inside "coverage"; `GrokWebSearchBackend` passes `max_turns`, `reasoning_effort` and `response_format` to `openai`'s `Responses.create`, which rejects them, so Grok runs fall back to DuckDuckGo; the indicator LLM helpers forward `model=` to adapters that reject it; the `.bib` keyword parser splits on commas while the entries use semicolons.
52
+ - **Docstrings and comments match the code**: `classify_coupling` (an edge the adjacency table does not list is `T`; `NaN` marks an edge with neither end in the focal system), the literature module (ranked by keyword and title matches, full-text relevance and citation count), `format_comparison` (stacked blocks, not side by side), the Michoacan comment (unaccented names resolve), the disputed overlay (23 of the 24 tracts; the UN Buffer Zone stays unassigned) and the source relabel (10 host polygons, 11 rows, 12 corridors), and the validation sampler (the same bytes only on the same inputs).
53
+ - **The indicator docstrings cite MANUAL §16 and §17** (30 references) instead of `docs/metacoupling_codex_prompts_and_formulas_with_llm.md`, a design spec that was never committed.
54
+
10
55
  ## [0.2.0] — 2026-10-10
11
56
 
12
57
  The first release since 0.1.2. Version 0.1.3 was never tagged or published to
@@ -1,33 +1,34 @@
1
- # Metacoupling: An LLM-Powered Python Package for Applying the Metacoupling Framework
1
+ # MetacouplingLLM: An LLM-Powered Python Package for Applying the Metacoupling Framework
2
2
 
3
3
  ## 1. Overview
4
4
 
5
- **Metacoupling** is a Python package (v0.2.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.
5
+ **MetacouplingLLM** (import name `metacouplingllm`) is a Python package (v0.2.1) 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
 
9
9
  - Structured metacoupling analysis from free-text research descriptions
10
10
  - Multi-turn refinement via conversational LLM interaction
11
- - Retrieval-Augmented Generation (RAG) over 420 telecoupling/metacoupling papers — 192 indexed as full text, the other 228 as structured paraphrased summaries (used wherever redistributing the full text would not be licence-safe)
11
+ - Retrieval-Augmented Generation (RAG) over 421 telecoupling/metacoupling papers — 219 indexed as full text, the other 202 as structured paraphrased summaries (used wherever redistributing the full text would not be licence-safe)
12
12
  - **RAG-only literature Q&A mode** for users already familiar with the framework (`coupling_analysis=False`)
13
13
  - Literature recommendation from a curated BibTeX database
14
- - Real-time web search grounding with native backends for OpenAI, Anthropic, Gemini, and Grok (DuckDuckGo fallback for custom clients) plus `evidence_coverage_note` self-assessment
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
+ - `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
15
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
17
  - Automated map generation at both country and subnational levels, including supranational-union dissolution (EU / ASEAN / USMCA)
17
- - Support for OpenAI, Anthropic, **Google Gemini**, **xAI Grok**, or any custom LLM backend (each with native web-search auto-wiring)
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)
18
19
  - **Scholar-ready export**: `result.abstract`, `result.to_markdown()`, `result.to_docx()` for manuscript-ready output
19
20
  - **Quantitative metacoupling indicators** (`metacouplingllm.indicators`) — IFS / PFS / TFS, MFE, MFCI computed on user-supplied flow data
20
21
  - **Optional LLM-assisted indicator helpers** — `define_study`, `check_inputs`, `classify_ambiguous_edges`, `interpret_results`, `write_methods`, each returning `(result, LLMTrace)` for reproducibility
21
- - **Built-in run tracing** (on by default) — every `analyze()`/`refine()` records a `RunTrace` (all model calls, intermediates, token usage, git SHA) and writes an inspectable artifact folder under `runs/`; disable with `trace=False`
22
+ - **Built-in run tracing** (on by default) — every `analyze()`/`refine()` records a `RunTrace` (the prompts, responses and token usage of every model call made through the assistant's client, plus the git SHA) and writes an inspectable artifact folder under `runs/` (the main-analysis, map-extraction and abstract calls, raw web results, retrieved chunks, parsed analysis, map data and the formatted report); the web-stage model calls (native web search, when used, and structured web extraction) bypass the traced client, so only their results are kept; disable with `trace=False`
22
23
 
23
- **Requirements:** Python 3.10+, two hard runtime dependencies: `numpy>=1.21` and `fastembed>=0.8` (offline RAG embeddings). Optional extras: `openai`, `anthropic`, `gemini`, `grok`, `geopandas`+`matplotlib` (visualization), `ddgs` (web search), `pandas` (quantitative indicators), `python-docx` (Word export).
24
+ **Requirements:** Python 3.10+, two hard runtime dependencies: `numpy>=1.21` and `fastembed>=0.8` (local ONNX embeddings: the corpus vectors ship with the package, but fastembed downloads the ~0.2 GB `BAAI/bge-base-en-v1.5` model on first use, so the first retrieval needs network access or a populated model cache). Optional extras: `openai`, `anthropic`, `gemini`, `grok`, `viz` (geopandas + matplotlib), `search` (ddgs), `indicators` (pandas), `export` (python-docx), `all`.
24
25
 
25
26
  ### Two complementary tracks
26
27
 
27
28
  The package exposes two complementary analysis tracks that can be used independently or combined:
28
29
 
29
- 1. **Qualitative LLM-driven case-study analysis** via `MetacouplingAssistant` — produces a structured, framework-compliant report with citations, optional maps, and scholar-ready Markdown / Word export.
30
- 2. **Quantitative deterministic indicators** via the `metacouplingllm.indicators` submodule — computes flow-share / evenness / concentration indicators on user-supplied flow data. Five optional LLM-assisted helpers (`define_study`, `check_inputs`, `classify_ambiguous_edges`, `interpret_results`, `write_methods`) wrap natural-language judgment tasks around the deterministic core.
30
+ 1. **Deterministic core** — the national (ADM0) and subnational (ADM1) adjacency databases and the `metacouplingllm.indicators` submodule, which computes flow-share / evenness / concentration indicators on user-supplied flow data. Five optional LLM-assisted helpers (`define_study`, `check_inputs`, `classify_ambiguous_edges`, `interpret_results`, `write_methods`) wrap natural-language judgment tasks around the deterministic core.
31
+ 2. **Qualitative LLM-driven case-study analysis** via `MetacouplingAssistant` — produces a structured, framework-compliant report with citations, optional maps, and scholar-ready Markdown / Word export.
31
32
 
32
33
  ### Quick Install
33
34
 
@@ -39,8 +40,8 @@ pip install "metacouplingllm[gemini]"
39
40
  pip install "metacouplingllm[grok]"
40
41
  pip install "metacouplingllm[search]"
41
42
  pip install "metacouplingllm[viz]"
42
- pip install "metacouplingllm[indicators]" # PR #35 quantitative indicators (pandas)
43
- pip install "metacouplingllm[export]" # PR #31/#32 scholar export (python-docx)
43
+ pip install "metacouplingllm[indicators]" # quantitative indicators (pandas)
44
+ pip install "metacouplingllm[export]" # scholar export (python-docx)
44
45
  pip install "metacouplingllm[all]"
45
46
  ```
46
47
 
@@ -50,7 +51,8 @@ If you want to use the built-in OpenAI example below, install `metacouplingllm[o
50
51
 
51
52
  - A structured metacoupling analysis from a plain-language study description
52
53
  - Optional literature recommendations and supporting evidence passages
53
- - Optional web-grounded context for current trade, policy, or event information, with an `evidence_coverage_note` self-assessment of which sources back which claims
54
+ - Optional web-grounded context for current trade, policy, or event information
55
+ - A closing `evidence_coverage_note` in every framework-mode analysis: the model's self-assessment of which retrieved literature passages and web sources back which claims
54
56
  - Optional map generation for country-level and ADM1-level analyses
55
57
  - Scholar-ready abstract + Markdown + Word export (`result.abstract`, `result.to_markdown()`, `result.to_docx()`)
56
58
  - Quantitative metacoupling indicators (IFS / PFS / TFS, MFE, MFCI) computed on user-supplied flow data via `metacouplingllm.indicators`
@@ -93,7 +95,7 @@ The package encodes 14 telecoupling categories from the literature (trade, migra
93
95
  | | |
94
96
  +-------v-------+ +-------v--------+ +-------v-------+
95
97
  | PromptBuilder | | Web Search | | RAG Engine |
96
- | (6-layer | | (native + | | (420 papers, |
98
+ | (6-layer | | (native + | | (421 papers, |
97
99
  | system prompt)| | DuckDuckGo) | | embeddings |
98
100
  | | | | | or TF-IDF |
99
101
  | | | | | fallback) |
@@ -125,17 +127,24 @@ The package encodes 14 telecoupling categories from the literature (trade, migra
125
127
  | AnalysisResult |
126
128
  | .parsed |
127
129
  | .formatted |
128
- | .abstract | (PR #31)
129
- | .to_markdown() | (PR #31)
130
- | .to_docx() | (PR #31, #32)
130
+ | .abstract |
131
+ | .to_markdown() |
132
+ | .to_docx() |
131
133
  | .map |
132
134
  +--------------------+
133
135
  ```
134
136
 
135
- **Quantitative indicators side-track** (PR #35 + #36):
137
+ **Quantitative indicators side-track**:
136
138
 
137
139
  ```
138
- User-supplied flow DataFrame + adjacency
140
+ User-supplied flow DataFrame
141
+ |
142
+ +----------v-----------+
143
+ | build_adjacency | ← fills the adjacent flag
144
+ | (optional) | from the bundled ADM0 /
145
+ | | ADM1 databases (or supply
146
+ | | your own adjacency table)
147
+ +----------+-----------+
139
148
  |
140
149
  +----------v-----------+
141
150
  | classify_coupling | ← assigns I / P / T
@@ -151,7 +160,7 @@ The package encodes 14 telecoupling categories from the literature (trade, migra
151
160
  +----------+-----------+
152
161
  |
153
162
  +----------v-----------+
154
- | LLM helpers (PR #36)| ← define_study,
163
+ | LLM helpers | ← define_study,
155
164
  | optional; each | check_inputs,
156
165
  | returns (result, | classify_ambiguous_edges,
157
166
  | LLMTrace) | interpret_results,
@@ -159,10 +168,15 @@ The package encodes 14 telecoupling categories from the literature (trade, migra
159
168
  +----------------------+
160
169
  ```
161
170
 
162
- Indicator math never calls an LLM (deterministic-first per PR #35
163
- design). The LLM helpers are scoped to natural-language tasks only
164
- (study setup, validation, interpretation, methods drafting) and
165
- always pair their output with an `LLMTrace` for reproducibility.
171
+ Indicator math never calls an LLM (deterministic-first by design).
172
+ The LLM helpers are scoped to natural-language and judgment tasks
173
+ (study setup, input validation, ambiguous-edge classification,
174
+ interpretation, methods drafting) and always pair their output with
175
+ an `LLMTrace` for reproducibility. `classify_ambiguous_edges`, and
176
+ `classify_coupling(llm_client=...)` which calls it, can assign the
177
+ I / P / T labels the indicators are computed from, so those labels
178
+ may vary between runs, while the indicator math itself stays
179
+ deterministic.
166
180
 
167
181
  ---
168
182
 
@@ -188,7 +202,7 @@ advisor = MetacouplingAssistant(
188
202
  web_search_max_results=10, # Number of web results (default)
189
203
  web_structured_extraction=True, # the default; validated countries + flows
190
204
  rag_top_k=8, # Number of RAG evidence passages (default)
191
- rag_min_score=0.60, # Min embeddings cosine sim (BGE-base scale)
205
+ rag_min_score=0.60, # embeddings backend only; omit for the backend-aware default
192
206
  max_examples=2, # Framework examples in prompt
193
207
  temperature=0.7, # LLM temperature
194
208
  verbose=True, # Print progress messages
@@ -200,7 +214,7 @@ advisor = MetacouplingAssistant(
200
214
  | Method | Purpose |
201
215
  |---|---|
202
216
  | `analyze(research_description)` | First-turn structured analysis |
203
- | `refine(info, focus_component=None)` | Multi-turn follow-up refinement |
217
+ | `refine(additional_info, focus_component=None)` | Multi-turn follow-up refinement |
204
218
  | `reset()` | Clear conversation for a new topic |
205
219
 
206
220
  ### 4.2 Prompt Engineering (6-Layer System)
@@ -210,7 +224,7 @@ The system prompt is constructed in six layers:
210
224
  1. **Role** -- Expert persona in metacoupling and sustainability science
211
225
  2. **Knowledge** -- Full framework definitions, 14 categories, coupling transformations
212
226
  3. **Methodology** -- Six-phase operationalization procedure (Liu, 2017)
213
- 4. **Examples** -- Semantically selected real-world case studies (e.g., Brazil-China soybean trade, Beijing water system)
227
+ 4. **Examples** -- The best keyword-matching published case studies (up to `max_examples`) from five bundled examples: Brazil-China soybean trade, red imported fire ant invasion, Beijing water supply, panda conservation / SDGs, Wolong Nature Reserve
214
228
  5. **Output Format** -- Structured template for seven analysis sections
215
229
  (with a **Citation Rules sub-layer, 5b**: turn-scoped `[Tk:N]`/`[Tk:Wn]`
216
230
  citation mechanics and hallucination guardrails)
@@ -219,26 +233,26 @@ The system prompt is constructed in six layers:
219
233
  Before calling the LLM, the system **conditionally** injects (each
220
234
  only fires if its precondition is met):
221
235
 
222
- - **Pericoupling-database hints** — exactly one of two flavors fires per query:
236
+ - **Pericoupling-database hints** — at most one of two flavors fires per query:
223
237
  - *Country-level hint*: if ≥1 country name is detected and no
224
238
  ADM1 region applies. If ≥2 countries are named, each
225
239
  focal-vs-other pair is reported with its database
226
240
  classification (e.g., `"Mexico (MEX) and United States (USA)
227
241
  are pericoupled"` for adjacent pairs, `"Brazil (BRA) and
228
242
  China (CHN) are telecoupled"` for distant pairs). If exactly
229
- 1 country is named (PR #44), the focal country's full
243
+ 1 country is named, the focal country's full
230
244
  pericoupled-neighbor list is injected as candidate context
231
245
  (e.g., a Mexico-only query gets Belize, Guatemala, USA
232
246
  presented as REFERENCE — the LLM is encouraged to consider
233
247
  these as potential pericoupled flows but must confirm with
234
248
  independent evidence). Framing is REFERENCE-only in both
235
- cases (harmonized with the ADM1 hint in PR #43).
249
+ cases.
236
250
  - *ADM1 (subnational) hint*: if any ADM1 region (e.g., Michigan,
237
251
  Mato Grosso) is detected. The focal region's adjacent
238
252
  neighbors are listed as **reference-only adjacency** rather
239
253
  than asserted pericoupling — the LLM is told that adjacency
240
254
  alone is NOT evidence of pericoupling and must find
241
- independent flow evidence (PR #20).
255
+ independent flow evidence.
242
256
  - Queries with no detectable country (and no ADM1 region) get
243
257
  no hint; queries with one country named but no pericoupled
244
258
  neighbors in the database (island nations like Australia,
@@ -247,15 +261,15 @@ only fires if its precondition is met):
247
261
  inline citation (turn-scoped — `k` is the conversation turn).
248
262
  Only when `web_search=True` and at least one hit returned.
249
263
  - **Structured web map hints** — receiving/spillover countries and
250
- flows extracted by a second LLM pass over the web snippets, each
264
+ flows extracted by a second LLM pass over the web results, each
251
265
  kept only if it resolves to a real country/union and cites a real
252
- retrieved snippet (confidence ≥ 0.7). This grounds the *evidence*,
266
+ retrieved web result (confidence ≥ 0.7). This grounds the *evidence*,
253
267
  not the spillover *role* (which classification the LLM still
254
268
  decides). Only when `web_structured_extraction=True` (the default).
255
269
 
256
270
  ### 4.3 Retrieval-Augmented Generation (RAG)
257
271
 
258
- The RAG engine provides evidence grounding from a corpus of 420 telecoupling and metacoupling papers. The split is by what can be redistributed, not by topic: 192 papers whose licences allow it are indexed as **full text**, and the remaining 228 are indexed as **structured, paraphrased summaries** (metadata plus key findings, no source text) so they stay searchable without reproducing copyrighted material. Those 228 are papers the corpus cannot redistribute in full — both paywalled articles and open-to-read articles whose licences still restrict reuse:
272
+ The RAG engine provides evidence grounding from a corpus of 421 telecoupling and metacoupling papers. The split is by what can be redistributed, not by topic: 219 papers whose licences allow it are indexed as **full text**, and the remaining 202 are indexed as **structured, paraphrased summaries** (metadata plus key findings, no source text) so they stay searchable without reproducing copyrighted material. Those 202 are papers the corpus cannot redistribute in full — 125 paywalled articles and 77 articles not cleared for redistribution (free to read without a redistribution licence, restrictively licensed, available only as a preprint, or with open-access status not established):
259
273
 
260
274
  - **Indexing**: Papers are chunked by section and indexed by one of two backends:
261
275
  - **Embeddings (default)** -- semantic retrieval via `fastembed` + the `BAAI/bge-base-en-v1.5` ONNX model. Captures synonyms, paraphrases, and related concepts (e.g., a query about "soybean trade" also matches chunks about "soya bean exports" and "Glycine max shipments"). Pre-computed corpus vectors are shipped with the package as `chunk_embeddings.npy` (~15 MB) so users never have to re-encode.
@@ -269,12 +283,12 @@ The RAG engine provides evidence grounding from a corpus of 420 telecoupling and
269
283
 
270
284
  Web search injects current, real-world context (trade data, policies, recent events) that may not be in the LLM's training data:
271
285
 
272
- - **Native auto-wiring** when `web_search=True`: each adapter routes to its own backend — `OpenAIWebSearchBackend` (PR #17), `AnthropicWebSearchBackend` (PR #28), `GeminiWebSearchBackend` (Google Search grounding, PR #29), `GrokWebSearchBackend` (xAI Live Search incl. X/Twitter, PR #29). Custom clients fall back to the built-in DuckDuckGo search cascade.
286
+ - **Native auto-wiring** when `web_search=True`: each adapter routes to its own backend — `OpenAIWebSearchBackend`, `AnthropicWebSearchBackend`, `GeminiWebSearchBackend` (Google Search grounding), `GrokWebSearchBackend` (xAI's server-side `web_search` tool on the `/responses` endpoint). Custom clients, and any native backend that raises or returns no results, fall back to the built-in DuckDuckGo search cascade.
273
287
  - DuckDuckGo backend has three fallback layers: `ddgs` -> `duckduckgo_search` -> stdlib (`urllib` + `html.parser`); works on Google Colab without any extra packages.
274
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.
275
- - On by default (`web_structured_extraction=True`): a second LLM pass (strict JSON / tool-output across all four providers, PR #28-#30) over the web snippets and validates map-ready countries and flows before using them in auto-maps.
276
- - `evidence_coverage_note` (PR #20) is a one-paragraph LLM self-assessment that summarises what kinds of web sources were available, what coverage gaps remain, and whether the analysis fell back to training memory — surfaced on `result.parsed.evidence_coverage_note`.
277
- - Supranational unions (EU / ASEAN / USMCA / NAFTA) are handled end-to-end: prompt teaches the LLM to keep the union label + list members (PR #22), Stage-3 web-summary buffer is bumped to 2500 chars (PR #26), and the map renderer dissolves union borders and colours member states by their relationship to the focal country (PR #23, #25).
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
+ - `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.
278
292
 
279
293
  ### 4.5 Pericoupling Databases
280
294
 
@@ -287,13 +301,13 @@ Two geographic adjacency databases validate LLM coupling classifications:
287
301
 
288
302
  Functions: `is_pericoupled()`, `get_pericoupled_neighbors()`, `lookup_adm1_pericoupling()`, etc.
289
303
 
290
- 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 fixed crossing open to traffic, `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 `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.
291
305
 
292
- Region names are resolved to ADM1 codes by `resolve_adm1_code`, which—beyond unaccented forms and hyphenated compounds—consults a bundled, deterministically-validated **English-exonym alias table** (1,145 aliases; e.g. Bavaria→Bayern, Tuscany→Toscana) and returns `None` rather than guessing on an ambiguous or padded name. (The prompt-hint scanner additionally strips possessive suffixes, e.g. "Michigan's"→"Michigan", from free text before calling it; `resolve_adm1_code` itself does not — `resolve_adm1_code("Michigan's")` returns `None` even though `resolve_adm1_code("Michigan")` returns `"USA023"`.)
306
+ 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,145 aliases; e.g. Bavaria→Bayern, Tuscany→Toscana) and returns `None` rather than guessing on an ambiguous or padded name. (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"`.)
293
307
 
294
308
  ### 4.6 Literature Recommendations
295
309
 
296
- From a curated BibTeX database of 265 empirical telecoupling/metacoupling journal articles (2013–2026), the system recommends the most relevant papers by matching keywords, coupling types, and domain overlap with the analysis. Call `get_database_info()` for live counts if the corpus drifts.
310
+ From a curated BibTeX database of 265 empirical telecoupling/metacoupling journal articles (2013–2026), the system ranks papers by author keywords (3.0 points per match), title words (2.0 per match), full-text relevance from the RAG index (up to 3.0) and a log-scaled citation bonus (up to 2.0), with ties broken by citation count and then year. Call `get_database_info()` for live counts if the corpus drifts.
297
311
 
298
312
  ### 4.7 Map Visualization
299
313
 
@@ -301,9 +315,9 @@ Three map functions generate matplotlib figures:
301
315
 
302
316
  | Function | Level | Data Source |
303
317
  |---|---|---|
304
- | `plot_focal_country_map(country)` | Country | Local World Bank Admin 0 `all_layers` if available; otherwise hosted `Admin 0_all_layers` mirror; fallback official World Bank Admin 0 10m |
318
+ | `plot_focal_country_map(focal_country)` | Country | Local World Bank Admin 0 `all_layers` if available; otherwise hosted `Admin 0_all_layers` mirror; fallback official World Bank Admin 0 10m |
305
319
  | `plot_analysis_map(parsed_analysis)` | Country | Local World Bank Admin 0 `all_layers` if available; otherwise hosted `Admin 0_all_layers` mirror; fallback official World Bank Admin 0 10m |
306
- | `plot_focal_adm1_map(adm1_code)` | Subnational (ADM1) | Local World Bank Admin 1 if available; otherwise hosted `Admin 1.gpkg` mirror, with World Bank `NDLSA.gpkg` for disputed-area overlay |
320
+ | `plot_focal_adm1_map(focal_adm1)` | Subnational (ADM1) | Cached World Bank Admin 1 if available; otherwise hosted `Admin 1.gpkg` mirror, with World Bank `NDLSA.gpkg` for disputed-area overlay |
307
321
 
308
322
  Map features: coupling-colored regions, flow arrows, disputed territory hatching, customizable color palettes.
309
323
 
@@ -312,11 +326,22 @@ Map features: coupling-colored regions, flow arrows, disputed territory hatching
312
326
  The package uses a protocol-based design that supports any LLM backend:
313
327
 
314
328
  ```python
315
- # Built-in adapters
316
- OpenAIAdapter(client, model="gpt-4o")
317
- AnthropicAdapter(client, model="claude-sonnet-4-20250514")
318
- GeminiAdapter(client, model="gemini-2.5-flash")
319
- GrokAdapter(client, model="grok-3") # OpenAI-protocol-compatible
329
+ from metacouplingllm import (
330
+ AnthropicAdapter,
331
+ GeminiAdapter,
332
+ GrokAdapter,
333
+ LLMResponse,
334
+ OpenAIAdapter,
335
+ )
336
+
337
+ # Built-in adapters, each wrapping its provider's own SDK client. openai_client,
338
+ # anthropic_client, genai_client and xai_client stand for clients you create yourself:
339
+ # openai.OpenAI(...), anthropic.Anthropic(...), google.genai.Client(...), and for Grok
340
+ # an openai.OpenAI(...) created with base_url="https://api.x.ai/v1"
341
+ OpenAIAdapter(openai_client, model="gpt-4o")
342
+ AnthropicAdapter(anthropic_client, model="claude-sonnet-4-20250514")
343
+ GeminiAdapter(genai_client, model="gemini-2.5-flash")
344
+ GrokAdapter(xai_client, model="grok-3") # OpenAI-protocol-compatible
320
345
 
321
346
  # Any custom client with a chat() method also works
322
347
  class MyClient:
@@ -324,37 +349,36 @@ class MyClient:
324
349
  return LLMResponse(content="...")
325
350
  ```
326
351
 
327
- Each built-in adapter auto-wires its native web-search backend when `web_search=True`; custom clients fall back to DuckDuckGo.
352
+ Each built-in adapter auto-wires its native web-search backend when `web_search=True`; custom clients, and any native backend that raises or returns no results, fall back to DuckDuckGo.
328
353
 
329
- ### 4.9 Scholar Export (PR #31, #32)
354
+ ### 4.9 Scholar Export
330
355
 
331
356
  `AnalysisResult` exposes three exporter surfaces so users can turn an LLM analysis into something a co-author or reviewer can read:
332
357
 
333
358
  | Surface | Description | Install needed |
334
359
  |---|---|---|
335
- | `result.abstract` | One-paragraph scholar abstract from a second, conservative LLM pass | none |
336
- | `result.to_markdown(path=None)` | Manuscript-ready Markdown with auto-derived title, bold sub-field labels, per-category Flows / Causes / Effects subsections, RAG + web evidence blocks, classification bullets | none |
337
- | `result.to_docx(path)` | Word document with the same structure as the Markdown export | `metacouplingllm[export]` (python-docx) |
338
-
339
- PR #32 added the auto-derived title, bold sub-field labels, and per-category flow / cause / effect subsections; PR #33 added classification bullets at the top of every system role section.
360
+ | `result.abstract` | One-paragraph scholar abstract from a separate, final LLM call (prompted not to add details absent from the analysis; skip it with `generate_abstract=False`) | none |
361
+ | `result.to_markdown(path=None)` | Manuscript-ready Markdown with auto-derived title, bold sub-field labels, per-category Flows / Causes / Effects subsections, RAG + web evidence blocks | none |
362
+ | `result.to_docx(path)` | Word document with the same structure as the Markdown export; a multi-bullet §1 classification is rendered as bullet paragraphs | `metacouplingllm[export]` (python-docx) |
340
363
 
341
- ### 4.10 Quantitative Indicators (PR #35)
364
+ ### 4.10 Quantitative Indicators
342
365
 
343
366
  The `metacouplingllm.indicators` submodule computes deterministic metacoupling indicators on user-supplied flow data:
344
367
 
345
368
  | Function | What it does |
346
369
  |---|---|
347
- | `classify_coupling(edges, focal_id, adjacency, ...)` | Add `coupling_type` (I / P / T) to an edge table using a user-supplied adjacency table. |
370
+ | `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`). |
371
+ | `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`. |
348
372
  | `compute_flow_shares(data, ...)` | Intracoupled / Pericoupled / Telecoupled Flow Shares (IFS / PFS / TFS) per focal system. |
349
- | `compute_mfe(data, ...)` | Metacoupled Flow Evenness — normalised Shannon entropy across coupling types. |
373
+ | `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. |
350
374
  | `compute_mfci(data, ...)` | Metacoupled Flow Concentration Index — normalised HHI (IFCI / PFCI / TFCI) within each coupling type. |
351
375
  | `summarize_metacoupling(data, ...)` | One-shot combined indicator table. |
352
376
 
353
- Built on established statistics (Shannon 1948 entropy; Hirschman 1945 HHI, normalised per Hannah & Kay 1977; Equivalent Number of Partners per Laakso & Taagepera 1979), not invented indices. Brazil-soybean worked example: IFS = 0.10, PFS = 0.20, TFS = 0.70, MFE ≈ 0.73, TFCI ≈ 0.33. See MANUAL §16 for the full math + code.
377
+ Built on established statistics (Shannon 1948 entropy; Hirschman 1945 HHI, normalised per Hannah & Kay 1977; Equivalent Number of Partners per Laakso & Taagepera 1979) and adapted to the metacoupling framework as Metacoupled Flow Shares (MFS), Evenness (MFE) and Concentration Index (MFCI); the package introduces no new statistic. Brazil-soybean worked example: IFS = 0.10, PFS = 0.20, TFS = 0.70, MFE ≈ 0.73, TFCI ≈ 0.33. See MANUAL §16 for the full math + code.
354
378
 
355
379
  Pandas is the only added dependency; install via `pip install "metacouplingllm[indicators]"`.
356
380
 
357
- ### 4.11 LLM-Assisted Indicator Helpers (PR #36)
381
+ ### 4.11 LLM-Assisted Indicator Helpers
358
382
 
359
383
  Five optional helpers in `metacouplingllm.indicators` wrap natural-language judgment tasks around the deterministic indicator core. Each returns `(result, LLMTrace)` for reproducibility (see MANUAL §17, *LLM-Assisted Indicator Helpers*):
360
384
 
@@ -368,7 +392,7 @@ Five optional helpers in `metacouplingllm.indicators` wrap natural-language judg
368
392
 
369
393
  The `LLMTrace` dataclass carries `timestamp_utc`, `model`, `prompt_version`, `system_prompt`, `user_prompt`, `raw_response`, `usage` so old traces stay attributable when prompt wording evolves.
370
394
 
371
- **Automatic LLM resolution of ambiguous edges in `classify_coupling()`:** pass `llm_client=` (plus optional `study_config=` and `model=`) and the function automatically calls `classify_ambiguous_edges()` on any rows the deterministic pass left as `NaN`, merging suggestions back. When the LLM returns `"unknown"`, the row stays `NaN` — the package never lets the LLM invent adjacency facts silently.
395
+ **Automatic LLM resolution of ambiguous edges in `classify_coupling()`:** pass `llm_client=` (plus optional `study_config=`) and the function automatically calls `classify_ambiguous_edges()` on any rows the deterministic pass left as `NaN`, merging suggestions back. A `model=` keyword runs the call on another model: a built-in adapter is copied with that model (its other settings kept), and a custom client receives `model=` on `chat()`. When the LLM returns `"unknown"`, the row stays `NaN`; any `"I"` / `"P"` / `"T"` label it does give is written into `coupling_type` whatever its confidence, with the call's `LLMTrace` kept in the returned table's `.attrs["llm_classify_trace"]`, so review the labels (`classify_ambiguous_edges()` called directly also returns each suggestion's `confidence` and `needs_user_confirmation`).
372
396
 
373
397
  All five helpers work across OpenAI / Anthropic / Gemini / Grok adapters and use each provider's native strict-JSON / tool-output mode for the structured-output helpers.
374
398
 
@@ -410,7 +434,6 @@ advisor = MetacouplingAssistant(
410
434
  web_search_max_results=10,
411
435
  web_structured_extraction=True,
412
436
  rag_top_k=8,
413
- rag_min_score=0.60,
414
437
  )
415
438
  ```
416
439
 
@@ -429,7 +452,7 @@ if result.map:
429
452
 
430
453
  The output includes:
431
454
  - Coupling classification (intracoupling / pericoupling / telecoupling)
432
- - Systems identification (sending, receiving, spillover with human and natural subsystems)
455
+ - Systems identification (focal, sending, receiving and spillover systems, each with human and natural subsystems)
433
456
  - Flows analysis (matter, capital, information, energy, people, organisms)
434
457
  - Agents grouped by the fixed five-category agent vocabulary
435
458
  - Causes grouped by the fixed cause/effect category vocabulary
@@ -476,8 +499,11 @@ find one, it auto-downloads the hosted `Admin 0_all_layers` mirror into
476
499
  the cache on first use, then falls back to the official World Bank Admin 0
477
500
  10m basemap if needed.
478
501
 
479
- Similarly, if you do not pass `adm1_shapefile`, ADM1 maps first look for a
480
- local Admin 1 file and then auto-download the hosted `Admin 1.gpkg` mirror.
502
+ Similarly, if you do not pass `shapefile=` to `plot_focal_adm1_map`
503
+ (`adm1_shapefile=` on `MetacouplingAssistant`), the ADM1 map looks in the
504
+ cache folder (`~/.cache/metacoupling/wb_adm1/`, or
505
+ `$METACOUPLING_CACHE_DIR/wb_adm1/`) and otherwise auto-downloads the
506
+ hosted `Admin 1.gpkg` mirror into it.
481
507
 
482
508
  ### Step 6: Access Structured Data
483
509
 
@@ -485,16 +511,18 @@ local Admin 1 file and then auto-download the hosted `Admin 1.gpkg` mirror.
485
511
  # Structured access to parsed analysis
486
512
  p = result.parsed
487
513
  print(p.coupling_classification)
488
- print(list(p.iter_system_entries())) # sending/receiving/spillover system entries
514
+ print(list(p.iter_system_entries())) # focal / sending / receiving / spillover system entries
515
+ # each a dict with role, name, human_subsystem, natural_subsystem, geographic_scope;
516
+ # sending / receiving entries also carry system_scope ("adjacent" or "distant")
489
517
  print(list(p.iter_flow_entries())) # flow dicts
490
518
  print(list(p.iter_agent_entries())) # agent dicts
491
519
  print(list(p.iter_category_items("causes"))) # (coupling_type, category, item) triples
492
520
  print(list(p.iter_category_items("effects"))) # (coupling_type, category, item) triples
493
521
  print(p.research_gaps) # list of research gap strings
494
- print(p.evidence_coverage_note) # PR #20 — reviewer-facing evidence audit
522
+ print(p.evidence_coverage_note) # reviewer-facing evidence self-assessment
495
523
  ```
496
524
 
497
- Or hand the result to the scholar exporters (PR #31, #32):
525
+ Or hand the result to the scholar exporters:
498
526
 
499
527
  ```python
500
528
  print(result.abstract) # one-paragraph scholar abstract
@@ -504,7 +532,7 @@ result.to_docx("brazil_soybean.docx") # requires metacouplingllm[export]
504
532
 
505
533
  ### Step 7 (optional): Compute Quantitative Indicators
506
534
 
507
- When you have your own flow data, plug it into `metacouplingllm.indicators` (PR #35) for deterministic indicator math:
535
+ When you have your own flow data, plug it into `metacouplingllm.indicators` for deterministic indicator math:
508
536
 
509
537
  ```python
510
538
  import pandas as pd
@@ -524,12 +552,15 @@ adjacency = pd.DataFrame({
524
552
 
525
553
  classified = classify_coupling(edges, focal_id="Brazil", adjacency=adjacency)
526
554
  summary = summarize_metacoupling(classified)
527
- print(summary)
528
- # focal_system_id IFS PFS TFS MFE IFCI PFCI TFCI
529
- # 0 Brazil 0.10 0.20 0.70 0.73 1.00 0.25 0.33
555
+ cols = ["focal_system_id", "IFS", "PFS", "TFS", "MFE", "IFCI", "PFCI", "TFCI"]
556
+ print(summary[cols].round(2))
557
+ # focal_system_id IFS PFS TFS MFE IFCI PFCI TFCI
558
+ # 0 Brazil 0.1 0.2 0.7 0.73 1.0 0.25 0.33
530
559
  ```
531
560
 
532
- The same DataFrame plugs into the optional LLM-assisted helpers (PR #36) — `define_study`, `check_inputs`, `classify_ambiguous_edges`, `interpret_results`, `write_methods` — for natural-language study setup, validation, ambiguous-edge classification, interpretation, and manuscript prose around the deterministic numbers. Install via `pip install "metacouplingllm[indicators]"`.
561
+ The full summary has 18 columns (`focal_system_id`, then `F_I` ... `ENP_T`: raw flow magnitudes, shares, `MFE`, the concentration indices, partner counts and equivalent numbers of partners); the snippet prints the headline indicators only.
562
+
563
+ The same tables feed the optional LLM-assisted helpers (natural-language study setup, validation, ambiguous-edge classification, interpretation, and manuscript prose around the deterministic numbers): pass the edge table (with a `study_config` dict) to `classify_ambiguous_edges` and the summary table to `interpret_results`; `define_study` takes a text description, `check_inputs` a summary dict (`columns`, `row_count`) plus a few sample rows, and `write_methods` an indicator-spec dict. Each needs `llm_client=` and returns `(result, LLMTrace)`. Install via `pip install "metacouplingllm[indicators]"`.
533
564
 
534
565
  ---
535
566
 
@@ -537,14 +568,17 @@ The same DataFrame plugs into the optional LLM-assisted helpers (PR #36) — `de
537
568
 
538
569
  | Resource | Description |
539
570
  |---|---|
540
- | 420 papers (Papers.zip) | Markdown for RAG — 192 indexed as full text, 228 as structured paraphrased summaries (papers that cannot be redistributed in full: paywalled, or open-to-read but restrictively licensed) |
571
+ | 421 papers (Papers.zip) | Markdown for RAG — 219 indexed as full text, 202 as structured paraphrased summaries (papers that cannot be redistributed in full: 125 paywalled, and 77 not cleared for redistribution — free to read without a redistribution licence, restrictively licensed, preprint-only, or with open-access status not established) |
572
+ | Precomputed embeddings (`chunk_embeddings.npy` + `chunk_embeddings.manifest.json`) | 10,970 × 768 float16 vectors (`BAAI/bge-base-en-v1.5`), one per chunk of the 421 papers, so the corpus never has to be re-encoded; the manifest records the chunk count and chunk-order fingerprint they were built from |
541
573
  | BibTeX database (telecoupling_literature.bib) | 265 empirical journal articles (2013–2026) with metadata for literature recommendation |
542
574
  | Country pericoupling database (CSV) | Global country-pair adjacency classification |
543
575
  | ADM1 edge list (CSV) | 8,462 subnational shared-border pairs across 3,374 regions in 196 countries (World Bank Official Boundaries, 2026-05-14; see `data/PROVENANCE.md`) |
544
576
  | ADM1 alias table (CSV) | 1,145 English exonyms / alternative spellings for 863 ADM1 regions in 136 countries (e.g. Bavaria→Bayern, Tuscany→Toscana), so `resolve_adm1_code` matches common English names; deterministically validated (see `data/PROVENANCE.md`) |
545
- | Framework examples | Curated case studies (soybean trade, urban water) for prompt injection |
577
+ | 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 |
578
+ | 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`) |
579
+ | Framework examples | Five curated case studies (soybean trade, red imported fire ant invasion, Beijing urban water, panda conservation, Wolong Nature Reserve); the best matches (`max_examples`, default 2) are injected into the prompt |
546
580
 
547
- *Counts above are as of v0.2.0. Call `get_database_info()` for the live BibTeX count and `len(zipfile.ZipFile("Papers.zip").namelist())` for the live paper count if the corpus drifts.*
581
+ *Counts above are as of v0.2.1. 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.*
548
582
 
549
583
  ---
550
584
 
@@ -553,20 +587,22 @@ The same DataFrame plugs into the optional LLM-assisted helpers (PR #36) — `de
553
587
  - **Lean dependencies** -- Core analysis works with only `numpy`, `fastembed`, and an LLM client; visualization, web search, quantitative indicators, and scholar export are optional extras
554
588
  - **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
555
589
  - **Protocol-based extensibility** -- Any object with a `chat()` method works as an LLM client
556
- - **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, correcting hallucinated adjacency claims against the database
590
+ - **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
557
591
  - **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.
558
592
  - **Colab-compatible** -- Web search includes a zero-dependency stdlib fallback for restricted environments
559
- - **Deterministic-first for quantitative analysis (PR #35, #36)** -- The `metacouplingllm.indicators` math never calls an LLM; numbers are reproducible from the input DataFrame alone. The five LLM-assisted helpers are explicitly scoped to natural-language tasks (study setup, validation, interpretation, methods drafting) and always pair their output with an `LLMTrace` record. When the LLM is uncertain, it returns `"unknown"` rather than guess; the package never lets the LLM invent adjacency facts or flow values silently.
593
+ - **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.
560
594
 
561
595
  ---
562
596
 
563
597
  ## 8. Testing
564
598
 
565
- The package includes a comprehensive test suite:
599
+ The package includes a comprehensive test suite. The tests are in the source repository, not in the installed wheel, so run them from a clone:
566
600
 
567
601
  ```bash
568
- pip install "metacouplingllm[dev]"
569
- pytest tests/
602
+ pip install -e ".[all,dev]"
603
+ pytest tests/ # CI runs: pytest tests/ -q
570
604
  ```
571
605
 
572
- 1422 tests covering all modules: core advisor logic, framework enums, prompt construction, LLM parsing, RAG retrieval, literature matching, web search (including stdlib fallback), pericoupling databases, country resolution, visualization colors, map generation, scholar export, quantitative indicators, and a CI-enforced doc-capability drift guard (PR #46) that fails the build when shipped features aren't advertised in INTRODUCTION/README/MANUAL.
606
+ Tests that need pandas, python-docx or geopandas are skipped when that extra is missing (`[all]` installs them), and the live OpenAI tests (`tests/test_openai_integration.py`) are skipped unless `OPENAI_API_KEY` is set in the environment or a `.env` file, in which case they make real API calls.
607
+
608
+ 1441 tests covering all modules: core advisor logic, framework enums, prompt construction, LLM parsing, RAG retrieval, literature matching, web search (including stdlib fallback), pericoupling databases, country resolution, visualization colors, map generation, scholar export, quantitative indicators, and a CI-enforced doc-capability drift guard that fails the build when shipped features aren't advertised in INTRODUCTION/README/MANUAL.