dewey-oracle/README.md

Dewy Oracle

Version 0.1 (Beta) - AI-powered book recommendations for Audiobookshelf

A self-hosted web application that syncs with your Audiobookshelf server to track listening history and provide personalized book recommendations using Google Gemini AI.

✨ Features

Core Features

• 🔄 Audiobookshelf Sync - Automatic sync of listening history and progress
• 🤖 AI Recommendations - Google Gemini-powered book suggestions based on your tastes
• 📊 Reading Analytics - Track books finished, hours listened, streaks, and genres
• ⭐ Book Ratings - Rate and track your favorite audiobooks
• 👥 Multi-User Support - Individual accounts with separate libraries
• 🎨 *arr-Style Dark Theme - Professional UI matching Sonarr/Radarr aesthetic
• 🔐 Admin Panel - User management, password changes, and settings

What's New in v0.1

• Complete dark theme redesign with sidebar navigation
• Admin user creation and password management
• Fixed author name extraction from Audiobookshelf API
• Accurate hours calculation using actual audiobook duration
• Working book rating system
• Local cover image caching

🚀 Quick Start

Prerequisites

• Python 3.12+
• Audiobookshelf server with API access
• Google Gemini API key

Installation

1. Clone the repository

   git clone https://git.mrbamm.xyz/Dewey_Orcale/dewey-oracle.git
   cd dewey-oracle
   

2. Create virtual environment

   python3 -m venv venv
   source venv/bin/activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Configure environment

   cp .env.example .env
   # Edit .env and add your GEMINI_API_KEY
   

5. Run the application

   python main.py
   

6. Access the web interface

7. Open http://localhost:8000

8. Register first user account

9. Enter your Audiobookshelf server URL and API token

10. Sync your library and generate recommendations!

Production Deployment (systemd)

./setup-service.sh

📖 Usage

1. Register - Create your account with Audiobookshelf credentials
2. Sync - Click "Sync with Audiobookshelf" to import your library
3. Get Recommendations - Click "Generate New Recommendations"
4. View Stats - Check your reading log for analytics and insights
5. Rate Books - Rate finished books to improve future recommendations

🛠️ Configuration

Environment Variables

Variable	Required	Default	Description
GEMINI_API_KEY	Yes	-	Google Gemini API key
SECRET_KEY	No	Auto-generated	Session encryption key
DATABASE_URL	No	sqlite:///./absrecommend.db	Database path
HOST	No	0.0.0.0	Server host
PORT	No	8000	Server port

Per-User Settings

• Audiobookshelf server URL
• Audiobookshelf API token (encrypted in database)

🏗️ Development

Branching Strategy (v0.1+)

Starting with version 0.1, we use feature branches:

# Create feature branch
git checkout -b feature/your-feature-name

# Make changes and commit
git add .
git commit -m "Description"

# Push to remote
git push origin feature/your-feature-name

# Merge to master when ready

Tech Stack

• Backend: FastAPI, Python 3.12, SQLAlchemy (async)
• Frontend: Jinja2, Vanilla JS, Chart.js
• Database: SQLite (aiosqlite)
• AI: Google Gemini 2.5 Flash
• External API: Audiobookshelf REST API

📝 Version History

v0.1 (Beta) - January 2026

• Initial beta release
• Multi-user authentication system
• AI-powered recommendations with Gemini
• Reading log with statistics and charts
• Admin panel with user management
• Dark theme with sidebar navigation
• Book rating system
• Local cover caching

🤝 Contributing

This project uses feature branches. Create a branch for your changes and submit via pull request.

📄 License

See repository for license information.

🔗 Links

• Repository: https://git.mrbamm.xyz/Dewey_Orcale/dewey-oracle
• Issues: Use Gogs issue tracker

---

Note: This is a beta release (v0.1). Some features may have rough edges. Please report issues via the Gogs issue tracker.