Blame for api_ner.py

#!/usr/bin/env python
# coding: utf-8
"""
FastAPI endpoint para el proyecto lanc-ner
Recibe un archivo .txt y devuelve las anotaciones NER en formato JSON
por línea, con el esquema:
  [
    { "Anotacion": "<línea>", "entities": [
        { "start": int, "end": int, "entity": str, "fields": [str] }
    ]},
    ...
  ]

Autenticación: Bearer token via variable de entorno API_TOKEN.
"""

from fastapi import FastAPI, File, UploadFile, HTTPException, Depends, Security, Query
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

# ── Logging ───────────────────────────────────────────────────────────────────
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# ── Configuración ─────────────────────────────────────────────────────────────
API_TOKEN = os.getenv("API_TOKEN", "")
if not API_TOKEN:
    logger.warning("⚠️  API_TOKEN no definido — la API está desprotegida.")

MODELS = {
    "ruler":    "./models/model_entities_ruler/model-last/",
    "toponyms": "./models/model_toponyms_patterns/model-last/",
}

# ── Carga de modelos ──────────────────────────────────────────────────────────
loaded_models = {}
for name, path in MODELS.items():
    try:
        loaded_models[name] = spacy.load(path)
        logger.info(f"Modelo '{name}' cargado desde {path}")
    except OSError:
        logger.error(f"Modelo '{name}' no encontrado en {path}")

# ── App ───────────────────────────────────────────────────────────────────────
app = FastAPI(
    title="Lancaster NER API",
    description=(
        "API REST para detección de entidades nombradas (NER) basada en spaCy.\n\n"
        "**Modelos disponibles:**\n"
        "- `ruler` — Spacy Ruler (Sentences): entidades generales\n"
        "- `toponyms` — DECM annotations with Paragraphs: topónimos\n\n"
        "**Autenticación:** todos los endpoints de anotación requieren "
        "`Authorization: Bearer <token>` en la cabecera.\n\n"
        "**Formato de salida:** lista de objetos por línea del documento, "
        "con campo `Anotacion` (texto de la línea) y `entities` (entidades detectadas)."
    ),
    version="1.3.0",
    docs_url="/docs",
    redoc_url="/redoc",
)

# ── Seguridad: Bearer token ───────────────────────────────────────────────────
bearer_scheme = HTTPBearer(auto_error=True)

def verify_token(credentials: HTTPAuthorizationCredentials = Security(bearer_scheme)):
    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 ───────────────────────────────────────────────────────────────
def run_ner(text: str, model_name: str) -> list:
    """
    Procesa el texto línea a línea y devuelve una lista con el formato:
    [
      {
        "Anotacion": "<línea>",
        "entities": [
          { "start": int, "end": int, "entity": str, "fields": [str] }
        ]
      },
      ...
    ]
    """
    if model_name not in loaded_models:
        raise HTTPException(
            status_code=400,
            detail=f"Modelo '{model_name}' no disponible. Opciones: {list(loaded_models.keys())}",
        )

    nlp = loaded_models[model_name]
    lines = text.splitlines()
    result = []

    for line in lines:
        doc = nlp(line)
        entities = []
        for ent in doc.ents:
            entities.append({
                "start":  ent.start_char,
                "end":    ent.end_char,
                "entity": ent.label_,
                "fields": [],
            })

        result.append({
            "Anotacion": line,
            "entities":  entities,
        })

    return result


# ── Endpoints ─────────────────────────────────────────────────────────────────

@app.get("/", tags=["Health"], summary="Health check")
def health_check():
    """Estado de la API y modelos cargados. **No requiere autenticación.**"""
    return {
        "status": "ok",
        "auth_enabled": bool(API_TOKEN),
        "models_available": list(loaded_models.keys()),
        "models_missing": [k for k in MODELS if k not in loaded_models],
    }


