Lleva tus documentos a pipelines de IA — directamente desde Python, on‑premise, con un solo pip install.

Hoy lanzamos la primera versión pública de GroupDocs.Markdown para Python vía .NET en PyPI. La biblioteca convierte PDF, Word, Excel, EPUB y más de 20 formatos adicionales a Markdown limpio y semántico — el formato con el que LLMs, pipelines RAG y generadores de sitios estáticos trabajan mejor.

Si has estado siguiendo el lanzamiento .NET de septiembre (o la revisión completa de la API en la 26.3), la razón es la misma: el formato del documento lleva semántica, y preservar esa estructura semántica es lo que permite a un sistema RAG dar buenas respuestas. La publicación anterior cubre el problema (OCR aplana la estructura, los LLMs necesitan markdown) y la solución (un renderizador basado en DOM que recorre el documento y genera Markdown) en profundidad — no repetiremos esa historia aquí.

En su lugar, centrémonos en lo nuevo para los desarrolladores de Python.

Qué obtienes

  • Una única rueda, sin dependencias en tiempo de ejecución. pip install groupdocs-markdown-net descarga una rueda autocontenida que incluye el runtime de .NET y todas las bibliotecas nativas que necesita. No hay instalación de dotnet, ni Microsoft Office, ni Adobe Acrobat, ni servicios en la nube.
  • Multiplataforma. Windows x64/x86, Linux x64, macOS x64 y Apple Silicon (ARM64). Python 3.5 a 3.14.
  • Una API pythonica. Las clases usan PascalCase, los métodos y propiedades usan snake_case, los valores de enumeración usan UPPER_SNAKE_CASE. Los administradores de contexto liberan los documentos cargados de forma determinista.
  • Verdaderamente async. Cada método estático e de instancia tiene una contraparte _async. La E/S de archivos es asíncrona y la conversión intensiva en CPU se ejecuta en un hilo de trabajo — tu bucle de eventos asyncio permanece libre.
  • Amigable para agentes de IA. La rueda instalada incluye un archivo AGENTS.md para que los asistentes de codificación (Claude Code, Cursor, GitHub Copilot, Codex) descubran automáticamente la superficie de la API, los patrones de uso idiomáticos y los consejos de solución de problemas. La documentación también se publica como llms.txt, un corpus de un solo archivo (llms-full.txt), Markdown por página y un servidor MCP — consulta la sección Amigable con IA por diseño para más detalles.

Comenzar

pip install groupdocs-markdown-net

La conversión más simple es una sola línea:

from groupdocs.markdown import MarkdownConverter

# Convertir a una cadena
md = MarkdownConverter.to_markdown("business-plan.docx")

# O escribir directamente a un archivo
MarkdownConverter.to_file("business-plan.docx", "business-plan.md")

Eso es todo — sin configuración, sin opciones, sin código boilerplate. El modo de evaluación procesa las primeras 3 páginas y añade una marca de agua. Para eliminar los límites, aplica una licencia:

from groupdocs.markdown import License

License().set_license("path/to/license.lic")

O establece GROUPDOCS_LIC_PATH como variable de entorno y se aplicará automáticamente al importar.

Formatos compatibles

El paquete Python maneja la misma amplitud de formatos que la biblioteca .NET:

  • PDF — .pdf
  • Word / Rich Text — .doc, .docx, .docm, .dot, .dotx, .dotm, .rtf, .odt, .ott
  • Hojas de cálculo — .xls, .xlsx, .xlsb, .xlsm, .csv, .tsv, .ods, .ots
  • eBooks — .epub, .mobi
  • Texto / Marcado / Ayuda — .txt, .xml, .chm

Ejemplos pythonicos

Opciones de conversión y estrategias de imágenes

from groupdocs.markdown import (
    MarkdownConverter,
    ConvertOptions,
    MarkdownFlavor,
    ExportImagesToFileSystemStrategy,
)

strategy = ExportImagesToFileSystemStrategy("output/images")
strategy.images_relative_path = "images"  # ![](images/img-001.png)

options = ConvertOptions()
options.flavor = MarkdownFlavor.GIT_HUB
options.heading_level_offset = 1      # # Title -> ## Title
options.include_front_matter = True    # prepend YAML metadata
options.image_export_strategy = strategy

MarkdownConverter.to_file("report.docx", "output/report.md", convert_options=options)

Inspección de documento sin conversión

from groupdocs.markdown import MarkdownConverter

info = MarkdownConverter.get_info("business-plan.docx")
print(f"{info.file_format}, {info.page_count} pages, author: {info.author}")

