name	familiar-check-env
description	Validate the .env configuration for familiar-ai. Detects common misconfigurations like wrong ports, missing MODEL, or TOOLS_MODE issues that cause silent failures or timeouts.

familiar-check-env

Validate the .env (or environment) for familiar-ai and surface likely misconfigurations before they cause cryptic errors.

When to Use

"It's not responding" / "Request timed out" with a local LLM
Setting up familiar-ai for the first time
Switching between platforms (Anthropic → LM Studio → Ollama, etc.)
After upgrading familiar-ai when new env vars were added

What to Check

Read the current .env (or os.environ) and validate each section:

Section 1: Core LLM

Var	Expected	Common Mistake
`PLATFORM`	`anthropic` / `openai` / `gemini` / `kimi`	Typo, or not set (defaults to `anthropic`)
`API_KEY`	Non-empty	Forgotten, wrong key for the platform
`MODEL`	Platform-appropriate model ID	Not set → defaults to `claude-haiku-4-5-20251001` or `gpt-4o-mini`, which LM Studio won't serve
`BASE_URL`	Valid URL	Wrong port (LM Studio=1234, Ollama=11434), HTTP vs HTTPS
`TOOLS_MODE`	`prompt` for local models, `native` for real OpenAI	Missing → now defaults to `prompt` for non-OpenAI (was `native` before v0.x)

Platform-specific checks:

PLATFORM=anthropic → API_KEY should start with sk-ant-; BASE_URL and TOOLS_MODE are ignored
PLATFORM=openai + BASE_URL not set → falls back to https://api.openai.com/v1 (real OpenAI)
PLATFORM=openai + BASE_URL set to local → warn if TOOLS_MODE=native (may cause timeout on models that don't support function calling)
PLATFORM=gemini → API_KEY should be a Google AI Studio key; BASE_URL is ignored
PLATFORM=kimi → API_KEY is a Moonshot AI key

LM Studio specific:

Default port is 1234, not 11434
LM Studio only binds to localhost by default; cross-machine access requires enabling "Allow connections from network" in LM Studio settings
MODEL must exactly match the identifier shown in LM Studio's loaded model list

Ollama specific:

Default port is 11434
Ollama binds to 0.0.0.0 by default, so cross-machine access usually works without extra config

Section 2: Camera (optional)

Var	Notes
`CAMERA_HOST`	IP of the camera on the local network
`CAMERA_USERNAME`	Usually `admin`
`CAMERA_PASSWORD`	Required if `CAMERA_HOST` is set
`CAMERA_ONVIF_PORT`	Default `2020` for Tapo; check your camera's spec

Warn if CAMERA_HOST is set but CAMERA_PASSWORD is empty — camera tool will silently skip init.

Section 3: TTS / Voice (optional)

Var	Notes
`ELEVENLABS_API_KEY`	Required for TTS
`ELEVENLABS_VOICE_ID`	Defaults to a built-in voice; override for custom voices
`GO2RTC_URL`	Default `http://localhost:1984`; only needed for camera speaker
`GO2RTC_STREAM`	Default `tapo_cam`

Check that mpv or ffplay is available in PATH for local speaker playback:

which mpv || which ffplay

Section 4: Mobility / Robot Vacuum (optional)

Var	Notes
`TUYA_API_KEY`	From Tuya IoT Platform
`TUYA_API_SECRET`	From Tuya IoT Platform
`TUYA_DEVICE_ID`	The vacuum's device ID in Tuya
`TUYA_REGION`	`us` / `eu` / `cn` / `in`

Mobility tool silently skips init if any of these are missing.

Output Format

Report findings grouped by severity:

[PLATFORM: openai]
  ✅ API_KEY is set
  ✅ BASE_URL = http://192.168.10.6:1234/v1  (LM Studio)
  ⚠️  TOOLS_MODE not set → defaulting to "prompt" (correct for local models)
  ❌ MODEL not set → will request "gpt-4o-mini" which LM Studio may not serve
     Fix: set MODEL=<your-loaded-model-identifier>

[CAMERA]
  ✅ CAMERA_HOST = 192.168.10.5
  ❌ CAMERA_PASSWORD is empty → camera tool will not initialize

[TTS]
  ⚠️  ELEVENLABS_API_KEY not set → TTS disabled
  ⚠️  mpv not found in PATH, ffplay not found → no local audio playback

[MOBILITY]
  ℹ️  TUYA_* not set → mobility disabled (OK if no robot vacuum)

Always end with a summary:

Summary: 1 error, 2 warnings. Fix errors before starting the agent.

name	familiar-check-env
description	Validate the .env configuration for familiar-ai. Detects common misconfigurations like wrong ports, missing MODEL, or TOOLS_MODE issues that cause silent failures or timeouts.