feat: enable AI-free operation — make Gemini API key optional

[hessius]

Summary

MeticAI should be fully usable without a Gemini API key. Users who just want to manage profiles, control their machine, browse shot history, and import existing profiles should be able to do so without configuring (or paying for) AI services. AI features should gracefully degrade — disabled in the UI, guarded on the backend — rather than blocking the entire app.

---

Motivation

• Lower the barrier to entry for new users
• Not everyone wants/needs AI-generated profiles — many users have profiles they already like
• Reduces cost for users who only want machine control + profile management
• The app already has significant non-AI value: Control Center, shot history, profile catalogue, scheduling, live telemetry

---

Current State: AI Dependency Audit

Hard AI dependencies (must disable when no key)

Feature	Endpoint	File
Coffee bag analysis	POST /api/analyze_coffee	apps/server/api/routes/coffee.py
AI profile creation	POST /api/analyze_and_profile	apps/server/api/routes/coffee.py
Description format conversion	POST /api/profile/convert-description	apps/server/api/routes/profiles.py
AI image generation	POST /api/profile/{name}/generate-image	apps/server/api/routes/profiles.py

Soft AI dependencies (can gracefully degrade)

Feature	Endpoint	Fallback
Profile import description	POST /api/profile/import	Skip generation, use static description (see below)
Bulk profile import	POST /api/profile/import-all	Same — already catches generation failures
LLM shot analysis	POST /api/shots/analyze-llm	Local algorithmic analysis already exists in _analyze_shot_local()
LLM cache check	GET /api/shots/{id}/llm-analysis	Returns null — no issue

No AI dependency (already works)

• Control Center (all machine commands, live telemetry, WebSocket)
• Profile catalogue browsing, manual image uploads
• Shot history with local/algorithmic analysis
• Scheduling, settings, machine profiles listing
• Health check, version endpoint

---

Proposed Changes

1. Backend: is_ai_available() helper

Add a simple check in services/gemini_service.py:

def is_ai_available() -> bool:
    """Check if the Gemini API key is configured."""
    return bool(os.environ.get("GEMINI_API_KEY", "").strip())

2. Backend: Guard AI endpoints

All hard-dependency endpoints should return HTTP 503 with a clear message when AI is unavailable:

{
  "status": "error",
  "error": "ai_not_configured",
  "message": "This feature requires a Gemini API key. Configure one in Settings."
}

3. Backend: Expose AI status in settings

The GET /api/settings response already includes gemini_configured: bool. The frontend can use this to conditionally render UI.

4. Frontend: Conditional AI UI

Components that need changes:

Component	Change
CoffeeAnalyzer.tsx	Disable "Create Profile" / "Analyze" buttons when !gemini_configured. Show a hint linking to Settings.
ProfileImportDialog.tsx	Default generate_description: false when AI unavailable. Hide the "Generate descriptions" toggle or show it as disabled.
HistoryView.tsx	Hide "Generate Image" and "Convert Description" buttons when AI unavailable. Manual image upload remains enabled.
ShotHistoryView.tsx	Hide "AI Analysis" tab/button when AI unavailable. Local analysis tab remains.
SettingsView.tsx	Already handles missing key gracefully. Could add a note: "AI features are optional — MeticAI works without a Gemini API key."

5. Static profile descriptions (for AI-free imports)

When importing profiles without AI, generate a deterministic local description from the profile JSON instead of calling the LLM. This should be a pure Python function, e.g.:

def generate_static_description(profile: dict) -> str:
    """Generate a human-readable description from profile JSON without AI."""
    name = profile.get("name", "Unknown")
    temp = profile.get("temperature")
    weight = profile.get("final_weight")
    stages = profile.get("stages", [])
    
    # Build stage summary
    stage_names = [s.get("name", f"Stage {i+1}") for i, s in enumerate(stages)]
    
    parts = [f"**Profile Created**: {name}\n"]
    parts.append(f"**Stages**: {len(stages)}-stage profile")
    if stage_names:
        parts.append(f"({', '.join(stage_names)})")
    if temp:
        parts.append(f"\n**Temperature**: {temp}°C")
    if weight:
        parts.append(f"\n**Target Weight**: {weight}g")
    
    return "\n".join(parts)

