README.md

---
title: 𝐂𝐡𝐚𝐭 𝐇𝐮𝐦𝐨𝐮𝐫 𝐋𝐋𝐌 𝟎.𝟓𝐁
emoji: 🐨
colorFrom: purple
colorTo: yellow
sdk: docker
pinned: false
---
# 🧠 DNAI Humour Chatbot - Interactive Web Interface

A beautiful, fully-functional chat interface for the **dnai-humour-0.5B-instruct** model. Chat with a witty, lightweight AI assistant that's fast, friendly, and surprisingly capable.

![DNAI Humour](https://via.placeholder.com/1200x300/667eea/ffffff?text=DNAI+Humour+Chatbot)

---

## ✨ Features

- 💬 **Real-time Chat** - Smooth, responsive conversation interface
- 🎨 **Beautiful UI** - Modern design with dark/light mode
- ⚡ **Fast Responses** - Optimized for 0.5B parameter model
- 🎭 **Personality** - Witty and helpful, not robotic
- 📱 **Responsive** - Works on all devices
- 🧹 **Clean UX** - Clear conversations, suggestions, timestamps

---

## 🚀 Quick Start

### Prerequisites
- Python 3.8+
- CUDA-capable GPU (recommended) or CPU
- 2GB+ VRAM (GPU) or 4GB+ RAM (CPU)

### Installation

1. **Clone the Space**
```bash
git clone https://huggingface.co/spaces/YOUR-USERNAME/dnai-humour-chatbot
cd dnai-humour-chatbot
```

2. **Install Dependencies**
```bash
pip install -r requirements.txt
```

3. **Run the Application**
```bash
uvicorn app:app --host 0.0.0.0 --port 7860
```

4. **Open Browser**
```
http://localhost:7860
```

---

## 🌐 Deploy to Hugging Face Spaces

### Step 1: Create Space

1. Go to [Hugging Face](https://huggingface.co/)
2. Click **New Space**
3. Settings:
   - **Name**: `dnai-humour-chatbot`
   - **SDK**: Docker
   - **Hardware**: T4 Small (or CPU basic for testing)
   - **Visibility**: Public

### Step 2: Upload Files

Upload these files to your Space:
```
dnai-humour-chatbot/
├── app.py
├── requirements.txt
├── index.html
├── README.md
└── Dockerfile (optional)
```

### Step 3: Create Dockerfile (if needed)

```dockerfile
FROM python:3.10-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application
COPY . .

# Expose port
EXPOSE 7860

# Run
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
```

### Step 4: Wait for Build

- Hugging Face will automatically build your Space
- Check logs for any errors
- Model will download on first startup (~500MB)
- Once "Running", your chatbot is live! 🎉

---

## 📁 File Structure

```
dnai-humour-chatbot/
│
├── app.py                    # FastAPI backend with model inference
│   ├── /api/chat            # POST - Send messages
│   ├── /api/info            # GET - Model information
│   ├── /health              # GET - Health check
│   └── /api/reset           # POST - Reset conversation
│
├── index.html               # React-based chat interface
│   ├── Message history
│   ├── Dark/Light mode
│   ├── Typing indicators
│   └── Quick suggestions
│
├── requirements.txt         # Python dependencies
│   ├── transformers
│   ├── torch
│   ├── fastapi
│   └── uvicorn
│
└── README.md               # This file
```

---

## 🔌 API Documentation

### POST `/api/chat`

**Request:**
```json
{
  "messages": [
    {
      "role": "user",
      "content": "Tell me a joke"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 256
}
```

**Response:**
```json
{
  "response": "Why don't scientists trust atoms? Because they make up everything! 😄",
  "model": "DarkNeuron-AI/dnai-humour-0.5B-instruct",
  "tokens_used": 45
}
```

### GET `/api/info`

**Response:**
```json
{
  "model_name": "DNAI Humour 0.5B Instruct",
  "version": "1.0",
  "base_model": "Qwen2.5-0.5B-Instruct",
  "parameters": "~0.5 Billion",
  "capabilities": [
    "Instruction following",
    "Conversational AI",
    "Light humor",
    "Low-latency responses"
  ]
}
```

---

## 🎨 UI Features

### Chat Interface
- Clean, modern design
- Message bubbles with timestamps
- User/Assistant avatars
- Smooth animations

### Dark/Light Mode
- Toggle between themes
- Smooth transitions
- Persistent preferences (client-side)

### Smart Suggestions
- Quick-start prompts
- Contextual examples
- One-click input

### Typing Indicators
- Real-time feedback
- Loading animations
- Response timing

---

## ⚙️ Configuration

### Model Parameters (app.py)

```python
MODEL_NAME = "DarkNeuron-AI/dnai-humour-0.5B-instruct"
MAX_LENGTH = 512          # Context window
TEMPERATURE = 0.7         # Creativity (0.0-1.0)
TOP_P = 0.9              # Nucleus sampling
TOP_K = 50               # Top-k sampling
```

### Generation Settings

Adjust in `/api/chat` request:
- `temperature`: 0.1 (focused) to 1.0 (creative)
- `max_tokens`: 50 (short) to 512 (long)
- `stream`: true/false (streaming support)

---

## 🐛 Troubleshooting

### Issue: Model not loading

**Symptoms**: 503 errors, "Model not loaded"

**Solutions**:
```bash
# Check CUDA availability
python -c "import torch; print(torch.cuda.is_available())"

# Verify model download
python -c "from transformers import AutoModelForCausalLM; AutoModelForCausalLM.from_pretrained('DarkNeuron-AI/dnai-humour-0.5B-instruct')"

# Check logs
uvicorn app:app --log-level debug
```

### Issue: Out of memory

**Solutions**:
1. Reduce `max_tokens` in generation
2. Use CPU instead of GPU (slower but works)
3. Enable model quantization (INT8)

```python
# In app.py, modify model loading:
model = AutoModelForCausalLM.from_pretrained(
    MODEL_NAME,
    load_in_8bit=True,  # Enable INT8 quantization
    device_map="auto"
)
```

### Issue: Slow responses

**Solutions**:
1. Use GPU instead of CPU
2. Reduce `max_tokens`
3. Lower `temperature` for faster sampling
4. Use smaller batch size

---

## 📊 Performance Benchmarks

| Hardware | Response Time | Memory Usage |
|----------|--------------|--------------|
| T4 GPU   | ~1-2s        | ~2GB VRAM    |
| CPU      | ~5-10s       | ~4GB RAM     |
| A10G GPU | ~0.5-1s      | ~2GB VRAM    |

---

## 🎯 Use Cases

- **Educational Chatbots** - Learning companions
- **Personal Assistants** - Quick help & info
- **Code Helpers** - Programming Q&A
- **Creative Writing** - Brainstorming & ideas
- **General Chat** - Friendly conversation

---

## 🚫 Limitations

- **Not for production medical/legal advice**
- **Limited context window** (512 tokens)
- **0.5B parameters** - expect occasional mistakes
- **No long-term memory** - each conversation is independent
- **English-focused** - other languages may be limited

---

## 🔒 Privacy & Safety

- **No data logging** - conversations not stored
- **Local processing** - your data stays with you
- **No tracking** - no analytics or monitoring
- **Open source** - fully transparent code

---

## 🛠️ Advanced Customization

### Change Model Personality

Edit the system prompt in `app.py`:

```python
def format_chat_prompt(messages: List[Message]) -> str:
    system_prompt = "You are a helpful, witty AI assistant."
    formatted_messages = [f"System: {system_prompt}"]
    # ... rest of code
```

### Add Memory

Implement conversation history storage:

```python
# Simple in-memory storage
conversations = {}

@app.post("/api/chat")
async def chat(request: ChatRequest, user_id: str = "default"):
    if user_id not in conversations:
        conversations[user_id] = []
    # ... use stored history
```

### Enable Streaming

For real-time token-by-token responses:

```python
from fastapi.responses import StreamingResponse

@app.post("/api/chat/stream")
async def chat_stream(request: ChatRequest):
    def generate():
        # Yield tokens as they're generated
        for token in model.generate_stream(...):
            yield f"data: {token}\n\n"
    
    return StreamingResponse(generate(), media_type="text/event-stream")
```

---

## 📞 Support

For issues, questions, or suggestions:
- Open an issue on GitHub
- Contact via Hugging Face
- Check model card: [DarkNeuron-AI/dnai-humour-0.5B-instruct](https://huggingface.co/DarkNeuron-AI/dnai-humour-0.5B-instruct)

---

## 🙏 Acknowledgments

- **Base Model**: Qwen2.5-0.5B-Instruct by Alibaba
- **Dataset**: OpenAssistant v1
- **Framework**: Hugging Face Transformers
- **UI**: React + Tailwind CSS

---

## 📝 License

MIT License - Free to use, modify, and distribute

---

<div align="center">

**Crafted with ❤️ and passion by @MADARA369Uchiha**

*Small brain, well-trained. Fast responses, good vibes.* ✨

[![Hugging Face](https://img.shields.io/badge/🤗-Hugging%20Face-yellow)](https://huggingface.co/DarkNeuron-AI)
[![GitHub](https://img.shields.io/badge/GitHub-@Madara369Uchiha-black)](https://github.com/Madara369Uchiha)

</div>