Pro edición

Extracción — Referencia detallada

De un vistazo

Esta página es la referencia a nivel de contrato de NextPDF\Pro\Extraction. El módulo contiene cinco símbolos públicos: dos extractores (CitedTextExtractor, CitedTableExtractor) y tres objetos de valor inmutables (CitedTextBlock, CitedTableBlock, CitedTableCell). Ambos extractores consumen un NextPDF\Ast\AstDocument ya analizado; ninguno lee los bytes crudos del PDF. La extracción es determinista y estructural. No existe ningún paso semántico, de incrustación (embedding) ni de clasificación en ninguna parte de este módulo. La vista orientada a tareas se encuentra en la página de capacidad.

Disponibilidad y licencias

Esta capacidad se distribuye en NextPDF Pro (nextpdf/pro) y se activa con un envoltorio de licencia de nivel Pro. Un despliegue sin ese derecho no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Ningún indicador de capacidad en tiempo de ejecución restringe este módulo. Las clases están disponibles siempre que nextpdf/pro esté instalado y licenciado.

Superficie de la API pública

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
`CitedTextExtractor::__construct()`	`?int $maxTokensPerChunk = null`, `int $minChunkLength = 10`	Sin presupuesto de tokens; el texto recortado por debajo de 10 bytes se descarta	`CitedTextExtractor`	No lanza	Un presupuesto `null` significa un bloque por nodo.
`CitedTextExtractor::extract()`	`AstDocument $document`	Recorrido en profundidad; un bloque por nodo de texto que cumple, dividido según el presupuesto de tokens	`list<CitedTextBlock>`	No lanza	Determinista; `chunkIndex` se reinicia a 0 en cada llamada.
`CitedTextBlock`	cinco campos readonly	Objeto de valor inmutable; sin método serializador	—	No lanza	Claves de `metadata`: `nodeType`, `pageIndex`, más opcionalmente `structType`, `lang`, `alt`, `untagged`.
`CitedTextBlock::estimatedTokens()`	ninguno	`ceil(byte length / 4)`	`int`	No lanza	Heurística de presupuesto; no es un tokenizador.
`CitedTableExtractor::extract()`	`AstDocument $document`	Recopila los nodos `Table` más externos en orden de documento	`list<CitedTableBlock>`	No lanza	Nunca desciende a un subárbol de tabla.
`CitedTableBlock`	cinco campos readonly	Matriz de celdas rectangular e inmutable en orden por filas	—	No lanza	Las filas cortas se rellenan por la derecha en el momento de la extracción.
`CitedTableBlock::toArray()`	ninguno	Serializa a un array plano en snake_case	`array<string, mixed>`	No lanza	Las celdas anidadas se serializan mediante `CitedTableCell::toArray()`.
`CitedTableCell`	siete campos readonly	Registro de celda inmutable con coordenadas de cita	—	No lanza	Las celdas de relleno llevan un `nodeId` vacío y confianza 0.0.
`CitedTableCell::toArray()`	ninguno	Serializa a un array plano en snake_case; `bbox` se anida o es `null`	`array<string, mixed>`	No lanza	—

final class CitedTextExtractor

public function __construct(
    private readonly ?int $maxTokensPerChunk = null,
    private readonly int $minChunkLength = 10,
)

public function extract(AstDocument $document): array

final class CitedTableExtractor

public function extract(AstDocument $document): array

final readonly class CitedTextBlock

public function __construct(
    public string $text,
    public CitationAnchor $anchor,
    public float $confidence,
    public int $chunkIndex,
    public array $metadata,
)

public function estimatedTokens(): int

final readonly class CitedTableBlock

public function __construct(
    public readonly string $nodeId,
    public readonly int    $pageIndex,
    public readonly int    $rowCount,
    public readonly int    $colCount,
    public readonly array  $matrix,
)

public function toArray(): array

final readonly class CitedTableCell

public function __construct(
    public readonly string       $nodeId,
    public readonly int          $row,
    public readonly int          $col,
    public readonly ?string      $textContent,
    public readonly ?BoundingBox $bbox,
    public readonly int          $pageIndex,
    public readonly float        $confidence,
)

public function toArray(): array

Contrato de comportamiento

