Implement conditional authentication middleware and OAuth routes for Hugging Face Spaces integration. Enhance environment debugging and add environment info endpoint. Update README with OAuth configuration details and improve startup logging.

README.md

@@ -7,6 +7,11 @@ sdk: docker
 pinned: false
 license: mit
 app_port: 7860
+hf_oauth: true
+hf_oauth_scopes:
+  - openid
+  - profile
+hf_oauth_expiration_minutes: 480
 ---
 
 # 🕸️ AgentGraph
@@ -21,7 +26,7 @@ The easiest way to get started is using our setup script:
 
 ```bash
 # 1. Clone the repository
-git clone <repository-url>
+git clone https://huggingface.co/spaces/holistic-ai/AgentGraph
 cd AgentGraph
 
 # 2. Run the setup script
@@ -41,7 +46,7 @@ If you prefer manual control:
 
 ```bash
 # 1. Clone and setup environment
-git clone <repository-url>
+git clone https://huggingface.co/spaces/holistic-ai/AgentGraph
 cd AgentGraph
 cp .env.example .env
 # Edit .env and add your OpenAI API key

backend/app.py

@@ -10,7 +10,10 @@ import sys
 from fastapi import FastAPI, Request, status
 from fastapi.staticfiles import StaticFiles
 from fastapi.middleware.cors import CORSMiddleware
+from starlette.middleware.sessions import SessionMiddleware
 from fastapi.responses import RedirectResponse, HTMLResponse
+from backend.middleware.auth import ConditionalAuthMiddleware
+from utils.environment import should_enable_auth, debug_environment
 
 
 # Add server module to path if not already there
@@ -30,6 +33,7 @@ from backend.routers import (
     example_traces,
     methods,
     observability,
+    auth,
 )
 
 # Setup logging
@@ -38,6 +42,16 @@ logger = logging.getLogger("agent_monitoring_server")
 # Create FastAPI app
 app = FastAPI(title="Agent Monitoring System", version="1.0.0")
 
