---
title: SAMUEL
sdk: docker
emoji: 🚀
colorFrom: red
colorTo: green
---

# Samuel - El Confidente Digital Argentino

Esta es la implementación completa de "Samuel", un compañero de IA diseñado como un artefacto cultural digital para el público argentino. La arquitectura está pensada para ser robusta, escalable y desplegable en entornos de contenedores de recursos limitados y con sistemas de archivos de solo lectura, como Hugging Face Spaces.

## Visión del Producto

"Samuel" es el amigo porteño, culto, piola y canchero. Su personalidad es una amalgama de Borges, el Indio Solari y un pibe de barrio. No es un asistente; es un par. Su propósito es hacer que el usuario se sienta visto, entendido y acompañado de una manera que se sienta más real y valiosa que la interacción humana promedio.

## Arquitectura y Stack Tecnológico

- **Backend**: Python 3.11+ con FastAPI.
- **Comunicación en Tiempo Real**: WebSockets.
- **Base de Datos**: SQLite (gestionada con SQLAlchemy ORM) para persistir usuarios y memorias.
- **Autenticación**: Tokens JWT seguros (email/contraseña).
- **Motor de IA (Cerebro)**: Google Gemini API (`gemini-1.5-flash-latest`).
- **Motor de Voz (Alma)**: Coqui TTS, con el modelo cargado en memoria al inicio.
- **Frontend**: HTML5, CSS3, y JavaScript (Vanilla), servido directamente desde el backend.
- **Contenerización**: Docker, con configuración específica para evitar errores de permisos en sistemas de solo lectura.

## Cómo Desplegar y Ejecutar

La aplicación está diseñada para ser ejecutada dentro de un contenedor Docker.

### Prerrequisitos

- Docker instalado.
- Una clave de API de Google Gemini.

### Pasos para la Ejecución

1.  **Clonar el Repositorio**

    ```bash
    git clone <URL_DEL_REPOSITORIO>
    cd <NOMBRE_DEL_REPOSITORIO>
    ```

2.  **Crear el Archivo de Secretos (`.env`)**

    Crea un archivo llamado `.env` en la raíz del proyecto. Este archivo **no** debe ser subido al repositorio (`.gitignore` ya lo excluye). Contendrá los secretos necesarios para la ejecución.

    ```
    # .env
    GEMINI_API_KEY="TU_API_KEY_DE_GEMINI_AQUI"
    JWT_SECRET_KEY="UNA_CLAVE_SECRETA_LARGA_Y_COMPLEJA_PARA_JWT"
    ```

    -   Reemplaza `TU_API_KEY_DE_GEMINI_AQUI` con tu clave real.
    -   Reemplaza `UNA_CLAVE_SECRETA_LARGA_Y_COMPLEJA_PARA_JWT` por una cadena de texto aleatoria y segura. Puedes generar una con `openssl rand -hex 32`.

3.  **Construir la Imagen de Docker**

    Desde la raíz del proyecto, ejecuta el siguiente comando. Esto leerá el `Dockerfile`, instalará las dependencias del `requirements.txt` y empaquetará la aplicación.

    ```bash
    docker build -t samuel-app .
    ```

4.  **Ejecutar el Contenedor**

    Ahora, ejecuta la imagen que acabas de construir. El comando `--env-file .env` inyecta las variables de entorno desde tu archivo de secretos al contenedor.

    ```bash
    docker run -p 8000:8000 --env-file .env samuel-app
    ```

5.  **Acceder a Samuel**

    Abre tu navegador web y dirígete a `http://localhost:8000`.

    Serás recibido por la pantalla de registro/login. Una vez dentro, comenzarás el "Ritual de Iniciación" antes de acceder al santuario digital.