diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..814104c0fbcc943cfec11bb7c91ab8062c788f57
--- /dev/null
+++ b/README.md
@@ -0,0 +1,98 @@
+
+# ML Mavericks – Machine Learning Coursework
+
+**Course**: Machine Learning / Data Mining  
+**Group Name**: ML Mavericks  
+**University**: University of Surrey  
+**Term**: Spring 2025  
+
+---
+
+## 📌 Project Overview
+
+This project implements a complete Machine Learning / Data Mining pipeline using Python and Prolog. It covers multiple learning tasks across regression, classification, clustering, logic-based learning (ILP), and reinforcement learning.  
+We apply various machine learning algorithms to different datasets and evaluate their performance using appropriate metrics and visualizations.
+
+---
+
+## 🧪 Datasets Used
+
+| Dataset Type         | Purpose                              |
+|----------------------|--------------------------------------|
+| Regression (Garment) | Used for SVM, Decision Tree, MLP     |
+| Regression (Incident)| Used for SVM, Decision Tree, MLP     |
+| Classification       | Used for SVM, Neural Network         |
+| Clustering           | Used for KMeans, Hierarchical        |
+| ILP                  | Used Aleph on Census Dataset         |
+| Reinforcement Learning | Used RL environments in Colab     |
+
+---
+
+## 🧠 Algorithms Implemented
+
+- **Regression**: SVM, Decision Tree, MLP  
+- **Classification**: SVM, Neural Network  
+- **Clustering**: KMeans, Hierarchical  
+- **Logic-Based Learning**: ILP (Aleph)  
+- **Reinforcement Learning**: Q-Learning, Deep Q-Learning  
+
+---
+
+## 🗂️ Repository Structure
+
+```
+mlmavericks_coursework/
+├── data/
+│   ├── raw/              # Original datasets
+│   └── processed/        # Cleaned and transformed datasets
+├── media/                # RL video outputs
+├── models/               # Saved models (.pkl/.pth)
+├── notebooks/            # Jupyter notebooks organized by task
+│   ├── classification/
+│   ├── clustering/
+│   ├── regression/
+│   ├── reinforcement learning/
+│   └── induction logic programming (ILP)/
+├── src/                  # Utility scripts and functions
+├── requirements.txt      # Environment dependencies
+└── README.md             # Project overview
+```
+
+---
+
+## 🚀 How to Run
+
+### Local (Jupyter):
+1. Install dependencies manually or use Anaconda.
+2. Open Jupyter Lab/Notebook.
+3. Navigate to the desired notebook and run all cells.
+
+### Google Colab (ILP and RL):
+1. Open notebooks in Colab.
+2. Install dependencies via `!pip install ...`.
+3. Upload relevant data/model files if needed.
+
+---
+
+## 📤 Outputs
+
+- **Evaluation Metrics**: Notebooks output tables and scores.
+- **Plots**: Visualizations of model performance.
+- **RL Videos**: `media/rl-video-episode-0.mp4`
+- **ILP Rules**: Prolog outputs in ILP notebooks.
+
+---
+
+## 👨‍💻 Team Members
+
+- Ritwik Mishra  
+- Shivasmi Sharma  
+- Ishwari Niphade  
+- Arpit Mahapatra  
+- Suraj Borude
+
+---
+
+## 📄 License
+
+This project is for educational purposes only.