Accelerator — Deep Reference

At a glance

This page is the deep reference for the public acceleration surface of NextPDF\Pro\Accelerator. It covers the provider factory, the accelerated batch optimizer, the differ wrapper, and the CPU sidecar services for embedding and vector search. It states parameters, defaults, failure modes, and fallback semantics. Read the Accelerator capability page first for workflow guidance.

Availability & licensing

This capability ships in NextPDF Pro (nextpdf/pro) and activates with a Pro-tier license envelope. A deployment without that entitlement does not load the capability’s classes. Compare editions and get a license.

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

Public API surface

composer require nextpdf/pro:^3

The nextpdf/premium metapackage installs the nextpdf/pro code; this module lives under the NextPDF\Pro\Accelerator namespace.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
ProAcceleratorProvider::__construct	SpectrumClient $client	Binds the provider to a Core sidecar client	ProAcceleratorProvider	Nothing declared	The caller constructs and supplies the client
ProAcceleratorProvider::isAvailable	none	Probes sidecar reachability through the client	bool	Nothing declared	Reachability only; endpoints are probed per call
ProAcceleratorProvider::embedding	none	Returns the memoized embedding service	EmbeddingServiceInterface	Nothing declared	One CpuEmbeddingService instance per provider
ProAcceleratorProvider::vectorIndex	string $collectionId = 'default'	Returns a fresh index handle bound to the collection	VectorIndexInterface	Nothing declared	Not memoized; one handle per call
ProAcceleratorProvider::optimizer	none	Returns the memoized accelerated optimizer	AcceleratedOptimizer	Nothing declared	Constructed with the provider’s client
ProAcceleratorProvider::differ	none	Returns the memoized differ wrapper	AcceleratedDiffer	Nothing declared	Constructed with the provider’s client
AcceleratedOptimizer::__construct	?SpectrumClient $spectrum = null, OptimizationLevel $level = OptimizationLevel::Balanced, ?LoggerInterface $logger = null	Wraps the PHP PdfOptimizer at the given level	AcceleratedOptimizer	Nothing declared	A null client selects the PHP path; a null logger selects NullLogger
AcceleratedOptimizer::optimizeBatch	array<string, string> $documents	Analyzes each document; offloads image work to the sidecar when reachable	BatchResultInterface	SpectrumApiException SPEC-SEC-001 (HTTP 413) on an over-limit batch; per-item error markers in the fallback result	Transport failures after admission degrade to the PHP path
AcceleratedDiffer::__construct	?SpectrumClient $spectrum = null	Retains the optional client for forward compatibility	AcceleratedDiffer	Nothing declared	The client is unused in this release
AcceleratedDiffer::compare	string $sourcePdf, string $targetPdf	Compares two documents fully in PHP	DiffResult	As the Pro PdfDiffer	No sidecar request is issued in this release
AcceleratedDiffer::isSpectrumWired	none	Reports whether a sidecar client was injected	bool	Nothing declared	Wiring state only; issues no request
CpuEmbeddingService::embed	string $text	Delegates to batchEmbed and returns element zero	list<float>	As batchEmbed	384-dimension vector
CpuEmbeddingService::batchEmbed	array $texts	Embeds the batch on the sidecar	list<list<float>>	InvalidArgumentException on an empty batch; SpectrumNotAvailableException when unreachable; SpectrumApiException on a failed, malformed, or count-mismatched response	Never returns partial results
CpuEmbeddingService::getDimension	none	Returns 384	int	Nothing declared	Constant
CpuEmbeddingService::getModelName	none	Returns all-MiniLM-L6-v2	string	Nothing declared	Constant
CpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Binds the handle to one collection	CpuVectorIndex	Nothing declared	One handle per collection identifier
CpuVectorIndex::build	array $vectors, array $ids	Builds the collection index on the sidecar	void	InvalidArgumentException on a length mismatch; SpectrumNotAvailableException when unreachable	An empty input returns without contacting the sidecar
CpuVectorIndex::search	array $queryVector, int $topK = 10	Ranked nearest-neighbor search	list<VectorSearchResult>	SpectrumNotAvailableException when unreachable; SpectrumApiException on an in-band error envelope; JsonException on a malformed body	Per-hit rank in result metadata
CpuVectorIndex::delete	array $ids	Always rejects	void (declared)	Always: SpectrumApiException SPEC-INDEX-004 (HTTP 501)	HNSW has no per-vector deletion; rebuild instead
CpuVectorIndex::count	none	Reads the collection total via a dimensioned probe	int	SpectrumNotAvailableException when unreachable; SpectrumApiException on an error or a malformed count response	Returns 0 only for a confirmed-empty index
CpuVectorIndex::INDEX_DIMENSION	—	Public constant 384	int	—	Matches the embedding dimension

