Calibre Converter

SKILL.md

# Calibre Converter

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.