---
license: apache-2.0
base_model: mistralai/Mistral-7B-v0.1
tags:
- finance
- conversational-ai
- ghana
- multilingual
- multimodal
- fintech
- whatsapp
- telegram
- twi
- pidgin
- hausa
- ga
- ewe
language:
- en
- ak  # Twi (Akan)
- ha  # Hausa
- ee  # Ewe
- mul  # Multiple languages (Pidgin is a creole)
pipeline_tag: text-generation
inference: true
---

# MOBOT - Ghana Financial Assistant 🤖🇬🇭

<div align="center">

![MOBOT Logo](https://via.placeholder.com/200x200?text=MOBOT)

**Your friendly financial assistant for Ghana**

[![Hugging Face](https://img.shields.io/badge/🤗%20Hugging%20Face-Model-blue)](https://huggingface.co/CHATMOBOT/mobot-ghana-complete)
[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)

</div>

---

## 🎯 What is MOBOT?

MOBOT is a **multilingual, multimodal conversational AI** specialized for Ghanaian financial services. Built on Mistral-7B, MOBOT helps users with:

- 💰 **Money Transfers** - Send money to friends and family
- 📄 **Bill Payments** - Pay ECG, GWCL, hospital bills, and more
- 📊 **Financial Tracking** - Check balances, view spending summaries
- 💡 **Financial Advice** - Savings tips, debt planning, budgeting
- 🎤 **Voice Interaction** - Speak naturally in Twi, Pidgin, English, and more
- 📷 **Bill Scanning** - Upload bill photos for automatic processing

---

## ✨ Key Features

### 🌍 Multilingual Support
- **English** - Full support
- **Twi** - Native language support
- **Pidgin** - Ghanaian Pidgin English
- **Hausa** - Northern Ghana language
- **Ga** - Greater Accra region
- **Ewe** - Volta region

### 🎨 Multimodal Capabilities
- 📝 **Text** - Natural language conversations
- 🎤 **Voice Input** - Speech-to-text (STT) with Whisper
- 📷 **Image Processing** - OCR for bills and receipts
- 🔊 **Voice Reply** - Text-to-speech (TTS) responses

### 💼 Financial Services
- Send money / transfers
- Pay utility bills (ECG, GWCL)
- Buy airtime and data
- Check account balance
- View transaction history
- Get spending summaries
- Financial coaching

### 🤝 Empathetic & Safe
- Emotional intelligence for sensitive situations
- Safety patterns for sensitive information
- Consent management for transactions
- Audit logging for compliance

---

## 🚀 Quick Start

### Installation

```bash
pip install transformers torch
```

### Basic Usage

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

# Load model
model_name = "CHATMOBOT/mobot-ghana-complete"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name)

# Chat with MOBOT
user_input = "Hey Mobot, send 50 cedis to Ama"
prompt = f"<s>[INST] You are MOBOT, Ghana's friendly financial assistant.\n\nUser: {user_input} [/INST]"

inputs = tokenizer(prompt, return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=512, temperature=0.2)
response = tokenizer.decode(outputs[0], skip_special_tokens=True)

print(response)
```

### With Pipeline

```python
from transformers import pipeline

mobot = pipeline(
    "text-generation",
    model="CHATMOBOT/mobot-ghana-complete"
)

response = mobot(
    "User: How much did I spend this week?",
    max_new_tokens=512,
    temperature=0.2
)
```

---

## 📚 Examples

### Money Transfer
```
User: Send 50 cedis to Kwame
Mobot: Sure! I'll send ₵50 to Kwame. Please confirm?
```

### Bill Payment
```
User: [Uploads ECG bill photo]
Mobot: I found an ECG bill for ₵100.00 (ref: REF123). Would you like me to pay it?
```

### Voice Note (Pidgin)
```
User: [Voice] "Chale send 20 ghs to Ama"
Mobot: Okay boss, sending ₵20 to Ama. Please confirm?
```

### Financial Advice
```
User: Help me save money
Mobot: Great question! Here are some tips: 
1. Set a monthly savings goal
2. Automate transfers to savings
3. Track your spending
Want more advice?
```

---

## 🔌 Integrations

### WhatsApp
```python
# See: integrations/whatsapp_webhook_example.py
# Full WhatsApp Business API integration
```

### Telegram
```python
# See: integrations/telegram_bot_example.py
# Interactive bot with buttons
```

### Agent Orchestration
```python
# See: agents/orchestrator.py
# Multi-step workflows
```

---

## 📊 Model Details

### Architecture
- **Base Model**: Mistral-7B-v0.1
- **Fine-tuning**: LoRA (Low-Rank Adaptation)
- **LoRA Rank**: 128
- **LoRA Alpha**: 32
- **Parameters**: 7B
- **Context Length**: 2048 tokens

### Training
- **Current Dataset**: 15,264 examples (quality-filtered)
- **Total Available**: 509,438+ examples (from larger dataset)
- **Languages**: 6 languages (English, Twi, Pidgin, Hausa, Ga, Ewe)
- **Intents**: 12+ financial intents
- **Training Time**: ~48 hours on RTX 4090
- **Training Config**: See `training_config.yaml`

### Performance
- **Intent Accuracy**: ≥95%
- **Slot F1**: ≥92%
- **Empathy Score**: ≥4.0/5.0

---

## 🛠️ Advanced Usage

### Multimodal Processing

```python
# OCR for bills
from scripts.multimodal.ocr_receipts import process_image
parsed = process_image("bill.jpg")

# STT for voice
from scripts.multimodal.stt_whisper import transcribe_audio
transcript = transcribe_audio("voice_note.mp3")

# TTS for replies
from services.tts_service import synthesize_text
audio = synthesize_text("Hello! I'm MOBOT.")
```

### Agent Orchestration

```python
from agents.orchestrator import AgentOrchestrator

orchestrator = AgentOrchestrator()
plan = orchestrator.plan("Pay this bill", context={"image": "bill.jpg"})
result = orchestrator.execute(plan, user_id="user123")
```

---

## 📖 Documentation

- **[Model Card](HUGGINGFACE_MODEL_CARD.md)** - Detailed model information
- **[Phase 4 Implementation](PHASE4_IMPLEMENTATION.md)** - Multimodal features
- **[Complete System Status](COMPLETE_SYSTEM_STATUS.md)** - Full system overview
- **[Training Guide](docs/PHASE3_PLAN.md)** - Training instructions

---

## 🔒 Safety & Privacy

- ✅ Refusal patterns for sensitive information
- ✅ PII redaction in training data
- ✅ Consent management for transactions
- ✅ Audit logging for compliance
- ✅ Ghana Data Protection Act compliant

---

## 🤝 Contributing

We welcome contributions! See our [GitHub repository](https://github.com/your-org/mobot) for:
- Issue reporting
- Feature requests
- Pull requests
- Documentation improvements

---

## 📄 License

Apache 2.0 License

---

## 🙏 Acknowledgments

- **Mistral AI** - Base model
- **RunPod** - Training infrastructure
- **Coqui TTS** - Voice synthesis
- **OpenAI Whisper** - Speech recognition
- **PaddleOCR** - Image processing

---

## 📞 Contact

- **Email**: support@chatmobot.com
- **Info**: info@chatmobot.com
- **GitHub Issues**: https://github.com/your-org/mobot/issues

### 🌐 Social Media

- **Facebook**: [MOBOT AI Ghana](https://www.facebook.com/profile.php?id=61581368944827)
- **Instagram**: [@MOBOTAI_GHANA](https://www.instagram.com/MOBOTAI_GHANA)
- **X (Twitter)**: [@MOBOTAI_GHANA](https://x.com/MOBOTAI_GHANA)
- **WhatsApp Channel**: [MOBOT Channel](https://whatsapp.com/channel/0029VbC8UJb6buMPPblI5d2v)

---

<div align="center">

**Made with ❤️ for Ghana**

🇬🇭 **MOBOT** - Your Financial Assistant

</div>