api endpoints for UI migration v11

FLASK_API_SETUP.md

@@ -35,6 +35,14 @@ The Flask API (`flask_api.py`) provides a simple REST API interface to the Resea
 
 ## Quick Start
 
+### Automatic Start (Hugging Face Spaces)
+
+**Flask API starts automatically** when you deploy to HF Spaces using `main.py` as the entry point.
+
+No additional configuration needed - it runs in the background alongside Gradio.
+
+### Manual Start (Local Development)
+
 ### Step 1: Install Dependencies
 
 ```bash
@@ -46,7 +54,7 @@ Or install all requirements:
 pip install -r requirements.txt
 ```
 
-### Step 2: Start Flask API
+### Step 2: Start Flask API (Optional - Only if not using main.py)
 
 ```bash
 # Default port 5001
@@ -56,11 +64,12 @@ python flask_api.py
 FLASK_PORT=5001 python flask_api.py
 ```
 
+**Note:** If using `main.py` (HF Spaces entry point), Flask API starts automatically. Only run `flask_api.py` directly if you want Flask API without Gradio.
+
 You should see:
 ```
-STARTING FLASK API
-INITIALIZING AI ORCHESTRATOR
-✓ AI ORCHESTRATOR READY
+INITIALIZING FLASK API ORCHESTRATOR
+✓ AI ORCHESTRATOR READY (shared with Gradio)
 Starting Flask API on port 5001
 ```
 
@@ -151,9 +160,10 @@ Check if orchestrator is available.
 ### Environment Variables
 
 ```bash
-# Flask configuration
-FLASK_PORT=5001      # Port for Flask API (default: 5001)
-FLASK_HOST=0.0.0.0  # Host to bind to (default: 0.0.0.0)
+# Flask configuration (for HF Spaces or manual start)
+ENABLE_FLASK_API=true   # Enable/disable Flask API (default: true)
+FLASK_PORT=5001          # Port for Flask API (default: 5001)
+FLASK_HOST=0.0.0.0      # Host to bind to (default: 0.0.0.0)
 
 # AI configuration (used by orchestrator)
 HF_TOKEN=your_token_here  # Hugging Face token for API access
@@ -161,21 +171,42 @@ HF_TOKEN=your_token_here  # Hugging Face token for API access
 
 ### Ports
 
-- **Flask API**: 5001 (configurable via `FLASK_PORT`)
+- **Flask API**: 5001 (configurable via `FLASK_PORT`, starts automatically with `main.py`)
 - **Gradio UI**: 7860 (separate, can run alongside)
 - **Express.js** (external): 3000 (your frontend)
 
+### Disable Flask API
+
+To disable Flask API on HF Spaces:
+```bash
+ENABLE_FLASK_API=false
+```
+
+This prevents Flask from starting (only Gradio will run).
+
 ## Running with Gradio
 
-You can run Flask API alongside Gradio:
+### On Hugging Face Spaces (Automatic)
+
+When using `main.py` as the entry point:
+- **Gradio UI**: Runs on port 7860 (primary interface)
+- **Flask API**: Starts automatically in background thread on port 5001
+- Both run together, sharing the same orchestrator instance
+
+### Local Development (Manual)
 
-**Terminal 1: Flask API**
+**Option 1: Use main.py (recommended - matches HF Spaces)**
 ```bash
-python flask_api.py
+python main.py
 ```
+This starts both Gradio and Flask API automatically.
 
-**Terminal 2: Gradio UI (optional)**
+**Option 2: Run separately**
 ```bash
