# ebk
**ebk** is a powerful eBook metadata management tool with a SQLAlchemy + SQLite database backend. It provides a comprehensive fluent API for programmatic use, a rich Typer-based CLI (with colorized output courtesy of [Rich](https://github.com/Textualize/rich)), full-text search with FTS5 indexing, automatic text extraction and chunking for semantic search, hash-based file deduplication, and optional AI-powered features including knowledge graphs and semantic search.
---
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [CLI Usage](#cli-usage)
- [Database Commands](#database-commands)
- [Web Server](#web-server)
- [AI-Powered Features](#ai-powered-features)
- [Configuration Management](#configuration-management)
- [Legacy Commands](#legacy-commands)
- [Python API](#python-api)
- [Integrations](#integrations)
- [Architecture](#architecture)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)
- [Documentation](#documentation)
- [Stay Updated](#stay-updated)
- [Support](#support)
---
## Features
- **SQLAlchemy + SQLite Backend**: Robust database with normalized schema, proper relationships, and FTS5 full-text search
- **Fluent Python API**: Comprehensive programmatic interface with method chaining and query builders
- **Typer + Rich CLI**: A colorized, easy-to-use command-line interface
- **Automatic Text Extraction**: Extract and index text from PDFs, EPUBs, and plaintext files
- PyMuPDF (primary) with pypdf fallback for PDFs
- ebooklib with HTML parsing for EPUBs
- Automatic chunking (500-word overlapping chunks) for semantic search
- **Hash-based Deduplication**: SHA256-based file deduplication
- Same file (same hash) = skipped
- Same book, different format = added as additional format
- Hash-prefixed directory storage for scalability
- **Advanced Search**: Powerful search with field-specific queries and boolean logic
- Field searches: `title:Python`, `author:Knuth`, `tag:programming`
- Boolean operators: `AND` (implicit), `OR`, `NOT`/`-prefix`
- Comparison filters: `rating:>=4`, `rating:3-5`
- Exact filters: `language:en`, `format:pdf`, `favorite:true`
- Phrase searches: `"machine learning"`
- Fast FTS5-powered full-text search across titles, descriptions, and extracted text
- **Import from Multiple Sources**:
- Calibre libraries (reads metadata.opf files)
- Individual ebook files with auto-metadata extraction
- Batch import with progress tracking
- **Cover Extraction**: Automatic cover extraction and thumbnail generation
- PDFs: First page rendered as image
- EPUBs: Cover from metadata or naming patterns
- **AI-Powered Features** (optional):
- **LLM Provider Abstraction**: Support for multiple LLM backends (Ollama, OpenAI-compatible APIs)
- **Metadata Enrichment**: Auto-generate tags, categories, and enhanced descriptions using LLMs
- **Local & Remote LLM**: Connect to local Ollama or remote GPU servers
- **Knowledge Graph**: NetworkX-based concept extraction and relationship mapping
- **Semantic Search**: Vector embeddings for similarity search (with TF-IDF fallback)
- **Reading Companion**: Track reading sessions with timestamps
- **Question Generator**: Generate active recall questions
- **Web Server Interface**:
- FastAPI-based REST API for library management
- URL-based navigation with filters, pagination, and sorting
- Clickable covers and file formats to open books
- Book details modal with comprehensive metadata display
- **Flexible Exports**:
- **HTML Export**: Self-contained interactive catalog with pagination (50 books/page)
- Client-side search and filtering
- URL state tracking for bookmarkable pages
- Optional file copying with `--copy` flag (includes covers)
- Export to ZIP archives
- Hugo-compatible Markdown with multiple organization options
- Jinja2 template support for customizable export formats
- **Integrations** (optional):
- **Streamlit Dashboard**: Interactive web interface
- **MCP Server**: AI assistant integration
- **Visualizations**: Network graphs for analysis
---
## Installation
### Basic Installation
```bash
pip install ebk
```
### From Source
```bash
git clone https://github.com/queelius/ebk.git
cd ebk
pip install .
```
### With Optional Features
```bash
# With Streamlit dashboard
pip install ebk[streamlit]
# With visualization tools
pip install ebk[viz]
# With all optional features
pip install ebk[all]
# For development
pip install ebk[dev]
```
> **Note**: Requires Python 3.10+
---
## Quick Start
### 1. Initialize Configuration
```bash
# Create default configuration file at ~/.config/ebk/config.json
ebk config init
# View current configuration
ebk config show
# Set default library path
ebk config set library.default_path ~/my-library
```
### 2. Create and Populate Library
```bash
# Initialize a new library
ebk init ~/my-library
# Import a single ebook with auto-metadata extraction
ebk import book.pdf ~/my-library
# Import from Calibre library
ebk import-calibre ~/Calibre/Library --output ~/my-library
# Search using full-text search
ebk search "python programming" ~/my-library
# List books with filtering
ebk list ~/my-library --author "Knuth" --limit 20
# Get statistics
ebk stats ~/my-library
```
### 3. Launch Web Interface
```bash
# Start web server (uses config defaults)
ebk serve ~/my-library
# Custom port and host
ebk serve ~/my-library --port 8080 --host 127.0.0.1
# Auto-open browser
ebk config set server.auto_open_browser true
ebk serve ~/my-library
```
### 4. AI-Powered Metadata Enrichment
```bash
# Configure LLM provider
ebk config set llm.provider ollama
ebk config set llm.model llama3.2
ebk config set llm.host localhost
# Enrich library metadata using LLM
ebk enrich ~/my-library
# Enrich with all features
ebk enrich ~/my-library --generate-tags --categorize --enhance-descriptions
# Use remote GPU server
ebk enrich ~/my-library --host 192.168.1.100
```
---
## Configuration
ebk uses a centralized configuration system stored at `~/.config/ebk/config.json`. This configuration file manages settings for LLM providers, web server, CLI defaults, and library preferences.
### Configuration File Structure
```json
{
"llm": {
"provider": "ollama",
"model": "llama3.2",
"host": "localhost",
"port": 11434,
"api_key": null,
"temperature": 0.7,
"max_tokens": null
},
"server": {
"host": "0.0.0.0",
"port": 8000,
"auto_open_browser": false,
"page_size": 50
},
"cli": {
"verbose": false,
"color": true,
"page_size": 50
},
"library": {
"default_path": null
}
}
```
### Configuration Management
```bash
# Initialize configuration (creates default config file)
ebk config init
# View current configuration
ebk config show
# Edit configuration in your default editor
ebk config edit
# Set specific values
ebk config set llm.provider ollama
ebk config set llm.model mistral
ebk config set server.port 8080
ebk config set library.default_path ~/my-library
# Get specific value
ebk config get llm.model
```
### LLM Provider Configuration
Configure LLM providers for metadata enrichment:
```bash
# Local Ollama (default)
ebk config set llm.provider ollama
ebk config set llm.host localhost
ebk config set llm.port 11434
ebk config set llm.model llama3.2
# Remote GPU server
ebk config set llm.host 192.168.1.100
# OpenAI-compatible API (future)
ebk config set llm.provider openai
ebk config set llm.api_key sk-...
ebk config set llm.model gpt-4
```
### CLI Overrides
All commands support CLI arguments that override configuration defaults:
```bash
# These override config settings
ebk serve ~/library --port 9000 --host 127.0.0.1
ebk enrich ~/library --host 192.168.1.50 --model mistral
```
## CLI Usage
ebk uses [Typer](https://typer.tiangolo.com/) with [Rich](https://github.com/Textualize/rich) for a beautiful, colorized CLI experience.
### General CLI Structure
```bash
ebk --help # See all available commands
ebk <command> --help # See specific command usage
ebk --verbose <command> # Enable verbose output
```
### Database Commands
Core library management with SQLAlchemy + SQLite backend:
```bash
# Initialize library
ebk init ~/my-library
# Import books
ebk import book.pdf ~/my-library
ebk import ~/books/*.epub ~/my-library
ebk import-calibre ~/Calibre/Library --output ~/my-library
# Search with advanced syntax
ebk search "machine learning" ~/my-library # Plain full-text search
ebk search "title:Python rating:>=4" ~/my-library # Field-specific with filters
ebk search "author:Knuth format:pdf" ~/my-library # Multiple criteria
ebk search "tag:programming NOT java" ~/my-library # Boolean operators
ebk search '"deep learning" language:en' ~/my-library # Phrase search with filter
# List and filter
ebk list ~/my-library
ebk list ~/my-library --author "Knuth" --language en --limit 20
ebk list ~/my-library --format pdf --rating 4
# Statistics
ebk stats ~/my-library
ebk stats ~/my-library --format json
# Manage reading status
ebk rate ~/my-library <book-id> 5
ebk favorite ~/my-library <book-id>
ebk tag ~/my-library <book-id> --add "must-read" "technical"
# Remove books
ebk purge ~/my-library --rating 1 --confirm
```
### Web Server
Launch FastAPI-based web interface:
```bash
# Start server (uses config defaults)
ebk serve ~/my-library
# Custom host and port
ebk serve ~/my-library --host 127.0.0.1 --port 8080
# Auto-open browser
ebk serve ~/my-library --auto-open
# Configure defaults in config
ebk config set server.port 8080
ebk config set server.auto_open_browser true
```
### AI-Powered Features
Enrich metadata using LLMs:
```bash
# Basic enrichment (uses config settings)
ebk enrich ~/my-library
# Full enrichment
ebk enrich ~/my-library \
--generate-tags \
--categorize \
--enhance-descriptions \
--assess-difficulty
# Enrich specific book
ebk enrich ~/my-library --book-id 42
# Use remote GPU server
ebk enrich ~/my-library --host 192.168.1.100 --model mistral
# Dry run (preview changes without saving)
ebk enrich ~/my-library --dry-run
```
### Configuration Management
Manage global configuration:
```bash
# Initialize configuration
ebk config init
# View configuration
ebk config show
ebk config show --section llm
# Edit in default editor
ebk config edit
# Set values
ebk config set llm.model llama3.2
ebk config set server.port 8080
ebk config set library.default_path ~/books
# Get values
ebk config get llm.model
```
### Export and Advanced Features
```bash
# Export library
ebk export html ~/my-library ~/library.html # Self-contained HTML with pagination
ebk export html ~/my-library ~/site/lib.html --copy --base-url /library # Copy files + covers
ebk export zip ~/my-library ~/backup.zip
ebk export json ~/my-library ~/metadata.json
# Virtual libraries (filtered views)
ebk vlib create ~/my-library "python-books" --subject Python
ebk vlib list ~/my-library
# Notes and annotations
ebk note add ~/my-library <book-id> "Great chapter on algorithms"
ebk note list ~/my-library <book-id>
```
---
## Documentation
Comprehensive documentation is available at: **[https://queelius.github.io/ebk/](https://queelius.github.io/ebk/)**
### Documentation Contents
- **Getting Started**
- [Installation](https://queelius.github.io/ebk/getting-started/installation/)
- [Quick Start](https://queelius.github.io/ebk/getting-started/quickstart/)
- [Configuration Guide](https://queelius.github.io/ebk/getting-started/configuration/)
- **User Guide**
- [CLI Reference](https://queelius.github.io/ebk/user-guide/cli/)
- [Python API](https://queelius.github.io/ebk/user-guide/api/)
- [LLM Features](https://queelius.github.io/ebk/user-guide/llm-features/)
- [Web Server](https://queelius.github.io/ebk/user-guide/server/)
- [Import/Export](https://queelius.github.io/ebk/user-guide/import-export/)
- [Search & Query](https://queelius.github.io/ebk/user-guide/search/)
- **Advanced Topics**
- [Hugo Export](https://queelius.github.io/ebk/advanced/hugo-export/)
- [Symlink DAG](https://queelius.github.io/ebk/advanced/symlink-dag/)
- [Recommendations](https://queelius.github.io/ebk/advanced/recommendations/)
- [Batch Operations](https://queelius.github.io/ebk/advanced/batch-operations/)
- **Development**
- [Architecture](https://queelius.github.io/ebk/development/architecture/)
- [Contributing](https://queelius.github.io/ebk/development/contributing/)
- [API Reference](https://queelius.github.io/ebk/development/api-reference/)
---
## Python API
ebk provides a comprehensive SQLAlchemy-based API for programmatic library management:
```python
from pathlib import Path
from ebk.library_db import Library
# Open or create a library
lib = Library.open(Path("~/my-library"))
# Import books with automatic metadata extraction
book = lib.add_book(
Path("book.pdf"),
metadata={"title": "My Book", "creators": ["Author Name"]},
extract_text=True,
extract_cover=True
)
# Fluent query interface
results = (lib.query()
.filter_by_language("en")
.filter_by_author("Knuth")
.filter_by_subject("Algorithms")
.order_by("title", desc=False)
.limit(20)
.all())
# Full-text search (FTS5)
results = lib.search("machine learning", limit=50)
# Get book by ID
book = lib.get_book(42)
print(f"{book.title} by {', '.join([a.name for a in book.authors])}")
# Update reading status
lib.update_reading_status(book.id, "reading", progress=50, rating=4)
# Add tags
lib.add_tags(book.id, ["must-read", "technical"])
# Get statistics
stats = lib.stats()
print(f"Total books: {stats['total_books']}")
print(f"Total authors: {stats['total_authors']}")
print(f"Languages: {', '.join(stats['languages'])}")
# Query with filters
from ebk.db.models import Book, Author
from sqlalchemy import and_
books = lib.session.query(Book).join(Book.authors).filter(
and_(
Author.name.like("%Knuth%"),
Book.language == "en"
)
).all()
# Always close when done
lib.close()
# Or use context manager
with Library.open(Path("~/my-library")) as lib:
results = lib.search("Python programming")
for book in results:
print(book.title)
```
### AI-Powered Metadata Enrichment
```python
from ebk.ai.llm_providers.ollama import OllamaProvider
from ebk.ai.metadata_enrichment import MetadataEnrichmentService
# Initialize provider (local or remote)
provider = OllamaProvider.remote(
host="192.168.1.100",
model="llama3.2"
)
service = MetadataEnrichmentService(provider)
async with provider:
# Generate tags
tags = await service.generate_tags(
title="Introduction to Algorithms",
authors=["Cormen", "Leiserson"],
description="Comprehensive algorithms textbook"
)
# Categorize
categories = await service.categorize(
title="Introduction to Algorithms",
subjects=["Algorithms", "Data Structures"]
)
# Enhance description
description = await service.enhance_description(
title="Introduction to Algorithms",
text_sample="Chapter 1: The Role of Algorithms..."
)
```
See the [CLAUDE.md](CLAUDE.md) file for architectural details and [API documentation](https://queelius.github.io/ebk/user-guide/api/) for complete reference.
---
## Contributing
Contributions are welcome! Here’s how to get involved:
1. **Fork the Repo**
2. **Create a Branch** for your feature or fix
3. **Commit & Push** your changes
4. **Open a Pull Request** describing the changes
We appreciate code contributions, bug reports, and doc improvements alike.
---
## License
Distributed under the [MIT License](https://github.com/queelius/ebk/blob/main/LICENSE).
---
## Integrations
ebk follows a modular architecture where the core library remains lightweight, with optional integrations available:
### Streamlit Dashboard
```bash
pip install ebk[streamlit]
streamlit run ebk/integrations/streamlit/app.py
```
### MCP Server (AI Assistants)
```bash
pip install ebk[mcp]
# Configure your AI assistant to use the MCP server
```
### Visualizations
```bash
pip install ebk[viz]
# Visualization tools will be available as a separate script
# Documentation coming soon in integrations/viz/
```
See the [Integrations Guide](integrations/README.md) for detailed setup instructions.
---
## Architecture
ebk is designed with a clean, layered architecture:
1. **Core Library** (`ebk.library`): Fluent API for all operations
2. **CLI** (`ebk.cli`): Typer-based commands using the fluent API
3. **Import/Export** (`ebk.imports`, `ebk.exports`): Modular format support
4. **Integrations** (`integrations/`): Optional add-ons (web UI, AI, viz)
This design ensures the core remains lightweight while supporting powerful extensions.
---
## Development
```bash
# Clone the repository
git clone https://github.com/queelius/ebk.git
cd ebk
# Create virtual environment
make venv
# Install in development mode
make setup
# Run tests
make test
# Check coverage
make coverage
```
---
## Stay Updated
- **GitHub**: [https://github.com/queelius/ebk](https://github.com/queelius/ebk)
- **Website**: [https://metafunctor.com](https://metafunctor.com)
---
## Support
- **Issues**: [Open an Issue](https://github.com/queelius/ebk/issues) on GitHub
- **Contact**: <lex@metafunctor.com>
---
Happy eBook managing! 📚✨
Raw data
{
"_id": null,
"home_page": "https://github.com/queelius/ebk",
"name": "ebk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Alex Towell <lex@metafunctor.com>",
"keywords": "ebook, metadata, library, books, management, calibre",
"author": "Alex Towell",
"author_email": "Alex Towell <lex@metafunctor.com>",
"download_url": "https://files.pythonhosted.org/packages/22/7a/da692a97e14c4d5f9d813d9d60949d10aad76c3891f31319a56fa277ba3b/ebk-0.3.2.tar.gz",
"platform": null,
"description": "# ebk\n\n**ebk** is a powerful eBook metadata management tool with a SQLAlchemy + SQLite database backend. It provides a comprehensive fluent API for programmatic use, a rich Typer-based CLI (with colorized output courtesy of [Rich](https://github.com/Textualize/rich)), full-text search with FTS5 indexing, automatic text extraction and chunking for semantic search, hash-based file deduplication, and optional AI-powered features including knowledge graphs and semantic search. \n\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [CLI Usage](#cli-usage)\n - [Database Commands](#database-commands)\n - [Web Server](#web-server)\n - [AI-Powered Features](#ai-powered-features)\n - [Configuration Management](#configuration-management)\n - [Legacy Commands](#legacy-commands)\n- [Python API](#python-api)\n- [Integrations](#integrations)\n- [Architecture](#architecture)\n- [Development](#development)\n- [Contributing](#contributing)\n- [License](#license)\n- [Documentation](#documentation)\n- [Stay Updated](#stay-updated)\n- [Support](#support)\n\n---\n\n## Features\n\n- **SQLAlchemy + SQLite Backend**: Robust database with normalized schema, proper relationships, and FTS5 full-text search\n- **Fluent Python API**: Comprehensive programmatic interface with method chaining and query builders\n- **Typer + Rich CLI**: A colorized, easy-to-use command-line interface\n- **Automatic Text Extraction**: Extract and index text from PDFs, EPUBs, and plaintext files\n - PyMuPDF (primary) with pypdf fallback for PDFs\n - ebooklib with HTML parsing for EPUBs\n - Automatic chunking (500-word overlapping chunks) for semantic search\n- **Hash-based Deduplication**: SHA256-based file deduplication\n - Same file (same hash) = skipped\n - Same book, different format = added as additional format\n - Hash-prefixed directory storage for scalability\n- **Advanced Search**: Powerful search with field-specific queries and boolean logic\n - Field searches: `title:Python`, `author:Knuth`, `tag:programming`\n - Boolean operators: `AND` (implicit), `OR`, `NOT`/`-prefix`\n - Comparison filters: `rating:>=4`, `rating:3-5`\n - Exact filters: `language:en`, `format:pdf`, `favorite:true`\n - Phrase searches: `\"machine learning\"`\n - Fast FTS5-powered full-text search across titles, descriptions, and extracted text\n- **Import from Multiple Sources**:\n - Calibre libraries (reads metadata.opf files)\n - Individual ebook files with auto-metadata extraction\n - Batch import with progress tracking\n- **Cover Extraction**: Automatic cover extraction and thumbnail generation\n - PDFs: First page rendered as image\n - EPUBs: Cover from metadata or naming patterns\n- **AI-Powered Features** (optional):\n - **LLM Provider Abstraction**: Support for multiple LLM backends (Ollama, OpenAI-compatible APIs)\n - **Metadata Enrichment**: Auto-generate tags, categories, and enhanced descriptions using LLMs\n - **Local & Remote LLM**: Connect to local Ollama or remote GPU servers\n - **Knowledge Graph**: NetworkX-based concept extraction and relationship mapping\n - **Semantic Search**: Vector embeddings for similarity search (with TF-IDF fallback)\n - **Reading Companion**: Track reading sessions with timestamps\n - **Question Generator**: Generate active recall questions\n- **Web Server Interface**:\n - FastAPI-based REST API for library management\n - URL-based navigation with filters, pagination, and sorting\n - Clickable covers and file formats to open books\n - Book details modal with comprehensive metadata display\n- **Flexible Exports**:\n - **HTML Export**: Self-contained interactive catalog with pagination (50 books/page)\n - Client-side search and filtering\n - URL state tracking for bookmarkable pages\n - Optional file copying with `--copy` flag (includes covers)\n - Export to ZIP archives\n - Hugo-compatible Markdown with multiple organization options\n - Jinja2 template support for customizable export formats\n- **Integrations** (optional):\n - **Streamlit Dashboard**: Interactive web interface\n - **MCP Server**: AI assistant integration\n - **Visualizations**: Network graphs for analysis\n\n---\n\n## Installation\n\n### Basic Installation\n\n```bash\npip install ebk\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/queelius/ebk.git\ncd ebk\npip install .\n```\n\n### With Optional Features\n\n```bash\n# With Streamlit dashboard\npip install ebk[streamlit]\n\n# With visualization tools\npip install ebk[viz]\n\n# With all optional features\npip install ebk[all]\n\n# For development\npip install ebk[dev]\n```\n\n> **Note**: Requires Python 3.10+\n\n---\n\n## Quick Start\n\n### 1. Initialize Configuration\n\n```bash\n# Create default configuration file at ~/.config/ebk/config.json\nebk config init\n\n# View current configuration\nebk config show\n\n# Set default library path\nebk config set library.default_path ~/my-library\n```\n\n### 2. Create and Populate Library\n\n```bash\n# Initialize a new library\nebk init ~/my-library\n\n# Import a single ebook with auto-metadata extraction\nebk import book.pdf ~/my-library\n\n# Import from Calibre library\nebk import-calibre ~/Calibre/Library --output ~/my-library\n\n# Search using full-text search\nebk search \"python programming\" ~/my-library\n\n# List books with filtering\nebk list ~/my-library --author \"Knuth\" --limit 20\n\n# Get statistics\nebk stats ~/my-library\n```\n\n### 3. Launch Web Interface\n\n```bash\n# Start web server (uses config defaults)\nebk serve ~/my-library\n\n# Custom port and host\nebk serve ~/my-library --port 8080 --host 127.0.0.1\n\n# Auto-open browser\nebk config set server.auto_open_browser true\nebk serve ~/my-library\n```\n\n### 4. AI-Powered Metadata Enrichment\n\n```bash\n# Configure LLM provider\nebk config set llm.provider ollama\nebk config set llm.model llama3.2\nebk config set llm.host localhost\n\n# Enrich library metadata using LLM\nebk enrich ~/my-library\n\n# Enrich with all features\nebk enrich ~/my-library --generate-tags --categorize --enhance-descriptions\n\n# Use remote GPU server\nebk enrich ~/my-library --host 192.168.1.100\n```\n\n---\n\n## Configuration\n\nebk uses a centralized configuration system stored at `~/.config/ebk/config.json`. This configuration file manages settings for LLM providers, web server, CLI defaults, and library preferences.\n\n### Configuration File Structure\n\n```json\n{\n \"llm\": {\n \"provider\": \"ollama\",\n \"model\": \"llama3.2\",\n \"host\": \"localhost\",\n \"port\": 11434,\n \"api_key\": null,\n \"temperature\": 0.7,\n \"max_tokens\": null\n },\n \"server\": {\n \"host\": \"0.0.0.0\",\n \"port\": 8000,\n \"auto_open_browser\": false,\n \"page_size\": 50\n },\n \"cli\": {\n \"verbose\": false,\n \"color\": true,\n \"page_size\": 50\n },\n \"library\": {\n \"default_path\": null\n }\n}\n```\n\n### Configuration Management\n\n```bash\n# Initialize configuration (creates default config file)\nebk config init\n\n# View current configuration\nebk config show\n\n# Edit configuration in your default editor\nebk config edit\n\n# Set specific values\nebk config set llm.provider ollama\nebk config set llm.model mistral\nebk config set server.port 8080\nebk config set library.default_path ~/my-library\n\n# Get specific value\nebk config get llm.model\n```\n\n### LLM Provider Configuration\n\nConfigure LLM providers for metadata enrichment:\n\n```bash\n# Local Ollama (default)\nebk config set llm.provider ollama\nebk config set llm.host localhost\nebk config set llm.port 11434\nebk config set llm.model llama3.2\n\n# Remote GPU server\nebk config set llm.host 192.168.1.100\n\n# OpenAI-compatible API (future)\nebk config set llm.provider openai\nebk config set llm.api_key sk-...\nebk config set llm.model gpt-4\n```\n\n### CLI Overrides\n\nAll commands support CLI arguments that override configuration defaults:\n\n```bash\n# These override config settings\nebk serve ~/library --port 9000 --host 127.0.0.1\nebk enrich ~/library --host 192.168.1.50 --model mistral\n```\n\n## CLI Usage\n\nebk uses [Typer](https://typer.tiangolo.com/) with [Rich](https://github.com/Textualize/rich) for a beautiful, colorized CLI experience.\n\n### General CLI Structure\n\n```bash\nebk --help # See all available commands\nebk <command> --help # See specific command usage\nebk --verbose <command> # Enable verbose output\n```\n\n### Database Commands\n\nCore library management with SQLAlchemy + SQLite backend:\n\n```bash\n# Initialize library\nebk init ~/my-library\n\n# Import books\nebk import book.pdf ~/my-library\nebk import ~/books/*.epub ~/my-library\nebk import-calibre ~/Calibre/Library --output ~/my-library\n\n# Search with advanced syntax\nebk search \"machine learning\" ~/my-library # Plain full-text search\nebk search \"title:Python rating:>=4\" ~/my-library # Field-specific with filters\nebk search \"author:Knuth format:pdf\" ~/my-library # Multiple criteria\nebk search \"tag:programming NOT java\" ~/my-library # Boolean operators\nebk search '\"deep learning\" language:en' ~/my-library # Phrase search with filter\n\n# List and filter\nebk list ~/my-library\nebk list ~/my-library --author \"Knuth\" --language en --limit 20\nebk list ~/my-library --format pdf --rating 4\n\n# Statistics\nebk stats ~/my-library\nebk stats ~/my-library --format json\n\n# Manage reading status\nebk rate ~/my-library <book-id> 5\nebk favorite ~/my-library <book-id>\nebk tag ~/my-library <book-id> --add \"must-read\" \"technical\"\n\n# Remove books\nebk purge ~/my-library --rating 1 --confirm\n```\n\n### Web Server\n\nLaunch FastAPI-based web interface:\n\n```bash\n# Start server (uses config defaults)\nebk serve ~/my-library\n\n# Custom host and port\nebk serve ~/my-library --host 127.0.0.1 --port 8080\n\n# Auto-open browser\nebk serve ~/my-library --auto-open\n\n# Configure defaults in config\nebk config set server.port 8080\nebk config set server.auto_open_browser true\n```\n\n### AI-Powered Features\n\nEnrich metadata using LLMs:\n\n```bash\n# Basic enrichment (uses config settings)\nebk enrich ~/my-library\n\n# Full enrichment\nebk enrich ~/my-library \\\n --generate-tags \\\n --categorize \\\n --enhance-descriptions \\\n --assess-difficulty\n\n# Enrich specific book\nebk enrich ~/my-library --book-id 42\n\n# Use remote GPU server\nebk enrich ~/my-library --host 192.168.1.100 --model mistral\n\n# Dry run (preview changes without saving)\nebk enrich ~/my-library --dry-run\n```\n\n### Configuration Management\n\nManage global configuration:\n\n```bash\n# Initialize configuration\nebk config init\n\n# View configuration\nebk config show\nebk config show --section llm\n\n# Edit in default editor\nebk config edit\n\n# Set values\nebk config set llm.model llama3.2\nebk config set server.port 8080\nebk config set library.default_path ~/books\n\n# Get values\nebk config get llm.model\n```\n\n### Export and Advanced Features\n\n```bash\n# Export library\nebk export html ~/my-library ~/library.html # Self-contained HTML with pagination\nebk export html ~/my-library ~/site/lib.html --copy --base-url /library # Copy files + covers\nebk export zip ~/my-library ~/backup.zip\nebk export json ~/my-library ~/metadata.json\n\n# Virtual libraries (filtered views)\nebk vlib create ~/my-library \"python-books\" --subject Python\nebk vlib list ~/my-library\n\n# Notes and annotations\nebk note add ~/my-library <book-id> \"Great chapter on algorithms\"\nebk note list ~/my-library <book-id>\n```\n\n---\n\n## Documentation\n\nComprehensive documentation is available at: **[https://queelius.github.io/ebk/](https://queelius.github.io/ebk/)**\n\n### Documentation Contents\n\n- **Getting Started**\n - [Installation](https://queelius.github.io/ebk/getting-started/installation/)\n - [Quick Start](https://queelius.github.io/ebk/getting-started/quickstart/)\n - [Configuration Guide](https://queelius.github.io/ebk/getting-started/configuration/)\n\n- **User Guide**\n - [CLI Reference](https://queelius.github.io/ebk/user-guide/cli/)\n - [Python API](https://queelius.github.io/ebk/user-guide/api/)\n - [LLM Features](https://queelius.github.io/ebk/user-guide/llm-features/)\n - [Web Server](https://queelius.github.io/ebk/user-guide/server/)\n - [Import/Export](https://queelius.github.io/ebk/user-guide/import-export/)\n - [Search & Query](https://queelius.github.io/ebk/user-guide/search/)\n\n- **Advanced Topics**\n - [Hugo Export](https://queelius.github.io/ebk/advanced/hugo-export/)\n - [Symlink DAG](https://queelius.github.io/ebk/advanced/symlink-dag/)\n - [Recommendations](https://queelius.github.io/ebk/advanced/recommendations/)\n - [Batch Operations](https://queelius.github.io/ebk/advanced/batch-operations/)\n\n- **Development**\n - [Architecture](https://queelius.github.io/ebk/development/architecture/)\n - [Contributing](https://queelius.github.io/ebk/development/contributing/)\n - [API Reference](https://queelius.github.io/ebk/development/api-reference/)\n\n---\n\n\n## Python API\n\nebk provides a comprehensive SQLAlchemy-based API for programmatic library management:\n\n```python\nfrom pathlib import Path\nfrom ebk.library_db import Library\n\n# Open or create a library\nlib = Library.open(Path(\"~/my-library\"))\n\n# Import books with automatic metadata extraction\nbook = lib.add_book(\n Path(\"book.pdf\"),\n metadata={\"title\": \"My Book\", \"creators\": [\"Author Name\"]},\n extract_text=True,\n extract_cover=True\n)\n\n# Fluent query interface\nresults = (lib.query()\n .filter_by_language(\"en\")\n .filter_by_author(\"Knuth\")\n .filter_by_subject(\"Algorithms\")\n .order_by(\"title\", desc=False)\n .limit(20)\n .all())\n\n# Full-text search (FTS5)\nresults = lib.search(\"machine learning\", limit=50)\n\n# Get book by ID\nbook = lib.get_book(42)\nprint(f\"{book.title} by {', '.join([a.name for a in book.authors])}\")\n\n# Update reading status\nlib.update_reading_status(book.id, \"reading\", progress=50, rating=4)\n\n# Add tags\nlib.add_tags(book.id, [\"must-read\", \"technical\"])\n\n# Get statistics\nstats = lib.stats()\nprint(f\"Total books: {stats['total_books']}\")\nprint(f\"Total authors: {stats['total_authors']}\")\nprint(f\"Languages: {', '.join(stats['languages'])}\")\n\n# Query with filters\nfrom ebk.db.models import Book, Author\nfrom sqlalchemy import and_\n\nbooks = lib.session.query(Book).join(Book.authors).filter(\n and_(\n Author.name.like(\"%Knuth%\"),\n Book.language == \"en\"\n )\n).all()\n\n# Always close when done\nlib.close()\n\n# Or use context manager\nwith Library.open(Path(\"~/my-library\")) as lib:\n results = lib.search(\"Python programming\")\n for book in results:\n print(book.title)\n```\n\n### AI-Powered Metadata Enrichment\n\n```python\nfrom ebk.ai.llm_providers.ollama import OllamaProvider\nfrom ebk.ai.metadata_enrichment import MetadataEnrichmentService\n\n# Initialize provider (local or remote)\nprovider = OllamaProvider.remote(\n host=\"192.168.1.100\",\n model=\"llama3.2\"\n)\n\nservice = MetadataEnrichmentService(provider)\n\nasync with provider:\n # Generate tags\n tags = await service.generate_tags(\n title=\"Introduction to Algorithms\",\n authors=[\"Cormen\", \"Leiserson\"],\n description=\"Comprehensive algorithms textbook\"\n )\n\n # Categorize\n categories = await service.categorize(\n title=\"Introduction to Algorithms\",\n subjects=[\"Algorithms\", \"Data Structures\"]\n )\n\n # Enhance description\n description = await service.enhance_description(\n title=\"Introduction to Algorithms\",\n text_sample=\"Chapter 1: The Role of Algorithms...\"\n )\n```\n\nSee the [CLAUDE.md](CLAUDE.md) file for architectural details and [API documentation](https://queelius.github.io/ebk/user-guide/api/) for complete reference.\n\n---\n\n## Contributing\n\nContributions are welcome! Here\u2019s how to get involved:\n\n1. **Fork the Repo** \n2. **Create a Branch** for your feature or fix\n3. **Commit & Push** your changes\n4. **Open a Pull Request** describing the changes\n\nWe appreciate code contributions, bug reports, and doc improvements alike.\n\n---\n\n## License\n\nDistributed under the [MIT License](https://github.com/queelius/ebk/blob/main/LICENSE).\n\n---\n\n## Integrations\n\nebk follows a modular architecture where the core library remains lightweight, with optional integrations available:\n\n### Streamlit Dashboard\n```bash\npip install ebk[streamlit]\nstreamlit run ebk/integrations/streamlit/app.py\n```\n\n### MCP Server (AI Assistants)\n```bash\npip install ebk[mcp]\n# Configure your AI assistant to use the MCP server\n```\n\n### Visualizations\n```bash\npip install ebk[viz]\n# Visualization tools will be available as a separate script\n# Documentation coming soon in integrations/viz/\n```\n\nSee the [Integrations Guide](integrations/README.md) for detailed setup instructions.\n\n---\n\n## Architecture\n\nebk is designed with a clean, layered architecture:\n\n1. **Core Library** (`ebk.library`): Fluent API for all operations\n2. **CLI** (`ebk.cli`): Typer-based commands using the fluent API\n3. **Import/Export** (`ebk.imports`, `ebk.exports`): Modular format support\n4. **Integrations** (`integrations/`): Optional add-ons (web UI, AI, viz)\n\nThis design ensures the core remains lightweight while supporting powerful extensions.\n\n---\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/queelius/ebk.git\ncd ebk\n\n# Create virtual environment\nmake venv\n\n# Install in development mode\nmake setup\n\n# Run tests\nmake test\n\n# Check coverage\nmake coverage\n```\n\n---\n\n## Stay Updated\n\n- **GitHub**: [https://github.com/queelius/ebk](https://github.com/queelius/ebk)\n- **Website**: [https://metafunctor.com](https://metafunctor.com)\n\n---\n\n## Support\n\n- **Issues**: [Open an Issue](https://github.com/queelius/ebk/issues) on GitHub\n- **Contact**: <lex@metafunctor.com>\n\n---\n\nHappy eBook managing! \ud83d\udcda\u2728\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight, extensible tool for managing eBook metadata",
"version": "0.3.2",
"project_urls": {
"Changelog": "https://github.com/queelius/ebk/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/queelius/ebk/wiki",
"Homepage": "https://github.com/queelius/ebk",
"Issues": "https://github.com/queelius/ebk/issues",
"Repository": "https://github.com/queelius/ebk.git"
},
"split_keywords": [
"ebook",
" metadata",
" library",
" books",
" management",
" calibre"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2610acec99c152f43bcede3a4420e33fb01cd476e44ad9d38188473e3736153f",
"md5": "55fd19ccacd2f7e1d015b41552911762",
"sha256": "fd9144cd1f39e9a1ab75b0506a3786325434f05b12eff822b1fad83000a8fafa"
},
"downloads": -1,
"filename": "ebk-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "55fd19ccacd2f7e1d015b41552911762",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 192290,
"upload_time": "2025-10-27T23:39:48",
"upload_time_iso_8601": "2025-10-27T23:39:48.756203Z",
"url": "https://files.pythonhosted.org/packages/26/10/acec99c152f43bcede3a4420e33fb01cd476e44ad9d38188473e3736153f/ebk-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "227ada692a97e14c4d5f9d813d9d60949d10aad76c3891f31319a56fa277ba3b",
"md5": "776567ebee54c69e0454c434f7a337cf",
"sha256": "21601254b7a0bf25b9f7a33dce1f11f90c69b109969a3d50dce77bff67394c70"
},
"downloads": -1,
"filename": "ebk-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "776567ebee54c69e0454c434f7a337cf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 225900,
"upload_time": "2025-10-27T23:39:49",
"upload_time_iso_8601": "2025-10-27T23:39:49.987478Z",
"url": "https://files.pythonhosted.org/packages/22/7a/da692a97e14c4d5f9d813d9d60949d10aad76c3891f31319a56fa277ba3b/ebk-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-27 23:39:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "queelius",
"github_project": "ebk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ebk"
}
JSON
