Document vignette workflow in README, add latest example results

- Add "Example Vignettes → Paper Workflow" section to README
- Clarify generate_latex.py is standalone (not used by main.tex)
- Add example_results_20260314_023319.json with fresh vignette outputs
- Add CLAUDE.md with project instructions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,3 @@
+# Project Instructions
+
+- **Figures**: Whenever any figure file (`panel_a_map.py`, `panel_b_architecture.tex`, or panel c in `main.tex`) is updated, also update `writing/65d4fadc59fceb1a54d1aae6/figures-in-making/README.md` to reflect the change. Same goes for next figures as well i.e. any paper in that main.tex file.

README.md

@@ -31,10 +31,25 @@ OPENROUTER_API_KEY=...        # optional, for Llama/Gemini
 | Run Eval | `python retrieval_evaluation.py` |
 | Run App | `python app.py` |
 | Run Examples | `python app.py --examples` (saves JSON to `examples-work-out/`) |
-| Generate LaTeX | `cd examples-work-out && python generate_latex.py <results.json>` |
 | Deploy Dev | `git push space3 fresh-start:main` |
 | Deploy Prod | `git push space2 fresh-start:main` |
 
+### Example Vignettes → Paper Workflow
+
+This is the workflow for generating example responses and getting them into the paper (`main.tex`):
+
+1. **Run examples**: `python app.py --examples` → saves 6 vignettes (SLF, Striga×2, FAW×2, Sahara Mustard) to `examples-work-out/example_results_{timestamp}.json`
+2. **Update paper via Claude**: Give the JSON file to Claude and ask it to update the vignette sections in `writing/65d4fadc59fceb1a54d1aae6/main.tex`. Claude formats each example into the `\configbox`/`\querybox`/`tcolorbox` LaTeX pattern defined in main.tex (lines ~485-497). There is no automated script for this step.
+3. **Recompile**: `pdflatex main.tex` to embed updated examples.
+
+**Key files:**
+- `app.py` — `run_examples()` (~line 670) defines the 6 vignettes; RAG prompt template (lines 406-429)
+- `examples-work-out/species-verification.md` — tracks which vignettes map to which JSON examples and their DB status
+- `writing/65d4fadc59fceb1a54d1aae6/main.tex` — paper draft with vignette sections (Witchweed §, Fall Armyworm §)
+
+**Not part of the main workflow:**
+- `examples-work-out/generate_latex.py` — generates a **standalone** LaTeX document from JSON results (useful for quick review), but does **not** feed into `main.tex`. Paper integration is done manually via Claude as described above.
+
 ### Git Remotes
 - `space2` → `git@hf.co:spaces/arbabarshad/agllm2` (production)
 - `space3` → `git@hf.co:spaces/arbabarshad/agllm2-dev` (dev)
@@ -63,7 +78,7 @@ OPENROUTER_API_KEY=...        # optional, for Llama/Gemini
 │   └── species_table.tex       # LaTeX species table
 │
 ├── examples-work-out/
-│   ├── generate_latex.py       # JSON → LaTeX converter for paper examples
+│   ├── generate_latex.py       # JSON → standalone LaTeX doc (not used by main.tex)
 │   ├── example_results_*.json  # Generated example outputs
 │   ├── example_results_20260303_110427.json  # All 4 vignettes (SLF, Striga, FAW, Sahara Mustard) — latest, updated prompt
 │   └── species-verification.md # Vignette tracking: species, regions, DB status, example outputs
@@ -77,17 +92,20 @@ OPENROUTER_API_KEY=...        # optional, for Llama/Gemini
 | Tier | Species | Chunks | Source |
 |------|---------|--------|--------|
 | Midwest USA | 82 | 388 | ISU Handbook PDFs |
-| USA | 219 | 913 | GPT-4o generated IPM |
+| USA | 109 | ~500 | GPT-4o generated IPM |
 | Africa | 35 | 70 | Expert-curated Excel |
 | India | 11 | 39 | Expert-curated Excel |
