# 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:

```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

```bash
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

```python
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:

```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:

```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:

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

---

# Schema Validation

You can enforce structure using `ToonSchema`.

Example:

```python
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:

```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:

```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:

```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
    }
  ]
}
```