moai-formats-data

データ形式スペシャリスト

クイックリファレンス

高度なデータ形式管理 — TOON エンコーディング、JSON／YAML の最適化、シリアライズのパターン、パフォーマンスが重要なアプリケーション向けのデータ検証を網羅した包括的なデータ処理です。

主な機能：

• TOON エンコーディング：LLM との通信において、JSON と比較してトークンを 40～60％削減
• JSON／YAML の最適化：効率的なシリアライズおよび解析のパターン
• データ検証：スキーマ検証、型チェック、エラー処理
• 形式変換：データ形式間のシームレスな変換
• パフォーマンス：最適化されたデータ構造とキャッシュ戦略
• スキーマ管理：動的なスキーマの生成と進化

使用する場面：

• トークン予算内での LLM へのデータ送信の最適化
• 高パフォーマンスなシリアライズ／デシリアライズ
• スキーマ検証とデータ整合性の確認
• 形式変換とデータ変換
• 大規模データセットの処理と最適化

クイックスタート：

TOONEncoder インスタンスを作成し、user と age フィールドを含む辞書を渡して encode を呼び出し、データを圧縮します。エンコード結果はトークンを 40～60％削減できます。decode を呼び出すと、元のデータ構造に復元できます。

JSONOptimizer インスタンスを作成し、大規模なデータセットに対して serialize_fast を呼び出すと、超高速な JSON 処理を実現できます。

DataValidator インスタンスを作成し、name を必須の文字列型として定義した辞書を渡して create_schema を呼び出します。データとスキーマを渡して validate を呼び出すと、有効性を確認できます。

---

実装ガイド

基本概念

TOON（Token-Optimized Object Notation）：

• LLM のトークン使用量に合わせて最適化された、バイナリー互換のカスタム形式
• 型マーカー：数値には #、ブール値には !、タイムスタンプには @、null には ~ を使用
• 一般的なデータ構造では、JSON と比較してサイズを 40～60％削減
• 情報を損なわないエンコード／デコードの往復処理

パフォーマンスの最適化：

• orjson による超高速な JSON 処理。標準の json と比較して 2～5 倍高速
• ijson を使用した大規模データセットのストリーミング処理
• LRU による古い項目の削除とメモリー管理を備えたインテリジェントなキャッシュ
• スキーマの圧縮と検証の最適化

データ検証：

• カスタムルールとパターンによる型安全な検証
• スキーマの進化と移行のサポート
• フィールド間の検証と依存関係のチェック
• パフォーマンスを最適化した一括検証

基本的な実装

LLM 最適化のための TOON エンコーディング：

TOONEncoder インスタンスを作成します。id、name、active のブール値、created の datetime を含む user オブジェクトと、permissions 配列を含むデータを定義します。encode を呼び出して圧縮し、decode を呼び出して復元します。サイズを比較して、削減できていることを確認します。

高速な JSON 処理：

JSONOptimizer インスタンスを作成します。serialize_fast を呼び出してバイト列を取得し、deserialize_fast を呼び出して解析します。type オブジェクトと properties 定義を指定して compress_schema を使用すると、繰り返し行う検証を最適化できます。

データ検証：

DataValidator インスタンスを作成します。username は文字列型で最小長が 3、email はメール型、age は最小値が 13 の任意の整数型となる user_schema を定義します。データとスキーマを渡して validate を呼び出し、結果の valid ステータス、sanitized_data、または errors リストを確認します。

一般的なユースケース

API レスポンスの最適化：

TOONEncoder でデータをエンコードし、LLM で使用する API レスポンスを最適化する関数を作成します。対応する関数を作成して、最適化されたレスポンスの TOON データをデコードし、辞書に戻します。

設定管理：

YAMLOptimizer インスタンスを作成し、設定ファイルのパスを渡して load_fast を呼び出します。base_config、env_config、user_config を渡して merge_configs を呼び出し、複数ファイルをマージします。

大規模データセットの処理：

chunk_size を 8192 に設定した StreamProcessor を作成します。各項目を処理する process_item 関数を定義します。ファイルパスとコールバックを渡して process_json_stream を呼び出し、JSON ファイルをメモリーに読み込まずに処理します。

---

高度な機能の概要

高度な TOON 機能

カスタム型ハンドラー（UUID、Decimal）、ストリーミングによる TOON 処理、TOON の一括エンコード、ベンチマークを用いたパフォーマンス特性については、modules/toon-encoding.md を参照してください。

高度な検証パターン

フィールド間の検証、スキーマの進化と移行、カスタム検証ルール、バッチ検証の最適化については、modules/data-validation.md を参照してください。

パフォーマンスの最適化

インテリジェントなキャッシュ戦略、キャッシュのウォームアップと無効化、メモリ管理、パフォーマンス監視については、modules/caching-performance.md を参照してください。

JSON/YAML の高度な機能

ストリーミング JSON 処理、メモリ効率の高い解析、スキーマの圧縮、形式変換ユーティリティについては、modules/json-optimization.md を参照してください。

---

相性の良いモジュール

• moai-domain-backend - バックエンドのデータシリアライズと API レスポンス
• moai-domain-database - データベースのデータ形式の最適化
• moai-foundation-core - MCP のデータシリアライズと転送パターン
• moai-workflow-docs - ドキュメントのデータ形式
• moai-foundation-context - トークン予算に合わせたコンテキストの最適化

---

モジュールの参照先

コア実装モジュール：

• modules/toon-encoding.md - TOON エンコーディングの実装
• modules/json-optimization.md - 高パフォーマンスな JSON/YAML
• modules/data-validation.md - 高度な検証とスキーマ
• modules/caching-performance.md - キャッシュ戦略

サポートファイル：

• modules/INDEX.md - モジュールの概要と統合パターン
• reference.md - 詳細なリファレンスドキュメント
• examples.md - 完全な動作例

---

技術スタック

コアライブラリ：

• orjson：超高速な JSON の解析とシリアライズ
• PyYAML：C ベースのローダーによる YAML 処理
• ijson：大容量ファイル向けのストリーミング JSON パーサー
• python-dateutil：高度な日時解析
• regex：高度な正規表現のサポート

パフォーマンスツール：

• lru_cache：組み込みのメモ化
• pickle：オブジェクトのシリアライズ
• hashlib：キャッシュ用のハッシュ生成
• functools：関数デコレーターとユーティリティ

検証ライブラリ：

• jsonschema：JSON Schema の検証
• cerberus：軽量なデータ検証
• marshmallow：オブジェクトのシリアライズ／デシリアライズ
• pydantic：Python の型ヒントを使ったデータ検証

---

リソース

実際に動作するコード例については、examples.md を参照してください。

ステータス：本番環境対応 最終更新日：2026-01-11 メンテナンス担当：MoAI-ADK Data Team