-| **Total** | **128 unique** | **1410** | |
+| **Primary 3 (unique)** | **115** | **497** | 82+35+11 entries; 13 appear in 2 regions |
+| **All 4 tiers** | **~224** | **~997** | 115 primary + 109 USA (109 overlap with primary) |
+
+> **Species counts verified 2026-03-13.** The USA tier was previously reported as 219 due to a bug in `generate_usa_ipm_info.py`: the results JSONL accumulated across 3 separate runs, and the dedup was case-sensitive (missing capitalization variants from older Excel versions). Both issues are fixed. True count: 109 unique species confirmed present in the USA out of 115 primary-tier species. 6 primary-tier species are not found in the USA (see Supplementary of the paper).
 
 **Midwest USA Data (82 species):**
 1. PDFs loaded from `agllm-data/agllm-data-isu-field-{insects,weeds}-all-species/` (content source)
 2. `matched_species_results_v2.csv` in each folder maps PDF filename → species name (metadata); region hardcoded as `"Midwest USA"` in `app_database_prep.py`
 3. The `Midwest USA` sheet in the Excel is a reference copy only — **not** read by `app_database_prep.py`
 
-**USA Data (219 species - LLM generated):**
+**USA Data (109 species - LLM generated):**
 4. Run `generate_usa_ipm_info.py` to query GPT-4o for all species (species from all 3 primary tiers, filtered to those confirmed in USA)
 5. Creates `USA` sheet in `species-organized/PestID Species - Organized.xlsx` — both content (IPM Info column) and metadata are read from this sheet
 
