documentacion añadida

api_ner.py

@@ -4,66 +4,77 @@
 FastAPI endpoint para el proyecto lanc-ner
 Recibe un archivo .txt y devuelve las anotaciones NER en formato JSON.
 
-Uso:
-    uvicorn api_ner:app --host 0.0.0.0 --port 8000 --reload
+Autenticación: Bearer token via variable de entorno API_TOKEN.
 
-Endpoint:
-    POST /annotate
-    - Body: multipart/form-data con campo "file" (archivo .txt)
-    - Respuesta: JSON con anotaciones NER
+Uso:
+    export API_TOKEN="mi-token-secreto"
+    uvicorn api_ner:app --host 0.0.0.0 --port 7860 --reload
 """
 
-from fastapi import FastAPI, File, UploadFile, HTTPException
-from fastapi.responses import JSONResponse
+from fastapi import FastAPI, File, UploadFile, HTTPException, Depends, Security
+from fastapi.responses import JSONResponse, HTMLResponse
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from fastapi.openapi.utils import get_openapi
 import spacy
 from spacy import displacy
 import os
 import logging
-from typing import Optional
 
-# ── Logging ──────────────────────────────────────────────────────────────────
+# ── Logging ───────────────────────────────────────────────────────────────────
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
+# ── Configuración ─────────────────────────────────────────────────────────────
+NLP_MODEL_PATH = os.getenv("NER_MODEL", "en_core_web_sm")
+API_TOKEN      = os.getenv("API_TOKEN", "")          # obligatorio en producción
+
+if not API_TOKEN:
+    logger.warning("⚠️  API_TOKEN no definido — la API está desprotegida.")
+
 # ── App ───────────────────────────────────────────────────────────────────────
 app = FastAPI(
     title="Lancaster NER API",
-    description="Recibe un documento .txt y devuelve sus anotaciones NER.",
-    version="1.0.0",
+    description=(
+        "API REST para detección de entidades nombradas (NER) basada en spaCy.\n\n"
+        "**Autenticación:** todos los endpoints protegidos requieren un "
+        "`Authorization: Bearer <token>` en la cabecera.\n\n"
+        "Consulta `/docs` para la documentación interactiva (Swagger UI) "
+        "o `/redoc` para la versión ReDoc."
+    ),
+    version="1.1.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
 )
 
-# ── Carga del modelo spaCy ────────────────────────────────────────────────────
-# Ajusta el nombre del modelo al que uses en tu proyecto (lanc-ner).
-# Si tienes un modelo entrenado propio en ./models/, cámbialo aquí:
-#   NLP_MODEL_PATH = "./models/mi_modelo"
-NLP_MODEL_PATH = os.getenv("NER_MODEL", "en_core_web_sm")
-
+# ── Modelo spaCy ──────────────────────────────────────────────────────────────
 try:
     nlp = spacy.load(NLP_MODEL_PATH)
     logger.info(f"Modelo cargado: {NLP_MODEL_PATH}")
 except OSError:
-    logger.error(
-        f"No se encontró el modelo '{NLP_MODEL_PATH}'. "
-        "Ejecuta: python -m spacy download en_core_web_sm"
-    )
+    logger.error(f"Modelo '{NLP_MODEL_PATH}' no encontrado.")
     nlp = None
 
+# ── Seguridad: Bearer token ───────────────────────────────────────────────────
+bearer_scheme = HTTPBearer(auto_error=True)
+
+def verify_token(credentials: HTTPAuthorizationCredentials = Security(bearer_scheme)):
+    """Valida el Bearer token contra la variable de entorno API_TOKEN."""
+    if API_TOKEN and credentials.credentials != API_TOKEN:
+        raise HTTPException(
+            status_code=401,
+            detail="Token inválido o expirado.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return credentials.credentials
 
-# ── Función NER (misma lógica que views/NER.py del repo) ─────────────────────
+
+# ── Función NER ───────────────────────────────────────────────────────────────
 def run_ner(text: str) -> dict:
-    """
-    Aplica el pipeline NER de spaCy sobre el texto y devuelve
-    un diccionario con:
-      - entities : lista de entidades detectadas
-      - tokens   : lista de todos los tokens con sus etiquetas IOB
-      - html     : visualización HTML (displaCy) — opcional
-    """
     if nlp is None:
         raise RuntimeError("El modelo NLP no está disponible.")
 
     doc = nlp(text)
 
-    # Entidades detectadas
     entities = [
         {
             "text": ent.text,
@@ -75,7 +86,6 @@ def run_ner(text: str) -> dict:
         for ent in doc.ents
     ]
 
-    # Tokens con etiquetas IOB
     tokens = [
         {
             "token": token.text,
@@ -88,7 +98,6 @@ def run_ner(text: str) -> dict:
         for token in doc
     ]
 
-    # Visualización HTML de displaCy (útil para depuración/front)
     html = displacy.render(doc, style="ent", page=False, minify=True)
 
     return {
@@ -101,71 +110,98 @@ def run_ner(text: str) -> dict:
 
 # ── Endpoints ─────────────────────────────────────────────────────────────────
 
-@app.get("/", tags=["Health"])
+@app.get(
+    "/",
+    tags=["Health"],
+    summary="Health check",
+    response_description="Estado de la API y del modelo cargado.",
+)
 def health_check():
-    """Comprueba que la API está en marcha."""
-    model_status = "loaded" if nlp is not None else "not loaded"
-    return {"status": "ok", "model": NLP_MODEL_PATH, "model_status": model_status}
+    """
+    Comprueba que la API está en marcha.  
+    **No requiere autenticación.**
+    """
+    return {
+        "status": "ok",
+        "model": NLP_MODEL_PATH,
+        "model_status": "loaded" if nlp is not None else "not loaded",
+        "auth_enabled": bool(API_TOKEN),
+    }
 
 
-@app.post("/annotate", tags=["NER"])
-async def annotate(file: UploadFile = File(..., description="Archivo .txt a anotar")):
+@app.post(
+    "/annotate",
+    tags=["NER"],
+    summary="Anotar documento .txt",
+    response_description="Entidades NER detectadas, tokens y visualización HTML.",
+)
+async def annotate(
+    file: UploadFile = File(..., description="Archivo de texto plano (.txt) a anotar."),
+    token: str = Depends(verify_token),
+):
     """
