init project

.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+__pycache__/
+*.pyc
+.venv

Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.12-slim
+
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+COPY --chown=user pyproject.toml ./
+RUN pip install --no-cache-dir .
+
+COPY --chown=user app ./app
+
+# Start the app with Uvicorn
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

Makefile

@@ -0,0 +1,15 @@
+APP_DIR := $(CURDIR)/app
+TESTS_DIR := $(CURDIR)/tests
+
+format:
+	uv run black $(APP_DIR) $(TESTS_DIR)/*.py
+	uv run ruff check $(APP_DIR) $(TESTS_DIR) --fix
+
+lint:
+	uv run black --check $(APP_DIR) $(TESTS_DIR)/*.py
+	uv run ruff check $(APP_DIR) $(TESTS_DIR)
+	uv run mypy $(APP_DIR) $(TESTS_DIR)
+
+test:
+	uv run pytest ${TESTS_DIR}
+

README.md

@@ -0,0 +1,145 @@
+---
+title: Text2vector
+emoji: 📊
+colorFrom: purple
+colorTo: green
+sdk: docker
+pinned: false
+short_description: Create a vector embedding from text
+---
+
+# Embedding API
+
+API to call an embedding model ([intfloat/multilingual-e5-large](https://huggingface.co/intfloat/multilingual-e5-large)) for generating multilingual text embeddings.<br>
+The embedding model takes a text string and converts it into 1024 dimension vector.<br>
+Using a `POST` request to the `/embed` endpoint with a list of texts, the API returns their corresponding embeddings.<br>
+A maximum of 2000 characters per text is enforced to avoid truncation, and thereby loss of information, by the tokenizer.<br>
+Each text must start with either "query: " or "passage: ".<br>
+
+
+The API is deployed at a Hugging Face Docker space where the Swagger UI can be acccessed at:<br>
+[https://emilbm-text2vector.hf.space/docs](https://emilbm-text2vector.hf.space/docs)
+
+
+## Features
+
+- FastAPI-based REST API
+- `/embed` endpoint for generating embeddings from a list of texts
+- `/health` endpoint for checking the API status
+- Uses HuggingFace Transformers and PyTorch
+- Includes linting and unit tests
+- Dockerfile for containerization
+- CI/CD with GitHub Actions to build, lint, test, and deploy to Hugging Face
+
+## Local Development
+### Requirements
+
+- Python 3.12+
+- [UV](https://docs.astral.sh/uv/)
+- (Optional) Docker
+### Installation
+
+1. **Clone the repository:**
+	 ```sh
+	 git clone https://github.com/EmilbMadsen/embedding-api.git
+	 cd embedding-api
+	 ```
+
+2. **Create a virtual environment and activate it:**
+	 ```sh
+	 uv venv
+	 source .venv/bin/activate
+	 ```
+
+3. **Install dependencies:**
+	 ```sh
+	 uv sync
+	 ```
+
+### Formatting, Linting and Unit Tests
+- **Formatting (with Black and Ruff) and linting (with Black, Ruff, and MyPy):**
+	```sh
+	make format
+	make lint
+	```
+- **Run unit tests:**
+	```sh
+	make test
+	```
+
+### Running Locally (without Docker)
+
+Start the API server with Uvicorn:
+
+```sh
+uvicorn app.main:app --reload --port 7860
+```
+
+### Running Locally (with Docker)
+Build and start the API server with Docker:
+
+```sh
+docker build -t embedding-api .
+docker run -p 7860:7860 embedding-api
+```
+### Test the endpoint
+Test the endpoint with either:
+```sh
+curl -X 'POST' \
+  'http://127.0.0.1:7860/embed' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "texts": [
+    "query: what is the capital of France?",
+    "passage: Paris is the capital of France."
+  ]
+}'
+```
+Or through the Swagger UI.
+
+
+
+## Usage
+
+### Embed Endpoint
+
+- **POST** `/embed`
+- **Request Body:**
+	```json
+	{
+		"texts": [
+			"query: what is the capital of France?",
+			"passage: Paris is the capital of France."
+		]
+	}
+	```
+- **Response:**
+	```json
+	{
+		"embeddings": [[...], [...]]
+	}
+	```
+
+### Health Endpoint
+
+- **GET** `/health`
+- **Response:**
+	```json
+	{
+		"status": "ok"
+	}
+	```
+
+## Project Structure
+
+```
+app/
+		main.py            # FastAPI app
+		embeddings.py      # Embedding logic
+		models.py          # Request/response models
+		logger.py          # Logging setup
+tests/
+		test_api.py        # API tests
+		test_embeddings.py # Embedding tests
+```

app/embeddings.py

@@ -0,0 +1,38 @@
+from transformers import AutoTokenizer, AutoModel
+from torch import Tensor
+from app.logger import logger
+
+model = AutoModel.from_pretrained("intfloat/multilingual-e5-large")
+tokenizer = AutoTokenizer.from_pretrained("intfloat/multilingual-e5-large")
+
+
+def average_pool(last_hidden_states: Tensor, attention_mask: Tensor) -> Tensor:
+    """Average pool the token embeddings."""
+    last_hidden = last_hidden_states.masked_fill(~attention_mask[..., None].bool(), 0.0)
+    return last_hidden.sum(dim=1) / attention_mask.sum(dim=1)[..., None]
+
+
+def embed_text(texts: list[str]) -> list[list[float]]:
+    """
+    Generate embeddings for a list of texts.
+
+    The model supports a maximum of 512 tokens per input which typically corresponds to about 2000-2500 characters.
+    To avoid losing important information, we set a limit of 2000 characters per input text.
+    """
+    if not texts:
+        raise ValueError("No input texts provided.")
+    if any(len(text) > 2000 for text in texts):
+        raise ValueError(
+            "One or more input texts exceed the maximum length of 2000 characters."
+        )
+
+    batch_dict = tokenizer(
+        texts, max_length=512, padding=True, truncation=True, return_tensors="pt"
+    )
+    logger.info(
+        f"Tokenized {len(texts)} texts with number of tokens per text: {batch_dict['input_ids'].ne(tokenizer.pad_token_id).sum(dim=1).tolist()}"
+    )
+    outputs = model(**batch_dict)
+    embeddings = average_pool(outputs.last_hidden_state, batch_dict["attention_mask"])
+
+    return embeddings.detach().cpu().tolist()

app/logger.py

@@ -0,0 +1,36 @@
+import logging
+from logging.config import dictConfig
+
+LOGGING_CONFIG = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "default": {
+            "format": "[%(asctime)s] [%(levelname)s] %(name)s: %(message)s",
+            "datefmt": "%Y-%m-%d %H:%M:%S",
+        },
+        "json": {
+            "format": (
+                '{"time": "%(asctime)s", '
+                '"level": "%(levelname)s", '
+                '"name": "%(name)s", '
+                '"message": "%(message)s"}'
+            ),
+            "datefmt": "%Y-%m-%d %H:%M:%S",
+        },
+    },
+    "handlers": {
+        "console": {
+            "class": "logging.StreamHandler",
+            "formatter": "default",
+        },
+    },
+    "root": {
+        "level": "INFO",
+        "handlers": ["console"],
+    },
+}
+
+dictConfig(LOGGING_CONFIG)
+
+logger = logging.getLogger("app")

app/main.py

@@ -0,0 +1,56 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.middleware.cors import CORSMiddleware
+from app.models import EmbedRequest, EmbedResponse
+from app.embeddings import embed_text
+from logging import getLogger
+from pathlib import Path
+
+logger = getLogger(__name__)
+
+app = FastAPI(
+    title="Embedding API",
+    description="A simple API to generate text embeddings using Microsoft's `multilingual-e5-large` model.",
+    version="1.0.0",
+)
+
+# Mount the frontend directory as static files under /static
+FRONTEND_DIR = Path(__file__).resolve().parents[1] / "frontend"
+if FRONTEND_DIR.exists():
+    app.mount("/static", StaticFiles(directory=str(FRONTEND_DIR)), name="static")
+
+# Allow simple cross-origin requests from local development (adjust in production)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.post("/embed", response_model=EmbedResponse)
+async def embed(request: EmbedRequest) -> dict[str, list[list[float]]]:
+    """Generate embeddings for a list of texts."""
+    try:
+        vectors = embed_text(request.texts)
+        return {"embeddings": vectors}
+    except Exception as e:
+        logger.exception("Error generating embeddings")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/health")
+async def health_check() -> dict[str, str]:
+    """Health check endpoint."""
+    return {"status": "ok"}
+
+
+@app.get("/", response_model=None)
+async def root() -> FileResponse | dict[str, str]:
+    """Serve the frontend `index.html` if present, otherwise return small JSON status."""
+    index_file = FRONTEND_DIR / "index.html"
+    if index_file.exists():
+        return FileResponse(str(index_file))
+    return {"status": "ok", "message": "Frontend not found"}

app/models.py

@@ -0,0 +1,42 @@
+from pydantic import BaseModel, Field, field_validator, StringConstraints
+from typing import Annotated
+
+PREFIX_ACCEPTED = ["query: ", "passage: "]
+
+ShortText = Annotated[str, StringConstraints(max_length=2000)]
+
+
+class EmbedRequest(BaseModel):
+    """
+    Request model for texts to be embedded.
+    Each text must start with an accepted prefix and be ≤ 2000 characters.
+    The texts need to start with either "query: " or "passage: ".
+    """
+
+    texts: list[ShortText] = Field(
+        ...,
+        json_schema_extra={
+            "example": [
+                "query: what is the capital of France?",
+                "passage: Paris is the capital of France.",
+            ]
+        },
+        description="List of texts to be embedded (≤ 2000 characters each) and must start with 'query: ' or 'passage: '.",
+    )
+
+    @field_validator("texts")
+    @classmethod
+    def check_prefixes(cls, texts: list[str]) -> list[str]:
+        for t in texts:
+            if not any(t.startswith(prefix) for prefix in PREFIX_ACCEPTED):
+                raise ValueError(f"Each text must start with one of {PREFIX_ACCEPTED}")
+        return texts
+
+
+class EmbedResponse(BaseModel):
+    """Response model containing embeddings."""
+
+    embeddings: list[list[float]] = Field(
+        ...,
+        description="List of embedding vectors corresponding to the input texts. Each embedding is a list of floats with length 1024.",
+    )

frontend/index.html

@@ -0,0 +1,340 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Text2Vector | Text to Vector Conversion</title>
+    <link rel="icon" type="image/x-icon" href="/static/favicon.ico">
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script src="https://unpkg.com/feather-icons"></script>
+    <script src="https://cdn.jsdelivr.net/npm/feather-icons/dist/feather.min.js"></script>
+        <style>
+            .text-input-group:hover .remove-text-btn {
+                display: block !important;
+            }
+.gradient-bg {
+            background: linear-gradient(135deg, #6e8efb 0%, #a777e3 100%);
+        }
+        .embed-card {
+            backdrop-filter: blur(10px);
+            background: rgba(255, 255, 255, 0.1);
+            border: 1px solid rgba(255, 255, 255, 0.2);
+        }
+        .text-area {
+            min-height: 150px;
+        }
+        .vector-display {
+            font-family: monospace;
+            white-space: pre-wrap;
+            overflow-x: auto;
+        }
+        #vanta-bg {
+            position: absolute;
+            top: 0;
+            left: 0;
+            width: 100%;
+            height: 100%;
+            z-index: -1;
+        }
+    </style>
+</head>
+<body class="min-h-screen text-gray-100">
+    <div id="vanta-bg"></div>
+    <div class="container mx-auto px-4 py-12">
+        <!-- Header -->
+        <header class="text-center mb-12">
+            <h1 class="text-4xl md:text-5xl font-bold mb-4">Text2Vector ⚡</h1>
+            <p class="text-xl opacity-80">Transform your text into powerful vector embeddings</p>
+        </header>
+
+        <!-- Main Content -->
+        <main class="max-w-4xl mx-auto">
+            <div class="grid md:grid-cols-2 gap-8">
+                <!-- Input Section -->
+                <div class="embed-card rounded-xl p-6 shadow-lg">
+                    <div class="flex items-center justify-between mb-4">
+                        <div class="flex items-center">
+                            <i data-feather="edit-3" class="mr-2"></i>
+                            <h2 class="text-xl font-semibold">Input Texts</h2>
+                        </div>
+                        <button id="add-text-btn" class="px-3 py-1 gradient-bg hover:opacity-90 rounded-lg transition flex items-center text-sm">
+                            <i data-feather="plus" class="mr-1"></i>
+                            Add Field
+                        </button>
+                    </div>
+                    <div id="text-inputs-container">
+                        <div class="text-input-group mb-3 relative">
+                            <textarea class="w-full text-area bg-gray-800 bg-opacity-50 rounded-lg p-4 text-white border border-gray-600 focus:border-purple-400 focus:ring-1 focus:ring-purple-400 transition" placeholder="Enter your text here..."></textarea>
+                            <button class="remove-text-btn absolute top-1 right-1 p-1 bg-gray-700 hover:bg-gray-600 rounded-full transition" style="display: none;">
+                                <i data-feather="x" class="w-4 h-4"></i>
+                            </button>
+                        </div>
+                    </div>
+                    <div class="flex justify-between mt-4">
+                        <button id="clear-btn" class="px-4 py-2 bg-gray-700 hover:bg-gray-600 rounded-lg transition flex items-center">
+                            <i data-feather="trash-2" class="mr-2"></i>
+                            Clear All
+                        </button>
+                        <button id="generate-btn" class="px-6 py-2 gradient-bg hover:opacity-90 rounded-lg transition flex items-center">
+                            <i data-feather="zap" class="mr-2"></i>
+                            Generate Embeddings
+                        </button>
+                    </div>
+                </div>
+<!-- Output Section -->
+                <div class="embed-card rounded-xl p-6 shadow-lg">
+                    <div class="flex items-center justify-between mb-4">
+                        <div class="flex items-center">
+                            <i data-feather="list" class="mr-2"></i>
+                            <h2 class="text-xl font-semibold">Vector Embeddings</h2>
+                        </div>
+                        <button id="copy-btn" class="px-3 py-1 bg-gray-700 hover:bg-gray-600 rounded-lg transition flex items-center text-sm" disabled>
+                            <i data-feather="copy" class="mr-1"></i>
+                            Copy
+                        </button>
+                    </div>
+                    <div id="output-container" class="vector-display bg-gray-800 bg-opacity-50 rounded-lg p-4 h-64 overflow-auto hidden">
+                        <pre id="output-vector" class="text-sm"></pre>
+                    </div>
+                    <div id="placeholder" class="bg-gray-800 bg-opacity-30 rounded-lg p-8 text-center h-64 flex items-center justify-center">
+                        <div class="opacity-60">
+                            <i data-feather="wind" class="w-12 h-12 mx-auto mb-4"></i>
+                            <p>Your embeddings will appear here</p>
+                        </div>
+                    </div>
+                    <button id="download-btn" class="w-full mt-4 px-4 py-2 gradient-bg hover:opacity-90 rounded-lg transition flex items-center justify-center hidden">
+                        <i data-feather="download" class="mr-2"></i>
+                        Download as JSON
+                    </button>
+                </div>
+            </div>
+
+            <!-- Info Section -->
+            <div class="embed-card rounded-xl p-6 mt-8 shadow-lg">
+                <div class="flex items-center mb-4">
+                    <i data-feather="info" class="mr-2"></i>
+                    <h2 class="text-xl font-semibold">About Text2Vector</h2>
+                </div>
+            <p class="mb-4">Text2Vector transforms your text into high-dimensional vector representations using Microsoft's multilingual-e5-large model, capturing semantic meaning across multiple languages.</p>
+<div class="grid md:grid-cols-3 gap-4">
+                    <div class="bg-gray-800 bg-opacity-30 p-4 rounded-lg">
+                        <div class="flex items-center mb-2">
+                            <i data-feather="hash" class="mr-2 text-purple-300"></i>
+                            <h3 class="font-medium">Dimensionality</h3>
+                        </div>
+                        <p class="text-sm opacity-80">1024-dimensional vectors</p>
+</div>
+        <div class="bg-gray-800 bg-opacity-30 p-4 rounded-lg">
+            <div class="flex items-center mb-2">
+                <i data-feather="cpu" class="mr-2 text-purple-300"></i>
+                <h3 class="font-medium">Model</h3>
+            </div>
+            <p class="text-sm opacity-80">Microsoft's multilingual-e5-large</p>
+        </div>
+<div class="bg-gray-800 bg-opacity-30 p-4 rounded-lg">
+                        <div class="flex items-center mb-2">
+                            <i data-feather="code" class="mr-2 text-purple-300"></i>
+                            <h3 class="font-medium">API</h3>
+                        </div>
+                        <p class="text-sm opacity-80">Simple REST integration</p>
+                    </div>
+                </div>
+            </div>
+        </main>
+    </div>
+    <!-- Footer -->
+    <footer class="text-center py-8 opacity-70 text-sm">
+        <p>© 2023 Text2Vector ⚡ | Powered by multilingual-e5-large embeddings</p>
+        <p class="mt-2" id="api-status">API Status: <span class="text-red-500">Checking...</span></p>
+    </footer>
+<!-- Scripts -->
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r121/three.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/vanta@latest/dist/vanta.globe.min.js"></script>
+    <script>
+        // Initialize Vanta.js background
+        VANTA.GLOBE({
+            el: "#vanta-bg",
+            mouseControls: true,
+            touchControls: true,
+            gyroControls: false,
+            minHeight: 200.00,
+            minWidth: 200.00,
+            scale: 1.00,
+            scaleMobile: 1.00,
+            color: 0x6e8efb,
+            backgroundColor: 0x0,
+            size: 0.8
+        });
+
+        // Initialize Feather Icons
+        feather.replace();
+        // DOM Elements
+        const textInputsContainer = document.getElementById('text-inputs-container');
+        const generateBtn = document.getElementById('generate-btn');
+        const clearBtn = document.getElementById('clear-btn');
+        const copyBtn = document.getElementById('copy-btn');
+        const downloadBtn = document.getElementById('download-btn');
+        const outputContainer = document.getElementById('output-container');
+        const outputVector = document.getElementById('output-vector');
+        const placeholder = document.getElementById('placeholder');
+        const addTextBtn = document.getElementById('add-text-btn');
+
+        // Add new text input field
+        addTextBtn.addEventListener('click', () => {
+            const newInputGroup = document.createElement('div');
+            newInputGroup.className = 'text-input-group mb-3 relative';
+            newInputGroup.innerHTML = `
+                <textarea class="w-full text-area bg-gray-800 bg-opacity-50 rounded-lg p-4 text-white border border-gray-600 focus:border-purple-400 focus:ring-1 focus:ring-purple-400 transition" placeholder="Enter your text here..."></textarea>
+                <button class="remove-text-btn absolute top-1 right-1 p-1 bg-gray-700 hover:bg-gray-600 rounded-full transition">
+                    <i data-feather="x" class="w-4 h-4"></i>
+                </button>
+            `;
+            textInputsContainer.appendChild(newInputGroup);
+            feather.replace();
+            setupRemoveButtons();
+        });
+
+        // Setup remove buttons for all input fields
+        function setupRemoveButtons() {
+            document.querySelectorAll('.remove-text-btn').forEach(btn => {
+                btn.addEventListener('click', (e) => {
+                    if (document.querySelectorAll('.text-input-group').length > 1) {
+                        e.target.closest('.text-input-group').remove();
+                    }
+                });
+            });
+        }
+
+        // Show remove buttons when hovering over input groups
+        document.addEventListener('mouseover', (e) => {
+            if (e.target.closest('.text-input-group')) {
+                const group = e.target.closest('.text-input-group');
+                if (document.querySelectorAll('.text-input-group').length > 1) {
+                    group.querySelector('.remove-text-btn').style.display = 'block';
+                }
+            }
+        });
+
+        document.addEventListener('mouseout', (e) => {
+            if (e.target.closest('.text-input-group')) {
+                const group = e.target.closest('.text-input-group');
+                group.querySelector('.remove-text-btn').style.display = 'none';
+            }
+        });
+
+        setupRemoveButtons();
+// API Configuration
+        const API_URL = '/embed';
+        // Check API health
+        async function checkApiHealth() {
+            try {
+                const response = await fetch('/health');
+if (response.ok) {
+                    document.getElementById('api-status').innerHTML = 
+                        'API Status: <span class="text-green-500">Online</span>';
+                } else {
+                    throw new Error('API not responding');
+                }
+            } catch (error) {
+                document.getElementById('api-status').innerHTML = 
+                    'API Status: <span class="text-red-500">Offline</span>';
+                console.error('API health check failed:', error);
+            }
+        }
+
+        // Initial health check
+        checkApiHealth();
+        setInterval(checkApiHealth, 30000);  // Check every 30 seconds
+
+        // Event Listeners
+generateBtn.addEventListener('click', async () => {
+            const textInputs = Array.from(document.querySelectorAll('.text-input-group textarea'));
+            const texts = textInputs
+                .map(input => input.value.trim())
+                .filter(text => text.length > 0);
+
+            if (texts.length === 0) {
+                alert('Please enter at least one text input');
+                return;
+            }
+// Show loading state
+            generateBtn.disabled = true;
+            generateBtn.innerHTML = '<i data-feather="loader" class="animate-spin mr-2"></i> Processing...';
+            feather.replace();
+        // Make API call to backend
+            try {
+                const response = await fetch('/embed', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        texts: texts
+                    })
+                });
+if (!response.ok) {
+                    throw new Error(`API Error: ${response.status}`);
+                }
+                const data = await response.json();
+                const embeddings = texts.map((text, index) => ({
+                    text: text,
+                    vector: data.embeddings[index],
+                    model: "multilingual-e5-large",
+                    timestamp: new Date().toISOString()
+                }));
+
+                // Display the embeddings
+                outputVector.textContent = JSON.stringify(embeddings.length === 1 ? embeddings[0] : embeddings, null, 2);
+placeholder.classList.add('hidden');
+                outputContainer.classList.remove('hidden');
+                copyBtn.disabled = false;
+                downloadBtn.classList.remove('hidden');
+
+            } catch (error) {
+                alert(`Failed to generate embeddings: ${error.message}`);
+                console.error(error);
+            }
+
+            // Reset button
+            generateBtn.disabled = false;
+            generateBtn.innerHTML = '<i data-feather="zap" class="mr-2"></i> Generate Embeddings';
+            feather.replace();
+});
+
+        clearBtn.addEventListener('click', () => {
+            document.querySelectorAll('.text-input-group textarea').forEach(input => {
+                input.value = '';
+            });
+outputVector.textContent = '';
+            outputContainer.classList.add('hidden');
+            placeholder.classList.remove('hidden');
+            copyBtn.disabled = true;
+            downloadBtn.classList.add('hidden');
+        });
+
+        copyBtn.addEventListener('click', () => {
+            navigator.clipboard.writeText(outputVector.textContent)
+                .then(() => {
+                    copyBtn.innerHTML = '<i data-feather="check" class="mr-1"></i> Copied!';
+                    feather.replace();
+                    setTimeout(() => {
+                        copyBtn.innerHTML = '<i data-feather="copy" class="mr-1"></i> Copy';
+                        feather.replace();
+                    }, 2000);
+                });
+        });
+
+        downloadBtn.addEventListener('click', () => {
+            const blob = new Blob([outputVector.textContent], { type: 'application/json' });
+            const url = URL.createObjectURL(blob);
+            const a = document.createElement('a');
+            a.href = url;
+            a.download = `embedding-${new Date().getTime()}.json`;
+            document.body.appendChild(a);
+            a.click();
+            document.body.removeChild(a);
+            URL.revokeObjectURL(url);
+        });
+    </script>
+</body>
+</html>

pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "text2vector"
+version = "1.0.0"
+description = "API to call an embedding model"
+readme = "README.md"
+requires-python = ">=3.12"
+
+dependencies = [
+    "black>=25.9.0",
+    "fastapi>=0.119.0",
+    "httpx>=0.28.1",
+    "mypy>=1.18.2",
+    "pydantic>=2.12.0",
+    "pytest>=8.4.2",
+    "ruff>=0.14.0",
+    "torch>=2.8.0",
+    "transformers>=4.57.0",
+    "uvicorn>=0.37.0",
+]
+
+# https://quantlane.com/blog/type-checking-large-codebase/
+[tool.mypy]
+# Ensure full coverage
+disallow_untyped_calls = false
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+disallow_untyped_decorators = false
+check_untyped_defs = true
+
+# Restrict dynamic typing
+disallow_any_generics = false
+disallow_subclassing_any = false
+warn_return_any = false
+
+# Know exactly what you're doing
+warn_redundant_casts = true
+warn_unused_ignores = false
+warn_unused_configs = true
+warn_unreachable = true
+show_error_codes = true
+
+# Explicit is better than implicit
+no_implicit_optional = true

tests/test_api.py

@@ -0,0 +1,26 @@
+from fastapi.testclient import TestClient
+from app.main import app
+
+client = TestClient(app)
+
+
+def test_embed() -> None:
+    """Test the /embed endpoint with valid input."""
+    response = client.post("/embed", json={"texts": ["query: Hello world"]})
+    assert response.status_code == 200  # OK
+    data = response.json()
+    assert "embeddings" in data
+    assert len(data["embeddings"][0]) == 1024
+
+
+def test_embed_no_texts() -> None:
+    """Test the /embed endpoint with no texts provided."""
+    response = client.post("/embed", json={})
+    assert response.status_code == 422  # Unprocessable Entity
+
+
+def test_embed_long_text() -> None:
+    """Test the /embed endpoint with a text longer than 2000 characters."""
+    long_text = "query: " + "a" * 1994  # 2001 characters
+    response = client.post("/embed", json={"texts": [long_text]})
+    assert response.status_code == 422  # Unprocessable Entity

tests/test_embeddings.py

@@ -0,0 +1,56 @@
+from app.embeddings import average_pool, embed_text
+import torch
+import pytest
+
+
+def test_average_pool_basic() -> None:
+    """Test average pooling produces correct shape and masking."""
+    last_hidden_states = torch.tensor(
+        [
+            [[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]],
+            [[10.0, 20.0], [30.0, 40.0], [50.0, 60.0]],
+        ]
+    )  # shape: (2, 3, 2)
+    attention_mask = torch.tensor(
+        [
+            [1, 1, 0],
+            [1, 0, 0],
+        ]
+    )  # shape: (2, 3)
+
+    result = average_pool(last_hidden_states, attention_mask)
+
+    # Expected averages:
+    # row1: [(1+3)/2, (2+4)/2] = [2,3]
+    # row2: [10, 20]
+    expected = torch.tensor([[2.0, 3.0], [10.0, 20.0]])
+
+    assert torch.allclose(result, expected, atol=1e-6)
+    assert result.shape == (2, 2)
+
+
+def test_embed_text_valid() -> None:
+    """Test embedding returns correct number of vectors and dimensions."""
+
+    texts = ["query: Hello world", "query: Hej verden"]
+    embeddings = embed_text(texts)
+
+    # Assertions
+    assert isinstance(embeddings, list)
+    assert len(embeddings) == len(texts)
+    assert all(isinstance(vec, list) for vec in embeddings)
+    assert all(isinstance(x, float) for x in embeddings[0])
+    assert len(embeddings[0]) == 1024
+
+
+def test_embed_text_empty_list() -> None:
+    """Should raise ValueError if no input texts."""
+    with pytest.raises(ValueError, match="No input texts provided"):
+        embed_text([])
+
+
+def test_embed_text_too_long() -> None:
+    """Should raise ValueError for inputs exceeding 2000 characters."""
+    too_long = ["query: " + "a" * 1994]  # 2001 characters
+    with pytest.raises(ValueError, match="exceed the maximum length"):
+        embed_text(too_long)