Indice de PDF para agentes IA

​

Ventajas

​

Cuando NO usarlo

​

Como funciona internamente

1. El backend descarga el PDF (1 vez, no se cachea).
2. Hace sample de 32 paginas distribuidas (inicio, medio, final) para construir el modelo de fuentes.
3. Recorre todas las paginas leyendo solo la cabeza (primeros 8 spans) para detectar headings.
4. Detecta cabeceras/pies repetidos en el 12% superior/inferior de cada pagina.
5. Devuelve JSON ~5-15KB con todo el mapa.
6. Borra el temporal y termina.

​

Patron de uso para agentes IA

​

Patron 1 - busqueda por seccion

# Agente pregunta: "Cual fue el revenue en Q3?"
spine = index_pdf(url)

# Buscar seccion relevante por titulo
target_section = next(
    s for s in spine["sections"]
    if "Revenue" in s["text"] or "Financial" in s["text"]
)
next_section = next(
    (s for s in spine["sections"] if s["page"] > target_section["page"]),
    None
)
end_page = (next_section["page"] - 1) if next_section else spine["page_count"]

# Pedir SOLO esa seccion
markdown = convert(url, pages=f"{target_section['page']}-{end_page}")
# ~5-15K tokens en vez de 250K

​

Patron 2 - busqueda por densidad

# Agente pregunta: "Hay graficos o tablas en este documento?"
spine = index_pdf(url)

# Paginas con muy pocos chars probablemente son visuales
visual_pages = [p["page"] for p in spine["pages"] if p["chars"] < 200]
if visual_pages:
    markdown = convert(url, pages=",".join(map(str, visual_pages[:5])))

​

Patron 3 - navegacion guiada al usuario

# Mostrar al usuario un TOC interactivo antes de descargar
spine = index_pdf(url)
toc = [
    {"page": s["page"], "title": s["text"], "level": s["level"]}
    for s in spine["sections"]
]
# Usuario hace clic en seccion -> request a /convert/from-url con esa pagina

​

Comparativa real

​

Limitaciones honestas

• Detection heuristica. Sections se detectan por tamano de fuente + numeracion + bold. No es semantica real. Funciona muy bien con documentos estructurados, peor con PDFs free-form.
• Tablas no detectadas v1. Solo headings + body chars + headers/footers repetidos. Para tablas usa mode=balanced.
• pages[] truncado a 200. PDFs >200 paginas exponen pages_truncated: true; el agente debe navegar por sections[].
• Sin cache servidor: cada llamada re-descarga el PDF. Si vas a hacer muchas, conserva el content_hash en el cliente para reusarlo via cache_key= en /convert/from-url.

​

Compatibilidad con otros endpoints

• El spine te dice que pedir. La extraccion real va siempre por /convert/from-url (o cualquier otro endpoint de conversion) con pages=.
• mode=ultra_fast + pages= = combinacion mas rapida.