Bookscout
Transform Your Reading Experience
Documentation
English
Introduction
Bookscout is a comprehensive personal library management application for macOS and iOS. It helps you organize your book collection, collect memorable quotes, and interact with an AI assistant to enhance your reading experience.
Getting Started
Main Interface
Bookscout's interface is organized into several sections accessible from the sidebar:
- Books: Manage your book collection
- Quotes: Organize your favorite quotes
- AI Assistant: Ask questions about your library
- Settings: Customize the application
Managing Books
Adding a Book
Manual Entry:
- Click the "+" button in the Books view toolbar
- Fill in the book details: Title (required), Author, ISBN, Genre, Language, Summary, Publication date, Rating, Reading status
- Optionally, add a cover image
- Click "Save"
ISBN Barcode Scanner:
- Click the barcode scanner icon in the toolbar
- Point your camera at the book's ISBN barcode
- Book information is automatically retrieved from online databases
- Review and save the book to your library
Import from File:
- Go to Settings > Data > Import Books
- Select a JSON backup file
- Review import results showing number of books imported, skipped (duplicates), and any errors
Viewing Your Books
Switch between two view modes using the toolbar button:
- Grid View: Visual book covers in a grid layout - perfect for browsing your collection
- List View: Compact list format showing title, author, and status - ideal for quick scanning
Searching and Filtering
Quick Search:
- Type in the search bar to find books by title, author, or ISBN
- Search results update in real-time as you type
Advanced Filters:
- Reading Status: Filter by To Read, Reading, Finished, or Abandoned
- Genre: Show books from specific genres
- Language: Filter by language
- Rating: Set minimum rating filter (1-5 stars)
- Date Range: Filter books by date added
Sorting Options:
- Title (A-Z)
- Date added (newest first)
- Reading status
- Rating (highest first)
Organizing Your Library
Reading Status: Track your reading progress with four statuses:
- To Read: Books in your reading list
- Reading: Currently reading
- Finished: Completed books
- Abandoned: Books you stopped reading
Ratings: Rate books from 1 to 5 stars to track your favorites and remember which books you enjoyed most.
Genres: Categorize books by genre for better organization and easier discovery.
Editing and Deleting Books
- Tap a book to view its details
- Tap the Edit button to modify any information
- Delete books using the delete option (associated quotes can be kept or removed)
Exporting Books
- Go to Settings > Data > Export Books
- Choose save location
- File is saved with timestamp:
bookscout_books_YYYY-MM-dd_HH-mm-ss.json - Use this file to backup or transfer your library
Managing Quotes
Creating Quotes
Manual Entry:
- Open Quotes view and tap the "+" button
- Enter quote text
- Optionally link to a book from your library
- Add page number, author name, or notes for context
- Save the quote
From AI Assistant:
- In AI Assistant, get a response
- Tap "Add to Book" on the message
- Select target book
- Quote is automatically saved to your collection
Viewing Quotes
Switch between two view modes:
- Grid View: Visual quote cards with preview text and associated book
- List View: Compact format showing full quote text and source book
Searching and Organizing Quotes
Search: Use the search bar to find quotes by content - search through all your saved quotes instantly.
Filter by Book: View all quotes from a specific book - quotes are automatically linked when you associate them with books.
Filter by Author: Filter quotes by the author of the source book to see all quotes from your favorite authors.
Editing and Managing Quotes
- Tap a quote to view full details
- Edit quote text or metadata
- Delete quotes you no longer need
Import and Export Quotes
Exporting:
- Go to Settings > Data > Export Quotes
- Choose save location
- File is saved with timestamp:
bookscout_quotes_YYYY-MM-dd_HH-mm-ss.json
Importing:
- Go to Settings > Data > Import Quotes
- Select a JSON backup file
- Review import results (imported, skipped, errors)
AI Assistant
Getting Started
Bookscout includes a powerful AI assistant that can help you:
- Answer questions about your collection
- Find books you've read this year
- Get book recommendations
- Explore library statistics
- Analyze your reading habits
RAG (Retrieval-Augmented Generation)
Bookscout features an advanced RAG system that enhances AI responses by searching through your library:
What is RAG?
RAG (Retrieval-Augmented Generation) allows the AI to search through your books and quotes to provide more accurate and contextually relevant answers. When RAG is enabled, the AI:
- Searches your library for relevant information before answering
- Uses both semantic search (understanding meaning) and keyword search (exact matches)
- Combines information from multiple sources (books, quotes, metadata)
- Provides answers based on your actual collection
How to Use RAG:
- Toggle RAG on/off using the magnifying glass icon in the input bar
- When enabled (blue icon), the AI will search your library before responding
- When disabled (gray icon), the AI responds using only its general knowledge
RAG Search Modes:
- Simple Mode: Searches through book metadata, summaries, and quotes - faster and uses less context
- RAG combines vector search (semantic similarity) with keyword search for best results
When to Use RAG:
- Questions about your specific collection ("What books have I read this year?")
- Finding information from your books ("What did I learn about [topic]?")
- Getting recommendations based on your reading history
- Analyzing patterns in your library
When to Disable RAG:
- General questions that don't require your library data
- Faster responses when you don't need library context
Setting Up AI Providers
Go to Settings > AI Providers to configure your preferred AI service:
Gemini (Google):
- Get API key from Google AI Studio
- Enter in Settings
- Select model
- Test connection
OpenAI:
- Get API key from OpenAI
- Enter in Settings
- Choose model (GPT-3.5 or GPT-4)
- Test connection
Mistral:
- Get API key from Mistral AI
- Enter in Settings
- Select model
- Test connection
Ollama (macOS only):
- Install Ollama on your Mac
- Set host URL (default: http://localhost:11434)
- No API key needed
- Run models locally for complete privacy
Using the AI Assistant
Common Use Cases:
- "What books have I read this year?"
- "Show me all science fiction books"
- "What's my average reading rating?"
- "Recommend books similar to [title]"
- "What should I read next?"
- "Find quotes about [topic]"
Adding Quotes from AI:
- Get a useful AI response
- Tap "Add to Book" button on the message
- Select target book
- Quote is saved automatically
Settings
Appearance
Themes: Choose from multiple themes:
- System: Automatically matches your device appearance
- Light: Bright, clean interface
- Dark: Reduced eye strain, better for low-light reading
- Sepia: Warm, paper-like tones
- High Contrast: Enhanced visibility and accessibility
- Voyelles: Special artistic theme with manuscript background
Density: Control spacing in the interface:
- Compact: More content visible
- Normal: Balanced layout
- Spacious: Comfortable spacing
Localization
Language: Switch between English and French. The interface updates immediately when you change the language.
AI Provider Configuration
Configure your AI assistant providers, API keys, and models. Test connections to ensure everything is working properly.
Sync
iCloud Sync:
- Enable CloudKit synchronization
- Access your library across all your Apple devices (Mac, iPhone, iPad)
- Automatic backup and synchronization
- All data is encrypted and securely backed up to iCloud
Data Management
Cache Management:
- Adjust memory cache size
- Clear image cache
- Free up storage space
Import/Export: Backup your entire library with JSON export. Import books and quotes from backups to ensure your data is always safe and portable.
Deletion: Clear local data (removes from device only) or clear CloudKit data (removes from all devices).
Privacy
- API keys are stored securely in Keychain
- Local data stays on your device
- CloudKit data is encrypted by Apple
Credits
The "Voyelles" theme uses a background image of Arthur Rimbaud's manuscript of the poem "Voyelles" (1871-1872). This image is used under the Creative Commons Attribution-ShareAlike 3.0 Unported license (CC BY-SA 3.0).
Image Attribution:
- Author: Siren-Com
- Source: Wikimedia Commons
- License: CC BY-SA 3.0
- Description: Facsimile of Rimbaud's autograph manuscript of the poem "Voyelles" from the Musée Rimbaud in Charleville-Mézières, photographed during the "Rimbaudmania" exhibition in Paris.