Restore Space from backup SmartDataAlex-Jupyter-c7b4fea26ef24db6722dbe9f25079b9021943a46.tar.gz

.dockerignore

@@ -8,5 +8,4 @@
 backup*
 tests
 scripts/*
-!scripts/download_model.py
-!scripts/bench_local.py
+!scripts/download_model.py

.github/workflows/ci-deploy.yml

@@ -0,0 +1,80 @@
+name: Test, backup, deploy and verify
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: vectorization-hf-space
+  cancel-in-progress: false
+
+jobs:
+  unit-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: pip
+      - name: Install CPU-only dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install torch==2.6.0 --index-url https://download.pytorch.org/whl/cpu
+          python -m pip install -r requirements-dev.txt
+      - name: Test validation and authorization
+        run: pytest -q tests/test_app.py --junitxml=unit-results.xml
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: unit-test-results
+          path: unit-results.xml
+          retention-days: 90
+
+  backup-and-deploy:
+    needs: unit-tests
+    if: github.ref == 'refs/heads/main' && vars.HF_DEPLOY_ENABLED == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 70
+    env:
+      HF_TOKEN: ${{ secrets.HF_TOKEN }}
+      API_TEST_KEY: ${{ secrets.API_TEST_KEY }}
+      SPACE_URL: https://smartdataalex-jupyter.hf.space
+      EXPECTED_SHA: ${{ github.sha }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: python -m pip install 'huggingface-hub==0.30.2' 'httpx==0.28.1'
+      - name: Verify deployment credentials exist
+        run: |
+          test -n "$HF_TOKEN" || { echo 'Missing HF_TOKEN GitHub secret'; exit 1; }
+          test -n "$API_TEST_KEY" || { echo 'Missing API_TEST_KEY GitHub secret'; exit 1; }
+      - name: Backup existing Space before any modification
+        run: python scripts/backup_space.py
+      - name: Upload original Space snapshot
+        uses: actions/upload-artifact@v4
+        with:
+          name: space-backup-${{ github.run_id }}
+          path: ${{ runner.temp }}/hf-space-backup/
+          retention-days: 90
+          if-no-files-found: error
+      - name: Set release identifier
+        run: echo "$GITHUB_SHA" > VERSION
+      - name: Deploy backed-up revision to Hugging Face Docker Space
+        run: python scripts/deploy_space.py
+      - name: Smoke-test actual published API (must match this commit)
+        run: python scripts/smoke_live.py
+      - name: Upload deployment test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: live-api-results-${{ github.run_id }}
+          path: smoke-result.json
+          if-no-files-found: ignore
+          retention-days: 90

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+.pytest_cache/
+.venv/
+.env
+*.pyc
+backup*/
+smoke-result.json

Dockerfile

@@ -1,26 +1,31 @@
 FROM python:3.11-slim
+
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
     PIP_NO_CACHE_DIR=1 \
     E5_MODEL_DIR=/opt/models/multilingual-e5-small \
-    QWEN_MODEL_DIR=/opt/models/qwen3-embedding-0.6b \
-    COLBERT_MODEL_DIR=/opt/models/mlateon \
-    MEMORY_BUDGET_MB=15360 \
-    CPU_THREADS=2 \
-    OMP_NUM_THREADS=2 \
-    TOKENIZERS_PARALLELISM=false
+    CPU_THREADS=2
+
 WORKDIR /service
