README.md

---
title: ACCESS EMBEDDING
emoji: 🐨
colorFrom: green
colorTo: red
sdk: docker
pinned: false
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
---
title: ACCESS SBERT Embedding Service
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---

# ACCESS SBERT Embedding Service

FastAPI service for generating SBERT embeddings for ACCESS semantic context search.

The service only converts text into normalized sentence embeddings. It does not store ACCESS data, query PostgreSQL, generate HEAT suggestions, or perform business workflow logic.

## Model

Default model:

```txt
sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
```

Expected embedding dimension:

```txt
384
```

## Endpoints

- `GET /health`
- `POST /embed`
- `POST /embed/batch`

## Environment Variables

```env
MODEL_NAME=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
EMBEDDING_API_KEY=change-this-secret
MAX_TEXT_LENGTH=3000
MAX_BATCH_SIZE=64
```

`EMBEDDING_API_KEY` is optional for local development. Configure it for deployed Spaces.

## Local Run

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 7860 --reload
```

## Health Check

```bash
curl http://localhost:7860/health
```

Expected response:

```json
{
  "status": "ok",
  "model": "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
  "dimension": 384
}
```

## Single Embedding

```bash
curl -X POST http://localhost:7860/embed \
  -H "Content-Type: application/json" \
  -H "X-API-Key: change-this-secret" \
  -d "{\"text\":\"Saldo saya terpotong tapi tiket tidak muncul.\"}"
```

## Batch Embedding

```bash
curl -X POST http://localhost:7860/embed/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: change-this-secret" \
  -d "{\"texts\":[\"Saldo terpotong tapi tiket belum muncul.\",\"Refund pembatalan tiket belum diterima.\"]}"
```

## Tests

```bash
pytest
```

The first embedding test run downloads and loads the SBERT model, so it can be slow.

## Docker

```bash
docker build -t access-sbert-embedding-service .
docker run --rm -p 7860:7860 -e EMBEDDING_API_KEY=change-this-secret access-sbert-embedding-service
```

## ACCESS Backend Integration

ACCESS Backend should call this service over HTTP, then store/search embeddings in PostgreSQL + pgvector.

Backend env shape:

```env
EMBEDDING_ENABLED=true
EMBEDDING_SERVICE_URL=https://<space-url>/embed
EMBEDDING_BATCH_SERVICE_URL=https://<space-url>/embed/batch
EMBEDDING_API_KEY=<same-secret>
EMBEDDING_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
EMBEDDING_DIMENSION=384
EMBEDDING_TIMEOUT_MS=10000
```

Failure rules:

- If embedding fails during preview, ACCESS Backend should keep HEAT suggestions working.
- If embedding fails during reference/case indexing, backend should keep source data saved and backfill embeddings later.