refigure

refigure

図表を損なわないコンバーター。

DOCX/XLSX → グラフやインフォグラフィックをOCRやビジョンモデルに頼らず、機械可読なまま保持するMarkdown。ネイティブのOOXMLグラフデータ（numCache/strCache）から正確な数値を復元します。GPU呼び出しもVLM呼び出しも不要で、精度も失われません。これはフォールバックではなく、デフォルトの動作です。

デフォルトの処理経路があるため、基本インストール（pip install "refigure[docx,xlsx]"）は、PyTorchベースの代替ツールより約500倍軽量です（5.6MB対数GB）。コアの変換にはMLモデルが一切必要ありません。ただし、この数値が示すのはコアアーキテクチャであり、すべての配布形式ではありません。Dockerイメージは意図的にその軽量さを犠牲にし、VLMプロバイダーとLibreOfficeをバンドルして、複合図表をすぐに処理できるようにしています（詳しくは下記のDockerを参照）。

VLMによる解釈は、ネイティブデータがまったくないまれな図表（ダッシュボードのスクリーンショットなど）に限って利用できます。どの配布形式でも、グラフから実際の数値を取得するためにVLMが必要になることはありません。

ライブラリ、CLI、MCP サーバー、ワンクリックで導入できるClaude Desktopバンドルとして提供されます。どの形態でも、エージェント向けに劣化した要約ではなく、ネイティブの忠実度を保った同じ出力を返します。

特長

• チャートデータのネイティブ抽出 — OOXML の numCache／strCache を直接読み取ります。チャートのラスタライズ／OCR／VLM 処理は不要で、常に実際の数値を取得します。
• 複合図版向けの位置情報付きゼロロスマーカー（DOCX） — 通常なら mammoth が何も通知せずに分断してしまうグループ化された図形やインフォグラフィックも、位置情報とキャプションテキストを保持した明確なマーカーに変換します。十分な資金を持つ既存製品にもない機能です。Docling issue #1287 をご覧ください。
• 任意の VLM による解釈（DOCX 複合図版、[vlm] エクストラ、--vlm／Config(use_vlm=True)） — ゼロロスの基盤に加えて、ネイティブのチャートデータがまったくない図版（例：ダッシュボードのスクリーンショット）を対象に、クラウドによる説明と実際に描画された mermaid 図を生成します（フローチャート、円グラフ／XY グラフ、シーケンス図／状態図／ER 図、ガントチャート／タイムライン／サンキーチャート／ツリーマップなど、26 種類の図に対応。詳細は「ステータス」をご覧ください）。プロバイダーを選ばず利用でき、デフォルトは OpenRouter です。また、--vlm-provider（[vlm-direct] エクストラ）を使って OpenAI／Ollama／vLLM／LM Studio／Anthropic に直接接続できます。--strict を指定すると、特定のエラー（システムの soffice／LibreOffice バイナリが見つからない場合）を、エラーを発生させずにスキップする代わりに、ハードエラーとして扱います。それ以外の VLM エラーは、引き続き機能を縮退させて処理します。
• 型付けされた豊富な結果 — 単なる文字列ではなく、ConversionResult（Markdown、警告、チャート／グループの件数、vlm_used）を返します。
• CLI を同梱 — refigure コンソールコマンドを利用できます。標準入力／標準出力を優先し、ネイティブのバッチモードと型付けされた終了コードに対応しています（詳細は後述）。
• MCP サーバーを同梱 — refigure-mcp コンソールコマンド（[mcp] エクストラ）を利用できます。stdio または Streamable HTTP、ツール／リソース／プロンプト、ファイルごとに処理を分離する一括変換に対応しています（詳細は後述）。
• Docker イメージ — ghcr.io/helgdemidov/refigure を提供しています。両方のコンソールコマンドを PATH から実行でき、soffice／LibreOffice を組み込み済みです。VLM による複合図版の処理も、そのまま利用でき、LibreOffice を手動でインストールする必要はありません。マルチアーキテクチャ対応で、linux/amd64 と linux/arm64 をサポートし、Apple Silicon でもネイティブに動作します（詳細は後述）。
• Claude Desktop 向け .mcpb バンドル — 端末を使わずにワンクリックでインストールできます（docx と xlsx のみ対応。詳細は後述）。

デモ

オプションの VLM 解釈 — ネイティブのチャートデータがまったくない（OOXML チャートパートではなくスクリーンショットである）うえに、対応する mermaid の構造もない図（a）（元の4種類の mermaid では表現できない高密度な放射状サンバースト図）の場合、--vlm は実際の内容を復元するだけでなく、復元されたテキストを出力するだけではなく、本当にレンダリング可能な図を生成します。

ネイティブのチャートデータ抽出 — スクリーンショットでも OCR でもなく、実際の OOXML numCache を使用します。

同じ抽出を DOCX からも実行 — Word にもネイティブのチャートが埋め込まれています。Excel だけではありません。refigure はどちらの形式でも同じキャッシュ済み OOXML データを読み取ります。

複合図 — 図自体をレンダリングできない場合でも、位置を保ったまま情報を一切失わずに処理します（これを行う既存ツールはありません。1年以上未解決のままのDocling issue #1287を参照してください）。

