Water Conflict Classifier

SetFit-based multi-label text classifier for identifying water-related conflict events in news headlines.

This folder contains the package source code. For usage instructions with the published package, see the PyPI page.

Project: Experimental research supporting the Pacific Institute's Water Conflict Chronology
Developer: Baobab Tech
License: CC BY-NC 4.0 (Non-Commercial)
PyPI Package: water-conflict-classifier

Package Installation & Usage

Install from PyPI:

pip install water-conflict-classifier

Use the trained model:

from setfit import SetFitModel

model = SetFitModel.from_pretrained("baobabtech/water-conflict-classifier")
predictions = model.predict(["Military group attack workers at dam"])
# Returns: [[1, 1, 1]]  # [Trigger, Casualty, Weapon]

The rest of this README is for developers who want to train their own model or modify the package.

Frugal AI: Training with Limited Data

This classifier demonstrates an intentional approach to building AI systems with limited data using SetFit - a framework for few-shot learning with sentence transformers. Rather than defaulting to massive language models (GPT, Claude, or 100B+ parameter models) for simple classification tasks, we fine-tune small, efficient models (e.g., BAAI/bge-small-en-v1.5 with ~33M parameters) on a focused dataset.

Why this matters: The industry has normalized using trillion-parameter models to classify headlines, answer simple questions, or categorize text - tasks that don't require world knowledge, reasoning, or generative capabilities. This is computationally wasteful and environmentally costly. A properly fine-tuned small model can achieve comparable or better accuracy while using a fraction of the compute resources.

Our approach:

• Train on ~2,000 examples (few-shot learning with SetFit)
• Deploy small parameter models (e.g., ~33M params) vs. 100B-1T parameter alternatives
• Achieve specialized task performance without the overhead of general-purpose LLMs
• Reduce inference costs and latency by orders of magnitude

This is not about avoiding large models altogether - they're invaluable for complex reasoning tasks. But for targeted classification problems with labeled data, fine-tuning remains the professional, responsible choice.

Package Structure

This is the source code for the water-conflict-classifier Python package, published to PyPI.

classifier/
├── __init__.py                         # Package marker
├── data_prep.py                        # Data loading (for training-ready datasets)
├── training_logic.py                   # Core training logic (fixed hyperparameters)
├── training_logic_optuna.py            # Optuna hyperparameter search training
├── evaluation.py                       # Model evaluation & metrics
├── model_card.py                       # Model card generation
├── versioning.py                       # Experiment tracking & versioning
├── evals_upload.py                     # Upload evaluation results to HF
├── train_setfit_headline_classifier.py # Local training script
├── pyproject.toml                      # Package configuration
├── setup.py                            # Build configuration
└── README.md                           # This file

Note: Scripts that use this package (like cloud training with HF Jobs and dataset preparation) are in the ../scripts/ folder.

Local Training

Train on your own hardware with local data files.

Setup

1. Install the package in development mode:

uv pip install -e .
# or with regular pip:
pip install -e .

This installs the modules (data_prep, training_logic, etc.) so they can be imported.

2. Prepare training data:

Training data should be in ../data/:

• ../data/positives.csv - Water conflict headlines with labels
• ../data/negatives.csv - Non-water conflict headlines

Build negatives (if needed) - see the scripts README:

cd ../scripts
python fetch_serpapi_negatives.py
uv run generate_synthetic_negatives.py --calls 140
uv run verify_negatives.py ../data/real_headlines.csv ../data/synthetic_headlines.csv ../data/hard_negatives.csv
uv run build_negatives.py

3. Train:

python train_setfit_headline_classifier.py

Model saved to ./water-conflict-classifier/

Cloud Training

For training on HuggingFace Jobs (managed GPUs):

1. Prepare training dataset: Use ../scripts/prepare_training_dataset.py to preprocess, balance, and upload training-ready data to HF Hub
2. Train model: Two options:
   • ../scripts/train_on_hf.py - Standard training with fixed hyperparameters
   • ../scripts/train_on_hf_optuna.py - Optuna hyperparameter search (finds optimal settings automatically)

Optuna training searches on a small sample (~200 examples) for speed, then trains the final model on full data with best hyperparameters. Results are logged to the HF evals dataset for comparison.

See the scripts README for complete workflow.

Publishing to PyPI

See PUBLISHING.md for complete instructions on building and publishing the package.

Data Sources

The training data combines:

• Positive Examples: Water conflict headlines from Pacific Institute Water Conflict Chronology
• Negative Examples: As many as positives, about half real Google News titles (via SerpApi) and half synthetic headlines generated with Claude Haiku 5.5, all checked by an LLM judge:
  1. Hard Negatives (~35%): Water-related news that is not conflict (utilities, infrastructure, floods and droughts, research, cooperation, water sports) to prevent false positives
  2. Other Negatives (~65%): Conflict and security news with no water role, plus general news
• Held-out Negatives: 300 real + 300 synthetic negatives never used in training; the false positive rate on each shows whether the model keys on synthetic style

Hard Negatives Strategy

Without hard negatives, the model learns "water mentioned → conflict" instead of "water + violence → conflict". Hard negatives are water-related headlines that lack violence or conflict:

• Water infrastructure projects (dams, treatment plants)
• Scientific water research and technology
• Water conservation initiatives and conferences
• Environmental water management

These are tagged with priority_sample=True in the dataset and are ALWAYS included in training (never diluted by sampling). This ensures the model correctly distinguishes peaceful water news from actual water conflicts.

Resources

• HF Jobs Guide
• UV Script Format (used in train_on_hf.py)
• SetFit Documentation
• Pacific Institute Water Conflict Chronology

License

Copyright © 2025 Baobab Tech

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License.

You are free to use, share, and adapt this work for non-commercial purposes with appropriate attribution to Baobab Tech. For commercial licensing inquiries, please contact Baobab Tech.