📚 CalibreSynapseCLI

CalibreSynapseCLI is a semantic metadata explorer for Calibre libraries. It allows readers and curators to navigate their personal book collections using custom metadata fields that can be combined or excluded dynamically. This tool requires users to enrich their libraries with metadata generated with the help of AI. These labels populate the vocabularies that power CalibreSynapse’s semantic engine.

---

🚀 Features

Query your Calibre library by emotional tone, pacing, themes, genres, and more Build a semantic compatibility matrix from your custom metadata Use AI to generate nuanced labels for each book Discover hidden connections between books you already own Fully offline and privacy-respecting

---

🛠️ Requirements

To run CalibreSynapseCLI on Linux:

• Python 3
• Calibre Server installed and running
• Python packages:

pip install pyfiglet feedparser urwid

---

📁 Files Included

• CalibreSynapse.py — the interactive CLI interface
• Semantic_Compatibility_Matrix_Builder.py — builds the semantic index
• config.json — sample configuration for paths and metadata fields
• sample_metadata_prompt.txt — example prompt for AI-assisted label generation
• calibre_import.sh — Calibre book import script
• sample_generated_files.txt — Want to see how the output files from semantic_compatibility_matrix_builder.py are structured? Check out the included sample.

---

📥 Book Import Script

This script allows you to upload digital books into your Calibre Library directly from the terminal. It supports both single-file and batch imports, and logs all actions for easy tracking.

🧰 Supported Formats

• .epub, .pdf, .cbz, .cbr, .mobi, .azw, .azw3, .txt, .djvu, .lit, .fb2, .zip, .rar

⚠️ Archive formats like .zip and .rar are supported only if Calibre can extract and recognize the book files inside.

🛠️ Features

• Import a single file or scan an entire folder
• Supports a wide range of ebook and comic formats
• Logs all actions to ~/.local/share/calibre_import/calibre_import.log
• Automatically fixes permissions after import

🚀 Usage

bash calibre_import.sh

You’ll be prompted to choose between:

• single — paste the full path to one file
• multi — paste the full path to a folder containing multiple files

Example session:

Do you want to import a single file or multiple files? (Type: single / multi)
single
Paste the full path to the file you want to import:
/home/user/Books/The_Great_Gatsby.epub
✅ File imported successfully.

---

🔍 How CalibreSynapse Works

CalibreSynapse isn’t just a metadata tool, it’s a semantic search engine for your personal library. Think of your labels as forming a vast constellation:

• Some are isolated islands, representing niche moods or rare themes
• Others form small atolls, clusters of books that share a few traits
• And some belong to large conglomerates, densely connected genres or emotional tones

When you select a label, CalibreSynapse instantly filters out all incompatible ones. What remains are only those labels that coexist with your current selection, forming a dynamic map of possibilities. You can switch labels freely, exploring combinations that reflect your mood, memories, or curiosities.

Each label displays a number, the count of books that match your current selection when that label is added. This lets you refine your search intuitively, guided by compatibility rather than rigid categories.

Books are visually distinguished:

• 🟦 Standalone books appear in one color
• 🟨 Series are shown in another, so you can track narrative arcs or thematic continuities

The result is a fluid, exploratory interface that helps you rediscover your own collection, not by title or author, but by emotional resonance, pacing, and thematic depth.

It’s the kind of search engine you use while sipping a warm cup of coffee or maybe tea, reflecting on what you’d like to read next — especially when you're not following any specific reading program and just want something undefined or unexpected.

In my case, it mirrors the books I actually own, but I guess it could also be used for books you don’t have yet, maybe even your local library’s catalogue. I guess I could add a wishlist to CalibreSynapse if I wanted to.

---

⚙️ Setup Instructions

1. Create Custom Columns in Calibre Desktop

Make sure to define your metadata fields as composite, not atomic. For example, if you enter rebellious, astute, brave, romantic in the "Character Traits" column and the field is atomic, Calibre will treat it as a single label. If the column is composite, each trait will be treated as a separate label — which is what CalibreSynapse requires.

You can use the structure provided in metadata-formAI.txt or create your own columns.

