docs: update README with Google Colab benchmark results (7x faster)

Author: vilsonrodrigues

README.md

@@ -21,12 +21,13 @@
 
 ## Features
 
-- ✅ **High performance** - Built on msgspec for speed
+- ✅ **7x faster than pydantic-settings** - High performance built on msgspec
+- ✅ **Drop-in API compatibility** - Familiar interface, easy migration from pydantic-settings
 - ✅ **Type-safe** - Full type hints and validation
 - ✅ **.env support** - Fast built-in .env parser (no dependencies)
 - ✅ **Nested settings** - Support for complex configuration structures
 - ✅ **Zero dependencies** - Only msgspec required
-- ✅ **Familiar API** - Easy to learn if you've used settings libraries before
+- ✅ **169x faster cached loads** - Smart caching for repeated access
 
 ## Installation
 
@@ -98,74 +99,81 @@ settings = AppSettings()
 
 ## Advanced Usage
 
-### Custom .env file path
+### Nested Configuration
 
 ```python
 from msgspec_ext import BaseSettings, SettingsConfigDict
 
-class AppSettings(BaseSettings):
-    model_config = SettingsConfigDict(
-        env_file=".env.production",
-        env_file_encoding="utf-8"
-    )
-
-    app_name: str
-```
-
-### Prefix for environment variables
-
-```python
-from msgspec_ext import BaseSettings, SettingsConfigDict
+class DatabaseSettings(BaseSettings):
+    host: str = "localhost"
+    port: int = 5432
+    name: str = "myapp"
+    user: str = "postgres"
+    password: str = ""
 
 class AppSettings(BaseSettings):
     model_config = SettingsConfigDict(
-        env_prefix="MYAPP_"
+        env_file=".env",
+        env_nested_delimiter="__"
     )
+    
+    name: str = "My App"
+    debug: bool = False
+    database: DatabaseSettings
 
-    name: str  # Will look for MYAPP_NAME
+# Loads nested config from DATABASE__HOST, DATABASE__PORT, etc.
+settings = AppSettings()
+print(settings.database.host)  # from DATABASE__HOST env var
 ```
 
-### Case sensitivity
+### Custom Validation
 
 ```python
 from msgspec_ext import BaseSettings, SettingsConfigDict
+from typing import Literal
 
 class AppSettings(BaseSettings):
-    model_config = SettingsConfigDict(
-        case_sensitive=True
-    )
+    model_config = SettingsConfigDict(env_file=".env")
+    
+    # Custom validation with enums
+    environment: Literal["development", "staging", "production"] = "development"
+    
+    # JSON parsing from environment variables
+    features: list[str] = ["auth", "api"]
+    limits: dict[str, int] = {"requests": 100, "timeout": 30}
 
-    AppName: str  # Exact match required
+settings = AppSettings()
+print(settings.features)  # Automatically parsed from JSON string
 ```
 
 ## Why Choose msgspec-ext?
 
 msgspec-ext provides a **faster, lighter alternative** to pydantic-settings while maintaining a familiar API and full type safety.
 
-### Performance Comparison
+### Performance Comparison (Google Colab Results)
 
-**Cold start** (first load, includes .env parsing):
+**Cold start** (first load, includes .env parsing) - *Benchmarked on Google Colab*:
 
 | Library | Time per load | Speed |
 |---------|---------------|-------|
-| **msgspec-ext** | **0.39ms** | **5.0x faster** ⚡ |
-| pydantic-settings | 1.95ms | Baseline |
+| **msgspec-ext** | **0.353ms** | **7.0x faster** ⚡ |
+| pydantic-settings | 2.47ms | Baseline |
 
-**Warm (cached)** (repeated loads in long-running applications):
+**Warm (cached)** (repeated loads in long-running applications) - *Benchmarked on Google Colab*:
 
 | Library | Time per load | Speed |
 |---------|---------------|-------|
-| **msgspec-ext** | **0.012ms** | **267x faster** ⚡ |
-| pydantic-settings | 3.2ms | Baseline |
+| **msgspec-ext** | **0.011ms** | **169x faster** ⚡ |
+| pydantic-settings | 1.86ms | Baseline |
 
-> *Benchmark includes .env file parsing, environment variable loading, type validation, and nested configuration (app settings, database, redis, feature flags). Run `benchmark/benchmark_cold_warm.py` to reproduce.*
+> *Benchmark executed on Google Colab includes .env file parsing, environment variable loading, type validation, and nested configuration. Run `benchmark/benchmark_cold_warm.py` on Google Colab to reproduce these results.*
 
 ### Key Advantages
 
 | Feature | msgspec-ext | pydantic-settings |
 |---------|------------|-------------------|
-| **Cold start** | **5.0x faster** ⚡ | Baseline |
-| **Warm (cached)** | **267x faster** ⚡ | Baseline |
+| **Cold start** | **7.0x faster** ⚡ | Baseline |
+| **Warm (cached)** | **169x faster** ⚡ | Baseline |
 | **Package size** | **0.49 MB** | 1.95 MB |
 | **Dependencies** | **1 (msgspec only)** | 5+ |
 | .env support | ✅ Built-in | ✅ Via python-dotenv |
@@ -180,25 +188,19 @@ msgspec-ext provides a **faster, lighter alternative** to pydantic-settings whil
 msgspec-ext achieves its performance through:
 - **Bulk validation**: Validates all fields at once in C (via msgspec), not one-by-one in Python
 - **Custom .env parser**: Built-in fast parser with zero external dependencies (no python-dotenv overhead)
-- **Smart caching**: Caches .env files, field mappings, and type information - loads after the first are 267x faster
+- **Smart caching**: Caches .env files, field mappings, and type information - loads after the first are 169x faster
 - **Optimized file operations**: Uses fast os.path operations instead of slower pathlib alternatives
 - **Zero overhead**: Fast paths for common types (str, bool, int, float) with minimal Python code
 
 This means your application **starts faster** and uses **less memory**, especially important for:
-- 🚀 **CLI tools** - 5.0x faster startup every time you run the command
+- 🚀 **CLI tools** - 7.0x faster startup every time you run the command
 - ⚡ **Serverless functions** - Lower cold start latency means better response times
-- 🔄 **Long-running apps** - After the first load, reloading settings is 267x faster (12 microseconds!)
+- 🔄 **Long-running apps** - After the first load, reloading settings is 169x faster (11 microseconds!)
 
 ## Contributing
 
 We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
-
-## Links
-
-- [GitHub Repository](https://github.com/msgflux/msgspec-ext)
-- [PyPI Package](https://pypi.org/project/msgspec-ext/)
-- [msgspec Documentation](https://jcristharif.com/msgspec/)
+MIT License - see [LICENSE](LICENSE) file for details.