sugo

Sugo

ドキュメントを、ぎゅっと凝縮。 LLM に水ではなく、うまみを与えましょう。

クイックスタート · できること · 比較 · MCP · ロードマップ · 🇮🇹 イタリア語

---

🔒 100% ローカル クラウドなし、テレメトリーなし

✂️ トークンを削減 繰り返しヘッダーがある場合は33～38%、実際の法律文書では約3%

🧾 知らないうちに失われるものはありません 削除した内容はすべて記録されます

🪶 軽量 GPU なしで8 GB RAMで動作

Sugo は、PDF、Office ファイル、スクリーンショット、画像を、RAG システム、AI エージェント、LLM チャット向けの、整然としたコンパクトな Markdown に変換します。トークンを消費するだけの要素（繰り返されるヘッダーやフッター、ページ番号、隠しテキスト、トラッキングパラメーター、スクリーンショット周囲のアプリ画面要素）を取り除き、内容、表、構造は保持します。すべての処理はお使いのコンピューター上で実行されます。クラウド API もテレメトリーもなく、データが外部に送信されることもありません。

イタリア語の il sugo del discorso は「要点」を意味し、sugo は、うまみだけが残るまで煮詰めるソースのことです。Sugo はドキュメントに対して、まさにそれを行います。

できること

生成した3ページの小さな PDF を、プレーンテキスト抽出ツールがモデルに渡す場合の内容です（1ページ目と3ページ目は同じです）。

ACME S.p.A. - Annual Report 2025                Confidential
3.2 Revenue
Revenue grew by 12% in the second half, driven by the export market.
Details: https://acme.example/report?utm_source=newsletter&utm_medium=email
Page 14 of 120

sudo report.pdf の出力：

ACME S.p.A. - Annual Report 2025

# 3.1 Costs

Costs fell by 3% thanks to the new suppliers.
Details: https://acme.example/report

# 3.2 Revenue

Revenue grew by 12% in the second half, driven by the export market.
Details: https://acme.example/report

# 3.3 Outlook

The board expects stable growth next year.
Details: https://acme.example/report

ヘッダーは各ページではなく1回だけ残ります。ページ番号、繰り返しの「Confidential」、トラッキングパラメーターは削除されます。テキストは変わりません。sugo stats で差を測定できます。この小さな生成例では、180 → 97トークン、46%削減です。ページ上の装飾要素が少ない実際のドキュメントでは、削減量はもっと小さくなります（下記参照）。削除内容はすべて、実行したクリーナーと理由とともに記録されるため、何が削除されたかをいつでも確認できます。読み取れないテキストは推測せず、判読不能として記録されます。

5言語のベンチマークコーパスでは、どのドキュメントでもテキストの欠落はありませんでした（3つのスクリーンショットでは OCR が一部の文字を誤読し、誤りは1～7%でした）。削減量はドキュメントによって大きく異なります。

ドキュメント	削減されたトークン数
ヘッダー、フッター、ページ番号が繰り返されるレポート	33～38%
チャットまたはコードのスクリーンショット。画像そのものを送信する場合と比べた Markdown	94～98%のコスト削減（Claude、Gemini、OpenAI）
EUR-Lex の実際の EU 規則。実質的な法律文書が大半	2.9～3.5%

新しいコンピューターに限らず、一般的なコンピューターでも高速です。2コアで GPU のない2010年製デスクトップでは、100ページの PDF を3.6秒、スマートフォンのスクリーンショットを13.7秒で変換します（詳しい数値はTESTINGをご覧ください）。

比較

よく知られた2つの代替ツールと、同じ31件のドキュメントからなるベンチマークコーパス（Sugo プロジェクトが作成した合成ドキュメント26件と、実際の EU 規制 PDF 5件）を、同じトークナイザーと同じ正解データで比較しました。手法の全容、数値の詳細、制限については、docs/comparisonsをご覧ください。

	Sugo	Docling	MarkItDown
内容の欠落や文字化けなしで変換できたドキュメント	28 / 31	25 / 31	14 / 31
チャット／コードのスクリーンショットに対する OCR	✅ テキストの欠落なし。アクセント記号付きの3枚のスクリーンショットで、文字エラーは1～7％	⚠️ 単語は正しいものの、一部のチャットで順序が誤っている	❌ 出力なし
PDFをそのまま読み込み	✅	✅	❌ 追加のものが必要
実際の EU 規制 PDFで、すべての条項を保持	✅	⚠️ 5件中2件で条項が欠落	❌ どのファイルでも2～7項目が欠落

