Improve benchmark with statistical analysis and fair comparison

.github/workflows/merge-bot.yml

@@ -403,6 +403,7 @@ jobs:
         if: steps.check_perms.outputs.has_permission == 'true'
         uses: actions/checkout@v4
         with:
+          repository: ${{ steps.pr_info.outputs.head_repo }}
           ref: ${{ steps.pr_info.outputs.head_branch }}
           fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -1,13 +1,15 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/msgflux/msgspec-ext/main/assets/msgspec-ext-logo-dark.svg">
-    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/msgflux/msgspec-ext/main/assets/msgspec-ext-logo-light.svg">
-    <img alt="msgspec-ext" src="https://raw.githubusercontent.com/msgflux/msgspec-ext/main/assets/msgspec-ext-logo-light.svg" width="340">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/msgflux/msgspec-ext/main/docs/assets/msgspec-ext-logo-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/msgflux/msgspec-ext/main/docs/assets/msgspec-ext-logo-light.png">
+    <img alt="msgspec-ext" src="https://raw.githubusercontent.com/msgflux/msgspec-ext/main/docs/assets/msgspec-ext-logo-light.png" width="340">
   </picture>
 </p>
 
+
+
 <p align="center">
-  <b>Fast settings management using <a href="https://github.com/jcrist/msgspec">msgspec</a></b> - a high-performance serialization library
+  <b>Fast settings management using <a href="https://github.com/jcrist/msgspec">msgspec</a></b> - a high-performance validation and serialization library
 </p>
 
 <p align="center">
@@ -140,26 +142,26 @@ class AppSettings(BaseSettings):
 
 msgspec-ext leverages msgspec's high-performance serialization with bulk JSON decoding for maximum speed.
 
-**Benchmark Results** (1000 iterations, Python 3.12):
+**Benchmark Results** (10 runs × 1000 iterations, Python 3.12):
 
 | Library | Time per load | Relative Performance |
 |---------|---------------|---------------------|
-| msgspec-ext | 0.702ms | Baseline ⚡ |
-| pydantic-settings | 2.694ms | 3.8x slower |
+| msgspec-ext | 2.271ms | Baseline ⚡ |
+| pydantic-settings | 6.157ms | 2.7x slower |
 
-msgspec-ext is **3.8x faster** than pydantic-settings while providing the same level of type safety and validation.
+msgspec-ext is **2.7x faster** than pydantic-settings while providing the same level of type safety and validation.
 
 **Key optimizations:**
 - Bulk JSON decoding in C (via msgspec)
 - Cached encoders and decoders
 - Automatic field ordering
 - Zero Python loops for validation
 
-*Benchmark measures complete settings initialization including .env file parsing and type validation. Run `python benchmark.py` to reproduce.*
+*Benchmark measures complete settings initialization with complex configuration (app settings, database, redis, feature flags) including .env file parsing and type validation. Run `./benchmark/run_benchmark.sh` to reproduce.*
 
 ## Why msgspec-ext?
 
-- **Performance** - 3.8x faster than pydantic-settings
+- **Performance** - 2.7x faster than pydantic-settings
 - **Lightweight** - 4x smaller package size (0.49 MB vs 1.95 MB)
 - **Type safety** - Full type validation with modern Python type checkers
 - **Minimal dependencies** - Only msgspec and python-dotenv
@@ -170,7 +172,7 @@ msgspec-ext is **3.8x faster** than pydantic-settings while providing the same l
 |---------|------------|-------------------|
 | .env support | ✅ | ✅ |
 | Type validation | ✅ | ✅ |
-| Performance | **3.8x faster** ⚡ | Baseline |
+| Performance | **2.7x faster** ⚡ | Baseline |
 | Package size | 0.49 MB | 1.95 MB |
 | Nested config | ✅ | ✅ |
 | Field aliases | ✅ | ✅ |