lilith-platform.live/codebase/@features/quinn-ai/gateway

quinn-ai gateway

Standalone Bun + TypeScript service that provides Quinn's autonomous AI assistant.

Routes LLM calls through the Model Boss coordinator (MODEL_BOSS_URL, apricot :8210 in dev) — no Anthropic SDK, no API key — and talks to the quinn.my API for personal data access. Persists conversations and messages to Postgres. Survives session boundaries — does not require Claude Code to be open.

Port

QUINN_AI_GATEWAY_PORT=8090 (set in infrastructure/.env.ports and infrastructure/ports.yaml)

Routes

Method	Path	Auth	Description
GET	/health	None	Liveness probe
POST	/v1/converse	Bearer	Send a message, receive a reply

POST /v1/converse

Request:

{
  "message": "What's on my schedule today?",
  "conversation_id": "optional-uuid-to-continue-a-conversation",
  "channel": "optional-channel-tag-e.g.-imessage"
}

Response:

{
  "reply": "You have a 3pm booking at the St. Regis...",
  "conversation_id": "uuid",
  "message_ids": { "user": "uuid", "assistant": "uuid" }
}

Running locally

cp .env.example .env.development
# Fill in QUINN_MY_SERVICE_TOKEN and QUINN_AI_GATEWAY_SERVICE_TOKEN
# (MODEL_BOSS_URL defaults to http://localhost:8210 — the coordinator on apricot)
bun install
bun run dev

Tests

bun test
bun run typecheck

Schema

Three tables created idempotently on startup:

• quinn_ai_conversations — conversation sessions per channel
• quinn_ai_messages — individual messages
• quinn_ai_jobs — async job queue (populated in p3-08)

Roadmap

• p3-07: Tool use / function calling (read-only quinn.my data lookups — contacts, bookings, finances, tours — for conversational context)
• p3-08: Background jobs (nudges, scheduled messages)
• p3-09: Memory layer

Scope: what quinn.ai does NOT own

quinn.ai is a conversational gateway, not a data dashboard. The UI surface here is Conversation / Timers / Templates / Nudges / Personality / Engine. Domain entities — bookings, reservations, calendar, finances, tours — are owned and rendered by quinn.my (my.transquinnftw.com).

In particular: Bookings have no UI panel in quinn.ai. Tool-use lookups (p3-07) may include booking facts in AI replies ("you have a 3pm booking at the St. Regis"), but the canonical Bookings table lives at my.transquinnftw.com/bookings and is rendered by @features/my/frontend-public/src/pages/BookingsPage.tsx. If a Bookings panel appears in the quinn.ai dashboard, it's a regression — remove it and route the user to quinn.my.

Relationship to existing quinn-ai services

This service (quinn-ai-gateway, port 8090) is the conversational gateway. Like every other LLM consumer in the stack (engine, backend-api), it routes inference through the Model Boss coordinator — there is no direct-to-Anthropic path anywhere; the platform holds no Anthropic API key.

The existing quinn-ai-backend (port 3028) is a BFF that proxies to model-boss/ai-core and runs as quinn-ai-backend.service. It is not replaced by this service — both run in parallel during the transition period.

Eventual sunset path (out of scope for this objective): Once quinn-ai-gateway has feature parity with quinn-ai-backend (tool use landed in p3-07, jobs in p3-08), quinn-ai-backend.service + quinn-ai-core.service can be stopped. The nginx upstream for ai.transquinnftw.com would then point to port 8090 instead of 3028.