Make LLM provider configurable via env vars (switch to Groq)

Support any OpenAI-compatible API (Groq, Mistral, Together, etc.) via
LLM_API_KEY, LLM_BASE_URL, and LLM_MODEL environment variables.
Fail fast on 429 rate limits so callers use their fallbacks instantly.

.env.example

@@ -1 +1,11 @@
-MISTRAL_API_KEY=your_mistral_api_key_here
+# LLM Provider Configuration
+# Supports any OpenAI-compatible API (Mistral, Groq, Together, Gemini, etc.)
+LLM_API_KEY=your-api-key-here
+LLM_BASE_URL=https://api.groq.com/openai/v1
+LLM_MODEL=llama-3.3-70b-versatile
+
+# Optional: separate model for conversation (leave empty to use LLM_MODEL)
+# LLM_CONVERSATION_MODEL=
+
+# Legacy Mistral config (still supported if LLM_API_KEY is not set):
+# MISTRAL_API_KEY=your-key-here

src/mindsphere/core/agent.py

@@ -164,7 +164,7 @@ class CoachingAgent:
                 client = MistralClient()
                 self._generator = CoachGenerator(client=client)
                 if self._generator.is_available:
-                    logger.info("LLM generator available — using Mistral for conversation")
+                    logger.info(f"LLM generator available — using {client.base_url} ({client.model})")
                 else:
                     logger.warning("LLM generator created but not available (no API key?) — using template responses")
                     self._generator = None
@@ -1074,12 +1074,12 @@ class CoachingAgent:
                     messages=messages,
                     temperature=0.7,
                     max_tokens=80,  # Keep acks short
-                    model_override="mistral-medium-latest",
+                    model_override=None,  # uses LLM_MODEL default
                 )
                 if response and response.strip():
                     logger.info(f"[LLM] Calibration ack: '{response.strip()[:60]}...'")
                     return response.strip()
-                logger.warning("[LLM] Empty calibration ack from Mistral")
+                logger.warning("[LLM] Empty calibration ack from LLM")
             except Exception as e:
                 logger.warning(f"[LLM] Calibration ack failed: {e}")
         else:
@@ -2093,12 +2093,12 @@ class CoachingAgent:
                     messages=messages,
                     temperature=0.7,
                     max_tokens=300,
-                    model_override="mistral-medium-latest",
+                    model_override=None,  # uses LLM_MODEL default
                 )
                 if response and response.strip():
                     logger.info(f"[LLM] Sphere commentary generated ({len(response)} chars)")
                     return response.strip()
-                logger.warning("[LLM] Empty sphere commentary from Mistral")
+                logger.warning("[LLM] Empty sphere commentary from LLM")
             except Exception as e:
                 logger.warning(f"[LLM] Sphere commentary failed: {e}")
 

src/mindsphere/llm/client.py

@@ -31,37 +31,58 @@ class MistralAPIError(Exception):
 @dataclass
 class MistralClient:
     """
-    Thin HTTP wrapper for Mistral's /v1/chat/completions endpoint.
+    HTTP wrapper for OpenAI-compatible /v1/chat/completions endpoints.
 
-    Handles authentication, retries, and response parsing.
-    The classifier and generator use this as their backend.
+    Works with any provider: Mistral, Groq, Together, Gemini, etc.
+    Configure via environment variables:
+        LLM_API_KEY / MISTRAL_API_KEY — API key
+        LLM_BASE_URL — API base URL (default: Mistral)
+        LLM_MODEL — Default model name
     """
 
     api_key: str = ""
-    model: str = "mistral-small-latest"
-    base_url: str = "https://api.mistral.ai/v1"
+    model: str = ""
+    base_url: str = ""
     timeout: float = 30.0
     max_retries: int = 2
 
     def __post_init__(self):
+        # Load .env file into os.environ so all config is accessible
+        self._load_dotenv()
+        if not self.base_url:
+            self.base_url = os.environ.get(
+                "LLM_BASE_URL", "https://api.mistral.ai/v1"
+            )
+        if not self.model:
+            self.model = os.environ.get("LLM_MODEL", "mistral-small-latest")
         if not self.api_key:
             self.api_key = self._load_api_key()
 
-    def _load_api_key(self) -> str:
-        """Load API key from environment variable or .env file."""
-        key = os.environ.get("MISTRAL_API_KEY", "")
-        if key:
-            return key
-
+    def _load_dotenv(self) -> None:
+        """Load .env file into os.environ (only vars not already set)."""
         for parent in [Path.cwd()] + list(Path(__file__).resolve().parents):
             env_path = parent / ".env"
             if env_path.exists():
                 for line in env_path.read_text().splitlines():
                     line = line.strip()