Selección de nodos. CitedTextExtractor emite bloques para los nodos cuyo tipo es Paragraph, Heading, ListItem, TableCell, Code o Annotation. Un nodo con texto null se omite. Un nodo se emite únicamente cuando la longitud de su texto recortado es al menos minChunkLength (por defecto 10). Todas las longitudes son longitudes en bytes.
Orden de recorrido. El recorrido es en profundidad desde la raíz del documento. Un nodo que cumple se emite antes de visitar sus hijos. chunkIndex se incrementa a lo largo de todo el recorrido del documento y se reinicia a 0 en cada llamada a extract().
Fragmentación. Con maxTokensPerChunk sin definir, cada nodo produce un bloque. Cuando se define, el texto más largo que maxTokensPerChunk * 4 bytes se divide. El divisor prefiere un límite de oración —un salto de línea, o un punto seguido de un espacio— hallado explorando hacia atrás como máximo 200 bytes desde el corte preferido. En caso contrario, corta de forma abrupta en el presupuesto. Los espacios posteriores a un corte se omiten; los fragmentos vacíos se descartan.
Ancla de cita. El CitationAnchor de cada bloque lleva el id del nodo, el índice de página, un recuadro delimitador, una confianza y un hash de contenido null. Los nodos sin recuadro delimitador reciben un centinela compartido de área cero, BoundingBox(0, 0, 0, 0), de modo que el ancla es siempre estructuralmente válida.
Confianza del texto. La confianza lee el atributo confidence del nodo cuando es un int o un float; el valor por defecto es 1.0. Los valores de atributo no numéricos recurren al valor por defecto.
Metadatos del bloque. metadata siempre lleva nodeType y pageIndex. structType, lang y alt se copian cuando están presentes en el nodo. untagged se establece en true cuando el nodo lleva un atributo untagged.
Selección de tablas. CitedTableExtractor recopila únicamente los nodos Table más externos, en orden de documento. Una vez procesado un nodo Table, su subárbol no se vuelve a examinar; las tablas anidadas no se admiten.
Forma de la matriz. Las filas provienen de los hijos TableRow; las celdas provienen de sus hijos TableCell. Otros tipos de hijo se ignoran. colCount es el número máximo de celdas entre todas las filas. Las filas cortas se rellenan por la derecha hasta colCount con celdas sintéticas: nodeId vacío, texto null, bbox null, el índice de página de la tabla, confianza 0.0. Una tabla sin filas o sin columnas no produce ningún bloque.
Confianza de celda. La confianza de una celda real lee su atributo confidence cuando es un int o un float; el valor por defecto es 0.8. Los bloques de texto usan 1.0 por defecto; las celdas de tabla usan 0.8 por defecto.
Mapeo de estructura. La jerarquía recorrida se corresponde con el modelo de estructura lógica del PDF (ISO 32000-2:2020 §14.7). Las filas de tabla se corresponden con el elemento de estructura TR (§14.8) cuando el origen está etiquetado.

Casos límite y modos de fallo

Nada en esta superficie lanza. Ambos métodos extract() devuelven una lista vacía para un documento sin nodos que cumplan.
El recuadro delimitador de área cero es un centinela singleton compartido. Los invocadores que necesiten una región real deben detectarlo explícitamente: width === 0.0 && height === 0.0.
Todas las comprobaciones de longitud y las divisiones son en bytes. Cuando no existe ningún límite de oración dentro de la ventana de 200 bytes, un corte abrupto puede caer dentro de una secuencia UTF-8 multibyte.
La cifra de 4 bytes por token es solo una heurística de presupuesto. No es un tokenizador y no coincide con la tokenización de ningún modelo concreto. estimatedTokens() usa la misma heurística.
Una cadena numérica en un atributo confidence no se convierte; se aplica el valor por defecto. Solo se respetan los valores int y float.
La omisión de espacios en blanco tras un corte elimina únicamente espacios simples. Las tabulaciones y los saltos de línea al inicio de un fragmento se conservan.
El texto de TableCell se extrae dos veces por diseño: como bloques de texto por CitedTextExtractor, y dentro de las matrices por CitedTableExtractor. Deduplicar aguas abajo al ejecutar ambos extractores sobre un mismo documento.
Las celdas de relleno son identificables por un nodeId vacío y una confianza 0.0. Una celda real pero vacía conserva su nodeId no vacío.
No ocurre ninguna operación criptográfica en este módulo, por lo que no hay comportamiento específico del modo FIPS.

Conformidad

Cuando el documento de origen está etiquetado, el AST refleja la jerarquía de estructura lógica de ISO 32000-2:2020 §14.7, y los nodos Table/TableRow se corresponden con los elementos de estructura Table/TR de §14.8. La calidad de la extracción está limitada por la calidad del etiquetado; el contenido sin etiquetar produce nodos menos numerosos o más gruesos.

Estas son afirmaciones de alineación estructural, no resultados de pruebas de conformidad. NextPDF no posee ninguna certificación ni la otorga. Este módulo no formula ninguna declaración de conformidad propia; consume la estructura que haya producido el subsistema AST de Core.

Notas de desarrollo

Reutilizar una única instancia de CitedTextExtractor entre documentos es seguro de forma secuencial; extract() reinicia chunkIndex antes de cada recorrido.
Ajustar minChunkLength para filtrar nodos de ruido (números de página, tiradas de glifos sueltas) antes de fragmentar, no después.
Para CJK y otros sistemas de escritura multibyte, la heurística basada en bytes sobreestima los tokens; dimensionar maxTokensPerChunk en consecuencia.
CitedTableBlock::toArray() y CitedTableCell::toArray() emiten claves en snake_case para las cadenas de procesamiento JSON. CitedTextBlock no tiene serializador; codificar sus campos manualmente.
El campo contentHash de CitationAnchor es siempre null en esta superficie. Calcular los hashes de contenido aguas abajo cuando la cadena de procesamiento los necesite.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de la API pública admitida. Las rutas de espacio de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de ticket quedan fuera del alcance.