内容を落とすツールは、見かけ上トークン数も「節約」しますが、それは圧縮ではなくデータ損失です。上記の数値はすべて、変換後に実際に保持された内容とあわせて示しています。

妥当な留意点：コーパスは小規模で、大半が合成データです。また、Sugo の作者が作成したものなので、決定的な評価ではなく、妥当性を確かめるための指標としてご覧ください。レポート PDF では、Docling は内容を損なわず、Sugo よりわずかに多くのトークンを削減します（約38～48％に対し、33～38％）。また、このコーパスでは処理速度が数倍遅くなります。生データとドキュメント別の詳細な表は、リンク先の比較資料をご覧ください。

ステータス

メモ

v0.1.1 をリリースしました。PyPIで sugo-cli として公開されています（v0.1.0 は初の署名付きリリースでした）。まだ0.xのため、1.0以前に、告知のうえで仕様が変更される場合があります。リリースは、SBOM、Sigstore アテステーション、PyPI Trusted Publishing を使用して再現可能な方法でビルドされています。

現在利用可能	今後の予定
ネイティブ PDF、DOCX、XLSX、PPTX、XML	スキャン書籍のクリーナー、EPUB、メール、ウェブページ
ローカル OCR による画像とスクリーンショット（PNG、JPEG、WEBP）	より大きな表、normal と quality のエンジンレベル
チャットとコードのスクリーンショット検出	日本語、中国語、韓国語
ベクターデータベース向けの Markdown と JSON Lines チャンク	対話型シェル、ガイド付きセットアップ
プロバイダー別のトークン指標（sugo stats）	バックグラウンドサービスとフォルダー監視
コマンドライン、エージェント向け MCP サーバー、ローカルウェブページ	作業プロファイルとレシピ
英語、イタリア語、スペイン語、フランス語、ドイツ語のインターフェースとテキストルール

計画の全容はロードマップをご覧ください。

クイックスタート

Sugo には Python 3.12、3.13、または3.14が必要です。PDF ライブラリ、OCR エンジン、そのモデルが同梱されているため、インストールにはディスク上で約400 MB必要です。最も簡単なインストール方法はuvを使うことです。

uv tool install sugo-cli

または pip を使います。

pip install sugo-cli

pip でインストールした後に sugo が「認識されない」または「見つからない」と表示される場合、pip がシステムの検索対象外のフォルダーにインストールした可能性があります。Windows で pip がユーザー用にのみインストールする場合（「Defaulting to user installation」）に発生します。uv tool install sugo-cli でインストールして uv tool update-shell を一度実行するか、pip の警告に表示されたフォルダー（Windows では %APPDATA%\Python\Python3XX\Scripts）を Path に追加してから、新しいターミナルを開いてください。

ヒント

PyPI の sugo という名前は、無関係な空のプロジェクトが使用しているため、このパッケージ名は sugo-cli です（名前の移管申請中です）。インストール後のコマンドは引き続き sugo です。sugo-cli も使えます。sugo-cli[lite] を使う古い手順も引き続き機能します。現在はすべてがデフォルトで含まれています。

代わりに、ソースから最新の開発バージョンを実行するには、次のようにします。

uv tool install git+https://github.com/Muralnick/sugo

ファイルを変換して、Markdown を出力します。

sugo report.pdf

その他にできること：

sugo convert *.pdf -o out/            # one NAME.md per file, in out/
sugo convert report.pdf --chunks      # chunks as JSON Lines, ready for RAG
sugo stats screenshot.png             # tokens saved, per LLM provider
sugo clip                             # convert the screenshot in your clipboard
sugo ui                               # open the local web page: drop a file, get Markdown
sugo doctor                           # check the installation

スクリプトで読み取れる出力にするには、--json を追加します。

AI エージェントから使う（MCP）

Sugo は MCP 経由で、Claude Code や Codex などのエージェントに機能を提供できます。指定したフォルダー内のみを読み込みます。

claude mcp add sugo -- sugo mcp --root ~/Documents

エージェントは2つのツール、convert_document と estimate_savings を利用できます。

アンインストール

インストールした方法と同じ方法でプログラムを削除します。

uv tool uninstall sugo-cli

または、pip を使った場合：

pip uninstall sugo-cli

エージェントに Sugo を追加した場合は、そこからも削除してください。たとえば、claude mcp remove sugo を実行します。

