Add context mode endpoints (fresh vs relevant) and update API documentation

API_DOCUMENTATION.md

@@ -62,7 +62,9 @@ Host: huggingface.co
   "endpoints": {
     "health": "GET /api/health",
     "chat": "POST /api/chat",
-    "initialize": "POST /api/initialize"
+    "initialize": "POST /api/initialize",
+    "context_mode_get": "GET /api/context/mode",
+    "context_mode_set": "POST /api/context/mode"
   }
 }
 ```
@@ -139,6 +141,7 @@ Content-Type: application/json
 | `history` | array | ❌ No | Conversation history as array of `[user, assistant]` pairs |
 | `session_id` | string | ❌ No | Unique session identifier for context continuity |
 | `user_id` | string | ❌ No | User identifier (defaults to "anonymous") |
+| `context_mode` | string | ❌ No | Context retrieval mode: `"fresh"` (no user context) or `"relevant"` (only relevant context). Defaults to `"fresh"` if not set. |
 
 **Response (Success):**
 ```json
@@ -186,6 +189,34 @@ Content-Type: application/json
 }
 ```
 
+**Context Mode Feature:**
+
+The `context_mode` parameter controls how user context is retrieved and used:
+
+- **`"fresh"`** (default): No user context is included. Each conversation starts fresh, ideal for:
+  - General questions requiring no prior context
+  - Avoiding context contamination
+  - Faster responses (no context retrieval overhead)
+
+- **`"relevant"`**: Only relevant user context is included based on relevance classification. The system:
+  - Analyzes all previous interactions for the session
+  - Classifies which interactions are relevant to the current query
+  - Includes only relevant context summaries
+  - Ideal for:
+    - Follow-up questions that build on previous conversations
+    - Maintaining continuity within a research session
+    - Personalized responses based on user history
+
+**Example with Context Mode:**
+```json
+{
+  "message": "Can you remind me what we discussed about quantum computing?",
+  "session_id": "session-123",
+  "user_id": "user-456",
+  "context_mode": "relevant"
+}
+```
+
 ---
 
 ### 4. Initialize Orchestrator
@@ -228,6 +259,132 @@ Content-Type: application/json
 
 ---
 
+### 5. Get Context Mode
+
+**Endpoint:** `GET /api/context/mode`
+
+**Description:** Retrieve the current context retrieval mode for a session.
+
+**Request:**
+```http
+GET /api/context/mode?session_id=session-123 HTTP/1.1
+Host: huggingface.co
+```
+
+**Query Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `session_id` | string | ✅ Yes | Session identifier |
+
+**Response (Success):**
+```json
+{
+  "success": true,
+  "session_id": "session-123",
+  "context_mode": "fresh",
+  "description": {
+    "fresh": "No user context included - starts fresh each time",
+    "relevant": "Only relevant user context included based on relevance classification"
+  }
+}
+```
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | boolean | Whether the request was successful |
+| `session_id` | string | Session identifier |
+| `context_mode` | string | Current mode: `"fresh"` or `"relevant"` |
+| `description` | object | Description of each mode |
+
+**Status Codes:**
+- `200 OK` - Success
+- `400 Bad Request` - Missing `session_id` parameter
+- `500 Internal Server Error` - Server error
+- `503 Service Unavailable` - Orchestrator not ready or context mode not available
+
+**Error Response:**
+```json
+{
+  "success": false,
+  "error": "session_id query parameter is required"
+}
+```
+
+---
+
+### 6. Set Context Mode
+
+**Endpoint:** `POST /api/context/mode`
+
+**Description:** Set the context retrieval mode for a session (fresh or relevant).
+
+**Request Headers:**
+```http
+Content-Type: application/json
+```
+
+**Request Body:**
+```json
+{
+  "session_id": "session-123",
+  "mode": "relevant",
+  "user_id": "user-456"
+}
+```
+
+**Request Fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `session_id` | string | ✅ Yes | Session identifier |
+| `mode` | string | ✅ Yes | Context mode: `"fresh"` or `"relevant"` |
+| `user_id` | string | ❌ No | User identifier (defaults to "anonymous") |
+
+**Response (Success):**
+```json
+{
+  "success": true,
+  "session_id": "session-123",
+  "context_mode": "relevant",
+  "message": "Context mode set successfully"
+}
+```
+
+**Response Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `success` | boolean | Whether the request was successful |
+| `session_id` | string | Session identifier |
+| `context_mode` | string | The mode that was set |
+| `message` | string | Success message |
+
+**Status Codes:**
+- `200 OK` - Context mode set successfully
+- `400 Bad Request` - Invalid request (missing fields, invalid mode)
+- `500 Internal Server Error` - Server error or failed to set mode
+- `503 Service Unavailable` - Orchestrator not ready or context mode not available
+
+**Error Response:**
+```json
+{
+  "success": false,
+  "error": "mode must be 'fresh' or 'relevant'"
+}
+```
+
+**Usage Notes:**
+
+- The context mode persists for the session until changed
+- Setting `mode` to `"relevant"` enables relevance classification, which analyzes all previous interactions to include only relevant context
+- Setting `mode` to `"fresh"` disables context retrieval, providing faster responses without user history
+- The mode can also be set per-request via the `context_mode` parameter in `/api/chat`
+
+---
+
 ## Code Examples
 
 ### Python
@@ -244,13 +401,15 @@ def check_health():
     return response.json()
 
 # Send chat message
-def send_message(message, session_id=None, user_id=None, history=None):
+def send_message(message, session_id=None, user_id=None, history=None, context_mode=None):
     payload = {
         "message": message,
         "session_id": session_id,
         "user_id": user_id or "anonymous",
         "history": history or []
     }
+    if context_mode:
+        payload["context_mode"] = context_mode
     
     response = requests.post(
         f"{BASE_URL}/api/chat",
@@ -280,13 +439,25 @@ if __name__ == "__main__":
         print(f"Response: {result['message']}")
         print(f"Reasoning: {result.get('reasoning', {})}")
         
-        # Continue conversation
+        # Set context mode to relevant for follow-up
+        import requests
+        requests.post(
+            f"{BASE_URL}/api/context/mode",
+            json={
+                "session_id": "my-session-123",
+                "mode": "relevant",
+                "user_id": "user-456"
+            }
+        )
+        
+        # Continue conversation with relevant context
         history = result['history']
         result2 = send_message(
             message="Can you explain neural networks?",
             session_id="my-session-123",
             user_id="user-456",
-            history=history
+            history=history,
+            context_mode="relevant"
         )
         print(f"Follow-up Response: {result2['message']}")
 ```