+# Add session middleware (required for OAuth)
+app.add_middleware(
+    SessionMiddleware, 
+    secret_key=os.getenv("SESSION_SECRET_KEY", "your-secret-key-change-in-production"),
+    max_age=86400,  # 24 hours
+)
+
+# Add conditional authentication middleware
+app.add_middleware(ConditionalAuthMiddleware)
+
 # Add CORS middleware
 app.add_middleware(
     CORSMiddleware,
@@ -51,6 +65,7 @@ app.add_middleware(
 app.mount("/data", StaticFiles(directory="datasets"), name="data")
 
 # Include routers
+app.include_router(auth.router)  # Add auth router first
 app.include_router(traces.router)
 app.include_router(knowledge_graphs.router)
 app.include_router(agentgraph.router)
@@ -69,6 +84,9 @@ async def startup_event():
     """Start background services on app startup"""
     logger.info("✅ Backend server starting...")
     
+    # 🌍 Debug environment information
+    debug_environment()
+    
     # 🔧 Create necessary directories
     ensure_directories()
     logger.info("📁 Directory structure created")
@@ -82,6 +100,12 @@ async def startup_event():
         logger.error(f"❌ Database initialization failed: {e}")
         # Don't fail startup - continue with empty database
     
+    # 🔐 Log authentication status
+    if should_enable_auth():
+        logger.info("🔐 Authentication ENABLED (HF Spaces environment)")
+    else:
+        logger.info("🏠 Authentication DISABLED (Local development)")
+    
     logger.info("🚀 Backend API available at: http://0.0.0.0:7860")
     # scheduler_service.start() # This line is now commented out
 

backend/middleware/__init__.py

@@ -0,0 +1,7 @@
+"""
+Middleware package for AgentGraph backend.
+"""
+
+from .auth import ConditionalAuthMiddleware
+
+__all__ = ["ConditionalAuthMiddleware"]

backend/middleware/auth.py

@@ -0,0 +1,130 @@
+"""
+Conditional Authentication Middleware
+
+This middleware only enables authentication when running in Hugging Face Spaces.
+Local development bypasses authentication entirely.
+"""
+
+import os
+import logging
+from typing import Optional, Dict, Any
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import RedirectResponse, JSONResponse
+from utils.environment import should_enable_auth, get_oauth_config, is_huggingface_space
+
+logger = logging.getLogger(__name__)
+
+
+class ConditionalAuthMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware that conditionally enables authentication based on deployment environment.
+    
+    - In HF Spaces: Full OAuth authentication required
+    - In local development: Authentication bypassed
+    """
+    
+    def __init__(self, app, excluded_paths: Optional[list] = None):
+        super().__init__(app)
+        
+        # Paths that don't require authentication even in HF Spaces
+        self.excluded_paths = excluded_paths or [
+            "/",
+            "/docs",
+            "/redoc", 
+            "/openapi.json",
+            "/api/observability/health-check",
+            "/api/observability/environment",
+            "/auth/login",
+            "/auth/callback",
+            "/auth/logout",
+            "/assets/",
+            "/static/",
+            "/agentgraph",  # Allow React app to load
+        ]
+        
+        # Check if auth should be enabled
+        self.auth_enabled = should_enable_auth()
+        self.oauth_config = get_oauth_config() if self.auth_enabled else None
+        
+        # Log auth status
+        if self.auth_enabled:
+            logger.info("🔐 Authentication middleware ENABLED (HF Spaces environment)")
+            if not self.oauth_config:
+                logger.warning("⚠️ OAuth configuration not found in HF Spaces environment")
+        else:
+            logger.info("🏠 Authentication middleware DISABLED (Local development)")
+    
+    async def dispatch(self, request: Request, call_next):
+        """
+        Process request through conditional authentication.
+        """
+        # If auth is disabled (local dev), bypass all authentication
+        if not self.auth_enabled:
+            return await call_next(request)
+        
+        # If auth is enabled but OAuth not properly configured, log warning and continue
+        if not self.oauth_config:
+            logger.warning("OAuth not configured properly, bypassing auth")
+            return await call_next(request)
+        
+        # Check if path is excluded from authentication
+        if self._is_excluded_path(request.url.path):
+            return await call_next(request)
+        
+        # Check user authentication
+        user = await self._get_current_user(request)
+        if not user:
+            # For API calls, return JSON error
+            if request.url.path.startswith("/api/"):
+                return JSONResponse(
+                    status_code=401,
+                    content={"error": "Authentication required", "login_url": "/auth/login"}
+                )
+            
+            # For web requests, redirect to login
+            return RedirectResponse(url="/auth/login", status_code=302)
+        
+        # Add user info to request state
+        request.state.user = user
+        return await call_next(request)
+    
+    def _is_excluded_path(self, path: str) -> bool:
+        """Check if the request path should bypass authentication."""
+        return any(
+            path.startswith(excluded_path) 
+            for excluded_path in self.excluded_paths
+        )
+    
+    async def _get_current_user(self, request: Request) -> Optional[Dict[str, Any]]:
+        """
+        Get current user from session or token.
+        
+        In a full implementation, this would:
+        1. Check session cookies
+        2. Validate JWT tokens
+        3. Call HF API to verify user info
+        
+        For now, we'll implement a basic session check.
+        """
+        # Check if user info is in session
+        user = request.session.get("user") if hasattr(request, "session") else None
+        
+        # Check Authorization header as fallback
+        if not user:
+            auth_header = request.headers.get("Authorization")
+            if auth_header and auth_header.startswith("Bearer "):
+                # In a full implementation, validate this token with HF API
+                # For now, we'll assume it's valid if present
+                pass
+        
+        return user
+    
+    def get_auth_status(self) -> Dict[str, Any]:
+        """Get current authentication configuration status."""
+        return {
+            "auth_enabled": self.auth_enabled,
+            "environment": "huggingface_spaces" if is_huggingface_space() else "local_development", 
+            "oauth_configured": bool(self.oauth_config),
+            "excluded_paths": self.excluded_paths,
+        }

backend/routers/auth.py

@@ -0,0 +1,208 @@
+"""
+Authentication routes for Hugging Face OAuth integration.
+
+These routes are only active when running in HF Spaces environment.
+"""
+
+import os
+import logging
+import secrets
+from typing import Optional
+from fastapi import APIRouter, Request, Response, HTTPException
+from fastapi.responses import RedirectResponse, HTMLResponse, JSONResponse
+from utils.environment import should_enable_auth, get_oauth_config, is_huggingface_space
+import requests
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/auth", tags=["authentication"])
+
+
+@router.get("/status")
+async def auth_status():
+    """Get authentication status and configuration."""
+    config = get_oauth_config()
+    return {
+        "auth_enabled": should_enable_auth(),
+        "environment": "huggingface_spaces" if is_huggingface_space() else "local_development",
+        "oauth_available": bool(config),
+        "login_required": should_enable_auth() and bool(config),
+    }
+
+
+@router.get("/login")
+async def login(request: Request):
+    """
+    Initiate OAuth login flow.
+    Only available in HF Spaces environment.
+    """
+    if not should_enable_auth():
+        return JSONResponse(
+            content={"message": "Authentication not required in local development"},
+            status_code=200
+        )
+    
+    oauth_config = get_oauth_config()
+    if not oauth_config:
+        raise HTTPException(
+            status_code=500, 
+            detail="OAuth not configured in this environment"
+        )
+    
+    # Generate state for CSRF protection
+    state = secrets.token_urlsafe(32)
+    request.session["oauth_state"] = state
+    
+    # Get the current host for redirect URI
+    base_url = str(request.base_url).rstrip('/')
+    redirect_uri = f"{base_url}/auth/callback"
+    
+    # Build authorization URL
+    auth_url = (
+        f"{oauth_config['provider_url']}/oauth/authorize"
+        f"?client_id={oauth_config['client_id']}"
+        f"&redirect_uri={redirect_uri}"
+        f"&response_type=code"
+        f"&scope={oauth_config['scopes']}"
+        f"&state={state}"
+    )
+    
+    return RedirectResponse(url=auth_url, status_code=302)
+
+
+@router.get("/callback")
+async def oauth_callback(request: Request, code: str, state: str):
+    """
+    Handle OAuth callback from Hugging Face.
+    """
+    if not should_enable_auth():
+        return RedirectResponse(url="/", status_code=302)
+    
+    oauth_config = get_oauth_config()
+    if not oauth_config:
+        raise HTTPException(status_code=500, detail="OAuth not configured")
+    
+    # Verify state parameter (CSRF protection)
+    stored_state = request.session.get("oauth_state")
+    if not stored_state or stored_state != state:
+        raise HTTPException(status_code=400, detail="Invalid state parameter")
+    
+    # Exchange code for tokens
+    base_url = str(request.base_url).rstrip('/')
+    redirect_uri = f"{base_url}/auth/callback"
+    
+    try:
+        token_response = requests.post(
+            f"{oauth_config['provider_url']}/oauth/token",
+            data={
+                "grant_type": "authorization_code",
+                "code": code,
+                "redirect_uri": redirect_uri,
+                "client_id": oauth_config['client_id'],
+                "client_secret": oauth_config['client_secret'],
+            },
+            timeout=10
+        )
+        token_response.raise_for_status()
+        tokens = token_response.json()
+        
+    except requests.RequestException as e:
+        logger.error(f"Token exchange failed: {e}")
+        raise HTTPException(status_code=400, detail="Token exchange failed")
+    
+    access_token = tokens.get("access_token")
+    if not access_token:
+        raise HTTPException(status_code=400, detail="No access token received")
+    
+    # Get user information
+    try:
+        user_response = requests.get(
+            f"{oauth_config['provider_url']}/api/whoami-v2",
+            headers={"Authorization": f"Bearer {access_token}"},
+            timeout=10
+        )
+        user_response.raise_for_status()
+        user_info = user_response.json()
+        
+    except requests.RequestException as e:
+        logger.error(f"User info fetch failed: {e}")
+        raise HTTPException(status_code=400, detail="Failed to fetch user information")
+    
+    # Store user in session
+    request.session["user"] = {
+        "id": user_info.get("id"),
+        "name": user_info.get("name"),
+        "username": user_info.get("login"),  # HF username
+        "email": user_info.get("email"),
+        "avatar_url": user_info.get("avatarUrl"),
+        "access_token": access_token,  # Store for future API calls if needed
+    }
+    
+    # Clean up state
+    request.session.pop("oauth_state", None)
+    
+    logger.info(f"User logged in: {user_info.get('name')} ({user_info.get('login')})")
+    
+    # Redirect to main application
+    return RedirectResponse(url="/", status_code=302)
+
+
+@router.get("/logout")
+async def logout(request: Request):
+    """Log out the current user."""
+    if hasattr(request, "session"):
+        request.session.clear()
+    
+    return RedirectResponse(url="/", status_code=302)
+
+
+@router.get("/user")
+async def get_current_user(request: Request):
+    """Get current user information."""
+    if not should_enable_auth():
+        return {"message": "Authentication disabled in local development"}
+    
+    user = getattr(request.state, "user", None) or request.session.get("user")
+    if not user:
+        raise HTTPException(status_code=401, detail="Not authenticated")
+    
+    # Return user info without sensitive data
+    return {
+        "id": user.get("id"),
+        "name": user.get("name"),
+        "username": user.get("username"),
+        "email": user.get("email"),
+        "avatar_url": user.get("avatar_url"),
+    }
+
+
+@router.get("/login-page")
+async def login_page(request: Request):
+    """
+    Serve a simple login page for environments where auth is required.
+    """
+    if not should_enable_auth():
+        return RedirectResponse(url="/", status_code=302)
+    
+    html_content = """
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <title>AgentGraph - Login Required</title>
+        <style>
+            body { font-family: Arial, sans-serif; text-align: center; margin-top: 100px; }
+            .login-container { max-width: 400px; margin: 0 auto; padding: 20px; border: 1px solid #ddd; border-radius: 8px; }
+            .login-btn { background: #ff6b35; color: white; padding: 12px 24px; text-decoration: none; border-radius: 6px; font-weight: bold; }
+        </style>
+    </head>
+    <body>
+        <div class="login-container">
+            <h1>🕸️ AgentGraph</h1>
+            <p>Please log in with your Hugging Face account to access AgentGraph.</p>
+            <a href="/auth/login" class="login-btn">Login with Hugging Face</a>
+        </div>
+    </body>
+    </html>
+    """
+    
+    return HTMLResponse(content=html_content)

backend/routers/observability.py

@@ -18,6 +18,7 @@ from datetime import datetime
 from typing import Dict, List, Optional, cast
 
 import psutil
+from utils.environment import get_environment_info, debug_environment
 import requests
 from fastapi import APIRouter, Depends, HTTPException
 from fastapi.responses import JSONResponse
@@ -871,6 +872,17 @@ async def clean_up(session: Session = Depends(get_db)):  # noqa: B008
         logger.error(f"Error cleaning up resources: {str(e)}")
         raise HTTPException(status_code=500, detail=f"Error cleaning up resources: {str(e)}") from e
 
+@router.get("/environment")
+async def get_environment():
+    """Get environment information and authentication status."""
+    env_info = get_environment_info()
+    
+    return {
+        "environment": env_info,
+        "timestamp": datetime.now().isoformat()
+    }
+
+
 @router.get("/health-check")
 async def health_check():
     """Comprehensive health check for the system."""

main.py

@@ -10,6 +10,7 @@ from utils.fix_litellm_stop_param import *  # This applies all the patches
 
 # Import configuration and debug utilities
 from utils.config import validate_config, debug_config
+from utils.environment import debug_environment as debug_env_info
 
 # Continue with regular imports
 import argparse
@@ -224,6 +225,7 @@ def main():
     # Debug configuration on startup (but only if not just showing help)
     if len(sys.argv) > 1:
         debug_config()
+        debug_env_info()  # Also show environment info
         if not validate_config():
             logger.error("❌ Configuration validation failed. Please check your environment variables.")
             logger.error("💡 Tip: Copy .env.example to .env and fill in your API keys")

utils/environment.py

@@ -0,0 +1,121 @@
+"""
+Environment Detection Utilities
+
+This module provides utilities to detect the deployment environment
+and configure authentication accordingly.
+"""
+
+import os
+from typing import Dict, Any, Optional
+
+
+def is_huggingface_space() -> bool:
+    """
+    Detect if the application is running in Hugging Face Spaces.
+    
+    Returns:
+        bool: True if running in HF Spaces, False otherwise
+    """
+    # HF Spaces sets specific environment variables
+    hf_indicators = [
+        "SPACE_ID",           # HF Space identifier
+        "SPACE_AUTHOR_NAME",  # Space author
+        "SPACE_REPO_NAME",    # Space repository name
+        "OAUTH_CLIENT_ID",    # OAuth client ID (when oauth enabled)
+    ]
+    
+    return any(os.getenv(indicator) for indicator in hf_indicators)
+
+
+def is_local_development() -> bool:
+    """
+    Detect if the application is running in local development mode.
+    
+    Returns:
+        bool: True if running locally, False otherwise
+    """
+    return not is_huggingface_space()
+
+
+def get_environment_info() -> Dict[str, Any]:
+    """
+    Get comprehensive environment information.
+    
+    Returns:
+        Dict containing environment details
+    """
+    env_info = {
+        "is_hf_space": is_huggingface_space(),
+        "is_local_dev": is_local_development(),
+        "space_id": os.getenv("SPACE_ID"),
+        "space_author": os.getenv("SPACE_AUTHOR_NAME"),
+        "space_repo": os.getenv("SPACE_REPO_NAME"),
+        "oauth_enabled": bool(os.getenv("OAUTH_CLIENT_ID")),
+        "host": os.getenv("HOST", "localhost"),
+        "port": os.getenv("PORT", "7860"),
+    }
+    
+    return env_info
+
+
+def should_enable_auth() -> bool:
+    """
+    Determine if authentication should be enabled based on environment.
+    
+    Returns:
+        bool: True if auth should be enabled, False otherwise
+    """
+    return is_huggingface_space()
+
+
+def get_oauth_config() -> Optional[Dict[str, str]]:
+    """
+    Get OAuth configuration if available.
+    
+    Returns:
+        Dict with OAuth config or None if not available
+    """
+    if not should_enable_auth():
+        return None
+        
+    oauth_config = {
+        "client_id": os.getenv("OAUTH_CLIENT_ID"),
+        "client_secret": os.getenv("OAUTH_CLIENT_SECRET"),
+        "scopes": os.getenv("OAUTH_SCOPES", "openid profile"),
+        "provider_url": os.getenv("OPENID_PROVIDER_URL", "https://huggingface.co"),
+    }
+    
+    # Only return config if client_id is available
+    if oauth_config["client_id"]:
+        return oauth_config
+    
+    return None
+
+
+def debug_environment() -> None:
+    """
+    Print debug information about the current environment.
+    """
+    env_info = get_environment_info()
+    oauth_config = get_oauth_config()
+    
+    print("🌍 Environment Debug Information:")
+    print("=" * 50)
+    print(f"🏗️ Environment Type: {'HF Spaces' if env_info['is_hf_space'] else 'Local Development'}")
+    print(f"🔐 Authentication: {'Enabled' if should_enable_auth() else 'Disabled'}")
+    
+    if env_info['is_hf_space']:
+        print(f"🆔 Space ID: {env_info['space_id']}")
+        print(f"👤 Author: {env_info['space_author']}")
+        print(f"📦 Repo: {env_info['space_repo']}")
+        
+        if oauth_config:
+            print(f"🔑 OAuth Client ID: {oauth_config['client_id'][:8]}..." if oauth_config['client_id'] else "Not set")
+            print(f"🔒 OAuth Scopes: {oauth_config['scopes']}")
+        else:
+            print("❌ OAuth not configured")
+    else:
+        print("🏠 Running in local development mode")
+        print("💡 Authentication will be automatically enabled when deployed to HF Spaces")
+    
+    print("=" * 50)