Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+images/confusion_matrix.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,188 @@
+---
+# Model Card Metadata (YAML Front Matter)
+license: mit
+base_model: microsoft/deberta-v3-small
+tags:
+  - text-classification
+  - character-analysis
+  - plot-arc
+  - narrative-analysis
+  - deberta
+  - transformers
+language: en
+datasets:
+  - custom/plot-arc-balanced-101k
+metrics:
+  - accuracy
+  - f1
+  - precision
+  - recall
+model_type: sequence-classification
+pipeline_tag: text-classification
+widget:
+  - text: "Sir Galahad embarks on a perilous quest to retrieve the stolen Crown of Ages."
+    example_title: "External Arc Example"
+  - text: "Maria struggles with crippling self-doubt after her mother's harsh words."
+    example_title: "Internal Arc Example"
+  - text: "Captain Torres must infiltrate enemy lines while battling his own cowardice."
+    example_title: "Both Arc Example"
+  - text: "A baker who makes bread every morning in his village shop."
+    example_title: "No Arc Example"
+library_name: transformers
+---
+
+# Plot Arc Classifier - DeBERTa Small
+
+A fine-tuned DeBERTa-v3-small model for classifying character plot arc types in narrative text.
+
+## Model Details
+
+### Model Description
+
+This model classifies character descriptions into four plot arc categories:
+- **NONE (0)**: No discernible character development or plot arc
+- **INTERNAL (1)**: Character growth driven by internal conflict/psychology  
+- **EXTERNAL (2)**: Character arc driven by external events/missions
+- **BOTH (3)**: Character arc with both internal conflict and external drivers
+
+**Model Type:** Text Classification (Sequence Classification)  
+**Base Model:** microsoft/deberta-v3-small (~60M parameters)  
+**Language:** English  
+**License:** MIT  
+
+### Model Architecture
+
+- **Base:** DeBERTa-v3-Small (60M parameters)
+- **Task:** 4-class sequence classification
+- **Input:** Character descriptions (max 512 tokens)
+- **Output:** Classification logits + probabilities for 4 classes
+
+## Training Data
+
+### Dataset Statistics
+- **Total Examples:** 101,348
+- **Training Split:** 91,213 examples (90%)
+- **Validation Split:** 10,135 examples (10%)
+- **Perfect Class Balance:** 25,337 examples per class
+
+### Data Sources
+- Systematic scanning of 1.8M+ character descriptions  
+- LLM validation using Llama-3.2-3B for quality assurance
+- SHA256-based deduplication to prevent data leakage
+- Carefully curated and balanced dataset across all plot arc types
+
+### Class Distribution
+| Class | Count | Percentage |
+|-------|-------|------------|
+| NONE | 25,337 | 25% |
+| INTERNAL | 25,337 | 25% |
+| EXTERNAL | 25,337 | 25% |
+| BOTH | 25,337 | 25% |
+
+## Performance
+
+### Key Metrics
+- **Accuracy:** 0.7286
+- **F1 (Weighted):** 0.7283
+- **F1 (Macro):** 0.7275
+
+### Per-Class Performance
+| Class | Precision | Recall | F1-Score | Support |
+|-------|-----------|--------|----------|---------|
+| NONE | 0.697 | 0.613 | 0.653 | 2,495 |
+| INTERNAL | 0.677 | 0.683 | 0.680 | 2,571 |
+| EXTERNAL | 0.892 | 0.882 | 0.887 | 2,568 |
+| BOTH | 0.652 | 0.732 | 0.690 | 2,501 |
+
+### Training Details
+- **Training Time:** 9.7 hours on Apple Silicon MPS
+- **Final Training Loss:** 0.635
+- **Epochs:** 3.86 (early stopping)
+- **Batch Size:** 16 (effective: 32 with gradient accumulation)  
+- **Learning Rate:** 2e-5 with warmup
+- **Optimizer:** AdamW with weight decay (0.01)
+
+
+## Confusion Matrix
+
+![Confusion Matrix](images/confusion_matrix.png)
+
+## Usage
+
+### Basic Usage
+
+```python
+from transformers import DebertaV2Tokenizer, DebertaV2ForSequenceClassification
+import torch
+
+# Load model and tokenizer
+model_name = "plot-arc-classifier-deberta-small"
+tokenizer = DebertaV2Tokenizer.from_pretrained(model_name)
+model = DebertaV2ForSequenceClassification.from_pretrained(model_name)
+
+# Example text
+text = "Sir Galahad embarks on a perilous quest to retrieve the stolen Crown of Ages."
+
+# Tokenize and predict
+inputs = tokenizer(text, return_tensors="pt", truncation=True, padding=True, max_length=512)
+with torch.no_grad():
+    outputs = model(**inputs)
+    probabilities = torch.softmax(outputs.logits, dim=-1)
+    predicted_class = torch.argmax(probabilities, dim=-1)
+
+# Class mapping
+class_names = ['NONE', 'INTERNAL', 'EXTERNAL', 'BOTH']
+prediction = class_names[predicted_class.item()]
+confidence = probabilities[0][predicted_class].item()
+
+print(f"Predicted class: {prediction} (confidence: {confidence:.3f})")
+```
+
+### Pipeline Usage
+
+```python
+from transformers import pipeline
+
+classifier = pipeline(
+    "text-classification", 
+    model="plot-arc-classifier-deberta-small",
+    return_all_scores=True
+)
+
+result = classifier("Captain Torres must infiltrate enemy lines while battling his own cowardice.")
+print(result)
+```
+
+## Limitations
+
+- **Domain:** Optimized for character descriptions in narrative fiction
+- **Length:** Maximum 512 tokens (longer texts are truncated)
+- **Language:** English only
+- **Context:** Works best with character-focused descriptions rather than plot summaries
+- **Ambiguity:** Some edge cases may be inherently ambiguous between INTERNAL/BOTH
+
+## Ethical Considerations
+
+- **Bias:** Training data may contain genre/cultural biases toward certain character archetypes
+- **Interpretation:** Classifications reflect Western narrative theory; other storytelling traditions may not map perfectly
+- **Automation:** Should complement, not replace, human literary analysis
+
+## Citation
+
+```bibtex
+@model{plot_arc_classifier_2025,
+  title={Plot Arc Classifier - DeBERTa Small},
+  author={Claude Code Assistant},
+  year={2025},
+  url={https://github.com/your-org/plot-arc-classifier},
+  note={Fine-tuned DeBERTa-v3-small for character plot arc classification}
+}
+```
+
+## Model Card Contact
+
+For questions about this model, please open an issue in the repository or contact the maintainers.
+
+---
+
+*Model trained on 2025-09-02 using transformers library.*

