PHPackages                             citomni/vectorembedding - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. citomni/vectorembedding

ActiveLibrary[Framework](/categories/framework)

citomni/vectorembedding
=======================

Lean vector embedding provider package for CitOmni: Unified embedding request/response format, provider adapters, and reuse of the existing Curl infrastructure service.

v1.0.0.0(1mo ago)00MITPHPPHP ^8.2

Since Mar 29Pushed 1mo agoCompare

[ Source](https://github.com/citomni/vectorembedding)[ Packagist](https://packagist.org/packages/citomni/vectorembedding)[ Docs](https://github.com/citomni/vectorembedding)[ GitHub Sponsors](https://github.com/LarsGMortensen)[ Fund](https://ko-fi.com/)[ RSS](/packages/citomni-vectorembedding/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (4)Versions (2)Used By (0)

CitOmni VectorEmbedding
=======================

[](#citomni-vectorembedding)

`citomni/vectorembedding` is a reusable CitOmni provider package for semantic embedding integrations. It offers one compact, stable internal contract for embedding-style requests and responses, so application code can work against a consistent structure rather than provider-specific JSON payloads. The package is intentionally narrow in scope: It is designed to be deterministic, explicit, and operationally useful, not a speculative "AI toolbox" bucket.

At its core, VectorEmbedding separates application intent from provider transport. The application submits a normalized request, VectorEmbedding resolves a profile, delegates provider translation to an adapter, performs the outbound HTTP call through the existing CitOmni cURL service, parses the provider response back into a common format, and returns one stable internal embedding response. This design keeps the public surface area small while preserving room for provider-specific capabilities through explicit escape hatches.

Highlights
----------

[](#highlights)

- **Unified embedding contract for CitOmni applications** with one compact internal request/response format across providers.
- **Profile-driven provider selection** so applications target stable profile ids rather than provider-specific payload logic.
- **Adapter-based translation layer** that keeps provider-specific JSON, headers, URLs, and response parsing out of application code.
- **Explicit support for package-level embedding options** such as dimensions and task type, translated by adapters into provider-native semantics.
- **Operationally explicit logging** with useful execution context and no parallel transport stack.
- **Reuse of the existing CitOmni cURL service** instead of introducing a second HTTP abstraction.
- **CLI integration out of the box** through `vectorembedding:embed` for diagnostics, development, and scripting.

Why VectorEmbedding
-------------------

[](#why-vectorembedding)

Embedding APIs differ in endpoint structure, request shape, option semantics, authentication headers, output dimensionality handling, and response envelopes. Those differences are operationally real, but they should not leak into every controller, command, or application service. VectorEmbedding exists to absorb that variability behind a single internal request/response model and a profile-based configuration layer. Profiles select concrete adapters and models; adapters perform provider-specific translation; the application stays focused on intent.

In practical terms, this yields four advantages:

- A single internal request format across providers.
- A single normalized response format for downstream application code.
- Explicit profile-driven configuration rather than implicit provider branching.
- Provider-specific flexibility without collapsing into an unstructured catch-all abstraction.

Design principles
-----------------

[](#design-principles)

VectorEmbedding follows a deliberately conservative architecture:

- **Profiles, not providers, are selected by the application.** A profile defines the adapter, model, endpoint base, API credentials, and timeout policy.
- **Adapters own translation.** They build provider URLs, payloads, headers, and response normalization.
- **The existing CitOmni cURL service remains the transport.** VectorEmbedding does not introduce its own generic transport layer.
- **Validation is structural and explicit.** The package validates request shape, known package-level option keys, and required fields. Provider-specific compatibility stays in adapters.
- **The response contract is stable.** Applications read one normalized `vectors[]` structure regardless of provider.
- **Logging is explicit.** Useful operational context is logged without inventing a second observability layer.

Requirements
------------

[](#requirements)

- PHP **8.2+**
- `ext-json`
- `citomni/kernel`
- `citomni/infrastructure`
- A CitOmni application with the existing cURL service available

OPcache is strongly recommended in production.

Installation
------------

[](#installation)

```
composer require citomni/vectorembedding
composer dump-autoload -o
```

Register the package provider in `config/providers.php`:

```