Feature/documentation rag (#5)

Creación de los endpoints para poder subir y listar documentación y la
creación de dos .MD sobre los endpoints de para poder subir "documentos"
y explicación del flujo del backend.

---------

Co-authored-by: Martin Silva <martin.s@lightit.io>

Author: AgustinPose

.env.example

@@ -6,6 +6,12 @@ POSTGRES_USER=postgres
 POSTGRES_PASSWORD=postgres
 POSTGRES_DB=ithaka
 
+# Auth para endpoints administrativos (documents create/upload/delete)
+# Opcion simple:
+# ADMIN_API_TOKEN=pon_un_token_largo_y_aleatorio
+# Opcion con roles (formato token:rol separados por coma):
+# AUTH_TOKENS=token_admin_1:admin,token_lector_1:reader
+
 # Other environment variables (add as needed)
 # TWILIO_ACCOUNT_SID=your_twilio_sid
 # TWILIO_AUTH_TOKEN=your_twilio_token

Dockerfile

@@ -10,17 +10,20 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
 # Set work directory
 WORKDIR /app
 
+# Pin uv to a trusted version; bump deliberately during dependency maintenance.
+ARG UV_VERSION=0.5.31
+
 # Install system dependencies
 RUN apt-get update \
     && apt-get install -y --no-install-recommends \
         build-essential \
         curl \
     && rm -rf /var/lib/apt/lists/*
 
-# Install Python dependencies
+# Install Python dependencies with uv
 COPY requirements.txt .
-RUN pip install --no-cache-dir --upgrade pip \
-    && pip install --no-cache-dir -r requirements.txt
+RUN pip install --no-cache-dir "uv==${UV_VERSION}" \
+    && uv pip install --system -r requirements.txt
 
 # Copy project
 COPY . .

README.md

@@ -203,7 +203,7 @@ print(result)
 
 ### Error: "No module named 'langchain'"
 ```bash
-pip install -r requirements.txt
+uv pip install -r requirements.txt
 ```
 
 ### Error: "Extension vector does not exist"
@@ -248,7 +248,7 @@ Verificar `DATABASE_URL` en `.env`
 Asegúrate de tener las dependencias necesarias:
 
 ```
-pip install -r requirements.txt
+uv pip install -r requirements.txt
 ```
 
 ## 2. Configurar variables de entorno

app/api/v1/documents.py

@@ -0,0 +1,167 @@
+from fastapi import APIRouter, Depends, File, HTTPException, Query, UploadFile
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.v1.schemas.documents import (
+    DocumentCreate,
+    DocumentResponse,
+    DocumentUploadResponse,
+)
+from app.db.config.database import get_async_session
+from app.db.models import FAQEmbedding
+from app.security.auth import AuthUser, require_admin_user
+from app.services.document_ingestion_service import document_ingestion_service
+from app.services.embedding_service import embedding_service
+
+router = APIRouter()
+
+
+@router.post("/documents", response_model=DocumentResponse, status_code=201)
+async def create_document(
+        document: DocumentCreate,
+        _current_user: AuthUser = Depends(require_admin_user),
+        session: AsyncSession = Depends(get_async_session)
+) -> DocumentResponse:
+    try:
+        created = await embedding_service.add_faq_embedding(
+            question=document.question,
+            answer=document.answer,
+            session=session
+        )
+
+        if created is None:
+            raise HTTPException(
+                status_code=500,
+                detail="No se pudo crear el documento y su embedding"
+            )
+
+        return DocumentResponse(
+            id=created.id,
+            question=created.question,
+            answer=created.answer,
+            created_at=created.created_at
+        )
+    except HTTPException:
+        raise
+    except Exception:
+        raise HTTPException(status_code=500, detail="Error creando documento")
+
+
+@router.post("/documents/upload", response_model=DocumentUploadResponse, status_code=201)
+async def upload_document(
+        file: UploadFile = File(...),
+        chunk_size: int = Query(1200, ge=200, le=4000),
+        chunk_overlap: int = Query(150, ge=0, le=1000),
+        _current_user: AuthUser = Depends(require_admin_user),
+        session: AsyncSession = Depends(get_async_session)
+) -> DocumentUploadResponse:
+    if not file.filename:
+        raise HTTPException(status_code=400, detail="Archivo sin nombre")
+
+    if chunk_overlap >= chunk_size:
+        raise HTTPException(
+            status_code=400,
+            detail="chunk_overlap debe ser menor que chunk_size"
+        )
+    if chunk_overlap * 2 >= chunk_size:
+        raise HTTPException(
+            status_code=400,
+            detail="chunk_overlap debe ser menor al 50% de chunk_size"
+        )
+
+    content = await file.read()
+    if not content:
+        raise HTTPException(status_code=400, detail="Archivo vacio")
+
+    if len(content) > document_ingestion_service.max_file_size_bytes:
+        raise HTTPException(status_code=400, detail="Archivo demasiado grande (max 20MB)")
+
+    file_type, text = document_ingestion_service.extract_file_text(file.filename, content)
+    chunks = document_ingestion_service.split_text(
+        text,
+        chunk_size=chunk_size,
+        chunk_overlap=chunk_overlap,
+    )
+
+    if not chunks:
+        raise HTTPException(status_code=400, detail="No se encontro texto util en el archivo")
+
+    created_ids: list[int] = []
+    total = len(chunks)
+
+    try:
+        for index, chunk in enumerate(chunks, start=1):
+            title = f"{file.filename} - fragmento {index}/{total}"
+            combined_text = f"Pregunta: {title}\nRespuesta: {chunk}"
+            vector = await embedding_service.generate_embedding(combined_text)
+            item = FAQEmbedding(question=title, answer=chunk, embedding=vector)
+            session.add(item)
+            await session.flush()
+            created_ids.append(item.id)
+
+        await session.commit()
+    except Exception:
+        await session.rollback()
+        raise HTTPException(status_code=500, detail="Error procesando el archivo")
+
+    return DocumentUploadResponse(
+        filename=file.filename,
+        file_type=file_type,
+        chunks_created=len(created_ids),
+        document_ids=created_ids
+    )
+
+
+@router.get("/documents", response_model=list[DocumentResponse])
+async def list_documents(
+        limit: int = Query(50, ge=1, le=200),
+        offset: int = Query(0, ge=0),
+        session: AsyncSession = Depends(get_async_session)
+) -> list[DocumentResponse]:
+    try:
+        stmt = (
+            select(FAQEmbedding)
+            .order_by(FAQEmbedding.created_at.desc())
+            .limit(limit)
+            .offset(offset)
+        )
+
+        result = await session.execute(stmt)
+        documents = result.scalars().all()
+
+        return [
+            DocumentResponse(
+                id=document.id,
+                question=document.question,
+                answer=document.answer,
+                created_at=document.created_at
+            ) for document in documents
+        ]
+    except Exception:
+        raise HTTPException(status_code=500, detail="Error listando documentos")
+
+
+@router.delete("/documents/{document_id}")
+async def delete_document(
+        document_id: int,
+        _current_user: AuthUser = Depends(require_admin_user),
+        session: AsyncSession = Depends(get_async_session)
+) -> dict:
+    try:
+        result = await session.execute(
+            select(FAQEmbedding).where(FAQEmbedding.id == document_id)
+        )
+        document = result.scalar_one_or_none()
+
+        if document is None:
+            raise HTTPException(status_code=404, detail="Documento no encontrado")
+
+        await session.delete(document)
+        await session.commit()
+
+        return {"message": f"Documento {document_id} eliminado correctamente"}
+    except HTTPException:
+        raise
+    except Exception:
+        await session.rollback()
+        raise HTTPException(status_code=500, detail="Error eliminando documento")

app/api/v1/schemas/__init__.py

@@ -0,0 +1 @@
+

app/api/v1/schemas/documents.py

@@ -0,0 +1,23 @@
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class DocumentCreate(BaseModel):
+    question: str = Field(..., min_length=3, description="Pregunta o titulo del documento")
+    answer: str = Field(..., min_length=3, description="Respuesta o contenido del documento")
+
+
+class DocumentResponse(BaseModel):
+    id: int
+    question: str
+    answer: str
+    created_at: Optional[datetime]
+
+
+class DocumentUploadResponse(BaseModel):
+    filename: str
+    file_type: str
+    chunks_created: int
+    document_ids: list[int]

app/db/config/create_tables.py

@@ -4,6 +4,9 @@
 from sqlalchemy import text
 
 from app.db.config.database import Base, engine
+from app.db import models  # noqa: F401 - needed so SQLAlchemy registers model metadata
+
+DATABASE_URL = os.getenv("DATABASE_URL", "")
 
 DATABASE_URL = os.getenv("DATABASE_URL", "")
 
@@ -16,4 +19,4 @@ async def create_tables():
         await conn.run_sync(Base.metadata.create_all)
 
 if __name__ == "__main__":
-    asyncio.run(create_tables())
+    asyncio.run(create_tables())

app/main.py

@@ -14,6 +14,7 @@
 
 from app.api.v1.conversations import router as conversations_router
 from app.api.v1.copilotkit_endpoint import router as copilotkit_router
+from app.api.v1.documents import router as documents_router
 from app.api.v1.scoring import router as scoring_router
 
 v1 = '/api/v1'
@@ -30,7 +31,8 @@
     allow_headers=["*"],
 )
 
-app.include_router(conversations_router)
+app.include_router(conversations_router, prefix=v1, tags=["Conversations"])
+app.include_router(documents_router, prefix=v1, tags=["Documents"])
 app.include_router(scoring_router, prefix=v1, tags=["Scoring"])
 app.include_router(copilotkit_router, prefix=v1, tags=["CopilotKit"])
 

app/security/auth.py

@@ -0,0 +1,78 @@
+import os
+import secrets
+from dataclasses import dataclass
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+bearer_scheme = HTTPBearer(auto_error=False)
+
+
+@dataclass(frozen=True)
+class AuthUser:
+    role: str
+
+
+def _load_token_roles() -> list[tuple[str, str]]:
+    """
+    Carga tokens desde variables de entorno.
+    Formatos soportados:
+    - ADMIN_API_TOKEN=<token_admin>
+    - AUTH_TOKENS=<token1>:<rol1>,<token2>:<rol2>
+    """
+    token_roles: list[tuple[str, str]] = []
+
+    admin_token = os.getenv("ADMIN_API_TOKEN", "").strip()
+    if admin_token:
+        token_roles.append((admin_token, "admin"))
+
+    raw_auth_tokens = os.getenv("AUTH_TOKENS", "").strip()
+    if raw_auth_tokens:
+        for pair in raw_auth_tokens.split(","):
+            token_and_role = pair.strip()
+            if not token_and_role or ":" not in token_and_role:
+                continue
+            token, role = token_and_role.split(":", 1)
+            token = token.strip()
+            role = role.strip().lower()
+            if token and role:
+                token_roles.append((token, role))
+
+    return token_roles
+
+
+def _resolve_user_from_token(token: str) -> AuthUser | None:
+    for expected_token, role in _load_token_roles():
+        if secrets.compare_digest(token, expected_token):
+            return AuthUser(role=role)
+    return None
+
+
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials | None = Depends(bearer_scheme),
+) -> AuthUser:
+    if credentials is None or credentials.scheme.lower() != "bearer":
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="No autenticado",
+        )
+
+    user = _resolve_user_from_token(credentials.credentials)
+    if user is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Token invalido",
+        )
+
+    return user
+
+
+async def require_admin_user(
+    user: AuthUser = Depends(get_current_user),
+) -> AuthUser:
+    if user.role != "admin":
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Permisos insuficientes. Se requiere rol admin",
+        )
+    return user