# ChromaticBot Backend - FastAPI API backend para ordenar �lbumes de Spotify por an�lisis crom�tico. ## Refactorizaci�n a FastAPI Este proyecto ha sido refactorizado de Flask a **FastAPI 0.121.0**, compatible con **Python 3.12**. ### Cambios Principales - � Migraci�n completa de Flask a FastAPI - � Inyecci�n de dependencias para MongoDB - � Anotaciones de tipo modernas de Python 3.12 (`list`, `dict`, `tuple`) - � Validaci�n de datos con Pydantic v2 - � Tipado fuerte con modelos Pydantic en respuestas - � Manejo de excepciones HTTP con HTTPException - � Documentaci�n autom�tica OpenAPI/Swagger - � Mejor estructura de proyecto con routers y servicios - � Endpoint legacy para compatibilidad con frontend existente ## Estructura del Proyecto ``` ChromaticBotBackEnd/ � app/ � � __init__.py � � main.py # Aplicaci�n FastAPI principal � � models/ � � � __init__.py � � � schemas.py # Modelos Pydantic � � routers/ � � � __init__.py � � � chromatic.py # Endpoints de an�lisis crom�tico � � � health.py # Health check � � services/ � � __init__.py � � database.py # Servicio MongoDB con DI � � spotify_api.py # Cliente Spotify API � � chromatic_logic.py # L�gica de an�lisis crom�tico � requirements.txt � Dockerfile � .env ``` ## Instalaci�n ### 1. Requisitos - Python 3.12+ - PDM (Python Dependency Manager) - MongoDB (opcional, para cach�) ### 2. Instalar PDM ```bash # macOS/Linux curl -sSL https://pdm-project.org/install-pdm.py | python3 - # Windows (Invoke-WebRequest -Uri https://pdm-project.org/install-pdm.py -UseBasicParsing).Content | py - # O usando pip pip install --user pdm ``` ### 3. Instalar Dependencias ```bash # Instalar todas las dependencias del proyecto pdm install # O si prefieres usar un virtualenv tradicional pdm venv create pdm use -f .venv pdm install ``` ### 4. Configurar Variables de Entorno Crear archivo `.env`: ```env # MongoDB (opcional - para cach� de an�lisis crom�tico) DB_URL=mongodb://localhost:27017 DB_NAME=chromatic_db DB_COLLECTION=albums # Spotify API (si es necesario) SPOTIPY_CLIENT_ID=tu_client_id SPOTIPY_CLIENT_SECRET=tu_client_secret ``` ## Ejecuci�n ### Desarrollo (con hot-reload) ```bash # Usando PDM (recomendado) pdm run uvicorn app.main:app --reload --host 0.0.0.0 --port 8080 # O agregar un script en pyproject.toml y ejecutar pdm run start # O activar el ambiente virtual y ejecutar directamente eval $(pdm venv activate) uvicorn app.main:app --reload --host 0.0.0.0 --port 8080 ``` ### Producci�n ```bash # Con PDM pdm run uvicorn app.main:app --host 0.0.0.0 --port 8080 --workers 4 # O con el ambiente activado eval $(pdm venv activate) uvicorn app.main:app --host 0.0.0.0 --port 8080 --workers 4 ``` ### Docker ```bash # Build docker build -t chromatic-backend . # Run docker run -p 8080:8080 --env-file .env chromatic-backend ``` ## Endpoints ### Documentaci�n Interactiva - **Swagger UI**: http://localhost:8080/docs - **ReDoc**: http://localhost:8080/redoc - **OpenAPI JSON**: http://localhost:8080/openapi.json ### API Endpoints #### 1. POST `/get_albums_by_chromaticity` (Legacy - compatibilidad) Obtener �lbumes ordenados por cromaticidad. **Request:** ```json { "token": "spotify_access_token", "timeRevision": "1m", "quantitySongs": 50 } ``` **Par�metros:** - `token`: Token de acceso de Spotify - `timeRevision`: Per�odo de tiempo - `"1m"`: �ltimo mes (short_term) - `"6m"`: �ltimos 6 meses (medium_term) - `"a"`: Todo el tiempo (long_term) - `quantitySongs`: Cantidad de canciones (1-50) **Response:** ```json [ { "album": "Album Name", "image": "https://...", "colors": [[255, 0, 0], [0, 255, 0], ...], "dominant": [128, 64, 32], "color_names": ["red", "green", ...], "colorfulness": 0.75, "songs": [ { "name": "Song Name", "artists": "Artist 1, Artist 2" } ] } ] ``` #### 2. POST `/chromatic/albums` (Nuevo endpoint) Mismo que el anterior, pero con ruta RESTful moderna. #### 3. GET `/health` Health check del servicio. **Response:** ```json { "status": "healthy", "service": "ChromaticBotBackEnd" } ``` ## Caracter�sticas de FastAPI ### Validaci�n Autom�tica FastAPI valida autom�ticamente: - Tipos de datos - Valores m�nimos/m�ximos - Campos requeridos ### Documentaci�n Autom�tica La documentaci�n OpenAPI se genera autom�ticamente a partir de: - Modelos Pydantic - Anotaciones de tipo - Docstrings ### Inyecci�n de Dependencias MongoDB se inyecta como dependencia: ```python async def endpoint(database: MusicDatabase = Depends(get_database)) -> ResponseModel: # La base de datos se configura autom�ticamente pass ``` ### Manejo de Excepciones HTTP ```python from fastapi import HTTPException # Lanzar excepciones HTTP raise HTTPException(status_code=401, detail="Invalid token") # Capturar y re-lanzar try: result = service.process() except HTTPException: raise # Re-lanzar HTTPException except Exception as e: raise HTTPException(status_code=500, detail=f"Error: {str(e)}") ``` ### Type Hints Modernos (Python 3.12) Se usan anotaciones nativas en lugar de `typing`: ```python # � Moderno (Python 3.12+) def process(data: list[dict[str, any]]) -> tuple[int, str]: pass @router.get("/endpoint") async def endpoint() -> ResponseModel: return ResponseModel(...) # L Antiguo (no usado) from typing import List, Dict, Any, Tuple def process(data: List[Dict[str, Any]]) -> Tuple[int, str]: pass ``` ## Migraci�n de C�digo Antiguo ### Endpoints Flask � FastAPI **Antes (Flask):** ```python @app.route("/endpoint", methods=["POST"]) def endpoint(): body = request.get_json() if "field" not in body: return Response("Error", status=400) return Response(json.dumps(data), status=200) ``` **Despu�s (FastAPI):** ```python @router.post("/endpoint") async def endpoint(request: RequestModel) -> ResponseModel: # Validaci�n autom�tica por Pydantic # Excepciones HTTP para errores return ResponseModel(...) # Serializaci�n autom�tica ``` ### Archivos Movidos - `main.py` � `app/main.py` - `database.py` � `app/services/database.py` - `spotifyApiConsumer.py` � `app/services/spotify_api.py` - `chromaticLogic.py` � `app/services/chromatic_logic.py` ## Testing Probar los endpoints: ```bash # Health check curl http://localhost:8080/health # Get albums curl -X POST http://localhost:8080/get_albums_by_chromaticity \ -H "Content-Type: application/json" \ -d '{ "token": "your_spotify_token", "timeRevision": "1m", "quantitySongs": 10 }' ``` ## Compatibilidad � El endpoint legacy `/get_albums_by_chromaticity` mantiene 100% de compatibilidad con el frontend existente. ## Tecnolog�as - **FastAPI 0.121.0** - Framework web moderno y r�pido - **Uvicorn** - ASGI server de alto rendimiento - **Pydantic v2** - Validaci�n de datos y serializaci�n - **PyMongo** - Cliente MongoDB - **ColorThief** - An�lisis crom�tico de im�genes - **NumPy** - Procesamiento num�rico - **Pillow** - Procesamiento de im�genes - **Python 3.12** - Con anotaciones de tipo nativas - **PDM** - Modern Python package and dependency manager ## Gesti�n de Dependencias con PDM Este proyecto usa **PDM (Python Dependency Manager)** en lugar de pip/requirements.txt tradicional. ### Ventajas de PDM - **Resoluci�n de dependencias determinista**: Lock file (`pdm.lock`) garantiza instalaciones reproducibles - **Est�ndar PEP 582**: No requiere activar virtualenvs manualmente - **Velocidad**: Cach� de paquetes y resoluci�n paralela de dependencias - **Compatibilidad PEP 621**: Usa `pyproject.toml` est�ndar para metadatos del proyecto - **Gesti�n de versiones de Python**: Maneja m�ltiples versiones de Python f�cilmente - **Scripts personalizados**: Define comandos r�pidos en `pyproject.toml` ### Comandos Comunes PDM ```bash # Instalar dependencias pdm install # Agregar nueva dependencia pdm add fastapi # Agregar dependencia de desarrollo pdm add -d pytest # Actualizar dependencias pdm update # Actualizar una dependencia espec�fica pdm update fastapi # Ejecutar scripts definidos pdm run start # Desarrollo con hot-reload pdm run prod # Producci�n con 4 workers pdm run dev # Desarrollo local # Listar dependencias pdm list # Crear ambiente virtual pdm venv create # Activar ambiente virtual eval $(pdm venv activate) # Exportar a requirements.txt (para compatibilidad) pdm export -f requirements -o requirements.txt ``` ### Migraci�n desde requirements.txt Si ten�as un proyecto con `requirements.txt`, PDM lo migra autom�ticamente: ```bash # PDM detecta requirements.txt y lo importa pdm init # O importar manualmente pdm import requirements.txt ``` ## Licencia [Tu licencia aqu�]