Accelerator — Deep Reference (GPU sidecar, KMS provider factory)

At a glance

This page is the deep reference for the public acceleration surface of NextPDF\Enterprise\Accelerator. It covers the KMS provider stack — the factory, the provider contract, the local provider, and the key-metadata result — and the GPU sidecar services for embedding and vector search. It states parameters, defaults, failure modes, and the key-custody stance. Read the Accelerator capability page first for workflow guidance. Other symbols in the same namespace belong to other capabilities and are outside this page’s scope.

Availability & licensing

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

The KMS provider is selected at runtime; calling code depends on the provider contract, not on the concrete provider. The embedding and vector-index services implement the Core EmbeddingServiceInterface and VectorIndexInterface contracts.

Public API surface

composer require nextpdf/enterprise:^3

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
KmsProviderFactory::fromEnvironment	none	Builds the provider named by the selector variable; unset or empty selects local	KmsProviderInterface	RuntimeException on a missing root key, an unavailable cloud provider, or an unknown name	Static entry point
KmsProviderFactory::create	string $providerType, array $config = []	Builds the named provider from explicit configuration	KmsProviderInterface	RuntimeException when local lacks a non-empty encryption_key, or on an unknown name	local is the only constructible name in this release
KmsProviderInterface::getEncryptionKey	string $collectionId	Returns current key metadata for the collection	EncryptionKeyResult	RuntimeException when the provider is unreachable or misconfigured (contract)	Metadata only; never raw key bytes
KmsProviderInterface::rotateKey	string $collectionId	Advances the key version	EncryptionKeyResult	RuntimeException when rotation fails (contract)	Rotation is a re-encryption signal to the caller
KmsProviderInterface::providerName	none	Reports the canonical provider name	string	Nothing declared	local, aws, gcp, azure, vault
LocalKmsProvider::__construct	string $encryptionKey (sensitive)	Validates a hex root key of at least 64 hex characters (32 bytes)	LocalKmsProvider	InvalidArgumentException on a short or non-hex value	Fail-fast guard; performs no derivation itself
LocalKmsProvider::getEncryptionKey	string $collectionId	Mints local:{collectionId}:v{version}; version defaults to 1	EncryptionKeyResult	Nothing declared	Algorithm label AES-256-GCM
LocalKmsProvider::rotateKey	string $collectionId	Increments the in-process version counter	EncryptionKeyResult	Nothing declared	Version state is per instance
EncryptionKeyResult::__construct	string $keyId, int $keyVersion, string $algorithm = 'AES-256-GCM', string $provider = 'local'	Immutable metadata value object	EncryptionKeyResult	Nothing declared	Never carries key material
GpuEmbeddingService::embed	string $text	Delegates to batchEmbed and returns element zero	list<float>	As batchEmbed	1024-dimension vector
GpuEmbeddingService::batchEmbed	array $texts	Embeds the batch on the sidecar	list<list<float>>	InvalidArgumentException on an empty batch; SpectrumNotAvailableException when the sidecar is unreachable; SpectrumApiException on a failed, malformed, or count-mismatched response	Never returns partial results
GpuEmbeddingService::getDimension	none	Returns 1024	int	Nothing declared	Constant
GpuEmbeddingService::getModelName	none	Returns multilingual-e5-large	string	Nothing declared	Constant
GpuVectorIndex::__construct	SpectrumClient $client, string $collectionId = 'default'	Binds the handle to one collection	GpuVectorIndex	Nothing declared	One handle per collection identifier
GpuVectorIndex::build	array $vectors, array $ids	Builds the collection index on the sidecar	void	InvalidArgumentException on an empty batch or a length mismatch; SpectrumNotAvailableException when unreachable; SpectrumApiException on an unexpected build response	A rebuild replaces the index
GpuVectorIndex::search	array $queryVector, int $topK = 10	Ranked nearest-neighbor search	list<VectorSearchResult>	SpectrumNotAvailableException when unreachable; JsonException on a malformed response body	Per-hit rank in result metadata
GpuVectorIndex::delete	array $ids	Always rejects	void (declared)	Always: SpectrumApiException (not implemented)	The built index is immutable; rebuild instead
GpuVectorIndex::count	none	Reads the collection total from the sidecar	int	Does not throw; any failure returns 0	0 is ambiguous: empty or unreachable

Entry-point signatures

final class KmsProviderFactory
{
    public static function fromEnvironment(): KmsProviderInterface

    public static function create(string $providerType, array $config = []): KmsProviderInterface
}

interface KmsProviderInterface
{
    public function getEncryptionKey(string $collectionId): EncryptionKeyResult;

    public function rotateKey(string $collectionId): EncryptionKeyResult;

    public function providerName(): string;
}

final class LocalKmsProvider implements KmsProviderInterface
{
    public function __construct(
        #[SensitiveParameter]
        private readonly string $encryptionKey,
    )
}

final readonly class EncryptionKeyResult
{
    public function __construct(
        public string $keyId,
        public int $keyVersion,
        public string $algorithm = 'AES-256-GCM',
        public string $provider = 'local',
    )
}