+# Terminal 1: Flask API
+python flask_api.py
+
+# Terminal 2: Gradio UI
 python app.py
 ```
 

flask_api.py

@@ -29,38 +29,45 @@ CORS(app)  # Enable CORS for Express.js and other frontends
 # This imports without triggering Gradio launch
 _orchestrator = None
 _process_message_async = None
+_initialized = False
 
 def initialize_orchestrator():
     """Initialize the orchestrator from app.py"""
-    global _orchestrator, _process_message_async
+    global _orchestrator, _process_message_async, _initialized
+    
+    if _initialized:
+        # Already initialized, return
+        return
     
     try:
         logger.info("=" * 60)
-        logger.info("STARTING FLASK API")
-        logger.info("=" * 60)
-        logger.info("INITIALIZING AI ORCHESTRATOR")
+        logger.info("INITIALIZING FLASK API ORCHESTRATOR")
         logger.info("=" * 60)
         
         # Import from app.py (this won't trigger app.py's launch code)
+        # The orchestrator is already initialized in app.py's module-level code
         from app import orchestrator, process_message_async
         
         _orchestrator = orchestrator
         _process_message_async = process_message_async
         
         if _orchestrator is not None:
-            logger.info("✓ AI ORCHESTRATOR READY")
+            logger.info("✓ AI ORCHESTRATOR READY (shared with Gradio)")
         else:
             logger.warning("⚠ Orchestrator not available - some features may be limited")
         
+        _initialized = True
         logger.info("=" * 60)
         
     except Exception as e:
         logger.error(f"Failed to initialize orchestrator: {e}", exc_info=True)
         _orchestrator = None
         _process_message_async = None
+        _initialized = False
 
-# Initialize on startup
-initialize_orchestrator()
+# Only initialize if running directly (not when imported)
+if __name__ == '__main__':
+    initialize_orchestrator()
 
 @app.route('/health', methods=['GET'])
 def health_check():
@@ -94,6 +101,10 @@ def chat():
         "skills": "..."  // skills HTML
     }
     """
+    # Ensure orchestrator is initialized (should already be from app.py)
+    if not _initialized:
+        initialize_orchestrator()
+    
     try:
         data = request.get_json()
         
@@ -170,13 +181,25 @@ def orchestrator_status():
         'orchestrator_type': type(_orchestrator).__name__ if _orchestrator else None
     })
 
-if __name__ == '__main__':
-    port = int(os.getenv('FLASK_PORT', 5001))
-    host = os.getenv('FLASK_HOST', '0.0.0.0')
+def start_flask_server(host='0.0.0.0', port=5001, debug=False):
+    """
+    Start Flask server (can be called programmatically)
     
-    logger.info(f"Starting Flask API on port {port}")
+    Args:
+        host: Host to bind to (default: 0.0.0.0)
+        port: Port to bind to (default: 5001)
+        debug: Enable debug mode (default: False)
+    """
+    # Initialize orchestrator before starting server
+    initialize_orchestrator()
+    
+    logger.info(f"Starting Flask API on {host}:{port}")
     logger.info(f"Health check: http://{host}:{port}/health")
     logger.info(f"Chat endpoint: http://{host}:{port}/api/chat")
-    
-    app.run(host=host, port=port, debug=False)
+    app.run(host=host, port=port, debug=debug, use_reloader=False)
+
+if __name__ == '__main__':
+    port = int(os.getenv('FLASK_PORT', 5001))
+    host = os.getenv('FLASK_HOST', '0.0.0.0')
+    start_flask_server(host=host, port=port, debug=False)
 

main.py

@@ -1,11 +1,13 @@
 """
 Main integration file for HF Spaces deployment
 Wires together UI, agents, and orchestrator
+Starts Flask API in background thread for external integrations
 """
 
 import gradio as gr
 import logging
 import os
+import threading
 from typing import Dict, Any
 
 # Configure logging
@@ -120,6 +122,51 @@ def create_event_handlers(demo, components):
     
     return get_response_handler
 
+def start_flask_background():
+    """Start Flask API in background thread"""
+    try:
+        # Check if Flask API should be enabled
+        enable_flask = os.getenv('ENABLE_FLASK_API', 'true').lower() == 'true'
+        if not enable_flask:
+            logger.info("Flask API disabled via ENABLE_FLASK_API=false")
+            return None
+        
+        logger.info("Starting Flask API in background thread...")
+        
+        # Import Flask API startup function
+        from flask_api import start_flask_server, initialize_orchestrator
+        
+        # Initialize orchestrator (shared with Gradio)
+        initialize_orchestrator()
+        
+        # Get Flask configuration
+        flask_port = int(os.getenv('FLASK_PORT', 5001))
+        flask_host = os.getenv('FLASK_HOST', '0.0.0.0')
+        
+        # Start Flask in background thread
+        flask_thread = threading.Thread(
+            target=start_flask_server,
+            args=(flask_host, flask_port, False),
+            daemon=True,  # Daemon thread so it stops when main thread stops
+            name="FlaskAPIThread"
+        )
+        flask_thread.start()
+        
+        # Give Flask a moment to start
+        import time
+        time.sleep(2)
+        
+        logger.info(f"✓ Flask API started in background on port {flask_port}")
+        logger.info(f"  Health: http://{flask_host}:{flask_port}/health")
+        logger.info(f"  Chat: http://{flask_host}:{flask_port}/api/chat")
+        
+        return flask_thread
+        
+    except Exception as e:
+        logger.warning(f"Failed to start Flask API: {e}")
+        logger.info("Continuing without Flask API (Gradio will still work)")
+        return None
+
 def main():
     """Main entry point for HF Spaces"""
     logger.info("🚀 Starting AI Research Assistant MVP")
@@ -130,6 +177,9 @@ def main():
     if not hf_token:
         logger.warning("HF_TOKEN not found in environment. Some features may be limited.")
     
+    # Start Flask API in background (for external integrations)
+    flask_thread = start_flask_background()
+    
     # Import the already-configured interface from app.py
     # This imports the interface without triggering app.py's launch code
     # (app.py's launch only runs when app.py is executed directly, not when imported)
@@ -161,6 +211,8 @@ def main():
     
     logger.info("=" * 60)
     logger.info("✅ Application ready for launch")
+    if flask_thread:
+        logger.info("✓ Flask API running in background")
     logger.info("=" * 60)
     return demo.launch(**launch_config)