-    Recibe un archivo de texto plano (.txt) y devuelve las anotaciones
-    NER producidas por el modelo spaCy configurado en el proyecto.
+    Recibe un archivo `.txt` y devuelve sus anotaciones NER.
 
-    **Respuesta JSON:**
+    **Cabecera requerida:**
+    ```
+    Authorization: Bearer <tu-token>
+    ```
+
+    **Respuesta:**
     ```json
     {
       "filename": "documento.txt",
-      "num_entities": 3,
+      "num_entities": 2,
       "entities": [
-        {"text": "London", "label": "GPE", "label_description": "Countries, cities, states",
-         "start": 5, "end": 11}
+        {
+          "text": "London",
+          "label": "GPE",
+          "label_description": "Countries, cities, states",
+          "start": 5,
+          "end": 11
+        }
       ],
       "tokens": [...],
       "html_visualization": "<div>...</div>"
     }
     ```
     """
-    # Validación del tipo de archivo
     if not file.filename.lower().endswith(".txt"):
-        raise HTTPException(
-            status_code=415,
-            detail="Solo se aceptan archivos .txt",
-        )
+        raise HTTPException(status_code=415, detail="Solo se aceptan archivos .txt.")
 
-    # Lectura del contenido
     try:
-        content_bytes = await file.read()
-        text = content_bytes.decode("utf-8")
+        text = (await file.read()).decode("utf-8")
     except UnicodeDecodeError:
-        raise HTTPException(
-            status_code=422,
-            detail="No se pudo decodificar el archivo como UTF-8.",
-        )
+        raise HTTPException(status_code=422, detail="El archivo no es UTF-8 válido.")
 
     if not text.strip():
-        raise HTTPException(
-            status_code=422,
-            detail="El archivo está vacío.",
-        )
+        raise HTTPException(status_code=422, detail="El archivo está vacío.")
 
-    # NER
     try:
         result = run_ner(text)
     except RuntimeError as e:
         raise HTTPException(status_code=503, detail=str(e))
 
-    return JSONResponse(
-        content={"filename": file.filename, **result}
-    )
+    return JSONResponse(content={"filename": file.filename, **result})
 
 
-@app.post("/annotate/text", tags=["NER"])
-async def annotate_text(payload: dict):
+@app.post(
+    "/annotate/text",
+    tags=["NER"],
+    summary="Anotar texto plano (JSON)",
+    response_description="Entidades NER detectadas, tokens y visualización HTML.",
+)
+async def annotate_text(
+    payload: dict,
+    token: str = Depends(verify_token),
+):
     """
