--- slug: "calibre-ebooks-x" source_type: "clawhub" source_url: "https://clawhub.ai/skills/calibre-ebooks" repo: "" source_file: "description" --- --- name: calibre-ebooks description: Manage and query the local Calibre library through the Books API, using local Calibre/RAG helpers only when file resolution or semantic indexing is explicitly needed. metadata: '{"openclaw":{"requires":{"bins":["python3"]}}}' homepage: https://github.com/carlosdelfino/openclaw-skill-calibre-ebooks --- # Calibre E-books Location: `/skills/calibre-ebooks/SKILL.md` from the OpenClaw workspace root. Use this skill only to manage and query the local Calibre-backed Books API and, when needed, prepare books that already exist in the local Calibre library for semantic RAG. ## Primary Interface Use the Books API for local catalog discovery, metadata, formats, covers, local file access, and library statistics. - Base URL: `http://host.docker.internal:6180` - Swagger UI: `http://host.docker.internal:6180/docs` - ReDoc: `http://host.docker.internal:6180/redoc` - OpenAPI JSON: `http://host.docker.internal:6180/openapi.json` - Python API client: `scripts/books_api_client.py` Do not assume endpoint names or hardcode URLs. The Python API client `books_api_client.py` features a dynamic discovery and scoring engine that auto-resolves logical actions (like searching, detail lookup, downloading, covers, stats, health status, and uploading) to the actual active endpoints defined in the current OpenAPI specification (`/openapi.json`). For custom endpoints not covered by logical commands, use the `find` command to discover details dynamically. ## Directory Reference Map Treat the skill directory as the sandbox for generated files `skills/calibre-ebboks/tmp`. Keep temporary book files, covers, exported local files, and derived artifacts inside `skills/calibre-ebooks/tmp/` unless a runtime explicitly provides a safer attachment path. External paths from the sandbox workspace and internal paths inside the sandbox: - `skills/calibre-ebooks/` - skill root; contains this `SKILL.md`, helper scripts, server code, and temporary skill artifacts. Sandbox `/workspace/` - `skills/calibre-ebooks/scripts/` - command-line clients and small automation helpers. Do not write exported files here. Sandbox `/workspace/scripts/` - `skills/calibre-ebooks/tmp/downloads/` - temporary local book/file exports meant for attachment delivery when the user is authorized to access the local Calibre library. Delete files here after the runtime confirms the attachment was sent/read. Sandbox `/workspace/tmp/downloads/`. - `skills/calibre-ebooks/tmp/calibre-covers/` - temporary cover images meant for `MEDIA:` attachment delivery. Delete files here after successful delivery. Sandbox `/workspace/tmp/calibre-covers/` - `skills/calibre-ebooks/tmp/` - general scratch area for this skill. It is safe to create subdirectories here for short-lived generated artifacts. Sandbox `/workspace/tmp` - `agents/rapport-bibliotecario/memory/calibre-import-queue/` - manual import queue for received book attachments. This is inside the OpenClaw workspace but outside this skill directory; use it only for queued inbound attachments. - `/api/downloads/queue` - download queue endpoint to record and process missing books. External or mapped paths and services: - `BOOKS_API_URL` - optional API base URL override for `books_api_client.py`. If unset, the client uses `http://host.docker.internal:6180`. - `http://host.docker.internal:6180` - Books API as seen from containerized runtimes. It is an internal service address, not a user-facing link. - `LOG_DIR` - external server log directory when configured by the server. Do not expose it in normal user-facing replies. - `/skill/calibre-books/tmp/...` - operating-system temporary space. Use only for ephemeral local experiments. Prefer `skills/calibre-ebooks/tmp/...` for files that may need to be attached, inspected, or cleaned by the skill. ## Python API Client Run commands from the OpenClaw workspace root: ```bash python3 /skills/calibre-ebooks/scripts/books_api_client.py --help ``` Or run from inside the skill directory: ```bash cd /skills/calibre-ebooks python3 scripts/books_api_client.py --help ``` Configuration precedence: 1. `--base URL` command-line option. 2. `BOOKS_API_URL` environment variable loaded from the shell or `.env`. 3. Default `http://host.docker.internal:6180`. The client reads `.env` files from these locations, in order, without overwriting variables already set in the environment: - `/skills/calibre-ebooks/scripts/.env` - `/skills/calibre-ebooks/.env` - current working directory `.env` Command syntax: ```bash python3 /skills/calibre-ebooks/scripts/books_api_client.py [--base URL] COMMAND [ARGS...] ``` Global option: - `--base URL` - override `BOOKS_API_URL` and the default Books API URL for this invocation. ### Dynamic Auto-Discovery Commands To support seamless gateway evolution, the client automatically discovers and maps the best-fitting active endpoints and parameters from the API's OpenAPI specification at runtime. Prefer these commands to avoid hardcoding routes: - `docs` - print Swagger UI, ReDoc, and OpenAPI JSON URLs for the selected API base. - `openapi` - fetch and print the current OpenAPI JSON document. - `paths` - summarize available API paths with methods, operation IDs, path parameters, and query parameters. - `find KEYWORD` - search the OpenAPI schema for paths, operation IDs, or summaries matching a keyword. Use this to discover new custom endpoints. - `search QUERY [--limit N]` - dynamically discovers the catalog search endpoint and executes search (catalog first, semantic fallback on server). - `semantic QUERY [--limit N] [--threshold VALUE]` - dynamically discovers the semantic/RAG search endpoint (POST or GET) and maps query, limit, and similarity threshold parameters. - `book BOOK_ID` - dynamically discovers the book detail endpoint and fetches metadata. - `download BOOK_ID [--output PATH] [--output-dir DIR] [--format FMT] [--check-virus]` - dynamically discovers the book file retrieval/download endpoint and downloads the book. - `cover BOOK_ID [--output PATH] [--output-dir DIR]` - dynamically discovers the cover image retrieval endpoint and downloads the cover. - `stats` - dynamically discovers the library/RAG statistics endpoint and fetches metrics. - `status` - dynamically discovers the health/database status endpoint and retrieves diagnostic status. - `upload FILE [--check-virus]` - dynamically discovers the book upload endpoint and uploads the local file using multipart form-data. - `request METHOD PATH [--query KEY=VALUE ...] [--body JSON] [--output PATH] [--output-dir DIR]` - fallback command to call an explicit endpoint when needed. Show documentation URLs: ```bash python3 /skills/calibre-ebooks/scripts/books_api_client.py docs ``` Fetch the current OpenAPI specification: ```bash python3 /skills/calibre-ebooks/scripts/books_api_client.py openapi ``` List available API paths with methods and parameters: ```bash python3 /skills/calibre-ebooks/scripts/books_api_client.py paths ``` Search for endpoints matching a keyword (e.g. "enrich"): ```bash python3 /skills/calibre-ebooks/scripts/books_api_client.py find "enrich" ``` Flexible catalog-first search, with semantic fallback handled by the server: ```bash python3 /skills/calibre-ebooks/scripts/books_api_client.py search "termo ou titulo" --limit 10 ``` Search embedded/RAG content through the Books API: ```bash python3 /skills/calibre-ebooks/scripts/books_api_client.py semantic "pergunta ou tema" --limit 10 --threshold 0.3 ``` Get book details by ID using endpoint discovery from OpenAPI: ```bash python3 /skills/calibre-ebooks/scripts/books_api_client.py book 123 ``` Check formats currently available for a book: ```bash python3 /skills/calibre-ebooks/scripts/books_api_client.py request GET /api/books/123/formats ``` Save a book cover image dynamically: ```bash python3 /skills/calibre-ebooks/scripts/books_api_client.py cover 123 --output-dir /skills/calibre-ebooks/tmp/calibre-covers ``` external folder: `skills/calibre-ebooks/tmp/calibre-covers` Get library and RAG summary statistics: ```bash python3 /skills/calibre-ebooks/scripts/books_api_client.py stats ``` Select a random book from the API catalog when the OpenAPI spec exposes a pagination/list endpoint: ```bash # First find the list/books endpoint: python3 /skills/calibre-ebooks/scripts/books_api_client.py find "books" # Then run request on the discovered path: python3 /skills/calibre-ebooks/scripts/books_api_client.py request GET /api/books --query limit=1000 ``` Call an explicit endpoint after inspecting OpenAPI: ```bash python3 /skills/calibre-ebooks/scripts/books_api_client.py request GET /books --query q=python --query limit=10 python3 /skills/calibre-ebooks/scripts/books_api_client.py request GET /books/123 python3 /skills/calibre-ebooks/scripts/books_api_client.py request POST /search --body '{"query":"python","limit":10}' ``` Save a file response dynamically: ```bash python3 /skills/calibre-ebooks/scripts/books_api_client.py download 123 --output-dir /skills/calibre-ebooks/tmp/downloads python3 /skills/calibre-ebooks/scripts/books_api_client.py download 123 --format EPUB --output-dir /skills/calibre-ebooks/tmp/downloads ``` external folder `skills/calibre-ebooks/tmp/downloads` When downloading a book, the dynamically resolved endpoint returns the selected available Calibre format with the `X-Book-Format` header. If a specific format (e.g. PDF or EPUB) is desired, supply the `--format` option. Before delivering a file to a user, check the book details or `/api/books/{id}/formats` and confirm which formats are available. If the user wants a format that is not listed, ask whether they want conversion and mention that it may take a few minutes. Use the `calibre-converter` skill to request the conversion. After conversion succeeds, download the requested format with: ```bash python3 /skills/calibre-ebooks/scripts/books_api_client.py download 123 --format EPUB --output-dir /skills/calibre-ebooks/tmp/downloads ``` For local file exports meant to be sent as attachments to an authorized user, save them in `/skills/calibre-ebooks/tmp/downloads`; externally this maps to `skills/calibre-ebooks/tmp/downloads/`. Use `--output-dir` so the API-provided complete filename is preserved. After the attachment is sent and the runtime has confirmed the upload/read, delete the temporary copy to avoid accumulating book files in the workspace. Never delete files from the Calibre library itself. If `BOOKS_API_URL` is set, the client uses it instead of `http://host.docker.internal:6180`. You can also pass `--base URL`. ## Recommended Workflow 1. Understand whether the user wants discovery, metadata, file access, or semantic analysis. 2. Run `books_api_client.py paths` or `openapi` before making specific API calls unless the exact endpoint has already been confirmed in this session. 3. Search and fetch details through the Books API. Confirm title, authors, formats, selected file format, and local access before promising delivery or analysis. 4. If the API exposes local file-access endpoints, use `books_api_client.py request` with the exact method and path from OpenAPI. 5. Never use destructive Calibre operations without explicit user request. 6. Do not search for, recommend, facilitate, or describe unauthorized sources for books. This skill is for the user's existing Calibre library only. ## Calibre metadata.db Diagnostics Before starting a Calibre sync, when health status reports degraded status, or when the Books API returns `calibre_metadata_db_unavailable`, diagnose the configured `CALIBRE_DB_PATH` through: ```bash python3 /skills/calibre-ebooks/scripts/books_api_client.py status ``` The diagnostic response includes: - `status`: `available` or `unavailable` - `reason`: stable machine-readable cause such as `file_missing`, `database_locked`, `not_sqlite_database`, `invalid_calibre_schema`, `integrity_check_failed`, `open_failed`, or `filesystem_error` - `message`: human-readable technical reason - `agent_action`: `proceed`, `wait`, or `notify_user` - `calibre_db_path`: the configured path being checked - `details`: optional evidence such as missing tables, size, mtime, or book count Agent behavior: - If `agent_action` is `proceed`, continue with the requested catalog/sync operation. - If `agent_action` is `wait`, do not alarm the user immediately. Wait briefly and retry; this usually means SQLite is temporarily locked or busy. - If `agent_action` is `notify_user`, treat the Calibre base as unsuitable for handling until the user fixes it. In internal notes include the diagnostic `reason` and `message`. In normal user-facing book replies, keep local paths and raw server details private unless the user asked for technical debugging. ## Conversational Book Replies Every book question should help the group conversation continue. Treat local availability as one part of the answer, not as the whole answer. Prefer a fluid paragraph or two over checklist-style replies. Never use tables, use list bullets When a user asks about a book, author, genre, topic, edition, or reading path: 1. Answer in a welcoming, intelligent tone that makes the reader feel invited into the library conversation. 2. If the book is confirmed in the local Calibre library, mention the confirmed title, author, id, and formats naturally in the prose, then add a reader-facing note about what the book is about, why it matters, who may enjoy it, or which question it helps answer. 3. If the book is not confirmed locally, do not answer like an inventory failure. Say naturally that the library does not have it yet, then continue by presenting the book or topic using verified public knowledge when available. Do not make the absence sound like a closed door. 4. Do not invent metadata. If external facts are not verified, phrase the reply as context, theme, or likely reading direction rather than as confirmed bibliographic detail. 5. End with one natural invitation to continue, such as asking whether the reader wants similar books in the local library, a reading order, a summary of the theme, or alternatives by the same subject. The invitation should feel conversational, not like a form. For a missing book, the visible reply should usually flow like this: 1. "The book you mentioned is interesting..." or, when appropriate, a direct neutral variation such as "This book opens an interesting conversation about..." 2. "It is not in the local library yet..." 3. A short, useful presentation of the book, subject, author, or field. 4. Lawful places to look when verified or generally appropriate: Amazon, Google Books, the publisher, and the official site for the book when such a site is verified. If there is no verified official site, do not mention one. 5. "I have informed Carlos Delfino about the absence; he will try to find it." 6. One invitation to continue: similar books in the local library, related authors, reading order, or a short explanation of the topic. Do not tell the group that the item was written to the download queue, logs, or any other internal file. The public wording is only that Carlos Delfino was informed about the absence. Example missing-book voice: `The book you mentioned is interesting because it enters a discussion about memory, identity, and how personal experience shapes our choices. It is not in the local library yet, but you can usually find it through lawful channels such as Amazon, Google Books, or the publisher. I have informed Carlos Delfino about the absence; he will try to find it. If you want, I can search the local collection for something in the same line while you wait.` Avoid dead-end replies such as only saying that the title is missing, only listing IDs, mentioning internal memory/logging, or ending with a bare operational status. ## References When Requested If the user asks for references, sources, links, or where the cited information came from, add a final `References` section to the visible reply. In that section: - Name each consulted source, such as Google Books, Amazon, the publisher, the official book site, a public library catalog, Wikipedia/Wikidata, or another verifiable catalog. - Include a link only when the exact page was confirmed. Do not invent URLs, ASINs, ISBNs, publisher pages, or official sites. - State which details came from each source: title, author, publisher, year, synopsis, subject, edition, ISBN, official page, or public availability. - If the information came from the local library, cite it as `local Calibre library` and expose only user-safe details such as title, author, id, and formats. - Do not cite internal commands, API endpoints, local filesystem paths, raw JSON, logs, OpenAPI schemas, or runtime diagnostics as references. - Never use tables, use simple bullets instead. Recommended shape: `References` `- Google Books: volume page consulted for title, author, publisher, and synopsis. ` `- Publisher: official page consulted for description and edition data. ` ## User-Facing Privacy Treat API URLs, server addresses, ports, OpenAPI paths, schema names, command lines, exit codes, filesystem paths, environment variables, timeout/connection errors, service-credit errors, and dependency diagnostics as internal instrumentation. Do not include those details in a user-facing reply unless the user explicitly asks for a technical/debug answer. When a catalog/API/local lookup fails, do not list the failed services, commands, ports, URLs, paths, or raw errors. Reply in library language: - "This title is not in the local library yet, but it connects with..." - "I could not confirm this book in the collection right now; even so, its theme touches on..." - "I have informed Carlos Delfino about the absence; he will try to find it. I can look for something close in the collection in the meantime." Do not end a normal book request by asking the user to restart services, run commands, wait for ports, or retry the API. Offer a useful next step instead: alternatives already confirmed in the local catalog, or a note that the item was registered for later review. ## Long-running Operations And Progress Updates Some Calibre and RAG operations can take several minutes, especially indexing, semantic search over a large collection, attachment processing, and metadata enrichment. When an operation may take longer than 2 minutes: 1. Send an initial visible message saying what will be processed and which step is starting. 2. Prefer queue/background/status workflows over a single blocking command. Use API status endpoints or lightweight status commands when available. 3. While the operation is active, send a short status update every 120 seconds through the available chat/message tool. 4. Include the current step, elapsed time, completed/total count when known, and the next expected step. 5. If progress numbers are not available, still send a concise heartbeat such as "I am still processing; current step: generating embeddings; elapsed time: 4 min." 6. Do not expose local filesystem paths, localhost URLs, internal API URLs, or server-only links in progress messages. 7. On completion, send one final summary with the result, relevant counts, and any failed or skipped items. On error or timeout, report the last completed step and the safest next action. If the only available implementation is a single long blocking command, do not claim that live progress messages are possible from the agent while that command is running. Use a queued/background mode or a command that writes/checkpoints status so the agent can poll and update the group every 120 seconds. ## Library And RAG Statistics When asked for counts such as indexed books, authors, publishers, categories, RAG chunks/excerpts, embedding model, chunk size, or overlap, call: ```bash python3 /skills/calibre-ebooks/scripts/books_api_client.py stats ``` Trigger this workflow for questions like: - "how many books have already been indexed?" - "how many topics are cataloged?" - "what is the library status?" - "how is the library doing?" - "what is the library state?" - "what condition is the library in?" - "give me information about the library" - "what is the RAG status?" - "how many authors/publishers/categories are there?" The endpoint returns: - `indexed_books` - `authors` - `publishers` - `categories` - `cataloged_topics` - `library_status` - `rag.chunks_excerpts` - `rag.embedding_model` - `rag.chunk_size` - `rag.overlap` - `usage.total_registered_requests` - `usage.most_requested_books` - `usage.latest_requested_book` For user-facing replies, answer in English with a compact status summary. Use `cataloged_topics` when the user asks about topics. Use `library_status` when the user asks for overall library status. For broad questions about the library situation, state, condition, or general information, treat them as library status requests and include catalog/RAG statistics plus usage statistics when available: top 5 requested books and latest requested book. Do not expose raw JSON, OpenAPI paths, local URLs, endpoint names, command exit codes, or server parameters unless the user explicitly asks for technical details. ## Book Covers When the user asks for a book cover, or when a recommendation would benefit from the cover, use the Books API cover endpoint after identifying the book id. Workflow: 1. Find or confirm the book id through the Books API. 2. Save the cover image inside this skill's temporary workspace: `/skills/calibre-ebooks/tmp/calibre-covers/`; externally this maps to `skills/calibre-ebooks/tmp/calibre-covers/` 3. Use `--output-dir` so the API filename is used, or a deterministic filename such as `book-123-cover.jpg` when an explicit path is required. 4. Send the image as an attachment using a `MEDIA:` directive on its own line: `MEDIA:skills/calibre-ebooks/tmp/calibre-covers/book-123-cover.jpg` 5. In the visible text, mention the title and author briefly. Do not print local filesystem paths, local API URLs, or server-only links. 6. If the cover endpoint returns 404 or no image is available, say that the cover is not available for that book and continue with metadata if useful. 7. After the image attachment is sent and confirmed by the runtime, delete the temporary cover file from `/skills/calibre-ebooks/tmp/calibre-covers/`. ## Title Search Fallback When the user asks for a specific book by title, do not stop after a failed catalog/title search. 1. Search the Books API for the title or quoted phrase: `python3 /skills/calibre-ebooks/scripts/books_api_client.py search "provided title" --limit 10` 2. The Books API search endpoint handles catalog-first lookup and semantic fallback. Inspect returned `result_type`: `catalog` means confirmed local book metadata, while `semantic` means a RAG/content match and should be presented as a related excerpt, not as an exact title match unless metadata confirms it. 3. Use the local RAG script only if the API semantic endpoint is unavailable or the task explicitly requires local RAG maintenance: `python3 /skills/calibre-ebooks/calibre-openclaw-server/scripts/document_semantic_rag.py --search "provided title" --json` 4. Use RAG results to identify likely related books by document/book id, page, similarity, and excerpt. Present them as probable semantic matches, not exact title matches, unless metadata confirms the title. 5. Only say that nothing was found after both catalog/title search and RAG semantic search fail or the RAG base is unavailable. If RAG is unavailable, state that the catalog search was tried and the semantic RAG fallback could not be used. 6. When the book is not found, add it to the download queue by calling the skill queue command: `python3 /skills/calibre-ebooks/scripts/books_api_client.py queue "title" --author "author" [other options]`. This will record the request on the server so Carlos Delfino or the system can retrieve it later. 7. After recording the missing book, suggest up to three alternatives from the existing library when possible. Infer category, style, genre, author, subject, and theme from the request and from any RAG snippets returned. Search the catalog/RAG again with those terms, then recommend books that are close in category, style, or theme. Clearly label them as alternatives, not as the requested book. 8. If the user wants to research the missing title outside the local library, suggest consulting Google Books or Amazon Books as public catalog/store pages for metadata, editions, publisher information, and lawful availability. Do not provide or imply unauthorized download sources. 9. Keep the visible reply open-ended and inviting: briefly introduce what the requested book or subject is about when you can verify it, connect it to a useful theme, then invite the reader to ask for similar books, context, author background, or a reading route. 10. In the visible reply, do not mention that the missing book was registered in memory or any internal file. Say only that Carlos Delfino was informed about the absence and will try to find it. Alternative suggestions should include: - title and id; - authors; - matching reason, e.g. same theme, similar genre, related subject, comparable style, or useful substitute; - available formats; - no local/server-only links. ## Incoming Book Attachments When someone sends a book file in the configured WhatsApp group, accept only book-like attachments in formats supported by the Calibre workflow, preferably PDF, EPUB, AZW3, MOBI, DjVu, TXT, RTF, or DOCX, for manual import review. Workflow: 1. Confirm the attachment is a book-like supported ebook/document format. If it is another format, politely refuse and ask for a common ebook format such as PDF or EPUB. 2. Do not import the file into Calibre automatically. 3. If the runtime provides a local attachment/media path, copy or save the file under the agent workspace: `memory/calibre-import-queue/files/` 4. Use a safe filename derived from date/time and the original basename. Avoid shell commands and never execute file contents. 5. Append an entry to: `memory/calibre-import-queue/index.md` 6. Record: date/time, source group, sender if available, original filename, detected format, saved internal path, title/author metadata if available, and status `waiting for manual import`. 7. Reply briefly to the group that the file was received and queued for manual Calibre import. Do not publish local filesystem paths, local API URLs, or internal media links in the group. The import queue lives in the Rapport Bibliotecario agent workspace: ```text agents/rapport-bibliotecario/memory/calibre-import-queue/ ``` ## Random Book Suggestions When the user asks for a book suggestion, a random book, "recommend me a book", or any generic book request without a specific title/author/topic, first try to provide one book from the Calibre library. For topic-based recommendations such as "recommend me a book about Python and digital twins", search the local library first with the topic terms and reasonable variants. If no local result is confirmed, say that the local library does not currently have a clear match and, when possible, suggest nearby alternatives already present in Calibre. You may also suggest consulting Google Books or Amazon Books for public catalog/store information about titles that are not in the local library. ## Good Night Reading Suggestions When the user says "good night", "good night everyone", "I am going to sleep", "see you tomorrow", or another night-time farewell, treat it as a light recommendation opportunity, not as a normal generic random-book request. Response goals: 1. Reply warmly and briefly. 2. Suggest one light, restful book for bedtime reading: chronicles, poetry, short stories, contemplative literature, gentle essays, calm spirituality, or quiet classics. Avoid heavy, technical, violent, polemical, or dense books. 3. Search the local Calibre library first when available. If a suitable local book is confirmed, mention title, author, id, and formats naturally. 4. If the selected bedtime book is not confirmed in the local library, add it to the download queue by calling the skill's queue command (`books_api_client.py queue`) so it can be obtained later. Do not tell the group about memory, files, queues, logs, or internal registration. 5. Public wording for missing bedtime suggestions should be: "This one is not in the local library yet, but I have informed Carlos Delfino so he can try to find it." 6. Even when the book is missing locally, present it gently: why it fits bedtime, what mood it brings, and why it can help the reader slow down. 7. Keep the reply conversational, ideally one short paragraph. Close with a calm good-night sentence. Example: `Good night. To close the day lightly, I would suggest The Little Prince, by Antoine de Saint-Exupery: it is a brief, luminous read, good for remembering friendship, care, and simplicity before sleeping. This one is not in the local library yet, but I have informed Carlos Delfino so he can try to find it. May the reading be short and sleep come gently.` Preferred API workflow: 1. Find the appropriate book listing endpoint using `books_api_client.py find "books"` or `paths` unless it is already known in this session. 2. Fetch a broad page from the listing endpoint (e.g. if the path is `/api/books`, run `python3 /skills/calibre-ebooks/scripts/books_api_client.py request GET /api/books --query limit=1000`). 3. Randomly choose exactly one item from the returned `books` array. 4. Return a useful reader-facing recommendation with title, authors, publisher, publication year, formats, id, synopsis/description, key themes, who it is for, why it is worth reading, and the practical context where the book applies. Base the synopsis on metadata/comments when available; summarize instead of copying long passages. If the API is unreachable or does not expose enough catalog items, use the read-only local fallback: ```bash python3 /skills/calibre-ebooks/calibre-openclaw-server/scripts/calibre_query.py --db "$CALIBRE_METADATA_DB" random ``` Do not repeatedly return the first item from a list. The selection must be randomized for each request. Do not include local server/API/file links such as `localhost`, `0.0.0.0`, `127.0.0.1`, `host.docker.internal`, `/api/books/...`, `file://`, or filesystem paths. Those links are not valid for group members outside the server. If access is needed, say that the book is available in the Calibre library and provide only the book id, title, authors, and formats so the librarian/admin can locate it. Recommended response shape for random suggestions: - `Book`: title and id. - `Author(s)`: authors from metadata. - `Publisher and year`: publisher and publication year when available; say `not provided` only when metadata is missing. - `Formats`: available file formats. - `Synopsis`: three to five short sentences based on Calibre comments/description, enough for a reader to understand what the book is about. - `Main themes`: two to four concrete themes covered by the book. - `Why read it`: one or two practical reasons why the recommendation is relevant. - `Context`: who should read it, what problem/topic it helps with, and when it is useful. - `Access`: mention that it is in the Calibre library by id/formats; do not add local or server-only links. ## Response Rules - Do not mention which API endpoint/method was used when returning API-derived results unless the user explicitly asked for technical details. - Show `id`, title, authors, and formats when there are multiple book matches. - Do not promise a specific format until the API response confirms that format or local file access. - If the API is unreachable, keep the URL, port, path, timeout, connection error, and command output internal. Use local fallback when available, then answer in user-facing language without exposing operational details. - For title lookups, use `books_api_client.py search`; the server handles catalog-first search and semantic fallback. Treat `result_type=semantic` as a related excerpt/match, not as confirmed availability of the requested exact title. Use `books_api_client.py semantic` or `document_semantic_rag.py --search` only for explicit RAG/content testing or local RAG maintenance. - When a requested book is still not found, queue it for download using the skill's queue command before replying. - If a requested book is missing, try alternatives from the same category, style, or theme before ending the reply. Make clear that suggestions come from the current local library. If useful, suggest consulting Google Books or Amazon Books for public catalog/store information about the missing title. - Missing locally does not mean the conversation ends. Give the reader useful context about the book or subject when verified, then leave one warm opening for the next interaction. - If `document_semantic_rag.py --check --json` reports missing dependencies, keep exact dependency diagnostics internal unless the user asked for technical debugging. For normal users, say only that semantic analysis is unavailable right now and continue with local catalog options. - For RAG-based answers, enrich the visible reply with the returned excerpt and cite document/book, page, chapter/section when available, similarity, and the relevant excerpt. If the API/script returns a `citation` field, use it as the citation base. Do not answer from memory when a RAG excerpt is available for the same claim. - If someone asks where the books come from, explain only that this skill does not add or source books. It manages and queries books that are already present in the user's local Calibre library. For books outside the library, suggest lawful public catalog/store references such as Google Books or Amazon Books. # Fetch Para fazer fetch simples, use o `curl`, só se der erro então use outros skills.