README.md

---
base_model: Qwen/Qwen3-4B
library_name: peft
tags:
  - base_model:adapter:Qwen/Qwen3-4B
  - lora
  - transformers
  - text-classification
  - moderation
  - star-trek
---

# Model Card for geoffmunn/Qwen3Guard-StarTrek-Classification-4B

This is a fine-tuned version of **Qwen3-4B** using LoRA (Low-Rank Adaptation) to classify whether user-provided text is related to *Star Trek* or not. The model acts as a domain-specific content classifier, returning one of two labels: `"related"` or `"not_related"`. It was developed as part of the Qwen3Guard demonstration project to showcase how large language models can be adapted for custom classification tasks.

## Model Details

### Model Description

This model is a binary sequence classifier fine-tuned on a synthetic dataset of Star Trek-related questions and general non-Star-Trek text. Built atop the Qwen3-4B foundation model, it uses parameter-efficient fine-tuning via LoRA to adapt the model for topic detection in conversational or input text. It is designed for use in moderation systems where filtering based on pop culture topics like *Star Trek* is desired.

- **Developed by:** Geoff Munn ([@geoffmunn](https://github.com/geoffmunn))
- **Shared by:** Geoff Munn
- **Model type:** Causal language model with LoRA adapter for sequence classification
- **Language(s) (NLP):** English
- **License:** MIT License (see [GitHub repo](https://github.com/geoffmunn/Qwen3Guard))
- **Finetuned from model:** Qwen/Qwen3-4B

### Model Sources

- **Repository:** [https://github.com/geoffmunn/Qwen3Guard](https://github.com/geoffmunn/Qwen3Guard)
- **Demo:** Interactive demo available via `star_trek_chat.html` in the repository; requires local API server

## Uses

### Direct Use

The model can directly classify whether a given piece of text is related to *Star Trek*. Example applications include:
- Filtering fan forum posts
- Moderating trivia chatbots
- Enhancing themed AI assistants
- Educational tools focused on science fiction media

Input: A string of text  
Output: One of two labels — `"related"` or `"not_related"`

### Downstream Use

This model can be integrated into larger systems such as:
- Themed conversational agents (e.g., a *Star Trek*-focused chatbot)
- Content recommendation engines that route queries based on topic relevance
- Fine-tuning starter for other sci-fi franchises (e.g., *Star Wars*, *Doctor Who*) using similar methodology

### Out-of-Scope Use

This model should **not** be used for:
- General content moderation (toxicity, hate speech, etc.)
- Medical, legal, or safety-critical decision-making
- Multilingual classification (trained only on English)
- Detecting nuanced sentiment or emotion
- Classifying topics outside entertainment/pop culture without retraining

It may produce inaccurate classifications when presented with ambiguous references, parody content, or highly technical scientific discussions unrelated to *Star Trek* lore.

## Bias, Risks, and Limitations

The training data consists entirely of synthetically generated questions about *Star Trek*, which introduces several limitations:
- Potential overfitting to question formats rather than natural language statements
- Limited coverage of obscure characters, episodes, or expanded universe material
- No representation of non-English *Star Trek* content
- Biases toward canonical series (TOS, TNG, DS9, etc.) over newer entries

Additionally, because the dataset was auto-generated using prompts, there may be inconsistencies in labeling or artificial phrasing patterns.

### Recommendations

Users should validate performance on real-world data before deployment. For production use, consider augmenting the dataset with human-labeled examples and testing across diverse inputs. Always pair this model with broader safeguards if used in public-facing applications.

## How to Get Started with the Model

You can load and run inference using Hugging Face Transformers:

```python
from transformers import AutoModelForSequenceClassification, AutoTokenizer

model_id = "geoffmunn/Qwen3Guard-StarTrek-Classification-4B"

tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForSequenceClassification.from_pretrained(model_id)

input_text = "What is the warp core made of in Star Trek?"
inputs = tokenizer(input_text, return_tensors="pt", truncation=True, max_length=512)

outputs = model(**inputs)
predicted_class_id = outputs.logits.argmax().item()
label = model.config.id2label[predicted_class_id]

print(f"Label: {label}")
```

Ensure you have the required libraries installed:

```bash
pip install transformers torch peft
```

## Training Details

### Training Data
The model was trained on a synthetic JSONL dataset containing 2,500 labeled examples of Star Trek-related questions marked as `"related"`, and an equal number of randomly sampled general knowledge questions labeled `"not_related"`. The dataset was generated using the script `generate_star_trek_questions.py` from the repository.

Dataset format:

```json
{"input": "What planet is Spock from?", "label": "related"}
{"input": "Who wrote 'Pride and Prejudice'?", "label": "not_related"}
```

Place your dataset at: `finetuning/star_trek/star_trek_guard_dataset.jsonl`

### Training Procedure

#### Preprocessing
Text inputs were tokenized using the Qwen3 tokenizer with a maximum sequence length of 512 tokens. Inputs longer than this were truncated. Labels were mapped via:

```python
label2id = {"not_related": 0, "related": 1}
id2label = {0: "not_related", 1: "related"}
```

### Training Hyperparameters

- **Training regime:** Mixed precision training (fp16), enabled via Hugging Face Accelerate
- **Batch size:** 2 (per GPU)
- **Gradient accumulation steps:** 16 → effective batch size: 32
- **Number of epochs:** 3
- **Learning rate:** 2e-4
- **Optimizer:** AdamW
- **Max sequence length:** 512
- **LoRA configuration:**
  - **Rank (r):** 16
  - **Alpha:** 32
  - **Dropout:** 0.05
  - **Target modules:** attention query/value layers and MLP up/down projections

### Speeds, Sizes, Times

- **Hardware used:** NVIDIA GPU (assumed: A100 or equivalent)
- **Training time:** ~2–3 hours depending on hardware
- **Checkpoint size:** ~3.8 GB (adapter weights only, PEFT format)
- **Inference memory:** < 10 GB VRAM (with quantization further reduction possible)

## Evaluation

### Testing Data, Factors & Metrics

#### Testing Data

A 10% holdout test set (~500 samples) was used for evaluation, split from the full dataset during training.

#### Factors

Evaluation focused on accuracy across:

- Canonical vs. obscure Star Trek references
- Question vs. statement format
- Length of input text
  
#### Metrics

- **Accuracy:** Primary metric
- **Precision, Recall, F1-score:** Per-class metrics reported during training
- **Confusion Matrix:** Generated internally during test phase

## Results

During final evaluation, the model achieved:

- **Accuracy:** ~96–98% (on synthetic test set)
- Strong precision/recall for "related" class
- Minor false positives on space/science topics unrelated to Star Trek
  
## Summary
The model performs well on its intended task within the scope of the training distribution but may degrade on edge cases or metaphorical references.

## Technical Specifications

### Model Architecture and Objective

- **Base architecture:** Qwen3-4B (causal decoder-only LLM)
- **Adaptation method:** LoRA (PEFT)
- **Task head:** Sequence classification (single-label)
- **Objective function:** Cross-entropy loss

### Compute Infrastructure

#### Hardware
GPU: NVIDIA A100 / RTX 3090 / L40S or equivalent
RAM: ≥ 32 GB system memory recommended

#### Software

- Python 3.10+
- PyTorch 2.4+ with CUDA 12.1+
- Transformers 4.40+
- PEFT 0.18.0
- Accelerate, Datasets, Tokenizers

## Citation

While no formal paper exists, please cite the GitHub repository if used academically.

BibTeX:

```bibtex
@software{munn_qwen3guard_2025,
  author = {Munn, Geoff},
  title = {Qwen3Guard: Demonstration of Qwen3Guard Models for Content Classification},
  year = {2025},
  publisher = {GitHub},
  journal = {GitHub repository},
  url = {https://github.com/geoffmunn/Qwen3Guard}
}
```

### APA:

Munn, G. (2025). Qwen3Guard: Demonstration of Qwen3Guard Models for Content Classification [Software]. GitHub. https://github.com/geoffmunn/Qwen3Guard

## Glossary

- **LoRA (Low-Rank Adaptation):** A parameter-efficient fine-tuning technique that adds trainable low-rank matrices to pretrained weights.
- **PEFT:** Parameter-Efficient Fine-Tuning, a Hugging Face library for lightweight adaptation of large models.
- **GGUF:** Format used for running models in llama.cpp; not supported for streaming variant here.
- **JSONL:** JSON Lines format – one JSON object per line.

## More Information

For more details, including API server setup and web demos, visit:
👉 https://github.com/geoffmunn/Qwen3Guard

Includes:

- Ollama-compatible scripts
- Flask-based API server (api_server.py)
- HTML chat interface (star_trek_chat.html)
- Dataset generation tools

## Model Card Authors
Geoff Munn – Developer and maintainer

## Model Card Contact
For questions or feedback, contact the author via GitHub:
@geoffmunn