-    Alternativa: envía el texto directamente como JSON.
+    Alternativa a `/annotate`: envía el texto directamente en el body JSON.
+
+    **Cabecera requerida:**
+    ```
+    Authorization: Bearer <tu-token>
+    ```
 
     **Body:**
     ```json
@@ -182,3 +218,157 @@ async def annotate_text(payload: dict):
         raise HTTPException(status_code=503, detail=str(e))
 
     return JSONResponse(content=result)
+
+
+@app.get(
+    "/docu",
+    tags=["Documentación"],
+    summary="Documentación HTML del servicio",
+    response_class=HTMLResponse,
+    include_in_schema=False,   # no aparece en /docs para no duplicar
+)
+def docu():
+    """
+    Página HTML autodocumentada con la descripción completa del servicio,
+    sus endpoints, parámetros y ejemplos de uso.  
+    **No requiere autenticación.**
+    """
+    schema = get_openapi(
+        title=app.title,
+        version=app.version,
+        description=app.description,
+        routes=app.routes,
+    )
+
+    endpoints_html = ""
+    for path, methods in schema.get("paths", {}).items():
+        for method, info in methods.items():
+            badge_color = {
+                "get": "#61affe", "post": "#49cc90",
+                "put": "#fca130", "delete": "#f93e3e",
+            }.get(method.lower(), "#888")
+
+            params_html = ""
+            for p in info.get("parameters", []):
+                params_html += f"""
+                <tr>
+                  <td><code>{p.get('name')}</code></td>
+                  <td>{p.get('in')}</td>
+                  <td>{'✅' if p.get('required') else '—'}</td>
+                  <td>{p.get('description','')}</td>
+                </tr>"""
+
+            params_section = (
+                f"""<table class="param-table">
+                  <thead><tr><th>Nombre</th><th>En</th><th>Req.</th><th>Descripción</th></tr></thead>
+                  <tbody>{params_html}</tbody>
+                </table>"""
+                if params_html else ""
+            )
+
+            endpoints_html += f"""
+            <div class="endpoint">
+              <div class="ep-header">
+                <span class="badge" style="background:{badge_color}">{method.upper()}</span>
+                <span class="ep-path">{path}</span>
+                <span class="ep-summary">{info.get('summary','')}</span>
+              </div>
+              <p class="ep-desc">{info.get('description','').strip().split(chr(10))[0]}</p>
+              {params_section}
+            </div>"""
+
+    html = f"""<!DOCTYPE html>
+<html lang="es">
+<head>
+  <meta charset="UTF-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+  <title>{app.title} — Documentación</title>
+  <style>
+    *, *::before, *::after {{ box-sizing: border-box; margin: 0; padding: 0; }}
+    body {{ font-family: 'Segoe UI', system-ui, sans-serif; background: #f5f7fa;
+            color: #1a1a2e; line-height: 1.6; }}
+    header {{ background: linear-gradient(135deg,#1a1a2e,#16213e);
+              color:#fff; padding: 2.5rem 2rem; }}
+    header h1 {{ font-size: 2rem; margin-bottom:.4rem; }}
+    header p  {{ opacity:.8; font-size:1rem; }}
+    .version  {{ display:inline-block; background:#e94560; color:#fff;
+                 font-size:.75rem; padding:.2rem .6rem; border-radius:12px;
+                 margin-left:.6rem; vertical-align:middle; }}
+    main {{ max-width: 860px; margin: 2rem auto; padding: 0 1rem 4rem; }}
+    section {{ margin-bottom: 2.5rem; }}
+    h2 {{ font-size: 1.25rem; border-bottom: 2px solid #e94560;
+          padding-bottom:.4rem; margin-bottom:1rem; color:#16213e; }}
+    .auth-box {{ background:#fff3cd; border-left:4px solid #ffc107;
+                 padding:1rem 1.2rem; border-radius:6px; margin-bottom:1.5rem; }}
+    .auth-box code {{ background:#ffe69c; padding:.1rem .4rem; border-radius:3px; }}
+    .endpoint {{ background:#fff; border:1px solid #e0e4ef; border-radius:8px;
+                 padding:1.2rem 1.4rem; margin-bottom:1rem;
+                 box-shadow:0 1px 4px rgba(0,0,0,.06); }}
+    .ep-header {{ display:flex; align-items:center; gap:.8rem; flex-wrap:wrap;
+                  margin-bottom:.5rem; }}
+    .badge {{ color:#fff; font-size:.7rem; font-weight:700; padding:.25rem .6rem;
+              border-radius:4px; letter-spacing:.05em; }}
+    .ep-path {{ font-family:monospace; font-size:1rem; font-weight:600; }}
+    .ep-summary {{ color:#555; font-size:.9rem; }}
+    .ep-desc {{ color:#444; font-size:.9rem; margin-bottom:.6rem; }}
+    .param-table {{ width:100%; border-collapse:collapse; font-size:.85rem; margin-top:.5rem; }}
+    .param-table th {{ background:#f0f2f8; text-align:left;
+                       padding:.4rem .6rem; border:1px solid #dde; }}
+    .param-table td {{ padding:.4rem .6rem; border:1px solid #eef; }}
+    pre {{ background:#1e2235; color:#cdd6f4; padding:1rem; border-radius:6px;
+           overflow-x:auto; font-size:.85rem; margin-top:.5rem; }}
+    .links {{ display:flex; gap:1rem; flex-wrap:wrap; }}
+    .links a {{ display:inline-block; background:#16213e; color:#fff; text-decoration:none;
+                padding:.5rem 1.1rem; border-radius:6px; font-size:.9rem; }}
+    .links a:hover {{ background:#e94560; }}
+  </style>
+</head>
+<body>
+<header>
+  <h1>{app.title} <span class="version">v{app.version}</span></h1>
+  <p>Detección de entidades nombradas (NER) sobre documentos de texto.</p>
+</header>
+<main>
+
+  <section>
+    <h2>Documentación interactiva</h2>
+    <div class="links">
+      <a href="/docs">Swagger UI</a>
+      <a href="/redoc">ReDoc</a>
+    </div>
+  </section>
+
+  <section>
+    <h2>Autenticación</h2>
+    <div class="auth-box">
+      Todos los endpoints de anotación requieren un <strong>Bearer token</strong>
+      en la cabecera HTTP:<br/><br/>
+      <code>Authorization: Bearer &lt;tu-token&gt;</code><br/><br/>
+      El token se configura mediante la variable de entorno <code>API_TOKEN</code>
+      en el Space de Hugging Face.
+    </div>
+  </section>
+
+  <section>
+    <h2>Endpoints</h2>
+    {endpoints_html}
+  </section>
+
+  <section>
+    <h2>Ejemplos de uso</h2>
+    <p><strong>Subir archivo .txt:</strong></p>
+    <pre>curl -X POST "https://&lt;space&gt;.hf.space/annotate" \\
+     -H "Authorization: Bearer &lt;token&gt;" \\
+     -F "file=@documento.txt"</pre>
+
+    <p style="margin-top:1rem"><strong>Enviar texto como JSON:</strong></p>
+    <pre>curl -X POST "https://&lt;space&gt;.hf.space/annotate/text" \\
+     -H "Authorization: Bearer &lt;token&gt;" \\
+     -H "Content-Type: application/json" \\
+     -d '{{"text": "John lives in New York."}}'</pre>
+  </section>
+
+</main>
+</body>
+</html>"""
+    return HTMLResponse(content=html)