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