Calibre Converter

Calibre Converter is an OpenClaw skill for requesting format conversion of books already registered in Calibre. It does not run ebook-convert or calibredb directly; instead, it identifies the book, confirms the target format, and calls calibre-openclaw-server to convert, register, and return the result. It supports EPUB, AZW3, MOBI, PDF, DOCX, and TXT, with safe agent rules for Kindle, Kobo, duplicate titles, and conversion quality review.

Use este skill sempre que o usuário pedir para converter um livro, e-book ou documento já cadastrado no Calibre para outro formato. Acione também quando o usuário mencionar conversão para formatos como epub, mobi, azw3, pdf, docx, txt, html, rtf, fb2, lit, lrf, pdb, rb, snb, tcr ou qualquer outro formato suportado pelo Calibre.

O objetivo deste skill é receber a intenção do usuário, identificar o livro de forma única e pedir ao calibre-openclaw-server que faça toda a operação. O skill não deve executar ebook-convert nem calibredb diretamente.

Responsabilidade do skill

• Entender qual livro o usuário quer converter.
• Identificar o livro por book_id, calibre_id ou pelo título exato quando o título identificar um único cadastro.
• Entender o formato de destino solicitado.
• Chamar o endpoint do calibre-openclaw-server.
• Informar ao usuário o resultado retornado pelo servidor.

Responsabilidade do calibre-openclaw-server

• Localizar o livro no catálogo pelo ID ou pelo título exato.
• Escolher o arquivo de origem disponível no cadastro do Calibre.
• Executar a conversão com as ferramentas do Calibre.
• Cadastrar o novo formato no Calibre.
• Sincronizar o estado do servidor com a biblioteca.
• Retornar ao skill o status, mensagem, livro identificado, formato gerado e caminho cadastrado.

Quando usar

• O usuário pede para converter um livro de um formato para outro.
• O usuário fornece o título exato ou o ID do livro e solicita um formato final específico.
• O usuário quer preparar um e-book para Kindle, Kobo, celular, tablet ou outro leitor.
• O usuário quer que o novo formato fique cadastrado na biblioteca do Calibre.
• O usuário menciona Calibre, calibre-openclaw-server, conversão de e-book ou cadastro de novo formato.

Endpoint esperado

O skill deve chamar:

http

POST /api/books/convert-format

Payload:

json

{
  "book_id": 123,
  "calibre_id": 456,
  "title": "Título exato do livro",
  "target_format": "epub",
  "source_format": "pdf",
  "force": false
}

Regras do payload:

• Envie apenas um identificador principal quando possível: book_id, calibre_id ou title.
• Use title somente quando o usuário fornecer o título exato ou quando uma busca anterior confirmar um único livro.
• target_format é obrigatório.
• source_format é opcional e só deve ser usado quando o usuário pedir ou quando houver necessidade técnica clara.
• force deve ficar false por padrão. Use true apenas quando o usuário pedir para substituir/regerar um formato que já existe.

Resposta esperada:

json

{
  "success": true,
  "message": "Converted and registered EPUB for book 456.",
  "book_id": 123,
  "calibre_id": 456,
  "title": "Título exato do livro",
  "source_format": "PDF",
  "target_format": "EPUB",
  "output_path": "/caminho/para/o/livro.epub",
  "already_available": false,
  "registered": true,
  "synced_count": 1
}

Script de apoio

Use o script scripts/calibre_converter_client.py quando precisar chamar o servidor pela linha de comando:

bash

python3 scripts/calibre_converter_client.py --calibre-id 456 --target-format epub

Também é possível identificar por título exato:

bash

python3 scripts/calibre_converter_client.py --title "Título exato do livro" --target-format azw3

Variáveis de ambiente suportadas:

• CALIBRE_OPENCLAW_SERVER_URL: URL base do servidor. Padrão: http://127.0.0.1:6180.
• CALIBRE_OPENCLAW_API_KEY: chave usada no cabeçalho Authorization: Bearer.

O script carrega automaticamente o arquivo .env da raiz deste skill antes de ler essas variáveis. Variáveis já exportadas no ambiente têm prioridade sobre o .env.

Regras de comportamento

• Se o usuário especificar o formato de saída, use exatamente esse formato.
• Se o usuário não especificar formato, pergunte qual formato deseja antes de chamar o servidor.
• Se o usuário mencionar Kindle sem especificar formato, prefira azw3, salvo se ele pedir explicitamente mobi, epub ou pdf.
• Se o usuário mencionar Kobo, Apple Books ou leitura geral em e-readers, prefira epub quando o formato não for especificado.
• Se houver mais de um livro com o mesmo título, não escolha sozinho: peça o ID ou uma confirmação do livro correto.
• Não prometa que a conversão foi feita antes de receber sucesso do servidor.
• Ao final, informe o título, formato gerado e caminho retornado pelo servidor.

Observações

Conversões de PDF para EPUB podem exigir ajustes manuais de layout, sumário e quebras de página. Quando a qualidade do resultado for importante, recomende revisar o arquivo convertido no Calibre ou em um leitor compatível.