spb/polyllm

1# PolyLLM23**One interface. Every model. Bring your own keys.** — https://www.polyllm.io45PolyLLM is a mobile-first, multi-model AI workspace — an "AI operating system" rather than a chat box: connect your own6OpenAI, Anthropic, Google Gemini, xAI, Mistral, DeepSeek, Kimi (Moonshot), OpenRouter and Cerebras API keys (plus any7OpenAI-compatible endpoint such as Ollama, LM Studio, vLLM, llama.cpp or MLX), discover the models your keys can reach,8configure each one with only the parameters it supports, chat with real token-by-token streaming, let the transparent9**Smart Router (AUTO)** recommend a model, compare 2–4 models inline or in the **Arena** (blind mode, votes per criterion,10personal scoreboard), organise work in **Projects** with a prompt library (`{{variables}}`) and a reusable file library,11search everything (`model:claude project:research after:2026-08-01`), share/export conversations, and track tokens,12latency, cost, projections and savings opportunities in **Usage**. Installable as a PWA; designed first for 375–430 px13phones (bottom navigation, bottom sheets, swipe gestures, keyboard-safe composer), then tablet and desktop. Keys are encrypted at rest (AES-256-GCM, HKDF-derived data key, AAD-bound to the user) and only decrypted on the14server immediately before a provider request.1516## Stack17Next.js 16 (App Router, Route Handlers with SSE streaming) · React 19 · TypeScript · Tailwind v4 · PostgreSQL 17 + Drizzle ·18Better Auth 1.7 (Argon2id, email verification, sessions, reset, change email, delete account) · Resend · Zod ·19official provider SDKs (`openai`, `@anthropic-ai/sdk`, `@google/genai`); xAI, Mistral, DeepSeek, Kimi, OpenRouter and Cerebras through the OpenAI SDK pointed at their endpoints with per-provider body translation (`providers/shared/openai-compat`).2021## Layout22```23src/app                 routes: (marketing) landing/legal · (auth) login/signup/verify/reset · app/* workspace · admin/* · share/[id] · api/*24src/lib/ai/core         provider-neutral contract: PolyModel, UnifiedChatRequest, UnifiedStreamEvent, errors, retry, pricing, normalization25src/lib/ai/providers    adapters (openai, anthropic, gemini, xai, mistral, deepseek, kimi, openrouter, cerebras) + catalogs — provider quirks live ONLY here26src/lib/ai/registry     model registry: live listing → catalog merge → Postgres; scheduled + manual sync27src/lib/chat            turn orchestration (edit/regenerate/continue/branch/adopt, ephemeral temporary chats), built-in tools loop, SSE28src/lib/arena           sessions, streaming per model, votes/criteria, winner & scoreboard math, exports, public shares29src/lib/projects|library|prompts   workspaces, reusable files (token estimates), prompt templates with variables30src/lib/search          full-text search (Postgres FTS + filter query language) · src/lib/export conversation exports (md/txt/json/html→print)31src/lib/endpoints       custom OpenAI-compatible endpoints (encrypted keys/headers, discovery, SSRF guard) · src/lib/usage analytics & savings32src/lib/models          model intelligence: badges, lifecycle, intent search, compare slugs, parameter groups · src/lib/client router & token estimators33src/lib/providers       encrypted key storage & validation34src/db                  schema.ts (core) + schema-workspace.ts (1.0 tables) · drizzle/ migrations35src/components          ui kit (sheet, segmented, …) · app shell (bottom nav, drawer) · chat · models · arena · projects · library · prompts · search · share · usage · providers · settings · marketing36docs/                   UPGRADE-PLAN (1.0 contract) + upgrade-notes/ (per area) · provider-research · provider-test-matrix · deployment-cluster · UI brief37scripts/                sync-models, provider-matrix (real-API tests), brand-assets (favicons / PWA icons / OG image)38e2e/, tests/, qa/       Playwright workflows, vitest unit + integration tests, responsive QA sweeps (`qa/responsive-qa.mjs`, `qa/flows.mjs`)39```4041## Development42```bash43cp .env.example .env            # fill AUTH_SECRET, API_KEY_ENCRYPTION_SECRET, RESEND_API_KEY, owner provider keys (optional)44createdb polyllm && pnpm install && pnpm db:migrate45pnpm models:sync                # populate the registry with the owner keys46pnpm dev                        # http://localhost:300047pnpm typecheck && pnpm lint && pnpm test48pnpm providers:matrix           # real-API capability matrix → docs/provider-test-matrix.md49EMAIL_DRY_RUN=1 EMAIL_DRY_RUN_PRINT=1 pnpm dev && pnpm test:e2e   # full browser workflow (links read from the dev log)50```5152## Responsive QA53```bash54pnpm dev                                                    # single dev server on :300055QA_EMAIL=… QA_PASSWORD=… node qa/responsive-qa.mjs          # 17 screens × 375/390/393/430/tablet/desktop → qa/out/ + report.json56node qa/flows.mjs --width=390 [--send]                      # drawer, model picker, composer, chat, Arena swipe, search, palette, sheets57```5859## Deployment60Runs on the private MacLustr cluster behind the MacLustr Tunnel (WireGuard + Caddy on BHS64) — see `docs/deployment-cluster.md`.61Built and hosted by Simon-Pierre Boucher on [MacLustr](https://www.maclustr.io) · contact@spboucher.ai6263## Security notes64No provider key ever reaches the browser, logs or analytics (structured logger redacts key-shaped strings and sensitive65field names). CSP, HSTS, HttpOnly/SameSite cookies, rate limits on auth and provider endpoints, per-user audit log.66