Skip to content

retrofit: reverse-spec vector-embeddings capability (5 REQs) #1813

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rubenvdlinde merged 1 commit into from
May 25, 2026
Merged

retrofit: reverse-spec vector-embeddings capability (5 REQs) #1813

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions lib/Service/Vectorization/Handlers/EmbeddingGeneratorHandler.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,8 @@ public function __construct(
* @throws \Exception If configuration is invalid or generator cannot be created
*
* @SuppressWarnings(PHPMD.CyclomaticComplexity) Multiple provider configurations require separate conditions
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-1
*/
public function getGenerator(array $config): EmbeddingGeneratorInterface
{
Expand Down Expand Up @@ -131,6 +133,8 @@ public function getGenerator(array $config): EmbeddingGeneratorInterface
* @return int Default dimensions
*
* @psalm-return 384|1536|3072
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-1
*/
public function getDefaultDimensions(string $model): int
{
Expand All @@ -148,6 +152,8 @@ public function getDefaultDimensions(string $model): int
* |OpenAI3LargeEmbeddingGenerator Generator instance
*
* @throws \Exception If model is not supported
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-1
*/
private function createOpenAIGenerator(
string $model,
Expand Down Expand Up @@ -185,6 +191,8 @@ private function createOpenAIGenerator(
* @throws \Exception If model is not supported
*
* @SuppressWarnings(PHPMD.ExcessiveMethodLength) Anonymous class requires complete implementation
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-1
*/
private function createFireworksGenerator(string $model, array $config): object
{
Expand Down Expand Up @@ -357,6 +365,8 @@ public function embedDocuments(array $documents): array
* @param array $config Configuration array with base_url
*
* @return OllamaEmbeddingGenerator Generator instance
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-1
*/
private function createOllamaGenerator(string $model, array $config): OllamaEmbeddingGenerator
{
Expand Down
8 changes: 8 additions & 0 deletions lib/Service/Vectorization/Handlers/VectorStatsHandler.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,8 @@ public function __construct(
* @psalm-return array{total_vectors: int, by_type: array<int>,
* by_model: array<int|mixed>, object_vectors?: int, file_vectors?: int,
* source?: 'solr'|'solr_error'|'solr_unavailable'}
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-5
*/
public function getStats(string $backend='php'): array
{
Expand Down Expand Up @@ -97,6 +99,8 @@ public function getStats(string $backend='php'): array
*
* @psalm-return array{total_vectors: int, by_type: array<int>,
* by_model: array<int>, object_vectors: int, file_vectors: int}
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-5
*/
private function getStatsFromDatabase(): array
{
Expand Down Expand Up @@ -157,6 +161,8 @@ private function getStatsFromDatabase(): array
* }
*
* @SuppressWarnings(PHPMD.CyclomaticComplexity) Multi-collection stats gathering requires multiple conditions
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-5
*/
private function getStatsFromSolr(): array
{
Expand Down Expand Up @@ -265,6 +271,8 @@ private function getStatsFromSolr(): array
* @return array{count: int, by_model: array} Count and breakdown by model
*
* @SuppressWarnings(PHPMD.CyclomaticComplexity) Facet processing requires multiple conditions
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-5
*/
private function countVectorsInCollection(
string $collection,
Expand Down
12 changes: 12 additions & 0 deletions lib/Service/Vectorization/Handlers/VectorStorageHandler.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,8 @@ public function __construct(
* @throws \Exception If storage fails
*
* @SuppressWarnings(PHPMD.ExcessiveParameterList) Required for flexible vector storage options
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-2
*/
public function storeVector(
string $entityType,
Expand Down Expand Up @@ -172,6 +174,8 @@ public function storeVector(
*
* @SuppressWarnings(PHPMD.ExcessiveParameterList) Required for flexible vector storage options
* @SuppressWarnings(PHPMD.CyclomaticComplexity) Multiple storage conditions and error handling
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-2
*/
private function storeVectorInDatabase(
string $entityType,
Expand Down Expand Up @@ -285,6 +289,8 @@ private function storeVectorInDatabase(
* @SuppressWarnings(PHPMD.CyclomaticComplexity) Multiple Solr storage conditions
* @SuppressWarnings(PHPMD.NPathComplexity) Multiple storage paths with error handling
* @SuppressWarnings(PHPMD.ExcessiveMethodLength) Comprehensive Solr vector storage with atomic updates
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-2
*/
private function storeVectorInSolr(
string $entityType,
Expand Down Expand Up @@ -414,6 +420,8 @@ private function storeVectorInSolr(
*
* @SuppressWarnings(PHPMD.CyclomaticComplexity) Collection resolution requires multiple conditions
* @SuppressWarnings(PHPMD.NPathComplexity) Multiple collection determination paths
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-2
*/
private function getSolrCollectionForEntityType(string $entityType): ?string
{
Expand Down Expand Up @@ -464,6 +472,8 @@ private function getSolrCollectionForEntityType(string $entityType): ?string
* Get the configured Solr vector field name
*
* @return string Solr vector field name (default: '_embedding_')
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-2
*/
private function getSolrVectorField(): string
{
Expand Down Expand Up @@ -493,6 +503,8 @@ private function getSolrVectorField(): string
* @param string $text Text to sanitize
*
* @return string Sanitized text safe for UTF-8 storage
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-2
*/
private function sanitizeText(string $text): string
{
Expand Down
14 changes: 14 additions & 0 deletions lib/Service/Vectorization/Strategies/ObjectVectorizationStrategy.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,8 @@ public function __construct(
* @return \OCA\OpenRegister\Db\ObjectEntity[]
*
* @psalm-return list<\OCA\OpenRegister\Db\ObjectEntity>
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-4
*/
public function fetchEntities(array $options): array
{
Expand Down Expand Up @@ -144,6 +146,8 @@ public function fetchEntities(array $options): array
* @return (int|string)[][] Array with single item containing serialized object
*
* @psalm-return list{array{text: string, index: 0}}
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-4
*/
public function extractVectorizationItems($entity): array
{
Expand Down Expand Up @@ -196,6 +200,8 @@ public function extractVectorizationItems($entity): array
*
* @SuppressWarnings(PHPMD.CyclomaticComplexity) Complex metadata extraction with multiple fallbacks
* @SuppressWarnings(PHPMD.NPathComplexity) Multiple field extraction paths
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-4
*/
public function prepareVectorMetadata($entity, array $item): array
{
Expand Down Expand Up @@ -270,6 +276,8 @@ public function prepareVectorMetadata($entity, array $item): array
* @param array $objectData Object data
*
* @return array<string> Array of @self keys
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-4
*/
private function extractSelfKeys(array $objectData): array
{
Expand All @@ -292,6 +300,8 @@ private function extractSelfKeys(array $objectData): array
*
* @SuppressWarnings(PHPMD.CyclomaticComplexity) Multiple field type checks required
* @SuppressWarnings(PHPMD.NPathComplexity) Multiple field validation paths
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-4
*/
private function extractFirstStringField(array $objectData): ?string
{
Expand Down Expand Up @@ -324,6 +334,8 @@ private function extractFirstStringField(array $objectData): ?string
* @param mixed $entity ObjectEntity
*
* @return string|int Object ID
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-4
*/
public function getEntityIdentifier($entity)
{
Expand All @@ -343,6 +355,8 @@ public function getEntityIdentifier($entity)
* @param array $config Vectorization configuration
*
* @return false|string Serialized text
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-4
*/
private function serializeObject(array $object, array $config): string|false
{
Expand Down
8 changes: 8 additions & 0 deletions lib/Service/Vectorization/Strategies/VectorizationStrategyInterface.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ interface VectorizationStrategyInterface
* @param array $options Strategy-specific options
*
* @return array Array of entities to vectorize
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-3
*/
public function fetchEntities(array $options): array;

Expand All @@ -60,6 +62,8 @@ public function fetchEntities(array $options): array;
* @param mixed $entity Entity to extract items from
*
* @return array Array of items, each with 'text' and other data
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-3
*/
public function extractVectorizationItems($entity): array;

Expand All @@ -78,6 +82,8 @@ public function extractVectorizationItems($entity): array;
* @param array $item Vectorization item (from extractVectorizationItems)
*
* @return array Metadata for vector storage
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-3
*/
public function prepareVectorMetadata($entity, array $item): array;

Expand All @@ -87,6 +93,8 @@ public function prepareVectorMetadata($entity, array $item): array;
* @param mixed $entity Entity
*
* @return string|int Identifier
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-3
*/
public function getEntityIdentifier($entity);
}//end interface
20 changes: 20 additions & 0 deletions lib/Service/Vectorization/VectorEmbeddings.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,8 @@ public function __construct(
* @throws \Exception If embedding generation fails
*
* @psalm-return array{embedding: array<float>, model: string, dimensions: int<0, max>}
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-1
*/
public function generateEmbedding(string $text, ?string $provider=null): array
{
Expand Down Expand Up @@ -151,6 +153,8 @@ public function generateEmbedding(string $text, ?string $provider=null): array
* @psalm-return array<float>
*
* @SuppressWarnings(PHPMD.CyclomaticComplexity) Complex config validation logic
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-1
*/
public function generateEmbeddingWithCustomConfig(string $text, array $config): array
{
Expand Down Expand Up @@ -228,6 +232,8 @@ public function generateEmbeddingWithCustomConfig(string $text, array $config):
* @param string $testText Optional test text to embed
*
* @return array
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-1
*/
public function testEmbedding(string $provider, array $config, string $testText='Test.'): array
{
Expand Down Expand Up @@ -303,6 +309,8 @@ public function testEmbedding(string $provider, array $config, string $testText=
* @return array<int, array{embedding: array<float>, model: string, dimensions: int}> Array of embeddings
*
* @throws \Exception If batch embedding generation fails
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-1
*/
public function generateBatchEmbeddings(array $texts, ?string $provider=null): array
{
Expand Down Expand Up @@ -399,6 +407,8 @@ public function generateBatchEmbeddings(array $texts, ?string $provider=null): a
* @return int The ID of the inserted vector
*
* @throws \Exception If storage fails
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-2
*/
public function storeVector(
string $entityType,
Expand Down Expand Up @@ -515,6 +525,8 @@ public function hybridSearch(
* @psalm-return array{total_vectors: int, by_type: array<int>,
* by_model: array<int|mixed>, object_vectors?: int, file_vectors?: int,
* source?: 'solr'|'solr_error'|'solr_unavailable'}
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-5
*/
public function getVectorStats(): array
{
Expand All @@ -535,6 +547,8 @@ public function getVectorStats(): array
* @SuppressWarnings(PHPMD.CyclomaticComplexity) Complex model comparison logic
* @SuppressWarnings(PHPMD.NPathComplexity) Multiple database queries and conditions
* @SuppressWarnings(PHPMD.ExcessiveMethodLength) Thorough model mismatch detection
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-5
*/
public function checkEmbeddingModelMismatch(): array
{
Expand Down Expand Up @@ -647,6 +661,8 @@ public function checkEmbeddingModelMismatch(): array
* @return (bool|int|string)[]
*
* @psalm-return array{success: bool, error?: string, message: string, deleted?: int}
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-5
*/
public function clearAllEmbeddings(): array
{
Expand Down Expand Up @@ -704,6 +720,8 @@ public function clearAllEmbeddings(): array
* Get the configured vector search backend
*
* @return string Vector search backend ('php', 'database', or 'solr')
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-2
*/
private function getVectorSearchBackend(): string
{
Expand All @@ -728,6 +746,8 @@ private function getVectorSearchBackend(): string
* api_key: string|null, base_url: string|null} Configuration
*
* @SuppressWarnings(PHPMD.CyclomaticComplexity) Provider-specific configuration mapping
*
* @spec openspec/changes/retrofit-2026-05-24-newcap-vector-embeddings/tasks.md#task-1
*/
private function getEmbeddingConfig(?string $provider=null): array
{
Expand Down
Loading
Loading