added_tokens.json

@@ -0,0 +1,3 @@
+{
+  "[MASK]": 128000
+}

config.json

@@ -0,0 +1,50 @@
+{
+  "architectures": [
+    "DebertaV2ForSequenceClassification"
+  ],
+  "attention_probs_dropout_prob": 0.1,
+  "bos_token_id": 1,
+  "dtype": "float32",
+  "eos_token_id": 2,
+  "hidden_act": "gelu",
+  "hidden_dropout_prob": 0.1,
+  "hidden_size": 768,
+  "id2label": {
+    "0": "LABEL_0",
+    "1": "LABEL_1",
+    "2": "LABEL_2",
+    "3": "LABEL_3"
+  },
+  "initializer_range": 0.02,
+  "intermediate_size": 3072,
+  "label2id": {
+    "LABEL_0": 0,
+    "LABEL_1": 1,
+    "LABEL_2": 2,
+    "LABEL_3": 3
+  },
+  "layer_norm_eps": 1e-07,
+  "legacy": true,
+  "max_position_embeddings": 512,
+  "max_relative_positions": -1,
+  "model_type": "deberta-v2",
+  "norm_rel_ebd": "layer_norm",
+  "num_attention_heads": 12,
+  "num_hidden_layers": 6,
+  "pad_token_id": 0,
+  "pooler_dropout": 0,
+  "pooler_hidden_act": "gelu",
+  "pooler_hidden_size": 768,
+  "pos_att_type": [
+    "p2c",
+    "c2p"
+  ],
+  "position_biased_input": false,
+  "position_buckets": 256,
+  "problem_type": "single_label_classification",
+  "relative_attention": true,
+  "share_att_key": true,
+  "transformers_version": "4.56.0",
+  "type_vocab_size": 0,
+  "vocab_size": 128100
+}

