refigure

Conversores donde las figuras sobreviven.

DOCX/XLSX → Markdown que mantiene los gráficos y las infografías legibles por máquina en lugar de perderlos ante un OCR o un modelo de visión: los datos nativos de gráficos OOXML (numCache/strCache) recuperan números exactos con cero llamadas a GPU, cero llamadas a VLM, cero pérdida de precisión, por defecto y no como respaldo.

Esa ruta por defecto es también la razón por la que la instalación base (pip install "refigure[docx,xlsx]") es ~500 veces más ligera que las alternativas basadas en PyTorch (5,6 MB frente a varios GB): la conversión principal no necesita ningún modelo de ML. Esa cifra se refiere a la arquitectura principal, no a todos los formatos de distribución: la imagen Docker lo intercambia deliberadamente, agrupando proveedores VLM + LibreOffice para una ruta llave en mano de figuras compuestas (ver Docker más abajo).

La interpretación VLM en sí está ahí para la rara figura sin ningún dato nativo (una captura de pantalla de un panel) — nunca se requiere solo para obtener números reales de un gráfico, en ningún formato de distribución.

Se distribuye como biblioteca, CLI, servidor MCP y paquete de Claude Desktop con un solo clic — cada interfaz devuelve la misma salida con fidelidad nativa, no un resumen degradado para agentes.

Características

• Extracción nativa de datos de gráficos — lee los numCache/strCache OOXML directamente; sin paso de rasterización/OCR/VLM para los gráficos, siempre números reales.

• Marcadores posicionados sin pérdida para figuras compuestas (DOCX) — las formas/infografías agrupadas que mammoth, de otro modo, fragmentaría silenciosamente en piezas desconectadas reciben en su lugar un marcador limpio, con la posición y cualquier texto de leyenda conservados. Ausente incluso en competidores bien financiados — ver Docling issue #1287.

• Interpretación VLM opcional (figuras compuestas DOCX, extra [vlm], --vlm/Config(use_vlm=True)) — descripción en la nube + un diagrama mermaid real renderizado (26 tipos de diagrama compatibles — diagramas de flujo, gráficos circulares/de xy, diagramas de secuencia/estado/ER, Gantt/línea temporal/sankey/treemap y más, ver Estado más abajo) sobre la base sin pérdida, para figuras sin ningún dato de gráfico nativo (p. ej. una captura de pantalla de un panel). Agnóstico respecto al proveedor — OpenRouter por defecto, u OpenAI/Ollama/vLLM/LM Studio/Anthropic directos mediante --vlm-provider (extra [vlm-direct]). --strict eleva un fallo concreto (la ausencia del binario soffice/LibreOffice del sistema) de una omisión elegante a un error grave; cualquier otro fallo VLM sigue degradándose.

• Resultado enriquecido y tipado — ConversionResult (markdown + advertencias + recuentos de gráficos/grupos + vlm_used), no una cadena simple.

• CLI incluida — comando de consola refigure, orientado a stdin/stdout, modo por lotes nativo, códigos de salida tipados (ver más abajo).

• Servidor MCP incluido — comando de consola refigure-mcp (extra [mcp]), stdio o Streamable HTTP, herramientas/recursos/indicaciones, conversión por lotes con aislamiento por archivo (ver más abajo).

• Imagen Docker — ghcr.io/helgdemidov/refigure, ambos comandos de consola en PATH, soffice/LibreOffice integrados — la ruta de figuras compuestas VLM funciona llave en mano, sin instalación manual de LibreOffice. Multiarquitectura — linux/amd64 + linux/arm64, Apple Silicon nativo (ver más abajo).

• Paquete .mcpb para Claude Desktop — instalación con un clic, sin terminal (solo docx+xlsx, ver más abajo).

Related MCP server: x2md

Demostración

Interpretación VLM opcional — para una figura sin ningún dato de gráfico nativo (una captura de pantalla, no una parte de gráfico OOXML) Y tampoco ninguna construcción mermaid equivalente (un sunburst radial denso — nada en los 4 tipos mermaid originales podía representarlo), --vlm recupera el contenido real y produce un diagrama genuinamente renderizable, no solo texto recuperado:

Extracción nativa de datos de gráficos — OOXML numCache real, no una captura de pantalla, no OCR:

La misma extracción, desde DOCX — Word también incrusta gráficos nativos, no solo Excel; refigure lee los mismos datos OOXML en caché en ambos casos:

Figuras compuestas — posicionadas, sin pérdida, incluso cuando la figura en sí no se puede renderizar (ningún competidor hace esto — ver Docling issue #1287, abierta desde hace más de 1 año):

Inicio rápido

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")

O sin una instalación permanente, mediante uv/uvx:

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

Interpretación VLM opcional, para una figura compuesta que el motor de gráficos no puede reconstruir por sí solo (ver Características arriba):

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

Instalación y uso

Un conversor, cuatro formas de ejecutarlo — elige la que mejor se adapte a tu flujo de trabajo. Haz clic en un encabezado para expandirlo.

refigure instala un comando de consola — un envoltorio fino sobre el mismo convert() usado programáticamente, sin lógica separada:

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

El modo por lotes (2 o más fuentes, o un único directorio) requiere -o DIR, sigue adelante tras una fuente fallida por defecto (--fail-fast aborta con la primera en su lugar) y siempre imprime un resumen (N/M converted, K failed) en stderr. --json emite el resultado completo — markdown más recuentos de gráficos/grupos y advertencias — en lugar de markdown plano. -v/-q controlan la verbosidad; --strict se reenvía al mismo Config.strict que usa la API de Python.

Códigos de salida:

refigure-mcp — los mismos conversores como servidor MCP, para agentes/IDEs que hablan el protocolo directamente en lugar de invocar una CLI o importar la biblioteca. Listado en el MCP Registry oficial como io.github.HelgDemidov/refigure:

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

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

O apunta el cliente a uvx en su lugar, sin ninguna instalación permanente:

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

refigure[full] es un atajo de refigure[mcp,docx,xlsx,vlm-direct] — todas las herramientas, ambos formatos, todos los proveedores VLM, una sola cadena de extras.

Tres herramientas — convert_docx, convert_xlsx y convert_batch (varios archivos en una sola llamada: un archivo con errores informa de su propio error sin abortar el resto) — cada una se registra solo si su extra de formato está realmente instalado. use_vlm/--vlm-provider y compañía funcionan igual que en la CLI. Un resultado demasiado grande para incrustarlo se almacena y se devuelve como un recurso refigure://conversion/{id} en lugar de inflar la respuesta de la herramienta. Dos indicaciones (ingest_for_rag, explain_conversion_warnings) ayudan al cliente a elegir la herramienta/los ajustes VLM adecuados para el trabajo.

Streamable HTTP es opcional, para un despliegue compartido/remoto — la autenticación con token Bearer es obligatoria, no opcional:

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

La limitación de frecuencia por llamador (protege el gasto del operador frente a un token filtrado/descontrolado) se aplica automáticamente a través de HTTP, junto con un tope flexible de equidad una vez que hay 2 o más llamadores configurados; refigure-mcp --help cubre todas las opciones de ajuste (concurrencia, tiempos de espera, límites del almacén de recursos, tamaño de lote, techo VLM).

Una imagen, ambas superficies — refigure y refigure-mcp ya están en PATH, sin compilaciones CLI/MCP separadas entre las que elegir. Lo único que este formato aporta sobre pip/uvx y que ninguno de ellos puede: el binario soffice/LibreOffice del sistema que la ruta de figuras compuestas VLM necesita viene integrado, no como instalación manual. Manifiesto multiarquitectura (linux/amd64 + linux/arm64) — docker pull resuelve la capa correcta automáticamente, incluso en Apple Silicon.

docker pull ghcr.io/helgdemidov/refigure:latest

Fija una versión exacta en lugar de :latest para la reproducibilidad — p. ej. :0.3.4 — consulta la página del paquete para ver las etiquetas disponibles.

La pestaña OS/Arch de la página del paquete lista unknown/unknown junto a las entradas reales linux/amd64/linux/arm64 — eso es una atestación de procedencia de compilación/SBOM (metadatos in-toto + SPDX que esta imagen publica para cada plataforma), no una imagen rota o no fiable. La propia interfaz de GHCR no etiqueta los manifiestos de atestación, una limitación conocida y ampliamente reportada de la vista de paquetes del registro, no relacionada con este proyecto.

CLI, mediante un bind mount (el directorio de trabajo de la imagen ya es /data):

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

MCP, stdio — el cliente lanza el contenedor por sí mismo:

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

MCP, Streamable HTTP — --mcp-http-host 0.0.0.0 es obligatorio aquí, no opcional: el enlace por defecto 127.0.0.1 es inalcanzable a través de la publicación de puertos -p (el NAT de Docker alcanza la interfaz de red externa del contenedor, no su loopback), por lo que la invocación «obvia» sin esta opción nunca respondería en silencio:

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

La instalación más sencilla para un usuario no técnico: descargar, hacer doble clic, listo — sin terminal, sin pip/uvx/docker. Cubre únicamente la conversión de docx+xlsx (sin VLM — eso requiere el extra [vlm], deliberadamente no incluido en este paquete); las dependencias se resuelven directamente desde PyPI mediante uv en el primer inicio, el mismo mecanismo que uvx usa internamente, solo que con un clic en lugar de un fragmento de configuración.

Descargar refigure.mcpb — ábrelo con Claude Desktop para instalarlo.

Ejemplos reales

Extractos concentrados (≤200 líneas cada uno) de la salida real de convert() sobre documentos reales con licencia abierta: el markdown real que una canalización ingeriría, no una captura de pantalla ni una frase suelta escogida a dedo. El encabezado de cada archivo indica su fuente, licencia y atribución; las secciones recortadas se marcan en línea, nunca se inventan para rellenar espacio.

Abre cualquiera de estos en GitHub y ambas vistas están ahí mismo: el delimitador ```mermaid sin procesar que una canalización LLM/RAG leería, y su renderizado nativo de GitHub — sin pasos adicionales, es el propio soporte de Markdown de GitHub.

Estado

• Validado contra 27 documentos reales (15 DOCX + 12 XLSX): 407 gráficos nativos encontrados (400 renderizados), 35 figuras compuestas recuperadas como marcadores posicionados sin pérdida. Procedencia completa: tests/integration/fixtures/manifest.yaml.

• Probado: la CI exige un mínimo de cobertura combinada de unitarias + integración del 95 %.

• Publicado como v0.3.4: PyPI (publicación de confianza, sin tokens almacenados), GHCR y el Registro oficial de MCP como io.github.HelgDemidov/refigure. refigure-md es un nombre alternativo reservado, no una versión activa.

Extraído de una canalización de análisis de documentos en funcionamiento (un corpus gubernamental de investigación sobre políticas de IA), no construido desde cero para esta versión.

La interpretación VLM de figuras compuestas que el motor de gráficos no puede reconstruir está completamente implementada y probada, no es un stub — extra [vlm], independiente del proveedor (acceso directo a OpenAI/Anthropic vía [vlm-direct]), y también requiere el binario del sistema soffice/LibreOffice.

El reconocimiento de diagramas Mermaid depende del tipo de diagrama y de lo que la figura de origen contiene en realidad:

• Los tipos comunes (diagramas de flujo, gráficos circulares/XY) se detectan de forma fiable.

• Los más especializados necesitan una señal visual inequívoca en la figura de origen.

• No toda figura produce un diagrama — una descripción en texto plano es un respaldo honesto, no un fallo.

PDF está fuera del alcance, a propósito: un límite, no un vacío. PDF no tiene equivalente de los datos de gráfico en caché de OOXML (numCache/strCache) para ningún generador de gráficos habitual, por lo que la extracción nativa, sin rasterizar, sobre la que se basa este proyecto no se traslada a PDF; así lo confirma la investigación sobre la propia estructura de PDF y sobre cómo los principales conversores de PDF manejan hoy los gráficos, no una suposición.

Para corpus de formato mixto, enruta por extensión en lugar de esperar que una sola herramienta lo cubra todo:

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

Usa Docling o MarkItDown para PDF, y refigure para DOCX/XLSX, donde los datos de los gráficos realmente se conservan en el archivo.

Licencia

Apache-2.0 — consulta LICENSE y NOTICE.