@@ -111,7 +129,7 @@ python generate_usa_ipm_info.py --step process   # Call GPT-4o API
 python generate_usa_ipm_info.py --step parse     # Create Excel sheet
 ```
 
-**Output:** Updates `species-organized/PestID Species - Organized.xlsx` with "USA" sheet containing 219 species present in the United States (pests + beneficials).
+**Output:** Updates `species-organized/PestID Species - Organized.xlsx` with "USA" sheet containing 109 species present in the United States (pests + beneficials).
 
 ### Evaluation Filters (retrieval_evaluation.py)
 | Filter | P@1 | P@2 | P@4 | P@8 | nDCG@1 | nDCG@2 | nDCG@4 | nDCG@8 |
@@ -165,6 +183,45 @@ python retrieval_evaluation.py
 
 ---
 
+### Verifying species counts
+
+To reproduce the verified species counts (2026-03-13):
+
+```bash
+source ~/miniconda3/etc/profile.d/conda.sh && conda deactivate && conda activate agllm-june-15
+
+python3 -c "
+import pandas as pd
+xl = 'species-organized/PestID Species - Organized.xlsx'
+sheets = {s: pd.read_excel(xl, sheet_name=s) for s in ['Midwest USA','Africa','India','USA']}
+for s, df in sheets.items():
+    print(f'{s}: {df[\"Species\"].notna().sum()} rows, {df[\"Species\"].dropna().str.strip().str.lower().nunique()} unique')
+primary = set()
+for s in ['Midwest USA','Africa','India']:
+    primary |= set(sheets[s]['Species'].dropna().str.strip().str.lower())
+usa = set(sheets['USA']['Species'].dropna().str.strip().str.lower())
+print(f'Primary 3 unique: {len(primary)}, USA unique: {len(usa)}')
+print(f'In USA: {len(primary & usa)}, Not in USA: {len(primary - usa)}')
+print('Not in USA:', sorted(primary - usa))
+"
+```
+
+**Expected output:**
+```
+Midwest USA: 82 rows, 82 unique
+Africa:      35 rows, 35 unique
+India:       11 rows, 11 unique
+USA:        109 rows, 109 unique
+Primary 3 unique: 115, USA unique: 109
+In USA: 109, Not in USA: 6
+Not in USA: ['cleome aculeata', 'cleome houtteana', 'cleome monophylla',
+             'cyperus mindorensis', 'spodoptera litura', 'trianthema triquetrum']
+```
+
+> **Bug history:** The USA sheet previously showed 219 rows due to (1) `generate_usa_ipm_info.py` being run 3× without clearing `usa_ipm_results.jsonl`, and (2) case-sensitive dedup missing capitalization variants from older Excel versions. Both fixed in `generate_usa_ipm_info.py`.
+
+---
+
 ## Git LFS Troubleshooting Notes
 
 This repository encountered several Git LFS issues during setup. Here's a summary for future reference:

examples-work-out/example_results_20260314_023319.json

@@ -0,0 +1,56 @@
+[
+  {
+    "species": "Lycorma delicatula",
+    "region": "Midwest USA",
+    "model": "Llama-3 70B",
+    "mode": "Researcher",
+    "question": "How can I identify and report spotted lanternfly in Iowa?",
+    "availability": "**Common Name:** Spotted Lanternfly\n\nInformation for **Lycorma delicatula** is available in region(s): **Midwest USA, USA**.",
+    "answer": "**Identification and Reporting in Iowa (Midwest USA):**\n\n* Spotted lanternfly nymphs: black with white spots (young) or red and black with white spots (older), found on host trees, usually on branches.\n* Spotted lanternfly adults: pinkish-gray cicada-like with black spots, long grayish-black legs, and a second pair of red, white, and black wings beneath the gray spotted wings.\n* Egg masses: present in Iowa from late July to the following spring.\n\n**Reporting:**\n\n* Report spotted lanternfly sightings to the authorities (no specific contact information provided in the context).\n\nNote: No specific information on reporting procedures or contact details is available in the provided context. It is recommended to search for up-to-date information on reporting spotted lanternfly sightings in Iowa."
+  },
+  {
+    "species": "Striga asiatica",
+    "region": "Africa",
+    "model": "Llama-3 70B",
+    "mode": "Researcher",
+    "question": "What is the most effective way to manage Striga in my maize field?",
+    "availability": "**Common Name:** Witch weed\n\nInformation for **Striga asiatica** is available in region(s): **Africa, USA**.",
+    "answer": "Based on the provided context, here is the answer:\n\n**In Africa:**\nThe most effective way to manage Striga in your maize field is to combine multiple Integrated Striga Management (ISM) technologies, including:\n\n* Using Striga-resistant maize varieties as the foundation\n* Maize-legume rotation to deplete the seedbank\n* Legume intercropping (push-pull) to trigger suicidal germination\n* Applying nitrogen fertilizer to suppress strigolactone exudation\n* Deploying Fusarium oxysporum biocontrol where feasible\n\n**In other regions:**\nIn the USA, integrated management strategies combining cultural, chemical, and biological controls are recommended for effective long-term management of Striga asiatica. Some cultural control practices that can be considered include crop rotation with non-host crops, trap crops, deep tillage, and sanitation."
+  },
+  {
+    "species": "Striga asiatica",
+    "region": "USA",
+    "model": "Llama-3 70B",
+    "mode": "Researcher",
+    "question": "What is the most effective way to manage Striga in my maize field?",
+    "availability": "**Common Name:** Witch weed\n\nInformation for **Striga asiatica** is available in region(s): **Africa, USA**.",
+    "answer": "Based on the provided context, here is the answer:\n\n**USA:**\nFor effective long-term management of Striga asiatica, an integrated approach combining cultural, chemical, and biological controls is recommended. Some specific strategies include:\n\n* Crop rotation with non-host crops to reduce Striga seed bank in the soil\n* Planting trap crops to stimulate Striga germination but not support its growth\n* Deep tillage to bury Striga seeds deeper in the soil, reducing their viability\n* Sanitation to prevent the spread of Striga seeds between fields\n* Pre-emergent and post-emergent herbicides, such as imazapyr and glyphosate, can be used to control Striga infestations\n* Ongoing studies into the use of certain fungi and bacteria that can attack Striga seeds or seedlings, though these are not widely implemented yet\n\n**Africa:**\nAdditionally, using Striga-resistant maize varieties as the foundation, combined with maize-legume rotation to deplete the seedbank, and adding legume intercropping (push-pull) to trigger suicidal germination, can be effective. Applying nitrogen fertilizer to suppress strigolactone exudation and deploying Fusarium oxysporum biocontrol where feasible can also be considered.\n\nNote: There is no specific information available from the Midwest USA region for this question."
+  },
+  {
+    "species": "Spodoptera frugiperda",
+    "region": "India",
+    "model": "Llama-3 70B",
+    "mode": "Researcher",
+    "question": "What are the recommended IPM strategies for managing fall armyworm in my corn field?",
+    "availability": "**Common Name:** Fall Armyworm\n\nInformation for **Spodoptera frugiperda** is available in region(s): **India, Midwest USA, USA**.",
+    "answer": "Based on the provided context, here are the recommended IPM strategies for managing fall armyworm in your corn field in India:\n\n**From India:**\n\n* Cultural Control: Crop rotation, intercropping, and planting shortly after major rainstorms to reduce pest incidence.\n* Monitoring: Use pheromone traps (8 traps/40 lures per acre) for early detection and adult population monitoring, applied based on Economic Threshold Level (ETL).\n* Biological Control: Apply Metarhizium anisopliae (entomopathogenic fungus) at 1 kg/acre.\n* Botanical/Biorational: Use azadirachtin 1500 ppm (neem-based) at 1 L/acre.\n* Chemical Control (need-based): Emamectin benzoate 5% SG at 100 g/acre, applied based on ETL.\n\n**From other regions:**\n\n* According to USA guidance, consider the following additional strategies:\n\t+ Crop Rotation: Rotate crops to disrupt the lifecycle of the pest.\n\t+ Planting Date Adjustment: Alter planting dates to avoid peak periods of armyworm activity.\n\t+ Field Sanitation: Remove crop residues and weeds that can serve as hosts.\n\t+ Trap Crops: Use trap crops to attract and manage populations away from main crops.\n* According to Midwest USA guidance, consider the following additional strategies:\n\t+ Scout for larvae in whorls prior to tasseling in corn, and use a sweep net in soybean and alfalfa.\n\t+ Manage grassy weeds in and near fields to reduce armyworm problems.\n\nPlease note that the context does not provide specific information on the effectiveness of these strategies in corn fields in India. Further research may be necessary to refine these recommendations."
+  },
+  {
+    "species": "Spodoptera frugiperda",
+    "region": "USA",
+    "model": "Llama-3 70B",
+    "mode": "Researcher",
+    "question": "What are the recommended IPM strategies for managing fall armyworm in my corn field?",
+    "availability": "**Common Name:** Fall Armyworm\n\nInformation for **Spodoptera frugiperda** is available in region(s): **India, Midwest USA, USA**.",
+    "answer": "Based on the provided context, here are the recommended IPM strategies for managing fall armyworm in your corn field in the USA:\n\n**From USA:**\n\n* **Cultural Control/Management Practices:**\n\t+ Crop rotation to disrupt the lifecycle of the pest\n\t+ Planting date adjustment to avoid peak periods of armyworm activity\n\t+ Field sanitation to remove crop residues and weeds that can serve as hosts\n\t+ Trap crops to attract and manage populations away from main crops\n* **Biological Control Options/Natural Enemies:**\n\t+ Conservation of natural enemies like parasitoids (e.g., Trichogramma spp.) and predators (e.g., lady beetles and lacewings) through habitat management\n* **Chemical Control Options:**\n\t+ Insecticides may be used, but resistance management is critical; use based on monitoring and threshold levels to minimize unnecessary applications\n\t+ Bacillus thuringiensis (Bt) products can be effective against larvae\n\n**From Midwest USA:**\n\n* **Scouting and Management:**\n\t+ Begin scouting in mid-June; continue until silks dry in corn\n\t+ Treat corn with foliar insecticides when 25% of plants are infested, caterpillars are small (<1 inch), and still exposed\n\t+ Transgenic Bt corn exhibits action against fall armyworm; some Bt proteins (e.g., Cry1F and Vip3Aa20) provide better control than others\n\nNote that there is no specific information on IPM strategies for corn fields in the USA region. The Midwest USA region provides more specific guidance on scouting and management for corn."
+  },
+  {
+    "species": "Brassica tournefortii",
+    "region": "Midwest USA",
+    "model": "Llama-3 70B",
+    "mode": "Researcher",
+    "question": "What mechanical, chemical, and cultural control methods are recommended for managing Sahara mustard infestations?",
+    "availability": "**Common Name:** Sahara Mustard\n\nInformation for **Brassica tournefortii** is available in region(s): **Midwest USA, USA**.",
+    "answer": "Based on the provided context, here are the recommended control methods for managing Sahara mustard infestations:\n\n**Mechanical Control:**\n\n* According to Midwest USA guidance, monitoring the area for rodent caches and treating them accordingly is important.\n\n**Chemical Control:**\n\n* According to Midwest USA guidance, early applications of chemicals may control Sahara mustard due to its extremely early development. Applications should be particularly effective if started before native species have begun to develop.\n* According to USA guidance, herbicides such as glyphosate and 2,4-D can be effective when applied to young plants before they set seed. Pre-emergent herbicides can be used to prevent seed germination in heavily infested areas.\n\n**Cultural Control:**\n\n* According to USA guidance, manual removal is effective for small infestations, ensuring the entire root is removed to prevent regrowth. Mowing before seed set can reduce seed production but may need to be repeated due to staggered germination. Restoration of native vegetation can help outcompete Sahara Mustard.\n\nNote: There is no specific information on mechanical control methods in the Midwest USA region, and no biological control options are mentioned in the provided context."
+  }
+]