LLM/pocketpaw
1
0
Fork 0
mirror of https://github.com/pocketpaw/pocketpaw.git synced 2026-05-19 08:26:34 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
dev
pocketpaw/docs/api/configuration-reference.mdx
Rohit Kushwaha 869407bf69 refactor: provider adapter pattern + LiteLLM support (#595) 
* feat: add LiteLLM provider support and unified env resolution

Add LiteLLM as a provider option for all backends (Claude SDK, OpenAI
Agents, Google ADK, Copilot SDK), enabling access to 100+ LLM providers
including HuggingFace, Ollama, vLLM, Together AI, Groq, Mistral, and
more through a single proxy or direct SDK integration.

Key changes:
- New config fields: litellm_api_base, litellm_api_key, litellm_model
- OpenAI Agents: native LitellmModel extension with proxy fallback
- Google ADK: LiteLlm model wrapper for cross-provider support
- Claude SDK: routes through LiteLLM proxy via ANTHROPIC_BASE_URL
- Copilot SDK: LiteLLM via OpenAI-compatible BYOK config
- resolve_backend_env() pushes unified POCKETPAW_* keys to env vars
  each SDK expects, fixing the issue where switching backends required
  manually reconfiguring environment variables

* fix: complete LiteLLM integration across dashboard, health checks, and WS

- Fix health check false warning: add 'litellm' to provider skip list
  in check_api_key_primary() for Claude SDK, OpenAI Agents, and
  Google ADK backends
- Add google_adk_provider to WS settings handler and broadcast
- Add litellm_api_base, litellm_api_key, litellm_model to WS handler
- Add 'LiteLLM (100+ Providers)' option to provider dropdowns in
  settings UI for Claude SDK and OpenAI Agents backends
- Add LiteLLM config fields (proxy URL, API key, model) shown when
  litellm provider is selected in the settings modal

* fix: add LiteLLM provider to Copilot SDK and Google ADK settings UI

- Add LiteLLM option to Copilot SDK provider dropdown
- Add provider dropdown to Google ADK settings (was missing entirely)
- Add LiteLLM config fields (proxy URL, API key, model) for Google ADK
  when litellm provider is selected

* fix: sync env vars at runtime when API keys change via dashboard

resolve_backend_env() now accepts force=True to overwrite existing env
vars. Called after every settings/API-key save so backends immediately
see updated keys without a restart. Codex CLI subprocess gets an
explicit env snapshot via env=os.environ.copy().

* refactor: provider adapter pattern for LLM providers

Extract provider-specific logic (config resolution, client creation,
env var setup, error formatting) into adapter classes under
llm/providers/. Six adapters: Anthropic, Ollama, OpenAICompatible,
OpenRouter, Gemini, LiteLLM.

LLMClient delegates to adapters internally while keeping its public
API stable. Backends (OpenAI Agents, Google ADK, Copilot SDK) now use
adapters directly, replacing 70+ line if/elif chains with ~5 line
adapter calls. Adding a new provider means adding one adapter file
and registering it, no backend changes needed.

30 new tests for adapters, registry, model resolution, and LLMClient
delegation.

* fix: _stderr_lines UnboundLocalError and test_fast_path failures

Move _stderr_lines initialization before the try block so the except
handler can always access it. Add missing _HookMatcher and is_litellm
to test mocks.

* style: format test files and fix UP038 lint

* docs: add Discord deployment config with multi-provider support

Add Docker Compose, Dockerfile, env example, and identity files for
headless Discord bot deployment. Supports direct Anthropic, LiteLLM
proxy, OpenAI-compatible, and OpenAI Agents backends out of the box.

* chore: remove Discord deploy files (moved to separate PR #597)

Deploy config now lives under deploy/discord/ in the
deploy/discord-docker branch to keep this PR focused on
the provider adapter pattern and LiteLLM integration.

* fix: LiteLLM max_tokens setting, config persistence, and health recheck

- Add litellm_max_tokens config option so users can cap output tokens
  for models like DeepSeek (8192 limit)
- Fix LiteLLM settings not persisting on reload: litellmApiBase,
  litellmModel, litellmMaxTokens were missing from SETTINGS_MAP in
  app.js, so the frontend never loaded them back from the server
- Also add 13 other missing backend settings to SETTINGS_MAP
  (openaiAgentsModel, googleAdkProvider, codexCliModel, etc.)
- Re-run health checks after settings save so switching to LiteLLM
  immediately clears the "no Anthropic API key" degraded warning
- Claude SDK fast-path respects provider max_tokens instead of
  hardcoding 1024

* fix: LiteLLM proxy routing, adapter bugs, and remove plan docs

- Fix LiteLLM + OpenAI Agents: use OpenAI-compat proxy path when
  base_url is set instead of native LitellmModel which tried to route
  directly (causing Vertex AI credential errors)
- Fix operator precedence in _to_provider_config() base_url resolution
- Fix dashboard unable to clear LiteLLM API key (falsy vs None check)
- Fix fragile hasattr duck-typing in openai_agents, add explicit
  provider == "litellm" guard
- Replace unnecessary getattr() with direct attribute access in
  google_adk now that the field exists in Settings
- Pass api_key and base_url to ADK LiteLlm wrapper explicitly
- Remove plan design doc

* docs: add OpenRouter and LiteLLM provider documentation

- Add dedicated OpenRouter and LiteLLM sections to LLM providers guide
  with configuration examples for proxy vs direct SDK mode
- Update backend compatibility matrix to include both new providers
- Update per-backend provider tables (Claude SDK, OpenAI Agents,
  Google ADK, Copilot SDK) with LiteLLM and OpenRouter support
- Add OpenRouter and LiteLLM config fields to configuration reference
- Update getting-started configuration with OpenRouter and LiteLLM
  environment variable examples
- Replace OpenRouter-only section in backends index with combined
  OpenRouter + LiteLLM section
2026-03-14 03:46:02 +05:30

190 lines
11 KiB
Plaintext
Raw Permalink Blame History

---
title: Configuration Reference
description: "Complete reference of all PocketPaw configuration options: environment variables with POCKETPAW_ prefix, JSON config fields, channel tokens, API keys, tool profiles, and memory backend settings."
section: API Reference
ogType: article
keywords: ["configuration", "environment variables", "settings reference", "config options"]
tags: ["api", "configuration"]
---
# Configuration Reference
Complete reference of all configuration settings. All environment variables use the `POCKETPAW_` prefix.
## Core Settings
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `anthropic_api_key` | `POCKETPAW_ANTHROPIC_API_KEY` | string | — | Anthropic API key |
| `openai_api_key` | `POCKETPAW_OPENAI_API_KEY` | string | — | OpenAI API key |
| `agent_backend` | `POCKETPAW_AGENT_BACKEND` | enum | `claude_agent_sdk` | Agent backend (`claude_agent_sdk`, `openai_agents`, `google_adk`, `codex_cli`, `opencode`, `copilot_sdk`) |
| `claude_sdk_model` | `POCKETPAW_CLAUDE_SDK_MODEL` | string | `""` (auto) | Model override for Claude SDK (empty = let Claude Code decide) |
| `claude_sdk_max_turns` | `POCKETPAW_CLAUDE_SDK_MAX_TURNS` | integer | `25` | Max tool-use turns per query in Claude SDK |
| `smart_routing_enabled` | `POCKETPAW_SMART_ROUTING_ENABLED` | boolean | `false` | Smart model routing (disabled by default — conflicts with Claude Code) |
| `model_tier_simple` | `POCKETPAW_MODEL_TIER_SIMPLE` | string | `claude-haiku-4-5-20251001` | Model for simple tasks (when smart routing is on) |
| `model_tier_moderate` | `POCKETPAW_MODEL_TIER_MODERATE` | string | `claude-sonnet-4-5-20250929` | Model for moderate tasks (when smart routing is on) |
| `model_tier_complex` | `POCKETPAW_MODEL_TIER_COMPLEX` | string | `claude-opus-4-6` | Model for complex tasks (when smart routing is on) |
| `dashboard_host` | `POCKETPAW_DASHBOARD_HOST` | string | `0.0.0.0` | Dashboard bind address |
| `dashboard_port` | `POCKETPAW_DASHBOARD_PORT` | integer | `8000` | Dashboard port |
## LLM Provider
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `llm_provider` | `POCKETPAW_LLM_PROVIDER` | enum | `auto` | LLM provider (`auto`, `anthropic`, `openai`, `ollama`, `openai_compatible`, `openrouter`, `gemini`, `litellm`) |
| `ollama_host` | `POCKETPAW_OLLAMA_HOST` | string | `http://localhost:11434` | Ollama server URL |
| `ollama_model` | `POCKETPAW_OLLAMA_MODEL` | string | `llama3.2` | Ollama model name |
When `llm_provider` is `auto`, PocketPaw uses Anthropic if an API key is set, otherwise falls back to Ollama.
## OpenRouter
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `openrouter_api_key` | `POCKETPAW_OPENROUTER_API_KEY` | string | -- | OpenRouter API key (sk-or-v1-...) |
| `openrouter_model` | `POCKETPAW_OPENROUTER_MODEL` | string | `""` | Model slug (e.g., `anthropic/claude-sonnet-4-6`) |
## LiteLLM
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `litellm_api_base` | `POCKETPAW_LITELLM_API_BASE` | string | `http://localhost:4000` | LiteLLM proxy URL (leave empty for direct SDK mode) |
| `litellm_api_key` | `POCKETPAW_LITELLM_API_KEY` | string | -- | Proxy master key or target provider API key |
| `litellm_model` | `POCKETPAW_LITELLM_MODEL` | string | `""` | Model name (use LiteLLM-prefixed names in direct mode) |
| `litellm_max_tokens` | `POCKETPAW_LITELLM_MAX_TOKENS` | integer | `0` | Max output tokens (0 = provider default) |
## Tool Policy
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `tool_profile` | `POCKETPAW_TOOL_PROFILE` | enum | `full` | Tool profile (`minimal`, `coding`, `full`) |
| `tools_allow` | `POCKETPAW_TOOLS_ALLOW` | string[] | `[]` | Allowed tools (comma-separated list) |
| `tools_deny` | `POCKETPAW_TOOLS_DENY` | string[] | `[]` | Denied tools (comma-separated list) |
## Telegram
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `telegram_token` | `POCKETPAW_TELEGRAM_TOKEN` | string | — | Bot token |
| `allowed_telegram_ids` | `POCKETPAW_ALLOWED_TELEGRAM_IDS` | string[] | `[]` | Allowed user IDs (comma-separated) |
## Discord
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `discord_bot_token` | `POCKETPAW_DISCORD_BOT_TOKEN` | string | — | Bot token |
| `discord_allowed_guild_ids` | `POCKETPAW_DISCORD_ALLOWED_GUILD_IDS` | integer[] | `[]` | Allowed guilds (comma-separated IDs) |
| `discord_allowed_user_ids` | `POCKETPAW_DISCORD_ALLOWED_USER_IDS` | integer[] | `[]` | Allowed users (comma-separated IDs) |
## Slack
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `slack_bot_token` | `POCKETPAW_SLACK_BOT_TOKEN` | string | — | Bot token (xoxb-) |
| `slack_app_token` | `POCKETPAW_SLACK_APP_TOKEN` | string | — | App token (xapp-) |
| `slack_allowed_channel_ids` | `POCKETPAW_SLACK_ALLOWED_CHANNEL_IDS` | string[] | `[]` | Allowed channels (comma-separated IDs) |
## WhatsApp
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `whatsapp_mode` | `POCKETPAW_WHATSAPP_MODE` | enum | `""` (unset) | Mode (`personal`, `business`) |
| `whatsapp_access_token` | `POCKETPAW_WHATSAPP_ACCESS_TOKEN` | string | — | Business API token |
| `whatsapp_phone_number_id` | `POCKETPAW_WHATSAPP_PHONE_NUMBER_ID` | string | — | Phone number ID |
| `whatsapp_verify_token` | `POCKETPAW_WHATSAPP_VERIFY_TOKEN` | string | — | Webhook verify token |
| `whatsapp_allowed_phone_numbers` | `POCKETPAW_WHATSAPP_ALLOWED_PHONE_NUMBERS` | string[] | `[]` | Allowed numbers (comma-separated) |
| `whatsapp_neonize_db` | `POCKETPAW_WHATSAPP_NEONIZE_DB` | string | `~/.pocketpaw/neonize.db` | Neonize DB path |
## Signal
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `signal_api_url` | `POCKETPAW_SIGNAL_API_URL` | string | — | signal-cli REST API URL |
| `signal_phone_number` | `POCKETPAW_SIGNAL_PHONE_NUMBER` | string | — | Registered number |
| `signal_allowed_numbers` | `POCKETPAW_SIGNAL_ALLOWED_NUMBERS` | string[] | `[]` | Allowed numbers (comma-separated) |
## Matrix
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `matrix_homeserver` | `POCKETPAW_MATRIX_HOMESERVER` | string | — | Homeserver URL |
| `matrix_user_id` | `POCKETPAW_MATRIX_USER_ID` | string | — | Bot user ID |
| `matrix_access_token` | `POCKETPAW_MATRIX_ACCESS_TOKEN` | string | — | Auth token |
| `matrix_device_id` | `POCKETPAW_MATRIX_DEVICE_ID` | string | — | Device ID |
| `matrix_allowed_room_ids` | `POCKETPAW_MATRIX_ALLOWED_ROOM_IDS` | string[] | `[]` | Allowed rooms (comma-separated IDs) |
| `matrix_display_name` | `POCKETPAW_MATRIX_DISPLAY_NAME` | string | — | Display name |
## Microsoft Teams
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `teams_app_id` | `POCKETPAW_TEAMS_APP_ID` | string | — | Bot Framework App ID |
| `teams_app_password` | `POCKETPAW_TEAMS_APP_PASSWORD` | string | — | App password |
| `teams_tenant_id` | `POCKETPAW_TEAMS_TENANT_ID` | string | — | Azure tenant ID |
| `teams_allowed_team_ids` | `POCKETPAW_TEAMS_ALLOWED_TEAM_IDS` | string[] | `[]` | Allowed teams (comma-separated IDs) |
## Google Chat
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `gchat_project_id` | `POCKETPAW_GCHAT_PROJECT_ID` | string | — | GCP project ID |
| `gchat_service_account_key` | `POCKETPAW_GCHAT_SERVICE_ACCOUNT_KEY` | string | — | SA key path |
| `gchat_mode` | `POCKETPAW_GCHAT_MODE` | enum | `webhook` | Connection mode (`webhook`, `pubsub`) |
| `gchat_subscription` | `POCKETPAW_GCHAT_SUBSCRIPTION` | string | — | Pub/Sub subscription |
| `gchat_allowed_space_ids` | `POCKETPAW_GCHAT_ALLOWED_SPACE_IDS` | string[] | `[]` | Allowed spaces (comma-separated IDs) |
## Web Search
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `web_search_provider` | `POCKETPAW_WEB_SEARCH_PROVIDER` | enum | `tavily` | Search provider (`tavily`, `brave`) |
| `tavily_api_key` | `POCKETPAW_TAVILY_API_KEY` | string | — | Tavily API key |
| `brave_search_api_key` | `POCKETPAW_BRAVE_SEARCH_API_KEY` | string | — | Brave Search key |
## Image Generation
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `google_api_key` | `POCKETPAW_GOOGLE_API_KEY` | string | — | Google AI API key |
| `image_model` | `POCKETPAW_IMAGE_MODEL` | string | `gemini-2.0-flash` | Model |
## Voice & STT
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `tts_provider` | `POCKETPAW_TTS_PROVIDER` | enum | `openai` | TTS provider (`openai`, `elevenlabs`, `sarvam`) |
| `tts_voice` | `POCKETPAW_TTS_VOICE` | string | `alloy` | Voice ID |
| `elevenlabs_api_key` | `POCKETPAW_ELEVENLABS_API_KEY` | string | — | ElevenLabs key |
| `stt_model` | `POCKETPAW_STT_MODEL` | string | `whisper-1` | STT model |
## Google Integration
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `google_client_id` | `POCKETPAW_GOOGLE_CLIENT_ID` | string | — | OAuth client ID |
| `google_client_secret` | `POCKETPAW_GOOGLE_CLIENT_SECRET` | string | — | OAuth secret |
## Spotify
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `spotify_client_id` | `POCKETPAW_SPOTIFY_CLIENT_ID` | string | — | Spotify client ID |
| `spotify_client_secret` | `POCKETPAW_SPOTIFY_CLIENT_SECRET` | string | — | Spotify secret |
## MCP
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `mcp_client_metadata_url` | `POCKETPAW_MCP_CLIENT_METADATA_URL` | string | — | CIMD URL for MCP OAuth (for servers without dynamic client registration) |
## Memory (Mem0)
| Setting | Env Variable | Type | Default | Description |
|---------|-------------|------|---------|-------------|
| `mem0_auto_learn` | `POCKETPAW_MEM0_AUTO_LEARN` | boolean | `false` | Enable auto-learn |
| `mem0_llm_provider` | `POCKETPAW_MEM0_LLM_PROVIDER` | enum | `anthropic` | LLM provider (`anthropic`, `openai`, `ollama`) |
| `mem0_llm_model` | `POCKETPAW_MEM0_LLM_MODEL` | string | `claude-haiku-4-5-20251001` | LLM model |
| `mem0_embedder_provider` | `POCKETPAW_MEM0_EMBEDDER_PROVIDER` | enum | `openai` | Embedder provider (`openai`, `ollama`, `huggingface`) |
| `mem0_embedder_model` | `POCKETPAW_MEM0_EMBEDDER_MODEL` | string | `text-embedding-3-small` | Embedder model |
| `mem0_vector_store` | `POCKETPAW_MEM0_VECTOR_STORE` | enum | `qdrant` | Vector store (`qdrant`, `chroma`) |
Reference in New Issue View Git Blame Copy Permalink