Accelerator — Deep Reference (Gated)

Gated content notice. This page is part of the gated reference surface. Distribution restricted by NDA. Do not mirror to public channels.

At a glance

This page documents the behavior limits, failure modes, and configuration surface of Accelerator beyond the public landing page. It references only the documented NextPDF\Pro\Accelerator public API.

Edition gate

Requires NextPDF Pro, installed via composer require nextpdf/premium. Get a license.

License feature flag

Accelerator has no per-feature license flag. The Pro edition gates the code; the accelerated path is selected at runtime by a sidecar reachability probe. The embedding service and vector index have no PHP fallback and therefore fail closed when the sidecar is unreachable.

Behavior contract

ProAcceleratorProvider exposes four accessors. embedding and optimizer and differ memoize their instances; vectorIndex($collectionId) returns a fresh handle per call bound to the given collection identifier (default "default").

Optimizer path: optimizeBatch(array<string,string> $documents) returns a batch result keyed by the caller’s document identifiers. When the sidecar is reachable the batch is dispatched for parallel image work; on any sidecar error the call degrades to the PHP optimizer running each document sequentially and reports an engine marker of php_fallback in the result metadata. The default optimization level is Balanced.

Differ path: compare(string $sourcePdf, string $targetPdf) parses both documents in parallel via the sidecar when available, then runs the diff algorithm in PHP. The diff result is identical whether or not acceleration was used; only parse latency differs. Any sidecar error falls back to the pure PHP differ.

Embedding path: embed delegates to batchEmbed([$text]) and returns element zero. batchEmbed([]) raises InvalidArgumentException. getDimension returns 384; getModelName returns the all-MiniLM-L6-v2 model identifier. A malformed or count-mismatched sidecar response raises a Spectrum API error rather than returning partial vectors.

Vector index path: build($vectors, $ids) requires equal-length inputs and raises InvalidArgumentException otherwise; an empty input returns without contacting the sidecar. search($queryVector, $topK = 10) returns ranked results with a per-hit rank in metadata. delete($ids) always rejects with a not-implemented error because HNSW does not support per-vector deletion — callers must rebuild. count returns 0 on sidecar unavailability or any error rather than raising.

Public API surface

composer require nextpdf/premium

Public types: ProAcceleratorProvider, AcceleratedOptimizer, AcceleratedDiffer, CpuEmbeddingService (implements the Core EmbeddingServiceInterface), CpuVectorIndex (implements the Core VectorIndexInterface). Behavior depends on the Pro Optimizer and Diff modules and on a Core-provided sidecar client passed by the caller.

Conformance

Accelerator delegates format-affecting work to the Optimizer and Diff modules and asserts no independent format conformance. The RAG corpus was unavailable at authoring time; no external clause identifiers are claimed on this page. Conformance for the delegated work is documented on the Optimizer and Diff reference pages.

Edge cases & FIPS-mode behavior

Sidecar memory is volatile: a restart clears all HNSW collections. Treat index build as idempotent and re-run after restart.
Mixed availability within a single process is supported: the optimizer and differ degrade per call; the embedding and vector services fail closed per call.
This module performs no cryptographic operations and defines no FIPS-specific behavior. FIPS-mode posture is governed by the signing and compliance modules, not here.
A top_k of 0 is used internally only to read collection metadata for count; callers should pass a positive topK for real searches.