evaluation_results.json

@@ -0,0 +1,78 @@
+{
+  "model_info": {
+    "base_model": "microsoft/deberta-v3-small",
+    "model_type": "sequence-classification",
+    "num_classes": 4,
+    "class_names": [
+      "NONE",
+      "INTERNAL",
+      "EXTERNAL",
+      "BOTH"
+    ]
+  },
+  "performance": {
+    "accuracy": 0.7285643808584115,
+    "f1_weighted": 0.7283043705111875,
+    "f1_macro": 0.7275298614210632
+  },
+  "per_class_metrics": {
+    "NONE": {
+      "precision": 0.6973564266180492,
+      "recall": 0.6132264529058116,
+      "f1-score": 0.6525911708253359,
+      "support": 2495.0
+    },
+    "INTERNAL": {
+      "precision": 0.6770712909441233,
+      "recall": 0.6833916763905096,
+      "f1-score": 0.6802168021680217,
+      "support": 2571.0
+    },
+    "EXTERNAL": {
+      "precision": 0.8924773532886964,
+      "recall": 0.882398753894081,
+      "f1-score": 0.8874094380262385,
+      "support": 2568.0
+    },
+    "BOTH": {
+      "precision": 0.6522978268614179,
+      "recall": 0.7321071571371451,
+      "f1-score": 0.6899020346646572,
+      "support": 2501.0
+    }
+  },
+  "confusion_matrix": [
+    [
+      1530,
+      388,
+      160,
+      417
+    ],
+    [
+      323,
+      1757,
+      45,
+      446
+    ],
+    [
+      131,
+      58,
+      2266,
+      113
+    ],
+    [
+      210,
+      392,
+      68,
+      1831
+    ]
+  ],
+  "training_info": {
+    "total_examples": 101348,
+    "train_examples": 91213,
+    "val_examples": 10135,
+    "examples_per_class": 25337,
+    "training_time_hours": 9.7,
+    "final_epoch": 3.86
+  }
+}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b9344c35266b171e7f56af4f92b3a0cc28964da72beb685d5f4f11b56d895a86
+size 567604704

requirements.txt

@@ -0,0 +1,6 @@
+torch>=2.0.0
+transformers>=4.30.0
+numpy>=1.21.0
+scikit-learn>=1.0.0
+matplotlib>=3.5.0
+seaborn>=0.11.0

special_tokens_map.json

@@ -0,0 +1,15 @@
+{
+  "bos_token": "[CLS]",
+  "cls_token": "[CLS]",
+  "eos_token": "[SEP]",
+  "mask_token": "[MASK]",
+  "pad_token": "[PAD]",
+  "sep_token": "[SEP]",
+  "unk_token": {
+    "content": "[UNK]",
+    "lstrip": false,
+    "normalized": true,
+    "rstrip": false,
+    "single_word": false
+  }
+}

spm.model

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c679fbf93643d19aab7ee10c0b99e460bdbc02fedf34b92b05af343b4af586fd
+size 2464616

