Token-Oriented Object Notation (TOON) for PHP Developers

Token-Oriented Object Notation (TOON) for PHP Developers ![rw-book-cover](https://img.youtube.com/vi/Nk9ayWxkJ1M/maxresdefault.jpg) 🔗 **Source:** [Token-Oriented Object Notation (TOON) for PHP Developers](https://www.youtube.com/watch?v=Nk9ayWxkJ1M) > [!note]+ Document Notes > tags: #php #ai #llm #api-optimization #token-efficiency > author: Scott Keck Warren > source: PHP Architect > reference: https://www.youtube.com/watch?v=Nk9ayWxkJ1M > date created: 2024-12-19 19:45 > > # 🏷️ Title: Token-Oriented Object Notation (TOON) For PHP Developers >  ## 🧰 Action Inbox - [H1] Evaluate current LLM API costs for JSON data transmission — identify repetitive field patterns #api-optimization - [H2] Test TOON library on production datasets — measure actual token savings vs benchmarks #php - [H3] Update system prompts to include TOON format instructions — ensure model comprehension #llm ## 🧭 Table of Contents - [[#📝 Summary]] - [[#📖 Main Content]] - [[#🗒️ Notes]] - [[#📚 References]] - [[#🗣️ Paraphrase]] - [[#📰 Newsletter]] - [[#✅ Action Items]] - [[#🧪 Hypotheses]] - [[#📊 Methodology]] - [[#❓ Questions]] - [[#🔮 Future Research]] - [[#💡 Implications]] - [[#🧠 Learning Styles Assessment]] - [[#📊 Accessibility Assessment]] - [[#🌍 DEIB Assessment]] - [[#✅ Logical Validity]] - [[#🛡️ DARVO Analysis]] - [[#🎯 Conclusion]] ### 🔗 References - [TOON PHP Library](https://packagist.org/packages/toon-php/toon) - [PHP Score](https://phpscore.com) ## 📝 Summary - **What happened**: Introduction of Token-Oriented Object Notation (TOON) as an alternative to JSON for sending structured data to large language models - **Why it matters**: JSON repetition of field names across records wastes tokens and increases API costs significantly at scale - **Key stakeholders**: PHP developers using LLM APIs, especially those processing large datasets - **Risks and tradeoffs**: Requires format explanation in prompts, only works with flat consistent data, needs scale to be cost-effective - **Bottom line**: TOON can reduce token usage by ~60% for tabular data by writing field names once as headers instead of repeating per record ## 📖 Main Content Token-Oriented Object Notation (TOON) addresses a specific cost problem in large language model API usage: the repetitive nature of JSON field names when sending arrays of similar objects. Instead of repeating field names for every record (which can result in thousands of redundant tokens), TOON uses a tabular format with field names as headers and comma-separated values for each record. The format trades JSON's familiar structure for YAML-like indentation and eliminates punctuation tokens while maintaining data integrity. For uniform datasets like podcast statistics or user records, this approach can achieve approximately 60% token reduction compared to JSON. However, TOON requires explicit format instructions in system prompts since LLMs aren't trained on this notation. It works best with flat, consistent records and falls apart with nested objects, optional fields, or irregular structures. The token savings only justify the format explanation overhead when working with hundreds or thousands of records. ## 🗒️ Notes #### ⏱️ [00:00](https://youtu.be/Nk9ayWxkJ1M?t=0) — [H1] Token cost problem with JSON - Key idea: JSON field name repetition wastes tokens when sending arrays to LLMs - Evidence: "Every time you send structured data to a large language model API, you're paying for tokens" #### ⏱️ [01:45](https://youtu.be/Nk9ayWxkJ1M?t=105) — [H2] JSON repetition example - Key idea: Field names repeat once per record in standard JSON arrays - Evidence: "Each one shows up three times, once per record... 500 episodes, you're repeating those same six field names 500 times" #### ⏱️ [03:15](https://youtu.be/Nk9ayWxkJ1M?t=195) — [H1] TOON format introduction - Key idea: TOON eliminates repetition with tabular format and reduced punctuation - Evidence: "Field names once at the top, one row per record below that... TOON achieves about a 60% token reduction" #### ⏱️ [05:30](https://youtu.be/Nk9ayWxkJ1M?t=330) — [H2] PHP implementation with toon-php library - Key idea: Ready-made library handles TOON encoding and decoding - Evidence: "It's called tune PHP... allows us to simply call tune in code on our data" #### ⏱️ [06:45](https://youtu.be/Nk9ayWxkJ1M?t=405) — [H1] System prompt requirement - Key idea: Models must be explicitly told how to parse TOON format - Evidence: "You also need to tell the model how to read this format... the model treats your data as unstructured text" #### ⏱️ [07:30](https://youtu.be/Nk9ayWxkJ1M?t=450) — [H2] Format explanation overhead - Key idea: TOON format instructions must be included in every prompt - Evidence: "You have to explain the format every time... JSON is something every large language model has been trained on" #### ⏱️ [08:15](https://youtu.be/Nk9ayWxkJ1M?t=495) — [H2] Data structure limitations - Key idea: TOON only works with flat, consistent tabular data - Evidence: "Nested objects, optional fields that vary between records, arrays inside arrays, all that breaks the tabular structure" #### ⏱️ [09:00](https://youtu.be/Nk9ayWxkJ1M?t=540) — [H3] Scale requirements for cost savings - Key idea: Token overhead only justified with hundreds or thousands of records - Evidence: "The math only works at scale... one or two records then the token overhead... costs more than you save" #### ⏱️ [09:30](https://youtu.be/Nk9ayWxkJ1M?t=570) — [H2] Accuracy benchmarks - Key idea: TOON maintains JSON-level accuracy in LLM responses - Evidence: "In benchmarks, tune is just as accurate as JSON for returned results" #### ⏱️ [10:15](https://youtu.be/Nk9ayWxkJ1M?t=615) — [H3] Hybrid approach option - Key idea: Combine TOON for flat data with JSON for complex structures - Evidence: "You might also do a hybrid where tune handles the flat parts and JSON handles anything irregular" ## 📚 References - [TOON PHP Library](https://packagist.org/packages/toon-php/toon) - [PHP Score Technical Debt Monitoring](https://phpscore.com) - [PHP Architect Channel](https://www.youtube.com/@PHPArchitect) ## 🗣️ Paraphrase - TOON solves the expensive problem of repeating JSON field names when sending tabular data to LLM APIs by using a header-row format that lists field names once - The format requires explicit parsing instructions in system prompts since models aren't trained on TOON notation, but can reduce token usage by approximately 60% on uniform datasets - Implementation works best for flat, consistent records at scale (hundreds+ records) and falls apart with nested or irregular data structures ## 📰 Newsletter **Cut Your LLM API Costs by 60% with TOON Format** If you're sending structured data to LLM APIs regularly, you're probably overpaying for tokens. Every JSON field name repeats for each record - send 500 podcast episodes and you're tokenizing the same 6 field names 500 times! **Token-Oriented Object Notation (TOON)** solves this with a simple tabular format: field names once as headers, then comma-separated values per record. The `toon-php` library makes implementation trivial, and benchmarks show ~60% token reduction on uniform datasets. **Key considerations**: You must explain the format in system prompts (LLMs aren't trained on TOON), it only works with flat consistent data, and savings require scale (hundreds of records minimum). Perfect for podcast stats, user analytics, or any tabular data you're currently JSON-encoding for AI analysis. Resources: [TOON PHP Library](https://packagist.org/packages/toon-php/toon), [PHP Score](https://phpscore.com), [PHP Architect](https://www.phparch.com/) ## ✅ Action Items #### DevRel - Developer advocacy: Create TOON format demos for conference talks, measure token savings in live coding sessions - Education: Develop workshops on LLM cost optimization, include TOON in PHP+AI curriculum - Developer experience: Document TOON integration patterns, create migration guides from JSON - Developer marketing: Content series on API cost optimization techniques - Community management: Monitor feedback on TOON adoption, address implementation questions #### WordPress - Core: Evaluate TOON for AI-powered features in core, assess block editor integration opportunities - Core AI: Include TOON format in AI guardrails documentation, test with WordPress data structures - Documentation: Add TOON examples to AI/ML development guides - Plugins: Review AI-powered plugins for token optimization opportunities - Community: Share TOON techniques at WordCamps, create cost optimization resources ## 🧪 Hypotheses - TOON format will show greater token savings on datasets with more fields and higher record counts - Hybrid TOON/JSON approaches will optimize costs while maintaining data structure flexibility - LLM training on TOON format will eventually eliminate the need for explicit parsing instructions - TOON adoption will correlate with increased frequency of batch LLM API calls in production applications ### 📊 Methodology - A/B test TOON vs JSON on identical datasets with varying record counts (10, 100, 1000, 10000) - Measure token usage, API response accuracy, and total cost across multiple LLM providers - Compare implementation complexity and developer experience between formats ### ❓ Questions - How does TOON performance vary across different LLM providers and model architectures? - What's the minimum dataset size where TOON format explanation overhead becomes worthwhile? - Could TOON be extended to handle nested structures while maintaining token efficiency? ### 🔮 Future Research - Investigate automatic JSON-to-TOON conversion based on data structure analysis - Explore TOON integration with popular PHP frameworks and ORM libraries - Develop cost prediction models for TOON vs JSON based on dataset characteristics ### 💡 Implications - **Practice**: Teams processing large datasets through LLM APIs need cost optimization strategies beyond model selection - **Policy**: API budget planning must account for data format efficiency, not just model costs - **Security**: Token optimization formats require validation to ensure no data corruption or injection vulnerabilities - **Education**: PHP curricula should include LLM cost optimization alongside traditional performance topics - **Funding**: Significant API cost reductions possible through data format optimization alone ### 🧠 Learning Styles Assessment Reading level estimate: 9th grade (technical concepts explained clearly with examples) #### 👀 Visual learners - Present: Code examples showing JSON vs TOON side-by-side, tabular data visualization - Improve: Token flow diagrams, cost comparison charts, data structure illustrations #### 🔊 Aural learners - Present: Video explanation with clear narration and pacing - Improve: Audio-only version for podcast consumption, key concept repetition #### 🗣️ Verbal learners - Present: Clear definitions, analogies to spreadsheet headers, concrete examples - Improve: Glossary of tokenization terms, format comparison narratives #### 🧩 Kinesthetic learners - Present: Step-by-step implementation guide, library installation instructions - Improve: Interactive code sandbox, hands-on token counting exercises #### 🧠 Logical learners - Present: Mathematical cost comparison, systematic format breakdown, decision criteria - Improve: Decision tree for format selection, ROI calculations, performance metrics #### 🧑‍🤝‍🧑 Social learners - Present: Community library recommendation, shared implementation experiences - Improve: Discussion forums for TOON adopters, peer code review examples #### 🧘‍♀️ Solitary learners - Present: Self-contained examples, independent benchmarking suggestions - Improve: Personal cost tracking worksheets, self-assessment checklists #### 🌿 Naturalistic learners - Present: Efficiency analogies, waste reduction concepts - Improve: Environmental impact of token efficiency, sustainable API practices ### 📊 Accessibility Assessment #### Screen reader semantics - Present: Clear headings, code examples with proper markup - Improve: Alt text for code screenshots, table headers for comparison data #### Keyboard navigation - Present: Standard video controls, logical tab order in embedded examples - Improve: Skip links for code sections, keyboard shortcuts for video segments #### Contrast and readability - Present: High contrast code highlighting, readable font sizes - Improve: Dark mode code examples, adjustable video caption contrast #### Text resizing and reflow - Present: Responsive video player, scalable code examples - Improve: Prevent code overflow at high zoom levels, maintain video aspect ratio #### Media and captions - Present: Video has clear narration - Improve: Downloadable captions, audio description for visual code examples #### Forms and interactions - Present: Standard video controls - Improve: Keyboard-accessible code copying, screen reader announcements for copied text ### 🌍 DEIB Assessment #### Cultural breadth - Present: Universal programming concepts, platform-agnostic approach - Improve: Examples from diverse business domains, international cost considerations #### Inclusive language - Present: Gender-neutral technical terms, explained acronyms - Improve: Plain language summaries, avoid financial assumptions #### Neurodiversity support - Present: Clear structure, consistent code formatting - Improve: Content warnings for rapid code switching, estimated reading times #### Representation - Present: Focus on technical merit over individual attribution - Improve: Diverse use case examples, varied business contexts #### Psychological safety - Present: Non-judgmental tone about current practices - Improve: Emphasize learning over criticism, acknowledge cost constraints ### ✅ Logical Validity #### Strong reasoning - Deductive strength: Clear mathematical logic showing token repetition leads to increased costs - Inductive strength: Benchmarks support generalization about 60% savings across similar datasets - Causal reasoning: Direct link established between format choice and API costs - Analogical strength: Spreadsheet header analogy effectively explains tabular concept #### Fallacies - Hasty generalization: 60% savings claimed broadly but only tested on specific data types - Appeal to novelty: TOON presented as solution without fully exploring JSON optimization alternatives #### Tone of voice - Overall tone: Educational and practical with appropriate technical detail and cost-conscious perspective ### 🛡️ DARVO Analysis - Deny: No denial patterns present - Attack: No attacks on existing practices or tools - Reverse victim/offender: No victim/offender dynamics present - Emotional cues and rhetoric: Straightforward technical presentation focused on cost optimization ## 🎯 Conclusion TOON represents a targeted solution for a specific but common problem: token waste in LLM API calls when sending structured data. The 60% token reduction for tabular data can translate to significant cost savings at scale, making it a valuable tool for PHP developers working with large datasets and LLM APIs. The format's limitations - requirement for explicit parsing instructions, restriction to flat data structures, and need for scale - are clearly defined, making it easy for developers to determine when TOON is appropriate. The availability of the toon-php library removes implementation barriers, making adoption straightforward for qualifying use cases. For teams regularly processing hundreds or thousands of uniform records through LLM APIs, TOON offers a practical path to cost optimization without sacrificing accuracy or requiring changes to underlying data structures. ## 🧱 Refactor Appendix ### 📚 Literature Split Pad ### [H1] TOON reduces token usage through tabular format > [!quote] [Token-Oriented Object Notation (TOON) For PHP Developers](https://youtu.be/Nk9ayWxkJ1M) by Scott Keck Warren via PHP Architect. Published 2024. Accessed 2024-12-19. > "TOON achieves about a 60% token reduction on uniform data like episode stats." Critical for LLM API cost optimization at scale. [view highlight](https://youtu.be/Nk9ayWxkJ1M?t=195#H1) #xref #articleseed ID: --- ## Full Transcript [00:01] [music] [00:05] >> It's an unfortunate piece of our current [00:06] developer reality that a lot of our day [00:08] is spent worrying about how many tokens [00:11] we're spending. Every time you send [00:13] structured data to a large language [00:15] model API, you're paying for tokens. And [00:18] if you're sending arrays of similar [00:19] objects as JSON, you're paying to repeat [00:22] the same field names for every single [00:24] record. [00:25] It's not a bug in JSON, it's just how [00:27] the format works. But there's a better [00:29] option for this specific use case. In [00:32] this video, we're going to look at Token [00:33] Oriented Object Notation and how it [00:35] strips that repetition out of your data. [00:37] Hello developers and welcome to the PHP [00:39] Architect channel. I'm Scott Keck Warren [00:41] and today we're tackling a cost problem [00:44] that will eventually eventually bite [00:45] anyone who's sending data to large [00:47] language language models regularly. Is [00:50] that you're wasting tokens on formatting [00:52] that doesn't need to be there. [00:54] If you're new here, we cover topics [00:56] related to the PHP ecosystem. Make sure [00:58] you hit that subscribe button so you [01:00] don't miss our next episode. So let's [01:01] say you're tracking podcast episode [01:03] statistics and you want to send that [01:05] data to a large language model. Maybe [01:07] you wanted to flag underperforming [01:09] episodes or summarize listening trends [01:11] across your whole catalog. Here's what a [01:13] typical batch of episode records look [01:15] like in PHP. Now that JSON encode call [01:19] produces some output that's going to [01:20] look something like this. [01:22] And you might notice that there's a lot [01:23] of duplicate information in the keys. [01:25] We're using ID, title, published at, [01:28] downloads, average listening time, [01:29] completion rate kind of over and over [01:31] again. [01:32] Each one shows up three times, once per [01:34] record. Now you might be saying that [01:36] three records is nothing, but as you [01:37] scale up and you send over 500 episodes, [01:40] you're repeating those same six field [01:42] names 500 times. That's 3,000 strings [01:45] that the large language model has to [01:47] tokenize and you're paying for every [01:48] single one of them. [01:50] Regardless of how cheap the tokens are [01:52] individually, your total bill is going [01:54] to climb faster than you would think [01:56] when you're running hundreds of API [01:57] calls a day. TOML stands for [01:59] Token-oriented Object Notation. It [02:01] solves the repetition problem for [02:03] earlier by trading structure for white [02:06] space. We won't see things we're [02:07] accustomed to in PHP like curly braces, [02:10] square brackets, or quoted key names. [02:12] We're just going to get indentation to [02:14] show hierarchy [02:16] like YAML. That alone cuts a [02:18] surprisingly number surprisingly large [02:20] number of punctuation tokens while not [02:22] increasing error rates all that much. An [02:25] even bigger win is the tabular format [02:27] that TOML uses. When all of your records [02:29] share the same fields, you write the [02:30] field names once as a header row, and [02:32] each record becomes a single [02:34] comma-separated line. The keys go from [02:36] appearing once per record to appearing [02:38] once, period. Our episode data in TOML [02:41] looks like this. And uh shockingly, [02:43] that's the whole data set. Field names [02:44] once at the top, one row per record [02:46] below that. And on this simple data, [02:49] TOML achieves about a 60% token [02:51] reduction. Now, it may be hard to get [02:52] excited about three rows, but again, if [02:55] you're sending 500 rows over, that's [02:57] where you really start to see that [02:58] savings. We'll have more after this word [03:00] from our sponsors. [03:02] Every app builds up technical debt over [03:04] time. It's the unfortunate price that we [03:06] pay for shipping new features and moving [03:08] fast. When we build up too much of it [03:10] though, it can start to impact how we [03:11] work. Team velocity suffers, bugs become [03:14] more frequent and take longer to fix, [03:15] and everyone starts to get a little bit [03:17] frustrated. The key to managing debt is [03:19] to measure it. A credit score can help [03:21] you understand how well you're managing [03:22] your debt, and now there's a credit [03:23] score for technical debt. Go to [03:25] phpscore.com to get a free technical [03:27] debt score and monitoring for all of [03:29] your PHP applications today. Head over [03:32] to phpscore.com and get control over [03:34] your technical debt. [03:35] As always with supporting file formats [03:37] in our code, we have two options. We can [03:40] build our own code and do it quickly and [03:42] dirty, or we can find a library on the [03:44] internet that does exactly what we want. [03:46] And as always, thankfully, somebody has [03:48] already done this for us, and it [03:49] supports more options than just our [03:50] basic array option examples. It's called [03:53] tune PHP. [03:55] And it allows us to simply call tune in [03:57] code on our data. Now, to get our data [03:59] in tune format, [04:01] it can also reverse tune back into PHP [04:03] arrays. [04:05] I think it's fairly slick. Now that we [04:07] have our data in tune format, you also [04:09] need to tell the model how to read this [04:11] format. This can be done by adding it to [04:13] your prompt. This is an example on the [04:15] screen. However, you leave that out, the [04:17] model treats your data as unstructured [04:18] text. It will miss the structure [04:20] entirely and give you garbage back. [04:23] It's still wild to me that this works as [04:25] well as it does, but that's where we're [04:27] at. Now, there are some gotchas you have [04:28] to keep in mind. The first is, as with [04:30] everything with large language models, [04:32] we have to include that everything is [04:34] brand new in this field. So, this is [04:36] most likely going to be out of date even [04:38] before we hit that publish button. It's [04:40] still beneficial just to understand the [04:42] concept because there are so many places [04:44] where we messy humans need structure [04:46] that large language models don't. [04:48] Because large language models are [04:50] non-deterministic, your mileage is going [04:52] to vary. But in benchmarks, tune is just [04:54] as accurate as JSON for returned [04:56] results. So, make sure you're always [04:58] looking for bad data coming back from [05:00] the large language model and include a [05:02] this data is generated using AI warning [05:04] on the output. Now, the most annoying [05:06] gotcha is you have to explain the format [05:08] every time. JSON is something every [05:10] large language model has been more or [05:12] less trained on because it exists out [05:14] there in the training data, but tune [05:16] isn't yet. If you don't include these [05:18] parsing instructions in the system [05:20] prompt, the model will read your rows as [05:22] plain text and the response is going to [05:24] be wackadoo. Tune also falls apart with [05:26] messy data. It works best with flat [05:28] consistent records where every item has [05:30] the same fields. Nested objects, [05:33] optional fields that vary between [05:34] records, arrays inside of arrays, all [05:36] that breaks the tabular structure. If [05:39] you're sending that data, stick with [05:40] JSON. You might also do a hybrid where [05:44] tune handles the flat parts and JSON [05:46] handles anything irregular. And then [05:48] finally the math only works at scale. If [05:50] you're just sending one or two records [05:51] then the token overhead of explaining [05:54] the format in the system prompt costs [05:56] more than you save. Hundreds or [05:58] thousands of records is where Tune [05:59] earned its keep. [06:01] As a brief recap, Tune writes field [06:03] names once as a header row and then one [06:05] comma separated line per record after [06:07] that. [06:08] Benchmarks on uniform data like episode [06:10] stats show roughly 60% reduced reduction [06:13] in token usage. You must include the [06:15] format instructions in your system [06:17] prompt as large large language models [06:19] aren't trained yet on the Tune format [06:21] and won't be able to figure it out on [06:22] their own. [06:23] Flat consistent data is where Tune [06:25] shines. Nested or irregular structures [06:27] are still better handled by JSON. If [06:30] this was useful, hit like and share it [06:31] with whoever on your team is watching [06:33] the large language model bills. [06:35] Subscribe so you don't miss the next [06:36] one. This is Scott Keck Warren for the [06:37] PHP Architect channel signing off and [06:39] reminding you to keep watching, keep [06:41] coding, and keep reading.  📄 **Full text:** ![[Full Document Contents/Articles/Token-Oriented Object Notation (TOON) for PHP Developers.md|Token-Oriented Object Notation (TOON) for PHP Developers by YouTube]] ## Highlights - to phpscore.com and get control over your technical debt. As always with supporting file formats in our code, we have two options. We can build our own code and do it quickly and dirty, or we can find a library on the internet that does exactly what we want. And as always, thankfully, somebody has already done this for us, and it supports more options than just our basic array option examples. It's called tune PHP. And it allows us to simply call tune in code on our data. Now, to get our data in tune format, ([View Highlight](https://read.readwise.io/read/01kr6tr56mk53fz2zq8r6z1661)) - Tags: 👻 ai highlighted