mini-toon 0.1.1

Simple TOON parser and converter for AI pipelines

mini-toon

Lightweight TOON parser and converter for LLM pipelines.

mini-toon is a small Python library designed to convert between TOON (Token-Oriented Object Notation) and JSON, making it easier to integrate outputs from LLMs, VLMs, OCR systems, and vision pipelines into structured data workflows.

The library focuses on simplicity, predictable structure, and data-oriented design.

---

Why mini-toon?

Large language models often struggle to generate valid JSON consistently. TOON provides a simpler, more predictable textual format that models can generate more reliably.

Example comparison:

JSON:

{
  "product": "rice",
  "quantity": 2
}

TOON:

product=rice; quantity=2

This format is:

• easier for LLMs to generate
• easier to parse
• token-efficient
• compatible with structured pipelines

---

Installation

pip install mini-toon

---

Features

• Convert TOON → JSON
• Convert JSON → TOON
• Automatic type detection
• Support for nested objects
• Support for arrays
• Schema validation
• Designed for AI pipelines

---

Basic Example

from mini_toon import (
    toon_to_json,
    json_to_toon,
    validate_toon,
    ToonSchema
)

toon = """
product=rice; quantity=2
product=beans; quantity=3
"""

validate_toon(toon)

data = toon_to_json(toon)

print(data)

toon2 = json_to_toon(data)

print(toon2)

Output JSON:

{
  "items": [
    {
      "product": "rice",
      "quantity": 2
    },
    {
      "product": "beans",
      "quantity": 3
    }
  ]
}

Converted back to TOON:

product=rice; quantity=2
product=beans; quantity=3

---

Nested Objects

TOON supports nested objects using the . notation.

Example TOON:

product.name=White Rice; product.price=5.90; quantity=2

Converted JSON:

{
  "items": [
    {
      "product": {
        "name": "White Rice",
        "price": 5.9
      },
      "quantity": 2
    }
  ]
}

---

Arrays

Arrays are defined using the | separator.

Example TOON:

product=rice; quantity=2; tags=food|basic|market

Converted JSON:

{
  "items": [
    {
      "product": "rice",
      "quantity": 2,
      "tags": ["food", "basic", "market"]
    }
  ]
}

---

Schema Validation

You can enforce structure using ToonSchema.

Example:

schema = ToonSchema({

    "product": {
        "name": str,
        "price": float
    },

    "quantity": int,
    "tags": list
})

schema.validate(data["items"])

If the structure is invalid, an exception will be raised.

---

Example

Example TOON generated by an AI model:

product.name=White Rice; product.price=5.90; quantity=2; category=food; tags=basic|market
product.name=Black Beans; product.price=7.50; quantity=3; category=food; tags=grain|market
product.name=Dish Soap; product.price=3.40; quantity=1; category=cleaning; tags=home|kitchen

Converted JSON:

{
  "items": [
    {
      "product": {
        "name": "White Rice",
        "price": 5.9
      },
      "quantity": 2,
      "category": "food",
      "tags": ["basic", "market"]
    },
    {
      "product": {
        "name": "Black Beans",
        "price": 7.5
      },
      "quantity": 3,
      "category": "food",
      "tags": ["grain", "market"]
    },
    {
      "product": {
        "name": "Dish Soap",
        "price": 3.4
      },
      "quantity": 1,
      "category": "cleaning",
      "tags": ["home", "kitchen"]
    }
  ]
}

---

AI Pipeline Example

mini-toon works well inside AI pipelines.

Example TOON generated by an LLM:

product.name=White Rice; product.price=5.90; quantity=2; category=food
product.name=Black Beans; product.price=7.50; quantity=3; category=food

Converted JSON:

{
  "items": [
    {
      "product": {
        "name": "White Rice",
        "price": 5.9
      },
      "quantity": 2,
      "category": "food"
    },
    {
      "product": {
        "name": "Black Beans",
        "price": 7.5
      },
      "quantity": 3,
      "category": "food"
    }
  ]
}

---

Vision Detection Example

TOON also works well for outputs from vision models.

Example detection output:

object=person; box.x=120; box.y=230; box.width=50; box.height=100; confidence=0.91
object=dog; box.x=300; box.y=200; box.width=80; box.height=60; confidence=0.78

Converted JSON:

{
  "items": [
    {
      "object": "person",
      "box": {
        "x": 120,
        "y": 230,
        "width": 50,
        "height": 100
      },
      "confidence": 0.91
    },
    {
      "object": "dog",
      "box": {
        "x": 300,
        "y": 200,
        "width": 80,
        "height": 60
      },
      "confidence": 0.78
    }
  ]
}