Actualizo la app

.dockerignore

@@ -0,0 +1,15 @@
+.git
+.gitignore
+.pytest_cache
+__pycache__/
+**/__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.db
+venv/
+.venv/
+.env
+alembic_smoke.db
+EDA_For_All_Tree.ipynb
+EDA_For_All_Tree_clean.ipynb

.env.example

@@ -0,0 +1,28 @@
+ORACULO_APP_NAME=Oraculo Adult Income API
+ORACULO_APP_VERSION=2.0.0
+ORACULO_ENVIRONMENT=development
+ORACULO_DEBUG=false
+
+ORACULO_DATABASE_URL=sqlite:///./oraculo.db
+ORACULO_DATABASE_ECHO=false
+ORACULO_AUTO_CREATE_TABLES=true
+ORACULO_AUTO_SEED_ADMIN=true
+ORACULO_SEED_ADMIN_EMAIL=admin@example.com
+ORACULO_SEED_ADMIN_PASSWORD=ChangeMe!12345
+ORACULO_SEED_ADMIN_NAME=Administrator
+
+ORACULO_MODEL_PATH=app/ml/pipeline_produccion.pkl
+
+ORACULO_JWT_SECRET_KEY=replace-this-with-a-long-random-secret-at-least-32-chars
+ORACULO_JWT_ALGORITHM=HS256
+ORACULO_ACCESS_TOKEN_EXPIRE_MINUTES=60
+
+ORACULO_ALLOWED_HOSTS=localhost,127.0.0.1,*.hf.space,*.huggingface.co
+ORACULO_CORS_ALLOW_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
+
+ORACULO_MAX_REQUEST_SIZE_BYTES=32768
+ORACULO_RATE_LIMIT_ENABLED=true
+ORACULO_RATE_LIMIT_REQUESTS=60
+ORACULO_RATE_LIMIT_WINDOW_SECONDS=60
+
+ORACULO_DOCS_ENABLED=true

.gitignore

@@ -0,0 +1,124 @@
+# ==========================================
+# OS / File Explorer
+# ==========================================
+.DS_Store
+Thumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+
+# ==========================================
+# Editors / IDEs
+# ==========================================
+.idea/
+.vscode/
+*.code-workspace
+
+# ==========================================
+# Python
+# ==========================================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.python-version
+
+# ==========================================
+# Virtual Environments
+# ==========================================
+venv/
+.venv/
+env/
+ENV/
+
+# ==========================================
+# Environment / Secrets
+# ==========================================
+.env
+.env.local
+.env.*.local
+!.env.example
+
+# ==========================================
+# Packaging / Build
+# ==========================================
+build/
+dist/
+site/
+.eggs/
+*.egg
+*.egg-info/
+pip-wheel-metadata/
+
+# ==========================================
+# Testing / Coverage / Type Checking
+# ==========================================
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.hypothesis/
+.tox/
+.nox/
+.mypy_cache/
+.pyre/
+.ruff_cache/
+
+# ==========================================
+# Jupyter
+# ==========================================
+.ipynb_checkpoints/
+
+# ==========================================
+# Logs / Runtime Files
+# ==========================================
+*.log
+logs/
+*.pid
+*.pid.lock
+*.out
+*.err
+
+# ==========================================
+# Local Databases / Storage
+# ==========================================
+*.db
+*.db-shm
+*.db-wal
+*.sqlite
+*.sqlite3
+instance/
+
+# ==========================================
+# Alembic / Migration Local Noise
+# ==========================================
+alembic_smoke.db
+
+# ==========================================
+# Local ML / Notebook Outputs
+# Keep the canonical model artifact tracked if needed.
+# ==========================================
+mlops_activos/
+artifacts/
+outputs/
+reports/
+tmp/
+temp/
+*.tmp
+*.bak
+*.orig
+
+# ==========================================
+# Hugging Face / Cache / Misc
+# ==========================================
+.cache/
+.huggingface/
+
+# ==========================================
+# Frontend / Node (safe to keep even if unused)
+# ==========================================
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*

Dockerfile

@@ -0,0 +1,31 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    ORACULO_ENVIRONMENT=staging \
+    ORACULO_DOCS_ENABLED=true
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN useradd --create-home --uid 1000 user
+
+WORKDIR /app
+
+COPY requirements.txt /app/requirements.txt
+
+RUN pip install --upgrade pip \
+    && pip install --no-cache-dir -r /app/requirements.txt
+
+COPY . /app
+
+RUN mkdir -p /data \
+    && chown -R user:user /app /data
+
+USER user
+
+EXPOSE 7860
+
+CMD ["sh", "-c", "alembic upgrade head && uvicorn app.main:app --host 0.0.0.0 --port 7860"]

README.md

@@ -1,11 +1,330 @@
 ---
-title: Oraculo Api
-emoji: 🏆
-colorFrom: indigo
-colorTo: gray
+title: Oraculo Adult Income API
+emoji: 🚀
+colorFrom: green
+colorTo: blue
 sdk: docker
+app_port: 7860
+base_path: /docs
 pinned: false
