# gabrielchua/embedding-adapter architecture

> Architecture diagram of the GitHub repository gabrielchua/embedding-adapter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gabrielchua/embedding-adapter
- Repository: https://github.com/gabrielchua/embedding-adapter

## Overview

#### Purpose and Public Entry Points
`embedding-adapter` is a Python library for fitting a post-processing adapter over existing embedding vectors, targeting retrieval, semantic search, and RAG use cases. Its primary API is:
- `EmbeddingAdapter.fit(query_embeddings, document_embeddings, labels)`
- `EmbeddingAdapter.transform(new_embeddings)`
- `EmbeddingAdapter.patch()` to wrap an existing embedding function.

Public package exports and core implementation are in:
- `embedding_adapter/__init__.py`
- `embedding_adapter/embedding_adapter.py`

#### Core Adapter Lifecycle
The main control flow is train-then-infer:
1. Call `fit` with query/document embedding pairs and relevance labels.
2. The adapter learns a transformation based on those labeled vectors.
3. Call `transform` on newly produced embeddings.
4. Optionally obtain a callable patch and apply it directly after an upstream embedding model function.

The adapter operates on vectors supplied by the caller; it does not appear to own text tokenization or base-model inference.
- `embedding_adapter/embedding_adapter.py`

#### Integration Boundary: Upstream Embedding Models
The library sits between an embedding provider and downstream retrieval infrastructure. Callers remain responsible for generating original embeddings, whether from hosted APIs such as OpenAI or local models such as `gte-large`. The patch interface provides the principal integration seam: it wraps a caller-provided embedding function and returns adapted vectors.

This keeps embedding-model selection, document storage, indexing, and retrieval systems outside this repository’s core boundary.
- `embedding_adapter/embedding_adapter.py`
- `README.md`

#### Label-Driven Training Data Boundary
Training requires three caller-owned inputs: query embeddings, document embeddings, and labels. Labels represent the relevance or supervision signal used to tune vector behavior for a domain. This separates adapter training from feedback collection, dataset construction, and embedding generation.

When real labels are unavailable, the repository provides a synthetic-label generation path rather than embedding that responsibility in the adapter training API.
- `embedding_adapter/embedding_adapter.py`
- `embedding_adapter/utils.py`

#### Synthetic Label Generation
`LabelGenerator` is a supporting component for generating labels through an external OpenAI-backed workflow. Its runtime dependency boundary is explicit: an `OPENAI_API_KEY` environment variable is required. This path is optional and distinct from the core vector adapter lifecycle.

External service and credential handling are therefore concentrated in the utility layer rather than the main adapter interface.
- `embedding_adapter/utils.py`
- `README.md`

#### Packaging and Runtime Distribution
The project is distributed as an installable Python package, including PyPI-oriented metadata and dependency declarations. Consumers install it with `pip` and import from `embedding_adapter`; the repository is library-first, with no indicated server, UI, or standalone application runtime.

- `setup.py`
- `requirements.txt`
- `embedding_adapter/__init__.py`

