DocumentAnalysisService 

class DocumentAnalysisService

Fully qualified name

\Netresearch\NrLlm\Specialized\Document\DocumentAnalysisService

Stateless "understand this document" primitive (ADR-076).

When the resolved provider implements DocumentCapableInterface (Gemini, Claude), the PDF is ingested natively as a Base64 document block in a single chat call — whole-document reasoning. Otherwise the document is rasterized page-by-page with poppler and each page is read by the vision model; the per-page answers are concatenated with [Page N] markers.

analyzeDocument ( string $pdf, string $prompt, ?ChatOptions $options = null) : DocumentAnalysisResult

Analyze a PDF with a custom prompt.

param string $pdf

Raw PDF bytes (must start with the %PDF- header)

param string $prompt

Analysis prompt, applied to the whole document on the native path and to each page on the fallback

param ChatOptions|null $options

Chat options; provider, model, maxTokens, temperature and the budget attribution fields (beUserUid, plannedCost) are passed through to whichever path runs

throws

UnsupportedFormatException when the bytes are not a PDF

throws

ProviderException when no provider is resolvable (no explicit provider and no active default configuration) — the same error a plain chat() call raises

throws

ServiceUnavailableException when the provider lacks native PDF support and poppler is not installed

throws

PdfRasterizationException when rasterization itself fails

Returns

DocumentAnalysisResult with the answer text, the model/provider that produced it, whether the native document path was used, and the rasterized page count

use Netresearch\NrLlm\Service\Option\ChatOptions;
use Netresearch\NrLlm\Specialized\Document\DocumentAnalysisService;

public function __construct(
    private readonly DocumentAnalysisService $documentAnalysis,
) {}

$result = $this->documentAnalysis->analyzeDocument(
    $pdfBytes,
    'List the key obligations defined in this contract.',
    new ChatOptions(maxTokens: 1024),
);

$result->text;                    // the answer
$result->usedNativeDocumentPath;  // true: one whole-document call
$result->rasterizedPageCount;     // pages read on the fallback path