Upload folder using huggingface_hub

README.md

@@ -0,0 +1,139 @@
+---
+license: mit
+tags:
+- text-classification
+- regression
+- bert
+- orality
+- linguistics
+- rhetorical-analysis
+language:
+- en
+metrics:
+- mae
+- r2
+base_model:
+- google-bert/bert-base-uncased
+pipeline_tag: text-classification
+library_name: transformers
+datasets:
+- custom
+model-index:
+- name: bert-orality-regressor
+  results:
+  - task:
+      type: text-classification
+      name: Orality Regression
+    metrics:
+    - type: mae
+      value: 0.0786
+      name: Mean Absolute Error
+    - type: r2
+      value: 0.756
+      name: R² Score
+---
+
+# Havelock Orality Regressor
+
+BERT-based regression model that scores text on the **oral–literate spectrum** (0–1), grounded in Walter Ong's *Orality and Literacy* (1982).
+
+Given a passage of text, the model outputs a continuous score where higher values indicate greater orality (spoken, performative, additive discourse) and lower values indicate greater literacy (analytic, subordinative, abstract discourse).
+
+## Model Details
+
+| Property | Value |
+|----------|-------|
+| Base model | `bert-base-uncased` |
+| Architecture | `BertForSequenceClassification` (num_labels=1) |
+| Task | Single-value regression (MSE loss) |
+| Output range | Continuous (not clamped) |
+| Max sequence length | 512 tokens |
+| Best MAE | **0.0786** |
+| R² | **0.756** |
+| Parameters | ~109M |
+
+## Usage
+```python
+from transformers import AutoTokenizer, AutoModelForSequenceClassification
+import torch
+
+model_name = "HavelockAI/bert-orality-regressor"
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+model = AutoModelForSequenceClassification.from_pretrained(model_name)
+
+text = "Tell me, O Muse, of that ingenious hero who travelled far and wide"
+inputs = tokenizer(text, return_tensors="pt", truncation=True, max_length=512)
+
+with torch.no_grad():
+    score = model(**inputs).logits.squeeze().item()
+
+print(f"Orality score: {score:.3f}")
+```
+
+### Score Interpretation
+
+| Score | Register |
+|-------|----------|
+| 0.8–1.0 | Highly oral — epic poetry, sermons, rap, oral storytelling |
+| 0.6–0.8 | Oral-dominant — speeches, podcasts, conversational prose |
+| 0.4–0.6 | Mixed — journalism, blog posts, dialogue-heavy fiction |
+| 0.2–0.4 | Literate-dominant — essays, expository prose |
+| 0.0–0.2 | Highly literate — academic papers, legal texts, philosophy |
+
+## Training
+
+### Data
+
+The model was trained on a curated corpus of documents annotated with orality scores using a multi-pass scoring system. Scores were originally on a 0–100 scale and normalized to 0–1 for training. The corpus draws from Project Gutenberg, textfiles.com, Reddit, and Wikipedia talk pages, representing a range of registers from highly oral to highly literate.
+
+An 80/20 train/test split was used (random seed 42).
+
+### Hyperparameters
+
+| Parameter | Value |
+|-----------|-------|
+| Epochs | 3 |
+| Batch size | 8 |
+| Learning rate | 2e-5 |
+| Optimizer | AdamW |
+| LR schedule | Linear warmup (10% of total steps) |
+| Gradient clipping | 1.0 |
+| Loss | MSE (via HF `num_labels=1`) |
+
+### Training Metrics
+
+| Epoch | Loss | MAE | R² |
+|-------|------|-----|-----|
+| 1 | 0.0382 | 0.1443 | 0.317 |
+| 2 | 0.0187 | 0.0852 | 0.722 |
+| 3 | 0.0128 | 0.0786 | 0.756 |
+
+## Limitations
+
+- **Short training**: Only 3 epochs — likely undertrained. Further epochs or hyperparameter search would probably improve R².
+- **No sigmoid clamping**: The model can output values outside [0, 1]. Consumers should clamp if needed.
+- **Domain coverage**: Training corpus skews historical/literary. Performance on modern social media, code-switched text, or non-English text is untested.
+- **Document length**: Texts longer than 512 tokens are truncated. The model sees only the first ~400 words, which may not be representative of longer documents.
+- **Regression target subjectivity**: Orality scores involve human judgment; inter-annotator agreement bounds the ceiling for model performance.
+
+## Theoretical Background
+
+The oral–literate spectrum follows Ong's framework, which characterizes oral discourse as additive, aggregative, redundant, agonistic, empathetic, and situational, while literate discourse is subordinative, analytic, abstract, distanced, and context-free. The model learns to place text along this continuum from document-level annotations informed by 72 specific rhetorical markers (36 oral, 36 literate).
+
+## Citation
+```bibtex
+@misc{havelock2026regressor,
+  title={Havelock Orality Regressor},
+  author={Havelock AI},
+  year={2026},
+  url={https://huggingface.co/HavelockAI/bert-orality-regressor}
+}
+```
+
+## References
+
+- Ong, Walter J. *Orality and Literacy: The Technologizing of the Word*. Routledge, 1982.
+
+---
+
+*Model version: 33b6eccc · Trained: February 2026*