final class GpuEmbeddingService 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 GpuVectorIndex implements VectorIndexInterface
{
    public function __construct(
        private readonly SpectrumClient $client,
        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
}

Configuration surface

Setting	Consumer	Meaning
SPECTRUM_KMS_PROVIDER	fromEnvironment()	Provider selector. Unset or empty resolves to local.
SPECTRUM_ENCRYPTION_KEY	The local provider path	Hex-encoded root key; at least 64 hex characters (32 bytes). Shared with the sidecar.
encryption_key	create('local', [...])	Explicit root key; same format and validation.

Behavior contract

Provider selection

KmsProviderFactory::fromEnvironment reads the selector variable and defaults to local. The cloud provider names aws, gcp, azure, and vault are recognized but not constructible in this release. Selecting aws raises a typed error naming the required aws/aws-sdk-php package; the other three report the integration as not implemented. An unknown name raises a typed error listing the supported names. KmsProviderFactory::create accepts an explicit provider name and a configuration map; local is the only name it constructs.

Key metadata and custody

A provider returns immutable key metadata: a key identifier, a monotonically increasing key version, the algorithm label, and the provider name. It never returns raw key bytes, so a metadata leak does not expose key material. The local provider splits duties with the accelerator sidecar. The PHP class validates the root secret at construction and mints a stable, collection-scoped key identity of the form local:{collectionId}:v{version}. The sidecar performs the HKDF-SHA256 derivation and the AES-256-GCM encryption, deriving a distinct 32-byte data-encryption key per collection with the collection identifier and version as domain separation. Both sides read the same configured root secret. No external KMS service is contacted; key handling stays inside the deployment. The key version and lifecycle model follows NIST SP 800-57 Part 1 Rev.5 §4.

A rotation call advances the key version and returns the new metadata. The caller re-encrypts collection data with the new version; the provider re-encrypts nothing itself.

Key security depends on the KMS or the root-key secret, on the deployment, and on the operator — not on NextPDF Enterprise alone. The operator owns root-key provisioning, secret storage, KMS configuration, and rotation scheduling. Key-protection responsibility follows NIST SP 800-57 Part 1 Rev.5 §5.5.2.

GPU embedding

GpuEmbeddingService implements the Core embedding contract and delegates to the sidecar. The sidecar runs the embedding model on a GPU when one is available and falls back to the CPU otherwise, flagging the response metadata as degraded from GPU. The vector shape is identical in both cases. The model (about 1.3 GB) is downloaded and loaded lazily on the first request. Batch semantics are all-or-nothing: a per-item failure, a malformed vector, or a count mismatch raises a typed error instead of returning partial results.

GPU vector search

GpuVectorIndex implements the Core vector-index contract and binds one handle to one collection identifier. build constructs the index on the sidecar; the sidecar uses a GPU index when one is available and a CPU index otherwise. The index is immutable once built: delete always rejects with a typed not-implemented error, and removal requires a rebuild. search returns ranked hits with a one-based rank in each result’s metadata. count asks the sidecar for the collection total and reports 0 on any failure rather than raising.

Edge cases & failure modes

• The root key must decode from hex to at least 32 bytes. A shorter or non-hex value raises InvalidArgumentException at construction, before any sidecar call.
• An unset or empty selector variable resolves to local; the factory never guesses another provider.
• fromEnvironment on the local path without the root-key variable raises a typed error naming the missing variable.
• create('local', [...]) without a non-empty encryption_key entry raises a typed error naming the missing entry.
• Key-version state is in-process and per provider instance. A new process observes version 1 until rotation runs again. Persist rotation outcomes by re-encrypting data, not by trusting provider state.
• An empty embedding batch raises InvalidArgumentException; the sidecar is not contacted.
• Sidecar availability is probed per call. An unreachable sidecar raises SpectrumNotAvailableException; the services never fail silently.
• A non-numeric component inside a returned embedding vector is coerced to 0.0; a missing or non-array vector raises SpectrumApiException.
• The first embedding request pays the one-time model download and load cost; size that timeout separately.
• build and search decode the sidecar response strictly; a malformed body raises JsonException. count swallows every failure and returns 0.
• A search hit missing its identifier or score defaults to an empty string and 0.0 rather than failing the batch.
• Sidecar error codes and the exception hierarchy are cataloged in the Accelerator error reference.

FIPS-mode behavior

The local key path uses HKDF-SHA256 for derivation and AES-256-GCM for encryption; the sidecar executes both. The algorithm label recorded in key metadata is AES-256-GCM. When the deployment runs against a FIPS-validated cryptographic provider, those primitives run in that validated boundary. AES-GCM use requires a unique initialization vector per key, per NIST SP 800-38D §5.

NextPDF Enterprise operates in a FIPS-compatible mode only when configured with a FIPS-validated cryptographic provider or a FIPS-validated KMS.

Conformance

Claim	Standard	Clause
The key version and lifecycle model follows the key-state guidance.	NIST SP 800-57 Part 1 Rev.5	§4
Key-protection and custody responsibility rests with the key owner and operator.	NIST SP 800-57 Part 1 Rev.5	§5.5.2
AES-GCM requires a unique initialization vector per key.	NIST SP 800-38D	§5

All clauses are paraphrased; NextPDF does not reproduce normative text. Alignment with the cited clauses is a capability statement. The FIPS-mode statement is a compatibility statement. Consult your own compliance and legal advisers.

Development notes

• The module source carries @since 2.1.0; this reference documents the surface as shipped in nextpdf/enterprise 3.1.0.
• All classes are final; EncryptionKeyResult is final readonly. Construct new instances instead of mutating.
• The root key is a sensitive constructor parameter (#[SensitiveParameter]); PHP redacts it from stack traces. Keep it out of application logs and configuration dumps.
• SpectrumClient, VectorSearchResult, and the EmbeddingServiceInterface and VectorIndexInterface contracts come from NextPDF Core; the caller constructs and supplies the sidecar client.
• The NextPDF\Enterprise\Accelerator namespace also carries batch offload engines and the retrieval-collection and OCR extraction stacks; those surfaces are outside this page’s scope.
• 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 — GPU sidecar and KMS provider factory — the capability page for workflow and custody guidance.
• Accelerator error reference — sidecar exception hierarchy and error codes.
• Security — Deep Reference
• Accelerator — NextPDF Pro Deep Reference