-license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Oraculo Adult Income API
+
+API REST profesional para inferencia del dataset Adult Census Income, reconstruida con enfoque de clean code, seguridad por capas, pruebas agresivas y contrato estable entre notebook y producción.
+
+## Objetivo
+
+Esta API resuelve tres problemas reales del proyecto:
+
+1. Exponer inferencia de modelo con un contrato HTTP limpio, autenticado y auditable.
+2. Blindar el salto entre `EDA_For_All_Tree_clean.ipynb` y el artefacto `pipeline_produccion.pkl`.
+3. Dejar una base escalable para crecer a más endpoints, más usuarios y despliegue en Render.
+
+## Stack elegido
+
+Tecnologías aplicadas en la implementación final:
+
+- `FastAPI`: framework principal, OpenAPI/Swagger, validación HTTP y alto rendimiento.
+- `Python`: lenguaje base del servicio, notebook y pipeline.
+- `Pydantic v2`: DTOs, validaciones estrictas, aliases y contratos de entrada/salida.
+- `SQLAlchemy 2.0`: ORM principal y capa de persistencia.
+- `Alembic`: migraciones versionadas de base de datos.
+- `SQLite` por defecto y `PostgreSQL` listo por `DATABASE_URL`: desarrollo local y despliegue escalable.
+- `JWT + bcrypt`: autenticación stateless y hashing de contraseñas.
+- `Swagger/OpenAPI`: documentación viva de endpoints.
+- `Pytest + TestClient`: pruebas HTTP, seguridad, errores y dominio.
+- `Uvicorn`: servidor ASGI para local y producción.
+- `Starlette middlewares`: CORS, GZip, Trusted Hosts, request id, límites de payload, rate limiting básico.
+- `joblib + LightGBM/sklearn pipeline`: artefacto de inferencia.
+
+Tecnología no seleccionada deliberadamente:
+
+- `SQLModel`: no se usó en esta versión porque superpone responsabilidades con SQLAlchemy + Pydantic. Para este nivel de control y separación entre ORM y DTOs, SQLAlchemy 2.0 fue una mejor decisión.
+
+Tecnologías adicionales que faltaban en la lista original y sí son importantes:
+
+- `pydantic-settings` para configuración por entorno.
+- `bcrypt` para hashing directo y estable.
+- `httpx/TestClient` para pruebas HTTP.
+- `Request ID / security headers / rate limiting` para endurecimiento operativo.
+
+## Arquitectura
+
+La API quedó organizada por capas:
+
+- `app/main.py`: app factory, lifespan, middlewares y bootstrap.
+- `app/api/`: routers, versionado y dependencias.
+- `app/core/`: configuración, seguridad, middleware, logging, errores.
+- `app/db/`: base ORM, sesión, modelos, repositorios, seeds.
+- `app/services/`: reglas de negocio.
+- `app/ml/`: carga del artefacto y contrato con el pipeline.
+- `app/schemas/`: DTOs HTTP.
+- `alembic/`: migraciones.
+- `tests/`: pruebas HTTP, seguridad, esquemas y modelo.
+
+## Funcionalidades incluidas
+
+- Registro y login con JWT.
+- Endpoint autenticado de predicción.
+- Historial de predicciones por usuario.
+- Consulta puntual por `prediction_id`.
+- Health checks `live` y `ready`.
+- Seeds de administrador por variables de entorno.
+- Manejador de errores unificado.
+- Headers de seguridad y request id.
+- Protección por tamaño máximo de payload.
+- Rate limiting in-memory.
+- Compatibilidad con el artefacto actual del modelo.
+
+## Endpoints
+
+### Salud
+
+- `GET /`
+- `GET /api/v1/health/live`
+- `GET /api/v1/health/ready`
+
+### Autenticación
+
+- `POST /api/v1/auth/register`
+- `POST /api/v1/auth/login`
+- `GET /api/v1/auth/me`
+
+### Predicciones
+
+- `POST /api/v1/predictions`
+- `GET /api/v1/predictions`
+- `GET /api/v1/predictions/{prediction_id}`
+
+## Seguridad aplicada
+
+### OWASP / API hardening
+
+- JWT firmado y validado.
+- Contraseñas hasheadas con `bcrypt`.
+- DTOs con `extra="forbid"` para bloquear campos sorpresa.
+- Validación fuerte de tipos, rangos y longitudes.
+- `TrustedHostMiddleware` para rechazar hosts no permitidos.
+- Headers de seguridad (`CSP`, `X-Frame-Options`, `nosniff`, `Cache-Control`).
+- Límite de tamaño de payload.
+- Rate limiting básico por IP.
+- Errores controlados sin exponer stacktrace al cliente.
+- Persistencia auditada de cada predicción.
+
+### Vulnerabilidades orientadas a LLM
+
+Tu lista incluía amenazas como `many-shot jailbreaking`, `indirect prompt injection`, `context hijacking`, `context poisoning`, `lost in the middle` y `context overflow`.
+
+Punto importante:
+
+- Esta API no expone un endpoint LLM conversacional, así que esas amenazas no aplican de forma directa al plano HTTP actual.
+- Sí aplican al notebook y a cualquier automatización futura que use prompts, agentes o generación asistida.
+
+Mitigaciones prácticas adoptadas o recomendadas:
+
+- Tratar todo texto externo como entrada no confiable.
+- No ejecutar prompts del usuario dentro del backend de inferencia.
+- Mantener separación entre features del modelo y texto libre.
+- Exportar el artefacto desde el notebook con validación previa.
+- Generar `model_manifest.json` junto con el `.pkl` para trazabilidad.
+- Evitar que la API acepte instrucciones ejecutables o plantillas arbitrarias.
+
+## Contrato Notebook -> API
+
+El notebook limpio `EDA_For_All_Tree_clean.ipynb` quedó orientado a producción:
+
+- Exporta `pipeline_produccion.pkl`.
+- Valida el pipeline con una muestra real antes de serializar.
+- Genera `model_manifest.json`.
+- Reúne artefactos serializables y modelos de forma explícita.
+
+El backend, a través de `ModelManager` y `PipelineProduccionMLOps`, puede:
+
+- Cargar el artefacto.
+- Reconstruir artefactos faltantes si el notebook exportó algo incompleto.
+- Leer el `model_manifest.json` cuando exista.
+
+## Base de datos
+
+Entidades incluidas:
+
+- `users`
+- `prediction_logs`
+
+Persistencia incluida:
+
+- usuarios autenticados
+- historial de predicciones
+- payload original
+- payload normalizado
+- request id
+- latencia
+- versión del modelo
+- hash del payload
+
+## Migraciones Alembic
+
+Inicialización incluida:
+
+- `alembic.ini`
+- `alembic/env.py`
+- migración inicial `initial_api_schema`
+
+Comandos útiles:
+
+```bash
+alembic upgrade head
+alembic revision --autogenerate -m "descripcion"
+alembic downgrade -1
+```
+
+## Seeds
+
+Si defines:
+
+- `ORACULO_SEED_ADMIN_EMAIL`
+- `ORACULO_SEED_ADMIN_PASSWORD`
+- `ORACULO_AUTO_SEED_ADMIN=true`
+
+la aplicación crea un administrador por bootstrap si no existe.
+
+## Configuración
+
+Variables principales:
+
+- `ORACULO_DATABASE_URL`
+- `ORACULO_MODEL_PATH`
+- `ORACULO_JWT_SECRET_KEY`
+- `ORACULO_ALLOWED_HOSTS`
+- `ORACULO_CORS_ALLOW_ORIGINS`
+- `ORACULO_RATE_LIMIT_REQUESTS`
+- `ORACULO_RATE_LIMIT_WINDOW_SECONDS`
+- `ORACULO_MAX_REQUEST_SIZE_BYTES`
+
+Toma como base el archivo `.env.example`.
+
+## Ejecución local
+
+```bash
+python -m venv venv
+venv\Scripts\activate
+pip install -r requirements.txt
+alembic upgrade head
+uvicorn app.main:app --reload
+```
+
+Swagger:
+
+- `http://127.0.0.1:8000/docs`
+
+## Tests
+
+La suite prueba:
+
+- esquemas
+- autenticación
+- autorización
+- predicción
+- historial
+- aislamiento de datos entre usuarios
+- health checks
+- middlewares de seguridad
+- payload demasiado grande
+- rate limit
+- modelo real (`pipeline_produccion.pkl`)
+
+Ejecución:
+
+```bash
+venv\Scripts\pytest -q
+```
+
+Estado actual de la suite:
+
+- `33 passed`
+
+## Despliegue en Render
+
+Recomendación:
+
+1. Subir el proyecto con `requirements.txt`.
+2. Configurar `Start Command`:
+
+```bash
+alembic upgrade head && uvicorn app.main:app --host 0.0.0.0 --port $PORT
+```
+
+3. Definir variables de entorno:
+
+- `ORACULO_ENVIRONMENT=production`
+- `ORACULO_DATABASE_URL=<postgres-url>`
+- `ORACULO_JWT_SECRET_KEY=<secret-largo>`
+- `ORACULO_ALLOWED_HOSTS=<tu-dominio-onrender>`
+- `ORACULO_DOCS_ENABLED=false`
+
+4. Subir `pipeline_produccion.pkl` y, cuando exista, `model_manifest.json`.
+
+## Despliegue en Hugging Face Spaces
+
+Este repositorio ya quedó preparado para un `Docker Space`.
+
+Archivos listos para eso:
+
+- `Dockerfile`
+- `.dockerignore`
+- front matter de Spaces al inicio de este `README.md`
+
+Pasos:
+
+1. Crea un nuevo Space en Hugging Face.
+2. Selecciona `Docker` como SDK.
+3. Sube este proyecto completo.
+4. En `Settings > Variables and secrets`, configura como mínimo:
+
+- `ORACULO_JWT_SECRET_KEY`
+- `ORACULO_SEED_ADMIN_EMAIL`
+- `ORACULO_SEED_ADMIN_PASSWORD`
+- `ORACULO_ALLOWED_HOSTS`
+
+5. Si quieres persistencia real para SQLite, usa almacenamiento persistente y define:
+
+```bash
+ORACULO_DATABASE_URL=sqlite:////data/oraculo.db
+```
+
+Si no activas almacenamiento persistente, la base será efímera y se reiniciará con el Space.
+
+Notas importantes para Spaces:
+
+- Swagger abrirá en `/docs` porque el Space usa `base_path: /docs`.
+- El contenedor escucha en `7860`, que es el puerto esperado por el Space.
+- Si quieres ocultar Swagger más adelante, cambia `ORACULO_DOCS_ENABLED=false`.
+- El modelo `pipeline_produccion.pkl`, `adult.csv` y el código backend deben permanecer en el repositorio o en el contexto del contenedor.
+
+## Qué falta para una versión todavía más dura
+
+Si quieres llevarla más arriba todavía, las siguientes mejoras son naturales:
+
+- rate limiting distribuido con Redis
+- refresh tokens
+- roles más finos (`admin`, `analyst`, `service`)
+- observabilidad con Prometheus / OpenTelemetry
+- CI con lint, type-check y cobertura
+- separación formal entre API pública e interna
+- Postgres nativo en desarrollo
+
+## Resumen ejecutivo
+
+Esta versión ya no es una API improvisada alrededor de un notebook. Ahora tienes una base con:
+
+- arquitectura limpia
+- autenticación
+- persistencia
+- auditoría
+- migraciones
+- seguridad razonable
+- tests HTTP exhaustivos
+- contrato más sano entre notebook y producción
+
+Es una base seria para seguir construyendo.

alembic.ini

@@ -0,0 +1,149 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts.
+# this is typically a path given in POSIX (e.g. forward slashes)
+# format, relative to the token %(here)s which refers to the location of this
+# ini file
+script_location = %(here)s/alembic
+
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
+# for all available tokens
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+# Or organize into date-based subdirectories (requires recursive_version_locations = true)
+# file_template = %%(year)d/%%(month).2d/%%(day).2d_%%(hour).2d%%(minute).2d_%%(second).2d_%%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+# defaults to the current working directory.  for multiple paths, the path separator
+# is defined by "path_separator" below.
+prepend_sys_path = .
+
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the tzdata library which can be installed by adding
+# `alembic[tz]` to the pip requirements.
+# string value is passed to ZoneInfo()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to <script_location>/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "path_separator"
+# below.
+# version_locations = %(here)s/bar:%(here)s/bat:%(here)s/alembic/versions
+
+# path_separator; This indicates what character is used to split lists of file
+# paths, including version_locations and prepend_sys_path within configparser
+# files such as alembic.ini.
+# The default rendered in new alembic.ini files is "os", which uses os.pathsep
+# to provide os-dependent path splitting.
+#
+# Note that in order to support legacy alembic.ini files, this default does NOT
+# take place if path_separator is not present in alembic.ini.  If this
+# option is omitted entirely, fallback logic is as follows:
+#
+# 1. Parsing of the version_locations option falls back to using the legacy
+#    "version_path_separator" key, which if absent then falls back to the legacy
+#    behavior of splitting on spaces and/or commas.
+# 2. Parsing of the prepend_sys_path option falls back to the legacy
+#    behavior of splitting on spaces, commas, or colons.
+#
+# Valid values for path_separator are:
+#
+# path_separator = :
+# path_separator = ;
+# path_separator = space
+# path_separator = newline
+#
+# Use os.pathsep. Default configuration used for new projects.
+path_separator = os
+
+# set to 'true' to search source files recursively
+# in each "version_locations" directory
+# new in Alembic version 1.10
+# recursive_version_locations = false
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+# database URL.  This is consumed by the user-maintained env.py script only.
+# other means of configuring database URLs may be customized within the env.py
+# file.
+sqlalchemy.url = sqlite:///./oraculo.db
+
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# lint with attempts to fix using "ruff" - use the module runner, against the "ruff" module
+# hooks = ruff
+# ruff.type = module
+# ruff.module = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Alternatively, use the exec runner to execute a binary found on your PATH
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Logging configuration.  This is also consumed by the user-maintained
+# env.py script only.
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

alembic/README

@@ -0,0 +1 @@
+Generic single-database configuration.

alembic/env.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+from app.core.config import get_settings
+from app.db import models  # noqa: F401
+from app.db.base import Base
+
+config = context.config
+settings = get_settings()
+config.set_main_option("sqlalchemy.url", settings.database_url)
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        compare_type=True,
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            compare_type=True,
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

alembic/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, Sequence[str], None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}

alembic/versions/33e682013d1c_initial_api_schema.py

