feat: Enable 100% HF Space capability with dynamic environment variables

- Add env helper functions for both naming conventions (simple and nested)
- Support all embeddings providers: Jina, Google, HuggingFace
- Enable Langfuse observability configuration
- Make LLM models configurable via environment
- Remove hardcoded values - everything is now dynamic
- Update HF README with complete secrets reference
- Add .env.huggingface template with all options
- Update deployment guide with secrets configuration
- Enhance startup logging to show all enabled features
- Tests passing: 4/4 llm_config, 3/3 settings

DEPLOY_HUGGINGFACE.md

@@ -65,15 +65,33 @@ mv README.md README_original.md
 cp huggingface/README.md ./README.md
 ```
 
-## Step 6: Add Your API Key (Secret)
+## Step 6: Add Your API Keys (Secrets)
 
 1. Go to your Space: `https://huggingface.co/spaces/YOUR_USERNAME/mediguard-ai`
 2. Click **Settings** tab
 3. Scroll to **Repository Secrets**
-4. Add a new secret:
-   - **Name**: `GROQ_API_KEY` (or `GOOGLE_API_KEY`)
-   - **Value**: Your API key
-5. Click **Add**
+
+### Required Secrets (pick one)
+
+| Secret | Description | Get Free Key |
+|--------|-------------|--------------|
+| `GROQ_API_KEY` | Groq API key (recommended) | [console.groq.com/keys](https://console.groq.com/keys) |
+| `GOOGLE_API_KEY` | Google Gemini API key | [aistudio.google.com](https://aistudio.google.com/app/apikey) |
+
+### Optional Secrets
+
+| Secret | Description | Default |
+|--------|-------------|---------|
+| `GROQ_MODEL` | Groq model to use | `llama-3.3-70b-versatile` |
+| `GEMINI_MODEL` | Gemini model to use | `gemini-2.0-flash` |
+| `EMBEDDING_PROVIDER` | Embedding provider: `jina`, `google`, `huggingface` | `huggingface` |
+| `JINA_API_KEY` | Jina AI API key for high-quality embeddings | - |
+| `LANGFUSE_ENABLED` | Enable Langfuse tracing (`true`/`false`) | `false` |
+| `LANGFUSE_PUBLIC_KEY` | Langfuse public key | - |
+| `LANGFUSE_SECRET_KEY` | Langfuse secret key | - |
+| `LANGFUSE_HOST` | Langfuse host URL | - |
+
+> **Tip**: See `huggingface/.env.huggingface` for a complete reference of all available secrets.
 
 ## Step 7: Push to Deploy
 

huggingface/.env.huggingface

@@ -0,0 +1,69 @@
+# ===========================================================================
+# MediGuard AI — HuggingFace Spaces Secrets Reference
+# ===========================================================================
+# Copy these to your HuggingFace Space Settings → Secrets
+# ===========================================================================
+
+# ===========================================================================
+# REQUIRED: LLM API Key (choose one)
+# ===========================================================================
+
+# Option 1: Groq (RECOMMENDED - fast, free)
+# Get key at: https://console.groq.com/keys
+GROQ_API_KEY=your_groq_api_key_here
+
+# Option 2: Google Gemini (free tier)
+# Get key at: https://aistudio.google.com/app/apikey
+# GOOGLE_API_KEY=your_google_api_key_here
+
+# ===========================================================================
+# OPTIONAL: LLM Model Configuration
+# ===========================================================================
+
+# Groq model (default: llama-3.3-70b-versatile)
+# Options: llama-3.3-70b-versatile, llama-3.1-8b-instant, mixtral-8x7b-32768
+# GROQ_MODEL=llama-3.3-70b-versatile
+
+# Gemini model (default: gemini-2.0-flash)
+# Options: gemini-2.0-flash, gemini-1.5-pro, gemini-1.5-flash
+# GEMINI_MODEL=gemini-2.0-flash
+
+# Force specific provider (auto-detected from keys if not set)
+# LLM_PROVIDER=groq
+
+# ===========================================================================
+# OPTIONAL: Embeddings Configuration
+# ===========================================================================
+
+# Embedding provider (default: huggingface - local, no API needed)
+# Options: jina (high-quality 1024d), google, huggingface
+# EMBEDDING_PROVIDER=huggingface
+
+# Jina AI API key for high-quality embeddings
+# Get key at: https://jina.ai/ (free tier available)
+# JINA_API_KEY=your_jina_api_key_here
+
+# ===========================================================================
+# OPTIONAL: Observability (Langfuse)
+# ===========================================================================
+
+# Enable Langfuse tracing (default: false)
+# LANGFUSE_ENABLED=true
+
+# Langfuse credentials (required if LANGFUSE_ENABLED=true)
+# Get at: https://cloud.langfuse.com/
+# LANGFUSE_PUBLIC_KEY=pk-lf-xxx
+# LANGFUSE_SECRET_KEY=sk-lf-xxx
+# LANGFUSE_HOST=https://cloud.langfuse.com
+
+# ===========================================================================
+# Notes:
+# ===========================================================================
+# 
+# 1. At minimum, you need either GROQ_API_KEY or GOOGLE_API_KEY
+# 2. Groq is recommended for best speed/quality balance (free tier)
+# 3. HuggingFace embeddings run locally - no API key needed (default)
+# 4. Jina embeddings are higher quality but require API key
+# 5. Langfuse provides observability for debugging and monitoring
+#
+# ===========================================================================

huggingface/Dockerfile

@@ -20,9 +20,13 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
 ENV GRADIO_SERVER_NAME="0.0.0.0" \
     GRADIO_SERVER_PORT=7860
 
-# Default to HuggingFace embeddings (local, no API key needed)
+# Default embedding provider (can be overridden by HF Secrets)
+# Options: huggingface (local, no key needed), google, jina
 ENV EMBEDDING_PROVIDER=huggingface
 
+# Disable HF hub implicit token warning
+ENV HF_HUB_DISABLE_IMPLICIT_TOKEN=1
+
 WORKDIR /app
 
 # System dependencies

huggingface/README.md

@@ -44,12 +44,38 @@ A production-ready **Multi-Agent RAG System** that analyzes blood test biomarker
 
 ## 🔧 Configuration
 
-This Space requires an LLM API key. Add one of these secrets in Space Settings:
+This Space requires at least one LLM API key. Configure secrets in **Space Settings → Secrets**.
 
-| Secret | Provider | Get Free Key |
-|--------|----------|--------------|
-| `GROQ_API_KEY` | Groq (recommended) | [console.groq.com/keys](https://console.groq.com/keys) |
-| `GOOGLE_API_KEY` | Google Gemini | [aistudio.google.com](https://aistudio.google.com/app/apikey) |
+### Required Secrets (pick one)
+
+| Secret | Provider | Description | Get Free Key |
+|--------|----------|-------------|--------------|
+| `GROQ_API_KEY` | Groq | **Recommended** - Fast, free LLaMA 3.3-70B | [console.groq.com/keys](https://console.groq.com/keys) |
+| `GOOGLE_API_KEY` | Google Gemini | Free Gemini 2.0 Flash | [aistudio.google.com](https://aistudio.google.com/app/apikey) |
+
+### Optional: LLM Configuration
+
+| Secret | Default | Description |
+|--------|---------|-------------|
+| `GROQ_MODEL` | `llama-3.3-70b-versatile` | Groq model to use |
+| `GEMINI_MODEL` | `gemini-2.0-flash` | Gemini model to use |
+| `LLM_PROVIDER` | auto-detected | Force provider: `groq` or `gemini` |
+
+### Optional: Embeddings
+
+| Secret | Default | Description |
+|--------|---------|-------------|
+| `EMBEDDING_PROVIDER` | `huggingface` | Provider: `jina`, `google`, or `huggingface` |
+| `JINA_API_KEY` | - | High-quality 1024d embeddings ([jina.ai](https://jina.ai/)) |
+
+### Optional: Observability (Langfuse)
+
+| Secret | Description |
+|--------|-------------|
+| `LANGFUSE_ENABLED` | Set to `true` to enable tracing |
+| `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
+| `LANGFUSE_SECRET_KEY` | Langfuse secret key |
+| `LANGFUSE_HOST` | Langfuse host URL (e.g., `https://cloud.langfuse.com`) |
 
 ## 🏗️ Architecture
 

huggingface/app.py

@@ -4,7 +4,28 @@ MediGuard AI — Hugging Face Spaces Gradio App
 Standalone deployment that uses:
 - FAISS vector store (local)
 - Cloud LLMs (Groq or Gemini - FREE tiers)
-- No external services required
+- Multiple embedding providers (Jina, Google, HuggingFace)
+- Optional Langfuse observability
+
+Environment Variables (HuggingFace Secrets):
+  Required (pick one):
+    - GROQ_API_KEY: Groq API key (recommended, free)
+    - GOOGLE_API_KEY: Google Gemini API key (free)
+  
+  Optional - LLM Configuration:
+    - LLM_PROVIDER: "groq" or "gemini" (auto-detected from keys)
+    - GROQ_MODEL: Model name (default: llama-3.3-70b-versatile)
+    - GEMINI_MODEL: Model name (default: gemini-2.0-flash)
+  
+  Optional - Embeddings:
+    - EMBEDDING_PROVIDER: "jina", "google", or "huggingface" (default: huggingface)
+    - JINA_API_KEY: Jina AI API key for high-quality embeddings
+  
+  Optional - Observability:
+    - LANGFUSE_ENABLED: "true" to enable tracing
+    - LANGFUSE_PUBLIC_KEY: Langfuse public key
+    - LANGFUSE_SECRET_KEY: Langfuse secret key
+    - LANGFUSE_HOST: Langfuse host URL
 """
 
 from __future__ import annotations
@@ -33,37 +54,122 @@ logging.basicConfig(
 logger = logging.getLogger("mediguard.huggingface")
 
 # ---------------------------------------------------------------------------
-# Configuration
+# Configuration - Environment Variable Helpers
 # ---------------------------------------------------------------------------
 
+def _get_env(primary: str, *fallbacks, default: str = "") -> str:
+    """Get env var with multiple fallback names for compatibility."""
+    value = os.getenv(primary)
+    if value:
+        return value
+    for fb in fallbacks:
+        value = os.getenv(fb)
+        if value:
+            return value
+    return default
+
+
 def get_api_keys():
-    """Get API keys dynamically (HuggingFace injects secrets after module load)."""
-    groq_key = os.getenv("GROQ_API_KEY", "")
-    google_key = os.getenv("GOOGLE_API_KEY", "")
+    """Get API keys dynamically (HuggingFace injects secrets after module load).
+    
+    Supports both simple and nested naming conventions:
+    - GROQ_API_KEY / LLM__GROQ_API_KEY
+    - GOOGLE_API_KEY / LLM__GOOGLE_API_KEY
+    """
+    groq_key = _get_env("GROQ_API_KEY", "LLM__GROQ_API_KEY")
+    google_key = _get_env("GOOGLE_API_KEY", "LLM__GOOGLE_API_KEY")
     return groq_key, google_key
 
 
+def get_jina_api_key() -> str:
+    """Get Jina API key for embeddings."""
+    return _get_env("JINA_API_KEY", "EMBEDDING__JINA_API_KEY")
+
+
+def get_embedding_provider() -> str:
+    """Get configured embedding provider."""
+    return _get_env("EMBEDDING_PROVIDER", "EMBEDDING__PROVIDER", default="huggingface")
+
+
+def get_groq_model() -> str:
+    """Get configured Groq model name."""
+    return _get_env("GROQ_MODEL", "LLM__GROQ_MODEL", default="llama-3.3-70b-versatile")
+
+
+def get_gemini_model() -> str:
+    """Get configured Gemini model name."""
+    return _get_env("GEMINI_MODEL", "LLM__GEMINI_MODEL", default="gemini-2.0-flash")
+
+
+def is_langfuse_enabled() -> bool:
+    """Check if Langfuse observability is enabled."""
+    enabled = _get_env("LANGFUSE_ENABLED", "LANGFUSE__ENABLED", default="false")
+    return enabled.lower() in ("true", "1", "yes")
+
+
 def setup_llm_provider():
-    """Set LLM provider based on available keys."""
+    """Set up LLM provider and related configuration based on available keys.
+    
+    Sets environment variables for the entire application to use.
+    """
     groq_key, google_key = get_api_keys()
+    provider = None
     
     if groq_key:
         os.environ["LLM_PROVIDER"] = "groq"
-        os.environ["GROQ_API_KEY"] = groq_key  # Ensure it's set
-        return "groq"
+        os.environ["GROQ_API_KEY"] = groq_key
+        os.environ["GROQ_MODEL"] = get_groq_model()
+        provider = "groq"
+        logger.info(f"Configured Groq provider with model: {get_groq_model()}")
     elif google_key:
         os.environ["LLM_PROVIDER"] = "gemini"
         os.environ["GOOGLE_API_KEY"] = google_key
-        return "gemini"
-    return None
+        os.environ["GEMINI_MODEL"] = get_gemini_model()
+        provider = "gemini"
+        logger.info(f"Configured Gemini provider with model: {get_gemini_model()}")
+    
+    # Set up embedding provider
+    embedding_provider = get_embedding_provider()
+    os.environ["EMBEDDING_PROVIDER"] = embedding_provider
+    
+    # If Jina is configured, set the API key
+    jina_key = get_jina_api_key()
+    if jina_key:
+        os.environ["JINA_API_KEY"] = jina_key
+        os.environ["EMBEDDING__JINA_API_KEY"] = jina_key
+        logger.info("Jina embeddings configured")
+    
+    # Set up Langfuse if enabled
+    if is_langfuse_enabled():
+        os.environ["LANGFUSE__ENABLED"] = "true"
+        for var in ["LANGFUSE_PUBLIC_KEY", "LANGFUSE_SECRET_KEY", "LANGFUSE_HOST"]:
+            val = _get_env(var, f"LANGFUSE__{var.split('_', 1)[1]}")
+            if val:
+                os.environ[var] = val
+        logger.info("Langfuse observability enabled")
+    
+    return provider
 
 
 # Log status at startup (keys may not be available yet)
 _groq, _google = get_api_keys()
+_jina = get_jina_api_key()
+logger.info("=" * 60)
+logger.info("MediGuard AI — HuggingFace Space Starting")
+logger.info("=" * 60)
+logger.info(f"GROQ_API_KEY: {'✓ configured' if _groq else '✗ not set'}")
+logger.info(f"GOOGLE_API_KEY: {'✓ configured' if _google else '✗ not set'}")
+logger.info(f"JINA_API_KEY: {'✓ configured' if _jina else '✗ not set (using HuggingFace embeddings)'}")
+logger.info(f"EMBEDDING_PROVIDER: {get_embedding_provider()}")
+logger.info(f"LANGFUSE: {'✓ enabled' if is_langfuse_enabled() else '✗ disabled'}")
+
 if not _groq and not _google:
     logger.warning(
         "No LLM API key found at startup. Will check again when analyzing."
     )
+else:
+    logger.info("LLM API key available — ready for analysis")
+logger.info("=" * 60)
 
 
 # ---------------------------------------------------------------------------
@@ -103,9 +209,11 @@ def get_guild():
     
     try:
         logger.info("Initializing Clinical Insight Guild...")
-        logger.info(f"LLM_PROVIDER={os.getenv('LLM_PROVIDER')}")
-        logger.info(f"GROQ_API_KEY={'set' if os.getenv('GROQ_API_KEY') else 'NOT SET'}")
-        logger.info(f"GOOGLE_API_KEY={'set' if os.getenv('GOOGLE_API_KEY') else 'NOT SET'}")
+        logger.info(f"  LLM_PROVIDER: {os.getenv('LLM_PROVIDER', 'not set')}")
+        logger.info(f"  GROQ_API_KEY: {'✓ set' if os.getenv('GROQ_API_KEY') else '✗ not set'}")
+        logger.info(f"  GOOGLE_API_KEY: {'✓ set' if os.getenv('GOOGLE_API_KEY') else '✗ not set'}")
+        logger.info(f"  EMBEDDING_PROVIDER: {os.getenv('EMBEDDING_PROVIDER', 'huggingface')}")
+        logger.info(f"  JINA_API_KEY: {'✓ set' if os.getenv('JINA_API_KEY') else '✗ not set'}")
         
         start = time.time()
         
@@ -191,10 +299,25 @@ def analyze_biomarkers(input_text: str, progress=gr.Progress()) -> tuple[str, st
 <div style="background: linear-gradient(135deg, #fee2e2 0%, #fecaca 100%); border: 1px solid #ef4444; border-radius: 10px; padding: 16px;">
     <strong style="color: #dc2626;">❌ No API Key Configured</strong>
     <p style="margin: 12px 0 8px 0; color: #991b1b;">Please add your API key in Space Settings → Secrets:</p>
-    <ul style="margin: 0; color: #7f1d1d;">
-        <li><code>GROQ_API_KEY</code> - <a href="https://console.groq.com/keys" target="_blank" style="color: #2563eb;">Get free key →</a></li>
-        <li><code>GOOGLE_API_KEY</code> - <a href="https://aistudio.google.com/app/apikey" target="_blank" style="color: #2563eb;">Get free key →</a></li>
-    </ul>
+    
+    <div style="margin: 12px 0;">
+        <strong style="color: #374151;">Required (pick one):</strong>
+        <ul style="margin: 4px 0; color: #7f1d1d;">
+            <li><code>GROQ_API_KEY</code> - <a href="https://console.groq.com/keys" target="_blank" style="color: #2563eb;">Get free key →</a> (Recommended)</li>
+            <li><code>GOOGLE_API_KEY</code> - <a href="https://aistudio.google.com/app/apikey" target="_blank" style="color: #2563eb;">Get free key →</a></li>
+        </ul>
+    </div>
+    
+    <details style="margin-top: 12px;">
+        <summary style="cursor: pointer; color: #374151; font-weight: 600;">Optional configuration secrets</summary>
+        <ul style="margin: 8px 0; color: #6b7280; font-size: 0.9em;">
+            <li><code>GROQ_MODEL</code> - Model name (default: llama-3.3-70b-versatile)</li>
+            <li><code>GEMINI_MODEL</code> - Model name (default: gemini-2.0-flash)</li>
+            <li><code>JINA_API_KEY</code> - High-quality embeddings (optional)</li>
+            <li><code>EMBEDDING_PROVIDER</code> - jina, google, or huggingface</li>
+            <li><code>LANGFUSE_ENABLED</code> - Enable observability tracing</li>
+        </ul>
+    </details>
 </div>
         """
     
@@ -837,6 +960,11 @@ def create_demo() -> gr.Blocks:
                 <strong>Setup Required:</strong> Add your <code>GROQ_API_KEY</code> or 
                 <code>GOOGLE_API_KEY</code> in Space Settings → Secrets to enable analysis.
                 <a href="https://console.groq.com/keys" target="_blank" style="color: #2563eb;">Get free Groq key →</a>
+                <br>
+                <span style="font-size: 0.9em; color: #64748b;">
+                    Optional: Configure <code>JINA_API_KEY</code> for high-quality embeddings, 
+                    <code>LANGFUSE_ENABLED=true</code> for observability.
+                </span>
             </div>
         </div>
         """)
@@ -999,7 +1127,10 @@ def create_demo() -> gr.Blocks:
                 <a href="https://faiss.ai/" target="_blank" style="color: #3b82f6;">FAISS</a>, and 
                 <a href="https://gradio.app/" target="_blank" style="color: #3b82f6;">Gradio</a>
             </p>
-            <p style="margin-top: 8px;">Powered by <strong>Groq</strong> (LLaMA 3.3-70B) • Open Source on GitHub</p>
+            <p style="margin-top: 8px;">
+                Powered by <strong>Groq</strong> or <strong>Google Gemini</strong> • 
+                <a href="https://github.com" target="_blank" style="color: #3b82f6;">Open Source on GitHub</a>
+            </p>
         </div>
         """)
         

huggingface/requirements.txt

@@ -33,10 +33,13 @@ pypdf>=4.0.0
 pydantic>=2.9.0
 pydantic-settings>=2.5.0
 
-# --- HTTP Client ---
+# --- HTTP Client (for Jina AI embeddings) ---
 httpx>=0.27.0
 
 # --- Utilities ---
 python-dotenv>=1.0.0
 tenacity>=8.0.0
 numpy<2.0.0
+
+# --- Observability (optional, for Langfuse support) ---
+langfuse>=2.0.0

src/llm_config.py

@@ -6,6 +6,10 @@ Supports multiple providers:
 - Groq (FREE, fast, llama-3.3-70b) - RECOMMENDED
 - Google Gemini (FREE tier)
 - Ollama (local, for offline use)
+
+Environment Variables (supports both naming conventions):
+- Simple: GROQ_API_KEY, GOOGLE_API_KEY, LLM_PROVIDER, GROQ_MODEL, etc.
+- Nested: LLM__GROQ_API_KEY, LLM__GOOGLE_API_KEY, LLM__PROVIDER, etc.
 """
 
 import os
@@ -20,9 +24,39 @@ load_dotenv()
 os.environ["LANGCHAIN_PROJECT"] = os.getenv("LANGCHAIN_PROJECT", "MediGuard_AI_RAG_Helper")
 
 
+def _get_env_with_fallback(primary: str, fallback: str, default: str = "") -> str:
+    """Get env var with fallback to alternate naming convention."""
+    return os.getenv(primary) or os.getenv(fallback) or default
+
+
 def get_default_llm_provider() -> str:
-    """Get default LLM provider dynamically from environment."""
-    return os.getenv("LLM_PROVIDER", "groq")
+    """Get default LLM provider dynamically from environment.
+    
+    Supports both naming conventions:
+    - LLM_PROVIDER (simple)
+    - LLM__PROVIDER (pydantic nested)
+    """
+    return _get_env_with_fallback("LLM_PROVIDER", "LLM__PROVIDER", "groq")
+
+
+def get_groq_api_key() -> str:
+    """Get Groq API key from environment (supports both naming conventions)."""
+    return _get_env_with_fallback("GROQ_API_KEY", "LLM__GROQ_API_KEY", "")
+
+
+def get_google_api_key() -> str:
+    """Get Google API key from environment (supports both naming conventions)."""
+    return _get_env_with_fallback("GOOGLE_API_KEY", "LLM__GOOGLE_API_KEY", "")
+
+
+def get_groq_model() -> str:
+    """Get Groq model from environment (supports both naming conventions)."""
+    return _get_env_with_fallback("GROQ_MODEL", "LLM__GROQ_MODEL", "llama-3.3-70b-versatile")
+
+
+def get_gemini_model() -> str:
+    """Get Gemini model from environment (supports both naming conventions)."""
+    return _get_env_with_fallback("GEMINI_MODEL", "LLM__GEMINI_MODEL", "gemini-2.0-flash")
 
 
 # For backward compatibility (but prefer using get_default_llm_provider())
@@ -53,15 +87,15 @@ def get_chat_model(
     if provider == "groq":
         from langchain_groq import ChatGroq
         
-        api_key = os.getenv("GROQ_API_KEY")
+        api_key = get_groq_api_key()
         if not api_key:
             raise ValueError(
                 "GROQ_API_KEY not found in environment.\n"
                 "Get your FREE API key at: https://console.groq.com/keys"
             )
         
-        # Default to llama-3.3-70b for best quality (free on Groq)
-        model = model or "llama-3.3-70b-versatile"
+        # Use model from environment or default
+        model = model or get_groq_model()
         
         return ChatGroq(
             model=model,
@@ -73,15 +107,15 @@ def get_chat_model(
     elif provider == "gemini":
         from langchain_google_genai import ChatGoogleGenerativeAI
         
-        api_key = os.getenv("GOOGLE_API_KEY")
+        api_key = get_google_api_key()
         if not api_key:
             raise ValueError(
                 "GOOGLE_API_KEY not found in environment.\n"
                 "Get your FREE API key at: https://aistudio.google.com/app/apikey"
             )
         
-        # Default to Gemini 2.0 Flash (fast and free)
-        model = model or "gemini-2.0-flash"
+        # Use model from environment or default
+        model = model or get_gemini_model()
         
         return ChatGoogleGenerativeAI(
             model=model,
@@ -108,22 +142,47 @@ def get_chat_model(
         raise ValueError(f"Unknown provider: {provider}. Use 'groq', 'gemini', or 'ollama'")
 
 
-def get_embedding_model(provider: Optional[Literal["google", "huggingface", "ollama"]] = None):
+def get_embedding_provider() -> str:
+    """Get embedding provider from environment (supports both naming conventions)."""
+    return _get_env_with_fallback("EMBEDDING_PROVIDER", "EMBEDDING__PROVIDER", "huggingface")
+
+
+def get_embedding_model(provider: Optional[Literal["jina", "google", "huggingface", "ollama"]] = None):
     """
     Get embedding model for vector search.
     
     Args:
-        provider: "google" (free, recommended), "huggingface" (local), or "ollama" (local)
+        provider: "jina" (high-quality), "google" (free), "huggingface" (local), or "ollama" (local)
     
     Returns:
         LangChain embedding model instance
+        
+    Note:
+        For production use, prefer src.services.embeddings.service.make_embedding_service()
+        which has automatic fallback chain: Jina → Google → HuggingFace.
     """
-    provider = provider or os.getenv("EMBEDDING_PROVIDER", "google")
+    provider = provider or get_embedding_provider()
+    
+    if provider == "jina":
+        # Try Jina AI embeddings first (high quality, 1024d)
+        jina_key = _get_env_with_fallback("JINA_API_KEY", "EMBEDDING__JINA_API_KEY", "")
+        if jina_key:
+            try:
+                # Use the embedding service for Jina
+                from src.services.embeddings.service import make_embedding_service
+                return make_embedding_service()
+            except Exception as e:
+                print(f"WARN: Jina embeddings failed: {e}")
+                print("INFO: Falling back to Google embeddings...")
+                return get_embedding_model("google")
+        else:
+            print("WARN: JINA_API_KEY not found. Falling back to Google embeddings.")
+            return get_embedding_model("google")
     
-    if provider == "google":
+    elif provider == "google":
         from langchain_google_genai import GoogleGenerativeAIEmbeddings
         
-        api_key = os.getenv("GOOGLE_API_KEY")
+        api_key = get_google_api_key()
         if not api_key:
             print("WARN: GOOGLE_API_KEY not found. Falling back to HuggingFace embeddings.")
             return get_embedding_model("huggingface")