Quickstart

Install

git clone https://github.com/RelativeDB/relational-transformers-gateway
cd relational-transformers-gateway
python -m pip install -e '.[dev]'

The runtime dependency is boto3 alone; the gateway carries no model code.

Run locally

The gateway needs four environment variables naming its AWS backing services (see Configuration):

export AWS_PROFILE=personal AWS_DEFAULT_REGION=us-west-2
export CLOUDMAP_NAMESPACE=workers.relativedb.local
export CLOUDMAP_SERVICE=inference
export KEYS_TABLE=relativedb-gateway-api-keys
export USAGE_TABLE=relativedb-gateway-usage
rtg-serve

GET /gateway/health answers without authentication:

curl localhost:8080/gateway/health
# {"status":"ok"}

Mint a key and score

rtg-manage create-key --table relativedb-gateway-api-keys --customer acme
# rtg_...   (plaintext printed once; only the SHA-256 digest is stored)

curl -H "Authorization: Bearer rtg_..." \
  -d '{"batch": {"b": 1, "s": 128}}' \
  localhost:8080/v1/forward

Clients authenticate with Authorization: Bearer rtg_... or X-Api-Key: rtg_.... Every response carries an x-request-id header; passing your own x-request-id makes retries idempotent — a replayed id is answered with 409 rather than billed twice.

Endpoints

Path	Upstream	Notes
GET /gateway/health	—	unauthenticated liveness check
POST /v1/forward	worker	token batch scoring
POST /v1/flat_features	worker	flat feature extraction
GET /health	worker	authenticated worker probe
POST /v1/chat/completions	LLM provider	SSE streaming supported
POST /v1/responses	LLM provider
GET /v1/models	LLM provider	filtered to the model allowlist

Streaming chat requests ("stream": true) are proxied chunk by chunk; the gateway forces stream_options.include_usage so the final SSE event carries token counts for metering, and it keeps consuming the upstream after a client disconnect so that usage is still recorded.