Additionally, if the profile JSON contains a description field (some Meticulous profiles do), use that as the description text directly.

6. Install scripts: Make API key optional

Both scripts/install.sh and scripts/install.ps1 currently require the Gemini API key input. Change to:

Enter your Gemini API key (press Enter to skip — AI features will be disabled):

7. MCP server / Gemini CLI: Conditional startup

The mcp-server s6 service and Gemini CLI are only useful when AI is configured. Make the s6 service check for the key and exit cleanly if not set, saving container resources:

#!/command/execlineb -P
if { test -n "${GEMINI_API_KEY}" }
  # start the MCP server

8. Docker image size consideration (optional / future)

The Gemini CLI (@google/gemini-cli) adds significant size to the Docker image. A future optimization could create a lighter "no-AI" image variant, but this is not required for the initial implementation.

---

Acceptance Criteria

• App starts and is fully functional with an empty GEMINI_API_KEY
• AI-dependent buttons/features are visually disabled (not hidden) with a tooltip/hint explaining why
• Profile import works without AI — uses static description or profile's own description field
• Shot history shows local analysis; LLM analysis button is disabled
• Install scripts accept a blank API key with a clear message
• Settings page communicates that AI is optional
• All existing tests pass
• No breaking changes for users who have an API key configured

---

Out of Scope

• Manual profile creation UI (separate feature request)
• "No-AI" Docker image variant (future optimization)
• Alternative AI providers (future feature)

[hessius]

Some ideas: The static description should a) use the description of the profile if available or b) could try to identify a few common types of shots, e.g. pre-infusion, flat, bloom, soup etc to make the description a bit more natural sounding. Should try to use some sort of natural language and should disclaim that this is not the full description.
we should have a toggle for auto generating descriptions on import yes / no and for those with ai features provide a button to generate the description
for users with disabled ai-features we should by default show deactivated buttons to show users what they're missing but provide an option to hide ai features.

[hessius]

v2.1.0-beta.7 Milestone Audit

Status: ✅ Fully Implemented

All acceptance criteria verified against the codebase:

Criterion	Status	Evidence
App starts with empty GEMINI_API_KEY	✅	docker-compose defaults to empty; uvicorn starts unconditionally
AI buttons disabled (not hidden) with tooltip	✅	disabled={!aiConfigured} + "AI unavailable" messages in StartView, HistoryView, ShotHistoryView, ProfileImportDialog
Profile import works without AI	✅	_build_static_profile_description() in analysis_service.py generates structural descriptions from profile JSON
Shot history local analysis; LLM button disabled	✅	ShotHistoryView gates button with disabled={!aiConfigured}
Install scripts accept blank API key	✅	Both install.sh (line ~530) and install.ps1 (line ~273) accept Enter-to-skip with warning
Settings page communicates AI optional	✅	geminiApiKeyConfigured exposed; "Hide AI when unavailable" toggle in SettingsView
All existing tests pass	✅	503 error test for missing key in test_main.py; CI green
No breaking changes for users with key	✅	is_ai_available() returns true when key present; normal flow unchanged

Key implementation details:

• is_ai_available() in gemini_service.py — simple env-var check
• AI endpoints return HTTP 503 with "ai_not_configured" error code
• Frontend isAiConfigured prop flows from App.tsx → all child components
• User preference to hide vs disable AI buttons (aiPreferences.ts)
• MCP s6 service starts unconditionally (external clients provide own keys)

Minor note: No dedicated E2E test for full app startup without API key, but unit test coverage exists for the 503 path.

[hessius]

Shipped in v2.1.0 — see release notes