{"id":27813265,"url":"https://github.com/josefdc/librorecomiendadb","last_synced_at":"2026-04-20T10:32:53.718Z","repository":{"id":290542655,"uuid":"973938438","full_name":"josefdc/LibroRecomiendaDB","owner":"josefdc","description":"An AI-powered book recommendation system built with Python, Streamlit, SQLAlchemy, and LangChain/LangGraph. Features user reviews, Google Books API integration, and an admin panel.","archived":false,"fork":false,"pushed_at":"2025-04-29T10:15:34.000Z","size":507,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-01T12:02:17.422Z","etag":null,"topics":["langchain","langgraph","recommendation-system","streamlit"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/josefdc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-28T02:38:58.000Z","updated_at":"2025-04-29T10:15:38.000Z","dependencies_parsed_at":"2025-04-29T11:35:49.976Z","dependency_job_id":null,"html_url":"https://github.com/josefdc/LibroRecomiendaDB","commit_stats":null,"previous_names":["josefdc/librorecomiendadb"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/josefdc/LibroRecomiendaDB","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josefdc%2FLibroRecomiendaDB","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josefdc%2FLibroRecomiendaDB/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josefdc%2FLibroRecomiendaDB/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josefdc%2FLibroRecomiendaDB/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/josefdc","download_url":"https://codeload.github.com/josefdc/LibroRecomiendaDB/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/josefdc%2FLibroRecomiendaDB/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264963539,"owners_count":23690052,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["langchain","langgraph","recommendation-system","streamlit"],"created_at":"2025-05-01T12:01:31.138Z","updated_at":"2026-04-20T10:32:53.669Z","avatar_url":"https://github.com/josefdc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LibroRecomienda: Sistema de Recomendación de Libros con IA\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](/LICENSE)\n\n**Autor:** Jose Felipe Duarte \n**Fecha:** April 28, 2025\n\n---\n\n## Descripción General\n\nLibroRecomienda es una aplicación web interactiva diseñada como proyecto final. Su objetivo es proporcionar a los usuarios recomendaciones de libros personalizadas y explicables a través de una interfaz conversacional impulsada por un agente inteligente construido con LangGraph y modelos de lenguaje grande (LLMs). La aplicación permite explorar un catálogo de libros, leer y añadir reseñas, y dialogar con el agente para refinar las sugerencias.\n\nEl proyecto demuestra la integración de tecnologías modernas como Streamlit para la interfaz, SQLAlchemy y Alembic para la gestión de la base de datos (compatible con PostgreSQL y SQLite), y Langchain/LangGraph para la orquestación del agente conversacional.\n\n![Screenshot from 2025-04-27 21-40-19](https://github.com/user-attachments/assets/91f35090-d280-4768-bdc3-edc46423e341)\n\n\n---\n\n## Características Principales Implementadas\n\n* **Catálogo de Libros:**\n  * Visualización del catálogo completo en `streamlit_app/app.py`.\n  * Vista detallada de cada libro (imagen, autor, género, ISBN, descripción, rating promedio).\n  * Filtros y opciones de ordenamiento en la vista principal.\n* **Gestión de Usuarios:**\n  * Registro de nuevos usuarios (`crud_user.py`, `streamlit_app/app.py`).\n  * Autenticación (Login/Logout) (`streamlit_app/app.py`).\n  * Distinción de roles (Usuario / Administrador) basada en `ADMIN_EMAILS` en `config.py`.\n* **Gestión de Reseñas:**\n  * Los usuarios logueados pueden añadir reseñas (puntuación + comentario) a los libros (`crud_review.py`, `streamlit_app/app.py`).\n  * Visualización de reseñas existentes para cada libro (excluyendo las borradas lógicamente) (`crud_review.py`).\n  * Los usuarios pueden borrar (lógicamente) sus propias reseñas (`crud_review.py`, `streamlit_app/app.py`).\n  * Cálculo y actualización automática del rating promedio del libro al añadir/modificar/borrar reseñas (`crud_review.py`).\n* **Panel de Administración (Página Dedicada):** (`streamlit_app/pages/admin.py`)\n  * Acceso restringido a usuarios administradores.\n  * Vista para gestionar usuarios (listar usuarios registrados) (`crud_user.py`).\n  * Vista para gestionar reseñas (`crud_review.py`):\n    * Listar *todas* las reseñas (incluyendo activas y borradas).\n    * Filtrar reseñas por estado (Activas, Borradas).\n    * Opción para restaurar reseñas borradas lógicamente.\n    * Opción para eliminar reseñas permanentemente (con confirmación).\n* **Agente Conversacional (LangGraph):** (`streamlit_app/pages/chat.py`, `src/librorecomienda/agents/`)\n  * Interfaz de chat dedicada.\n  * Mantenimiento de memoria conversacional por sesión (`MemorySaver` en `graph.py`).\n  * Capacidad de llamar a herramientas para interactuar con la base de datos (`search_books`, `get_book_details` en `tools.py`).\n  * Generación de recomendaciones basada en la conversación.\n  * Flujo conversacional básico gestionado por LangGraph (`graph.py`).\n\n---\n\n## Diagrama Entidad-Relación (ERD)\n\nA continuación se muestra el modelo conceptual de la base de datos utilizada en el proyecto.\n\n**Descripción de Entidades y Relaciones:**\n\n* **User:** (`users` table in `models/user.py`)\n  * `id` [PK]: Identificador único del usuario.\n  * `email` [Unique]: Dirección de correo electrónico (usada para login).\n  * `hashed_password`: Contraseña almacenada de forma segura.\n  * `is_active`: Indicador de si la cuenta está activa (default: True).\n  * `created_at`, `updated_at`: Marcas de tiempo automáticas.\n* **Book:** (`books` table in `models/book.py`)\n  * `id` [PK]: Identificador único del libro.\n  * `title`: Título del libro.\n  * `author`: Autor del libro.\n  * `genre`: Género principal.\n  * `description`: Sinopsis o descripción.\n  * `average_rating`: Puntuación promedio calculada de las reseñas.\n  * `cover_image_url`: URL de la imagen de portada.\n  * `isbn` [Unique]: ISBN del libro.\n* **Review:** (`reviews` table in `models/review.py`)\n  * `id` [PK]: Identificador único de la reseña.\n  * `rating`: Puntuación dada por el usuario (1-5).\n  * `comment`: Comentario opcional.\n  * `created_at`: Fecha y hora de creación.\n  * `is_deleted`: Indicador de borrado lógico (default: False).\n  * `user_id` [FK -\u003e User.id]: Usuario que escribió la reseña.\n  * `book_id` [FK -\u003e Book.id]: Libro al que pertenece la reseña.\n* **Relaciones:**\n  * Un `User` puede escribir muchas `Review`s (1-N).\n  * Un `Book` puede tener muchas `Review`s (1-N).\n  * Una `Review` pertenece exactamente a un `User` y a un `Book`.\n\n![graphviz](https://github.com/user-attachments/assets/5691b998-786f-485a-804c-e4e49b74c20e)\n\n---\n\n## Tecnologías Utilizadas\n\n* **Backend \u0026 ORM:** Python 3.11+, SQLAlchemy 2.x\n* **Migraciones DB:** Alembic\n* **Base de Datos:** PostgreSQL (recomendado) / SQLite (para desarrollo/pruebas)\n* **Framework Web UI:** Streamlit\n* **Agente IA:** Langchain, LangGraph\n* **Modelos LLM:** OpenAI GPT-4o-mini (configurable vía `ChatOpenAI` en `graph.py`)\n* **Validación de Datos:** Pydantic v2\n* **Gestión de Dependencias:** uv (basado en `pyproject.toml`)\n* **Testing:** Pytest\n* **Generación de Datos Falsos:** Faker (`scripts/generate_fake_data.py`)\n* **Variables de Entorno:** python-dotenv, Pydantic-Settings\n\n---\n\n## Estructura del Proyecto\n\n```text\nLibroRecomienda/\n├── .env             # (No versionado) Variables de entorno (DATABASE_URL, API Keys)\n├── .venv/           # Entorno virtual (creado por uv o venv)\n├── alembic.ini      # Configuración de Alembic\n├── migrations/      # Scripts de migración de Alembic\n│   ├── versions/    # Archivos de migración específicos\n│   └── ...\n├── scripts/         # Scripts útiles\n│   ├── generate_fake_data.py # Genera usuarios y reseñas falsas\n│   └── populate_db.py      # (Opcional) Script para poblar libros inicialmente\n├── src/\n│   └── librorecomienda/ # Código fuente principal del paquete Python\n│       ├── agents/    # Lógica del agente LangGraph (state, tools, graph)\n│       ├── core/      # Configuración central (config.py), seguridad (security.py)\n│       ├── crud/      # Funciones CRUD (crud_book.py, crud_review.py, crud_user.py)\n│       ├── db/        # Configuración de la sesión de SQLAlchemy (session.py)\n│       ├── models/    # Modelos SQLAlchemy (book.py, review.py, user.py)\n│       ├── schemas/   # Modelos Pydantic (review.py, user.py)\n│       └── __init__.py\n├── streamlit_app/   # Código de la interfaz de usuario Streamlit\n│   ├── app.py       # Página principal (catálogo, login)\n│   └── pages/       # Páginas adicionales (admin.py, chat.py)\n├── tests/           # Pruebas con Pytest\n│   ├── crud/        # Pruebas para las funciones CRUD\n│   ├── models/      # Pruebas para los modelos SQLAlchemy\n│   └── conftest.py  # Fixtures de configuración de pruebas (ej. sesión de BD)\n├── pyproject.toml   # Definición del proyecto y dependencias para uv/pip\n├── README.md        # Este archivo\n├── uv.lock          # Archivo de bloqueo de dependencias de uv\n└── ...              # Otros archivos (ej. .gitignore, collect_snapshot.py)\n```\n\n---\n\n## Instalación y Configuración\n\nSigue estos pasos para poner en marcha el proyecto localmente:\n\n1. **Prerrequisitos:**\n   * Python \u003e= 3.11\n   * Un servidor de base de datos PostgreSQL (recomendado) o SQLite instalado.\n   * `uv` instalado globalmente (`pip install uv` o sigue las [instrucciones oficiales](https://github.com/astral-sh/uv)).\n   * Git.\n\n2. **Clonar el Repositorio**\n\n   ```bash\n   git clone https://github.com/josefdc/LibroRecomienda.git\n   cd LibroRecomienda\n   ```\n\n3. **Crear y Activar Entorno Virtual (usando uv):**\n\n   ```bash\n   uv venv\n   source .venv/bin/activate  # Linux/macOS\n   # .venv\\Scripts\\activate  # Windows (cmd/powershell)\n   ```\n\n4. **Instalar Dependencias (usando uv):**\n   * Instala las dependencias principales y de desarrollo definidas en `pyproject.toml`:\n\n     ```bash\n     uv pip install -e .[dev]\n     ```\n   * El flag `-e .` instala el proyecto `librorecomienda` en modo editable. `[dev]` instala las dependencias de desarrollo (como `pytest`, `faker`).\n\n5. **Variables de Entorno:**\n   * Crea un archivo llamado `.env` en la raíz del proyecto (`LibroRecomienda/.env`).\n   * Añade las siguientes variables, ajustando los valores según tu configuración:\n\n     ```dotenv\n     # --- Base de Datos ---\n     # Ejemplo para PostgreSQL local (asegúrate que la BD 'librorecomienda_db' exista)\n     DATABASE_URL=postgresql+psycopg2://user:password@localhost:5432/librorecomienda_db\n\n     # Ejemplo para SQLite (creará un archivo librorecomienda.db en la raíz)\n     # DATABASE_URL=sqlite:///./librorecomienda.db\n\n     # --- APIs Externas ---\n     # API Key para el LLM (ej. OpenAI)\n     OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n     # (Opcional) API Key para Google Books (si implementas esa funcionalidad)\n     # GOOGLE_BOOKS_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n     # --- Configuración de la Aplicación ---\n     # Lista de emails de administradores separados por coma (sin espacios alrededor)\n     ADMIN_EMAILS=admin@example.com,tu_email@dominio.com\n\n     # Entorno (opcional, puede ser usado para configuraciones específicas)\n     # ENVIRONMENT=development\n     ```\n   * **Importante:** Si usas PostgreSQL, asegúrate de que la base de datos (`librorecomienda_db` en el ejemplo) exista en tu servidor antes de continuar. Si usas SQLite, el archivo se creará automáticamente.\n\n6. **Migraciones de Base de Datos:**\n   * Aplica las migraciones para crear/actualizar las tablas en la base de datos configurada en `.env`:\n\n     ```bash\n     alembic upgrade head\n     ```\n\n---\n\n## Ejecución\n\n1. **Poblar Base de Datos (Opcional pero Recomendado):**\n   * Para generar usuarios y reseñas falsas para probar la aplicación:\n\n     ```bash\n     python scripts/generate_fake_data.py\n     ```\n   * *(Nota: El script `populate_db.py` podría necesitar ser adaptado o usado si tienes una fuente específica para cargar libros iniciales).*\n\n2. **Iniciar la Aplicación Streamlit:**\n\n   ```bash\n   streamlit run streamlit_app/app.py\n   ```\n   * Abre la URL local que te indique Streamlit (generalmente `http://localhost:8501`) en tu navegador.\n\n---\n\n## Ejecución de Pruebas\n\n* Asegúrate de tener las dependencias de desarrollo instaladas (`uv pip install -e .[dev]`).\n* Desde la raíz del proyecto (`LibroRecomienda/`), ejecuta:\n\n  ```bash\n  pytest\n  ```\n* Las pruebas usarán una base de datos SQLite en memoria (`sqlite:///:memory:`) definida en `tests/conftest.py` para no interferir con tu base de datos principal.\n\n---\n\n## Contribuciones\n\nLas contribuciones son bienvenidas. Por favor, lee nuestras [Directrices de Contribución](CONTRIBUTING.md) y nuestro [Código de Conducta](CODE_OF_CONDUCT.md).\n\n---\n\n## Licencia\n\nEste proyecto se distribuye bajo la licencia [MIT](LICENSE). Ver el archivo `LICENSE` para más detalles.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosefdc%2Flibrorecomiendadb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjosefdc%2Flibrorecomiendadb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjosefdc%2Flibrorecomiendadb/lists"}