🎯 Tenty Parser

Tenty Parser es una herramienta CLI moderna para parsear, transformar y convertir entre diferentes formatos de datos estructurados: JSON, YAML y TOON (Token-Oriented Object Notation).

✨ Características

• 🔍 Parse múltiples formatos: JSON, YAML, TOON
• 🌳 Visualización en árbol de estructuras de datos
• 📊 Generación de schemas: JSON Schema y OpenAPI
• 🔄 Conversión entre formatos con un solo comando
• 🎨 Salida colorida con Rich
• ⚡ Optimizado para LLMs con formato TOON (30-60% reducción de tokens)

📦 Instalación

Requisitos previos

• Python 3.12+

Con pip (uso normal)

pip install tenty-parser

Esto deja disponible el comando tenty directamente en tu shell — no hace falta clonar el repositorio ni usar python -m para nada:

tenty --help

Si estás desarrollando el proyecto en sí (no solo usándolo), ve a Desarrollo más abajo para instalar desde el código fuente con uv.

Si instalas con uv en vez de pip, lee esto. tenty-parser depende de toon-format (la librería que maneja el formato TOON), y a día de hoy esa librería no tiene ninguna versión estable publicada — solo existe como pre-release (0.9.0b1). Un pip install tenty-parser normal instala bien porque pip sí resuelve pre-releases cuando es la única opción disponible. Pero uv add tenty-parser / uv sync no lo hace por defecto: en vez de fallar con un error, se queda calladamente instalado en una versión vieja de tenty-parser que sí puede resolver sin pre-releases — nunca vas a enterarte de que te perdiste una actualización a menos que lo busques a propósito. Si usas uv, instala así:

uv add tenty-parser --prerelease=allow

o agrega esto a tu pyproject.toml:

[tool.uv]
prerelease = "allow"

Este es un problema del lado de toon-format, no algo que podamos arreglar desde tenty-parser mientras esa librería no publique una versión estable. Detalle completo en docs/dependency-research.md.

🚀 Uso

Comandos principales

1. Parse - Analizar archivos

# Visualizar estructura en árbol
tenty parse data.json

# Mostrar como JSON estructurado
tenty parse data.json --format json

# Generar schema
tenty parse data.json --format schema

# Convertir a TOON
tenty parse data.json --format toon

# Guardar resultado
tenty parse data.json --format toon -o output.toon

2. Convert - Convertir entre formatos

# JSON a TOON
tenty convert input.json output.toon --to toon

# YAML a JSON
tenty convert config.yaml config.json --to json

# JSON a YAML
tenty convert data.json data.yaml --to yaml

# TOON a JSON
tenty convert data.toon data.json --to json

3. Schema - Generar schemas

# Generar JSON Schema
tenty schema data.json -o schema.json

# Generar OpenAPI Schema
tenty schema data.json --format openapi -o openapi.json

# Con título personalizado
tenty schema data.json --title "User API Schema"

4. Version - Ver versión

tenty version

📖 Formato TOON

TOON (Token-Oriented Object Notation) es un formato optimizado para modelos de lenguaje que reduce el uso de tokens en 30-60%.

Características de TOON

• ✅ Arrays con tamaño explícito: users[2]:
• ✅ Formato tabular para objetos: users[2]{id,name,role}:
• ✅ Indentación en lugar de llaves
• ✅ Sin comillas innecesarias

Ejemplo de conversión

JSON original:

{
  "user": {
    "name": "John Doe",
    "age": 30,
    "tags": ["developer", "python", "rust"]
  },
  "posts": [
    {
      "id": 1,
      "title": "Hello World",
      "published": true
    }
  ]
}

TOON equivalente:

user:
  name: "John Doe"
  age: 30
  tags[3]: developer, python, rust
posts[1]{id,title,published}:
  1,"Hello World",true

Reducción de tokens: ~45% menos tokens que JSON

🏗️ Estructura del proyecto

tenty-parser/
├── tenty_parser/
│   ├── models/
│   │   └── structure.py          # Modelos Pydantic
│   ├── parsers/
│   │   ├── json_parser.py        # Parser JSON
│   │   ├── yaml_parser.py        # Parser YAML
│   │   └── toon_parser.py        # Parser TOON
│   ├── transformers/
│   │   ├── to_structure.py       # Transformador a estructura
│   │   ├── to_toon.py           # Transformador a TOON
│   │   └── to_schema.py         # Generador de schemas
│   └── cli.py                    # Interfaz CLI
├── tests/                        # Suite de tests (pytest, cobertura mínima 90%)
├── docs/
│   ├── functionality.md          # Arquitectura y comandos del CLI
│   ├── deployment.md             # Flujo de release y publicación a PyPI
│   ├── dependency-research.md    # Hand-written vs. librerías mantenidas
│   └── testing.md                # Ejemplos reales de entrada/salida por comando
├── pyproject.toml               # Configuración del proyecto
├── README.md                    # Este archivo
├── LICENSE                      # Licencia personalizada
└── .gitignore                   # Archivos ignorados

