datoon

datoon

スマートな構造化データ→TOONゲートウェイ — トークンを実際に節約できる場合にのみ変換します

変換前／変換後 • インストール • 利用できる機能 • 仕組み • ベンチマーク • インストールガイド全文

構造化データをそのままLLMのプロンプトに入れると、冗長になりがちです。TOONを使えばトークンを節約できますが、何も考えずに変換すると、かえってペイロードが悪化することもあります。datoonは判断レイヤーを追加し、構造と節約効果が見込める場合は変換し、そうでない場合は変換を見送ります。また、その理由を必ず説明します。

JSON、CSV、JSONL、YAML、XML、Parquet、Avro、ORC、Excel、Apple Numbersに対応しており、ファイル拡張子から形式を自動検出します。

変換前／変換後

{"users":[
  {"id":1,"name":"Ada","role":"admin"},
  {"id":2,"name":"Lin","role":"analyst"},
  {"id":3,"name":"Grace","role":"viewer"}
]}

users[3]{id,name,role}:
  1,Ada,admin
  2,Lin,analyst
  3,Grace,viewer

{"decision":"convert","reason":"Estimated savings 44.19% (threshold 15.00%)."}

id,name,role
1,Ada,admin
2,Lin,analyst
3,Grace,viewer

datoon data.csv --report-stdout

{"config":{"debug":true},"tags":["a","b"]}

{"decision":"skip","reason":"No uniform object arrays found with at least 3 rows."}

同じデータに、適切な形式。判断理由も必ず明示。

┌──────────────────────────────────────────────────┐
│  PAYLOAD SAVINGS (auto avg)    ████░░░░░░   28%  │
│  PAYLOAD SAVINGS (agent skill) ████████░░   62%  │
│  DECISION ACCURACY             ██████████  100%  │
│  HARMFUL CONVERSIONS BLOCKED   ██████████  100%  │
└──────────────────────────────────────────────────┘

重要

datoonが節約するのはペイロードのトークン、つまりプロンプト内の構造化データ部分のトークンです。節約量はペイロードの形状によって異なります。均一な表形式データはうまく変換できますが、深くネストされた構造や均一でない構造は変換を見送ります。すべての判断に理由が含まれるため、パイプラインで結果を記録、デバッグし、安心して利用できます。

インストール

# core (JSON, CSV, JSONL, XML — no extra deps)
uv add datoon
pip install datoon

# with YAML support
pip install "datoon[yaml]"

# with Excel support
pip install "datoon[excel]"

# with Parquet / ORC / Avro support
pip install "datoon[columnar]"

# with Apple Numbers support
pip install "datoon[numbers]"

# with tiktoken-based token counting
pip install "datoon[tokens]"

# with MCP server
pip install "datoon[mcp]"

# everything
pip install "datoon[all]"

Python 3.12以降が必要です。TOONへの変換には、npxがPATHに含まれたNode.jsが必要ですが、分析や形式の読み取りには不要です。

Claude Codeプラグイン、Codex、MCPの設定については、INSTALL.mdをご覧ください。

利用できる機能

サポートされている入力形式

仕組み

1. 形式を検出 — --format フラグ、ファイル拡張子、または標準入力の場合はデフォルトの JSON から判定します
2. 読み込みと正規化 — ソースを行の辞書のリストとして解析し、コンパクトな JSON にシリアライズします
3. 構造を分析 — オブジェクトの配列は均一か、許容可能な深さか、最小行数を満たすかを確認します
4. 早期に判定 — 対象外のデータは CLI 呼び出しの前にスキップされるため、Node.js のオーバーヘッドはありません
5. 変換と推定 — TOON CLI を実行し、トークンの削減量を計算します
6. 削減量を判定 — しきい値未満なら JSON を返し、しきい値以上ならレポートとともに TOON を返します

どの経路でも、decision、reason、トークン推定値を含む ConversionReport が返されます。パイプラインで予期しない動作が起こることはありません。

クイックスタート

JSON（標準入力）：

echo '{"users":[{"id":1,"name":"Ada"},{"id":2,"name":"Lin"},{"id":3,"name":"Grace"}]}' | datoon --report-stdout

CSV（拡張子から自動検出）：

datoon data.csv --report-stdout

JSONL：

datoon data.jsonl -o output.toon

YAML（datoon[yaml] が必要）：

datoon data.yaml --report-stdout

Parquet（datoon[columnar] が必要）：

datoon data.parquet --report ./report.json

形式を明示的に指定：

datoon --format csv < data.csv --report-stdout

変換を強制（判定をバイパス — 実験用）：

datoon data.json --force --report-stdout

