Dominando la CLI de TOON

Si has estado trabajando con Grandes Modelos de Lenguaje (LLMs), sabes que JSON es la lengua franca del intercambio de datos. Sin embargo, también sabes que JSON es notoriamente "verborrágico". Todas esas llaves, comillas y claves repetidas se comen tu ventana de contexto, aumentan la latencia y elevan los costos de la API.

Aquí es donde brilla TOON (The Object-Oriented Notation). Mientras que la biblioteca TypeScript es excelente para el código de aplicación, a veces solo necesitas hacer las cosas rápidamente en la terminal. Ya sea que estés depurando un prompt, preparando un conjunto de datos o simplemente tengas curiosidad sobre cuánto dinero podrías ahorrar en tokens, la CLI @toon-format/toon es tu nueva mejor amiga.

En esta guía, veremos cómo aprovechar la Interfaz de Línea de Comandos de TOON para integrar la optimización de datos directamente en tus flujos de trabajo de shell.

Configuración

Una de las mejores cosas de las herramientas modernas de JavaScript es que a menudo no necesitas "instalar" nada para empezar. Si solo quieres probar TOON en un archivo individual, puedes usar npx para ejecutar el binario directamente:

npx @toon-format/cli entrada.json -o salida.toon

Sin embargo, si planeas usar esto con frecuencia —y una vez que veas los ahorros de tokens, probablemente lo harás— una instalación global es el camino a seguir. Te da acceso al comando conciso toon en cualquier parte de tu sistema.

npm install -g @toon-format/cli
# o
pnpm add -g @toon-format/cli

Una vez instalado, estás listo para comenzar a reducir tus datos.

La Magia de la Detección Automática

La CLI de TOON está diseñada para ser inteligente sobre lo que estás tratando de hacer. Rara vez necesitas decirle explícitamente que codifique o decodifique; mira las extensiones de tus archivos para decidir.

Si le das un archivo .json, asume que quieres codificarlo a TOON. Si proporcionas un archivo .toon, cambia al modo de decodificación para devolverte JSON.

# Codifica automáticamente a TOON
toon datos.json -o comprimido.toon

# Decodifica automáticamente a JSON
toon comprimido.toon -o restaurado.json

Pero donde la CLI realmente demuestra su valor es en la "filosofía Unix" —herramientas pequeñas unidas libremente. Debido a que la CLI de TOON lee de la entrada estándar (stdin) y escribe en la salida estándar (stdout), puedes canalizar datos directamente a través de ella.

# Canaliza JSON directamente a TOON
cat conjunto-datos-grande.json | toon > datos.toon

# Haz eco de un objeto rápido para ver cómo se ve en TOON
echo '{"nombre": "Ada", "rol": "admin"}' | toon

Cuando estás canalizando datos vía stdin, la CLI por defecto usa el modo codificar. Si necesitas decodificar un flujo de datos TOON proveniente de otro proceso, simplemente agrega la bandera --decode (o -d).

Analizando Ahorros de Tokens

Optimizar formatos de datos a menudo se trata de juegos de adivinanzas. "¿Si elimino los espacios en blanco, cuánto ahorro?" "¿Qué pasa si cambio a YAML?"

La CLI de TOON elimina las conjeturas con la bandera --stats. Al codificar, esta opción calcula el recuento estimado de tokens y te muestra los ahorros inmediatamente. Esto es invaluable cuando estás presupuestando llamadas a LLM de alto volumen.

toon contexto.json --stats

Podrías ver una salida indicando una reducción del 30% o 40% en tamaño. Eso no es solo espacio en disco; es un 40% menos de latencia y un 40% menos de costo en tokens de entrada.

Ajuste Avanzado: Delimitadores y Formato

Por defecto, TOON usa comas para separar elementos de array, similar a JSON. Sin embargo, diferentes tokenizadores de LLM se comportan de manera diferente con la puntuación. A veces, un carácter de tabulación o una barra vertical (|) es más eficiente en tokens que una coma.

La CLI te permite intercambiar delimitadores sobre la marcha. Si estás tratando con datos tabulares, cambiar a un delimitador de tabulación puede hacer que la salida se vea más limpia y se procese de manera más eficiente.

Para una lista de productos, esto transforma la salida de una lista separada por comas a una estructura limpia separada por tabuladores que se parece casi a una hoja de cálculo, lo que muchos modelos analizan excepcionalmente bien.

# Usa tabuladores para elementos de array
toon items.json --delimiter "\t" -o items.toon

::: tip Consejo Pro: Los delimitadores de tabulación a menudo reducen la necesidad de escapar comillas y pueden resultar en una mejor tokenización para datos numéricos. Si estás procesando conjuntos de datos masivos, prueba --delimiter "\t" para exprimir cada bit de eficiencia. :::

Comprimiendo Estructura con Plegado de Claves

Una de las características más nuevas (introducida en la especificación v1.5) disponible en la CLI es el Plegado de Claves. Los datos JSON a menudo están profundamente anidados, con claves contenedoras como data.response.items que agregan profundidad estructural sin agregar significado.

La CLI te permite "plegar" estas claves anidadas en una sola ruta de notación por puntos, aplanando la jerarquía y ahorrando tokens en indentación y llaves.

toon estructura-profunda.json --key-folding safe -o plana.toon

Esto transforma objetos anidados:

{ "user": { "profile": { "id": 1 } } }

En una representación TOON concisa:

user.profile.id: 1

Si necesitas convertir esto de vuelta a JSON completo más tarde, puedes usar la bandera --expand-paths safe durante la decodificación para reconstruir perfectamente la estructura profunda de objetos.

Integrando en Tuberías

El verdadero poder de la CLI de TOON viene cuando la encadenas con otras herramientas como curl y jq. Puedes obtener datos de una API, filtrarlos a lo esencial y convertirlos a TOON en una sola línea —listos para ser pegados en un prompt o enviados a un endpoint de inferencia.

En este flujo de trabajo, obtienes los datos, extraes solo los usuarios activos, los conviertes a un formato TOON delimitado por pipes y obtienes un informe de estadísticas sobre cuántos tokens acabas de ahorrar.

curl -s https://api.example.com/users \
  | jq '.data.active_users' \
  | toon --stats --delimiter "|"

Resumen

El @toon-format/cli es más que solo un convertidor de archivos; es un cinturón de herramientas para la era de los LLM. Al mover el procesamiento de datos a la línea de comandos, puedes iterar más rápido, visualizar optimizaciones inmediatamente e integrar formatos eficientes en tokens en tus flujos de trabajo de ingeniería existentes.

Ya sea que estés preparando documentos RAG (Generación Aumentada por Recuperación) o simplemente tratando de ajustar un blob JSON masivo en una pequeña ventana de contexto, dale una vuelta a la CLI. Tu presupuesto de tokens te lo agradecerá.