プログラムをアンインストールしても、Sugo が作成したファイルは削除されません。ファイルはお使いのコンピューターにのみ保存されているため、手動で削除できます。

項目	Windows	macOS	Linux
設定（config.toml）	%LOCALAPPDATA%\sugo	~/Library/Application Support/sugo	~/.config/sugo
キャッシュ（変換したドキュメントのテキスト）	%LOCALAPPDATA%\sugo\Cache	~/Library/Caches/sugo	~/.cache/sugo

SUGO_CACHE_DIR を設定している場合、キャッシュは代わりにそのフォルダーに保存されます。キャッシュには変換したドキュメントのテキストが含まれるため、それらのドキュメントが非公開のものだった場合は削除してください。この2つのフォルダーと、書き込むよう指定したファイル（-o の出力や受領証など）を除き、Sugo がディスク上にほかのものを保存することはありません。

古いコンピューターでの動作

2026-11-03 に、2010年製のデスクトップで測定しました。Intel Core i5-650（2コア、4スレッド、AVX 非対応）、RAM 8 GB、SSD、使用可能な GPU なし。Sugo が対象とする RAM 8 GB、4コアのマシンより低い性能です。

タスク	結果	目標
ネイティブ PDF、100ページ、クリーニング込み	3.6 秒、約28ページ/秒	≥ 20ページ/秒
その PDF のピークメモリ使用量	98 MB	< 1 GB
高密度なスマートフォンのスクリーンショット（30行）→テキスト、OCR	30行中30行、文字誤り率0％、411 MB	< 1 GB
同じスクリーンショットの処理時間	13.7 秒	< 2 秒

ネイティブのドキュメントは、このマシンでも目標を十分に満たして動作します。OCR は正確ですが、AVX 非対応の CPU では時間がかかります。高速化は今後のロードマップに含まれています。詳細とスクリプトについては、TESTING をご覧ください。

サポートされているファイル

種類	形式	サイズ上限
ドキュメント	PDF（テキストレイヤー付き）、DOCX、XLSX、PPTX	200 MB
画像	PNG、JPEG、WEBP（スクリーンショット、文字の写真）	50 MB
データ	XML	50 MB

古い .doc、.xls、.ppt ファイルとパスワード保護されたファイルは読み込めません。先に新しいコピーとして保存してください。

仕組み

flowchart LR
    F[Your file] --> E[Reader<br/>PDF · Office · OCR · XML]
    E --> IR[Document → Page → Block]
    IR --> C[Cleaners<br/>propose removals]
    C --> K[Core<br/>applies and records them]
    K --> M[Markdown]
    K --> J[JSONL chunks]
    K --> S[Token metrics]

各リーダーは、ファイルをページとブロックからなる共通の構造に変換します。クリーナーは変更を「提案」するだけで、コアが変更を適用し、削除する代わりに、削除した各ブロックに削除したものと理由を記録します。これにより、出力を検証可能かつ再現可能にできます。設計の詳細については、ARCHITECTURE をご覧ください。

保証事項

これらは PRINCIPLES に明記され、テストで確認されています。

• 原則としてローカルで処理します。 変換にインターネット接続は必要ありません。クラウド API もテレメトリーもありません。
• 推測しません。 読み取れないテキストは判読不能として示し、決して補完しません。
• 何も気づかれないまま失われることはありません。 削除のたびに、その理由を記録します。
• 指標を正直に示します。 削減量を測定し、元の画像を送信したほうがコストが低い場合も Sugo が伝えます。
• 信頼できないファイルにも安全です。 サイズと時間に上限を設け、XML を安全に解析し、チェックサムでモデルを検証します。脅威モデルをご覧ください。

ドキュメント

ドキュメント	内容
ARCHITECTURE	システム設計の全容
FEATURES	エンジンレベルごとの機能、作業プロファイル、対応フォーマット
THREAT_MODEL	セキュリティ分析
TESTING	テスト、ベンチマーク、パフォーマンス目標
ROADMAP	開発計画と初回リリースの範囲
ADRs	アーキテクチャ決定記録
PRINCIPLES	Sugo が決して破らない約束
AI_WORKFLOW	AI の支援を受けてこのプロジェクトを構築する方法

コントリビューションとセキュリティ

CONTRIBUTING をご覧ください。脆弱性は公開イシューではなく、SECURITY に記載されている方法で非公開で報告してください。

ライセンス

AGPL-3.0-or-later（ADR-010 を参照）。