@@ -302,14 +473,52 @@ async function checkHealth() {
     return await response.json();
 }
 
+// Get context mode for a session
+async function getContextMode(sessionId) {
+    const response = await fetch(`${BASE_URL}/api/context/mode?session_id=${sessionId}`);
+    if (!response.ok) {
+        throw new Error(`API Error: ${response.status}`);
+    }
+    return await response.json();
+}
+
+// Set context mode for a session
+async function setContextMode(sessionId, mode, userId = null) {
+    const payload = {
+        session_id: sessionId,
+        mode: mode
+    };
+    if (userId) {
+        payload.user_id = userId;
+    }
+    
+    const response = await fetch(`${BASE_URL}/api/context/mode`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(payload)
+    });
+    
+    if (!response.ok) {
+        const error = await response.json();
+        throw new Error(`API Error: ${response.status} - ${error.error || error.message}`);
+    }
+    
+    return await response.json();
+}
+
 // Send chat message
-async function sendMessage(message, sessionId = null, userId = null, history = []) {
+async function sendMessage(message, sessionId = null, userId = null, history = [], contextMode = null) {
     const payload = {
         message: message,
         session_id: sessionId,
         user_id: userId || 'anonymous',
         history: history
     };
+    if (contextMode) {
+        payload.context_mode = contextMode;
+    }
     
     const response = await fetch(`${BASE_URL}/api/chat`, {
         method: 'POST',
@@ -345,14 +554,20 @@ async function main() {
             console.log('Response:', result.message);
             console.log('Reasoning:', result.reasoning);
             
-            // Continue conversation
+            // Continue conversation with relevant context
+            await setContextMode('my-session-123', 'relevant', 'user-456');
             const result2 = await sendMessage(
                 'Can you explain neural networks?',
                 'my-session-123',
                 'user-456',
-                result.history
+                result.history,
+                'relevant'
             );
             console.log('Follow-up Response:', result2.message);
+            
+            // Check current context mode
+            const modeInfo = await getContextMode('my-session-123');
+            console.log('Current context mode:', modeInfo.context_mode);
         }
     } catch (error) {
         console.error('Error:', error);
@@ -368,6 +583,18 @@ main();
 # Check health
 curl -X GET "https://jatinautonomouslabs-research-ai-assistant-api.hf.space/api/health"
 
+# Get context mode
+curl -X GET "https://jatinautonomouslabs-research-ai-assistant-api.hf.space/api/context/mode?session_id=my-session-123"
+
+# Set context mode to relevant
+curl -X POST "https://jatinautonomouslabs-research-ai-assistant-api.hf.space/api/context/mode" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "session_id": "my-session-123",
+    "mode": "relevant",
+    "user_id": "user-456"
+  }'
+
 # Send chat message
 curl -X POST "https://jatinautonomouslabs-research-ai-assistant-api.hf.space/api/chat" \
   -H "Content-Type: application/json" \
@@ -375,6 +602,7 @@ curl -X POST "https://jatinautonomouslabs-research-ai-assistant-api.hf.space/api
     "message": "What is machine learning?",
     "session_id": "my-session-123",
     "user_id": "user-456",
+    "context_mode": "relevant",
     "history": []
   }'
 
@@ -404,15 +632,38 @@ async function checkHealth() {
     return response.data;
 }
 
+// Get context mode
+async function getContextMode(sessionId) {
+    const response = await axios.get(`${BASE_URL}/api/context/mode`, {
+        params: { session_id: sessionId }
+    });
+    return response.data;
+}
+
+// Set context mode
+async function setContextMode(sessionId, mode, userId = null) {
+    const payload = {
+        session_id: sessionId,
+        mode: mode
+    };
+    if (userId) payload.user_id = userId;
+    
+    const response = await axios.post(`${BASE_URL}/api/context/mode`, payload);
+    return response.data;
+}
+
 // Send chat message
-async function sendMessage(message, sessionId = null, userId = null, history = []) {
+async function sendMessage(message, sessionId = null, userId = null, history = [], contextMode = null) {
     try {
-        const response = await axios.post(`${BASE_URL}/api/chat`, {
+        const payload = {
             message: message,
             session_id: sessionId,
             user_id: userId || 'anonymous',
             history: history
-        }, {
+        };
+        if (contextMode) payload.context_mode = contextMode;
+        
+        const response = await axios.post(`${BASE_URL}/api/chat`, payload, {
             headers: {
                 'Content-Type': 'application/json'
             }
@@ -434,13 +685,22 @@ async function sendMessage(message, sessionId = null, userId = null, history = [
         console.log('API Status:', health);
         
         if (health.orchestrator_ready) {
+            // Set context mode to relevant
+            await setContextMode('my-session-123', 'relevant', 'user-456');
+            
             const result = await sendMessage(
                 'What is machine learning?',
                 'my-session-123',
-                'user-456'
+                'user-456',
+                [],
+                'relevant'
             );
             
             console.log('Response:', result.message);
+            
+            // Check current mode
+            const modeInfo = await getContextMode('my-session-123');
+            console.log('Context mode:', modeInfo.context_mode);
         }
     } catch (error) {
         console.error('Error:', error.message);

flask_api_standalone.py

@@ -104,7 +104,9 @@ def root():
         'endpoints': {
             'health': 'GET /api/health',
             'chat': 'POST /api/chat',
-            'initialize': 'POST /api/initialize'
+            'initialize': 'POST /api/initialize',
+            'context_mode_get': 'GET /api/context/mode',
+            'context_mode_set': 'POST /api/context/mode'
         }
     })
 
@@ -177,6 +179,7 @@ def chat():
         history = data.get('history', [])
         session_id = data.get('session_id')
         user_id = data.get('user_id', 'anonymous')
+        context_mode = data.get('context_mode')  # Optional: 'fresh' or 'relevant'
         
         logger.info(f"Chat request - User: {user_id}, Session: {session_id}")
         logger.info(f"Message length: {len(message)} chars, preview: {message[:100]}...")
@@ -192,6 +195,14 @@ def chat():
         # Set user_id for session tracking
         if session_id:
             orchestrator.set_user_id(session_id, user_id)
+            
+            # Set context mode if provided
+            if context_mode and hasattr(orchestrator.context_manager, 'set_context_mode'):
+                if context_mode in ['fresh', 'relevant']:
+                    orchestrator.context_manager.set_context_mode(session_id, context_mode, user_id)
+                    logger.info(f"Context mode set to '{context_mode}' for session {session_id}")
+                else:
+                    logger.warning(f"Invalid context_mode '{context_mode}', ignoring. Use 'fresh' or 'relevant'")
         
         # Run async process_request in event loop
         loop = asyncio.new_event_loop()
@@ -253,6 +264,150 @@ def initialize():
             'message': 'Initialization failed. Check logs for details.'
         }), 500
 
+# Context mode management endpoints
+@app.route('/api/context/mode', methods=['GET'])
+def get_context_mode():
+    """
+    Get current context mode for a session
+    
+    GET /api/context/mode?session_id=session-123
+    
+    Returns:
+    {
+        "success": true,
+        "session_id": "session-123",
+        "context_mode": "fresh" | "relevant",
+        "description": {
+            "fresh": "No user context included - starts fresh each time",
+            "relevant": "Only relevant user context included based on relevance classification"
+        }
+    }
+    """
+    try:
+        session_id = request.args.get('session_id')
+        
+        if not session_id:
+            return jsonify({
+                'success': False,
+                'error': 'session_id query parameter is required'
+            }), 400
+        
+        if not orchestrator_available or orchestrator is None:
+            return jsonify({
+                'success': False,
+                'error': 'Orchestrator not ready'
+            }), 503
+        
+        if not hasattr(orchestrator.context_manager, 'get_context_mode'):
+            return jsonify({
+                'success': False,
+                'error': 'Context mode not available'
+            }), 503
+        
+        context_mode = orchestrator.context_manager.get_context_mode(session_id)
+        
+        return jsonify({
+            'success': True,
+            'session_id': session_id,
+            'context_mode': context_mode,
+            'description': {
+                'fresh': 'No user context included - starts fresh each time',
+                'relevant': 'Only relevant user context included based on relevance classification'
+            }
+        })
+        
+    except Exception as e:
+        logger.error(f"Get context mode error: {e}", exc_info=True)
+        return jsonify({
+            'success': False,
+            'error': str(e)
+        }), 500
+
+@app.route('/api/context/mode', methods=['POST'])
+def set_context_mode():
+    """
+    Set context mode for a session
+    
+    POST /api/context/mode
+    {
+        "session_id": "session-123",
+        "mode": "fresh" | "relevant",
+        "user_id": "user-456" (optional)
+    }
+    
+    Returns:
+    {
+        "success": true,
+        "session_id": "session-123",
+        "context_mode": "fresh" | "relevant",
+        "message": "Context mode set successfully"
+    }
+    """
+    try:
+        data = request.get_json()
+        
+        if not data:
+            return jsonify({
+                'success': False,
+                'error': 'Request body is required'
+            }), 400
+        
+        session_id = data.get('session_id')
+        mode = data.get('mode')
+        user_id = data.get('user_id', 'anonymous')
+        
+        if not session_id:
+            return jsonify({
+                'success': False,
+                'error': 'session_id is required'
+            }), 400
+        
+        if not mode:
+            return jsonify({
+                'success': False,
+                'error': 'mode is required'
+            }), 400
+        
+        if mode not in ['fresh', 'relevant']:
+            return jsonify({
+                'success': False,
+                'error': "mode must be 'fresh' or 'relevant'"
+            }), 400
+        
+        if not orchestrator_available or orchestrator is None:
+            return jsonify({
+                'success': False,
+                'error': 'Orchestrator not ready'
+            }), 503
+        
+        if not hasattr(orchestrator.context_manager, 'set_context_mode'):
+            return jsonify({
+                'success': False,
+                'error': 'Context mode not available'
+            }), 503
+        
+        success = orchestrator.context_manager.set_context_mode(session_id, mode, user_id)
+        
+        if success:
+            return jsonify({
+                'success': True,
+                'session_id': session_id,
+                'context_mode': mode,
+                'message': 'Context mode set successfully'
+            })
+        else:
+            return jsonify({
+                'success': False,
+                'error': 'Failed to set context mode'
+            }), 500
+        
+    except Exception as e:
+        logger.error(f"Set context mode error: {e}", exc_info=True)
+        return jsonify({
+            'success': False,
+            'error': str(e)
+        }), 500
+
 # Initialize on startup
 if __name__ == '__main__':
     logger.info("=" * 60)
@@ -270,6 +425,8 @@ if __name__ == '__main__':
     logger.info("  GET  /api/health")
     logger.info("  POST /api/chat")
     logger.info("  POST /api/initialize")
+    logger.info("  GET  /api/context/mode")
+    logger.info("  POST /api/context/mode")
     logger.info("=" * 60)
     
     app.run(