@app.post(
    "/annotate",
    tags=["NER"],
    summary="Anotar documento .txt",
    response_description="Lista de anotaciones NER por línea del documento.",
)
async def annotate(
    file: UploadFile = File(..., description="Archivo de texto plano (.txt) a anotar."),
    model: str = Query(
        default="ruler",
        description="Modelo NER a usar: `ruler` o `toponyms`.",
        enum=["ruler", "toponyms"],
    ),
    token: str = Depends(verify_token),
):
    """
    Recibe un archivo `.txt` y devuelve una lista de anotaciones NER por línea.

    **Cabecera requerida:**
    ```
    Authorization: Bearer <tu-token>
    ```

    **Formato de respuesta:**
    ```json
    [
      {
        "Anotacion": "Registraron Baltasar Perez y Ernando de Sanctiago vesinos de Sevilla",
        "entities": [
          { "start": 12, "end": 26, "entity": "Persona", "fields": ["Nombre", "Hombre"] },
          { "start": 61, "end": 68, "entity": "Localización", "fields": ["Topónimo"] }
        ]
      }
    ]
    ```
    """
    if not file.filename.lower().endswith(".txt"):
        raise HTTPException(status_code=415, detail="Solo se aceptan archivos .txt.")

    try:
        text = (await file.read()).decode("utf-8")
    except UnicodeDecodeError:
        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.")

    result = run_ner(text, model)
    return JSONResponse(content=result)


@app.post(
    "/annotate/text",
    tags=["NER"],
    summary="Anotar texto plano (JSON)",
    response_description="Lista de anotaciones NER por línea.",
)
async def annotate_text(
    payload: dict,
    model: str = Query(
        default="ruler",
        description="Modelo NER a usar: `ruler` o `toponyms`.",
        enum=["ruler", "toponyms"],
    ),
    token: str = Depends(verify_token),
):
    """
    Envía el texto directamente en el body JSON.

    **Body:**
    ```json
    { "text": "El municipio de Atengo se encuentra en Jalisco." }
    ```
    """
    text = payload.get("text", "").strip()
    if not text:
        raise HTTPException(status_code=422, detail="El campo 'text' está vacío.")

    result = run_ner(text, model)
    return JSONResponse(content=result)


@app.get(
    "/docu",
    tags=["Documentación"],
    summary="Documentación HTML del servicio",
    response_class=HTMLResponse,
    include_in_schema=False,
)
def docu():
    """Página HTML autodocumentada. **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; }}
    .model-box {{ background:#e8f4fd; border-left:4px solid #61affe; padding:1rem 1.2rem; border-radius:6px; margin-bottom:1rem; }}
    .model-box code {{ background:#cce5ff; padding:.1rem .4rem; border-radius:3px; }}
    .format-box {{ background:#f0fff4; border-left:4px solid #49cc90; padding:1rem 1.2rem; border-radius:6px; margin-bottom:1rem; }}
    .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 históricos.</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>Formato de respuesta</h2>
    <div class="format-box">
      El documento se procesa <strong>línea a línea</strong>. Cada línea genera un objeto con:<br/><br/>
      <code>Anotacion</code> — texto original de la línea<br/>
      <code>entities</code> — lista de entidades detectadas con <code>start</code>, <code>end</code>, <code>entity</code> y <code>fields</code>
    </div>
    <pre>[
  {{
    "Anotacion": "Registraron Baltasar Perez y Ernando de Sanctiago vesinos de Sevilla",
    "entities": [
      {{ "start": 12, "end": 26, "entity": "Persona", "fields": ["Nombre", "Hombre"] }},
      {{ "start": 61, "end": 68, "entity": "Localización", "fields": ["Topónimo"] }}
    ]
  }}
]</pre>
  </section>

  <section>
    <h2>Modelos disponibles</h2>
    <div class="model-box">
      <p><code>ruler</code> — <strong>Spacy Ruler (Sentences)</strong><br/>
      Detecta entidades generales con reglas sobre oraciones.</p>
      <br/>
      <p><code>toponyms</code> — <strong>DECM annotations with Paragraphs</strong><br/>
      Especializado en topónimos y anotaciones geográficas por párrafos.</p>
    </div>
  </section>

  <section>
    <h2>Autenticación</h2>
    <div class="auth-box">
      Todos los endpoints de anotación requieren un <strong>Bearer token</strong>:<br/><br/>
      <code>Authorization: Bearer &lt;tu-token&gt;</code>
    </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://alezsd-lancaster-ner-api.hf.space/annotate?model=ruler" \\
     -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://alezsd-lancaster-ner-api.hf.space/annotate/text?model=toponyms" \\
     -H "Authorization: Bearer &lt;token&gt;" \\
     -H "Content-Type: application/json" \\
     -d '{{"text": "El municipio de Atengo se encuentra en Jalisco."}}'</pre>
  </section>

</main>
</body>
</html>"""
    return HTMLResponse(content=html)