Traga seus documentos para pipelines de IA — diretamente do Python, on‑premise, com um único pip install.

Hoje estamos lançando a primeira versão pública do GroupDocs.Markdown para Python via .NET no PyPI. A biblioteca converte PDF, Word, Excel, EPUB e mais de 20 formatos em Markdown limpo e semântico — o formato que LLMs, pipelines RAG e geradores de sites estáticos utilizam da melhor forma.

Se você tem acompanhado o .NET release de setembro (ou a reformulação completa da API na 26.3), a lógica é a mesma: a formatação de documentos carrega semântica, e preservar essa estrutura semântica é o que faz um sistema RAG gerar boas respostas. O post anterior aborda o problema (OCR achata a estrutura, LLMs precisam de markdown) e a solução (um renderizador baseado em DOM que percorre o documento e gera Markdown) em detalhes — não vamos repetir essa história aqui.

Em vez disso, vamos focar no que há de novo para desenvolvedores Python.

What you get

  • Um único wheel, sem dependências de tempo de execução. pip install groupdocs-markdown-net baixa um wheel autocontido que inclui o runtime .NET e todas as bibliotecas nativas necessárias. Sem necessidade de instalar dotnet, sem Microsoft Office, sem Adobe Acrobat, sem serviços de nuvem.
  • Multiplataforma. Windows x64/x86, Linux x64, macOS x64 e Apple Silicon (ARM64). Python 3.5 até 3.14.
  • Uma API pythonic. Classes usam PascalCase, métodos e propriedades usam snake_case, valores de enum usam UPPER_SNAKE_CASE. Gerenciadores de contexto descartam documentos carregados de forma determinística.
  • Realmente async. Cada método estático e de instância tem um equivalente _async. I/O de arquivos é assíncrono e a conversão que consome CPU roda em uma thread de trabalho — seu loop de eventos asyncio permanece livre.
  • Amigável a agentes de IA. O wheel instalado inclui um arquivo AGENTS.md para que assistentes de codificação (Claude Code, Cursor, GitHub Copilot, Codex) descubram automaticamente a superfície da API, padrões de uso idiomáticos e dicas de solução de problemas. A documentação também é publicada como llms.txt, um corpus de arquivo único (llms-full.txt), Markdown por página e um servidor MCP — veja AI-friendly by design abaixo para detalhes.

Get started

pip install groupdocs-markdown-net

A conversão mais simples é uma única linha:

from groupdocs.markdown import MarkdownConverter

# Converte para uma string
md = MarkdownConverter.to_markdown("business-plan.docx")

# Ou grava diretamente em um arquivo
MarkdownConverter.to_file("business-plan.docx", "business-plan.md")

É isso — sem configuração, sem opções, sem boilerplate. O modo de avaliação processa as primeiras 3 páginas e adiciona uma marca d’água. Para remover os limites, aplique uma licença:

from groupdocs.markdown import License

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

Ou defina GROUPDOCS_LIC_PATH como variável de ambiente e ela será aplicada automaticamente na importação.

Supported formats

O pacote Python lida com a mesma variedade de formatos da biblioteca .NET:

  • PDF — .pdf
  • Word / Rich Text — .doc, .docx, .docm, .dot, .dotx, .dotm, .rtf, .odt, .ott
  • Planilhas — .xls, .xlsx, .xlsb, .xlsm, .csv, .tsv, .ods, .ots
  • eBooks — .epub, .mobi
  • Texto / Marcação / Ajuda — .txt, .xml, .chm

Pythonic examples

Conversion options and image strategies

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)

Inspeção de documento sem conversão

from groupdocs.markdown import MarkdownConverter

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

Carregando um arquivo protegido por senha

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 e gerenciadores de contexto

from groupdocs.markdown import MarkdownConverter

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

Async API — convertendo muitos documentos simultaneamente

Como I/O de arquivos é assíncrono, asyncio.gather() permite que um único worker processe vários documentos sem bloqueio:

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

Isso torna a biblioteca uma escolha natural para frameworks ASGI como FastAPI — um único worker pode atender a muitas requisições de conversão concorrentes sem contenção de threads.

Tratamento de erros

Todos os métodos de conversão lançam exceções em caso de falha, com tipos específicos para cenários comuns:

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

Built for RAG and LLM pipelines

Markdown é o formato de entrada preferido para modelos de embedding e pipelines de recuperação — ele preserva cabeçalhos, listas, tabelas e ênfase enquanto é fácil de dividir e tokenizar. Uma ingestão típica de RAG se parece com isto:

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

options = ConvertOptions()
options.image_export_strategy = SkipImagesStrategy()   # text-only for 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()

# Divide por cabeçalhos de nível superior, então embed/indexa cada fragmento
chunks = [c for c in re.split(r"\n#{1,2} ", markdown) if c.strip()]

Como a biblioteca funciona totalmente on‑premise, documentos sensíveis nunca deixam seu ambiente — um requisito comum em indústrias reguladas, equipes jurídicas e bases de conhecimento internas.

AI-friendly by design

