Add model card

README.md

@@ -20,9 +20,9 @@ tags:
 
 A compact GPT-2 Small model (~117M params) **trained from scratch** on historical London texts (1500–1850). Fast to run on CPU, and supports NVIDIA (CUDA) and AMD (ROCm) GPUs.
 
-**Note**:
- * This model was **trained from scratch** - not fine-tuned from existing models.
- * This page includes simple **virtual-env setup**, **install choices for CPU/CUDA/ROCm**, and an **auto-device inference** example so anyone can get going quickly.
+> **Note**: This model was **trained from scratch** - not fine-tuned from existing models.
+
+> This page includes simple **virtual-env setup**, **install choices for CPU/CUDA/ROCm**, and an **auto-device inference** example so anyone can get going quickly.
 
 ---
 
@@ -31,39 +31,17 @@ A compact GPT-2 Small model (~117M params) **trained from scratch** on historica
 This is a **Small Language Model (SLM)** version of the London Historical LLM, **trained from scratch** using GPT-2 Small architecture on historical London texts with a custom historical tokenizer. The model was built from the ground up, not fine-tuned from existing models.
 
 ### Key Features
-- ~117M parameters (vs ~354M in the full model)
-- Custom historical tokenizer (≈30k vocab)
-- London-specific context awareness and historical language patterns (e.g., *thou, thee, hath*)
-- Lower memory footprint and faster inference on commodity hardware
-- **Trained from scratch** - not fine-tuned from existing models
-
----
-
-## Repository
-
-The complete source code, training scripts, and documentation for this model are available on GitHub:
-
-** [https://github.com/bahree/helloLondon](https://github.com/bahree/helloLondon)**
-
-This repository includes:
-- Complete data collection pipeline for 1500-1850 historical English
-- Custom tokenizer optimized for historical text  
-- Training infrastructure with GPU optimization
-- Evaluation and deployment tools
-- Comprehensive documentation and examples
-
-### Quick Start with Repository
-```bash
-git clone https://github.com/bahree/helloLondon.git
-cd helloLondon
-python 06_inference/test_published_models.py --model_type slm
-```
+- ~117M parameters (vs ~354M in the full model)  
+- Custom historical tokenizer (≈30k vocab)  
+- London-specific context awareness and historical language patterns (e.g., *thou, thee, hath*)  
+- Lower memory footprint and faster inference on commodity hardware  
+- **Trained from scratch** - not fine-tuned from existing models  
 
 ---
 
 ## 🧪 Intended Use & Limitations
 
-**Use cases:** historical-style narrative generation, prompt-based exploration of London themes (1500–1850), creative writing aids.
+**Use cases:** historical-style narrative generation, prompt-based exploration of London themes (1500–1850), creative writing aids.  
 **Limitations:** may produce anachronisms or historically inaccurate statements; smaller models have less complex reasoning than larger LLMs. Validate outputs before downstream use.
 
 ---
@@ -135,7 +113,61 @@ Upgrade basics, then install Hugging Face libs:
 
 ```bash
 python -m pip install -U pip setuptools wheel
-python -m pip install "transformers[torch]" accelerate safetensors
+python -m pip install "transformers" "accelerate" "safetensors"
+```
+
+---
+
+## Install **one** PyTorch variant (CPU / NVIDIA / AMD)
+
+Use **one** of the commands below. For the most accurate command per OS/accelerator and version, prefer PyTorch's **Get Started** selector.
+
+### A) CPU-only (Linux/Windows/macOS)
+
+```bash
+pip install torch --index-url https://download.pytorch.org/whl/cpu
+```
+
+### B) NVIDIA GPU (CUDA)
+
+Pick the CUDA series that matches your system (examples below):
+
+```bash
+# CUDA 12.6
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126
+
+# CUDA 12.4
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
+
+# CUDA 11.8
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
+```
+
+### C) AMD GPU (ROCm, **Linux-only**)
+
+Install the ROCm build matching your ROCm runtime (examples):
+
+```bash
+# ROCm 6.3
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.3
+
+# ROCm 6.2 (incl. 6.2.x)
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.2.4
+
+# ROCm 6.1
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.1
+```
+
+**Quick sanity check**
+
+```bash
+python - <<'PY'
+import torch
+print("torch:", torch.__version__)
+print("GPU available:", torch.cuda.is_available())
+if torch.cuda.is_available():
+    print("device:", torch.cuda.get_device_name(0))
+PY
 ```
 
 ---
@@ -170,36 +202,20 @@ outputs = model.generate(
     no_repeat_ngram_size=3,
     pad_token_id=tokenizer.eos_token_id,
     eos_token_id=tokenizer.eos_token_id,
+    early_stopping=True,
 )
+
 print(tokenizer.decode(outputs[0], skip_special_tokens=True))
 ```
 
----
-
-## 📖 **Sample Output**
-
-**Prompt:** "In the year 1834, I walked through the streets of London and witnessed"
-
-**Generated Text:**
-> "In the year 1834, I walked through the streets of London and witnessed a scene in which some of those who had no inclination to come in contact with him took part in his discourse. It was on this occasion that I perceived that he had been engaged in some new business connected with the house, but for some days it had not taken place, nor did he appear so desirous of pursuing any further display of interest. The result was, however, that if he came in contact witli any one else in company with him he must be regarded as an old acquaintance or companion, and when he came to the point of leaving, I had no leisure to take up his abode. The same evening, having ram ##bled about the streets, I observed that the young man who had just arrived from a neighbouring village at the time, was enjoying himself at a certain hour, and I thought that he would sleep quietly until morning, when he said in a low voice — " You are coming. Miss — I have come from the West Indies. " Then my father bade me go into the shop, and bid me put on his spectacles, which he had in his hand; but he replied no: the room was empty, and he did not want to see what had passed. When I asked him the cause of all this conversation, he answered in the affirmative, and turned away, saying that as soon as the lad could recover, the sight of him might be renewed. " Well, Mr. , " said I, " you have got a little more of your wages, do you? " " No, sir, thank 'ee kindly, " returned the boy, " but we don 't want to pay the poor rates. We"
-
----
-
 ## 🧪 **Testing Your Model**
 
-### **Quick Testing (Recommended First)**
+### **Quick Testing (10 Automated Prompts)**
 ```bash
-# Test the published model with 10 automated prompts
+# Test with 10 automated historical prompts
 python 06_inference/test_published_models.py --model_type slm
 ```
 
-**What this does:**
-- Loads model from `bahree/london-historical-slm`
-- Tests 10 historical prompts automatically
-- Shows model info (vocab size, parameters, etc.)
-- Uses SLM-optimized generation parameters
-- **No user interaction** - just runs and reports results
-
 **Expected Output:**
 ```
 🧪 Testing SLM Model: bahree/london-historical-slm
@@ -214,13 +230,10 @@ python 06_inference/test_published_models.py --model_type slm
    Max length: 512
 
 🎯 Testing generation with 10 prompts...
-
---- Test 1/10 ---
-Prompt: In the year 1834, I walked through the streets of London and witnessed
-Generated: . a scene in which some of those who had no inclination to come in contact with him took part in his discourse . It was on this occasion that I perceived that he had been engaged in some new business connected with the house , but for some days it had not taken place , nor did he appear so desirous of pursuing any further display of interest . The result was , however , that if he came in contact witli any one else in company with him he must be regarded as an old acquaintance or companion , and when he came to the point of leaving , I had no leisure to take up his abode . The same evening , having ram ##bled about the streets , I observed that the young man who had just arrived from a neighbouring village at the time , was enjoying himself at a certain hour , and I thought that he would sleep quietly until morning , when he said in a low voice — " You are coming . Miss — I have come from the West Indies . " Then my father bade me go into the shop , and bid me put on his spectacles , which he had in his hand ; but he replied no : the room was empty , and he did not want to see what had passed . When I asked him the cause of all this conversation , he answered in the affirmative , and turned away , saying that as soon as the lad could recover , the sight of him might be renewed . " Well , Mr . , " said I , " you have got a little more of your wages , do you ? " " No , sir , thank ' ee kindly , " returned the boy , " but we don ' t want to pay the poor rates . We
+[10 automated tests with historical text generation]
 ```
 
-### **Interactive Testing (For Exploration)**
+### **Interactive Testing**
 ```bash
 # Interactive mode for custom prompts
 python 06_inference/inference_unified.py --published --model_type slm --interactive
@@ -229,20 +242,86 @@ python 06_inference/inference_unified.py --published --model_type slm --interact
 python 06_inference/inference_unified.py --published --model_type slm --prompt "In the year 1834, I walked through the streets of London and witnessed"
 ```
 
+**Need more headroom later?** Load with 🤗 Accelerate and `device_map="auto"` to spread layers across available devices/CPU automatically.
+
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
+tok = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForCausalLM.from_pretrained(model_id, device_map="auto")
+```
+
+---
+
+## 🪟 Windows Terminal one-liners
+
+**PowerShell**
+
+```powershell
+python -c "from transformers import AutoTokenizer,AutoModelForCausalLM; m='bahree/london-historical-slm'; t=AutoTokenizer.from_pretrained(m); model=AutoModelForCausalLM.from_pretrained(m); p='In the year 1834, I walked through the streets of London and witnessed'; i=t(p,return_tensors='pt'); print(t.decode(model.generate(i['input_ids'],max_new_tokens=50,do_sample=True)[0],skip_special_tokens=True))"
+```
+
+**Command Prompt (CMD)**
+
+```cmd
+python -c "from transformers import AutoTokenizer, AutoModelForCausalLM ^&^& import torch ^&^& m='bahree/london-historical-slm' ^&^& t=AutoTokenizer.from_pretrained(m) ^&^& model=AutoModelForCausalLM.from_pretrained(m) ^&^& p='In the year 1834, I walked through the streets of London and witnessed' ^&^& i=t(p, return_tensors='pt') ^&^& print(t.decode(model.generate(i['input_ids'], max_new_tokens=50, do_sample=True)[0], skip_special_tokens=True))"
+```
+
+---
+
+## 💡 Basic Usage (Python)
+
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
+
+tokenizer = AutoTokenizer.from_pretrained("bahree/london-historical-slm")
+model = AutoModelForCausalLM.from_pretrained("bahree/london-historical-slm")
+
+if tokenizer.pad_token is None:
+    tokenizer.pad_token = tokenizer.eos_token
+
+prompt = "In the year 1834, I walked through the streets of London and witnessed"
+inputs = tokenizer(prompt, return_tensors="pt")
+outputs = model.generate(
+    inputs["input_ids"],
+    max_new_tokens=50,
+    do_sample=True,
+    temperature=0.8,
+    top_p=0.95,
+    top_k=40,
+    repetition_penalty=1.2,
+    no_repeat_ngram_size=3,
+    pad_token_id=tokenizer.pad_token_id,
+    eos_token_id=tokenizer.eos_token_id,
+    early_stopping=True,
+)
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
+```
+
+---
+
+## 🧰 Example Prompts
+
+* **Tudor (1558):** "On this day in 1558, Queen Mary has died and …"
+* **Stuart (1666):** "The Great Fire of London has consumed much of the city, and …"
+* **Georgian/Victorian:** "As I journeyed through the streets of London, I observed …"
+* **London specifics:** "Parliament sat in Westminster Hall …", "The Thames flowed dark and mysterious …"
+
 ---
 
 ## 🛠️ Training Details
 
-*   **Architecture:** Custom GPT-2 Small (built from scratch)
-*   **Parameters:** ~117M
-*   **Tokenizer:** Custom historical tokenizer (~30k vocab) with London-specific and historical tokens
-*   **Data:** Historical London corpus (1500-1850) with proper segmentation
-*   **Steps:** 4,000 steps (early stopping for SLM)
-*   **Final Training Loss:** ~3.08 (good convergence)
-*   **Final Validation Loss:** ~3.67 (good generalization)
-*   **Training Time:** ~1.5 hours
-*   **Hardware:** 1× GPU training
-*   **Training Method:** **Train from scratch** using `04_training/train_model_slm.py`
+* **Architecture:** GPT-2 Small (12 layers, hidden size 768)
+* **Params:** ~117M
+* **Tokenizer:** custom historical tokenizer (~30k vocab) with London-specific and historical tokens
+* **Data:** historical London corpus (1500–1850)
+* **Steps/Epochs:** 30,000 steps (extended training for better convergence)
+* **Batch/LR:** 32, 3e-4 (optimized for segmented data)
+* **Hardware:** 2× GPU training with Distributed Data Parallel
+* **Final Training Loss:** 1.395 (43% improvement from 20K steps)
+* **Model Flops Utilization:** 3.5% (excellent efficiency)
+* **Training Method:** **Trained from scratch** - not fine-tuned
+* **Context Length:** 256 tokens (optimized for historical text segments)
+* **Status:** ✅ **Successfully published and tested** - ready for production use
 
 ---
 
@@ -281,6 +360,28 @@ If you use this model, please cite:
 
 ---
 
+## Repository
+
+The complete source code, training scripts, and documentation for this model are available on GitHub:
+
+**🔗 [https://github.com/bahree/helloLondon](https://github.com/bahree/helloLondon)**
+
+This repository includes:
+- Complete data collection pipeline for 1500-1850 historical English
+- Custom tokenizer optimized for historical text  
+- Training infrastructure with GPU optimization
+- Evaluation and deployment tools
+- Comprehensive documentation and examples
+
+### Quick Start with Repository
+```bash
+git clone https://github.com/bahree/helloLondon.git
+cd helloLondon
+python 06_inference/test_published_models.py --model_type slm
+```
+
+---
+
 ## 🧾 License
 
-MIT (see [LICENSE](https://huggingface.co/bahree/london-historical-slm/blob/main/LICENSE) in repo).
+MIT (see [LICENSE](https://github.com/bahree/helloLondon/blob/main/LICENSE) in repo).