@@ -0,0 +1,71 @@
+"""initial_api_schema
+
+Revision ID: 33e682013d1c
+Revises: 
+Create Date: 2026-04-11 14:36:06.659737
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '33e682013d1c'
+down_revision: Union[str, Sequence[str], None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('users',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('email', sa.String(length=255), nullable=False),
+    sa.Column('full_name', sa.String(length=255), nullable=False),
+    sa.Column('password_hash', sa.String(length=255), nullable=False),
+    sa.Column('role', sa.String(length=32), nullable=False),
+    sa.Column('is_active', sa.Boolean(), nullable=False),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_users'))
+    )
+    op.create_index(op.f('ix_users_email'), 'users', ['email'], unique=True)
+    op.create_table('prediction_logs',
+    sa.Column('id', sa.String(length=36), nullable=False),
+    sa.Column('user_id', sa.String(length=36), nullable=False),
+    sa.Column('request_id', sa.String(length=64), nullable=False),
+    sa.Column('ip_address', sa.String(length=64), nullable=False),
+    sa.Column('label', sa.String(length=16), nullable=False),
+    sa.Column('probability', sa.Float(), nullable=False),
+    sa.Column('latency_ms', sa.Float(), nullable=False),
+    sa.Column('model_version', sa.String(length=64), nullable=False),
+    sa.Column('payload_hash', sa.String(length=64), nullable=False),
+    sa.Column('input_payload', sa.JSON(), nullable=False),
+    sa.Column('normalized_payload', sa.JSON(), nullable=False),
+    sa.Column('notes', sa.Text(), nullable=True),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=False),
+    sa.ForeignKeyConstraint(['user_id'], ['users.id'], name=op.f('fk_prediction_logs_user_id_users')),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_prediction_logs'))
+    )
+    op.create_index(op.f('ix_prediction_logs_label'), 'prediction_logs', ['label'], unique=False)
+    op.create_index(op.f('ix_prediction_logs_payload_hash'), 'prediction_logs', ['payload_hash'], unique=False)
+    op.create_index(op.f('ix_prediction_logs_request_id'), 'prediction_logs', ['request_id'], unique=False)
+    op.create_index(op.f('ix_prediction_logs_user_id'), 'prediction_logs', ['user_id'], unique=False)
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f('ix_prediction_logs_user_id'), table_name='prediction_logs')
+    op.drop_index(op.f('ix_prediction_logs_request_id'), table_name='prediction_logs')
+    op.drop_index(op.f('ix_prediction_logs_payload_hash'), table_name='prediction_logs')
+    op.drop_index(op.f('ix_prediction_logs_label'), table_name='prediction_logs')
+    op.drop_table('prediction_logs')
+    op.drop_index(op.f('ix_users_email'), table_name='users')
+    op.drop_table('users')
+    # ### end Alembic commands ###

app/api/__init__.py

@@ -0,0 +1,3 @@
+from app.api.router import router
+
+__all__ = ["router"]

app/api/dependencies.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from collections.abc import Generator
+
+from fastapi import Depends, Request
+from sqlalchemy.orm import Session
+
+from app.core.config import Settings
+from app.core.exceptions import AuthorizationError
+from app.core.security import bearer_scheme, decode_access_token, extract_bearer_token
+from app.db.models import User
+from app.db.repositories import PredictionRepository, UserRepository
+from app.db.session import yield_session
+from app.ml.model_manager import ModelManager
+from app.services import AuthService, HealthService, PredictionService
+
+
+def get_settings(request: Request) -> Settings:
+    return request.app.state.settings
+
+
+def get_model_manager(request: Request) -> ModelManager:
+    return request.app.state.model_manager
+
+
+def get_db_session(request: Request) -> Generator[Session, None, None]:
+    yield from yield_session(request.app.state.session_factory)
+
+
+def get_user_repository(session: Session = Depends(get_db_session)) -> UserRepository:
+    return UserRepository(session)
+
+
+def get_prediction_repository(session: Session = Depends(get_db_session)) -> PredictionRepository:
+    return PredictionRepository(session)
+
+
+def get_auth_service(
+    settings: Settings = Depends(get_settings),
+    user_repository: UserRepository = Depends(get_user_repository),
+) -> AuthService:
+    return AuthService(user_repository=user_repository, settings=settings)
+
+
+def get_prediction_service(
+    model_manager: ModelManager = Depends(get_model_manager),
+    prediction_repository: PredictionRepository = Depends(get_prediction_repository),
+) -> PredictionService:
+    return PredictionService(
+        model_manager=model_manager,
+        prediction_repository=prediction_repository,
+    )
+
+
+def get_health_service(
+    settings: Settings = Depends(get_settings),
+    model_manager: ModelManager = Depends(get_model_manager),
+) -> HealthService:
+    return HealthService(settings=settings, model_manager=model_manager)
+
+
+def get_current_user(
+    credentials=Depends(bearer_scheme),
+    settings: Settings = Depends(get_settings),
+    auth_service: AuthService = Depends(get_auth_service),
+) -> User:
+    token = extract_bearer_token(credentials)
+    token_payload = decode_access_token(token, settings)
+    user = auth_service.get_user(token_payload.sub)
+    if not user.is_active:
+        raise AuthorizationError("Inactive users cannot access this resource.")
+    return user
+
+
+def get_current_admin_user(current_user: User = Depends(get_current_user)) -> User:
+    if current_user.role != "admin":
+        raise AuthorizationError("Administrator privileges are required.")
+    return current_user

app/api/router.py

@@ -0,0 +1,6 @@
+from fastapi import APIRouter
+
+from app.api.v1.router import router as v1_router
+
+router = APIRouter()
+router.include_router(v1_router)

app/api/v1/__init__.py

@@ -0,0 +1,3 @@
+from app.api.v1.router import router
+
+__all__ = ["router"]

app/api/v1/endpoints/__init__.py

@@ -0,0 +1 @@
+# Package marker for API endpoints.

app/api/v1/endpoints/auth.py

@@ -0,0 +1,29 @@
+from fastapi import APIRouter, Depends, status
+
+from app.api.dependencies import get_auth_service, get_current_user
+from app.db.models import User
+from app.schemas.auth import LoginRequest, RegisterRequest, TokenResponse, UserResponse
+from app.services.auth import AuthService
+
+router = APIRouter(prefix="/auth", tags=["Authentication"])
+
+
+@router.post("/register", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
+def register(
+    payload: RegisterRequest,
+    auth_service: AuthService = Depends(get_auth_service),
+) -> UserResponse:
+    return auth_service.register(payload)
+
+
+@router.post("/login", response_model=TokenResponse)
+def login(
+    payload: LoginRequest,
+    auth_service: AuthService = Depends(get_auth_service),
+) -> TokenResponse:
+    return auth_service.login(payload)
+
+
+@router.get("/me", response_model=UserResponse)
+def me(current_user: User = Depends(get_current_user)) -> UserResponse:
+    return UserResponse.model_validate(current_user)

app/api/v1/endpoints/health.py

@@ -0,0 +1,21 @@
+from fastapi import APIRouter, Depends
+from sqlalchemy.orm import Session
+
+from app.api.dependencies import get_db_session, get_health_service
+from app.schemas.health import LiveHealthResponse, ReadyHealthResponse
+from app.services.health import HealthService
+
+router = APIRouter(prefix="/health", tags=["Health"])
+
+
+@router.get("/live", response_model=LiveHealthResponse)
+def live(service: HealthService = Depends(get_health_service)) -> LiveHealthResponse:
+    return service.live()
+
+
+@router.get("/ready", response_model=ReadyHealthResponse)
+def ready(
+    service: HealthService = Depends(get_health_service),
+    session: Session = Depends(get_db_session),
+) -> ReadyHealthResponse:
+    return service.ready(session)

app/api/v1/endpoints/predictions.py

@@ -0,0 +1,61 @@
+from fastapi import APIRouter, Depends, Query, Request, status
+
+from app.api.dependencies import get_current_user, get_prediction_service, get_settings
+from app.core.config import Settings
+from app.db.models import User
+from app.schemas.prediction import (
+    PredictionDetailResponse,
+    PredictionInput,
+    PredictionListResponse,
+    PredictionLabel,
+)
+from app.services.prediction import PredictionService
+
+router = APIRouter(prefix="/predictions", tags=["Predictions"])
+
+
+@router.post("", response_model=PredictionDetailResponse, status_code=status.HTTP_201_CREATED)
+def create_prediction(
+    payload: PredictionInput,
+    request: Request,
+    current_user: User = Depends(get_current_user),
+    prediction_service: PredictionService = Depends(get_prediction_service),
+) -> PredictionDetailResponse:
+    return prediction_service.predict(
+        payload=payload,
+        user=current_user,
+        request_id=request.state.request_id,
+        client_ip=request.state.client_ip,
+    )
+
+
+@router.get("", response_model=PredictionListResponse)
+def list_predictions(
+    skip: int = Query(default=0, ge=0),
+    limit: int = Query(default=20, ge=1, le=100),
+    label: PredictionLabel | None = Query(default=None),
+    min_probability: float | None = Query(default=None, ge=0.0, le=1.0),
+    current_user: User = Depends(get_current_user),
+    prediction_service: PredictionService = Depends(get_prediction_service),
+    settings: Settings = Depends(get_settings),
+) -> PredictionListResponse:
+    safe_limit = min(limit, settings.prediction_history_max_limit)
+    return prediction_service.list_predictions(
+        user=current_user,
+        skip=skip,
+        limit=safe_limit,
+        label=label,
+        min_probability=min_probability,
+    )
+
+
+@router.get("/{prediction_id}", response_model=PredictionDetailResponse)
+def get_prediction(
+    prediction_id: str,
+    current_user: User = Depends(get_current_user),
+    prediction_service: PredictionService = Depends(get_prediction_service),
+) -> PredictionDetailResponse:
+    return prediction_service.get_prediction(
+        prediction_id=prediction_id,
+        user=current_user,
+    )

app/api/v1/router.py

@@ -0,0 +1,10 @@
+from fastapi import APIRouter
+
+from app.api.v1.endpoints.auth import router as auth_router
+from app.api.v1.endpoints.health import router as health_router
+from app.api.v1.endpoints.predictions import router as predictions_router
+
+router = APIRouter(prefix="/api/v1")
+router.include_router(health_router)
+router.include_router(auth_router)
+router.include_router(predictions_router)

app/core/config.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+from typing import Literal
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_prefix="ORACULO_",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    app_name: str = "Oraculo Adult Income API"
+    app_version: str = "2.0.0"
+    environment: Literal["local", "development", "test", "staging", "production"] = "development"
+    debug: bool = False
+
+    api_v1_prefix: str = "/api/v1"
+    docs_enabled: bool = True
+    openapi_url: str = "/openapi.json"
+    docs_url: str = "/docs"
+    redoc_url: str = "/redoc"
+
+    database_url: str = "sqlite:///./oraculo.db"
+    database_echo: bool = False
+    auto_create_tables: bool = True
+    auto_seed_admin: bool = True
+    seed_admin_email: str | None = None
+    seed_admin_password: str | None = None
+    seed_admin_name: str = "Administrator"
+
+    model_path: str = "app/ml/pipeline_produccion.pkl"
+
+    jwt_secret_key: str = "change-me-in-production"
+    jwt_algorithm: str = "HS256"
+    access_token_expire_minutes: int = 60
+
+    allowed_hosts: list[str] = Field(
+        default_factory=lambda: [
+            "localhost",
+            "127.0.0.1",
+            "testserver",
+            "*.hf.space",
+            "*.huggingface.co",
+        ]
+    )
+    cors_allow_origins: list[str] = Field(
+        default_factory=lambda: ["http://localhost:3000", "http://127.0.0.1:3000"]
+    )
+
+    max_request_size_bytes: int = 32_768
+    rate_limit_enabled: bool = True
+    rate_limit_requests: int = 60
+    rate_limit_window_seconds: int = 60
+    rate_limit_exempt_paths: list[str] = Field(
+        default_factory=lambda: [
+            "/",
+            "/docs",
+            "/redoc",
+            "/openapi.json",
+            "/api/v1/health/live",
+            "/api/v1/health/ready",
+        ]
+    )
+    security_headers_enabled: bool = True
+
+    prediction_history_default_limit: int = 20
+    prediction_history_max_limit: int = 100
+
+    @field_validator("allowed_hosts", "cors_allow_origins", "rate_limit_exempt_paths", mode="before")
+    @classmethod
+    def _split_csv_values(cls, value: str | list[str]) -> list[str]:
+        if isinstance(value, list):
+            return value
+        if not value:
+            return []
+        return [item.strip() for item in value.split(",") if item.strip()]
+
+    @property
+    def base_dir(self) -> Path:
+        return Path(__file__).resolve().parents[2]
+
+    @property
+    def resolved_model_path(self) -> Path:
+        model_path = Path(self.model_path)
+        if model_path.is_absolute():
+            return model_path
+        return self.base_dir / model_path
+
+    @property
+    def is_production(self) -> bool:
+        return self.environment == "production"
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

app/core/error_handlers.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+from app.core.exceptions import AppError
+
+logger = logging.getLogger("oraculo_api.errors")
+
+
+def build_error_payload(
+    request: Request,
+    *,
+    code: str,
+    message: str,
+    detail: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    request_id = getattr(request.state, "request_id", None)
+    return {
+        "error": {
+            "code": code,
+            "message": message,
+            "detail": detail or {},
+            "request_id": request_id,
+        }
+    }
+
+
+def register_error_handlers(app: FastAPI) -> None:
+    @app.exception_handler(AppError)
+    async def handle_app_error(request: Request, exc: AppError) -> JSONResponse:
+        payload = build_error_payload(request, code=exc.code, message=exc.message, detail=exc.detail)
+        return JSONResponse(status_code=exc.status_code, content=payload)
+
+    @app.exception_handler(RequestValidationError)
+    async def handle_validation_error(request: Request, exc: RequestValidationError) -> JSONResponse:
+        payload = build_error_payload(
+            request,
+            code="validation_error",
+            message="Request validation failed.",
+            detail={"errors": exc.errors()},
+        )
+        return JSONResponse(status_code=422, content=payload)
+
+    @app.exception_handler(HTTPException)
+    async def handle_http_exception(request: Request, exc: HTTPException) -> JSONResponse:
+        detail = exc.detail if isinstance(exc.detail, dict) else {"reason": exc.detail}
+        payload = build_error_payload(
+            request,
+            code="http_error",
+            message="HTTP error.",
+            detail=detail,
+        )
+        return JSONResponse(status_code=exc.status_code, content=payload, headers=exc.headers)
+
+    @app.exception_handler(Exception)
+    async def handle_unexpected_error(request: Request, exc: Exception) -> JSONResponse:
+        logger.exception("Unhandled error: %s", exc)
+        payload = build_error_payload(
+            request,
+            code="internal_server_error",
+            message="Unexpected internal error.",
+        )
+        return JSONResponse(status_code=500, content=payload)

app/core/exceptions.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class AppError(Exception):
+    message: str
+    status_code: int = 400
+    code: str = "app_error"
+    detail: dict[str, Any] = field(default_factory=dict)
+
+
+class BadRequestError(AppError):
+    def __init__(self, message: str, detail: dict[str, Any] | None = None) -> None:
+        super().__init__(message=message, status_code=400, code="bad_request", detail=detail or {})
+
+
+class AuthenticationError(AppError):
+    def __init__(self, message: str = "Authentication failed.") -> None:
+        super().__init__(message=message, status_code=401, code="authentication_error")
+
+
+class AuthorizationError(AppError):
+    def __init__(self, message: str = "You are not allowed to access this resource.") -> None:
+        super().__init__(message=message, status_code=403, code="authorization_error")
+
+
+class ResourceNotFoundError(AppError):
+    def __init__(self, resource_name: str, resource_id: str) -> None:
+        super().__init__(
+            message=f"{resource_name} '{resource_id}' was not found.",
+            status_code=404,
+            code="resource_not_found",
+            detail={"resource_name": resource_name, "resource_id": resource_id},
+        )
+
+
+class ConflictError(AppError):
+    def __init__(self, message: str, detail: dict[str, Any] | None = None) -> None:
+        super().__init__(message=message, status_code=409, code="conflict", detail=detail or {})
+
+
+class RateLimitExceededError(AppError):
+    def __init__(self, retry_after_seconds: int) -> None:
+        super().__init__(
+            message="Rate limit exceeded. Please retry later.",
+            status_code=429,
+            code="rate_limit_exceeded",
+            detail={"retry_after_seconds": retry_after_seconds},
+        )
+
+
+class ServiceUnavailableError(AppError):
+    def __init__(self, message: str = "Service temporarily unavailable.") -> None:
+        super().__init__(message=message, status_code=503, code="service_unavailable")
+
+
+class ModelInferenceError(AppError):
+    def __init__(self, message: str = "Model inference failed.") -> None:
+        super().__init__(message=message, status_code=500, code="model_inference_error")

app/core/logging.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import logging
+import logging.config
+
+from app.core.config import Settings
+
+
+def configure_logging(settings: Settings) -> None:
+    level = "DEBUG" if settings.debug else "INFO"
+    logging.config.dictConfig(
+        {
+            "version": 1,
+            "disable_existing_loggers": False,
+            "formatters": {
+                "standard": {
+                    "format": "%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+                }
+            },
+            "handlers": {
+                "default": {
+                    "class": "logging.StreamHandler",
+                    "level": level,
+                    "formatter": "standard",
+                }
+            },
+            "root": {"level": level, "handlers": ["default"]},
+            "loggers": {
+                "uvicorn": {"level": level, "handlers": ["default"], "propagate": False},
+                "uvicorn.access": {"level": level, "handlers": ["default"], "propagate": False},
+                "oraculo_api": {"level": level, "handlers": ["default"], "propagate": False},
+            },
+        }
+    )

app/core/middleware.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import logging
+import time
+from collections import defaultdict, deque
+from threading import Lock
+from typing import Deque
+from uuid import uuid4
+
+from fastapi import Request
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from app.core.config import Settings
+from app.core.error_handlers import build_error_payload
+
+logger = logging.getLogger("oraculo_api.middleware")
+
+
+def resolve_client_ip(request: Request) -> str:
+    forwarded_for = request.headers.get("x-forwarded-for")
+    if forwarded_for:
+        return forwarded_for.split(",")[0].strip()
+    if request.client:
+        return request.client.host
+    return "unknown"
+
+
+class RequestContextMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        request_id = request.headers.get("x-request-id", str(uuid4()))
+        request.state.request_id = request_id
+        request.state.started_at = time.perf_counter()
+        request.state.client_ip = resolve_client_ip(request)
+
+        response = await call_next(request)
+        duration_ms = (time.perf_counter() - request.state.started_at) * 1000
+        response.headers["X-Request-ID"] = request_id
+        response.headers["X-Process-Time-MS"] = f"{duration_ms:.2f}"
+        return response
+
+
+class SecurityHeadersMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, settings: Settings):
+        super().__init__(app)
+        self.settings = settings
+
+    def _content_security_policy_for_path(self, path: str) -> str:
+        docs_paths = {
+            self.settings.docs_url,
+            self.settings.redoc_url,
+            self.settings.openapi_url,
+        }
+        if path in {value for value in docs_paths if value}:
+            return (
+                "default-src 'self'; "
+                "script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; "
+                "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; "
+                "img-src 'self' data: https://fastapi.tiangolo.com https://cdn.jsdelivr.net; "
+                "font-src 'self' https://cdn.jsdelivr.net; "
+                "connect-src 'self'; "
+                "frame-ancestors 'none'; "
+                "base-uri 'self';"
+            )
+
+        return "default-src 'none'; frame-ancestors 'none'; base-uri 'none';"
+
+    async def dispatch(self, request: Request, call_next):
+        response = await call_next(request)
+        if not self.settings.security_headers_enabled:
+            return response
+
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["Referrer-Policy"] = "no-referrer"
+        response.headers["Permissions-Policy"] = "camera=(), microphone=(), geolocation=()"
+        response.headers["Cache-Control"] = "no-store"
+        response.headers["Pragma"] = "no-cache"
+        response.headers["Content-Security-Policy"] = self._content_security_policy_for_path(request.url.path)
+        return response
+
+
+class MaxRequestSizeMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, max_request_size_bytes: int):
+        super().__init__(app)
+        self.max_request_size_bytes = max_request_size_bytes
+
+    async def dispatch(self, request: Request, call_next):
+        content_length = request.headers.get("content-length")
+        if content_length and int(content_length) > self.max_request_size_bytes:
+            payload = build_error_payload(
+                request,
+                code="payload_too_large",
+                message="Payload exceeds the maximum allowed size.",
+                detail={"max_request_size_bytes": self.max_request_size_bytes},
+            )
+            return JSONResponse(status_code=413, content=payload)
+        return await call_next(request)
+
+
+class SimpleInMemoryRateLimiter:
+    def __init__(self, max_requests: int, window_seconds: int):
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+        self._storage: dict[str, Deque[float]] = defaultdict(deque)
+        self._lock = Lock()
+
+    def is_allowed(self, client_key: str) -> tuple[bool, int]:
+        now = time.time()
+        with self._lock:
+            bucket = self._storage[client_key]
+            while bucket and now - bucket[0] > self.window_seconds:
+                bucket.popleft()
+
+            if len(bucket) >= self.max_requests:
+                retry_after = max(1, int(self.window_seconds - (now - bucket[0])))
+                return False, retry_after
+
+            bucket.append(now)
+            return True, 0
+
+
+class RateLimitMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, settings: Settings):
+        super().__init__(app)
+        self.settings = settings
+        self.limiter = SimpleInMemoryRateLimiter(
+            max_requests=settings.rate_limit_requests,
+            window_seconds=settings.rate_limit_window_seconds,
+        )
+
+    async def dispatch(self, request: Request, call_next):
+        if not self.settings.rate_limit_enabled or request.url.path in self.settings.rate_limit_exempt_paths:
+            return await call_next(request)
+
+        client_key = resolve_client_ip(request)
+        is_allowed, retry_after = self.limiter.is_allowed(client_key)
+        if not is_allowed:
+            payload = build_error_payload(
+                request,
+                code="rate_limit_exceeded",
+                message="Rate limit exceeded. Please retry later.",
+                detail={"retry_after_seconds": retry_after},
+            )
+            return JSONResponse(
+                status_code=429,
+                content=payload,
+                headers={"Retry-After": str(retry_after)},
+            )
+
+        return await call_next(request)

app/core/security.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+import hashlib
+from typing import Any
+
+import bcrypt
+import jwt
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from pydantic import BaseModel
+
+from app.core.config import Settings
+from app.core.exceptions import AuthenticationError
+
+
+bearer_scheme = HTTPBearer(auto_error=False)
+
+
+class TokenPayload(BaseModel):
+    sub: str
+    role: str = "user"
+    exp: int
+
+
+def hash_password(password: str) -> str:
+    password_bytes = _password_to_bytes(password)
+    return bcrypt.hashpw(password_bytes, bcrypt.gensalt()).decode("utf-8")
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    password_bytes = _password_to_bytes(plain_password)
+    return bcrypt.checkpw(password_bytes, hashed_password.encode("utf-8"))
+
+
+def _password_to_bytes(password: str) -> bytes:
+    raw_bytes = password.encode("utf-8")
+    if len(raw_bytes) <= 72:
+        return raw_bytes
+    return hashlib.sha256(raw_bytes).hexdigest().encode("utf-8")
+
+
+def create_access_token(
+    *,
+    subject: str,
+    role: str,
+    settings: Settings,
+    expires_delta: timedelta | None = None,
+) -> str:
+    expire_at = datetime.now(timezone.utc) + (
+        expires_delta or timedelta(minutes=settings.access_token_expire_minutes)
+    )
+    payload: dict[str, Any] = {
+        "sub": subject,
+        "role": role,
+        "exp": expire_at,
+    }
+    return jwt.encode(payload, settings.jwt_secret_key, algorithm=settings.jwt_algorithm)
+
+
+def decode_access_token(token: str, settings: Settings) -> TokenPayload:
+    try:
+        payload = jwt.decode(token, settings.jwt_secret_key, algorithms=[settings.jwt_algorithm])
+        return TokenPayload(**payload)
+    except jwt.ExpiredSignatureError as exc:
+        raise AuthenticationError("Access token expired.") from exc
+    except jwt.PyJWTError as exc:
+        raise AuthenticationError("Invalid access token.") from exc
+
+
+def extract_bearer_token(credentials: HTTPAuthorizationCredentials | None) -> str:
+    if credentials is None or not credentials.credentials:
+        raise AuthenticationError("Missing bearer token.")
+    return credentials.credentials

app/db/__init__.py

@@ -0,0 +1,3 @@
+from app.db import models
+
+__all__ = ["models"]

app/db/base.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from sqlalchemy import MetaData
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+NAMING_CONVENTION = {
+    "ix": "ix_%(column_0_label)s",
+    "uq": "uq_%(table_name)s_%(column_0_name)s",
+    "ck": "ck_%(table_name)s_%(constraint_name)s",
+    "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+    "pk": "pk_%(table_name)s",
+}
+
+
+class Base(DeclarativeBase):
+    metadata = MetaData(naming_convention=NAMING_CONVENTION)
+
+
+class TimestampMixin:
+    created_at: Mapped[datetime] = mapped_column(default=lambda: datetime.now(timezone.utc))
+    updated_at: Mapped[datetime] = mapped_column(
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+    )

app/db/models/__init__.py

@@ -0,0 +1,4 @@
+from app.db.models.prediction_log import PredictionLog
+from app.db.models.user import User, UserRole
+
+__all__ = ["PredictionLog", "User", "UserRole"]

app/db/models/prediction_log.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from uuid import uuid4
+
+from sqlalchemy import Float, ForeignKey, JSON, String, Text
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.db.base import Base, TimestampMixin
+
+
+class PredictionLog(TimestampMixin, Base):
+    __tablename__ = "prediction_logs"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    user_id: Mapped[str] = mapped_column(String(36), ForeignKey("users.id"), index=True)
+    request_id: Mapped[str] = mapped_column(String(64), index=True)
+    ip_address: Mapped[str] = mapped_column(String(64))
+    label: Mapped[str] = mapped_column(String(16), index=True)
+    probability: Mapped[float] = mapped_column(Float)
+    latency_ms: Mapped[float] = mapped_column(Float)
+    model_version: Mapped[str] = mapped_column(String(64))
+    payload_hash: Mapped[str] = mapped_column(String(64), index=True)
+    input_payload: Mapped[dict] = mapped_column(JSON)
+    normalized_payload: Mapped[dict] = mapped_column(JSON)
+    notes: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    user = relationship("User", back_populates="predictions")

app/db/models/user.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from enum import Enum
+from uuid import uuid4
+
+from sqlalchemy import Boolean, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.db.base import Base, TimestampMixin
+
+
+class UserRole(str, Enum):
+    ADMIN = "admin"
+    USER = "user"
+
+
+class User(TimestampMixin, Base):
+    __tablename__ = "users"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    full_name: Mapped[str] = mapped_column(String(255))
+    password_hash: Mapped[str] = mapped_column(String(255))
+    role: Mapped[str] = mapped_column(String(32), default=UserRole.USER.value)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
+
+    predictions = relationship("PredictionLog", back_populates="user", cascade="all, delete-orphan")

app/db/repositories/__init__.py

@@ -0,0 +1,4 @@
+from app.db.repositories.predictions import PredictionRepository
+from app.db.repositories.users import UserRepository
+
+__all__ = ["PredictionRepository", "UserRepository"]

app/db/repositories/predictions.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from sqlalchemy import Select, func, select
+from sqlalchemy.orm import Session
+
+from app.db.models import PredictionLog
+
+
+class PredictionRepository:
+    def __init__(self, session: Session):
+        self.session = session
+
+    def create(
+        self,
+        *,
+        user_id: str,
+        request_id: str,
+        ip_address: str,
+        label: str,
+        probability: float,
+        latency_ms: float,
+        model_version: str,
+        payload_hash: str,
+        input_payload: dict,
+        normalized_payload: dict,
+        notes: str | None = None,
+    ) -> PredictionLog:
+        prediction_log = PredictionLog(
+            user_id=user_id,
+            request_id=request_id,
+            ip_address=ip_address,
+            label=label,
+            probability=probability,
+            latency_ms=latency_ms,
+            model_version=model_version,
+            payload_hash=payload_hash,
+            input_payload=input_payload,
+            normalized_payload=normalized_payload,
+            notes=notes,
+        )
+        self.session.add(prediction_log)
+        self.session.flush()
+        self.session.refresh(prediction_log)
+        return prediction_log
+
+    def list_for_user(
+        self,
+        *,
+        user_id: str,
+        skip: int,
+        limit: int,
+        label: str | None = None,
+        min_probability: float | None = None,
+    ) -> tuple[list[PredictionLog], int]:
+        statement: Select[tuple[PredictionLog]] = select(PredictionLog).where(PredictionLog.user_id == user_id)
+
+        if label:
+            statement = statement.where(PredictionLog.label == label)
+        if min_probability is not None:
+            statement = statement.where(PredictionLog.probability >= min_probability)
+
+        total = self.session.scalar(select(func.count()).select_from(statement.subquery())) or 0
+        rows = self.session.scalars(
+            statement.order_by(PredictionLog.created_at.desc()).offset(skip).limit(limit)
+        ).all()
+        return rows, total
+
+    def get_for_user(self, *, prediction_id: str, user_id: str) -> PredictionLog | None:
+        statement = select(PredictionLog).where(
+            PredictionLog.id == prediction_id,
+            PredictionLog.user_id == user_id,
+        )
+        return self.session.scalar(statement)

app/db/repositories/users.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.db.models import User
+
+
+class UserRepository:
+    def __init__(self, session: Session):
+        self.session = session
+
+    def get_by_email(self, email: str) -> User | None:
+        statement = select(User).where(User.email == email.lower())
+        return self.session.scalar(statement)
+
+    def get_by_id(self, user_id: str) -> User | None:
+        statement = select(User).where(User.id == user_id)
+        return self.session.scalar(statement)
+
+    def create(self, *, email: str, full_name: str, password_hash: str, role: str = "user") -> User:
+        user = User(
+            email=email.lower(),
+            full_name=full_name,
+            password_hash=password_hash,
+            role=role,
+        )
+        self.session.add(user)
+        self.session.flush()
+        self.session.refresh(user)
+        return user

app/db/seeds.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import logging
+
+from sqlalchemy.orm import Session
+
+from app.core.config import Settings
+from app.core.security import hash_password
+from app.db.models import UserRole
+from app.db.repositories import UserRepository
+
+logger = logging.getLogger("oraculo_api.seeds")
+
+
+def seed_admin_user(session: Session, settings: Settings) -> None:
+    if not settings.auto_seed_admin:
+        return
+    if not settings.seed_admin_email or not settings.seed_admin_password:
+        return
+
+    repository = UserRepository(session)
+    existing_user = repository.get_by_email(settings.seed_admin_email)
+    if existing_user:
+        return
+
+    repository.create(
+        email=settings.seed_admin_email,
+        full_name=settings.seed_admin_name,
+        password_hash=hash_password(settings.seed_admin_password),
+        role=UserRole.ADMIN.value,
+    )
+    logger.info("Default admin user created for bootstrap.")

app/db/session.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from collections.abc import Generator
+
+from sqlalchemy import create_engine, text
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import Session, sessionmaker
+from sqlalchemy.pool import StaticPool
+
+from app.core.config import Settings
+from app.db.base import Base
+
+
+def build_engine(settings: Settings) -> Engine:
+    connect_args = {"check_same_thread": False} if settings.database_url.startswith("sqlite") else {}
+    engine_kwargs = {
+        "echo": settings.database_echo,
+        "pool_pre_ping": True,
+        "future": True,
+        "connect_args": connect_args,
+    }
+    if settings.database_url.endswith(":memory:"):
+        engine_kwargs["poolclass"] = StaticPool
+
+    return create_engine(
+        settings.database_url,
+        **engine_kwargs,
+    )
+
+
+def build_session_factory(engine: Engine) -> sessionmaker[Session]:
+    return sessionmaker(bind=engine, autoflush=False, autocommit=False, expire_on_commit=False)
+
+
+def create_tables(engine: Engine) -> None:
+    Base.metadata.create_all(bind=engine)
+
+
+def check_database_connection(session: Session) -> bool:
+    session.execute(text("SELECT 1"))
+    return True
+
+
+def get_db_session_factory(request) -> sessionmaker[Session]:
+    return request.app.state.session_factory
+
+
+def yield_session(session_factory: sessionmaker[Session]) -> Generator[Session, None, None]:
+    session = session_factory()
+    try:
+        yield session
+        session.commit()
+    except Exception:
+        session.rollback()
+        raise
+    finally:
+        session.close()

app/main.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.middleware.gzip import GZipMiddleware
+from starlette.middleware.trustedhost import TrustedHostMiddleware
+
+from app.api.router import router as api_router
+from app.core.config import Settings, get_settings
+from app.core.error_handlers import register_error_handlers
+from app.core.logging import configure_logging
+from app.core.middleware import (
+    MaxRequestSizeMiddleware,
+    RateLimitMiddleware,
+    RequestContextMiddleware,
+    SecurityHeadersMiddleware,
+)
+from app.db import models  # noqa: F401
+from app.db.seeds import seed_admin_user
+from app.db.session import build_engine, build_session_factory, create_tables
+from app.ml.model_manager import ModelManager
+
+logger = logging.getLogger("oraculo_api")
+
+
+def create_app(settings: Settings | None = None, model_manager: ModelManager | None = None) -> FastAPI:
+    app_settings = settings or get_settings()
+    configure_logging(app_settings)
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        engine = build_engine(app_settings)
+        session_factory = build_session_factory(engine)
+
+        app.state.settings = app_settings
+        app.state.engine = engine
+        app.state.session_factory = session_factory
+
+        if app_settings.auto_create_tables:
+            create_tables(engine)
+
+        with session_factory() as session:
+            seed_admin_user(session, app_settings)
+            session.commit()
+
+        active_model_manager = model_manager or ModelManager(app_settings.resolved_model_path)
+        active_model_manager.load_model()
+        app.state.model_manager = active_model_manager
+
+        logger.info("%s started in %s mode.", app_settings.app_name, app_settings.environment)
+        yield
+
+        if hasattr(app.state.model_manager, "unload_model"):
+            app.state.model_manager.unload_model()
+        app.state.engine.dispose()
+        logger.info("%s shutdown completed.", app_settings.app_name)
+
+    docs_enabled = app_settings.docs_enabled
+    application = FastAPI(
+        title=app_settings.app_name,
+        version=app_settings.app_version,
+        debug=app_settings.debug,
+        lifespan=lifespan,
+        docs_url=app_settings.docs_url if docs_enabled else None,
+        redoc_url=app_settings.redoc_url if docs_enabled else None,
+        openapi_url=app_settings.openapi_url if docs_enabled else None,
+    )
+
+    application.add_middleware(GZipMiddleware, minimum_size=1024)
+    application.add_middleware(
+        CORSMiddleware,
+        allow_origins=app_settings.cors_allow_origins,
+        allow_credentials=True,
+        allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
+        allow_headers=["*"],
+    )
+    application.add_middleware(TrustedHostMiddleware, allowed_hosts=app_settings.allowed_hosts)
+    application.add_middleware(SecurityHeadersMiddleware, settings=app_settings)
+    application.add_middleware(MaxRequestSizeMiddleware, max_request_size_bytes=app_settings.max_request_size_bytes)
+    application.add_middleware(RateLimitMiddleware, settings=app_settings)
+    application.add_middleware(RequestContextMiddleware)
+
+    register_error_handlers(application)
+    application.include_router(api_router)
+
+    @application.get("/", tags=["Root"])
+    def root() -> dict[str, str]:
+        return {
+            "service": app_settings.app_name,
+            "version": app_settings.app_version,
+            "environment": app_settings.environment,
+        }
+
+    return application
+
+
+app = create_app()

app/ml/custom_transformers.py

@@ -0,0 +1,479 @@
+import logging
+import re
+import time
+import warnings
+from pathlib import Path
+from typing import Any, Dict, Iterable, Optional
+
+import numpy as np
+import pandas as pd
+
+logger = logging.getLogger("api_logger")
+
+_COLUMN_SANITIZER = re.compile(r"[^a-z0-9_]")
+_MULTI_UNDERSCORE = re.compile(r"_+")
+_MASK_PATTERN = re.compile(r"(?i)^(unknown|n/?a|null|nan|missing|none|-1|)$|^[^a-zA-Z0-9]+$")
+_LLM_OPERATORS = {"_+_": "+", "_-_": "-", "_*_": "*"}
+_RARE_LABEL = "Rare"
+
+
+class PipelineProduccionMLOps:
+    """
+    Standalone production pipeline compatible with the notebook artifact.
+
+    The current notebook exports a partially broken pickle: several feature
+    engineering recipes are not serialized, and the API receives raw JSON with
+    snake_case / dotted-name mismatches. This class heals that gap at runtime.
+    """
+
+    def __init__(self, rutas: Dict, artefactos: Dict, modelos: Dict):
+        self.rutas = rutas or {}
+        self.artefactos = artefactos or {}
+        self.modelos = modelos or {}
+        self.umbral_oro = float(
+            self.artefactos.get(
+                "umbral_decision",
+                self.rutas.get("umbral_decision_optimo", 0.50),
+            )
+        )
+        self.version = "1.0.0"
+        self.fecha_ensamblaje = time.strftime("%Y-%m-%d %H:%M:%S")
+
+    def _ensure_runtime_state(self) -> None:
+        if not hasattr(self, "rutas") or self.rutas is None:
+            self.rutas = {}
+        if not hasattr(self, "artefactos") or self.artefactos is None:
+            self.artefactos = {}
+        if not hasattr(self, "modelos") or self.modelos is None:
+            self.modelos = {}
+        if not hasattr(self, "umbral_oro"):
+            self.umbral_oro = float(
+                self.artefactos.get(
+                    "umbral_decision",
+                    self.rutas.get("umbral_decision_optimo", 0.50),
+                )
+            )
+        if not hasattr(self, "_reference_dataset"):
+            self._reference_dataset = None
+        if not hasattr(self, "_did_infer_missing_artefacts"):
+            self._did_infer_missing_artefacts = False
+
+    def _get_modelo_final(self) -> Any:
+        self._ensure_runtime_state()
+        return self.modelos.get("oraculo_calibrado", self.modelos.get("oraculo_lightgbm"))
+
+    def _get_training_feature_names(self) -> list[str]:
+        modelo_final = self._get_modelo_final()
+        if modelo_final is None:
+            return []
+
+        if hasattr(modelo_final, "feature_names_in_"):
+            return [str(col) for col in modelo_final.feature_names_in_]
+
+        if hasattr(modelo_final, "estimator") and hasattr(modelo_final.estimator, "feature_name_"):
+            feature_names = modelo_final.estimator.feature_name_
+            feature_names = feature_names() if callable(feature_names) else feature_names
+            return [str(col) for col in feature_names]
+
+        if hasattr(modelo_final, "booster_"):
+            return [str(col) for col in modelo_final.booster_.feature_name()]
+
+        return []
+
+    @staticmethod
+    def _sanitize_column_name(name: Any) -> str:
+        text = str(name).strip().lower()
+        text = _COLUMN_SANITIZER.sub("_", text)
+        text = _MULTI_UNDERSCORE.sub("_", text)
+        return text.strip("_")
+
+    @classmethod
+    def _sanitize_text_series(cls, series: pd.Series) -> pd.Series:
+        mask = series.isna()
+        clean = series.astype("string")
+        clean = clean.str.lower()
+        clean = clean.str.normalize("NFKD").str.encode("ascii", errors="ignore").str.decode("utf-8")
+        clean = clean.str.replace(r"\s+", " ", regex=True)
+        clean = clean.str.replace(r"\s*([^\w\s])\s*", r"\1", regex=True)
+        clean = clean.str.replace(r"(?<=\d)\s+(?=[a-z])|(?<=[a-z])\s+(?=\d)", "", regex=True)
+        clean = clean.str.strip().str.replace(r"\s+", "_", regex=True)
+        clean = clean.astype(object)
+        clean[mask] = np.nan
+        return clean
+
+    @classmethod
+    def _normalize_input_frame(cls, X_raw: pd.DataFrame) -> pd.DataFrame:
+        X = X_raw.copy()
+        X.columns = [cls._sanitize_column_name(col) for col in X.columns]
+
+        for col in X.columns:
+            dtype = X[col].dtype
+            if (
+                pd.api.types.is_object_dtype(dtype)
+                or pd.api.types.is_string_dtype(dtype)
+                or isinstance(dtype, pd.CategoricalDtype)
+            ):
+                X[col] = cls._sanitize_text_series(X[col])
+        return X
+
+    def _reference_dataset_path(self) -> Path:
+        return Path(__file__).resolve().parents[2] / "adult.csv"
+
+    def _load_reference_dataset(self) -> Optional[pd.DataFrame]:
+        self._ensure_runtime_state()
+        if self._reference_dataset is not None:
+            return self._reference_dataset.copy()
+
+        dataset_path = self._reference_dataset_path()
+        if not dataset_path.exists():
+            logger.warning(
+                "No se encontro '%s'; la inferencia seguira sin reconstruir recetas faltantes.",
+                dataset_path,
+            )
+            return None
+
+        try:
+            df = pd.read_csv(dataset_path, sep=";")
+        except Exception as exc:
+            logger.warning(
+                "No fue posible leer '%s' para reconstruir artefactos de inferencia: %s",
+                dataset_path,
+                exc,
+            )
+            return None
+
+        df = self._normalize_input_frame(df)
+        self._reference_dataset = df
+        return df.copy()
+
+    def _get_rare_recipe(self) -> Dict[str, list]:
+        self._ensure_runtime_state()
+        recipe = self.artefactos.get("receta_categorias_raras")
+        if recipe:
+            return recipe
+        recipe = self.modelos.get("vocabulario_rare_labeling")
+        if recipe:
+            return recipe
+        return {}
+
+    def _get_binary_recipe(self) -> Dict[str, Dict[Any, int]]:
+        self._ensure_runtime_state()
+        recipe = self.artefactos.get("receta_mapeo_binario") or self.artefactos.get("reglas_binarias") or {}
+        return {
+            col: mapping
+            for col, mapping in recipe.items()
+            if not str(col).startswith("TARGET_")
+        }
+
+    def _get_target_recipe(self) -> Dict[str, Dict[str, Dict[Any, float]]]:
+        self._ensure_runtime_state()
+        return self.artefactos.get("receta_target_encoding") or self.artefactos.get("receta_woe_encoding") or {}
+
+    def _get_ratio_recipe(self) -> Iterable[tuple]:
+        self._ensure_runtime_state()
+        return self.artefactos.get("receta_ratios_matematicos") or self.artefactos.get("receta_ratios_train") or []
+
+    def _get_llm_recipe(self) -> Dict[str, str]:
+        self._ensure_runtime_state()
+        return self.artefactos.get("receta_llm_fe") or {}
+
+    def _learn_rare_recipe(self, X: pd.DataFrame, threshold: float = 0.01) -> Dict[str, list]:
+        recipe: Dict[str, list] = {}
+        cat_cols = X.select_dtypes(include=["object", "category", "string"]).columns.tolist()
+
+        for col in cat_cols:
+            frequencies = X[col].value_counts(normalize=True)
+            valid_categories = frequencies[frequencies >= threshold].index.tolist()
+            masks = [val for val in frequencies.index if _MASK_PATTERN.match(str(val).strip())]
+            valid_categories.extend(masks)
+            valid_categories = list(dict.fromkeys(valid_categories))
+            rare_categories = frequencies[~frequencies.index.isin(valid_categories)]
+            if not rare_categories.empty:
+                recipe[col] = valid_categories
+
+        return recipe
+
+    @staticmethod
+    def _apply_rare_labeling(X: pd.DataFrame, recipe: Dict[str, list]) -> pd.DataFrame:
+        X_trans = X.copy()
+        for col, valid_categories in recipe.items():
+            if col not in X_trans.columns:
+                continue
+            mask_null = X_trans[col].isna()
+            mask_replace = ~X_trans[col].isin(valid_categories) & ~mask_null
+            X_trans.loc[mask_replace, col] = _RARE_LABEL
+        return X_trans
+
+    @staticmethod
+    def _encode_binary_target(target: pd.Series) -> pd.Series:
+        ordered_values = sorted(target.dropna().unique().tolist())
+        mapping = {value: index for index, value in enumerate(ordered_values)}
+        return target.map(mapping).astype(float)
+
+    @staticmethod
+    def _learn_binary_recipe(X: pd.DataFrame) -> Dict[str, Dict[Any, int]]:
+        recipe: Dict[str, Dict[Any, int]] = {}
+        for col in X.columns:
+            values = X[col].dropna().unique().tolist()
+            if len(values) != 2:
+                continue
+            if pd.api.types.is_numeric_dtype(X[col]):
+                continue
+            ordered_values = sorted(values)
+            recipe[col] = {ordered_values[0]: 0, ordered_values[1]: 1}
+        return recipe
+
+    @staticmethod
+    def _learn_target_encoding_recipe(
+        X: pd.DataFrame,
+        y: pd.Series,
+        rutas: Optional[Dict[str, list]] = None,
+        smoothing: float = 10.0,
+    ) -> Dict[str, Dict[str, Dict[Any, float]]]:
+        rutas = rutas or {"cat_vars": []}
+        recipe: Dict[str, Dict[str, Dict[Any, float]]] = {}
+
+        for col in X.columns:
+            if col.startswith("TARGET_"):
+                continue
+
+            unique_values = X[col].dropna().nunique()
+            is_numeric = pd.api.types.is_numeric_dtype(X[col])
+            is_categorical = (
+                col in rutas.get("cat_vars", [])
+                or pd.api.types.is_object_dtype(X[col])
+                or isinstance(X[col].dtype, pd.CategoricalDtype)
+            )
+
+            if not is_categorical or is_numeric or unique_values <= 2:
+                continue
+
+            working = X[col].astype(object)
+            stats = pd.DataFrame({"Target": y, "Categoria": working}).groupby("Categoria")["Target"].agg(["count", "mean"])
+            n_obs = stats["count"]
+            global_mean = float(y.mean())
+            smooth = (n_obs * stats["mean"] + smoothing * global_mean) / (n_obs + smoothing)
+            recipe[col] = {
+                "Target_Directo": {
+                    **smooth.to_dict(),
+                    "__GLOBAL_MEAN__": global_mean,
+                }
+            }
+
+        return recipe
+
+    def _infer_llm_recipe_from_feature_names(self, feature_names: Iterable[str]) -> Dict[str, str]:
+        llm_recipe: Dict[str, str] = {}
+
+        for feature_name in feature_names:
+            if not feature_name.startswith("llm_"):
+                continue
+
+            expression = feature_name[4:]
+            for token, operator in _LLM_OPERATORS.items():
+                if token not in expression:
+                    continue
+                left, right = expression.split(token, 1)
+                llm_recipe[feature_name] = f"X['{left}'] {operator} X['{right}']"
+                break
+
+        return llm_recipe
+
+    def _infer_missing_artefacts(self) -> None:
+        self._ensure_runtime_state()
+        if self._did_infer_missing_artefacts:
+            return
+
+        feature_names = self._get_training_feature_names()
+        needs_binary = "sex" in feature_names and not self._get_binary_recipe()
+        needs_target = any(
+            feature in feature_names
+            for feature in ("workclass", "marital_status", "occupation", "relationship", "race", "native_country")
+        ) and not self._get_target_recipe()
+        needs_rare = (needs_binary or needs_target) and not self._get_rare_recipe()
+        needs_llm = any(feature.startswith("llm_") for feature in feature_names) and not self._get_llm_recipe()
+
+        if not any((needs_binary, needs_target, needs_rare, needs_llm)):
+            self._did_infer_missing_artefacts = True
+            return
+
+        reference_df = self._load_reference_dataset()
+        if reference_df is None:
+            self._did_infer_missing_artefacts = True
+            return
+
+        target_name = self.rutas.get("target_name", "income")
+        if target_name not in reference_df.columns:
+            logger.warning(
+                "El dataset de referencia no contiene la columna target '%s'; no se pudieron reconstruir todas las recetas.",
+                target_name,
+            )
+            self._did_infer_missing_artefacts = True
+            return
+
+        X_ref = reference_df.drop(columns=[target_name]).copy()
+        y_ref = self._encode_binary_target(reference_df[target_name].copy())
+
+        rare_recipe = self._get_rare_recipe() or self._learn_rare_recipe(X_ref)
+        X_rare = self._apply_rare_labeling(X_ref, rare_recipe)
+
+        if rare_recipe and "receta_categorias_raras" not in self.artefactos:
+            self.artefactos["receta_categorias_raras"] = rare_recipe
+
+        binary_recipe = self._get_binary_recipe() or self._learn_binary_recipe(X_rare)
+        if binary_recipe and "receta_mapeo_binario" not in self.artefactos:
+            self.artefactos["receta_mapeo_binario"] = binary_recipe
+
+        target_recipe = self._get_target_recipe() or self._learn_target_encoding_recipe(X_rare, y_ref, self.rutas)
+        if target_recipe and "receta_target_encoding" not in self.artefactos and "receta_woe_encoding" not in self.artefactos:
+            self.artefactos["receta_target_encoding"] = target_recipe
+
+        llm_recipe = self._get_llm_recipe() or self._infer_llm_recipe_from_feature_names(feature_names)
+        if llm_recipe and "receta_llm_fe" not in self.artefactos:
+            self.artefactos["receta_llm_fe"] = llm_recipe
+
+        if needs_binary or needs_target or needs_rare or needs_llm:
+            logger.warning(
+                "Se reconstruyeron artefactos faltantes del notebook usando '%s'. "
+                "La causa raiz es un desajuste entre la exportacion del .pkl y la API.",
+                self._reference_dataset_path().name,
+            )
+
+        self._did_infer_missing_artefacts = True
+
+    def _apply_llm_formulas(self, X: pd.DataFrame) -> pd.DataFrame:
+        llm_recipe = self._get_llm_recipe()
+        if not llm_recipe:
+            return X
+
+        X_trans = X.copy()
+        safe_env = {"np": np, "X": X_trans}
+
+        for feature_name, formula in llm_recipe.items():
+            try:
+                X_trans[feature_name] = eval(formula, {"__builtins__": {}}, safe_env)
+            except Exception:
+                X_trans[feature_name] = 0.0
+
+        return X_trans
+
+    def _transformar_features(self, X_raw: pd.DataFrame) -> pd.DataFrame:
+        self._ensure_runtime_state()
+        self._infer_missing_artefacts()
+
+        X = self._normalize_input_frame(X_raw)
+        X = self._apply_llm_formulas(X)
+
+        receta_raras = self._get_rare_recipe()
+        if receta_raras:
+            X = self._apply_rare_labeling(X, receta_raras)
+
+        receta_target = self._get_target_recipe()
+        for col, config_encoding in receta_target.items():
+            if col not in X.columns:
+                continue
+
+            if "__GLOBAL_NEUTRAL__" in config_encoding:
+                neutral = config_encoding.get("__GLOBAL_NEUTRAL__", 0.0)
+                mask_nan = X[col].isna()
+                pure_map = {key: value for key, value in config_encoding.items() if key != "__GLOBAL_NEUTRAL__"}
+                X[col] = X[col].astype(object).map(pure_map).fillna(neutral)
+                X.loc[mask_nan, col] = np.nan
+                continue
+
+            for class_name, mapping in config_encoding.items():
+                global_mean = mapping.get("__GLOBAL_MEAN__", 0.0)
+                pure_map = {key: value for key, value in mapping.items() if key != "__GLOBAL_MEAN__"}
+                new_col = col if len(config_encoding) == 1 else f"{col}_prob_{class_name}"
+                mask_nan = X[col].isna()
+                X[new_col] = X[col].astype(object).map(pure_map).fillna(global_mean)
+                X.loc[mask_nan, new_col] = np.nan
+
+            if len(config_encoding) > 1:
+                X.drop(columns=[col], inplace=True)
+
+        receta_binaria = self._get_binary_recipe()
+        for col, mapping in receta_binaria.items():
+            if col in X.columns:
+                X[col] = X[col].map(mapping).fillna(0).astype(int)
+
+        receta_ratios = self._get_ratio_recipe()
+        for ratio in receta_ratios:
+            if len(ratio) != 3:
+                continue
+            if ratio[0] in X.columns and ratio[1] in X.columns and ratio[2] not in X.columns:
+                div_col, num_col, ratio_name = ratio
+            else:
+                ratio_name, num_col, div_col = ratio
+
+            if num_col in X.columns and div_col in X.columns:
+                X[ratio_name] = X[num_col].astype(float) / (X[div_col].astype(float) + 1e-9)
+
+        receta_winsor = self.artefactos.get("receta_winsorizacion", {})
+        for col, (lim_inf, lim_sup) in receta_winsor.items():
+            if col in X.columns:
+                X[col] = pd.to_numeric(X[col], errors="coerce").clip(lower=lim_inf, upper=lim_sup)
+
+        escalador = self.modelos.get("escalador_numerico")
+        if escalador is not None:
+            cols_to_scale = getattr(escalador, "feature_names_in_", [])
+            cols_present = [col for col in cols_to_scale if col in X.columns]
+            if cols_present:
+                X.loc[:, cols_present] = escalador.transform(X[cols_present]).astype(np.float32)
+
+        basura = (
+            self.rutas.get("basura_boruta", [])
+            + self.rutas.get("gemelos_colineales", [])
+            + self.rutas.get("fugas_del_futuro", [])
+        )
+        basura_presente = [col for col in basura if col in X.columns]
+        if basura_presente:
+            X.drop(columns=basura_presente, inplace=True)
+
+        return X
+
+    def _coerce_model_input(self, X: pd.DataFrame, expected_features: list[str]) -> pd.DataFrame:
+        X_final = X.copy()
+
+        for feature in expected_features:
+            if feature not in X_final.columns:
+                X_final[feature] = np.nan
+
+        X_final = X_final[expected_features].copy()
+
+        receta_nativas = self.artefactos.get("receta_categorias_nativas", {})
+        for col, categories in receta_nativas.items():
+            if col in X_final.columns:
+                dtype = pd.CategoricalDtype(categories=categories, ordered=False)
+                X_final[col] = X_final[col].astype(str).replace("nan", np.nan).astype(dtype)
+
+        for col in X_final.columns:
+            if isinstance(X_final[col].dtype, pd.CategoricalDtype):
+                continue
+            if pd.api.types.is_object_dtype(X_final[col]) or pd.api.types.is_string_dtype(X_final[col]):
+                X_final[col] = pd.to_numeric(X_final[col], errors="coerce")
+
+        return X_final
+
+    def predict_proba(self, X_raw: pd.DataFrame) -> np.ndarray:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+
+            modelo_final = self._get_modelo_final()
+            if modelo_final is None:
+                raise RuntimeError("No hay un modelo cargado dentro del pipeline de produccion.")
+
+            expected_features = self._get_training_feature_names()
+            X_procesado = self._transformar_features(X_raw)
+            X_final = self._coerce_model_input(X_procesado, expected_features or list(X_procesado.columns))
+            return modelo_final.predict_proba(X_final)
+
+    def predict(self, X_raw: pd.DataFrame) -> np.ndarray:
+        probas = self.predict_proba(X_raw)
+
+        if probas.shape[1] == 2:
+            classes = (probas[:, 1] >= self.umbral_oro).astype(int)
+            label_map = {0: "<=50K", 1: ">50K"}
+            return np.array([label_map[value] for value in classes])
+
+        return np.argmax(probas, axis=1)

app/ml/model_manager.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import logging
+import sys
+from dataclasses import dataclass
+import json
+from pathlib import Path
+from threading import Lock
+from typing import Any
+
+import joblib
+import numpy as np
+import pandas as pd
+
+import app.ml.custom_transformers as custom_transformers
+from app.core.exceptions import ModelInferenceError, ServiceUnavailableError
+
+logger = logging.getLogger("oraculo_api.model")
+
+
+@dataclass(slots=True)
+class ModelPrediction:
+    label: str
+    probability: float
+    raw_probabilities: list[float]
+    model_version: str
+
+
+class ModelManager:
+    def __init__(self, model_path: str | Path):
+        self.model_path = Path(model_path)
+        self.pipeline: Any = None
+        self.manifest: dict[str, Any] = {}
+        self._lock = Lock()
+
+    @property
+    def is_loaded(self) -> bool:
+        return self.pipeline is not None
+
+    @property
+    def model_version(self) -> str:
+        if self.manifest.get("model_version"):
+            return str(self.manifest["model_version"])
+        if self.pipeline is None:
+            return "unloaded"
+        return str(getattr(self.pipeline, "version", "unknown"))
+
+    @property
+    def manifest_path(self) -> Path:
+        return self.model_path.with_name("model_manifest.json")
+
+    def _register_pickle_bridge(self) -> None:
+        setattr(
+            sys.modules["__main__"],
+            "PipelineProduccionMLOps",
+            custom_transformers.PipelineProduccionMLOps,
+        )
+
+    def load_model(self) -> None:
+        with self._lock:
+            if self.pipeline is not None:
+                return
+
+            if not self.model_path.exists():
+                raise ServiceUnavailableError(f"Model artifact not found at '{self.model_path}'.")
+
+            try:
+                self._register_pickle_bridge()
+                self.pipeline = joblib.load(self.model_path)
+                if hasattr(self.pipeline, "_infer_missing_artefacts"):
+                    self.pipeline._infer_missing_artefacts()
+                if self.manifest_path.exists():
+                    self.manifest = json.loads(self.manifest_path.read_text(encoding="utf-8"))
+                logger.info("Model artifact loaded from %s", self.model_path)
+            except Exception as exc:
+                logger.exception("Unable to load model artifact: %s", exc)
+                raise ServiceUnavailableError("Model artifact could not be loaded.") from exc
+
+    def unload_model(self) -> None:
+        with self._lock:
+            self.pipeline = None
+            self.manifest = {}
+
+    def _ensure_loaded(self) -> Any:
+        if self.pipeline is None:
+            raise ServiceUnavailableError("Model is not loaded.")
+        return self.pipeline
+
+    @staticmethod
+    def _to_frame(input_data: dict[str, Any] | pd.DataFrame) -> pd.DataFrame:
+        if isinstance(input_data, pd.DataFrame):
+            return input_data.copy()
+        return pd.DataFrame([input_data])
+
+    def predict(self, input_data: dict[str, Any] | pd.DataFrame) -> np.ndarray:
+        pipeline = self._ensure_loaded()
+        try:
+            frame = self._to_frame(input_data)
+            return pipeline.predict(frame)
+        except Exception as exc:
+            logger.exception("Prediction failed: %s", exc)
+            raise ModelInferenceError("Prediction failed.") from exc
+
+    def predict_proba(self, input_data: dict[str, Any] | pd.DataFrame) -> np.ndarray:
+        pipeline = self._ensure_loaded()
+        try:
+            frame = self._to_frame(input_data)
+            return pipeline.predict_proba(frame)
+        except Exception as exc:
+            logger.exception("Probability inference failed: %s", exc)
+            raise ModelInferenceError("Probability inference failed.") from exc
+
+    def predict_one(self, input_data: dict[str, Any]) -> ModelPrediction:
+        labels = self.predict(input_data)
+        probabilities = self.predict_proba(input_data)
+        probability_vector = probabilities[0].tolist()
+        positive_probability = float(probability_vector[1] if len(probability_vector) > 1 else probability_vector[0])
+        return ModelPrediction(
+            label=str(labels[0]),
+            probability=positive_probability,
+            raw_probabilities=probability_vector,
+            model_version=self.model_version,
+        )

app/ml/pipeline_produccion.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:78ce8c47e3e47951191bbe190af36bc975973b249fbf7449a621d554ab45ad87
+size 6454915

app/schemas/__init__.py

@@ -0,0 +1,21 @@
+from app.schemas.auth import LoginRequest, RegisterRequest, TokenResponse, UserResponse
+from app.schemas.health import LiveHealthResponse, ReadyHealthResponse
+from app.schemas.prediction import (
+    PredictionDetailResponse,
+    PredictionInput,
+    PredictionListResponse,
+    PredictionResponse,
+)
+
+__all__ = [
+    "LiveHealthResponse",
+    "LoginRequest",
+    "PredictionDetailResponse",
+    "PredictionInput",
+    "PredictionListResponse",
+    "PredictionResponse",
+    "ReadyHealthResponse",
+    "RegisterRequest",
+    "TokenResponse",
+    "UserResponse",
+]

app/schemas/adult_dataset.py

@@ -0,0 +1,4 @@
+from app.schemas.prediction import PredictionInput as AdultDataInput
+from app.schemas.prediction import PredictionResponse as AdultPredictionOutput
+
+__all__ = ["AdultDataInput", "AdultPredictionOutput"]

app/schemas/auth.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from typing import Literal
+
+from pydantic import ConfigDict, Field, field_validator
+
+from app.schemas.common import BaseSchema
+
+EMAIL_PATTERN = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+
+
+class RegisterRequest(BaseSchema):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    email: str = Field(..., max_length=255)
+    full_name: str = Field(..., min_length=3, max_length=255)
+    password: str = Field(..., min_length=12, max_length=128)
+
+    @field_validator("email")
+    @classmethod
+    def validate_email(cls, value: str) -> str:
+        lowered = value.lower()
+        if not EMAIL_PATTERN.match(lowered):
+            raise ValueError("Invalid email format.")
+        return lowered
+
+    @field_validator("password")
+    @classmethod
+    def validate_password_strength(cls, value: str) -> str:
+        checks = [
+            any(char.islower() for char in value),
+            any(char.isupper() for char in value),
+            any(char.isdigit() for char in value),
+            any(not char.isalnum() for char in value),
+        ]
+        if not all(checks):
+            raise ValueError(
+                "Password must contain uppercase, lowercase, numeric, and special characters."
+            )
+        return value
+
+
+class LoginRequest(BaseSchema):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    email: str = Field(..., max_length=255)
+    password: str = Field(..., min_length=12, max_length=128)
+
+    @field_validator("email")
+    @classmethod
+    def normalize_email(cls, value: str) -> str:
+        lowered = value.lower()
+        if not EMAIL_PATTERN.match(lowered):
+            raise ValueError("Invalid email format.")
+        return lowered
+
+
+class UserResponse(BaseSchema):
+    id: str
+    email: str
+    full_name: str
+    role: Literal["admin", "user"]
+    is_active: bool
+    created_at: datetime
+    updated_at: datetime
+
+
+class TokenResponse(BaseSchema):
+    access_token: str
+    token_type: Literal["bearer"] = "bearer"
+    expires_in_seconds: int
+    user: UserResponse

app/schemas/common.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class BaseSchema(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+
+class PaginationMeta(BaseSchema):
+    total: int
+    skip: int
+    limit: int
+
+
+class TimestampedSchema(BaseSchema):
+    created_at: datetime
+    updated_at: datetime

app/schemas/health.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from app.schemas.common import BaseSchema
+
+
+class LiveHealthResponse(BaseSchema):
+    status: str
+    service: str
+    version: str
+
+
+class ReadyHealthResponse(BaseSchema):
+    status: str
+    service: str
+    version: str
+    model_loaded: bool
+    database_connected: bool