Initial release of `citomni/vectorembedding`

citomni/vectorembedding 1.0.0

Initial release of citomni/vectorembedding.

This package introduces a dedicated CitOmni provider package for semantic embedding generation with one compact, stable internal contract across providers. It is intentionally narrow in scope and focused on one job: Turning input content into normalized embedding vectors without leaking provider-specific request and response formats into application code.

Highlights

• Unified internal request/response contract for embeddings
• Profile-based provider selection
• Adapter-based provider translation
• Shared orchestration through VectorEmbedder
• CLI support through vectorembedding:embed
• OpenAI adapter
• Gemini adapter
• Package-specific exception hierarchy
• Boot registry, package config baseline, Composer metadata, and README documentation

What this package does

citomni/vectorembedding gives CitOmni applications one reusable embedding service:

• normalize and validate embedding requests
• resolve provider profiles from config
• delegate provider-specific URL, payload, header, and response handling to adapters
• execute transport through the existing CitOmni cURL service
• return one stable normalized response with vectors[], usage, and meta

Why it was added

Embedding APIs differ in:

• endpoint structure
• request payload shape
• option names and semantics
• authentication headers
• response envelopes

Those differences are real, but they should not leak into every controller, command, or service in application code.

This package was added to give CitOmni a focused, deterministic embedding layer instead of:

• overloading citomni/helloai with non-chat responsibilities
• scattering provider-specific embedding logic throughout application code
• introducing a vague, catch-all AI package with unclear boundaries

What this enables in CitOmni applications

This release gives CitOmni applications a reusable foundation for:

• semantic search
• retrieval pipelines
• RAG indexing workflows
• similarity comparison
• duplicate detection
• clustering
• classification
• embedding generation from both HTTP and CLI applications

Applications can now switch embedding providers through profile/config changes rather than rewriting provider-specific request logic.

Included in this release

Core package structure

• Boot/Registry.php
• Service/VectorEmbedder.php
• Interface/EmbeddingAdapterInterface.php
• Exception/*
• Command/EmbedCommand.php

Provider adapters

• OpenAiEmbeddingAdapter
• GeminiEmbeddingAdapter

CLI

• vectorembedding:embed

Configuration

• vectorembedding config baseline with:
  • default_profile
  • debug
  • cache (future-friendly, not active in V1)
  • profiles

Documentation

• package README
• Composer package metadata
• initial usage and architecture documentation

Architectural notes

This release follows the CitOmni philosophy closely:

• explicit contracts
• deterministic behavior
• fail-fast validation
• low overhead
• narrow responsibilities
• no hidden fallback behavior
• no duplicate transport abstraction

The package is deliberately limited to embedding generation only.

It does not implement:

• chunking
• retrieval logic
• vector storage
• nearest-neighbor search
• RAG orchestration
• indexing pipelines
• database-backed embedding cache

Those belong in higher layers or future packages.

V1 behavior

• text input is fully supported
• request format is item-based and multimodal-ready in shape
• adapters translate package-level options into provider-native semantics
• normalized responses always return vectors[]
• raw provider responses and built provider payloads can be included through debug flags
• CLI command supports direct embedding generation and JSON output for diagnostics

Notes

• OpenAI dimensions override is supported
• Gemini task type and output dimensionality are supported through adapter translation
• cache config exists, but response caching is not implemented in this release
• production installations should provide real API keys through app config or environment overlays

Bottom line

This release establishes citomni/vectorembedding as the dedicated CitOmni building block for applications that need semantic embeddings without forcing provider-specific API logic into app-layer code.