-                    if line.startswith("MISTRAL_API_KEY=") and not line.startswith("#"):
-                        return line.split("=", 1)[1].strip()
+                    if not line or line.startswith("#"):
+                        continue
+                    if "=" in line:
+                        key, value = line.split("=", 1)
+                        key, value = key.strip(), value.strip()
+                        if key and key not in os.environ:
+                            os.environ[key] = value
+                break  # only load the first .env found
 
-        raise MistralAPIError(401, "No MISTRAL_API_KEY found in env or .env file")
+    def _load_api_key(self) -> str:
+        """Load API key from environment variable."""
+        # Check generic LLM_API_KEY first, then legacy MISTRAL_API_KEY
+        for env_var in ("LLM_API_KEY", "MISTRAL_API_KEY"):
+            key = os.environ.get(env_var, "")
+            if key:
+                return key
+
+        raise MistralAPIError(401, "No LLM_API_KEY or MISTRAL_API_KEY found in env or .env file")
 
     def _headers(self) -> Dict[str, str]:
         return {
@@ -123,14 +144,11 @@ class MistralClient:
                 if resp.status_code in (400, 401, 403, 404):
                     raise MistralAPIError(resp.status_code, resp.text)
 
-                # Rate limit: respect Retry-After header if present
+                # Rate limit: fail fast so callers can use their fallback
                 if resp.status_code == 429:
-                    retry_after = resp.headers.get("Retry-After")
-                    wait = float(retry_after) if retry_after else (2 ** attempt + 1)
-                    logger.warning(f"[MistralClient] Rate limited (429), waiting {wait:.0f}s")
-                    if attempt < self.max_retries:
-                        time.sleep(wait)
-                        continue
+                    retry_after = resp.headers.get("Retry-After", "?")
+                    logger.warning(f"[LLMClient] Rate limited (429), Retry-After={retry_after}s — failing fast")
+                    raise MistralAPIError(429, f"Rate limited (Retry-After: {retry_after}s)")
 
                 last_error = MistralAPIError(resp.status_code, resp.text)
 

src/mindsphere/llm/generator.py

@@ -21,8 +21,10 @@ from .client import MistralClient, MistralAPIError
 logger = logging.getLogger(__name__)
 
 
-# The model to use for conversation (needs web_search support)
-CONVERSATION_MODEL = "mistral-medium-latest"
+# Optional: separate model for conversation (e.g. a stronger model for responses).
+# Set via LLM_CONVERSATION_MODEL env var. Empty = use the default LLM_MODEL.
+import os
+CONVERSATION_MODEL = os.environ.get("LLM_CONVERSATION_MODEL", "")
 
 # Web search tool definition for Mistral
 # NOTE: web_search format varies by Mistral API version.
@@ -352,7 +354,7 @@ class CoachGenerator:
 
         # Log message structure for debugging
         roles = [m["role"] for m in messages]
-        logger.info(f"[CoachGenerator] Sending {len(messages)} messages to Mistral (roles: {roles[-5:]})")
+        logger.info(f"[CoachGenerator] Sending {len(messages)} messages to LLM (roles: {roles[-5:]})")
 
         # Detect duplicate user messages (bug diagnostic)
         user_msgs = [m["content"][:80] for m in messages if m["role"] == "user"]
@@ -373,12 +375,12 @@ class CoachGenerator:
                 temperature=0.7,
                 max_tokens=300,
                 tools=tools,
-                model_override=CONVERSATION_MODEL,
+                model_override=CONVERSATION_MODEL or None,
             )
             if response and response.strip():
-                logger.info(f"[CoachGenerator] Mistral responded ({len(response)} chars)")
+                logger.info(f"[CoachGenerator] LLM responded ({len(response)} chars)")
                 return response.strip()
-            logger.warning("[CoachGenerator] Empty response from Mistral")
+            logger.warning("[CoachGenerator] Empty response from LLM")
             return ""
         except Exception as e:
             logger.warning(f"[CoachGenerator] Exception: {e}")
@@ -422,7 +424,7 @@ class CoachGenerator:
             messages.append({"role": msg["role"], "content": msg["content"]})
         messages.append({"role": "user", "content": user_message})
 
-        logger.info(f"[CoachGenerator] Streaming {len(messages)} messages to Mistral")
+        logger.info(f"[CoachGenerator] Streaming {len(messages)} messages to LLM")
 
         try:
             collected = []
@@ -430,7 +432,7 @@ class CoachGenerator:
                 messages=messages,
                 temperature=0.7,
                 max_tokens=300,
-                model_override=CONVERSATION_MODEL,
+                model_override=CONVERSATION_MODEL or None,
             ):
                 collected.append(chunk)
                 yield chunk