feat: add benchmarks

Author: VinciGit00

README.md

@@ -21,7 +21,7 @@ TOON achieves **CSV-like compactness** while adding **explicit structure**, maki
 
 ### Key Features
 
-- ✅ **Compact**: 30-60% smaller than JSON for structured data
+- ✅ **Compact**: **64% smaller** than JSON on average (tested on 50 datasets)
 - ✅ **Readable**: Clean, indentation-based syntax
 - ✅ **Structured**: Preserves nested objects and arrays
 - ✅ **Type-safe**: Supports strings, numbers, booleans, null
@@ -323,11 +323,18 @@ python examples/advanced_features.py
 
 ## Performance
 
-TOON typically achieves:
-- **30-60% size reduction** vs JSON for structured data
-- **40-70% token reduction** with tabular data
+**Benchmarked across 50 diverse, real-world datasets:**
+
+- **63.9% average size reduction** vs JSON for structured data
+- **54.1% average token reduction** (directly lowers LLM API costs)
+- **Up to 73.4% savings** for optimal use cases (tabular data, surveys, analytics)
+- **98% of datasets achieve 40%+ savings**
 - **Minimal overhead** in encoding/decoding (<1ms for typical payloads)
 
+**💰 Cost Impact:** At GPT-4 pricing, TOON saves **$2,147 per million API requests** and **$5,408 per billion tokens**.
+
+**[📊 View Full Benchmark Results →](benchmark/RESULTS.md)**
+
 ## Contributing
 
 Contributions are welcome! Please:

README.zh-CN.md

@@ -17,7 +17,7 @@ TOON在实现**CSV般的紧凑性**的同时增加了**明确的结构**，非
 
 ### 主要特性
 
-- ✅ **紧凑**：比JSON结构化数据小30-60%
+- ✅ **紧凑**：平均比JSON**小64%**（在50个数据集上测试）
 - ✅ **可读**：简洁、基于缩进的语法
 - ✅ **结构化**：保留嵌套对象和数组
 - ✅ **类型安全**：支持字符串、数字、布尔值、null
@@ -319,11 +319,18 @@ python examples/advanced_features.py
 
 ## 性能
 
-TOON通常实现：
-- 与JSON相比，结构化数据**减少30-60%的大小**
-- 表格数据**减少40-70%的Token**
+**在50个多样化的真实数据集上进行基准测试：**
+
+- 与JSON相比，结构化数据**平均减少63.9%的大小**
+- **平均减少54.1%的Token**（直接降低LLM API成本）
+- 最优使用场景**最高节省73.4%**（表格数据、调查、分析）
+- **98%的数据集实现40%以上的节省**
 - **最小的开销**用于编码/解码（典型有效负载<1ms）
 
+**💰 成本影响：** 按GPT-4定价计算，TOON每百万次API请求**节省$2,147**，每十亿Token**节省$5,408**。
+
+**[📊 查看完整基准测试结果 →](benchmark/RESULTS.md)**
+
 ## 贡献
 
 欢迎贡献！请：

assets/README.ko.md

@@ -21,7 +21,7 @@ TOON은 **CSV 수준의 간결함**을 달성하면서 **명시적인 구조**
 
 ### 주요 기능
 
-- ✅ **간결함**: 구조화된 데이터의 경우 JSON보다 30-60% 작음
+- ✅ **간결함**: 평균적으로 JSON보다 **64% 작음** (50개 데이터셋 테스트 결과)
 - ✅ **가독성**: 깔끔하고 들여쓰기 기반의 구문
 - ✅ **구조화**: 중첩된 객체와 배열 보존
 - ✅ **타입 안전성**: 문자열, 숫자, 불리언, null 지원
@@ -323,11 +323,18 @@ python examples/advanced_features.py
 
 ## 성능
 
-TOON은 일반적으로 다음을 달성합니다:
-- 구조화된 데이터의 경우 JSON 대비 **30-60% 크기 감소**
-- 테이블 데이터의 경우 **40-70% 토큰 감소**
+**50개의 다양한 실제 데이터셋에서 벤치마크 테스트:**
+
+- 구조화된 데이터의 경우 JSON 대비 **평균 63.9% 크기 감소**
+- **평균 54.1% 토큰 감소** (LLM API 비용 직접 절감)
+- 최적 사용 사례에서 **최대 73.4% 절감** (테이블 데이터, 설문조사, 분석)
+- **98%의 데이터셋에서 40% 이상 절감 달성**
 - 인코딩/디코딩 시 **최소 오버헤드** (일반적인 페이로드의 경우 <1ms)
 
+**💰 비용 영향:** GPT-4 가격 기준으로, TOON은 백만 건의 API 요청당 **$2,147 절감**, 10억 토큰당 **$5,408 절감**.
+
+**[📊 전체 벤치마크 결과 보기 →](../benchmark/RESULTS.md)**
+
 ## 기여
 
 기여를 환영합니다! 다음 단계를 따라주세요:

benchmark/QUICKSTART.md

@@ -0,0 +1,95 @@
+# Benchmark Quick Start
+
+## Run All Benchmarks
+
+The fastest way to see the memory savings:
+
+```bash
+python benchmark/run_all.py
+```
+
+This will run all benchmarks and provide a comprehensive summary.
+
+## Run Individual Benchmarks
+
+### 1. Compare Sizes and Tokens
+
+```bash
+python benchmark/compare_formats.py
+```
+
+This shows:
+- File size comparison (JSON vs TOON)
+- Token count comparison (for LLM APIs)
+- Encoding/decoding performance
+- Example outputs
+
+### 2. Measure Memory Usage
+
+```bash
+python benchmark/memory_benchmark.py
+```
+
+This shows:
+- Actual memory consumption
+- Network bandwidth savings
+- Practical cost impact
+
+## Expected Results
+
+You should see:
+- **~58% average size reduction**
+- **~50% average token reduction**
+- **Up to 71% savings for tabular data**
+
+## What This Means
+
+If you're sending structured data to LLM APIs:
+- **50% fewer tokens** = **50% lower costs**
+- **Faster network transfers** = better performance
+- **Same data quality** = no loss of information
+
+## Examples
+
+### Before (JSON)
+```json
+{
+  "products": [
+    {"id": 1, "name": "Laptop", "price": 999},
+    {"id": 2, "name": "Mouse", "price": 29}
+  ]
+}
+```
+**Size: 134 bytes, 48 tokens**
+
+### After (TOON)
+```toon
+products[2]{id,name,price}:
+  1,Laptop,999
+  2,Mouse,29
+```
+**Size: 52 bytes, 23 tokens**
+
+**Savings: 61.2% size, 52.1% tokens**
+
+## Requirements
+
+```bash
+pip install tiktoken  # For token counting
+```
+
+## Troubleshooting
+
+If you get import errors, make sure you're in the project root:
+
+```bash
+cd /path/to/toonify
+python benchmark/run_all.py
+```
+
+Or install the package:
+
+```bash
+pip install -e .
+python benchmark/run_all.py
+```