# PolyLLM — repository guide

PolyLLM (www.polyllm.io) is a BYOK multi-provider AI workspace: OpenAI, Anthropic, Gemini, xAI behind one normalized adapter layer, real streaming, capability-driven configuration, Arena comparisons, usage/cost tracking. The original product brief lives in docs/SPEC-original.md; the UI conventions in docs/UI-BRIEF.md.

# Non-negotiables

• Research before provider changes. Read docs/provider-research/<provider>.md, re-fetch the official docs, probe the real API (pnpm providers:matrix), then update src/lib/ai/providers/<provider>/catalog*.ts. Never assume model ids, parameters, event names or limits from memory. Bump Last documentation audit.
• Provider quirks stay inside src/lib/ai/providers/*. UI and services only see PolyModel, UnifiedChatRequest, UnifiedStreamEvent, PolyProviderError.
• Capabilities drive the UI. Never branch on a model id in components; use model.capabilities / model.parameters. Never send a parameter the model does not accept (filterSettings() + adapter translation).
• Keys. User keys are encrypted (src/lib/crypto/keys.ts) and decrypted only in getDecryptedKey() right before a request. Never log, return or serialize them; PublicConnection exposes keyHint only. Owner keys in .env are for the registry sync, admin diagnostics and tests — never for user requests.
• No fake integrations. A capability is ✅ only after a real request passed (docs/provider-test-matrix.md).
• Secrets only in .env (gitignored) and the mld manifest on M1M32; .env.example documents the variables.

# Commands

pnpm dev · pnpm typecheck · pnpm lint · pnpm test (vitest) · pnpm test:e2e (Playwright; dev server with EMAIL_DRY_RUN=1 EMAIL_DRY_RUN_PRINT=1) · pnpm db:generate / pnpm db:migrate · pnpm models:sync [provider] · pnpm providers:matrix [provider].

# Deploy

mld from the laptop (see docs/deployment-cluster.md): mld stage . polyllm && mld deploy polyllm --node M3U96a. Manifest with secrets: M1M32:~/dispatch/apps/polyllm.json (local gitignored copy deploy/polyllm.mld.json).

# Gotchas

• React Compiler lint: no Date.now()/impure calls in render, no setState synchronously in effects without an explicit eslint-disable, memoize derived lists.
• import "server-only" modules are used by CLI scripts through scripts/hooks.mjs (tsx --import) and by vitest via an alias.
• Anthropic: adaptive thinking may legitimately produce zero thinking tokens on easy prompts; Haiku 4.5 needs budget_tokens.
• Gemini: free-tier keys have tiny per-model daily quotas (429 limit: 20) and some models are paid-tier only (429 limit: 0); thought signatures must be replayed on function-call parts.
• xAI: bad keys return HTTP 400 (Incorrect API key), frequency/presence_penalty always 400, web search only via /v1/responses.
• OpenAI: Responses API has no seed/stop; sampling params only when reasoning.effort === "none" on reasoning models.