test_model.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""
+Test script for plot arc classifier
+"""
+
+import json
+import torch
+from transformers import DebertaV2Tokenizer, DebertaV2ForSequenceClassification
+
+def load_tests():
+    """Load synthetic test cases"""
+    with open('tests/synthetic_tests.json', 'r') as f:
+        return json.load(f)
+
+def run_tests():
+    """Run all synthetic tests"""
+    print("Loading model...")
+    tokenizer = DebertaV2Tokenizer.from_pretrained('.')
+    model = DebertaV2ForSequenceClassification.from_pretrained('.')
+    
+    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+    model.to(device)
+    model.eval()
+    
+    class_names = ['NONE', 'INTERNAL', 'EXTERNAL', 'BOTH']
+    class_to_idx = {name: idx for idx, name in enumerate(class_names)}
+    
+    tests = load_tests()
+    
+    correct = 0
+    total = len(tests)
+    
+    print(f"Running {total} synthetic tests...\n")
+    
+    for i, test in enumerate(tests, 1):
+        text = test['description']
+        expected = test['expected_class']
+        expected_idx = class_to_idx[expected]
+        
+        # Predict
+        inputs = tokenizer(text, return_tensors="pt", truncation=True, padding=True, max_length=512)
+        inputs = {k: v.to(device) for k, v in inputs.items()}
+        
+        with torch.no_grad():
+            outputs = model(**inputs)
+            probabilities = torch.softmax(outputs.logits, dim=-1)
+            predicted_idx = torch.argmax(probabilities, dim=-1).item()
+            confidence = probabilities[0][predicted_idx].item()
+        
+        predicted = class_names[predicted_idx]
+        is_correct = predicted == expected
+        
+        if is_correct:
+            correct += 1
+            status = "✅ PASS"
+        else:
+            status = "❌ FAIL"
+        
+        print(f"Test {i:2d}: {status}")
+        print(f"  Text: {text[:100]}{'...' if len(text) > 100 else ''}")
+        print(f"  Expected: {expected} | Predicted: {predicted} (conf: {confidence:.3f})")
+        print(f"  Reasoning: {test['reasoning']}")
+        print()
+    
+    accuracy = correct / total
+    print(f"Results: {correct}/{total} correct ({accuracy:.1%})")
+    
+    return accuracy
+
+if __name__ == "__main__":
+    run_tests()

tests/synthetic_tests.json

@@ -0,0 +1,92 @@
+[
+  {
+    "description": "A baker who makes bread every morning in his small village shop.",
+    "expected_class": "NONE",
+    "reasoning": "No character development or conflict indicated"
+  },
+  {
+    "description": "Sir Galahad embarks on a perilous quest to retrieve the stolen Crown of Ages from the dragon's lair.",
+    "expected_class": "EXTERNAL",
+    "reasoning": "Clear external mission/quest with specific objective"
+  },
+  {
+    "description": "Maria struggles with crippling self-doubt after her mother's harsh words echo in her mind daily.",
+    "expected_class": "INTERNAL",
+    "reasoning": "Internal psychological conflict, no external events"
+  },
+  {
+    "description": "Captain Torres must infiltrate enemy lines while battling his own cowardice from past failures.",
+    "expected_class": "BOTH",
+    "reasoning": "External mission (infiltration) + internal conflict (overcoming cowardice)"
+  },
+  {
+    "description": "Dr. Elise Chen, a brilliant neurosurgeon whose perfectionist nature stems from childhood trauma, must perform an experimental procedure to save her estranged brother while confronting the guilt that has haunted her for decades.",
+    "expected_class": "BOTH",
+    "reasoning": "Complex case: external medical crisis + deep internal psychological journey"
+  },
+  {
+    "description": "The ancient librarian who has catalogued every book in the Grand Archive for three centuries, maintaining perfect order and silence.",
+    "expected_class": "NONE",
+    "reasoning": "Static character with no indicated change or conflict despite intriguing background"
+  },
+  {
+    "description": "Commander Vex leads the final assault against the rebel stronghold, knowing that victory means destroying the city where his daughter lives.",
+    "expected_class": "BOTH",
+    "reasoning": "External military objective complicated by internal moral conflict"
+  },
+  {
+    "description": "A merchant who travels between kingdoms, buying low and selling high, always seeking the next profitable deal.",
+    "expected_class": "NONE",
+    "reasoning": "Routine activity without character growth or meaningful conflict"
+  },
+  {
+    "description": "Zara must decode the ancient prophecy before the lunar eclipse triggers the apocalypse, while wrestling with visions that make her question her own sanity.",
+    "expected_class": "BOTH",
+    "reasoning": "External time-pressure quest + internal psychological struggle"
+  },
+  {
+    "description": "The assassin who kills without emotion, following contracts with mechanical precision, never questioning orders or feeling remorse.",
+    "expected_class": "NONE",
+    "reasoning": "No internal conflict or character development despite dramatic profession"
+  },
+  {
+    "description": "Elena discovers her recurring nightmares are actually suppressed memories of witnessing her father's murder, forcing her to relive the trauma to identify the killer.",
+    "expected_class": "INTERNAL",
+    "reasoning": "Psychological journey of memory recovery and trauma processing, no external plot"
+  },
+  {
+    "description": "Prince Aldric must unite the warring clans before the demon army arrives, though he secretly fears he's too weak to lead and will fail like his father.",
+    "expected_class": "BOTH",
+    "reasoning": "External political/military crisis + internal self-doubt and leadership anxiety"
+  },
+  {
+    "description": "A shape-shifting entity that observes human civilization across millennia, adapting its form but never truly understanding emotion or purpose.",
+    "expected_class": "INTERNAL",
+    "reasoning": "Subtle: the struggle to understand emotion/purpose is internal character development"
+  },
+  {
+    "description": "Detective Morgan investigates a series of murders that mirror her own childhood trauma, each clue forcing her to confront buried memories while racing to catch the killer before he strikes again.",
+    "expected_class": "BOTH",
+    "reasoning": "External investigation/race against time + internal trauma processing"
+  },
+  {
+    "description": "An immortal being who grants wishes to mortals, following cosmic rules without deviation or personal desire.",
+    "expected_class": "NONE",
+    "reasoning": "No change or conflict despite supernatural nature - purely functional role"
+  },
+  {
+    "description": "The village healer who tends to every wound and illness with the same gentle care, asking nothing in return, content in her service to others.",
+    "expected_class": "NONE",
+    "reasoning": "Static, fulfilled character with no indicated conflict or growth arc"
+  },
+  {
+    "description": "Kai realizes that saving the world requires sacrificing the one person he loves most, but cannot bring himself to make the choice that logic demands.",
+    "expected_class": "INTERNAL",
+    "reasoning": "Pure internal moral/emotional conflict - the external 'saving world' is context, not plot"
+  },
+  {
+    "description": "The time-traveling historian who documents major events across eras, maintaining strict neutrality and never interfering with the timeline's natural course.",
+    "expected_class": "NONE",
+    "reasoning": "Observer role with no character development or conflict despite extraordinary circumstances"
+  }
+]

tokenizer_config.json

@@ -0,0 +1,59 @@
+{
+  "added_tokens_decoder": {
+    "0": {
+      "content": "[PAD]",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "1": {
+      "content": "[CLS]",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "2": {
+      "content": "[SEP]",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "3": {
+      "content": "[UNK]",
+      "lstrip": false,
+      "normalized": true,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    },
+    "128000": {
+      "content": "[MASK]",
+      "lstrip": false,
+      "normalized": false,
+      "rstrip": false,
+      "single_word": false,
+      "special": true
+    }
+  },
+  "bos_token": "[CLS]",
+  "clean_up_tokenization_spaces": false,
+  "cls_token": "[CLS]",
+  "do_lower_case": false,
+  "eos_token": "[SEP]",
+  "extra_special_tokens": {},
+  "mask_token": "[MASK]",
+  "model_max_length": 1000000000000000019884624838656,
+  "pad_token": "[PAD]",
+  "sep_token": "[SEP]",
+  "sp_model_kwargs": {},
+  "split_by_punct": false,
+  "tokenizer_class": "DebertaV2Tokenizer",
+  "unk_token": "[UNK]",
+  "vocab_type": "spm"
+}

training_args.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f983cf6452d26be88ab8737aa8462f06399ec39bd8cd32e41bf985dbd6ba16e9
+size 5777