Trytellypls/TellyAI-Telly-Oasis-1-Pre1r

Telly Oasis 1

A lightweight, CPU-friendly GPT-style conversational AI built from scratch in PyTorch. Trained on a curated mix of instruction-tuning and identity datasets, it runs locally with no cloud dependencies.

---

Project Structure

Telly_Oasis_1/
├── README.md              # This file
├── LICENSE                # MIT License
├── requirements.txt       # Python dependencies
├── config.py              # Centralised configuration (Config dataclass)
├── model.py               # GPTModel — GPT decoder-only transformer
├── tokenizer.py           # Character-level tokenizer
├── dataset_loader.py      # Loads JSON / JSONL / Markdown / plain-text datasets
├── inference.py           # Generation helpers (generate_response, chat_loop)
├── train.py               # Full training pipeline
├── api_server.py          # Local HTTP API server (/generate, /chat, /health)
├── chat.py                # Interactive terminal chat CLI
├── convert_and_merge.py   # Convert OpenOrca / UltraChat parquet → project JSONL
├── generate_identity.py   # Generate identity/self-introduction dataset
├── utils.py               # Logging, seeding, timing, save helpers
├── datasets/
│   ├── telly-oasis-1.jsonl      # Main training dataset (merged & cleaned)
│   ├── identity.jsonl           # Identity / self-introduction Q&A pairs
│   ├── identity_alias1.jsonl    # Alias variant of identity dataset
│   └── uk bro.md                # Markdown-format dataset
├── models/
│   ├── tokenizer_vocab.json     # Tokenizer vocabulary
│   └── tokenizer_merges.txt     # Tokenizer merges (BPE-compatible)
├── checkpoints/               # Training checkpoints saved here
└── web/                       # Browser-based chat client
    ├── index.html
    ├── app.js
    └── style.css

---

Installation

# Clone or navigate to the project directory
cd Telly_Oasis_1

# (Optional) Create a virtual environment
python -m venv venv
source venv/bin/activate        # Linux/Mac
# venv\Scripts\activate         # Windows

# Install dependencies
pip install -r requirements.txt

The only dependency is PyTorch ≥ 2.0. The project is designed to run on CPU; CUDA is optional.

---

Quick Start — Training

# Train with defaults (3 epochs, batch size 4, CPU)
python train.py

# Customise training
python train.py --epochs 5 --batch-size 8 --lr 3e-4

# Resume from a previous checkpoint
python train.py --resume --model checkpoints/telly_oasis_1.pt

# Train on a custom dataset
python train.py --dataset C:\Users\trytellypls\OneDrive\Desktop\Projects\AI\Telly_Oasis_1\datasets\telly-oasis-1.jsonl

Training checkpoints are saved to checkpoints/telly_oasis_1.pt. The best model (by validation loss) is also saved as checkpoints/best_model.pt.

---

Quick Start — Chat (Terminal)

python chat.py --model checkpoints/telly_oasis_1.pt

This launches an interactive terminal session. Type quit or exit to end, clear to reset the conversation.

---

Quick Start — Web Chat

# Terminal 1: start the API server
python api_server.py --host 127.0.0.1 --port 8765 --api-key your-secret-key

# Terminal 2: open the web client
# Open web/index.html in a browser (or serve it)
python -m http.server 8080 --directory web
# Then visit http://localhost:8080

API Key Authentication

The API server supports optional API key authentication. When enabled, all POST endpoints (/chat, /generate) require the key in the X-API-Key header.

Setting the API key:

# Via command line
python api_server.py --api-key my-secret-key

# Via environment variable
export TELLY_API_KEY=my-secret-key
python api_server.py

# Auto-generate a key (first run creates .api_key file)
python api_server.py

Generating a new key at runtime:

curl -X GET http://127.0.0.1:8765/api-key -H "X-API-Key: <existing-key>"

API Endpoints

Method	Endpoint	Auth Required	Description
GET	/health	No	Health check; returns model loaded state
GET	/api-key	Yes	Generate a new API key
POST	/generate	Yes	Complete a prompt
POST	/chat	Yes	Conversational chat

/generate body:

{ "prompt": "Hello, who are you?", "max_tokens": 256, "temperature": 0.8, "top_p": 0.9 }

/chat body:

{ "messages": [{"from": "human", "value": "Hello"}], "max_tokens": 256, "temperature": 0.8, "top_p": 0.9 }

---

Dataset Format

Telly Oasis 1 supports four dataset formats (auto-detected by file extension):

Extension	Format	Description
.json	JSON	A JSON array of conversation objects
.jsonl	JSONL	One JSON object per line
.md	Markdown	Conversations separated by ---, with ### role headings
.txt	Plain Text	Pairs of lines treated as human/gpt turns

JSON / JSONL Format

{"conversations": [
  {"from": "system", "value": "You are Telly Oasis AI."},
  {"from": "human", "value": "Hello"},
  {"from": "gpt", "value": "Hello! How can I help?"}
]}

Valid roles: system, human, gpt.

Markdown Format

### System
You are Telly Oasis AI.

### Human
Hello

### Assistant
Hi there!

---

### Human
What can you do?

### Assistant
I can help with coding, math, reasoning, and more.

Supported role headings: System, Human, Assistant, GPT, gpt.

---

Preparing Your Own Dataset

1. Convert OpenOrca parquet files

python convert_and_merge.py

This reads datasets/OpenOrca/*.parquet and datasets/ultrachat_200k/data/*.parquet, converts them to the project JSONL format, merges them with the identity dataset, deduplicates, and writes datasets/telly-oasis-1.jsonl.

2. Generate the identity dataset

python generate_identity.py

This creates datasets/identity.jsonl with self-introduction Q&A pairs about Telly Oasis 1 and its creator Ahmad Asif Khan.

3. Validate your dataset

from dataset_loader import load_dataset
conversations = load_dataset("datasets/telly-oasis-1.jsonl")
print(f"Loaded {len(conversations)} conversations")

---

Configuration

All training and inference settings live in config.py (Config dataclass). Key fields:

Field	Default	Description
epochs	3	Training epochs
batch_size	4	Batch size per step
learning_rate	3e-4	Optimiser learning rate
context_length	512	Maximum sequence length
hidden_size	256	Embedding / FFN inner dimension
num_heads	4	Attention heads
num_layers	4	Transformer blocks
dropout	0.1	Dropout probability
device	"cpu"	"cpu" or "cuda"
model_save_path	"checkpoints/telly_oasis_1.pt"	Where to save checkpoints
dataset_path	"datasets/telly-oasis-1.jsonl"	Path to training data

---

Model Architecture

Telly Oasis 1 is a GPT decoder-only transformer:

• Token + positional embeddings
• Multi-head causal self-attention (pre-norm)
• Feed-forward blocks with GELU activation
• Layer normalisation (pre-norm)
• Dropout
• Causal masking
• Weight tying (embedding ↔ output projection)

Default size: ~4.2M parameters (CPU-friendly).

---

License

MIT License — see LICENSE.

---

Credits

Created by Ahmad Asif Khan as part of the TellyAI project. YouTube: @trytellypls