Python API

JSON 変換：

from datoon import convert_json_for_llm, ConversionConfig, DatoonError

config = ConversionConfig(min_savings_ratio=0.15, max_depth=6, min_uniform_rows=3)

try:
    outcome = convert_json_for_llm(raw_json, config)
except DatoonError as exc:
    raise

# outcome.payload_text  — TOON or original JSON
# outcome.report.decision  — "convert" | "skip"
# outcome.report.reason    — human-readable explanation
send_to_model(outcome.payload_text)

read_tabular で任意の形式を指定：

import json
from pathlib import Path
from datoon import read_tabular, convert_json_for_llm, ConversionConfig

# text formats: csv, jsonl, yaml, xml
rows = read_tabular("csv", text=csv_string)

# binary formats: excel, parquet, orc, avro, numbers
rows = read_tabular("parquet", path=Path("data.parquet"))

json_text = json.dumps(rows, separators=(",", ":"))
outcome = convert_json_for_llm(json_text, ConversionConfig())
send_to_model(outcome.payload_text)

構造のみを分析（Node.js は不要）：

from datoon.analyzer import analyze_payload
from datoon.models import ConversionConfig

analysis = analyze_payload(parsed_data, ConversionConfig())
print(analysis.is_candidate, analysis.reason)

MCP サーバー

datoon には、3 つのツールを備えた MCP サーバーが含まれています。

Claude Desktop / Cursor / Windsurf の設定：

{
  "mcpServers": {
    "datoon": {
      "command": "uvx",
      "args": ["--from", "datoon[mcp]", "datoon", "mcp"]
    }
  }
}

ローカルで実行：

datoon mcp     # or the standalone script: datoon-mcp

MCP Registry、Smithery、および Glama に掲載されています。MARKETPLACES.md を参照してください。

Claude Code プラグイン

GitHub から直接インストールします。

claude plugin marketplace add andrii-su/datoon
claude plugin install datoon@datoon

セッション中に呼び出します。

/datoon
convert this JSON to TOON if it saves tokens
use datoon mode for structured data

CLI リファレンス

形式はファイル拡張子から自動検出されます。上書きする場合や標準入力から読み込む場合は、--format を使用してください。

ベンチマーク

PYTHONPATH=src python benchmarks/run.py --dry-run
PYTHONPATH=src python benchmarks/run.py
PYTHONPATH=src python benchmarks/run.py --update-readme

自動モードが強制変換を上回る理由

自動モードでは、メリットが小さいデータやリスクの高いデータ（orders-nested、mixed-non-uniform）を避けながら、適したデータでは強制 TOON と同等の平均トークン数を実現します。判断ごとに、理由を含むレポートが表示されます。

強制変換では、5/5 のペイロードの変換に成功しました。

フォーマット変換ベンチマーク

一般的な構造化フォーマット（CSV、JSONL、XML、YAML）から変換した場合のトークン削減量です。 ベースラインは同じデータの JSON 表現です。これは、datoon を使わずに LLM が受け取る形式です。

強制変換では、4/4 のペイロードの変換に成功しました。

エージェントスキルの評価

アーティファクトベースのサブエージェント比較 — 同一の分析タスクを 2 つのモードで実施します。

• with_skill：エージェントに datoon スキルを与え、変換ワークフローに従わせます。
• without_skill：エージェントは JSON を直接使用し、TOON も datoon も使用しません。

ペイロードサイズ 3 種類 × 3 回の反復 = エージェントの実行は合計 18 回です。どちらのモードも、回答の正解率は 100% でした。

レポート全文と生の出力： benchmarks/agent_skill_eval/。削減量はペイロードのトークン数の推定値であり、エンドツーエンドのモデル使用トークン数全体ではありません。

開発

コントリビューターのワークフロー：CONTRIBUTING.md。メンテナー／エージェント向けメモ：CLAUDE.md。

セットアップ：

uv sync --extra dev
uvx pre-commit install

テスト：

pytest -m "not integration"   # unit only (102 tests)
pytest                        # with integration (requires Node.js + npx)

スキルの同期とプラグインのメタデータ：

python scripts/validate_skill_sync.py
python scripts/validate_plugin_metadata.py

リンク

• INSTALL.md — インストール方法の全体一覧、すべての対象、エージェントごとの詳細
• CONTRIBUTING.md — コントリビューターのワークフロー
• CLAUDE.md — エージェント向けメンテナーガイド
• CHANGELOG.md — リリース履歴
• SECURITY.md — 脆弱性の報告
• ライブドキュメント — docs/
• イシュー — バグ、機能、質問

ライセンス

MIT