Cargando un archivo protegido con contraseña

from groupdocs.markdown import MarkdownConverter, LoadOptions, FileFormat

load_opts = LoadOptions(FileFormat.DOCX)
load_opts.password = "secret"

MarkdownConverter.to_file("protected.docx", "output.md", load_options=load_opts)

Streams y administradores de contexto

from groupdocs.markdown import MarkdownConverter

with open("document.docx", "rb") as stream:
    with MarkdownConverter(stream) as converter:
        converter.convert("document.md")

API async — convirtiendo muchos documentos concurrentemente

Como la E/S de archivos es asíncrona, asyncio.gather() permite que un solo trabajador procese muchos documentos sin bloquear:

import asyncio
from groupdocs.markdown import MarkdownConverter

async def convert_many():
    await asyncio.gather(
        MarkdownConverter.to_file_async("a.docx", "a.md", None),
        MarkdownConverter.to_file_async("b.pdf",  "b.md", None),
        MarkdownConverter.to_file_async("c.xlsx", "c.md", None),
    )

asyncio.run(convert_many())

Esto hace que la biblioteca encaje de forma natural en frameworks ASGI como FastAPI — un solo trabajador puede atender muchas solicitudes de conversión concurrentes sin contención de hilos.

Manejo de errores

Todos los métodos de conversión lanzan excepciones en caso de fallo, con tipos específicos para escenarios comunes:

from groupdocs.markdown import (
    MarkdownConverter,
    DocumentProtectedException,
    InvalidFormatException,
    GroupDocsMarkdownException,
)

try:
    MarkdownConverter.to_file("annual-report.docx", "annual-report.md")
except DocumentProtectedException:
    print("Wrong or missing password.")
except InvalidFormatException:
    print("File is corrupt or unsupported.")
except GroupDocsMarkdownException as ex:
    print(f"Conversion failed: {ex}")

Construido para pipelines RAG y LLM

Markdown es el formato de entrada preferido para modelos de incrustación y pipelines de recuperación — preserva encabezados, listas, tablas y énfasis mientras es fácil de dividir y tokenizar. Una ingestión RAG típica se ve así:

import re
from groupdocs.markdown import MarkdownConverter, ConvertOptions, SkipImagesStrategy, MarkdownFlavor

options = ConvertOptions()
options.image_export_strategy = SkipImagesStrategy()   # solo texto para RAG
options.flavor = MarkdownFlavor.COMMON_MARK

MarkdownConverter.to_file("business-plan.pdf", "business-plan.md", convert_options=options)

with open("business-plan.md", "r", encoding="utf-8") as f:
    markdown = f.read()

# Dividir por encabezados de nivel superior, luego incrustar/indexar cada fragmento
chunks = [c for c in re.split(r"\n#{1,2} ", markdown) if c.strip()]

Como la biblioteca se ejecuta completamente on‑premise, los documentos sensibles nunca abandonan tu entorno — un requisito común en industrias reguladas, equipos legales y bases de conocimiento internas.

Amigable con IA por diseño

La mayoría de los SDK de Python tratan a los asistentes de codificación de IA como una idea posterior — el desarrollador aún debe apuntar al agente a la documentación, pegar ejemplos o depurar mediante prueba y error. GroupDocs.Markdown para Python vía .NET invierte eso: la biblioteca está diseñada para que agentes como Claude Code, Cursor, GitHub Copilot y Codex la adopten sin configuración manual.

AGENTS.md se incluye dentro del wheel

Este es el primer paquete GroupDocs que incluye un archivo AGENTS.md directamente dentro del wheel instalado. El archivo sigue la emergente convención AGENTS.md — un README en Markdown plano escrito específicamente para asistentes de codificación de IA en lugar de humanos.

Al ejecutar pip install groupdocs-markdown-net, el archivo queda en:

site-packages/groupdocs/markdown/AGENTS.md

Un asistente de IA que abra tu proyecto puede leerlo y aprender de inmediato:

  • La superficie completa de la API pública (clases, métodos, enums, excepciones) y sus relaciones.
  • Patrones de uso idiomáticos para los escenarios más comunes — API estática vs instancia, sync vs async, estrategias de imágenes, front matter, manejo de errores.
  • Trampas comunes y cómo evitarlas — por ejemplo, qué sobrecargas de ConvertOptions aceptan None, cómo manejar archivos protegidos con contraseña, cómo capturar advertencias de conversión.
  • Solución de problemas para cuestiones específicas de plataforma (libSkiaSharp en macOS, ICU en Linux).

