{"id":42402702,"url":"https://github.com/henryhamon/dc-toon","last_synced_at":"2026-01-28T01:26:33.741Z","repository":{"id":333461150,"uuid":"1112599871","full_name":"henryhamon/dc-toon","owner":"henryhamon","description":"Token-Oriented Object Notation (TOON) encoder/decoder for InterSystems IRIS ObjectScript – a compact, human-readable alternative to JSON that cuts LLM prompt size by ~30–50% while preserving full structure for RAG and agents.","archived":false,"fork":false,"pushed_at":"2026-01-19T10:51:07.000Z","size":22,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-19T17:50:48.920Z","etag":null,"topics":["intersystems-iris","json-alternative","llm","objectscript","prompt-optimization","rag","token-economy","token-efficiency","token-oriented-object-notation","toon"],"latest_commit_sha":null,"homepage":"","language":"ObjectScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/henryhamon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-08T21:09:56.000Z","updated_at":"2026-01-19T10:51:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/henryhamon/dc-toon","commit_stats":null,"previous_names":["henryhamon/dc-toon"],"tags_count":null,"template":false,"template_full_name":"intersystems-community/intersystems-iris-dev-template","purl":"pkg:github/henryhamon/dc-toon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henryhamon%2Fdc-toon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henryhamon%2Fdc-toon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henryhamon%2Fdc-toon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henryhamon%2Fdc-toon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/henryhamon","download_url":"https://codeload.github.com/henryhamon/dc-toon/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henryhamon%2Fdc-toon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28831296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T23:29:49.665Z","status":"ssl_error","status_checked_at":"2026-01-27T23:25:58.379Z","response_time":168,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["intersystems-iris","json-alternative","llm","objectscript","prompt-optimization","rag","token-economy","token-efficiency","token-oriented-object-notation","toon"],"created_at":"2026-01-28T01:26:33.149Z","updated_at":"2026-01-28T01:26:33.736Z","avatar_url":"https://github.com/henryhamon.png","language":"ObjectScript","funding_links":[],"categories":[],"sub_categories":[],"readme":" [![Gitter](https://img.shields.io/badge/Available%20on-Intersystems%20Open%20Exchange-00b2a9.svg)](https://openexchange.intersystems.com/package/intersystems-iris-dev-template)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat\u0026logo=AdGuard)](LICENSE)\n\n# dc-toon – TOON for InterSystems IRIS\n\n## 📖 Overview\n\n**dc-toon** is a lightweight, production-ready implementation of **TOON (Token-Oriented Object Notation)** for **InterSystems IRIS ObjectScript**.  \nIt brings the benefits of the TOON format—originally designed for Python and TypeScript—to IRIS, enabling you to serialize structured data more compactly than JSON and dramatically reduce LLM token usage in AI workflows.\n\nThis project is especially useful for:\n\n- RAG pipelines where large JSON payloads inflate prompt size.\n- Agentic workflows (LangGraph, custom orchestrators) that pass rich state between tools.\n\ndc-toon currently provides:\n\n- `dc.toon.Converter` – TOON encoder/decoder for `%DynamicObject` / `%DynamicArray`.\n- `dc.toon.Parser` – TOON → JSON parser used internally by the converter.\n\n***\n\n## 🎯 Motivation\n\nLarge JSON structures are expensive to send to LLMs. Even when you compress content semantically, the **structural overhead** (braces, brackets, quotes, repeated keys) still consumes a lot of tokens. TOON was created to address exactly this:  \na **human-readable, LLM-friendly, token-efficient** representation of structured data.\n\nThis port brings that same idea to the InterSystems IRIS ecosystem:\n\n- Replace verbose JSON with compact TOON when sending context to LLMs.\n- Maintain clear structure (objects, primitive arrays, tabular arrays).\n- Keep everything native: `%DynamicObject`, `%DynamicArray`, ObjectScript.\n\nTypical savings in this implementation are around **30–50% fewer characters** for the same payload, which translates directly into **lower token usage and cost** in LLM prompts.\n\n***\n\n## ⚙️ How It Works\n\nAt the core of dc-toon are two classes:\n\n### `dc.toon.Converter`\n\nThis is the main entry point. It knows how to:\n\n- **Encode** IRIS dynamic structures to TOON:\n  - Objects → `key: value` lines with indentation.\n  - Primitive arrays → `[N]: v1,v2,v3`.\n  - Tabular arrays of objects → `[N,]{field1,field2}:\\n  v1,v2\\n  v3,v4`.\n  - Mixed arrays → `[N]:\\n- item1\\n- item2`.\n\n- **Decode** TOON back into `%DynamicObject` / `%DynamicArray` using the parser.\n\nKey class methods:\n\n```objectscript\n/// Encode IRIS dynamic value to TOON\nClassMethod ToTOON(input As %DynamicAbstractObject, options As %DynamicObject = \"\") As %String\n\n/// Decode TOON string back into a dynamic value\nClassMethod FromTOON(toonStr As %String, options As %DynamicObject = \"\", Output result) As %Status\n```\n\nEncoding options are provided via a `%DynamicObject`:\n\n- `indent` – spaces per indentation level (default: 2).\n- `delimiter` – `\",\" | \"pipe\" | \"tab\"` (default: comma).\n- `lengthMarker` – `\"#\"` to enable markers like `[3]`, or `\"\"` (default).\n\nExample (primitive array with pipe delimiter):\n\n```objectscript\nSet data = ##class(%DynamicArray).%New()\nDo data.%Push(1), data.%Push(2), data.%Push(3)\n\nSet opts = ##class(%DynamicObject).%New()\nDo opts.%Set(\"delimiter\",\"pipe\")\n\nSet toon = ##class(dc.toon.Converter).ToTOON(data, opts)\n// [3|]: 1|2|3\n```\n\n### `dc.toon.Parser`\n\nThe parser is responsible for TOON → JSON semantics:\n\n- Interprets headers like `[N]`, `[N,]{...}`, `[N|]:`.\n- Splits rows, fields, and mixed lists.\n- Reconstructs `%DynamicArray` and `%DynamicObject` instances.\n- Supports a `strict` option for length validation and basic syntax checks.\n\nYou typically don’t call `dc.toon.Parser` directly – it is used internally by `dc.toon.Converter.FromTOON()`.\n\n***\n\n## 🧪 Test Suite\n\nThe project includes a comprehensive `%UnitTest` suite in  \n`dc.toon.unittests.TestToon`, covering:\n\n- Simple object encoding.\n- Primitive array encoding/decoding.\n- Tabular array encoding/decoding.\n- Nested objects with indentation.\n- Delimiter handling (comma, pipe).\n- Length markers `[#N]`.\n- Quoting behavior for special strings.\n- Round-trip encode → decode.\n- Token savings vs JSON for realistic payloads.\n\n\nTo run the unit tests we can use the Package Manager environment.\n\n```objectscript\nzpm\ndc-toon test -v\n```\n\nYou should see **All PASSED** \n\n\n***\n\n## 🚀 Installation with IPM\n\n```\nzpm:USER\u003einstall dc-toon\n```\n\n## 🛠️ Installation with Docker\n\nThe backend is containerized for easy setup. Follow these steps to get it running.\n\n1.  **Clone the repository:**\n    ```bash\n    git clone [https://github.com/henryhamon/dc-toon.git](https://github.com/henryhamon/dc-toon.git)\n    cd dc-toon\n    ```\n\n2.  **Build the Docker container:**\n    This command builds the necessary images for the application. The `--no-cache` flag ensures you are building from the latest source.\n    ```bash\n    docker-compose build --no-cache --progress=plain\n    ```\n\n3.  **Start the application:**\n    This command starts the services in detached mode (`-d`).\n    ```bash\n    docker-compose up -d\n    ```\n\n4.  **Stop and remove containers (when done):**\n    To stop the application and remove all associated containers, networks, and volumes.\n    ```bash\n    docker-compose down --rmi all\n    ```\n\n***\n\n## 💡 Usage Examples\n\n### Encode a Simple Object\n\n```objectscript\nSet obj = {\"name\":\"Alice\",\"age\":30}\nSet toon = ##class(dc.toon.Converter).ToTOON(obj)\n\n// name: Alice\n// age: 30\n```\n\n### Encode a Tabular Array\n\n```objectscript\nSet users = ##class(%DynamicArray).%New()\nDo users.%Push({\"id\":1,\"name\":\"Alice\",\"age\":30})\nDo users.%Push({\"id\":2,\"name\":\"Bob\",\"age\":25})\n\nSet toon = ##class(dc.toon.Converter).ToTOON(users)\n\n// [2,]{id,name,age}:\n//   1,Alice,30\n//   2,Bob,25\n```\n\n### Decode Back from TOON\n\n```objectscript\nSet toonStr = \"[2,]{id,name}:\"_$Char(10)_\"  1,Alice\"_$Char(10)_\"  2,Bob\"\nSet status = ##class(dc.toon.Converter).FromTOON(toonStr,, .result)\n// result is a %DynamicArray of %DynamicObject\n```\n\n***\n\n## 🔍 Limitations \n\n- IRIS does not have a native `null` type; empty values are represented using `\"\"`.  \n  dc-toon maps empty / undefined values to the literal `null` in TOON where appropriate.\n- Boolean values in IRIS are typically `0` / `1`. The current implementation focuses on correctness and compactness rather than adding a distinct boolean type.\n\n***\n\n## 🙌 Credits\n\n- Original TOON idea and Python implementations:\n  - [xaviviro/python-toon (reference and inspiration for behavior/format).](https://github.com/xaviviro/python-toon)\n\n\u003e dc-toon is developed with ❤️ by \n\u003e [Henry Pereira](https://community.intersystems.com/user/henry-pereira)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhenryhamon%2Fdc-toon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhenryhamon%2Fdc-toon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhenryhamon%2Fdc-toon/lists"}