Documentación detallada: docs/functionality.md y docs/deployment.md.

🔧 Desarrollo

Si vas a modificar el código del proyecto (no solo usarlo), instala desde el código fuente con uv:

# Clonar repositorio
git clone https://github.com/Keniding/tenty-parser.git
cd tenty-parser

# Instalar en modo desarrollo (crea el venv e instala el comando `tenty` en él)
uv sync

# Ejecutar el CLI desde el código fuente
uv run tenty --help

# Ejecutar tests con cobertura
uv run pytest --cov=tenty_parser --cov-report=term-missing

Agregar nuevas características

1. Fork el proyecto
2. Crea una rama: git checkout -b feature/nueva-caracteristica
3. Commit cambios: git commit -am 'Agregar nueva característica'
4. Push a la rama: git push origin feature/nueva-caracteristica
5. Crea un Pull Request

📚 Ejemplos

Ejemplo 1: Analizar API Response

# Descargar respuesta de API
curl https://api.example.com/users > users.json

# Visualizar estructura
tenty parse users.json

# Generar schema para documentación
tenty schema users.json -o users-schema.json

# Convertir a TOON para usar con LLMs
tenty convert users.json users.toon --to toon

Ejemplo 2: Convertir configuración

# Convertir YAML a JSON
tenty convert config.yaml config.json --to json

# Ver estructura
tenty parse config.json --format tree

Ejemplo 3: Workflow completo

# 1. Parse archivo original
tenty parse data.json --format tree

# 2. Generar schema
tenty schema data.json -o schema.json

# 3. Convertir a TOON para LLM
tenty convert data.json data.toon --to toon

# 4. Convertir de vuelta a JSON
tenty convert data.toon data-restored.json --to json

🎯 Casos de uso

Para desarrolladores

• 📝 Generar schemas automáticamente desde ejemplos
• 🔄 Convertir entre formatos de configuración
• 🔍 Explorar estructuras de datos complejas
• 📊 Documentar APIs

Para trabajar con LLMs

• ⚡ Reducir tokens en prompts (formato TOON)
• 📦 Estructurar datos de forma eficiente
• 🎯 Mejorar comprensión de estructuras por LLMs

Para análisis de datos

• 🌳 Visualizar jerarquías de datos
• 📋 Validar estructuras
• 🔄 Normalizar formatos

🤝 Contribuir

¡Las contribuciones son bienvenidas! Por favor:

1. Lee las guías de contribución
2. Abre un issue para discutir cambios grandes
3. Escribe tests para nuevas características
4. Mantén el estilo de código consistente

Nota: Al contribuir, aceptas que tus contribuciones se licencien bajo los mismos términos que este proyecto.

📄 Licencia

Este proyecto está bajo una Licencia Personalizada con los siguientes términos:

✅ Uso Personal y No Comercial

• LIBRE: Puedes usar, modificar y distribuir el software gratuitamente
• Requisito: Debes dar crédito al autor original (Keniding)

⚠️ Uso Comercial

• REQUIERE AUTORIZACIÓN: Contacta para obtener una licencia comercial
• Incluye: Compensación acordada y/o reconocimiento

📝 Reconocimiento Obligatorio

En cualquier uso del software, debes incluir:

Powered by Tenty Parser - Created by Keniding
https://github.com/Keniding/tenty-parser

Para más detalles, consulta el archivo LICENSE.

Para licencias comerciales, contacta a través de:

• GitHub: @Keniding
• Issues: tenty-parser/issues

🙏 Agradecimientos

• Rich - Beautiful terminal output
• Typer - CLI framework
• Pydantic - Data validation
• TOON Format - Inspiration

📞 Contacto

• Autor: Keniding
• GitHub: @Keniding
• Repositorio: tenty-parser

🗺️ Roadmap

• Tests unitarios completos
• Parser TOON más robusto
• Soporte para más formatos (XML, TOML)
• Validación de schemas
• API Python para uso programático
• Plugins para editores (VSCode)
• Documentación interactiva

---

⭐ Si te gusta este proyecto, dale una estrella en GitHub!

---

Powered by Tenty Parser - Created by Keniding