+
 RUN apt-get update && apt-get install -y --no-install-recommends libgomp1 \
     && rm -rf /var/lib/apt/lists/*
-RUN pip install --no-cache-dir torch==2.8.0 --index-url https://download.pytorch.org/whl/cpu
-COPY requirements.txt ./
+
+# Explicit CPU-only PyTorch wheel; no CUDA or GPU required.
+RUN pip install --no-cache-dir torch==2.6.0 --index-url https://download.pytorch.org/whl/cpu
+COPY requirements.txt .
 RUN pip install --no-cache-dir -r requirements.txt
+
+# Download only one copy of weights while building (immutable model revision).
 COPY scripts/download_model.py ./scripts/download_model.py
-COPY scripts/bench_local.py ./scripts/bench_local.py
 RUN python scripts/download_model.py
+
 COPY app ./app
 COPY VERSION ./VERSION
+
+# CPU inference is fully local at runtime.
 ENV HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1
+
 RUN useradd --uid 1000 --create-home appuser
 USER appuser
 EXPOSE 7860

README.md

@@ -8,147 +8,89 @@ app_port: 7860
 pinned: false
 ---
 
-# Vectorization API — three resident models
+# Vectorization API
 
-CPU-only FastAPI inference service. **All three models load once, during startup**, and remain resident. Inference never loads model weights. No search, Qdrant, Manticore, reranking or Entity Linking.
+CPU-only FastAPI embedding service for `intfloat/multilingual-e5-small` (384 dimensions).
 
-| Task | Model | Max tokens | Output |
-| --- | --- | ---: | --- |
-| Standard | `intfloat/multilingual-e5-small` | 512 | 384D |
-| Literature | `Qwen/Qwen3-Embedding-0.6B` | 32768 | 1024D |
-| ColBERT | `lightonai/mLateOn` | 8192 | 128D per token |
+## Endpoints
 
-## API
+- `POST /embed` (requires `X-API-Key`) takes `{ "text": "Example text", "type": "query" }` or type `passage`.
+- `GET /model` (requires `X-API-Key`) returns metadata, including dimensions and maximum token count.
+- `GET /health` is public, and returns ready only after the model has loaded.
+- `GET /docs` is public Swagger UI. Click **Authorize** and enter the API key to call protected endpoints.
 
-Legacy endpoints require `X-API-Key`; Voyage-compatible `/v1/embeddings` uses `Authorization: Bearer <API_KEY>`. Public endpoints: `/health`, `/docs` and `/openapi.json`.
-
-- `POST /embed`: `{"text":"Your text","type":"query"}` defaults to E5. The optional `model` accepts `e5`, `qwen`, or the corresponding full model name. The existing E5 response fields are unchanged: `text`, `type`, `tokens_count`, `embedding_model`, `dimensions`, `embedding`.
-- `POST /colbert/encode`: `{"text":"Your text","type":"passage"}` returns `embedding_model`, `tokens_count`, `dimensions` and `token_embeddings` (matrix of individual 128D vectors).
-- `GET /models`: readiness, dimensions, limits, normalization method, current/peak RSS and startup RAM readings for all models.
-- `GET /model`: original E5-only metadata contract.
-- `GET /health`: returns 200 only when all three models have completed startup.
-
-Example (replace URL and key):
+Example:
 
 ```bash
-curl -sS -X POST 'http://localhost:7860/embed' \
-  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
-  -d '{"text":"What does the author mean?","type":"query","model":"qwen"}'
-
-curl -sS -X POST 'http://localhost:7860/colbert/encode' \
-  -H 'X-API-Key: YOUR_API_KEY' -H 'Content-Type: application/json' \
-  -d '{"text":"שלום עולם","type":"passage"}'
+curl -fsS -X POST 'https://smartdataalex-jupyter.hf.space/embed' \
+  -H 'Content-Type: application/json' \
+  -H 'X-API-Key: YOUR_API_KEY' \
+  -d '{"text":"How to find similar documents?","type":"query"}'
 ```
 
-E5 keeps `query: ` / `passage: ` prefixes, attention-mask-aware mean pooling, **no extra L2 normalization**. Qwen uses its official query instruction + last-token pooling + L2 normalization; documents have no instruction. PyLate mLateOn handles query and passage separately, retaining token vectors and their model-native normalization. Token limits are checked *including model markers and special tokens*, without silent truncation. Exceeding limits or using invalid input returns HTTP 422. When the shared inference gate is occupied, requests return HTTP 429 with `Retry-After`.
+Sample response structure (embedding values are illustrative, complete real response contains 384 floats):
+
+```json
+{
+  "text": "How to find similar documents?",
+  "type": "query",
+  "tokens_count": 10,
+  "embedding_model": "intfloat/multilingual-e5-small",
+  "dimensions": 384,
+  "embedding": [0.12, -0.03]
+}
+```
 
-## Official Voyage AI SDK compatibility
+The service adds `query: ` / `passage: ` according to `type`, uses the model's own tokenizer and attention-mask-aware mean pooling. `tokens_count` includes the prefix and tokenizer's special tokens. Inputs over 512 tokens, including prefix and special tokens, get HTTP 422; inputs are **never silently truncated**. Input length is limited to 4096 characters as an additional resource guard.
 
-The **unmodified Voyage Python client** can talk directly to our service.
-The base URL includes `/v1` (not `/v1/embeddings`):
+**No extra L2 normalization** is applied by the service. Configure your Qdrant vector collection with dimension `384` and distance `Cosine`; Qdrant will normalize stored vectors. No database, search, or document storage is implemented here.
 
-```python
-import voyageai
+## Secrets and one-time deployment setup
 
-client = voyageai.Client(
-    api_key="YOUR_API_KEY",
-    base_url="https://YOUR-SPACE.hf.space/v1",
-)
+1. In **Hugging Face → SmartDataAlex/Jupyter → Settings → Secrets**, set `API_KEY` to a long, random, private value. Secrets are exposed to Docker as environment variables. Never commit this value.
+2. In GitHub repository secrets, set `HF_TOKEN` to a **fine-grained Hugging Face write token** restricted to the existing Space, and `API_TEST_KEY` to the *same* API key value (for post-deploy authenticated smoke tests).
+3. After verifying GitHub is connected to this repository and that you are ready for the Space's contents to be replaced, add GitHub repository variable `HF_DEPLOY_ENABLED` with value `true`.
+4. Each subsequent push to `main` tests source code, **backs up the current Space first**, deploys using a guarded Hugging Face Hub commit, and tests the deployed public HTTPS API. CI uploads JSON test results and the pre-deploy backup as GitHub Actions artifacts. If backup fails, deployment does **not** run.
 
-documents = client.embed(
-    ["Первый чанк", "Второй чанк"],
-    model="e5",               # or "qwen"
-    input_type="document",
-    truncation=False,
-)
-print(documents.embeddings)   # list of 384D or 1024D vectors
-print(documents.total_tokens)
+**Important:** deployment replaces Space files after successful backup. It also refuses to overwrite the Space if its revision changed after the backup. This workflow intentionally does not deploy without `HF_DEPLOY_ENABLED=true`. Backups are retained as GitHub Actions artifacts for 90 days. Keep an additional durable copy of the initial backup before deleting old workflow artifacts; the Space's Git history also provides rollback revisions.
 
-query = client.embed(
-    ["Что происходило в книге?"],
-    model="qwen",
-    input_type="query",
-)
-```
+No additional `API_KEY` parameter is added to the JSON request body. All API key checks happen via the `X-API-Key` request header. If the runtime secret is missing, the application fails to start rather than permitting anonymous access.
 
-The official client sends `POST /v1/embeddings` with Bearer authorization,
-`input`, `model`, `input_type`, `truncation`, and optional output settings.
-Our response implements Voyage's standard `object`/`data`/`model`/`usage`
-envelope; the SDK's `EmbeddingsObject.embeddings` and `total_tokens` work.
-
-Model names: `e5`, `qwen`, `colbert` (or the corresponding full Hugging Face IDs).
-`input_type="query"` selects query instructions, `input_type="document"` selects
-document/passage encoding; an omitted type defaults to document.
-A single string or a list of 1–1000 strings is accepted.
-
-`model="colbert"` is a **non-standard multi-vector extension**:
-the standard Voyage client will expose `embeddings` as a 3-D array
-`[document][token][128]`. This is not interchangeable with regular
-Voyage dense embeddings or dense-only vector database integrations.
-
-All three models are already loaded in RAM. Batch calls use **actual model
-batch inference** where possible: E5 and Qwen run padded tensor batches,
-and mLateOn uses PyLate's batch encoding. The server partitions requests
-by padded token cost to protect 16-GiB CPU memory. Requests are limited to
-65,536 aggregate tokens for dense vectors or 32,768 for ColBERT.
-Requests beyond these limits return HTTP 422 rather than truncating content;
-even `truncation=True` from Voyage's default SDK settings cannot override
-our no-silent-truncation policy. Only float output and the fixed model
-dimensions are supported; quantization, changing dimensions, and Voyage's
-other API families are not implemented.
-
-Unmodified-SDK integration smoke test:
+## Local development
 
 ```bash
-pip install voyageai==0.5.0
-SPACE_URL=http://localhost:7860 API_TEST_KEY='your-strong-api-key' \
-  python scripts/smoke_voyage_sdk.py
-```
-
-## Deployment, RAM and rollback
-
-Docker downloads immutable checkpoints at image build, and runtime operates offline. Startup fails if any of the three models cannot be loaded or exceeds the configured resident memory budget. The default `MEMORY_BUDGET_MB=15360` reserves memory within a nominal 16-GiB container. Run exactly **one** Uvicorn worker and one concurrent inference.
-
-```bash
-docker build -t vectorization:three-models .
-docker run --rm -p 7860:7860 --memory 16g \
-  -e API_KEY='your-strong-api-key' vectorization:three-models
+# CPU PyTorch: install per https://pytorch.org/get-started/locally/
+python -m pip install -r requirements-dev.txt
+# Download the pinned model into E5_MODEL_DIR (Docker does this at build time)
+export API_KEY='local-only-long-random-value'
+export E5_MODEL_DIR='/path/to/downloaded/model'
+uvicorn app.main:app --host 127.0.0.1 --port 7860
 ```
 
-16 GiB RAM is a target, **not verified sufficient** for 32768-token Qwen inference. Validate longest contexts on the target server, including peak RSS, CPU time and stability. Do not lower the advertised token limits if tests fail.
-
-### Tests
+Unit tests do not download model weights:
 
 ```bash
-python -m pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cpu
-python -m pip install -r requirements-dev.txt
-pytest -q tests/test_app.py --junitxml=unit-results.xml
-
-SPACE_URL=http://localhost:7860 API_TEST_KEY='your-strong-api-key' \
-  python scripts/smoke_live.py
+pytest -q tests/test_app.py
 ```
 
-Unit tests stub model weights. Only a real Space smoke test demonstrates end-to-end inference. For separate 16-GiB RAM/CPU benchmark runs using the downloaded Docker model weights:
+Post-deploy check:
 
 ```bash
-docker run --rm --memory 16g --entrypoint python -e BENCH_LONG=1 \
-  -v "$PWD/reports:/service/reports" \
-  -e BENCH_REPORT=/service/reports/bench-result.json \
-  vectorization:three-models scripts/bench_local.py
+SPACE_URL='https://smartdataalex-jupyter.hf.space' \
+API_TEST_KEY='your-key' \
+python scripts/smoke_live.py
 ```
 
-The benchmark loads all three models at startup and saves timings plus process RSS after every case.
-
-### Preserve the existing Space
+The actual Space URL must be verified once the Space is published.
 
-GitHub Actions runs unit tests on PRs and pushes. **Automatic production deployment from `main` is opt-in:** set the GitHub repository variable `HF_AUTO_DEPLOY_ENABLED=true` and secrets `GIT_TOKEN` plus `API_TEST_KEY`. After a successful test run on each new commit to `main`, Actions backs up the current Space, deploys with commit/revision protection, and runs the old API and official Voyage SDK smoke tests. If a post-deployment smoke check fails, the workflow attempts a revision-guarded automatic restore from the backup. Manual deployment is also available from `main` through `workflow_dispatch` (`deploy=true`) with `HF_DEPLOY_ENABLED=true`. Commits to feature branches and PRs never deploy the production Space. Production runs and PR runs use separate concurrency groups, so a PR update cannot interrupt a deployment. The existing workflow first makes a complete backup of `SmartDataAlex/Jupyter`, uploads it as a CI artifact, deploys only if the Space revision matches the backup and runs real authenticated smoke tests. If the backup fails, deployment is blocked.
+## Rollback
 
-Manual rollback using a saved backup:
+Retrieve the `space-backup-<run_id>` artifact from a previous GitHub Actions run, unzip it to obtain `SmartDataAlex-Jupyter-<revision>.tar.gz`, and run:
 
 ```bash
-HF_TOKEN='space-scoped-write-token' python scripts/restore_space.py \
+HF_TOKEN='your-space-scoped-write-token' python scripts/restore_space.py \
   SmartDataAlex-Jupyter-<revision>.tar.gz \
   --confirm-space SmartDataAlex/Jupyter
 ```
 
-Store a permanent backup separately; GitHub Actions artifacts expire.
+This operation explicitly overwrites the current Space content to restore the saved files; it does not run automatically after a failed smoke test, because automatic rollback could mask a deployment failure. Secrets managed in Hugging Face Space Settings are stored separately from the repository and are not contained in the archive.

VERSION

@@ -1 +1 @@
-f2db93bf98da4215ba2bca5a47adf4565ba5e739
+development

app/batching.py

@@ -1,133 +0,0 @@
-"""True token-budgeted batched inference with resident models.
-
-The external service-wide inference gate is held by ModelRegistry for the full call.
-No model initialization, truncation, or extra E5 normalization occurs here.
-"""
-from __future__ import annotations
-
-from app.embedding import EmbeddingResult, TooManyTokens
-from app.models import ColbertResult, validate_vector, INSTRUCTION
-
-
-def _split_by_padding_cost(counts, token_budget, max_size):
-    """Partition ordered inputs, accounting for batch padding to longest text."""
-    groups = []
-    current = []
-    current_max = 0
-    for index, count in enumerate(counts):
-        proposed_max = max(current_max, count)
-        if current and (len(current) >= max_size or
-                        proposed_max * (len(current) + 1) > token_budget):
-            groups.append(current)
-            current = []
-            current_max = 0
-        current.append(index)
-        current_max = max(current_max, count)
-    if current:
-        groups.append(current)
-    return groups
-
-
-def _token_count(tokenizer, text):
-    encoded = tokenizer(text, add_special_tokens=True, truncation=False)
-    return len(encoded["input_ids"])
-
-
-def _dense_batch(engine, texts, kind, is_qwen):
-    if is_qwen:
-        strings = [
-            f"Instruct: {INSTRUCTION}\nQuery:{text}" if kind == "query" else text
-            for text in texts
-        ]
-        # Smaller padded batches limit CPU activation memory; single long
-        # documents are still allowed up to the model's advertised context.
-        budget, max_size = 4096, 16
-    else:
-        strings = [f"{kind}: {text}" for text in texts]
-        budget, max_size = 8192, 64
-
-    counts = [_token_count(engine.tokenizer, text) for text in strings]
-    for count in counts:
-        if count > engine.max_tokens:
-            raise TooManyTokens(count, engine.max_tokens)
-    # Bound total work in one HTTP request (not the model context limit).
-    if sum(counts) > 65536:
-        raise ValueError("Batch exceeds 65536 total input tokens")
-
-    results = [None] * len(texts)
-    for group in _split_by_padding_cost(counts, budget, max_size):
-        inputs = [strings[i] for i in group]
-        batch = engine.tokenizer(
-            inputs, return_tensors="pt", padding=True,
-            truncation=False, add_special_tokens=True,
-        )
-        with engine.torch.inference_mode():
-            hidden = engine.model(**batch).last_hidden_state
-            if is_qwen:
-                # Qwen tokenizer is explicitly left padded. The final index
-                # therefore refers to the final real token in every row.
-                vectors = engine.torch.nn.functional.normalize(
-                    hidden[:, -1, :], p=2, dim=1,
-                )
-            else:
-                mask = batch["attention_mask"].unsqueeze(-1)
-                vectors = (hidden * mask).sum(dim=1) / mask.sum(dim=1).clamp(min=1)
-
-            vectors = vectors.float().cpu().tolist()
-
-        for index, vector in zip(group, vectors):
-            validate_vector(vector, engine.dimensions)
-            results[index] = EmbeddingResult(
-                tokens_count=counts[index], embedding=vector,
-            )
-    return results
-
-
-def _colbert_batch(engine, texts, kind):
-    model = engine.model
-    query = kind == "query"
-    prefix = model.query_prefix if query else model.document_prefix
-    counts = [_token_count(model.tokenizer, prefix + text) for text in texts]
-    for count in counts:
-        if count > engine.max_tokens:
-            raise TooManyTokens(count, engine.max_tokens)
-    if sum(counts) > 32768:
-        raise ValueError("ColBERT request exceeds 32768 total input tokens")
-
-    results = [None] * len(texts)
-    for group in _split_by_padding_cost(counts, 4096, 8):
-        if query:
-            model.query_length = max(32, max(counts[i] for i in group))
-        outputs = model.encode(
-            [texts[i] for i in group],
-            is_query=query, batch_size=len(group), show_progress_bar=False,
-        )
-        if len(outputs) != len(group):
-            raise RuntimeError("Unexpected PyLate batch length")
-        for index, matrix in zip(group, outputs):
-            if hasattr(matrix, "detach"):
-                matrix = matrix.detach().float().cpu()
-            if hasattr(matrix, "tolist"):
-                matrix = matrix.tolist()
-            vectors = [[float(value) for value in row] for row in matrix]
-            if not vectors or len(vectors) > engine.max_tokens:
-                raise RuntimeError("Unexpected PyLate output token count")
-            for vector in vectors:
-                validate_vector(vector, engine.dimensions)
-            # Note: encoded tokens and emitted token vectors may differ
-            # because PyLate can filter special/padding tokens.
-            results[index] = ColbertResult(
-                tokens_count=counts[index], token_embeddings=vectors,
-            )
-    return results
-
-
-def batch_encode(engine, texts, kind, is_qwen=False, is_colbert=False):
-    """Native tensor batch for real models, single-item fallback for test doubles."""
-    if is_colbert:
-        if not hasattr(engine, "model") or not hasattr(engine.model, "tokenizer"):
-            return [engine.encode(text, kind) for text in texts]
-        return _colbert_batch(engine, texts, kind)
-    if not hasattr(engine, "tokenizer") or not hasattr(engine, "model"):
-        return [engine.encode(text, kind) for text in texts]
-    return _dense_batch(engine, texts, kind, is_qwen)

app/main.py

@@ -1,9 +1,12 @@
-"""FastAPI HTTP-only vectorization service."""
+"""HTTP service: authenticate, validate, and generate embeddings only."""
+
+from __future__ import annotations
+
 import logging
 import os
 import secrets
-from pathlib import Path
 from contextlib import asynccontextmanager
+from pathlib import Path
 from typing import Literal
 
 from fastapi import Depends, FastAPI, HTTPException, Security
@@ -11,66 +14,51 @@ from fastapi.responses import RedirectResponse
 from fastapi.security import APIKeyHeader
 from pydantic import BaseModel, Field, field_validator
 
-from app.embedding import MODEL_ID, TooManyTokens
-from app.models import (
-    ModelRegistry, QWEN_ID, COLBERT_ID, ServiceBusy, memory_mb,
+from app.embedding import (
+    MODEL_ID,
+    EmbeddingEngine,
+    TooManyTokens,
 )
 
-log = logging.getLogger(__name__)
+logger = logging.getLogger(__name__)
 api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
-EmbeddingModel = Literal[
-    "e5", "qwen", "intfloat/multilingual-e5-small", "Qwen/Qwen3-Embedding-0.6B"
-]
 
 
-def deployment_version():
+def deployment_version() -> str:
     path = Path(__file__).resolve().parent.parent / "VERSION"
     return path.read_text(encoding="utf-8").strip() if path.is_file() else "development"
 
 
 @asynccontextmanager
-async def lifespan(application: FastAPI):
+async def lifespan(app: FastAPI):
+    # Fail closed: an unset secret must never expose unauthenticated inference.
     if not os.getenv("API_KEY"):
-        raise RuntimeError("API_KEY must be configured")
-    # All three models become resident before health becomes ready.
-    application.state.registry = ModelRegistry.load()
-    try:
-        yield
-    finally:
-        application.state.registry = None
-
+        raise RuntimeError("API_KEY must be configured in Hugging Face Space Secrets")
+    app.state.engine = EmbeddingEngine.load()
+    yield
+    app.state.engine = None
 
-from app.voyage_api import router as voyage_router
 
 app = FastAPI(
     title="Vectorization API",
-    version="2.0.0",
-    description="Resident E5, Qwen3 and mLateOn CPU embedding API.",
+    version="1.0.0",
+    description="CPU embedding service backed by intfloat/multilingual-e5-small.",
     lifespan=lifespan,
 )
 
 
-app.include_router(voyage_router)
-
-
-class TextRequest(BaseModel):
-    text: str = Field(min_length=1, description="Full input, no silent truncation")
-    type: Literal["query", "passage"] = Field(examples=["query"])
+class EmbedRequest(BaseModel):
+    text: str = Field(min_length=1, max_length=4096)
+    type: Literal["query", "passage"]
 
     @field_validator("text")
     @classmethod
-    def nonblank(cls, text):
+    def reject_blank_text(cls, text: str) -> str:
         if not text.strip():
             raise ValueError("Text must not be blank")
         return text
 
 
-class EmbedRequest(TextRequest):
-    model: EmbeddingModel | None = Field(
-        default=None, examples=["qwen"], description="E5 by default"
-    )
-
-
 class EmbedResponse(BaseModel):
     text: str
     type: Literal["query", "passage"]
@@ -80,13 +68,6 @@ class EmbedResponse(BaseModel):
     embedding: list[float]
 
 
-class ColbertResponse(BaseModel):
-    embedding_model: str
-    tokens_count: int
-    dimensions: int
-    token_embeddings: list[list[float]]
-
-
 class ModelResponse(BaseModel):
     embedding_model: str
     dimensions: int
@@ -95,31 +76,21 @@ class ModelResponse(BaseModel):
     version: str
 
 
-def require_api_key(provided: str | None = Security(api_key_header)):
+def require_api_key(provided: str | None = Security(api_key_header)) -> None:
     expected = os.getenv("API_KEY")
     if not expected or provided is None or not secrets.compare_digest(provided, expected):
-        raise HTTPException(status_code=401, detail="Invalid or missing API key",
-                            headers={"WWW-Authenticate": "ApiKey"})
-
+        raise HTTPException(
+            status_code=401,
+            detail="Invalid or missing API key",
+            headers={"WWW-Authenticate": "ApiKey"},
+        )
 
-def get_registry():
-    registry = getattr(app.state, "registry", None)
-    if registry is None:
-        raise HTTPException(status_code=503, detail="Models are not ready")
-    return registry
 
-
-def guard(callback):
-    try:
-        return callback()
-    except TooManyTokens as exc:
-        raise HTTPException(status_code=422, detail=str(exc)) from exc
-    except ServiceBusy as exc:
-        raise HTTPException(status_code=429, detail=str(exc),
-                            headers={"Retry-After": "2"}) from exc
-    except Exception as exc:
-        log.exception("Inference failed")
-        raise HTTPException(status_code=500, detail="Inference failed") from exc
+def get_engine() -> EmbeddingEngine:
+    engine = getattr(app.state, "engine", None)
+    if engine is None:
+        raise HTTPException(status_code=503, detail="Model is not ready")
+    return engine
 
 
 @app.get("/", include_in_schema=False)
@@ -129,59 +100,35 @@ def root():
 
 @app.get("/health")
 def health():
-    if getattr(app.state, "registry", None) is None:
-        raise HTTPException(status_code=503, detail="Models are not ready")
+    if getattr(app.state, "engine", None) is None:
+        raise HTTPException(status_code=503, detail="Model is not ready")
     return {"status": "ok", "version": deployment_version()}
 
 
 @app.get("/model", response_model=ModelResponse, dependencies=[Depends(require_api_key)])
-def model_info(registry=Depends(get_registry)):
+def model_info(engine: EmbeddingEngine = Depends(get_engine)) -> ModelResponse:
     return ModelResponse(
-        embedding_model=MODEL_ID, dimensions=registry.e5.dimensions,
-        max_input_tokens=registry.e5.max_tokens, version=deployment_version(),
+        embedding_model=MODEL_ID,
+        dimensions=engine.dimensions,
+        max_input_tokens=engine.max_tokens,
+        version=deployment_version(),
     )
 
 
-@app.get("/models", dependencies=[Depends(require_api_key)])
-def models_info(registry=Depends(get_registry)):
-    return {
-        "version": deployment_version(),
-        "models": [
-            {"embedding_model": MODEL_ID, "purpose": "standard",
-             "dimensions": registry.e5.dimensions,
-             "max_input_tokens": registry.e5.max_tokens,
-             "normalization": "none", "ready": True},
-            {"embedding_model": QWEN_ID, "purpose": "literature",
-             "dimensions": registry.qwen.dimensions,
-             "max_input_tokens": registry.qwen.max_tokens,
-             "normalization": "l2", "ready": True},
-            {"embedding_model": COLBERT_ID, "purpose": "colbert",
-             "dimensions": registry.colbert.dimensions,
-             "max_input_tokens": registry.colbert.max_tokens,
-             "normalization": "model-native", "ready": True},
-        ],
-        "resources": memory_mb(),
-        "startup_memory": registry.startup_memory,
-    }
-
-
-@app.post("/embed", response_model=EmbedResponse,
-          dependencies=[Depends(require_api_key)])
-def embed(payload: EmbedRequest, registry=Depends(get_registry)):
-    identifier, dimensions, result = guard(
-        lambda: registry.embed(payload.text, payload.type, payload.model)
-    )
+@app.post("/embed", response_model=EmbedResponse, dependencies=[Depends(require_api_key)])
+def embed(payload: EmbedRequest, engine: EmbeddingEngine = Depends(get_engine)) -> EmbedResponse:
+    try:
+        result = engine.encode(payload.text, payload.type)
+    except TooManyTokens as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    except Exception as exc:
+        logger.exception("Embedding generation failed")
+        raise HTTPException(status_code=500, detail="Embedding generation failed") from exc
     return EmbedResponse(
-        text=payload.text, type=payload.type, tokens_count=result.tokens_count,
-        embedding_model=identifier, dimensions=dimensions, embedding=result.embedding,
-    )
-
-
-@app.post("/colbert/encode", response_model=ColbertResponse,
-          dependencies=[Depends(require_api_key)])
-def colbert_encode(payload: TextRequest, registry=Depends(get_registry)):
-    result = guard(lambda: registry.colbert_encode(payload.text, payload.type))
-    return ColbertResponse(
-        embedding_model=COLBERT_ID, dimensions=registry.colbert.dimensions,
-        tokens_count=result.tokens_count, token_embeddings=result.token_embeddings,
+        text=payload.text,
+        type=payload.type,
+        tokens_count=result.tokens_count,
+        embedding_model=MODEL_ID,
+        dimensions=engine.dimensions,
+        embedding=result.embedding,
     )

app/models.py

@@ -1,183 +0,0 @@
-"""Resident E5, Qwen3 and PyLate mLateOn. No per-request model loading."""
-import gc
-import math
-import os
-import resource
-import threading
-from pathlib import Path
-from dataclasses import dataclass
-
-from app.embedding import EmbeddingEngine, EmbeddingResult, MODEL_ID as E5_ID, TooManyTokens
-
-QWEN_ID = "Qwen/Qwen3-Embedding-0.6B"
-COLBERT_ID = "lightonai/mLateOn"
-QWEN_MAX = 32768
-COLBERT_MAX = 8192
-INSTRUCTION = "Given a question, retrieve relevant passages that answer the question"
-
-
-class ServiceBusy(Exception):
-    pass
-
-
-def memory_mb():
-    current = None
-    try:
-        with open("/proc/self/status", encoding="utf-8") as f:
-            for line in f:
-                if line.startswith("VmRSS:"):
-                    current = round(int(line.split()[1]) / 1024, 1)
-                    break
-    except OSError:
-        pass
-    peak = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
-    return {"rss_mb": current, "peak_rss_mb": round(peak / 1024, 1),
-            "budget_mb": int(os.getenv("MEMORY_BUDGET_MB", "15360"))}
-
-
-def validate_vector(vector, dimensions):
-    if len(vector) != dimensions or any(not math.isfinite(v) for v in vector):
-        raise RuntimeError("Invalid embedding vector")
-
-
-class QwenEngine:
-    dimensions = 1024
-    max_tokens = QWEN_MAX
-
-    def __init__(self, tokenizer, model, torch):
-        self.tokenizer, self.model, self.torch = tokenizer, model, torch
-
-    @classmethod
-    def load(cls):
-        import torch
-        from transformers import AutoModel, AutoTokenizer
-        path = os.getenv("QWEN_MODEL_DIR", "/opt/models/qwen3-embedding-0.6b")
-        tokenizer = AutoTokenizer.from_pretrained(path, padding_side="left",
-                                                   local_files_only=True)
-        model = AutoModel.from_pretrained(path, torch_dtype=torch.float32,
-                                          attn_implementation="sdpa",
-                                          local_files_only=True).to("cpu").eval()
-        if int(model.config.hidden_size) != 1024:
-            raise RuntimeError("Incorrect Qwen output size")
-        return cls(tokenizer, model, torch)
-
-    def encode(self, text, kind):
-        inp = (f"Instruct: {INSTRUCTION}\nQuery:{text}"
-               if kind == "query" else text)
-        tokens = self.tokenizer(inp, add_special_tokens=True, truncation=False,
-                                return_tensors="pt")
-        count = int(tokens["attention_mask"].sum().item())
-        if count > self.max_tokens:
-            raise TooManyTokens(count, self.max_tokens)
-        with self.torch.inference_mode():
-            last = self.model(**tokens).last_hidden_state[:, -1, :]
-            normalized = self.torch.nn.functional.normalize(last, p=2, dim=1)
-            values = normalized[0].float().cpu().tolist()
-        validate_vector(values, self.dimensions)
-        return EmbeddingResult(tokens_count=count, embedding=values)
-
-
-@dataclass(frozen=True)
-class ColbertResult:
-    tokens_count: int
-    token_embeddings: list[list[float]]
-
-
-class ColbertEngine:
-    dimensions = 128
-    max_tokens = COLBERT_MAX
-
-    def __init__(self, model):
-        self.model = model
-
-    @classmethod
-    def load(cls):
-        from pylate import models
-        model = models.ColBERT(
-            model_name_or_path=os.getenv("COLBERT_MODEL_DIR", "/opt/models/mlateon"),
-            device="cpu", query_length=32, document_length=COLBERT_MAX,
-        )
-        model.eval()
-        model.document_length = COLBERT_MAX
-        return cls(model)
-
-    def encode(self, text, kind):
-        is_query = kind == "query"
-        prefix = self.model.query_prefix if is_query else self.model.document_prefix
-        tokens = self.model.tokenizer(f"{prefix}{text}", add_special_tokens=True,
-                                      truncation=False)
-        count = len(tokens["input_ids"])
-        if count > self.max_tokens:
-            raise TooManyTokens(count, self.max_tokens)
-        if is_query:
-            # PyLate pads queries to query_length. Never pad short queries to 8192.
-            self.model.query_length = max(32, count)
-        output = self.model.encode([text], is_query=is_query, batch_size=1,
-                                   show_progress_bar=False)
-        if len(output) != 1:
-            raise RuntimeError("Unexpected PyLate batch size")
-        matrix = output[0]
-        if hasattr(matrix, "detach"):
-            matrix = matrix.detach().float().cpu()
-        if hasattr(matrix, "tolist"):
-            matrix = matrix.tolist()
-        vectors = [[float(x) for x in row] for row in matrix]
-        if not vectors or len(vectors) > COLBERT_MAX:
-            raise RuntimeError("Unexpected PyLate output length")
-        for row in vectors:
-            validate_vector(row, self.dimensions)
-        return ColbertResult(tokens_count=len(vectors), token_embeddings=vectors)
-
-
-class ModelRegistry:
-    def __init__(self, e5, qwen, colbert, startup_memory=None):
-        self.e5, self.qwen, self.colbert = e5, qwen, colbert
-        self.startup_memory = startup_memory or {}
-        self._gate = threading.BoundedSemaphore(1)
-
-    @classmethod
-    def load(cls):
-        import torch
-        torch.set_num_threads(max(1, min(4, int(os.getenv("CPU_THREADS", "2")))))
-        readings = {}
-        e5 = EmbeddingEngine.load()
-        readings["e5"] = memory_mb()
-        qwen = QwenEngine.load()
-        readings["qwen"] = memory_mb()
-        colbert = ColbertEngine.load()
-        readings["colbert"] = memory_mb()
-        gc.collect()
-        ram = memory_mb()
-        if ram["rss_mb"] is not None and ram["rss_mb"] > ram["budget_mb"]:
-            raise MemoryError("All resident models exceed RAM budget")
-        return cls(e5, qwen, colbert, readings)
-
-    def _run(self, callback):
-        if not self._gate.acquire(blocking=False):
-            raise ServiceBusy("Inference busy; retry later")
-        try:
-            return callback()
-        finally:
-            self._gate.release()
-
-    def embed(self, text, kind, selected):
-        engine = self.qwen if selected in ("qwen", QWEN_ID) else self.e5
-        result = self._run(lambda: engine.encode(text, kind))
-        return (QWEN_ID if engine is self.qwen else E5_ID), engine.dimensions, result
-
-    def colbert_encode(self, text, kind):
-        return self._run(lambda: self.colbert.encode(text, kind))
-
-
-    def voyage_encode(self, texts, kind, canonical_model):
-        """Atomic inference gate protects all microbatches in one HTTP request."""
-        from app.batching import batch_encode
-        if canonical_model == E5_ID:
-            engine, mode = self.e5, {}
-        elif canonical_model == QWEN_ID:
-            engine, mode = self.qwen, {"is_qwen": True}
-        elif canonical_model == COLBERT_ID:
-            engine, mode = self.colbert, {"is_colbert": True}
-        else:
-            raise ValueError("Unknown model")
-        return self._run(lambda: batch_encode(engine, texts, kind, **mode))

app/voyage_api.py

@@ -1,130 +0,0 @@
-"""Voyage AI Python SDK compatible /v1/embeddings facade.
-
-Voyage Client(base_url="https://host/v1", api_key="...").embed(...)
-works without a custom client. ColBERT's nested token vectors are an
-intentional 3-D extension; Voyage ordinarily returns one dense vector/input.
-"""
-import os
-import secrets
-from typing import Literal
-
-from fastapi import APIRouter, Depends, HTTPException, Security
-from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
-from pydantic import BaseModel, Field, field_validator
-
-from app.embedding import MODEL_ID as E5_ID, TooManyTokens
-from app.models import COLBERT_ID, QWEN_ID, ServiceBusy, ModelRegistry
-
-router = APIRouter()
-bearer = HTTPBearer(auto_error=False)
-ModelName = Literal[
-    "e5", "qwen", "colbert",
-    "intfloat/multilingual-e5-small",
-    "Qwen/Qwen3-Embedding-0.6B",
-    "lightonai/mLateOn",
-]
-
-
-class VoyageEmbedRequest(BaseModel):
-    input: str | list[str] = Field(
-        description="One text or a list of texts; max 1000 texts per request",
-        examples=[["The first chunk", "The second chunk"]],
-    )
-    model: ModelName = Field(examples=["qwen"])
-    input_type: Literal["query", "document"] | None = Field(default=None)
-    truncation: bool = Field(
-        default=True,
-        description="Accepted for SDK compatibility; this service never truncates silently",
-    )
-    output_dtype: Literal["float", "float32"] | None = None
-    output_dimension: int | None = None
-    encoding_format: Literal["base64", "float"] | None = None
-
-    @field_validator("input")
-    @classmethod
-    def check_input(cls, value):
-        texts = [value] if isinstance(value, str) else value
-        if not texts or len(texts) > 1000:
-            raise ValueError("Batch must contain between 1 and 1000 texts")
-        if any(not isinstance(text, str) or not text.strip() for text in texts):
-            raise ValueError("Each input must be a nonblank string")
-        return value
-
-
-def authenticate(credentials: HTTPAuthorizationCredentials | None = Security(bearer)):
-    expected = os.getenv("API_KEY")
-    if (
-        not expected or credentials is None
-        or not secrets.compare_digest(credentials.credentials, expected)
-    ):
-        raise HTTPException(
-            status_code=401, detail="Invalid or missing API key",
-            headers={"WWW-Authenticate": "Bearer"},
-        )
-
-
-def resident_models():
-    # import here avoids app/router circular module initialization.
-    from app.main import app
-    registry = getattr(app.state, "registry", None)
-    if registry is None:
-        raise HTTPException(status_code=503, detail="Models are not ready")
-    return registry
-
-
-@router.post("/v1/embeddings", dependencies=[Depends(authenticate)])
-def embeddings(payload: VoyageEmbedRequest, registry: ModelRegistry = Depends(resident_models)):
-    texts = [payload.input] if isinstance(payload.input, str) else payload.input
-    model = payload.model
-    canonical = {
-        "e5": E5_ID, E5_ID: E5_ID,
-        "qwen": QWEN_ID, QWEN_ID: QWEN_ID,
-        "colbert": COLBERT_ID, COLBERT_ID: COLBERT_ID,
-    }[model]
-    dimensions = {
-        E5_ID: registry.e5.dimensions,
-        QWEN_ID: registry.qwen.dimensions,
-        COLBERT_ID: registry.colbert.dimensions,
-    }[canonical]
-    if payload.output_dimension is not None and payload.output_dimension != dimensions:
-        raise HTTPException(
-            status_code=422,
-            detail=f"Model {canonical} only supports {dimensions} dimensions",
-        )
-
-    # Voyage's None mode has no equivalent for asymmetric E5/Qwen/ColBERT.
-    # Consistently treat it as 'document'. input_type remains recommended.
-    kind = "query" if payload.input_type == "query" else "passage"
-    try:
-        results = registry.voyage_encode(texts, kind, canonical)
-    except TooManyTokens as exc:
-        raise HTTPException(status_code=422, detail=str(exc)) from exc
-    except ServiceBusy as exc:
-        raise HTTPException(
-            status_code=429, detail=str(exc), headers={"Retry-After": "2"}
-        ) from exc
-    except ValueError as exc:
-        raise HTTPException(status_code=422, detail=str(exc)) from exc
-    except Exception as exc:
-        import logging
-        logging.getLogger(__name__).exception("Voyage embedding failed")
-        raise HTTPException(status_code=500, detail="Embedding failed") from exc
-
-    return {
-        "object": "list",
-        "data": [
-            {
-                "object": "embedding",
-                "index": index,
-                "embedding": (
-                    result.token_embeddings
-                    if canonical == COLBERT_ID else result.embedding
-                ),
-            }
-            for index, result in enumerate(results)
-        ],
-        "model": model,
-        "usage": {
-            "total_tokens": sum(item.tokens_count for item in results),
-        },
-    }

pyproject.toml

@@ -0,0 +1,3 @@
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]

requirements-dev.txt

@@ -0,0 +1,3 @@
+-r requirements.txt
+pytest==8.3.5
+httpx==0.28.1

requirements.txt

@@ -1,9 +1,6 @@
-torch==2.8.0+cpu
 fastapi==0.115.12
 uvicorn==0.34.2
-transformers==4.56.2
-huggingface-hub==0.36.0
-sentence-transformers==5.1.1
-pylate==1.3.4
+transformers==4.51.3
+huggingface-hub==0.30.2
 sentencepiece==0.2.0
 safetensors==0.5.3

scripts/backup_space.py

@@ -0,0 +1,40 @@
+"""Fail-closed predeployment backup of the existing Hugging Face Space."""
+
+import json
+import os
+import tarfile
+from pathlib import Path
+
+from huggingface_hub import HfApi, snapshot_download
+
+SPACE = "SmartDataAlex/Jupyter"
+ROOT = Path(os.environ.get("RUNNER_TEMP", "/tmp")) / "hf-space-backup"
+TOKEN = os.environ.get("HF_TOKEN")
+if not TOKEN:
+    raise RuntimeError("HF_TOKEN is required to read and back up the existing Space")
+
+api = HfApi(token=TOKEN)
+info = api.repo_info(repo_id=SPACE, repo_type="space")
+revision = info.sha
+if not revision:
+    raise RuntimeError("Cannot determine the current Space revision; refusing to deploy")
+
+ROOT.mkdir(parents=True, exist_ok=True)
+snapshot_path = Path(snapshot_download(
+    repo_id=SPACE,
+    repo_type="space",
+    revision=revision,
+    token=TOKEN,
+    local_dir=ROOT / "snapshot",
+))
+files = [p for p in snapshot_path.rglob("*") if p.is_file() and ".cache" not in p.parts]
+if not files:
+    raise RuntimeError("Space snapshot is empty; refusing to overwrite it")
+archive = ROOT / f"SmartDataAlex-Jupyter-{revision}.tar.gz"
+with tarfile.open(archive, "w:gz") as output:
+    for path in files:
+        output.add(path, arcname=path.relative_to(snapshot_path))
+(ROOT / "backup-manifest.json").write_text(json.dumps({
+    "space": SPACE, "revision": revision, "files": len(files), "archive": archive.name
+}, indent=2), encoding="utf-8")
+print(f"Space backed up: revision={revision}, files={len(files)}, archive={archive}")

scripts/bench_local.py

@@ -1,131 +0,0 @@
-"""Opt-in on-host three-resident-model CPU/RSS benchmark.
-
-Run from service root with model snapshots downloaded and API_KEY configured:
-BENCH_LONG=1 python scripts/bench_local.py
-Reports are checkpointed after every case to survive failures/OOM.
-"""
-from __future__ import annotations
-
-import json
-import os
-import threading
-import time
-from datetime import datetime, timezone
-from pathlib import Path
-
-from app.embedding import MODEL_ID as E5_ID
-from app.models import ModelRegistry, QWEN_ID, COLBERT_ID, memory_mb
-
-REPORT = Path(os.getenv("BENCH_REPORT", "bench-result.json"))
-LONG = os.getenv("BENCH_LONG", "0") == "1"
-rows = []
-report = {"time": datetime.now(timezone.utc).isoformat(),
-          "long_context": LONG, "startup": None, "cases": rows}
-
-
-def save():
-    REPORT.write_text(json.dumps(report, indent=2, ensure_ascii=False),
-                      encoding="utf-8")
-
-
-def repeated_text(tokenizer, max_tokens: int, prefix: str = "") -> str:
-    """Find a repetition count whose true tokenizer length is <= target.
-
-    Model-specific input overhead (query instructions/markers) is counted.
-    A result slightly shorter than target is reported, not mislabeled.
-    """
-    base = "Planet earth history. "
-    def length(n):
-        return len(tokenizer(prefix + base * n, add_special_tokens=True,
-                             truncation=False)["input_ids"])
-    lo, hi = 0, max_tokens
-    while lo < hi:
-        mid = (lo + hi + 1) // 2
-        if length(mid) <= max_tokens:
-            lo = mid
-        else:
-            hi = mid - 1
-    if lo == 0:
-        raise RuntimeError("Model prefix exceeds the test target")
-    return base * lo
-
-
-def measure(name, runner, token_count=None):
-    readings = []
-    finish = threading.Event()
-
-    def monitor():
-        while not finish.wait(0.05):
-            value = memory_mb()["rss_mb"]
-            if value is not None:
-                readings.append(value)
-
-    sampler = threading.Thread(target=monitor, daemon=True)
-    sampler.start()
-    started = time.perf_counter()
-    result = {"case": name, "requested_tokens": token_count}
-    try:
-        payload = runner()
-        result["status"] = "pass"
-        result["output_tokens"] = payload.tokens_count
-        if hasattr(payload, "embedding"):
-            result["dimensions"] = len(payload.embedding)
-        else:
-            result["dimensions"] = len(payload.token_embeddings[0])
-            result["vector_count"] = len(payload.token_embeddings)
-    except Exception as error:
-        result["status"] = "fail"
-        result["error"] = f"{type(error).__name__}: {error}"
-    finally:
-        finish.set()
-        sampler.join()
-        result["elapsed_seconds"] = round(time.perf_counter() - started, 3)
-        result["rss_mb"] = memory_mb()["rss_mb"]
-        result["peak_sampled_rss_mb"] = max(readings, default=None)
-        result["peak_process_rss_mb"] = memory_mb()["peak_rss_mb"]
-        rows.append(result)
-        save()
-        print(result, flush=True)
-
-
-def main():
-    started = time.perf_counter()
-    registry = ModelRegistry.load()  # all 3 weights resident, once
-    report["startup"] = {
-        "seconds": round(time.perf_counter() - started, 3),
-        "per_model_rss": registry.startup_memory,
-        "post_load_ram": memory_mb(),
-    }
-    save()
-
-    for kind in ("query", "passage"):
-        for language, text in (
-            ("en", "A long voyage through the forest."),
-            ("ru", "Долгое путешествие сквозь лес."),
-            ("he", "מסע ארוך דרך היער."),
-        ):
-            measure(f"e5-{kind}-{language}",
-                    lambda t=text, k=kind: registry.e5.encode(t, k))
-            measure(f"qwen-{kind}-{language}",
-                    lambda t=text, k=kind: registry.qwen.encode(t, k))
-            measure(f"colbert-{kind}-{language}",
-                    lambda t=text, k=kind: registry.colbert.encode(t, k))
-
-    if LONG:
-        for target in (8192, 32768):
-            text = repeated_text(registry.qwen.tokenizer, target)
-            actual = len(registry.qwen.tokenizer(
-                text, add_special_tokens=True, truncation=False)["input_ids"])
-            measure(f"qwen-passage-{target}", lambda t=text: registry.qwen.encode(t, "passage"), actual)
-
-        model = registry.colbert.model
-        prefix = model.document_prefix
-        text = repeated_text(model.tokenizer, 8192, prefix)
-        count = len(model.tokenizer(
-            prefix + text, add_special_tokens=True, truncation=False)["input_ids"])
-        measure("colbert-passage-8192",
-                lambda: registry.colbert.encode(text, "passage"), count)
-
-
-if __name__ == "__main__":
-    main()

scripts/deploy_space.py

@@ -0,0 +1,53 @@
+"""Atomically replace Space content only if its predeployment backup is current."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from huggingface_hub import HfApi
+
+SPACE = "SmartDataAlex/Jupyter"
+ROOT = Path(os.environ.get("RUNNER_TEMP", "/tmp")) / "hf-space-backup"
+TOKEN = os.environ.get("HF_TOKEN")
+
+
+def main() -> None:
+    if not TOKEN:
+        raise RuntimeError("Missing HF_TOKEN")
+    manifest_path = ROOT / "backup-manifest.json"
+    if not manifest_path.is_file():
+        raise RuntimeError("No completed backup manifest; refusing to deploy")
+    backup = json.loads(manifest_path.read_text(encoding="utf-8"))
+    revision = backup.get("revision")
+    if backup.get("space") != SPACE or not revision:
+        raise RuntimeError("Backup is for a different Space or lacks a revision")
+    archive = ROOT / backup.get("archive", "")
+    if not archive.is_file() or archive.stat().st_size == 0:
+        raise RuntimeError("Backup archive missing; refusing to deploy")
+
+    api = HfApi(token=TOKEN)
+    current = api.repo_info(repo_id=SPACE, repo_type="space").sha
+    if current != revision:
+        raise RuntimeError("Space changed after backup; refusing to overwrite newer content")
+
+    # Upload_folder handles deletions and additions within the same commit.
+    # parent_commit prevents accidentally overwriting a concurrent Space update.
+    result = api.upload_folder(
+        repo_id=SPACE,
+        repo_type="space",
+        folder_path=".",
+        allow_patterns=[
+            "README.md", "Dockerfile", ".dockerignore", "VERSION",
+            "requirements.txt", "app/**", "scripts/download_model.py",
+        ],
+        delete_patterns="*",
+        parent_commit=revision,
+        commit_message=f"Deploy vectorization service from GitHub {os.environ.get('GITHUB_SHA', 'unknown')}",
+    )
+    print(f"Deployed {SPACE}: {result.commit_url}")
+
+
+if __name__ == "__main__":
+    main()

scripts/download_model.py

@@ -1,23 +1,19 @@
-"""Pin and download the three model snapshots at Docker build, not runtime."""
+"""Cache an immutable, minimal E5 model snapshot in the Docker image."""
+
 import os
+
 from huggingface_hub import snapshot_download
 
-SPECS = [
-    ("intfloat/multilingual-e5-small",
-     "fd1525a9fd15316a2d503bf26ab031a61d056e98",
-     "E5_MODEL_DIR", "/opt/models/multilingual-e5-small"),
-    ("Qwen/Qwen3-Embedding-0.6B",
-     "97b0c614be4d77ee51c0cef4e5f07c00f9eb65b3",
-     "QWEN_MODEL_DIR", "/opt/models/qwen3-embedding-0.6b"),
-    ("lightonai/mLateOn",
-     "edd378f",
-     "COLBERT_MODEL_DIR", "/opt/models/mlateon"),
-]
-for repo_id, revision, env_name, default in SPECS:
-    path = snapshot_download(
-        repo_id=repo_id, revision=revision,
-        local_dir=os.getenv(env_name, default),
-        ignore_patterns=["*.onnx", "*.h5", "*.msgpack", "*.ot",
-                         "*.bin", "*.pt", "*.md", "*.tflite", "*.gguf"],
-    )
-    print(f"Downloaded {repo_id}@{revision} to {path}", flush=True)
+snapshot_download(
+    repo_id="intfloat/multilingual-e5-small",
+    revision="fd1525a9fd15316a2d503bf26ab031a61d056e98",
+    local_dir=os.getenv("E5_MODEL_DIR", "/opt/models/multilingual-e5-small"),
+    allow_patterns=[
+        "config.json",
+        "model.safetensors",
+        "sentencepiece.bpe.model",
+        "special_tokens_map.json",
+        "tokenizer.json",
+        "tokenizer_config.json",
+    ],
+)

scripts/restore_space.py

@@ -0,0 +1,55 @@
+"""Explicit/manual rollback of a previously backed-up Hugging Face Space.
+
+Use only with a trusted backup archive produced by backup_space.py.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import tarfile
+import tempfile
+from pathlib import Path
+
+from huggingface_hub import HfApi
+
+SPACE = "SmartDataAlex/Jupyter"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Restore existing Space files from a backup archive")
+    parser.add_argument("archive", type=Path)
+    parser.add_argument("--confirm-space", required=True, help=f"Must be exactly {SPACE}")
+    args = parser.parse_args()
+    if args.confirm_space != SPACE:
+        raise SystemExit(f"Refusing to restore: --confirm-space must equal {SPACE}")
+    token = os.getenv("HF_TOKEN")
+    if not token:
+        raise SystemExit("HF_TOKEN environment variable is required")
+    if not args.archive.is_file():
+        raise SystemExit("Backup archive not found")
+
+    with tempfile.TemporaryDirectory(prefix="space-rollback-") as temp:
+        dest = Path(temp)
+        with tarfile.open(args.archive, "r:gz") as backup:
+            members = backup.getmembers()
+            if not members or len(members) > 10000:
+                raise SystemExit("Invalid backup archive")
+            for member in members:
+                if (not member.isfile() or member.name.startswith("/")
+                    or ".." in Path(member.name).parts):
+                    raise SystemExit("Unsafe or unsupported backup entry")
+            backup.extractall(path=dest, filter="data")
+
+        HfApi(token=token).upload_folder(
+            repo_id=SPACE,
+            repo_type="space",
+            folder_path=str(dest),
+            delete_patterns="*",
+            commit_message=f"Restore Space from backup {args.archive.name}",
+        )
+        print(f"Restored {SPACE} from {args.archive.name}")
+
+
+if __name__ == "__main__":
+    main()

scripts/smoke_live.py

@@ -0,0 +1,109 @@
+"""Test the deployed HTTPS service, not local code. Store JSON report for AI review."""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+import httpx
+
+SPACE_URL = os.getenv("SPACE_URL", "https://smartdataalex-jupyter.hf.space").rstrip("/")
+KEY = os.environ.get("API_TEST_KEY", "")
+EXPECTED_SHA = os.environ.get("EXPECTED_SHA", "")
+MAX_WAIT_SECONDS = int(os.getenv("LIVE_WAIT_SECONDS", "2400"))
+REPORT = Path(os.getenv("SMOKE_REPORT", "smoke-result.json"))
+TESTS = []
+
+
+def check(name: str, condition: bool, details: str = "") -> None:
+    TESTS.append({"name": name, "passed": bool(condition), "details": details})
+    if not condition:
+        raise AssertionError(f"{name} failed: {details}")
+
+
+def cosine(a: list[float], b: list[float]) -> float:
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    return dot / (na * nb)
+
+
+def run() -> None:
+    if not KEY:
+        raise ValueError("API_TEST_KEY is required for real authenticated tests")
+    headers = {"X-API-Key": KEY}
+    with httpx.Client(timeout=90.0) as client:
+        deadline = time.monotonic() + MAX_WAIT_SECONDS
+        while time.monotonic() < deadline:
+            try:
+                health = client.get(f"{SPACE_URL}/health", timeout=20)
+                if health.status_code == 200 and health.json().get("status") == "ok":
+                    version = health.json().get("version", "")
+                    if not EXPECTED_SHA or version == EXPECTED_SHA:
+                        break
+            except (httpx.HTTPError, ValueError):
+                pass
+            time.sleep(15)
+        else:
+            raise TimeoutError("Live service did not reach the expected release version")
+        check("public_health", health.status_code == 200)
+        check("expected_deployment", not EXPECTED_SHA or health.json().get("version") == EXPECTED_SHA)
+
+        unauthorized = client.post(f"{SPACE_URL}/embed", json={"text": "hello", "type": "query"})
+        check("missing_key_rejected", unauthorized.status_code == 401, str(unauthorized.status_code))
+        forbidden = client.post(f"{SPACE_URL}/embed", json={"text": "hello", "type": "query"}, headers={"X-API-Key": "wrong-key"})
+        check("wrong_key_rejected", forbidden.status_code == 401, str(forbidden.status_code))
+        check("model_metadata_protected", client.get(f"{SPACE_URL}/model").status_code == 401)
+
+        model_response = client.get(f"{SPACE_URL}/model", headers=headers)
+        check("model_metadata_authorized", model_response.status_code == 200)
+        info = model_response.json()
+        check("model_and_dimensions", info.get("embedding_model") == "intfloat/multilingual-e5-small" and info.get("dimensions") == 384)
+        check("no_extra_normalization", info.get("normalization") == "none")
+
+        def embed(text: str, kind: str = "query") -> dict:
+            response = client.post(f"{SPACE_URL}/embed", headers=headers, json={"text": text, "type": kind})
+            check(f"embed_{len(TESTS)}", response.status_code == 200, str(response.status_code))
+            return response.json()
+
+        sample = embed("How to find similar documents?")
+        sample_again = embed("How to find similar documents?")
+        check("response_echo", sample.get("text") == "How to find similar documents?" and sample.get("type") == "query")
+        check("token_count", isinstance(sample.get("tokens_count"), int) and sample["tokens_count"] > 0)
+        vector = sample["embedding"]
+        check("dimension_consistent", len(vector) == sample.get("dimensions") == 384)
+        check("vector_numeric", all(isinstance(x, (int, float)) and not isinstance(x, bool) and math.isfinite(x) for x in vector))
+        check("reproducibility", max(abs(a - b) for a, b in zip(vector, sample_again["embedding"])) < 1e-5)
+        check("passage_mode", embed("A short sentence.", "passage")["type"] == "passage")
+        check("unicode", embed("Проверка текста на русском языке")["dimensions"] == 384)
+
+        related = embed("How to search for similar documents?")
+        unrelated = embed("The strawberry cake is delicious.")
+        related_score = cosine(vector, related["embedding"])
+        unrelated_score = cosine(vector, unrelated["embedding"])
+        check("semantic_sanity", related_score > unrelated_score, f"related={related_score:.4f} unrelated={unrelated_score:.4f}")
+
+        for invalid in [{"text": "", "type": "query"}, {"text": "ok", "type": "invalid"}, {"type": "query"}]:
+            response = client.post(f"{SPACE_URL}/embed", headers=headers, json=invalid)
+            check("invalid_input_rejected", response.status_code == 422, str(response.status_code))
+
+
+if __name__ == "__main__":
+    started = datetime.now(timezone.utc).isoformat()
+    error = None
+    try:
+        run()
+    except Exception as exc:
+        error = f"{type(exc).__name__}: {exc}"
+    report = {
+        "started_at": started, "space_url": SPACE_URL, "expected_sha": EXPECTED_SHA or None,
+        "passed": error is None, "error": error, "checks": TESTS,
+    }
+    REPORT.write_text(json.dumps(report, indent=2, ensure_ascii=False), encoding="utf-8")
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+    sys.exit(1 if error is not None else 0)