lifemate-ai/familiar-ai/familiar-check-env

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

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)

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

Section 3: TTS / Voice (optional)

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

which mpv || which ffplay

Section 4: Mobility / Robot Vacuum (optional)

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.