Entry-point signatures

final class ProAcceleratorProvider
{
    public function __construct(
        private readonly SpectrumClient $client,
    )

    public function isAvailable(): bool

    public function embedding(): EmbeddingServiceInterface

    public function vectorIndex(string $collectionId = 'default'): VectorIndexInterface

    public function optimizer(): AcceleratedOptimizer

    public function differ(): AcceleratedDiffer
}

final class AcceleratedOptimizer
{
    public function __construct(
        private readonly ?SpectrumClient $spectrum = null,
        private readonly OptimizationLevel $level = OptimizationLevel::Balanced,
        ?LoggerInterface $logger = null,
    )

    public function optimizeBatch(array $documents): BatchResultInterface
}

final class AcceleratedDiffer
{
    public function __construct(
        private readonly ?SpectrumClient $spectrum = null,
    )

    public function compare(string $sourcePdf, string $targetPdf): DiffResult

    public function isSpectrumWired(): bool
}

final class CpuEmbeddingService implements EmbeddingServiceInterface
{
    public function __construct(
        private readonly SpectrumClient $client,
    )

    public function embed(string $text): array

    public function batchEmbed(array $texts): array

    public function getDimension(): int

    public function getModelName(): string
}

final class CpuVectorIndex implements VectorIndexInterface
{
    public const int INDEX_DIMENSION = 384;

    public function __construct(
        private readonly SpectrumClient $client,
        private readonly string $collectionId = 'default',
    )

    public function build(array $vectors, array $ids): void

    public function search(array $queryVector, int $topK = 10): array

    public function delete(array $ids): void

    public function count(): int
}

Behavior contract

Provider

ProAcceleratorProvider is the entry point. embedding(), optimizer(), and differ() memoize their instances. vectorIndex($collectionId) returns a fresh handle per call, bound to the given collection identifier. isAvailable() probes sidecar reachability through the injected Core SpectrumClient.

Batch optimization

optimizeBatch returns a batch result keyed by the caller’s document identifiers. When the sidecar is reachable, the aggregate payload is validated against the client budget before any buffering or upload. An over-limit batch fails closed with SpectrumApiException SPEC-SEC-001 (HTTP 413); it never degrades to the PHP path. An admitted batch is dispatched to the sidecar for parallel image work.

A transport, authentication, or response-parse failure after admission degrades to the PHP optimizer, which analyzes each document sequentially. The degradation is observable twice: the result metadata reports engine php_fallback with summary hardware cpu, and a PSR-3 warning is emitted under the event name spectrum.optimize.fallback. The warning carries the exception class and document count only; no document bytes are logged. In the fallback result, a per-document analysis failure yields an item with error status and code SPEC-PARSE-001; other documents in the batch still complete.

The default optimization level is Balanced. Per-item result fields are original_bytes, optimized_bytes, objects_removed, images_before, images_after, savings_percent, and processing_time_ms.

Document diff

