README.md

---
title: GCMD Keyword Classifier MVP
emoji: 🌎
colorFrom: blue
colorTo: green
sdk: gradio
app_file: app.py
pinned: false
---

# GCMD Science Keyword Classifier

## Running a Small Classification Batch

Use `scripts/run_small_classification.py` to run a small manual MVP batch through the existing classification pipeline. The script loads `data/gcmd_hierarchy.json` and `data/articles.json`, processes the first valid articles up to `--limit`, and writes outputs to the selected `--output-dir`.

Fake-model dry run:

```bash
python scripts/run_small_classification.py --fake --limit 1 --output-dir outputs/small_run_fake
```

Fake-model run with 10 valid articles:

```bash
python scripts/run_small_classification.py --fake --limit 10 --output-dir outputs/small_run_fake_10
```

Live OpenAI run:

```bash
export OPENAI_API_KEY="your-api-key"
python scripts/run_small_classification.py --provider openai --model gpt-4o --limit 1 --output-dir outputs/small_run_gpt4o

python scripts/run_small_classification.py --provider openai --model gpt-5.5 --limit 1 --output-dir outputs/small_run_gpt5.5
```

Another live run using 10 valid articles:

```bash
export OPENAI_API_KEY="your-api-key"
python scripts/run_small_classification.py --provider openai --model gpt-4o --limit 10 --output-dir outputs/small_run_gpt4o
```

The selected output directory is created if it does not already exist. For example, with `--output-dir outputs/small_run_gpt4o`, the script writes the consolidated JSON output and review CSV beside each other:

```text
outputs/small_run_gpt4o/results.json
outputs/small_run_gpt4o/review_table.csv
```

The script also stores per-article checkpoint files and cache files under the same output directory. Source files under `data/` are treated as read-only and are not modified.

The frozen proof-of-concept app at `prototype/app_hf_poc.py` is not used by this script. The small-run command uses the MVP pipeline under `src/gcmd_classifier/`.

Accepted classifications in `results.json` and `review_table.csv` have passed deterministic vocabulary validation against the loaded GCMD hierarchy. That means their UUIDs, names, levels, canonical paths, and hierarchy relationships are structurally valid. It does not prove that the article scientifically supports the classification, so accepted results still need manual scientific review before operational use.