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.
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/.github/workflows/test.yml +1 -6
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/CHANGELOG.md +45 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/INTRODUCTION.md +117 -81
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/MANUAL.md +740 -321
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/PKG-INFO +118 -82
- metacouplingllm-0.2.1/README.md +190 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/FUTURE_EDGE_AUDITS.md +1 -1
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/FUTURE_WORK.md +19 -14
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/METHODS_adjacency.md +6 -4
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/REPRODUCING.md +121 -62
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/VALIDATION_STUDY.md +45 -19
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/pyproject.toml +1 -1
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/build_embeddings.py +7 -4
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/build_pericoupling_db.py +5 -4
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/draw_validation_sample.py +6 -2
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/strategy_b_decision.py +14 -7
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/__init__.py +7 -7
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/core.py +29 -28
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/PROVENANCE.md +6 -4
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/Papers.zip +0 -0
- metacouplingllm-0.2.1/src/metacouplingllm/data/chunk_embeddings.manifest.json +11 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/chunk_embeddings.npy +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/denylist_pairs.csv +1 -1
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/indicators/__init__.py +5 -5
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/indicators/_math.py +5 -5
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/indicators/_prompts.py +2 -2
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/indicators/classify.py +16 -11
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/indicators/core.py +16 -17
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/indicators/llm.py +45 -19
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/adm1_pericoupling.py +7 -5
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/literature.py +9 -4
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/websearch.py +86 -36
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/llm/client.py +2 -1
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/output/formatter.py +4 -1
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/prompts/templates.py +3 -3
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/visualization/__init__.py +4 -4
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/visualization/adm1_map.py +2 -2
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/visualization/worldmap.py +2 -2
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_core.py +69 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_docs_capabilities.py +14 -4
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_docs_examples.py +1 -1
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_indicators.py +4 -4
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_indicators_llm.py +110 -1
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_literature.py +26 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_rag.py +3 -3
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_websearch.py +119 -12
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_worldmap.py +20 -0
- metacouplingllm-0.2.0/README.md +0 -140
- metacouplingllm-0.2.0/src/metacouplingllm/data/chunk_embeddings.manifest.json +0 -11
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/.gitignore +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/LICENSE +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/arc_and_combined_screens/SPEC_ba1_border_arc_and_screens.md +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/build_record/relabel_RESULTS.md +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/geodesic_distances/SPEC_gd1_geodesic_distances.md +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/ndlsa_ne/SPEC_da1_defacto_administrators.md +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/stage_order/SPEC_st1_stages.md +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/water_screen_rebuild/corridor_census_exact/SPEC_cc1_corridor_census.md +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/water_screen_rebuild/crossing_adjudication/SPEC_ca1_crossing_adjudication.md +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/water_screen_rebuild/crossing_width/SPEC_cw1_crossing_width.md +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/water_screen_rebuild/july_rejections/SPEC_jr1_july_rejections.md +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/water_screen_rebuild/rule_rejections/SPEC_mr1_rule_rejections.md +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/build_data/water_screen_rebuild/uniform_acceptance/SPEC_ua1_uniform_acceptance.md +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/BRIDGE_CLASSIFICATION_METHODOLOGY.md +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/VALIDATION_SAMPLING_PLAN.md +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/adm1_aliases_audit.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/docs/ndlsa_tract_audit.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/brazil_soybean_adjacency.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/brazil_soybean_flows.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/.gitignore +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/00_build_edge_table.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/01_build_region_map.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/02_compute_indicators.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/03_analysis.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/README.md +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/data/eez_region.json +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/data/fishing_edge_table.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/data/s16_country_region.json +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/outputs/global_totals.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/outputs/indicators_by_eez.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/outputs/regional_catch.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/outputs/regional_indicators.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/outputs/telecoupled_share_timeseries.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/examples/fishing_eez/run_all.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/apply_check_keywords.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/apply_overlays.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/audit_unreplaced.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/build_adm1_aliases.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/build_all.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/build_paper_metadata_table.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/build_rag.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/check_no_stale_metacoupling.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/check_oa_status.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/copyright_audit.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/diagnose_anthropic_web_search.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/extract_keywords.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/integrate_keywords.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/match_references.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/organize_pdfs.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/organize_pdfs_v2.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/organize_pdfs_v3.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/patch_doi_inventory.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/rebuild_rag_corpus.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/regenerate_paper_metadata.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/relabel_sliver_corridors.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/trace_pipeline.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/validate_adm1_aliases.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/scripts/verify_papers_vs_bib.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/PeriTelecoupling_clean.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/PeriTelecoupling_subset.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/adm1_aliases.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/disputed_overlay_pairs.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/land_gap_overlay_pairs.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/pericoupled_adm1_edge_list.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/sliver_corridor_relabel.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/telecoupling_literature.bib +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/water_classification_pairs.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/data/water_separated_pairs.csv +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/indicators/_schemas.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/indicators/adjacency.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/__init__.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/citations.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/countries.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/examples.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/framework.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/pericoupling.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/rag.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/knowledge/references.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/llm/__init__.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/llm/parser.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/output/__init__.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/output/export.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/prompts/__init__.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/prompts/builder.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/src/metacouplingllm/tracing.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/__init__.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/_helpers.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/conftest.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/data/adm1_resolve_golden.json +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/data/avocado_main_analysis_response.md +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_adm1_map.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_adm1_name_matching_regression.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_adm1_pericoupling.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_apply_overlays.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_build_pericoupling_db.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_builder.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_citations.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_client.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_countries.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_coupling_first.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_data_csvs.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_examples.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_formatter.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_framework.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_gemini_grok_support.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_integration.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_openai_integration.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_output.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_parser.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_pericoupling.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_rag_only_mode.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_rag_pipeline.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_relabel_sliver_corridors.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_structured_extraction.py +0 -0
- {metacouplingllm-0.2.0 → metacouplingllm-0.2.1}/tests/test_templates.py +0 -0
- {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
|
-
|
|
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
|
-
#
|
|
1
|
+
# MetacouplingLLM: An LLM-Powered Python Package for Applying the Metacoupling Framework
|
|
2
2
|
|
|
3
3
|
## 1. Overview
|
|
4
4
|
|
|
5
|
-
**
|
|
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
|
|
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
|
|
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
|
|
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` (
|
|
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` (
|
|
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. **
|
|
30
|
-
2. **
|
|
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]" #
|
|
43
|
-
pip install "metacouplingllm[export]" #
|
|
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
|
|
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 + | | (
|
|
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 |
|
|
129
|
-
| .to_markdown() |
|
|
130
|
-
| .to_docx() |
|
|
130
|
+
| .abstract |
|
|
131
|
+
| .to_markdown() |
|
|
132
|
+
| .to_docx() |
|
|
131
133
|
| .map |
|
|
132
134
|
+--------------------+
|
|
133
135
|
```
|
|
134
136
|
|
|
135
|
-
**Quantitative indicators side-track
|
|
137
|
+
**Quantitative indicators side-track**:
|
|
136
138
|
|
|
137
139
|
```
|
|
138
|
-
User-supplied flow DataFrame
|
|
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
|
|
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
|
|
163
|
-
|
|
164
|
-
(study setup, validation,
|
|
165
|
-
always pair their output with
|
|
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, #
|
|
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(
|
|
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** --
|
|
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** —
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
276
|
-
- `evidence_coverage_note`
|
|
277
|
-
- Supranational unions (EU / ASEAN / USMCA / NAFTA) are handled end-to-end: prompt
|
|
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
|
|
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
|
|
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
|
|
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(
|
|
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(
|
|
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
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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),
|
|
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
|
|
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=`
|
|
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
|
|
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 `
|
|
480
|
-
|
|
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) #
|
|
522
|
+
print(p.evidence_coverage_note) # reviewer-facing evidence self-assessment
|
|
495
523
|
```
|
|
496
524
|
|
|
497
|
-
Or hand the result to the scholar exporters
|
|
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`
|
|
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
|
-
|
|
528
|
-
|
|
529
|
-
#
|
|
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
|
|
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
|
-
|
|
|
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
|
-
|
|
|
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.
|
|
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,
|
|
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
|
|
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 "
|
|
569
|
-
pytest tests/
|
|
602
|
+
pip install -e ".[all,dev]"
|
|
603
|
+
pytest tests/ # CI runs: pytest tests/ -q
|
|
570
604
|
```
|
|
571
605
|
|
|
572
|
-
|
|
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.
|