Replace auto-generated card with full model card

README.md

@@ -1,73 +1,143 @@
 ---
-library_name: transformers
 license: apache-2.0
 base_model: answerdotai/ModernBERT-base
+datasets:
+- biglam/on_the_books
+language:
+- en
+library_name: transformers
+pipeline_tag: text-classification
 tags:
+- text-classification
+- legal
+- glam
+- digital-humanities
+- jim-crow
+- north-carolina
+- legislation
 - generated_from_trainer
 metrics:
-- accuracy
 - f1
-- precision
-- recall
+- accuracy
+- roc_auc
 model-index:
 - name: dhd-demo
-  results: []
+  results:
+  - task:
+      type: text-classification
+      name: Text Classification
+    dataset:
+      name: biglam/on_the_books
+      type: biglam/on_the_books
+      split: train (held-out 10%)
+    metrics:
+    - type: accuracy
+      value: 0.9832
+    - type: f1
+      value: 0.9709
+    - type: precision
+      value: 0.9615
+    - type: recall
+      value: 0.9804
+    - type: f1_macro
+      value: 0.9796
+    - type: roc_auc
+      value: 0.9980
 ---
 
-<!-- This model card has been generated automatically according to the information the Trainer had access to. You
-should probably proofread and complete it, then remove this comment. -->
+# dhd-demo: ModernBERT Jim Crow law classifier
+
+Fine-tuned [`answerdotai/ModernBERT-base`](https://huggingface.co/answerdotai/ModernBERT-base) on
+[`biglam/on_the_books`](https://huggingface.co/datasets/biglam/on_the_books) to classify North
+Carolina session-law sections (1866–1967) as Jim Crow laws or not.
+
+Built as a live demo for the *Digital Humanities & Discovery* webinar
+(2026-05-05) showing end-to-end fine-tuning via `hf jobs`.
+
+## Labels
+
+- `0` = `no_jim_crow`
+- `1` = `jim_crow`
+
+## Training data
+
+[`biglam/on_the_books`](https://huggingface.co/datasets/biglam/on_the_books) — 1,785 expert-labeled chapter/section pairs from NC session
+laws, 512 positive / 1,273 negative. Split 90/10 (stratified) for train/eval.
+Class imbalance handled with inverse-frequency cross-entropy weights.
+
+## Training setup
 
-# dhd-demo
+| | |
+|---|---|
+| Base model | `answerdotai/ModernBERT-base` |
+| Epochs | 4 |
+| Batch size | 16 |
+| Learning rate | 5e-5 |
+| Warmup steps | 50 |
+| Weight decay | 0.01 |
+| Max sequence length | 1024 |
+| Precision | bf16 |
+| Loss | weighted cross-entropy |
+| Seed | 42 |
+| Hardware | 1× NVIDIA L4 (24 GB) via `hf jobs` |
+| Train runtime | 223 s |
 
-This model is a fine-tuned version of [answerdotai/ModernBERT-base](https://huggingface.co/answerdotai/ModernBERT-base) on an unknown dataset.
-It achieves the following results on the evaluation set:
-- Loss: 0.0949
-- Accuracy: 0.9832
-- F1: 0.9709
-- Precision: 0.9615
-- Recall: 0.9804
-- F1 Macro: 0.9796
-- Roc Auc: 0.9980
+## Evaluation (held-out 10% split, n=179)
 
-## Model description
+| Metric | Value |
+|---|---|
+| Accuracy | 0.9832 |
+| F1 (positive class) | 0.9709 |
+| Precision | 0.9615 |
+| Recall | 0.9804 |
+| F1 (macro) | 0.9796 |
+| ROC-AUC | 0.9980 |
 
-More information needed
+### Per-epoch results
 
-## Intended uses & limitations
+| Epoch | Train loss | Val loss | Accuracy | F1 | Precision | Recall | ROC-AUC |
+|------:|-----------:|---------:|---------:|----:|----------:|-------:|--------:|
+| 1 | 0.0856 | 0.1061 | 0.9553 | 0.9273 | 0.8644 | 1.0000 | 0.9960 |
+| 2 | 0.0353 | 0.0538 | 0.9777 | 0.9615 | 0.9434 | 0.9804 | 0.9989 |
+| 3 | 0.0015 | 0.1310 | 0.9777 | 0.9600 | 0.9796 | 0.9412 | 0.9980 |
+| 4 | 0.0019 | 0.0949 | **0.9832** | **0.9709** | 0.9615 | 0.9804 | 0.9980 |
 
-More information needed
+## Usage
 
-## Training and evaluation data
+```python
+from transformers import pipeline
 
-More information needed
+clf = pipeline("text-classification", model="davanstrien/dhd-demo")
+clf("All schools for the white and colored races shall be kept separate.")
+```
 
-## Training procedure
+## Limitations
 
-### Training hyperparameters
+- Trained on **North Carolina** laws, 1866–1967. Will not transfer cleanly to
+  other jurisdictions or modern legal language.
+- The training labels reflect what named expert sources / project staff
+  flagged. The negative class is "not flagged," not "verified
+  non-discriminatory."
+- OCR noise from period scans is present in training and will be present at
+  inference time on similar corpora.
+- Eval set is small (n=179); treat the high metrics as encouraging but
+  bounded by sample size.
 
-The following hyperparameters were used during training:
-- learning_rate: 5e-05
-- train_batch_size: 16
-- eval_batch_size: 32
-- seed: 42
-- optimizer: Use OptimizerNames.ADAMW_TORCH_FUSED with betas=(0.9,0.999) and epsilon=1e-08 and optimizer_args=No additional optimizer arguments
-- lr_scheduler_type: linear
-- lr_scheduler_warmup_steps: 50
-- num_epochs: 4
+See the [dataset card](https://huggingface.co/datasets/biglam/on_the_books) for full
+context, including the *Algorithms of Resistance* framing of the original
+**On the Books** project at UNC Chapel Hill Libraries.
 
-### Training results
+## Citation
 
-| Training Loss | Epoch | Step | Validation Loss | Accuracy | F1     | Precision | Recall | F1 Macro | Roc Auc |
-|:-------------:|:-----:|:----:|:---------------:|:--------:|:------:|:---------:|:------:|:--------:|:-------:|
-| 0.0856        | 1.0   | 101  | 0.1061          | 0.9553   | 0.9273 | 0.8644    | 1.0    | 0.9475   | 0.9960  |
-| 0.0353        | 2.0   | 202  | 0.0538          | 0.9777   | 0.9615 | 0.9434    | 0.9804 | 0.9729   | 0.9989  |
-| 0.0015        | 3.0   | 303  | 0.1310          | 0.9777   | 0.96   | 0.9796    | 0.9412 | 0.9722   | 0.9980  |
-| 0.0019        | 4.0   | 404  | 0.0949          | 0.9832   | 0.9709 | 0.9615    | 0.9804 | 0.9796   | 0.9980  |
+Please cite the original project:
 
+> On the Books: Jim Crow and Algorithms of Resistance.
+> University of North Carolina at Chapel Hill Libraries.
+> https://onthebooks.lib.unc.edu — DOI: https://doi.org/10.17615/5c4g-sd44
 
-### Framework versions
+## Framework versions
 
 - Transformers 5.7.0
-- Pytorch 2.11.0+cu130
+- PyTorch 2.11.0+cu130
 - Datasets 4.8.5
 - Tokenizers 0.22.2