Skip to main content

​
Overview

Toonify introduces TOON (Token-Oriented Object Notation), a compact serialization format designed by ScrapeGraphAI to make structured payloads cheaper to send to Large Language Models. Compared with JSON, TOON frequently reduces token counts by 30–60% while keeping data human-readable and type-safe Toonify README.
Looking for the source? Explore the open-source project on GitHub.

​
Key Features

Compact Encoding

CSV-like density for structured data while preserving hierarchy

Human Friendly

Indentation-based syntax that stays readable and easy to edit

Type Safety

Supports strings, numbers, booleans, and null values without ambiguity

Flexible Delimiters

Choose comma, tab, or pipe to match your downstream tooling

​
Installation

Use pip to add Toonify to your project: 
pip install toonify
For development or contributions: 
git clone https://github.com/ScrapeGraphAI/toonify.git
cd toonify
pip install -e .[dev]

​
Python Quick Start

from toon import encode, decode

data = {
    "products": [
        {"sku": "LAP-001", "name": "Gaming Laptop", "price": 1299.99},
        {"sku": "MOU-042", "name": "Wireless Mouse", "price": 29.99},
    ]
}

# Encode Python dict to TOON
toon_string = encode(data)
print(toon_string)

# Decode TOON back to Python
result = decode(toon_string)
assert result == data

​
Expressive Tabular Output

products[3]{id,name,price}:
  101,Laptop Pro,1299
  102,Magic Mouse,79
  103,USB-C Cable,19
Compared with the equivalent JSON, this TOON snippet cuts the payload size by roughly 60% while remaining easy to scan by humans and LLMs.

​
Command Line Usage

Toonify ships with a CLI for converting between JSON and TOON: 
# Encode JSON to TOON
toon data.json -o data.toon

# Decode TOON to JSON
toon data.toon -o data.json

# Stream from stdin and inspect stats
cat data.json | toon -e --stats

​
Helpful Flags

FlagDescription
--delimiter {comma,tab,pipe}Choose the delimiter used in tabular data
--indent INDENTConfigure indentation (default: 2 spaces)
--statsDisplay byte and token savings for a conversion
--key-folding {off,safe}Collapse nested keys into dotted paths when encoding
--expand-paths {off,safe}Expand dotted paths back into nested objects when decoding

​
Advanced Capabilities

  • Key Folding: Safely condenses deep objects into dotted keys (api.response.data.count) for even smaller payloads.
  • Path Expansion: Reconstructs dotted keys into nested objects on decode, keeping round-trips lossless.
  • Delimiter Control: Switch to tab or pipe delimiters when your data contains commas, preventing unnecessary quoting.
  • Strict Parsing: Enable or disable strict validation based on your tolerance for loosely formatted input.

​
When to Use TOON

Great Fit

Slim down prompts, preserve schema structure, and feed uniform tables to LLMs.

Use JSON Instead

Prefer JSON when interoperability with existing JSON-only tooling outweighs token savings.

​
Testing & Quality

The repository includes an automated test suite—run it locally with: 
pytest
pytest --cov=toon --cov-report=term-missing

​
Resources

Contribute

Join the open-source effort and help evolve the TOON ecosystem.