compare runs entirely in PHP via the Pro PdfDiffer: structure parsing, text extraction, and the diff algorithm. No sidecar request is issued in this release. The differ contract accepts raw PDF strings only, so a sidecar parse result cannot be consumed; offloading would add cost with no benefit. An injected client is retained for a future parse-offload feature. isSpectrumWired() exposes the wiring state without issuing a request.

CPU embedding

embed delegates to batchEmbed([$text]) and returns element zero. batchEmbed([]) raises InvalidArgumentException before contacting the sidecar. An unreachable sidecar raises SpectrumNotAvailableException. Batch semantics are all-or-nothing: a per-item failure, a missing or malformed vector, or a count mismatch raises SpectrumApiException (protocol-shape failures carry SPEC-IO-001) instead of returning partial vectors. A non-numeric component inside a returned vector is coerced to 0.0. getDimension returns 384; getModelName returns all-MiniLM-L6-v2. The sidecar downloads and loads the ONNX model lazily on the first request.

CPU vector search

Each handle binds one collection identifier; each collection maps to a separate in-memory HNSW index in the sidecar. build requires equal-length vector and identifier lists and raises InvalidArgumentException otherwise; an empty input returns without a sidecar call. search returns ranked hits with a one-based rank in each result’s metadata. An in-band error envelope raises SpectrumApiException; an envelope without a code maps to SPEC-INDEX-003. delete always rejects with SpectrumApiException SPEC-INDEX-004 (HTTP 501, not retryable) because HNSW does not support per-vector deletion; rebuild the index instead.

count is fail-closed and unambiguous. An unreachable sidecar raises SpectrumNotAvailableException; transport and sidecar errors propagate unchanged. On an otherwise-successful response, a non-JSON body raises SPEC-INDEX-005, a missing metadata.total_vectors raises SPEC-INDEX-006, and a non-integer or negative total raises SPEC-INDEX-007. count returns 0 only for a confirmed-empty index. The size probe submits a zero vector of exactly INDEX_DIMENSION (384) dimensions with a top_k of 0, so a dimension-validating sidecar accepts it.

Edge cases & failure modes

• Sidecar memory is volatile: a restart clears all HNSW collections. Treat index build as idempotent and re-run after a restart.
• Mixed availability within a single process is supported: the optimizer degrades per call; the embedding and vector services fail closed per call.
• An over-limit optimizer batch fails closed before any upload; it does not fall back to the PHP path.
• The optimizer fallback never fails silently: check the result metadata engine marker and monitor the warning event.
• count never reports an unreachable sidecar or a protocol error as 0; those raise typed exceptions.
• A search hit missing its identifier or score defaults to an empty string and 0.0 rather than failing the batch.
• A top_k of 0 is used internally only for the count probe; pass a positive topK for real searches.
• The first embedding request pays the one-time model download and load cost; size that timeout separately.
• The sidecar exception hierarchy and error-code families are cataloged in the Accelerator error reference.
• 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.

Conformance

Accelerator delegates format-affecting work to the Optimizer and Diff modules; conformance for that delegated work is documented on the Optimizer and Diff reference pages.

Development notes

• The module source carries @since 2.1.0; this reference documents the surface as shipped in nextpdf/pro 3.1.0.
• All classes are final and use constructor injection; construct new instances instead of mutating.
• SpectrumClient, VectorSearchResult, BatchResultInterface, and the EmbeddingServiceInterface and VectorIndexInterface contracts come from NextPDF Core; the caller constructs and supplies the sidecar client.
• OptimizationLevel, PdfOptimizer, and PdfDiffer come from the Pro Optimizer and Diff modules; their semantics are documented on those reference pages.
• The embedding service and the vector index share the 384 dimension. Build index vectors to the same dimension as the embeddings that query them.
• Internal mechanism detail stays in the source repository’s internal documentation and is out of scope for this manual.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.

See also

• Accelerator — the capability page for workflow guidance.
• Accelerator error reference — sidecar exception hierarchy and error codes.
• Optimizer — Deep Reference
• Diff — Deep Reference
• Accelerator — NextPDF Enterprise Deep Reference