# Capability: Embedding Prefetch & Batch Similarity

## ADDED Requirements

### Requirement: Bulk prefetch and deduplicate embedding inputs

The server MUST collect all texts that require embeddings for a matching run, normalize them, deduplicate them, and prefetch their embeddings before computing similarity scores.

#### Scenario: Matching run with repeated competences

- Given a matching run where the required competences contain duplicates (e.g. "Python", "Python")
- And a candidate list contains overlapping competences (e.g. multiple candidates list "Python")
- When the similarity computation starts
- Then the embedding for "Python" is requested at most once from the Azure embeddings API
- And all uses of "Python" reuse the same embedding vector for similarity computation

### Requirement: Compute similarity using prefetched vectors (no inner-loop embedding calls)

The similarity computation MUST use prefetched embedding vectors and MUST NOT request embeddings from inside per-competence or per-candidate inner loops.

#### Scenario: Per-skill similarity on large candidate set

- Given required competences and a large candidate competence list
- When `per_skill` similarity is computed
- Then all embeddings are resolved prior to the nested loops
- And the nested loops perform only cosine similarity calculations

## MODIFIED Requirements

### Requirement: Batch embedding API support in Azure client

`AzureOpenAIClient.get_embeddings_batch(...)` MUST support true request-level batching using the Azure embeddings API (`input=[...]`) and MUST preserve input ordering.

#### Scenario: Batch embedding input list

- Given a list of N texts to embed
- When `get_embeddings_batch(texts)` is called
- Then the client makes as few Azure embedding requests as possible (subject to chunking)
- And the returned list of embeddings aligns with `texts` order

### Requirement: Run-scoped in-memory embedding cache

The server MUST maintain a run-scoped in-memory cache to prevent repeated SQLite cache reads for identical texts during a single matching operation.

#### Scenario: Frequent repeated cache hits within one run

- Given cached embeddings are present on disk
- And a matching run needs the same text embedding multiple times
- When the similarity engine resolves embeddings
- Then repeated lookups for the same text are served from an in-memory cache after the first lookup
- And no additional SQLite reads are required for that text during the run

## REMOVED Requirements

### Requirement: Sequential batch behavior requirement

The previous constraint that `get_embeddings_batch` must call the embeddings API sequentially per text is removed.

#### Scenario: Legacy sequential constraint

- Given earlier requirements constrained `get_embeddings_batch` to per-text calls
- When the system is upgraded for performance
- Then this constraint no longer applies
- And request-level batching is allowed