# Vector Service

A minimal Go container that provides text embedding vectors using the
[bge-small-en-v1.5](https://huggingface.co/BAAI/bge-small-en-v1.5) model
(384 dimensions). The service accepts POST requests and returns an embedding
vector, ready to be consumed by pgvector.

## Model

bge-small-en-v1.5 uses **asymmetric** embeddings: queries and passages are
embedded differently, which is what lets a short search query align with a
package description. To support this, the request carries a `type`:

- **default (omitted)** — treated as a **query**: the text is prefixed with
  the bge retrieval instruction
  (`Represent this sentence for searching relevant passages: `). This keeps
  existing callers that send a bare `{"text": ...}` working unchanged.
- `"passage"` — embedded as-is (used for documents/descriptions).

## API

`POST /vector`

```bash
curl -X POST http://localhost:8080/vector \
  -H "Content-Type: application/json" \
  -d '{"text": "sqlite editor", "type": "query"}'
```

```json
{ "vector": [0.023, -0.118, ...] }
```

Endpoints:

- `POST /vector` — embed text.
- `GET /ok` — health check.
- `GET /version` — build revision.

Optional Bearer auth via the `API_SECRET` environment variable.

## Build

```bash
docker build -t vector-service .
```

The build downloads the pre-converted ONNX model
(`onnx-community/bge-small-en-v1.5-ONNX`) and the ONNX Runtime shared library,
then compiles the Go binary.

## Run

```bash
docker run --rm -p 8080:8080 -e API_SECRET=your-secret-key vector-service
```

## Technical details

- **Model**: bge-small-en-v1.5 (ONNX), 384 dimensions
- **Pooling/normalization**: the export's `sentence_embedding` output is
  mean-pooled and L2-normalized
- **Runtime**: Go + ONNX Runtime (no Python)
- **Files**: `main.go` (server), `Dockerfile`