Configuration & Providers

The AI stack relies on a consistent split between public, server, and runtime configuration files:

dapp/app/config/ai.public.ts exposes safe toggles (chat path and whether the UI must attach a JWT).
dapp/app/config/public.env.ts contains broader NEXT_PUBLIC values, including the state-worker flag and active chain.
dapp/app/config/ai.server.ts handles provider secrets, model lists, image pipeline settings, crypto quota limits, and backdoor reset secrets.
dapp/app/config/server.env.ts validates sensitive infrastructure values (Durable Object URL/API key, JWT signing keys).

Provider Selection

Chat Models — AI_PROVIDER selects openai or lmstudio. Each provider defines up to three models (AI_OPENAI_MODEL_* or AI_LOCAL_MODEL_*) that can be accessed by modelIndex.
Vision + Images — AI_OPENAI_VISION_MODEL / AI_LOCAL_VISION_MODEL supply the multimodal companion, while AI_IMAGE_PROVIDER switches between OpenAI, Replicate, or HuggingFace for the generate_image_with_alt workflow.
Temperature & Limits — AI_TEMPERATURE, AI_CHAT_MAX_OUTPUT_TOKENS, and AI_CHAT_MAX_DURATION flow directly into providerRegistry and handleChatRequest.

⚠️

JWT gating is enforced twice. Setting NEXT_PUBLIC_AI_CHAT_REQUIRES_JWT makes the client attach a bearer token, and the server-side aiServerConfig.requiresJwt ensures both /api/chat and /api/mcp reject unauthenticated calls.

Text-to-Speech (TTS)

RapBotRito’s voice clone uses a provider adapter so we can swap vendors later. ElevenLabs powers the current production voice clone.

Key	Location	Purpose
`NEXT_PUBLIC_TTS_API_PATH`	`tts.public.ts`	Client POST path for TTS requests (default: `/api/tts`).
`TTS_PROVIDER`	`tts.server.ts`	Set to `elevenlabs` or `disabled`. When disabled, the API returns 503.
`ELEVENLABS_API_KEY`	`tts.server.ts`	Required when `TTS_PROVIDER=elevenlabs`.
`ELEVENLABS_VOICE_ID`	`tts.server.ts`	Required ElevenLabs voice id for the Rito Rhymes clone.
`ELEVENLABS_MODEL_ID`	`tts.server.ts`	Optional ElevenLabs model id override.
`ELEVENLABS_BASE_URL`	`tts.server.ts`	Override base URL (normalized to `/v1`).
`ELEVENLABS_OUTPUT_FORMAT`	`tts.server.ts`	Audio output format (default: `mp3_44100_128`).
`ELEVENLABS_VOICE_STABILITY`	`tts.server.ts`	Optional voice setting (0.0 - 1.0).
`ELEVENLABS_VOICE_SIMILARITY`	`tts.server.ts`	Optional voice setting (0.0 - 1.0).

The /api/tts route uses the same JWT requirement as chat (NEXT_PUBLIC_AI_CHAT_REQUIRES_JWT and aiServerConfig.requiresJwt), so the client will attach a bearer token whenever chat auth is enabled.

Feature Flags & Secrets

Key	Location	Purpose
`NEXT_PUBLIC_ENABLE_STATE_WORKER`	`public.env.ts`	Turns on Durable Object backed quotas; requires `STATE_WORKER_URL`/`STATE_WORKER_API_KEY` in `server.env.ts`.
`AI_CRYPTO_QUOTA_*`	`ai.server.ts`	Configures global/per-user ETH spend limits for the send-crypto tools (`dapp/app/lib/quotas/crypto-quota.ts`).
`AI_QUOTA_RESET_SECRET`	`ai.server.ts`	Enables `/api/quota-reset` so admins can wipe token or crypto windows.
`AI_PRIVATE_KEY`	`ai.server.ts`	Required for `send_crypto_to_signed_in_user`, the agent sender, and Key NFT management tools.
`OPENAI_API_KEY`/`AI_BASE_URL`	`ai.server.ts`	Supply credentials for OpenAI or point to a local LM Studio endpoint.

Pinecone & Semantics

dapp/app/config/pinecone.config.ts parses PINECONE_INDEX_* environment variables, exposes helper methods for namespace validation, and is consumed by both the MCP tool (pinecone-search.ts) and the agent rap workflow. The seeding scripts under dapp/pinecone rely on PINECONE_API_KEY plus index/namespace lists.

See the Pinecone database page for index layout, seeding workflows, and dataset format.

Operational Tips

Keep public and server env validation errors actionable: both files log issues once per boot via their run-once guards.
Because the chat route reads JSON before opening the SSE stream, incorrect payloads fail fast without tying up a connection.
When switching to LM Studio, remember to set AI_BASE_URL to the server’s /v1 endpoint—providerRegistry normalizes trailing slashes but expects the OpenAI-compatible path.