A maioria dos SDKs Python trata assistentes de codificação de IA como um detalhe posterior — o desenvolvedor ainda precisa apontar o agente para a documentação, colar exemplos ou depurar por tentativa e erro. O GroupDocs.Markdown para Python via .NET inverte isso: a biblioteca foi projetada para que agentes como Claude Code, Cursor, GitHub Copilot e Codex a adotem sem nenhuma configuração manual.

AGENTS.md vem dentro do wheel

Este é o primeiro pacote GroupDocs a incluir um arquivo AGENTS.md diretamente dentro do wheel instalado. O arquivo segue a convenção emergente AGENTS.md convention — um README em Markdown puro escrito especificamente para assistentes de codificação de IA, não para humanos.

Ao executar pip install groupdocs-markdown-net, um arquivo é colocado em:

site-packages/groupdocs/markdown/AGENTS.md

Um assistente de IA que abre seu projeto pode lê‑lo e aprender imediatamente:

  • A superfície completa da API pública (classes, métodos, enums, exceções) e como eles se relacionam.
  • Padrões de uso idiomáticos para os cenários mais comuns — API estática vs. de instância, sync vs. async, estratégias de imagem, front matter, tratamento de erros.
  • Armadilhas comuns e como evitá‑las — por exemplo, quais sobrecargas de ConvertOptions aceitam None, como lidar com arquivos protegidos por senha, como capturar avisos de conversão.
  • Solução de problemas para questões específicas de plataforma (libSkiaSharp no macOS, ICU no Linux).

Na prática, isso significa que você pode dizer “use groupdocs-markdown-net para converter esta pasta de PDFs em Markdown para meu pipeline RAG” e o agente gera código funcional na primeira tentativa — sem nomes de método hallucinated, sem ordem de argumentos errada, sem importações adivinhadas.

Documentação legível por máquina

Para agentes que precisam consultar algo que não está em AGENTS.md, a documentação completa do produto também é publicada em formato legível por máquina:

  • Corpus de arquivo único — a documentação completa como um único arquivo Markdown, pronto para ser inserido no contexto de um agente:
    https://docs.groupdocs.com/markdown/python-net/llms-full.txt
  • Markdown por página — adicione .md a qualquer URL de docs para obter o fonte bruto:
    https://docs.groupdocs.com/markdown/python-net/quick-start-guide.md
  • Índice llms.txt — uma tabela de conteúdo no estilo llms.txt que aponta os agentes para as páginas necessárias:
    https://docs.groupdocs.com/markdown/python-net/llms.txt

Servidor MCP para consultas ao vivo

Para agentes que falam Model Context Protocol, expomos a documentação como um servidor MCP. Adicione isso à configuração do seu Claude Code ou Cursor:

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

Depois disso, seu agente pode consultar a documentação sob demanda em vez de depender de dados de treinamento que podem estar desatualizados.

Markdown como entrada e saída

Há uma simetria agradável aqui: a saída da biblioteca é Markdown — o formato que LLMs analisam melhor para RAG — e sua documentação também é Markdown, servida como um único arquivo para fácil ingestão no janela de contexto. Seja pedindo a um agente para escrever código que usa a biblioteca, ou pedindo a um agente para entender seus documentos via a biblioteca, Markdown é o meio comum.

Export Example

Os trechos acima são quase o programa útil mais curto que você pode escrever com a biblioteca. Aqui está a mesma ideia empacotada como um projeto executável — documento fonte, script Python, saída pré‑gerada, requirements.txt e um Dockerfile — para que você possa experimentar de ponta a ponta sem escrever nada do zero.

DOCX de origem

O arquivo de origem business-plan.docx é um plano de negócios curto e ricamente formatado, com cabeçalhos, tabelas, imagens e metadados.

Script Python

from groupdocs.markdown import MarkdownConverter, ConvertOptions, MarkdownFlavor

def quick_example():
    """Convert a Word document to Markdown with GitHub flavor and YAML front matter."""

    # One-liner — returns a Markdown string
    md = MarkdownConverter.to_markdown("business-plan.docx")

    # With options — writes to a file
    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 saída

A saída quick-example.md começa com um bloco de front‑matter YAML extraído automaticamente dos metadados do documento, seguido pelo conteúdo convertido com tabelas no estilo GitHub Flavored e hierarquia de cabeçalhos deslocada (pronta para ser incorporada em um documento maior).

Aplicativo de exemplo executável

Tudo agrupado: sample-app.zip. Descompacte, então:

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

Ou execute no Docker — o Dockerfile incluído configura a dependência ICU que o runtime .NET empacotado precisa no Linux:

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

Summary

O GroupDocs.Markdown para Python via .NET traz o motor completo de conversão documento‑para‑Markdown para Python como um wheel autocontido — sem runtime externo, sem nuvem, sem surpresas. Uma API pythonic, suporte async e integração de ferramentas de IA de primeira classe o tornam uma escolha prática para equipes Python que constroem sistemas RAG, geradores de sites estáticos ou pipelines de processamento de documentos.

Learn more

Support & feedback

Para perguntas ou assistência técnica, use nosso Free Support Forum — teremos prazer em ajudar.