custom_llm_project/sage_model/README.md

# Sage - Custom LLM Model

Sage is a custom-built transformer language model designed for text generation tasks. This model demonstrates the full lifecycle of building and publishing a custom AI model to Hugging Face.

## Model Overview

- **Model Type**: Transformer-based language model
- **Architecture**: Decoder-only transformer
- **Vocabulary Size**: 40 characters
- **Hidden Size**: 256
- **Number of Layers**: 4
- **Number of Attention Heads**: 8
- **Feedforward Size**: 1024
- **Max Sequence Length**: 64
- **Parameters**: ~3,195,944
- **Training Framework**: PyTorch
- **License**: MIT

## Training Data

Sage was trained on a curated dataset of example sentences covering:
- Conversational phrases and greetings
- Weather and environmental descriptions
- Machine learning and AI concepts
- Deep learning architectures (transformers, neural networks)
- Natural language processing applications
- Model development and deployment practices

The dataset consists of 10 examples designed to teach the model patterns in technical and conversational English.

## Technical Specifications

### Model Architecture
```
TransformerLM(
  (embedding): Embedding(40, 256)
  (pos_embedding): Embedding(64, 256)
  (transformer_encoder): TransformerEncoder(
    (layers): ModuleList(
      (0-3): TransformerEncoderLayer(
        (self_attn): MultiheadAttention(embed_dim=256, num_heads=8)
        (linear1): Linear(256, 1024)
        (linear2): Linear(1024, 256)
        (norm1): LayerNorm(256)
        (norm2): LayerNorm(256)
        (dropout): Dropout(p=0.1)
      )
    )
  )
  (output_layer): Linear(256, 40)
)
```

### Tokenization
Sage uses a character-level tokenizer with:
- Vocabulary: 40 unique characters including special tokens
- Special tokens: `<PAD>` (0), `<UNK>` (1)
- Encoding: UTF-8 character mapping
- Maximum sequence length: 64 tokens

## Usage

### With Transformers Library
```python
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

model_name = "itriedcoding/Sage"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name)

def generate_text(prompt, max_length=50, temperature=0.8):
    inputs = tokenizer.encode(prompt, return_tensors="pt")
    with torch.no_grad():
        outputs = model.generate(
            inputs,
            max_length=max_length,
            temperature=temperature,
            do_sample=True,
            pad_token_id=tokenizer.eos_token_id
        )
    return tokenizer.decode(outputs[0], skip_special_tokens=True)

print(generate_text("Hello"))
print(generate_text("Deep learning"))
```

### Direct PyTorch Usage
```python
import torch
from modeling_transformer_lm import TransformerLM

model = TransformerLM.from_pretrained("itriedcoding/Sage")
```

## Model Card Metadata

```
library_name: transformers
license: MIT
base_model: custom-built
tags:
- text-generation
- transformer
- character-level
- custom-model
- educational
pipeline_tag: text-generation
```

## Hugging Face Spaces Deployment

You can run Sage in the dedicated Hugging Face Space:
https://huggingface.co/spaces/itriedcoding/sage-space

### Gradio Space
The Space at `itriedcoding/sage-space` provides a Gradio interface for text generation.
Create a new Space with `app.py`:
```python
import gradio as gr
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

model_name = "itriedcoding/Sage"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name)

def generate_text(prompt, max_length, temperature):
    inputs = tokenizer.encode(prompt, return_tensors="pt")
    with torch.no_grad():
        outputs = model.generate(
            inputs,
            max_length=int(max_length),
            temperature=temperature,
            do_sample=True,
            pad_token_id=tokenizer.eos_token_id
        )
    return tokenizer.decode(outputs[0], skip_special_tokens=True)

demo = gr.Interface(
    fn=generate_text,
    inputs=[
        gr.Textbox(label="Prompt", value="Hello"),
        gr.Slider(minimum=10, maximum=100, value=30, label="Max Length"),
        gr.Slider(minimum=0.1, maximum=2.0, value=0.8, label="Temperature")
    ],
    outputs=gr.Textbox(label="Generated Text"),
    title="Sage Text Generator",
    description="Custom character-level language model"
)

if __name__ == "__main__":
    demo.launch()
```

## GGUF Quantization

WARNING: Sage uses a custom transformer architecture (not Llama-family). Standard GGUF conversion tools (llama.cpp) do not support this architecture. To generate GGUF files, you must write a custom conversion script that maps Sage's layers to GGUF format. A conversion script template is provided below.

### GGUF Conversion Script Template
```python
import torch
import struct

def convert_to_gguf(model_path, output_path):
    checkpoint = torch.load(model_path, map_location='cpu', weights_only=False)
    state_dict = checkpoint['model_state_dict']
    # Custom conversion logic to write GGUF format
    # Standard GGUF tools like llama.cpp's convert.py will NOT work
    # You need to implement the GGUF tensor serialization manually
    print(f"Converting {len(state_dict)} tensors to GGUF format...")
    # Implementation depends on the target runtime

convert_to_gguf("pytorch_model.bin", "sage.gguf")
```

### Recommended Alternative Formats
- **PyTorch**: Full precision (pytorch_model.bin) - already provided
- **TorchScript**: torch.jit.trace for optimized CPU/GPU inference
- **ONNX**: Use torch.onnx.export for cross-platform deployment

## Performance & Limitations

### Intended Use
- Educational demonstrations of transformer architectures
- Character-level language modeling experiments
- Prototyping and testing custom model pipelines
- Learning about model deployment on Hugging Face

### Limitations
- Character-level tokenization limits coherence
- Small training dataset (10 examples)
- Small model size (3.2M parameters)
- Not suitable for production NLP applications
- Best for short text generation (<50 tokens)

## Citation

```bibtex
@misc{sage_model_2026,
  author = {itriedcoding},
  title = {Sage: Custom Character-Level Language Model},
  year = {2026},
  publisher = {Hugging Face},
  journal = {Hugging Face Model Hub},
  url = {https://huggingface.co/itriedcoding/Sage}
}
```

## Training Reproducibility

To reproduce this model:
1. Clone the repository
2. Install requirements: `pip install torch pandas`
3. Run training: The model was trained using the script in `train_model.py`
4. The trained checkpoint is saved as a PyTorch .pth file

## Contact

- Hugging Face: https://huggingface.co/itriedcoding
- Model Space: https://huggingface.co/spaces/itriedcoding/sage-space
- Issues: Use the "Issues" tab on this model page