Main entry points: [`embedding_adapter/embedding_adapter.py`](https://github.com/gabrielchua/embedding-adapter/blob/main/embedding_adapter/embedding_adapter.py) (EmbeddingAdapter), [`embedding_adapter/utils.py`](https://github.com/gabrielchua/embedding-adapter/blob/main/embedding_adapter/utils.py) (LabelGenerator), [`embedding_adapter/__init__.py`](https://github.com/gabrielchua/embedding-adapter/blob/main/embedding_adapter/__init__.py) (Package Exports), [`setup.py`](https://github.com/gabrielchua/embedding-adapter/blob/main/setup.py) (Package Distribution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Adapter Library"]
  node_public_api["Package Exports<br/>Python package API<br/>[__init__.py]"]
  node_adapter["EmbeddingAdapter<br/>adapter class"]
  node_fit["fit<br/>training method"]
  node_transform["transform<br/>inference method"]
  node_patch["patch<br/>integration method"]
end

subgraph group_optional["Optional Labeling"]
  node_label_generator["LabelGenerator<br/>utility component<br/>[utils.py]"]
  node_openai_key["OPENAI_API_KEY<br/>environment credential"]
end

node_consumer(("Library Consumer<br/>caller"))
node_upstream_model["Embedding Provider<br/>external model"]
node_training_inputs["Labeled Vector Pairs<br/>training input"]
node_adapted_vectors["Adapted Embeddings<br/>vector output"]
node_retrieval["Retrieval Infrastructure<br/>external downstream system"]
node_openai["OpenAI Service<br/>external API"]
node_package_metadata["Package Distribution<br/>packaging metadata<br/>[setup.py]"]
node_requirements["Runtime Dependencies<br/>dependency manifest<br/>[requirements.txt]"]

node_consumer -->|"requests embeddings"| node_upstream_model
node_upstream_model -->|"produces training vectors"| node_training_inputs
node_training_inputs -->|"query/document vectors + labels"| node_fit
node_public_api -->|"exports"| node_adapter
node_consumer -->|"imports"| node_public_api
node_fit -->|"stores learned transformation"| node_adapter
node_adapter -->|"serves inference"| node_transform
node_upstream_model -->|"new embeddings"| node_transform
node_transform -->|"transforms"| node_adapted_vectors
node_adapter -->|"provides callable wrapper"| node_patch
node_patch -->|"adapts provider output"| node_adapted_vectors
node_adapted_vectors -->|"indexes or searches"| node_retrieval
node_label_generator -.->|"optional synthetic labels"| node_training_inputs
node_openai_key -->|"authorizes"| node_label_generator
node_label_generator -->|"calls"| node_openai
node_package_metadata -->|"declares dependencies"| node_requirements
node_package_metadata -->|"distributes"| node_public_api

click node_public_api "https://github.com/gabrielchua/embedding-adapter/blob/main/embedding_adapter/__init__.py"
click node_adapter "https://github.com/gabrielchua/embedding-adapter/blob/main/embedding_adapter/embedding_adapter.py"
click node_fit "https://github.com/gabrielchua/embedding-adapter/blob/main/embedding_adapter/embedding_adapter.py"
click node_transform "https://github.com/gabrielchua/embedding-adapter/blob/main/embedding_adapter/embedding_adapter.py"
click node_patch "https://github.com/gabrielchua/embedding-adapter/blob/main/embedding_adapter/embedding_adapter.py"
click node_label_generator "https://github.com/gabrielchua/embedding-adapter/blob/main/embedding_adapter/utils.py"
click node_package_metadata "https://github.com/gabrielchua/embedding-adapter/blob/main/setup.py"
click node_requirements "https://github.com/gabrielchua/embedding-adapter/blob/main/requirements.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_adapter,node_fit,node_transform,node_patch toneBlue
class node_label_generator,node_openai_key toneAmber
class node_consumer,node_upstream_model,node_training_inputs,node_adapted_vectors,node_retrieval,node_openai,node_package_metadata,node_requirements toneNeutral
```

## Components

### Adapter Library

Core train-and-infer vector adaptation.

- [Package Exports](https://github.com/gabrielchua/embedding-adapter/blob/main/embedding_adapter/__init__.py): Python package API · Public import surface for the library. · `embedding_adapter/__init__.py`
- [EmbeddingAdapter](https://github.com/gabrielchua/embedding-adapter/blob/main/embedding_adapter/embedding_adapter.py): adapter class · Fits and applies the learned embedding transformation. · `embedding_adapter/embedding_adapter.py`
- [fit](https://github.com/gabrielchua/embedding-adapter/blob/main/embedding_adapter/embedding_adapter.py): training method · Learns a transformation from labeled vector pairs. · `embedding_adapter/embedding_adapter.py`
- [transform](https://github.com/gabrielchua/embedding-adapter/blob/main/embedding_adapter/embedding_adapter.py): inference method · Adapts newly generated embeddings. · `embedding_adapter/embedding_adapter.py`
- [patch](https://github.com/gabrielchua/embedding-adapter/blob/main/embedding_adapter/embedding_adapter.py): integration method · Wraps a caller-provided embedding function. · `embedding_adapter/embedding_adapter.py`

### Optional Labeling

External synthetic-label workflow.

- [LabelGenerator](https://github.com/gabrielchua/embedding-adapter/blob/main/embedding_adapter/utils.py): utility component · Optionally generates synthetic supervision labels. · `embedding_adapter/utils.py`
- **OPENAI_API_KEY**: environment credential · Required by the OpenAI-backed labeling path.

### Other components

- **Library Consumer**: caller · Supplies vectors and integrates adapted output.
- **Embedding Provider**: external model · Produces original query and document vectors.
- **Labeled Vector Pairs**: training input · Query embeddings, document embeddings, and relevance labels.
- **Adapted Embeddings**: vector output · Vectors for downstream retrieval use.
- **Retrieval Infrastructure**: external downstream system · Indexing, storage, and search remain outside the library.
- **OpenAI Service**: external API · Supports synthetic label generation.
- [Package Distribution](https://github.com/gabrielchua/embedding-adapter/blob/main/setup.py): packaging metadata · Defines installable package metadata and dependencies. · `setup.py`
- [Runtime Dependencies](https://github.com/gabrielchua/embedding-adapter/blob/main/requirements.txt): dependency manifest · `requirements.txt`

## Connections

- Library Consumer → Embedding Provider: requests embeddings
- Embedding Provider → Labeled Vector Pairs: produces training vectors
- Labeled Vector Pairs → fit: query/document vectors + labels
- Package Exports → EmbeddingAdapter: exports
- Library Consumer → Package Exports: imports
- fit → EmbeddingAdapter: stores learned transformation
- EmbeddingAdapter → transform: serves inference
- Embedding Provider → transform: new embeddings
- transform → Adapted Embeddings: transforms
- EmbeddingAdapter → patch: provides callable wrapper
- patch → Adapted Embeddings: adapts provider output
- Adapted Embeddings → Retrieval Infrastructure: indexes or searches
- LabelGenerator → Labeled Vector Pairs: optional synthetic labels
- OPENAI_API_KEY → LabelGenerator: authorizes
- LabelGenerator → OpenAI Service: calls
- Package Distribution → Runtime Dependencies: declares dependencies
- Package Distribution → Package Exports: distributes