En la práctica, esto significa que puedes decir “usa groupdocs-markdown-net para convertir esta carpeta de PDFs a Markdown para mi pipeline RAG” y el agente escribe código funcional en el primer intento — sin nombres de método alucinados, sin orden de argumentos incorrecto, sin importaciones adivinadas.

Documentación legible por máquinas

Para los agentes que necesiten buscar algo que no esté en AGENTS.md, la documentación completa del producto también se publica en forma legible por máquinas:

  • Corpus de un solo archivo — la documentación completa como un único archivo Markdown, listo para colocar en la ventana de contexto de un agente:
    https://docs.groupdocs.com/markdown/python-net/llms-full.txt
  • Markdown por página — agrega .md a cualquier URL de docs para obtener el origen crudo:
    https://docs.groupdocs.com/markdown/python-net/quick-start-guide.md
  • Índice llms.txt — una tabla de contenidos estilo llms.txt que dirige a los agentes a las páginas que necesitan:
    https://docs.groupdocs.com/markdown/python-net/llms.txt

Servidor MCP para búsquedas de documentación en vivo

Para los agentes que hablen Model Context Protocol, exponemos la documentación como un servidor MCP. Añade esto a la configuración de tu Claude Code o Cursor:

{
  "mcpServers": {
    "groupdocs-docs": {
      "url": "https://docs.groupdocs.com/mcp"
    }
  }
}

Después, tu agente podrá consultar la documentación bajo demanda en lugar de depender de datos de entrenamiento que pueden estar desactualizados.

Markdown entra, Markdown sale

Hay una agradable simetría aquí: la salida de la biblioteca es Markdown — el formato que los LLMs procesan mejor para RAG — y su documentación también es Markdown, servida como un solo archivo para una fácil ingestión en la ventana de contexto. Ya sea que le pidas a un agente que escriba código que use la biblioteca, o que comprenda tus documentos mediante la biblioteca, Markdown es el medio común.

Ejemplo de exportación

Los fragmentos anteriores están cerca del programa útil más corto que puedes escribir con la biblioteca. Aquí tienes la misma idea empaquetada como un proyecto ejecutable — documento fuente, script Python, salida pre‑generada, requirements.txt y un Dockerfile — para que lo pruebes de extremo a extremo sin escribir nada desde cero.

DOCX de origen

El archivo fuente business-plan.docx es un breve plan de negocio rico en formato, con encabezados, tablas, imágenes y metadatos.

Script Python

from groupdocs.markdown import MarkdownConverter, ConvertOptions, MarkdownFlavor

def quick_example():
    """Convertir un documento Word a Markdown con sabor GitHub y front matter YAML."""

    # One-liner — devuelve una cadena Markdown
    md = MarkdownConverter.to_markdown("business-plan.docx")

    # Con opciones — escribe a un archivo
    options = ConvertOptions()
    options.flavor = MarkdownFlavor.GIT_HUB
    options.include_front_matter = True
    options.heading_level_offset = 1
    MarkdownConverter.to_file("business-plan.docx", "quick-example.md", convert_options=options)

if __name__ == "__main__":
    quick_example()

Markdown de salida

El archivo de salida quick-example.md comienza con un bloque de front‑matter YAML extraído automáticamente de los metadatos del documento, seguido del contenido convertido con tablas al estilo GitHub y una jerarquía de encabezados desplazada (listo para incrustarse dentro de un documento mayor).

Aplicación de ejemplo ejecutable

Todo empaquetado junto: sample-app.zip. Descomprime y luego:

cd src
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python quick_example.py

O ejecútalo en Docker — el Dockerfile incluido configura la dependencia ICU que necesita el runtime .NET empaquetado en Linux:

cd src
docker build -t groupdocs-markdown-python-example .
docker run --rm -v "$(pwd)/output:/app/output" groupdocs-markdown-python-example

Resumen

GroupDocs.Markdown para Python vía .NET lleva el motor completo de conversión documento‑a‑Markdown a Python como una rueda autocontenida — sin runtime externo, sin nube, sin sorpresas. Una API pythonica, soporte async y una integración de herramientas de IA de primera clase la convierten en una opción práctica para equipos Python que construyen sistemas RAG, generadores de sitios estáticos o pipelines de procesamiento de documentos.

Más información

Soporte y comentarios

Para preguntas o asistencia técnica, utiliza nuestro Free Support Forum — estaremos encantados de ayudar.