# 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**
```bash
git clone https://git.mrbamm.xyz/Dewey_Orcale/dewey-oracle.git
cd dewey-oracle
```

2. **Create virtual environment**
```bash
python3 -m venv venv
source venv/bin/activate
```

3. **Install dependencies**
```bash
pip install -r requirements.txt
```

4. **Configure environment**
```bash
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY
```

5. **Run the application**
```bash
python main.py
```

6. **Access the web interface**
- Open http://localhost:8000
- Register first user account
- Enter your Audiobookshelf server URL and API token
- Sync your library and generate recommendations!

### Production Deployment (systemd)

```bash
./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:

```bash
# 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.