If you're running a GUI-less Calibre server, use SQLite3 to create your custom columns manually.

---

2. Inspect Column Names via SQLite

To match your custom columns with their internal database names:

sqlite3 /path/to/metadata.db
.schema custom_column_1

Then run:

SELECT rowid, label, name, datatype FROM custom_columns ORDER BY rowid;
SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'custom_column_%' AND name != 'custom_columns';

Now you can manually pair each custom_column_X table with its corresponding label. This helps you identify how Calibre internally names your columns (e.g. #genre, #themes).

---

3. Edit the Semantic Matrix Builder

1. Modify the paths in Semantic_Compatibility_Matrix_Builder.py to match:

   • The location of your metadata.db
   • The folder where CalibreSynapse is stored

2. Update the script to include your personalized columns using the internal names retrieved via SQLite.

---

4. Generate Semantic Labels

a. Find the book ID in your Calibre Library

Books are stored under /Author Name/Book Title (ID). If the author is unknown, the book will be placed in /Unknown/.

b. Use the Sample AI Prompt to Generate Semantic Labels
Paste the book’s metadata form and its Calibre book ID into your AI tool, along with a prompt that instructs it to generate clean, structured semantic labels. These labels will populate your custom metadata fields and feed into CalibreSynapse’s semantic engine.

Formatting Guidelines

1. publication_period
   Use decade-based labels like "1950s", "1980s", or broader descriptors like "Ancient", "Classics", "Modern Classics", "Modern"
   ❌ Avoid ranges like "1999–2006" or "1920–1956"

2. Comma Usage
   Always separate labels with commas — never use "and"
   ✅ "existential dread, fast paced"
   ❌ "existential dread and fast paced"

3. Descriptions
   Include colorful HTML-style emoticons and a short description of the book. Add biographical info about the author.
   Example:

   📘 A haunting tale of memory and loss set in post-war Japan. Author Yasunari Kawabata was born in Osaka and won the Nobel Prize in Literature in 1968.

4. provenance
   Only include the author's nationality
   ✅ "provenance": ["Japan"]
   ❌ "provenance": ["Penguin Classics"]

5. Label Length
   Use short, punchy labels — ideally one word, max three. Avoid full sentences
   ✅ "whodunit", "crime fiction", "existential dread"
   ❌ "fast paced mounting to unsettling feelings"

6. book_setting
   Use generalized descriptors like "estate", "village", "seaside town", "urban district", "countryside"
   ✅ "book_setting": ["England, countryside"]
   ✅ "book_setting": ["Paris", urban district"]
   ❌ "book_setting": ["12 Rue des Fleurs, Paris"]

   Also provide a more specific version of the setting outside the code block for reference.

c. Manually Refine the Output

Review and edit the AI-generated labels to ensure they match your taxonomy and expectations.

d. Inject the Labels into Calibre

Use the terminal or Calibre GUI to paste the metadata into the correct fields.

e. Run the Semantic Matrix Builder

This will generate the following files inside your CalibreSynapse folder:

• semantic_label_map.json
• dynamic_vocabulary.json

---

e. Run the Semantic Matrix Builder

This will generate the following files inside your CalibreSynapse folder:

• semantic_label_map.json
• dynamic_vocabulary.json
• vocabulary_parser.json
• label_frequency.json
• flat_label_index.json

f. Update CalibreSynapseCLI

Edit the paths in CalibreSynapse.py to point to your CalibreSynapse folder.

g. Launch CalibreSynapseCLI

python CalibreSynapse.py

---

🧠 Tips

• To view available metadata fields:

python CalibreSynapse.py --labels

• To inspect canonical labels in a specific field:

python CalibreSynapse.py show genre

• To customize allowed fields, edit the ALLOWED_FIELDS set in the code:

# 🛠️ Customize this set with the same columns you created in Calibre Desktop.
ALLOWED_FIELDS = {
    "Genre", "Themes", "Perspective", "Reading Mood", "Narrative Structure"
}

---

📦 License

This project is licensed under the MIT License — feel free to use, modify, and share.