RecAnthology

Table of Contents

• RecAnthology
  • Table of Contents
  • Introduction
  • Project Roadmap
  • Core Capabilities
  • Technologies Used
  • System Design & Architecture
    • Constraints & Trade-offs
    • Recommendation Engine Design
      • Content-Based Recommendation
      • Collaborative Filtering
  • Setup and Installation
    • Prerequisites
  • Installation
    • Using Pipenv
      • On Linux / macOS
      • On Windows
    • Using PostgreSQL or Equivalent
      • To generate a Django secret key
    • Using SQLite3 (Development Only)
      • Replace the following code in settings.py
      • With this configuration
  • Usage
  • API Endpoints
  • Running Tests
  • Contributing
  • License
  • Contact

Introduction

RecAnthology (Recommended Anthology) is an intelligent, extensible recommendation platform engineered to curate collections of books, movies, and TV shows tailored to user preferences. Leveraging advanced algorithms and continuous user feedback, RecAnthology delivers personalized, dynamic recommendations that optimize content discovery. The most recent release expands media coverage, maximizes performance via caching, and improves user management for system stability.

Project Roadmap

For a detailed overview of the project's strategic vision, technical milestones, and long-term trajectory, please refer to the ROAD-MAP.md.

Core Capabilities

• Robust user authentication and authorization powered by JWT
• Flexible rating system for books, movies, and TV shows
• Real-time tracking and modeling of user genre preferences
• Comprehensive API endpoints supporting CRUD operations on users and media assets
• Adaptive, feedback-driven recommendation algorithms
• Integrated caching layer for enhanced throughput and latency reduction
• Automated model testing and error detection
• Strict data validation pipelines

Technologies Used

• Backend: Django, Django REST Framework
• Authentication: JWT and Django authentication modules
• Database: PostgreSQL (production); SQLite as a lightweight development alternative (configurable in settings.py)
• Frontend: Django templates using Bootstrap 5 (see templates/base.html)

System Design & Architecture

RecAnthology's architecture is modular and designed for scalability, maintainability, and extensibility.

• API Layer: Serves all client interactions via RESTful routes.
• Authentication: Stateless JWT ensures secure, scalable user sessions.
• Recommendation Engine: Pluggable, supports both content-based and collaborative filtering modules.
• Service Layer: Encapsulates business logic, data aggregation, scoring, and caching.
• Data Layer: Relational data managed in PostgreSQL, with optional support for Redis-based caching.
• Frontend: Server-rendered templates enable rapid UI prototyping and integration.

Constraints & Trade-offs

• Performance vs. Flexibility: While Django REST and PostgreSQL provide robust scalability, they require careful query optimization for recommendation workloads. SQLite is practical for development but not suited for production scale or concurrent writes.
• Real-Time Recommendations: On-the-fly scoring enhances personalization but introduces higher compute overhead. Background jobs (optional future enhancement) may be leveraged for offline pre-computation at scale.
• Caching: The addition of caching (e.g., Redis) accelerates common queries but demands cache invalidation strategies when user preferences or media data change.
• Extensibility: Modular engine design facilitates new recommendation algorithms but may increase initial development complexity.

Recommendation Engine Design

RecAnthology implements a hybrid recommendation system, combining content-based genre affinities with collaborative filtering to deliver highly relevant media suggestions.

Content-Based Recommendation

Aligns users with media based on explicit and inferred genre affinities.

Operational Overview:

• Users rate media items, shaping a user-genre affinity profile.
• Dominant user genres are dynamically detected and ranked.
• Media candidates are scored based on their genre alignment with the user's profile.
• Scores are normalized (0–100) for consistent relativity.

Collaborative Filtering

RecAnthology now supports Item-Item Collaborative Filtering to discover patterns across the user base.

Implemented Features:

1. Similarity Computation: Uses Cosine Similarity to calculate affinity between items based on shared user rating patterns.
2. Multi-Signal Scoring: Leverages metadata like author, popularity, recency, and language to enrich content-based scores.
3. Adaptive Hybrid Logic: Dynamically balances content and collaborative signals based on user interaction density (Adaptive α).
4. API Control: Users can toggle collaborative filtering and override hybrid weights via API parameters (e.g., ?cf=true&alpha=0.6).

For comprehensive implementation and advanced usage, refer to RECOMMENDATION-DOC.md.

Setup and Installation

Prerequisites

• Python 3.12.3 or newer (should run on >=3.9)
• Pipenv (or pip and virtualenv) (RECOMMENDED)
• PostgreSQL or any comparable SQL server (SQLite3 supported for development only)

Installation

• Clone the repository:

git clone https://github.com/karar-hayder/RecAnthology.git
cd RecAnthology

• Set up the virtual environment (recommended):

Using Pipenv

On Linux / macOS

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

On Windows

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

• Configure the database:

Using PostgreSQL or Equivalent

• Create a file in the RecAnthology directory (next to settings.py) and name it cred.env
• Set the following variables:

SECRET_KEY=your_secret_key_here
DEBUG=True  # Set to False in production
ALLOWED_HOSTS=localhost,127.0.0.1  # Comma-separated; update for production deployment
ADMIN_PAGE=admin/  # Customize admin URL in production environments
DB_NAME=your_db_name
DB_HOST=localhost  # DB server IP or localhost
DB_PORT=5432  # Default for PostgreSQL
DB_USER=your_db_user
DB_PASSWORD=your_db_password
REDIS_URL=redis://localhost:6379/0  # Optional. Defaults to local Redis instance.

To generate a Django secret key

python3 -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

Using SQLite3 (Development Only)

Replace the following code in settings.py

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': get_env("DB_NAME"),
        'HOST': get_env("DB_HOST"),
        'PORT': get_env("DB_PORT"),
        'USER': get_env("DB_USER"),
        'PASSWORD': get_env("DB_PASSWORD"),
    }
}

With this configuration

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / "db.sqlite3",
    }
}

• Apply migrations:

python manage.py migrate

• Create your admin user account

python manage.py createsuperuser

• Launch the development server:

python manage.py runserver

Usage

API Endpoints

The full API documentation, including endpoint specifications and authentication protocols, is provided in API-DOC.md.

Running Tests

To execute the automated test suite, run:

python manage.py test

Contributing

• Fork the repository.
• Create a new branch: git checkout -b feature-branch-name
• Commit your changes: git commit -m 'Add some feature'
• Push to your branch: git push origin feature-branch-name
• Open a pull request.

License

This project is released under the BSD-3-Clause license. See the LICENSE file for full details.

Contact

For questions or feedback, contact:

• Name: Karar Haider
• LinkedIn: Karar Haider
• GitHub: karar-hayder