クイックスタート

pip install "refigure[docx,xlsx]"

refigure report.docx                      # markdown to stdout

from refigure.docx import convert

result = convert("report.docx")
print(result.markdown)
print(f"{result.charts_found} charts, {result.groups_found} composite figures")

または、恒久的にインストールせずに、uv/uvx を使う方法もあります。

uvx --from "refigure[docx,xlsx]" refigure report.docx

チャートエンジンだけでは再構成できない複合図向けのオプションの VLM 解釈については、「Features」を参照してください。

pip install "refigure[docx,vlm]"
export OPENROUTER_API_KEY=...                 # or --vlm-api-key-file/--vlm-provider
refigure report.docx --vlm                    # needs the system soffice/LibreOffice binary too

インストールと使い方

1つのコンバーターを4通りの方法で実行できます。パイプラインに合った方法を選んでください。 見出しをクリックすると展開します。

refigure report.docx                      # markdown to stdout
refigure report.docx -o report.md         # markdown to a file
cat report.docx | refigure --format docx  # stdin, format hint required
refigure reports/ -o out/                 # batch: directory, walked recursively
refigure a.docx b.xlsx -o out/            # batch: 2+ explicit sources

pip install "refigure[mcp,docx,xlsx]"
refigure-mcp                              # stdio — the MCP client launches it

{
  "mcpServers": {
    "refigure": { "command": "refigure-mcp" }
  }
}

{
  "mcpServers": {
    "refigure": {
      "command": "uvx",
      "args": ["--from", "refigure[mcp,docx,xlsx,vlm-direct]", "refigure-mcp"]
    }
  }
}

echo "sk-... = alice" > tokens.txt
refigure-mcp --transport http --mcp-auth-token-file tokens.txt

docker pull ghcr.io/helgdemidov/refigure:latest

docker run --rm -v "$PWD:/data:ro" ghcr.io/helgdemidov/refigure:latest \
  refigure /data/report.docx

{
  "mcpServers": {
    "refigure": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/helgdemidov/refigure:latest", "refigure-mcp"]
    }
  }
}

echo "sk-... = alice" > tokens.txt
docker run --rm -p 8000:8000 -v "$PWD/tokens.txt:/data/tokens.txt:ro" \
  ghcr.io/helgdemidov/refigure:latest \
  refigure-mcp --transport http --mcp-http-host 0.0.0.0 \
  --mcp-auth-token-file /data/tokens.txt

実際にオープンライセンスで公開されている文書を使った、実際の convert() 出力の抜粋（各200行以下）です。スクリーンショットでも、都合よく選んだ一行でもなく、パイプラインが取り込む実際の Markdown です。各ファイルのヘッダーに、出典、ライセンス、帰属表示を記載しています。省略した箇所にはインラインで印を付けており、内容を埋めるために捏造したものではありません。

GitHub でいずれかを開けば、元の ```mermaid fence an LLM/RAG pipeline would read, and its native GitHub rendering — no extra step, that's GitHub's own Markdown support.

Status

• Validated against 27 real documents (15 DOCX + 12 XLSX) — 407 native charts found (400 rendered), 35 composite figures recovered as positioned zero-loss markers. Full provenance: tests/integration/fixtures/manifest.yaml.
• Tested: CI gates on a combined unit+integration coverage floor of 95%.
• Published as v0.3.4 — PyPI (trusted publishing, no stored tokens), GHCR, and the official MCP Registry as io.github.HelgDemidov/refigure. refigure-md is a reserved alternate name, not an active release.

Extracted from a working document-analysis pipeline (a government AI-policy research corpus), not built from scratch for this release.

VLM interpretation of composite figures the chart engine can't reconstruct is fully implemented and tested, not a stub — [vlm] extra, provider-agnostic (direct OpenAI/Anthropic via [vlm-direct]), also needs the system soffice/LibreOffice binary.

Mermaid-diagram recognition depends on diagram type and on what the source figure actually contains:

• Common types (flowcharts, pie/xy charts) are picked reliably.
• More specialized ones need an unambiguous visual cue on the source figure.
• Not every figure produces a diagram — a plain-text description is an honest fallback, not a failure.

PDF is out of scope, on purpose — a boundary, not a gap. PDF has no equivalent of OOXML's cached chart data (numCache/strCache) for any mainstream chart generator, so the native, rasterize-free extraction this project is built on doesn't transfer to it — confirmed by research into PDF's own structure and how leading PDF converters handle charts today, not assumed. For mixed-format corpora, route by extension instead of expecting one tool to cover everything:

import refigure.docx
import refigure.xlsx

if path.suffix == ".pdf":
    markdown = docling_convert(path)      # or any PDF-capable converter
elif path.suffix == ".docx":
    markdown = refigure.docx.convert(path).markdown
else:
    markdown = refigure.xlsx.convert(path).markdown

Use Docling or MarkItDown for PDF, refigure for DOCX/XLSX where the chart data actually survives in the file.

License

Apache-2.0 — see LICENSE and NOTICE.