doc: Enhance README.md

Author: thefeqy

README.md

@@ -14,47 +14,49 @@ Supports **PHP 8.2+**, built with **OOP best practices**, and **fully type-safe*
 ---
 
 ## 📖 Table of Contents
-- [✨ Features](#-features)
-- [📦 Installation](#-installation)
-- [🚀 Quick Start](#-quick-start)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
   - [Basic Usage](#basic-usage)
   - [Advanced Configuration](#advanced-configuration)
-- [📌 Available Grok AI Models](#-available-grok-ai-models)
-- [⚡ Streaming Responses](#-streaming-responses)
-- [🧪 Testing](#-testing)
-- [🔒 Security](#-security)
-- [🤝 Contributing](#-contributing)
-- [📄 License](#-license)
+- [Available Grok AI Models](#available-grok-ai-models)
+- [Streaming Responses](#streaming-responses)
+- [Error Handling](#error-handling)
+- [Testing](#testing)
+- [Security](#security)
+- [Contributing](#contributing)
+- [License](#license)
 
 ---
 
-## ✨ Features
+## **Features**
 
 ![Grok PHP Client Demo](assets/images/demo.gif)
 
-✅ **Plug & Play** – Quickly integrates with Grok AI APIs.  
-✅ **Type-Safe & Modern** – Fully utilizes **PHP 8.1+ features** like enums, traits, and interfaces.  
-✅ **Works Everywhere** – Compatible with **CLI scripts, APIs, and any PHP project**.  
-✅ **Streaming Ready** – Built-in support for **streaming API responses**.  
-✅ **Lightweight & Optimized** – No unnecessary dependencies, **PSR-4 autoloading**.
+- **Easy Integration** – Seamlessly connects with Grok AI APIs.  
+- **Modern PHP Features** – Utilizes PHP 8.2+ features like enums and traits.  
+- **Framework Agnostic** – Works with any PHP project, CLI scripts, or web applications.  
+- **Streaming Support** – Built-in support for real-time responses.  
+- **Lightweight & Efficient** – Optimized with PSR-4 autoloading and minimal dependencies.
 
 ---
 
-## 📦 Installation
+## **Installation**
 
-Install via **Composer**:
+Install via Composer:
 ```sh
 composer require grok-php/client
 ```
 
-### Requirements:
-
-- PHP 8.1+
+### **Requirements:**
+- PHP 8.2+
 - Composer 2.0+
 
-## 🚀 Quick Start
+---
+
+## **Quick Start**
 
-### Basic Usage
+### **Basic Usage**
 
 ```php
 use GrokPHP\Client\Clients\GrokClient;
@@ -76,18 +78,17 @@ $messages = [
 $options = new ChatOptions(model: Model::GROK_2, temperature: 0.7, stream: false);
 $response = $client->chat($messages, $options);
 
-echo "🤖 AI Response: " . $response['choices'][0]['message']['content'];
+echo "AI Response: " . $response['choices'][0]['message']['content'];
 ```
 
-### 📌 Defaults Used:
-
-- Model: grok-2
-- Temperature: 0.7
-- Streaming: false
+### **Defaults Used:**
+- Model: `grok-2`
+- Temperature: `0.7`
+- Streaming: `false`
 
 ---
 
-### Advanced Configuration
+### **Advanced Configuration**
 
 ```php
 use GrokPHP\Client\Clients\GrokClient;
@@ -115,17 +116,19 @@ $options = new ChatOptions(
 );
 
 $response = $client->chat($messages, $options);
-echo "🚀 AI Says: " . $response['choices'][0]['message']['content'];
+echo "AI Says: " . $response['choices'][0]['message']['content'];
 ```
+
 ---
 
-## 📌 Available Grok AI Models
-Grok AI offers multiple models, each optimized for different use cases.
-These models are available in the Model enum inside our package:
+## **Available Grok AI Models**
+
+Grok AI offers multiple models optimized for different use cases.  
+These models are available in the `Model` enum inside our package:  
 📄 `src/Enums/Model.php`
 
-| Model Enum                  | API Model Name       | Description                                         |
-|-----------------------------|----------------------|-----------------------------------------------------|
+| Model Enum                   | API Model Name       | Description                                         |
+|------------------------------|----------------------|-----------------------------------------------------|
 | `Model::GROK_VISION_BETA`     | grok-vision-beta     | Experimental vision-enabled model                   |
 | `Model::GROK_2_VISION`        | grok-2-vision        | Advanced multi-modal vision model                   |
 | `Model::GROK_2_VISION_LATEST` | grok-2-vision-latest | Latest iteration of Grok vision models              |
@@ -135,11 +138,13 @@ These models are available in the Model enum inside our package:
 | `Model::GROK_2_LATEST`        | grok-2-latest        | Latest iteration of Grok-2                          |
 | `Model::GROK_BETA`            | grok-beta            | Experimental beta model                             |
 
-#### 📌 Default model used: `Model::GROK_2`
+#### **Default model used:** `Model::GROK_2`
+
 ---
 
-## ⚡ Streaming Responses
-The Grok API supports streaming responses for real-time interaction.
+## **Streaming Responses**
+
+The Grok API supports streaming responses for real-time interaction.  
 Enable it by setting `stream: true`:
 
 ```php
@@ -150,23 +155,73 @@ Streaming can be useful for chatbots, real-time applications, and CLI assistants
 
 ---
 
-## 🧪 Testing
-Run tests using Pest PHP:
+## **Error Handling**
+
+This package includes built-in error handling with a dedicated exception class.  
+Common errors and their messages:
+
+| Error Type         | HTTP Code | Message |
+|--------------------|----------|-------------------------------------------|
+| `Invalid API Key` | 400      | No API key provided. Specify your API key. |
+| `Invalid Request` | 400      | Client specified an invalid argument. |
+| `Invalid Role`    | 422      | Unknown role variant provided in messages. |
+
+Example of handling exceptions:
+
+```php
+use GrokPHP\Client\Exceptions\GrokException;
+
+try {
+    $response = $client->chat($messages, $options);
+} catch (GrokException $e) {
+    echo "Error: " . $e->getMessage();
+}
+```
+
+---
+## **Testing**
+
+To run PHPUnit tests, you need to set up your API key. Follow these steps:
+
+1. **Copy the default PHPUnit configuration file:**
+```sh
+cp phpunit.xml.dist phpunit.xml
+```
+
+2. **Update the API key in `phpunit.xml`:**
+Open the file and replace `your-grok-api-key-here` with your actual API key:
+```xml
+<php>
+   <env name="GROK_API_KEY" value="your-grok-api-key-here"/>
+</php>
+```
+
+3. **Obtain an API Key:**  
+If you don’t have an API key, sign up at [Grok AI](https://x.ai/api/) and create one.
 
+4. **Run the tests with PHPUnit:**
 ```sh
 composer test
-or
-vendor/bin/pest
 ```
+Or run PHPUnit manually:
+```sh
+vendor/bin/phpunit
+```
+---
+
+## **Security**
 
-## 🔒 Security
-If you discover a security vulnerability, please report it via email:
-📩 [thefeqy@gmail.com](mailto:thefeqy@gmail.com)   
+If you discover a security vulnerability, please report it via email:  
+📩 [thefeqy@gmail.com](mailto:thefeqy@gmail.com)
 
-## 🤝 Contributing
+---
+
+## **Contributing**
 
 Want to improve this package? Check out [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
 
-## 📄 License
+---
+
+## **License**
 
 This package is open-source software licensed under the [MIT License](LICENSE).