> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markpdf.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Indice de PDF para agentes IA

> Patron de uso de /pdf/index + pages= para que tu agente IA pague 20-30x menos tokens en PDFs grandes.

Cuando un agente IA necesita responder sobre un PDF de 500 paginas, lo natural seria convertirlo entero a Markdown y meterlo en el prompt. **Esto es caro**: 250.000 tokens al LLM, segundos de extraccion, y la mayor parte del contenido no se usa.

El patron correcto es **indexar primero, extraer despues solo lo necesario**.

## Ventajas

<Tip>
  * **Tokens al LLM**: 20-30x menos. Cliente IA paga menos.
  * **Latencia**: spine en 300-700ms incluso para PDFs de 500MB.
  * **Coste backend**: extrae solo las paginas pedidas, no las 5000. **Tu factura baja proporcional**.
  * **Sin cache servidor**: el spine viaja al cliente, no se guarda. Respeta privacidad.
  * **Stateless**: el agente decide. No requiere session ni job.
</Tip>

## Cuando NO usarlo

<Warning>
  * **PDFs pequenos** (\<10 paginas): el coste fijo del spine no compensa. Usa `/convert/from-url` directo.
  * **Necesitas el Markdown completo**: salta el indice y pide `/convert/from-url` sin `pages=`.
  * **Agente que no puede tomar decisiones de routing**: necesita logica para mapear pregunta -> secciones.
</Warning>

## 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.

**Coste constante respecto al tamano del PDF**: un PDF de 50 paginas y uno de 5000 tardan casi lo mismo en indexarse.

## Patron de uso para agentes IA

### Patron 1 - busqueda por seccion

```python theme={null}
# 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

```python theme={null}
# 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

```python theme={null}
# 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

PDF de 500 paginas (academic paper, 10MB descomprimido en Markdown):

| Operacion                              | Sin indice |                                  Con indice |
| -------------------------------------- | ---------: | ------------------------------------------: |
| Tokens al LLM (GPT-4o input)           |    250.000 |             **5K spine + 8K seccion = 13K** |
| Coste cliente IA (\$5/1M input tokens) |     \$1.25 |                                  **\$0.07** |
| Tiempo extraccion backend              |        5 s | 0.4 s (spine) + 0.2 s (seccion) = **0.6 s** |
| GB-s Lambda facturados                 |       1.0x |                                   **0.12x** |
| Egress bytes del backend               |      10 MB |     15 KB spine + 20 KB seccion = **35 KB** |

**Cliente IA paga 18x menos. Tu backend factura 8x menos compute.** Ambos ganan.

## 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.

Ver tambien: [POST /pdf/index](/docs/public/es/api/pdf-index), [POST /convert/from-url](/docs/public/es/api/convert-from-url), [Modos](/docs/public/es/concepts/modes) y [Formatos](/docs/public/es/concepts/formats).