Fix: Update last_activity only for user messages

- Remove automatic last_activity updates from get_session()
- Add update_activity parameter to update_session()
- Only update last_activity when user messages are added
- Viewing sessions/history no longer updates last_activity
- Ensures session list shows true last interaction time

API_CHANGES_REQUIRED.md

@@ -0,0 +1,555 @@
+# API Response Changes Required
+
+This document outlines **ALL** the changes that need to be made to the MasterLLM API responses based on the corrections defined in `API_RESPONSES_correction.md`.
+
+---
+
+## 1. Session Management APIs
+
+### 1.1 `GET /api/v2/sessions` (with `include_stats=True`)
+
+#### Changes Required:
+
+1. **Sort sessions by `last_activity`** (most recent first)
+   - **Current:** No sorting specified
+   - **Required:** Sessions array must be sorted by `last_activity` in descending order
+
+2. **Update `state` field logic**
+   - **Current:** `"state": "initial"`
+   - **Required:** State should indicate pipeline/conversation status:
+     - `"in_progress"` - if pipeline is currently running
+     - `"completed"` - if pipeline completed successfully
+     - `"initial"` - if no pipeline has been run
+     - `"failed"` - if pipeline failed
+
+3. **Remove `current_file` field**
+   - **Current:** `"current_file": "s3://my-bucket/masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf"`
+   - **Required:** This field is not needed for session list
+
+---
+
+### 1.2 `GET /api/v2/sessions/{session_id}/history`
+
+#### Changes Required:
+
+1. **Add `message_id` to each history item**
+   - **Current:** No `message_id` field
+   - **Required:** Each message in history array needs a unique `message_id`
+   ```json
+   {
+     "message_id": "msg_abc123",
+     "role": "user",
+     "content": "...",
+     ...
+   }
+   ```
+
+2. **Ensure `content` contains only conversation text**
+   - **Current:** Content field is correct
+   - **Required:** Content should NOT contain pipeline output (pipeline output goes in `pipelines_history`)
+
+3. **Standardize file attachment fields**
+   - **Current:** Has both `file_data` object AND separate `file`, `fileName`, `fileUrl` fields
+   - **Required:** Keep both structures for backward compatibility, but ensure consistency:
+     - If `file_data.has_file` is `true`, then `file` must be `true`
+     - `file_url` should be a presigned URL with 7-day validity
+     - If no file, all file-related fields should be `false`/`null`
+
+4. **Update pipeline history - rename `result_preview` to `result`**
+   - **Current:** `"result_preview": "The Q3 report indicates..."`
+   - **Required:** 
+     ```json
+     "result": "The Q3 report indicates a 15% growth in revenue..."
+     ```
+   - **Note:** If pipeline completed successfully, populate with output. If failed/in-progress, set to `null`
+
+5. **Add error handling fields to pipeline history**
+   - **Current:** No error fields
+   - **Required:** Add to each pipeline in `pipelines_history`:
+     ```json
+     {
+       "pipeline_id": "pipe_987654321",
+       "hasError": false,
+       "error": null,
+       ...
+     }
+     ```
+   - If pipeline failed:
+     ```json
+     {
+       "pipeline_id": "pipe_987654321",
+       "hasError": true,
+       "error": {
+         "error_code": "EXTRACTION_FAILED",
+         "message": "Failed to extract text from PDF",
+         "details": "..."
+       },
+       ...
+     }
+     ```
+
+6. **Remove `pipeline_s3_key` from response**
+   - **Current:** `"pipeline_s3_key": "masterllm/pipelines/pipe_987654321.json"`
+   - **Required:** Store internally but don't include in API response
+
+7. **Add component-level details to each component**
+   - **Current:** Components only have basic info
+   - **Required:** Each component needs:
+     ```json
+     {
+       "component_id": "comp_001",
+       "step_id": 1,
+       "tool_name": "extract_text",
+       "description": "Extract text from the PDF",
+       "status": "success",  // or "failed", "running"
+       "component_output": "Extracted text content here...",
+       "hasError": false,
+       "error": null,
+       "metadata": {  // Optional
+         "duration_ms": 1500,
+         "tokens_consumed": 250,
+         "model_used": "claude-3-sonnet"
+       },
+       "parameters": {
+         "file_path": "s3://..."
+       }
+     }
+     ```
+
+---
+
+### 1.3 `GET /api/v2/sessions/{session_id}/pipelines`
+
+#### Changes Required:
+
+1. **Add component details**
+   - **Current:** Only basic pipeline info
+   - **Required:** Include full component data as specified in `/history` endpoint
+   ```json
+   {
+     "pipeline_id": "pipe_987654321",
+     "pipeline_name": "Document Summarization",
+     "status": "completed",
+     "created_at": "2023-11-15T08:31:05Z",
+     "final_output_url": "s3://bucket/results/pipe_987654321_output.json",
+     "components": [
+       {
+         "component_id": "comp_001",
+         "step_id": 1,
+         "tool_name": "extract_text",
+         "status": "success",
+         "component_output": "...",
+         "hasError": false,
+         "error": null,
+         "metadata": { ... },
+         "parameters": { ... }
+       }
+     ]
+   }
+   ```
+
+---
+
+## 2. Unified Chat (Non-Streaming) - `POST /api/v2/chat/unified`
+
+### 2.1 All Scenarios - Add `message_id`
+
+#### Changes Required:
+
+1. **Add `message_id` to assistant responses**
+   - **Current:** No `message_id` field
+   - **Required:** Every response needs a unique message ID
+   ```json
+   {
+     "message_id": "msg_xyz789",
+     "assistant_response": "...",
+     ...
+   }
+   ```
+
+---
+
+### 2.2 Scenario 4: Pipeline Generated (Proposal)
+
+#### Changes Required:
+
+1. **Add `component_id` to each component**
+   - **Current:** Components don't have unique IDs
+   - **Required:**
+   ```json
+   "components": [
+     {
+       "component_id": "comp_001",
+       "tool_name": "extract_text",
+       "args": { "pages": "all" }
+     },
+     {
+       "component_id": "comp_002",
+       "tool_name": "summarize_text",
+       "args": { "style": "brief" }
+     }
+   ]
+   ```
+
+---
+
+### 2.3 Scenario 5: Pipeline Completed (Execution Success)
+
+#### Changes Required:
+
+1. **Add error handling fields**
+   - **Current:** Only has `exception: null`
+   - **Required:** Add `hasError` field
+   ```json
+   {
+     "assistant_response": "🎉 Pipeline completed successfully!",
+     "hasError": false,
+     "exception": null,
+     ...
+   }
+   ```
+
+2. **Add output download capability to `final_output`**
+   - **Current:** Only has text and result
+   - **Required:**
+   ```json
+   "final_output": {
+     "output_id": "output_abc123",
+     "download_url": "https://s3.amazonaws.com/.../output.json?signature=...",
+     "text": "The Q3 financial report highlights...",
+     "result": {
+       "summary": "...",
+       "metadata": { ... }
+     }
+   }
+   ```
+   - **Note:** `download_url` is optional for now; `output_id` is required for separate download endpoint
+
+3. **Remove nested `result` object from `final_output`**
+   - **Current:** Has both `text` and `result` with duplicate data
+   - **Required:** Simplify structure - move result data to component level
+   ```json
+   "final_output": {
+     "output_id": "output_abc123",
+     "download_url": "https://s3.amazonaws.com/.../output.json?signature=...",
+     "text": "The Q3 financial report highlights a strong performance..."
+   }
+   ```
+
+4. **Add component-level details in `api_response.pipeline.components`**
+   - **Current:** Components only have tool names
+   - **Required:** Full component details with status, output, errors
+   ```json
+   "components": [
+     {
+       "component_id": "comp_001",
+       "tool_name": "extract_text",
+       "status": "success",
+       "component_output": "Full extracted text...",
+       "hasError": false,
+       "error": null,
+       "metadata": {
+         "duration_ms": 1200,
+         "tokens_consumed": 300
+       }
+     },
+     {
+       "component_id": "comp_002",
+       "tool_name": "summarize_text",
+       "status": "success",
+       "component_output": "The Q3 financial report highlights...",
+       "hasError": false,
+       "error": null,
+       "metadata": {
+         "duration_ms": 800,
+         "tokens_consumed": 150
+       }
+     }
+   ]
+   ```
+
+---
+
+### 2.4 Scenario 6: Error
+
+#### Changes Required:
+
+1. **Add `hasError` field**
+   - **Current:** Only has `exception`
+   - **Required:**
+   ```json
+   {
+     "assistant_response": "❌ Pipeline execution failed: ValueError: Input file is empty.",
+     "hasError": true,
+     "exception": "ValueError: Input file is empty.",
+     ...
+   }
+   ```
+
+2. **Keep `api_response` format unchanged**
+   - **Note:** Don't change the error response format in `api_response`
+   - **Required:** If error is in a specific component, send error at component level (in component's `error` field)
+
+3. **Component-level error example:**
+   ```json
+   "api_response": {
+     "type": "error",
+     "error_code": "PIPELINE_EXECUTION_FAILED",
+     "message": "Component 'extract_text' failed",
+     "pipeline": {
+       "pipeline_id": "pipe_123abc",
+       "components": [
+         {
+           "component_id": "comp_001",
+           "tool_name": "extract_text",
+           "status": "failed",
+           "hasError": true,
+           "error": {
+             "error_code": "FILE_READ_ERROR",
+             "message": "ValueError: Input file is empty.",
+             "details": "The uploaded PDF file contains no readable content"
+           }
+         }
+       ]
+     }
+   }
+   ```
+
+---
+
+## 3. Workflows APIs
+
+### 3.1 `GET /api/v2/workflows/{workflow_id}`
+
+#### Changes Required:
+
+1. **Add component details to workflow definition**
+   - **Current:** Components only have tool name and args
+   - **Required:** When workflow is executed, include full component details:
+   ```json
+   "definition": {
+     "pipeline_name": "Quarterly Report Analyzer",
+     "components": [
+       {
+         "component_id": "comp_001",
+         "tool_name": "extract_text",
+         "args": {},
+         "status": "success",  // Only if workflow was executed
+         "component_output": "...",  // Only if workflow was executed
+         "hasError": false,
+         "error": null,
+         "metadata": {  // Optional
+           "duration_ms": 1500,
+           "tokens_consumed": 250
+         }
+       }
+     ]
+   }
+   ```
+
+---
+
+## 4. Summary of All Changes by Category
+
+### A. New Fields to Add
+
+| Field | Location | Type | Description |
+|-------|----------|------|-------------|
+| `message_id` | All chat messages | string | Unique identifier for each message |
+| `component_id` | All components | string | Unique identifier for each pipeline component |
+| `hasError` | Pipeline/Component responses | boolean | Indicates if error occurred |
+| `error` | Pipeline/Component responses | object/null | Error details if hasError is true |
+| `status` | Components | string | Component execution status (success/failed/running) |
+| `component_output` | Components | string/object | Output from component execution |
+| `metadata` | Components (optional) | object | Execution metadata (duration, tokens, etc.) |
+| `output_id` | final_output | string | ID for downloading output |
+| `download_url` | final_output (optional) | string | Direct download URL for output |
+
+### B. Fields to Remove/Hide
+
+| Field | Location | Reason |
+|-------|----------|--------|
+| `current_file` | Session list (include_stats=true) | Not needed for session list |
+| `pipeline_s3_key` | Pipeline history | Internal use only, don't expose |
+| Nested `result` in `final_output` | Chat responses | Redundant, move to component level |
+
+### C. Fields to Rename
+
+| Old Name | New Name | Location |
+|----------|----------|----------|
+| `result_preview` | `result` | Pipeline history |
+
+### D. Behavioral Changes
+
+| Change | Location | Description |
+|--------|----------|-------------|
+| Sort by `last_activity` | Session list | Most recent sessions first |
+| Dynamic `state` values | Sessions & pipelines | Reflect actual pipeline status |
+| 7-day presigned URLs | File attachments | Extend URL validity |
+| Component-level errors | Error responses | Show which component failed |
+
+---
+
+## 5. Implementation Priority
+
+### High Priority (Critical for UI)
+
+1. ✅ Add `message_id` to all messages
+2. ✅ Add `component_id` to all components
+3. ✅ Add component `status`, `hasError`, and `error` fields
+4. ✅ Rename `result_preview` to `result`
+5. ✅ Sort sessions by `last_activity`
+6. ✅ Add `output_id` to `final_output`
+
+### Medium Priority (Important for UX)
+
+7. ✅ Add `component_output` to components
+8. ✅ Remove `current_file` from session list
+9. ✅ Remove `pipeline_s3_key` from responses
+10. ✅ Add `download_url` to `final_output`
+11. ✅ Update `state` field logic
+
+### Low Priority (Nice to Have)
+
+12. ✅ Add component `metadata` (duration, tokens, etc.)
+13. ✅ Extend presigned URL validity to 7 days
+
+---
+
+## 6. Code Files to Modify
+
+Based on these changes, the following files will need modifications:
+
+1. **`api_routes_v2.py`** - Update all endpoint response structures
+2. **`session_manager.py`** - Add message_id generation, update session retrieval logic
+3. **`pipeline_executor.py`** - Add component_id, status tracking, error handling
+4. **`schemas.py`** (if exists) - Update Pydantic models for responses
+5. **Database models** - May need to add fields for message_id, component_id, etc.
+
+---
+
+## 7. Testing Checklist
+
+After implementing changes, verify:
+
+- [ ] All messages have unique `message_id`
+- [ ] All components have unique `component_id`
+- [ ] Sessions are sorted by `last_activity` (descending)
+- [ ] `state` field reflects actual pipeline status
+- [ ] `result` field (renamed from `result_preview`) shows correct data
+- [ ] Component errors are properly captured and returned
+- [ ] `hasError` flag is set correctly
+- [ ] `output_id` is generated for completed pipelines
+- [ ] File presigned URLs have 7-day validity
+- [ ] `current_file` is removed from session list
+- [ ] `pipeline_s3_key` is not exposed in responses
+- [ ] Component-level output is captured and returned
+- [ ] Error responses include component-level details
+
+---
+
+## 8. Example: Complete Corrected Response
+
+### `GET /api/v2/sessions/{session_id}/history` (Corrected)
+
+```json
+{
+  "session_id": "550e8400-e29b-41d4-a716-446655440000",
+  "history": [
+    {
+      "message_id": "msg_001",
+      "role": "user",
+      "content": "Uploaded file: report.pdf",
+      "timestamp": "2023-11-15T08:30:00Z",
+      "file_data": {
+        "has_file": true,
+        "file_name": "report.pdf",
+        "file_url": "https://s3.amazonaws.com/bucket/key?signature=..."
+      },
+      "file": true,
+      "fileName": "report.pdf",
+      "fileUrl": "https://s3.amazonaws.com/bucket/key?signature=..."
+    },
+    {
+      "message_id": "msg_002",
+      "role": "assistant",
+      "content": "File uploaded successfully.",
+      "timestamp": "2023-11-15T08:30:05Z",
+      "file_data": {
+        "has_file": false
+      },
+      "file": false,
+      "fileName": null,
+      "fileUrl": null
+    }
+  ],
+  "count": 2,
+  "limit": 50,
+  "chat_name": "Q3 Financial Report Analysis",
+  "pipelines_history": [
+    {
+      "pipeline_id": "pipe_987654321",
+      "pipeline_name": "Document Summarization",
+      "status": "completed",
+      "created_at": "2023-11-15T08:31:05Z",
+      "created_from": "request",
+      "model_provider": "bedrock",
+      "model_name": "anthropic.claude-3-sonnet-20240229-v1:0",
+      "result": "The Q3 report indicates a 15% growth in revenue...",
+      "hasError": false,
+      "error": null,
+      "updated_at": "2023-11-15T08:32:00Z",
+      "tools": ["extract_text", "summarize_text"],
+      "component_count": 2,
+      "components": [
+        {
+          "component_id": "comp_001",
+          "step_id": 1,
+          "tool_name": "extract_text",
+          "description": "Extract text from the PDF",
+          "status": "success",
+          "component_output": "Full extracted text from the PDF document...",
+          "hasError": false,
+          "error": null,
+          "metadata": {
+            "duration_ms": 1200,
+            "tokens_consumed": 300
+          },
+          "parameters": {
+            "file_path": "s3://..."
+          }
+        },
+        {
+          "component_id": "comp_002",
+          "step_id": 2,
+          "tool_name": "summarize_text",
+          "description": "Summarize the extracted content",
+          "status": "success",
+          "component_output": "The Q3 report indicates a 15% growth in revenue...",
+          "hasError": false,
+          "error": null,
+          "metadata": {
+            "duration_ms": 800,
+            "tokens_consumed": 150
+          },
+          "parameters": {
+            "max_length": 500
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## 9. Next Steps
+
+1. Review this document with the development team
+2. Create implementation tasks for each change category
+3. Update API documentation
+4. Implement changes in backend code
+5. Update frontend to consume new response structure
+6. Test all endpoints thoroughly
+7. Deploy and monitor

API_RESPONSES.md

@@ -0,0 +1,750 @@
+# MasterLLM API Response Schemas (Updated)
+
+This document outlines the **ACTUAL** JSON response structures for the `api_routes_v2.py` endpoints after implementing all API response corrections. All fields shown reflect the current implementation.
+
+**Last Updated:** January 3, 2026  
+**Implementation Status:** 100% Complete ✅
+
+---
+
+## 1. Session Management
+
+### `GET /api/v2/sessions`
+
+**Description:** Returns a list of all chat sessions, sorted by `last_activity` (descending).
+
+**Parameters:**
+- `limit` (int, default=100) - Maximum sessions to return
+- `skip` (int, default=0) - Pagination offset
+- `include_stats` (bool, default=False) - Include detailed statistics
+
+**Response (Default - `include_stats=False`):**
+
+```json
+{
+  "sessions": [
+    {
+      "session_id": "550e8400-e29b-41d4-a716-446655440000",
+      "created_at": null,
+      "last_activity": null
+    },
+    {
+      "session_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+      "created_at": null,
+      "last_activity": null
+    }
+  ],
+  "pagination": {
+    "total": 2,
+    "returned": 2,
+    "limit": 100,
+    "skip": 0,
+    "has_more": false
+  }
+}
+```
+
+**Response (with `include_stats=True`):**
+
+```json
+{
+  "sessions": [
+    {
+      "session_id": "550e8400-e29b-41d4-a716-446655440000",
+      "user_id": "user_12345",
+      "created_at": "2023-11-15T08:30:00.000000Z",
+      "last_activity": "2023-11-15T09:45:00.000000Z",
+      "state": "completed",
+      "chat_name": "Q3 Financial Report Analysis",
+      "stats": {
+        "message_count": 12
+      },
+      "total_messages": 12,
+      "pipeline_executions_count": 3
+    }
+  ],
+  "pagination": {
+    "total": 1,
+    "returned": 1,
+    "limit": 100,
+    "skip": 0,
+    "has_more": false
+  }
+}
+```
+
+**Key Changes:**
+- ✅ Sessions sorted by `last_activity` (descending)
+- ✅ `current_file` field removed
+- ✅ `state` reflects actual pipeline/conversation status
+
+---
+
+### `GET /api/v2/sessions/{session_id}/history`
+
+**Description:** Returns the full message history and pipeline history for a specific session.
+
+**Parameters:**
+- `limit` (int, default=50) - Maximum messages to return
+
+**Response:**
+
+```json
+{
+  "session_id": "550e8400-e29b-41d4-a716-446655440000",
+  "history": [
+    {
+      "message_id": "msg_a1b2c3d4e5f6",
+      "role": "user",
+      "content": "Uploaded file: report.pdf",
+      "timestamp": "2023-11-15T08:30:00Z",
+      "file_data": {
+        "has_file": true,
+        "file_name": "report.pdf",
+        "file_url": "https://s3.amazonaws.com/bucket/key?signature=..."
+      },
+      "file": true,
+      "fileName": "report.pdf",
+      "fileUrl": "https://s3.amazonaws.com/bucket/key?signature=..."
+    },
+    {
+      "message_id": "msg_g7h8i9j0k1l2",
+      "role": "assistant",
+      "content": "File uploaded successfully.",
+      "timestamp": "2023-11-15T08:30:05Z",
+      "file_data": {
+        "has_file": false
+      },
+      "file": false,
+      "fileName": null,
+      "fileUrl": null
+    },
+    {
+      "message_id": "msg_m3n4o5p6q7r8",
+      "role": "user",
+      "content": "Summarize this document.",
+      "timestamp": "2023-11-15T08:31:00Z",
+      "file_data": {
+        "has_file": false
+      },
+      "file": false,
+      "fileName": null,
+      "fileUrl": null
+    }
+  ],
+  "count": 3,
+  "limit": 50,
+  "chat_name": "Q3 Financial Report Analysis",
+  "pipelines_history": [
+    {
+      "pipeline_id": "pipe_987654321",
+      "pipeline_name": "Document Summarization",
+      "status": "completed",
+      "created_at": "2023-11-15T08:31:05Z",
+      "created_from": "request",
+      "model_provider": "bedrock",
+      "model_name": "anthropic.claude-3-sonnet-20240229-v1:0",
+      "result": "The Q3 report indicates a 15% growth in revenue...",
+      "hasError": false,
+      "error": null,
+      "updated_at": "2023-11-15T08:32:00Z",
+      "tools": ["extract_text", "summarize_text"],
+      "component_count": 2,
+      "components": [
+        {
+          "component_id": "comp_abc123def456",
+          "component_name": "extract_text",
+          "order": 1,
+          "status": "completed",
+          "started_at": "2023-11-15T08:31:10Z",
+          "completed_at": "2023-11-15T08:31:25Z",
+          "component_output": {
+            "text": "Full extracted text from the PDF...",
+            "pages_processed": 15
+          },
+          "hasError": false,
+          "error": null,
+          "success_message": "Text extraction completed",
+          "metadata": {
+            "duration_ms": 15000,
+            "pages_count": 15
+          }
+        },
+        {
+          "component_id": "comp_ghi789jkl012",
+          "component_name": "summarize_text",
+          "order": 2,
+          "status": "completed",
+          "started_at": "2023-11-15T08:31:26Z",
+          "completed_at": "2023-11-15T08:32:00Z",
+          "component_output": {
+            "summary": "The Q3 report indicates a 15% growth in revenue...",
+            "word_count": 150
+          },
+          "hasError": false,
+          "error": null,
+          "success_message": "Summarization completed",
+          "metadata": {
+            "duration_ms": 34000,
+            "tokens_used": 250
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Key Changes:**
+- ✅ All messages include `message_id`
+- ✅ Pipelines use `result` instead of `result_preview`
+- ✅ `pipeline_s3_key` removed from response
+- ✅ Added `hasError` and structured `error` fields
+- ✅ Components include `component_id`, `status`, `component_output`, `hasError`, `error`, `metadata`
+- ✅ Presigned URLs valid for 7 days
+
+---
+
+### `GET /api/v2/sessions/{session_id}/pipelines`
+
+**Description:** Get all pipeline executions for a session with full component details.
+
+**NEW ENDPOINT** ✨
+
+**Response:**
+
+```json
+{
+  "session_id": "550e8400-e29b-41d4-a716-446655440000",
+  "pipelines": [
+    {
+      "execution_id": "exec_abc123",
+      "pipeline_id": "pipe_987654321",
+      "pipeline_name": "Document Summarization",
+      "status": "completed",
+      "created_at": "2023-11-15T08:31:05Z",
+      "completed_at": "2023-11-15T08:32:00Z",
+      "created_from": "request",
+      "executor": "bedrock",
+      "result": "The Q3 report indicates a 15% growth in revenue...",
+      "hasError": false,
+      "error": null,
+      "output_id": "output_xyz789abc123",
+      "final_output_url": "https://s3.amazonaws.com/bucket/outputs/exec_abc123/final_output.json?signature=...",
+      "final_output_presigned_expires_at": "2023-11-22T08:32:00Z",
+      "components": [
+        {
+          "component_id": "comp_abc123def456",
+          "component_name": "extract_text",
+          "order": 1,
+          "status": "completed",
+          "component_output": {
+            "text": "Full extracted text...",
+            "pages_processed": 15
+          },
+          "hasError": false,
+          "error": null,
+          "metadata": {
+            "duration_ms": 15000
+          }
+        },
+        {
+          "component_id": "comp_ghi789jkl012",
+          "component_name": "summarize_text",
+          "order": 2,
+          "status": "completed",
+          "component_output": {
+            "summary": "The Q3 report indicates...",
+            "word_count": 150
+          },
+          "hasError": false,
+          "error": null,
+          "metadata": {
+            "duration_ms": 34000,
+            "tokens_used": 250
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Key Features:**
+- ✅ Full component details with IDs and outputs
+- ✅ `output_id` for download tracking
+- ✅ `final_output_url` with 7-day validity
+- ✅ Internal S3 keys removed
+- ✅ Component-level error tracking
+
+---
+
+### `DELETE /api/v2/sessions/{session_id}`
+
+**Description:** Deletes a session and its S3 conversation history.
+
+**Response:**
+
+```json
+{
+  "status": "deleted",
+  "session_id": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+---
+
+### `PUT /api/v2/sessions/{session_id}/rename`
+
+**Description:** Renames a session.
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "session_id": "550e8400-e29b-41d4-a716-446655440000",
+  "new_name": "New Chat Title"
+}
+```
+
+---
+
+## 2. Unified Chat (Non-Streaming)
+
+### `POST /api/v2/chat/unified`
+
+**Description:** Main interaction endpoint for chat, pipeline generation, and execution.
+
+#### **Scenario 1: Casual Chat / Question**
+
+**Response:**
+
+```json
+{
+  "message_id": "msg_s9t0u1v2w3x4",
+  "assistant_response": "I am MasterLLM, an advanced AI agent designed to help you process documents.",
+  "output": {},
+  "final_output": null,
+  "hasError": false,
+  "exception": null,
+  "api_response": {
+    "type": "informational_response",
+    "message": "I am MasterLLM, an advanced AI agent designed to help you process documents.",
+    "intent_classification": {
+      "intent": "question",
+      "confidence": 0.98,
+      "requires_pipeline": false
+    }
+  },
+  "intent": {
+    "intent": "question",
+    "confidence": 0.98,
+    "requires_pipeline": false
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "initial",
+  "file": false,
+  "fileName": null,
+  "fileUrl": null
+}
+```
+
+#### **Scenario 2: File Uploaded (Only)**
+
+**Response:**
+
+```json
+{
+  "message_id": "msg_y5z6a7b8c9d0",
+  "assistant_response": "📁 File uploaded successfully. Tell me what you'd like to do with it (e.g., extract text, get tables, summarize).",
+  "output": {},
+  "final_output": null,
+  "hasError": false,
+  "exception": null,
+  "api_response": {
+    "type": "file_uploaded",
+    "file": {
+      "bucket": "my-s3-bucket",
+      "key": "masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf",
+      "s3_uri": "s3://my-s3-bucket/masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf",
+      "presigned_url": "https://s3.amazonaws.com/my-s3-bucket/masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf?signature=...",
+      "presigned_expires_at": "2023-11-22T08:30:00.000000Z"
+    },
+    "next_action": "send_instruction"
+  },
+  "intent": {
+    "intent": "file_uploaded"
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "initial",
+  "file": true,
+  "fileName": "report.pdf",
+  "fileUrl": "https://s3.amazonaws.com/my-s3-bucket/..."
+}
+```
+
+#### **Scenario 3: Pipeline Generated (Proposal)**
+
+**Response:**
+
+```json
+{
+  "message_id": "msg_e1f2g3h4i5j6",
+  "assistant_response": "🎯 **Pipeline Created: Document Summarization**\nHere's what I'll do:\n  1. extract_text\n  2. summarize_text\n**Ready to proceed?**\n- Type 'approve' or 'yes' to execute\n- Type 'reject' or 'no' to cancel\n- Describe changes to modify the plan",
+  "output": {
+    "pipeline_id": "pipe_123abc",
+    "pipeline_name": "Document Summarization",
+    "steps_count": 2,
+    "tools": ["extract_text", "summarize_text"]
+  },
+  "final_output": null,
+  "hasError": false,
+  "exception": null,
+  "api_response": {
+    "type": "pipeline_generated",
+    "message": "Pipeline successfully created",
+    "pipeline": {
+      "pipeline_id": "pipe_123abc",
+      "pipeline_name": "Document Summarization",
+      "session_id": "550e8400-e29b-41d4-a716-446655440000",
+      "created_at": "2023-11-15T08:35:00Z",
+      "_generator": "Claude 3.5 Sonnet",
+      "_model": "claude-3-5-sonnet-20240620",
+      "components": [
+        {
+          "component_id": "comp_k7l8m9n0o1p2",
+          "tool_name": "extract_text",
+          "args": { "pages": "all" }
+        },
+        {
+          "component_id": "comp_q3r4s5t6u7v8",
+          "tool_name": "summarize_text",
+          "args": { "style": "brief" }
+        }
+      ]
+    },
+    "required_action": "approval"
+  },
+  "intent": {
+    "intent": "pipeline_request",
+    "requires_pipeline": true,
+    "confidence": 0.99
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "pipeline_proposed",
+  "file": true,
+  "fileName": "report.pdf",
+  "fileUrl": "https://s3.amazonaws.com/..."
+}
+```
+
+#### **Scenario 4: Pipeline Completed (Execution Success)**
+
+**Response:**
+
+```json
+{
+  "message_id": "msg_w9x0y1z2a3b4",
+  "assistant_response": "🎉 Pipeline completed successfully!",
+  "output": {
+    "component_summary": "Pipeline executed successfully",
+    "steps": 2
+  },
+  "final_output": {
+    "text": "The Q3 financial report highlights a strong performance with a 15% revenue increase driven by the new product line launch. Operating expenses were reduced by 5% due to efficiency improvements. The outlook for Q4 is positive with projected growth of 10%.",
+    "output_id": "output_c5d6e7f8g9h0",
+    "download_url": "https://s3.amazonaws.com/bucket/outputs/exec_abc123/final_output.json?signature=..."
+  },
+  "hasError": false,
+  "exception": null,
+  "api_response": {
+    "type": "pipeline_completed",
+    "result": {
+      "pipeline_id": "pipe_123abc",
+      "status": "completed",
+      "components_executed": [
+        {
+          "component_id": "comp_k7l8m9n0o1p2",
+          "tool_name": "extract_text",
+          "status": "completed",
+          "component_output": {
+            "text": "Full extracted text...",
+            "pages_processed": 15
+          }
+        },
+        {
+          "component_id": "comp_q3r4s5t6u7v8",
+          "tool_name": "summarize_text",
+          "status": "completed",
+          "component_output": {
+            "summary": "The Q3 financial report highlights..."
+          }
+        }
+      ]
+    },
+    "pipeline": {
+      "pipeline_id": "pipe_123abc",
+      "pipeline_name": "Document Summarization",
+      "components": [
+        { "component_id": "comp_k7l8m9n0o1p2", "tool_name": "extract_text" },
+        { "component_id": "comp_q3r4s5t6u7v8", "tool_name": "summarize_text" }
+      ]
+    }
+  },
+  "intent": {
+    "intent": "pipeline_execute"
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "initial",
+  "file": true,
+  "fileName": "report.pdf",
+  "fileUrl": "https://s3.amazonaws.com/..."
+}
+```
+
+**Key Changes:**
+- ✅ `message_id` in all responses
+- ✅ `hasError` flag
+- ✅ `output_id` and `download_url` in `final_output`
+- ✅ Component IDs in pipeline proposals
+- ✅ Removed nested `result` object from `final_output`
+
+#### **Scenario 5: Error**
+
+**Response:**
+
+```json
+{
+  "message_id": "msg_i1j2k3l4m5n6",
+  "assistant_response": "❌ Pipeline execution failed: ValueError: Input file is empty.",
+  "output": {},
+  "final_output": null,
+  "hasError": true,
+  "exception": "ValueError: Input file is empty.",
+  "api_response": {
+    "type": "error",
+    "error_code": "PIPELINE_EXECUTION_FAILED",
+    "message": "ValueError: Input file is empty.",
+    "failed_component": {
+      "component_id": "comp_k7l8m9n0o1p2",
+      "tool_name": "extract_text",
+      "error": {
+        "message": "ValueError: Input file is empty.",
+        "error_code": "FILE_READ_ERROR"
+      }
+    }
+  },
+  "intent": {
+    "intent": "pipeline_execute"
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "initial",
+  "file": true,
+  "fileName": "report.pdf",
+  "fileUrl": "https://s3.amazonaws.com/..."
+}
+```
+
+**Key Changes:**
+- ✅ `hasError` set to `true`
+- ✅ Component-level error details in `failed_component`
+- ✅ Structured error with `error_code` and `message`
+
+---
+
+## 3. Unified Chat (Streaming)
+
+### `POST /api/v2/chat/unified/stream`
+
+**Description:** Streaming version of the unified chat. Returns **NDJSON** (Newlines Delimited JSON).
+
+**Event Type: `status`**
+
+```json
+{
+  "type": "status",
+  "message": "Analyzing request and creating a pipeline...",
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "initial"
+}
+```
+
+**Event Type: `assistant_final` (Typical Chat Response)**
+
+```json
+{
+  "type": "assistant_final",
+  "content": "Hello! How can I help you today?",
+  "intent": {
+    "intent": "casual_chat",
+    "confidence": 0.99
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "initial"
+}
+```
+
+**Event Type: `assistant_final` (Execution Completed)**
+
+```json
+{
+  "type": "assistant_final",
+  "content": "🎉 Pipeline Completed Successfully!\n- Pipeline: Document Summarization\n- Total Steps: 2\n- Successful: 2\n- Executor: Bedrock Agent\n\nThe Q3 financial report highlights...",
+  "result": {
+    "summary": "The Q3 financial report highlights...",
+    "full_text": "..."
+  },
+  "output": {
+    "component_summary": "Executed 2 steps successfully",
+    "steps_completed": 2,
+    "total_steps": 2
+  },
+  "final_output": {
+    "text": "The Q3 financial report highlights...",
+    "output_id": "output_o9p0q1r2s3t4",
+    "download_url": "https://s3.amazonaws.com/..."
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "initial"
+}
+```
+
+---
+
+## 4. File Management
+
+### `POST /api/v2/chats/{chat_id}/upload`
+
+**Description:** Direct file upload endpoint.
+
+**Response:**
+
+```json
+{
+  "status": "success",
+  "message": "File uploaded to S3",
+  "file": {
+    "bucket": "my-s3-bucket",
+    "key": "masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf",
+    "s3_uri": "s3://my-s3-bucket/masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf",
+    "presigned_url": "https://s3.amazonaws.com/my-s3-bucket/masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf?signature=...",
+    "presigned_expires_at": "2023-11-22T08:30:00.000000Z"
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "next_action": "💬 Now tell me what you'd like to do with this document"
+}
+```
+
+**Key Changes:**
+- ✅ Presigned URLs valid for 7 days
+
+---
+
+## 5. System
+
+### `POST /api/v2/chats`
+
+**Description:** Create a new empty chat session.
+
+**Response:**
+
+```json
+{
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+### `GET /api/v2/health`
+
+**Description:** Health check.
+
+**Response:**
+
+```json
+{
+  "status": "ok",
+  "service": "MasterLLM v2.0",
+  "time": "2023-11-15T08:30:00.000000Z"
+}
+```
+
+---
+
+## Summary of Changes
+
+### ✅ New Fields Added
+- `message_id` - Unique identifier for all messages (format: `msg_xxxxxxxxxxxx`)
+- `component_id` - Unique identifier for pipeline components (format: `comp_xxxxxxxxxxxx`)
+- `output_id` - Unique identifier for pipeline outputs (format: `output_xxxxxxxxxxxx`)
+- `hasError` - Boolean flag for error detection
+- `error` - Structured error object with `message`, `error_code`, `details`
+- `component_output` - Actual output from component execution
+- `download_url` - Direct download URL for pipeline results
+- `failed_component` - Component-level error details in error responses
+- `metadata` - Component execution metadata (duration, tokens, etc.)
+
+### ✅ Fields Renamed
+- `result_preview` → `result`
+
+### ✅ Fields Removed
+- `current_file` (from session list response)
+- `pipeline_s3_key` (internal field, not exposed in API)
+- Nested `result` object in `final_output` (simplified structure)
+
+### ✅ New Endpoints
+- `GET /api/v2/sessions/{session_id}/pipelines` - Get all pipelines for a session
+
+### ✅ Behavioral Changes
+- Sessions sorted by `last_activity` (descending)
+- Presigned URLs valid for 7 days (604800 seconds)
+- Component-level error tracking and reporting
+- State field dynamically reflects pipeline/conversation status
+
+---
+
+## ID Formats
+
+All IDs follow consistent formats for easy identification:
+
+- **Message IDs:** `msg_xxxxxxxxxxxx` (12 hex characters)
+- **Component IDs:** `comp_xxxxxxxxxxxx` (12 hex characters)
+- **Output IDs:** `output_xxxxxxxxxxxx` (12 hex characters)
+- **Session IDs:** Standard UUID v4 format
+- **Pipeline IDs:** `pipe_` prefix or UUID format
+
+---
+
+## Error Handling
+
+All error responses now include:
+
+1. **Top-level `hasError` flag** - Quick error detection
+2. **Structured `error` object** - Detailed error information
+3. **Component-level errors** - Identify which component failed
+4. **Error codes** - Machine-readable error classification
+
+Example error structure:
+```json
+{
+  "hasError": true,
+  "error": {
+    "message": "Detailed error message",
+    "error_code": "ERROR_TYPE",
+    "details": {
+      "additional": "context"
+    }
+  },
+  "failed_component": {
+    "component_id": "comp_xxxxxxxxxxxx",
+    "tool_name": "tool_name",
+    "error": {...}
+  }
+}
+```
+
+---
+
+**Document Version:** 2.0  
+**Implementation Date:** January 3, 2026  
+**Status:** Production Ready ✅

API_RESPONSES_correction.md

@@ -0,0 +1,763 @@
+# MasterLLM API Response Schemas
+
+This document outlines the COMPLETE JSON response structures for the `api_routes_v2.py` endpoints. All fields are shown with example data.
+
+## 1. **Session Management**
+
+### `GET /api/v2/sessions`
+
+**Description:** Returns a list of all chat sessions.
+**Parameters:** `limit` (int, default=100), `skip` (int, default=0), `include_stats` (bool, default=False)
+
+**Response (Default - `include_stats=False`):**
+
+```json
+{
+  "sessions": [
+    {
+      "session_id": "550e8400-e29b-41d4-a716-446655440000",
+      "created_at": null,
+      "last_activity": null
+    },
+    {
+      "session_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
+      "created_at": null,
+      "last_activity": null
+    }
+  ],
+  "pagination": {
+    "total": 2,
+    "returned": 2,
+    "limit": 100,
+    "skip": 0,
+    "has_more": false
+  }
+}
+```
+
+**Response (with `include_stats=True`):**
+
+```json
+{
+  // The sessions needs to be sorted according to the last activity. The latest should come first key is last_activity
+  "sessions": [
+    {
+      "session_id": "550e8400-e29b-41d4-a716-446655440000",
+      "user_id": "user_12345",
+      "created_at": "2023-11-15T08:30:00.000000Z",
+      "last_activity": "2023-11-15T09:45:00.000000Z",
+      // state should indicate the status of the pipeline or the conversation. If the pipeline is in pogress it should be in pogress if not then completed, initial, or failed
+      "state": "initial",
+      // current_file is not needed for session list
+      "current_file": "s3://my-bucket/masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf",
+      "chat_name": "Q3 Financial Report Analysis",
+      "stats": {
+        "tokens_used": 1500,
+        "cost_estimate": 0.045
+      },
+      "total_messages": 12,
+      "pipeline_executions_count": 3
+    }
+  ],
+  "pagination": {
+    "total": 1,
+    "returned": 1,
+    "limit": 100,
+    "skip": 0,
+    "has_more": false
+  }
+}
+```
+
+### `GET /api/v2/sessions/{session_id}/history`
+
+**Description:** Returns the full message history and pipeline history for a specific session.
+**Parameters:** `limit` (int, default=50)
+
+**Response:**
+
+```json
+{
+  "session_id": "550e8400-e29b-41d4-a716-446655440000",
+  // This is the history of msg and chats
+  "history": [
+    {
+      // Need message_id
+      "role": "user",
+      // content should always have basic conversation content, it should not have the output of the pipeline
+      "content": "Uploaded file: report.pdf",
+      "timestamp": "2023-11-15T08:30:00Z",
+      "file_data": {
+        "has_file": true,
+        "file_name": "report.pdf",
+        "file_url": "https://s3.amazonaws.com/bucket/key?signature=..."
+      },
+      // This should be proper, like if file was attached to this particular msg then true with file details like a presigned url with a validity of 7 days.
+      // If Not then file should be false
+      "file": true,
+      "fileName": "report.pdf",
+      "fileUrl": "https://s3.amazonaws.com/bucket/key?signature=..."
+    },
+    {
+      "role": "assistant",
+      "content": "File uploaded successfully.",
+      "timestamp": "2023-11-15T08:30:05Z",
+      "file_data": {
+        "has_file": false
+      },
+      "file": false,
+      "fileName": null,
+      "fileUrl": null
+    },
+    {
+      "role": "user",
+      "content": "Summarize this document.",
+      "timestamp": "2023-11-15T08:31:00Z",
+      "file_data": {
+        "has_file": false
+      },
+      "file": false,
+      "fileName": null,
+      "fileUrl": null
+    }
+  ],
+  "count": 3,
+  "limit": 50,
+  "chat_name": "Q3 Financial Report Analysis",
+  "pipelines_history": [
+    {
+      "pipeline_id": "pipe_987654321",
+      "pipeline_name": "Document Summarization",
+      // status should indicate the state of the pipeline, if success then completed, if not failed or in pogress.
+      "status": "completed",
+      "created_at": "2023-11-15T08:31:05Z",
+      "created_from": "request",
+      "model_provider": "bedrock",
+      "model_name": "anthropic.claude-3-sonnet-20240229-v1:0",
+      // No need for pipeline_s3_key store it but dont need in the output,
+      "pipeline_s3_key": "masterllm/pipelines/pipe_987654321.json",
+      // result_preview should be named as result. And in here if the pipeline has completed with success the output should be provided, if not or failed this should be null.
+      "result_preview": "The Q3 report indicates a 15% growth in revenue...",
+      // Please add another key called hasError, and error details where if the pipeline is failed or has error the error should be provided. If the pipeline is passed then this will be null and hasError false.
+      "updated_at": "2023-11-15T08:32:00Z",
+      "tools": ["extract_text", "summarize_text"],
+      "component_count": 2,
+      "components": [
+        {
+          // Please provide a component ID to unique identify each
+          // Please provide the status of each component, like status: success, failed, or running
+          // If success send the result of this component run. like component_output: This will have the output of the component
+          // Please send hasError, and error details where if the component is failed or has error the error should be provided. If the component is passed then this will be null and hasError false
+          // Send the component meta data if present like the duration run, token consumed, etc (This is optional)
+          "step_id": 1,
+          "tool_name": "extract_text",
+          "description": "Extract text from the PDF",
+          "parameters": {
+            "file_path": "s3://..."
+          }
+        },
+        {
+          "step_id": 2,
+          "tool_name": "summarize_text",
+          "description": "Summarize the extracted content",
+          "parameters": {
+            "max_length": 500
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+### `DELETE /api/v2/sessions/{session_id}`
+
+**Description:** Deletes a session and its S3 conversation history.
+
+**Response:**
+
+```json
+{
+  "status": "deleted",
+  "session_id": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+### `PUT /api/v2/sessions/{session_id}/rename`
+
+**Description:** Renames a session.
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "session_id": "550e8400-e29b-41d4-a716-446655440000",
+  "new_name": "New Chat Title"
+}
+```
+
+### `GET /api/v2/sessions/{session_id}/pipelines`
+
+**Description:** Get all pipeline executions for a session.
+
+**Response:**
+
+```json
+{
+  "session_id": "550e8400-e29b-41d4-a716-446655440000",
+  "pipelines": [
+    {
+      "pipeline_id": "pipe_987654321",
+      "pipeline_name": "Document Summarization",
+      "status": "completed",
+      "created_at": "2023-11-15T08:31:05Z",
+      "final_output_url": "s3://bucket/results/pipe_987654321_output.json"
+      // Please also send the components and its data as you are / will be sending in the `GET /api/v2/sessions/{session_id}/history`
+    }
+  ]
+}
+```
+
+---
+
+## 2. **Unified Chat (Non-Streaming)**
+
+### `POST /api/v2/chat/unified`
+
+**Description:** Main interaction endpoint.
+
+#### **Scenario 1: Casual Chat / Question**
+
+**Response:**
+
+```json
+{
+  // This should also have the message id, as this is a msg from the LLM
+  "assistant_response": "I am MasterLLM, an advanced AI agent designed to help you process documents.",
+  "output": {},
+  "final_output": null,
+  "exception": null,
+  "api_response": {
+    "type": "informational_response",
+    "message": "I am MasterLLM, an advanced AI agent designed to help you process documents.",
+    "intent_classification": {
+      "intent": "question",
+      "confidence": 0.98,
+      "requires_pipeline": false
+    }
+  },
+  "intent": {
+    "intent": "question",
+    "confidence": 0.98,
+    "requires_pipeline": false
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "initial",
+  "file": false,
+  "fileName": null,
+  "fileUrl": null
+}
+```
+
+#### **Scenario 2: Clarification Needed**
+
+**Response:**
+
+```json
+{
+  // This should also have the message id, as this is a msg from the LLM
+  "assistant_response": "I'm not sure what you mean by 'do it'. Could you please specify if you want to summarize, extract text, or translate the document?",
+  "output": {},
+  "final_output": null,
+  "exception": null,
+  "api_response": {
+    "type": "clarification_needed",
+    "message": "I'm not sure what you mean by 'do it'. Could you please specify if you want to summarize, extract text, or translate the document?",
+    "intent_classification": {
+      "intent": "unclear",
+      "confidence": 0.45,
+      "requires_pipeline": false
+    },
+    "suggestions": [
+      "Be more specific about what you want to do",
+      "Use keywords like: extract, summarize, translate, etc.",
+      "Type 'help' for examples"
+    ]
+  },
+  "intent": {
+    "intent": "unclear",
+    "confidence": 0.45,
+    "requires_pipeline": false
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "initial",
+  "file": true,
+  "fileName": "report.pdf",
+  "fileUrl": "https://s3.amazonaws.com/..."
+}
+```
+
+#### **Scenario 3: File Uploaded (Only)**
+
+**Response:**
+
+```json
+{
+  // This should also have the message id, as this is a msg from the LLM
+  "assistant_response": "📁 File uploaded successfully. Tell me what you'd like to do with it (e.g., extract text, get tables, summarize).",
+  "output": {},
+  "final_output": null,
+  "exception": null,
+  "api_response": {
+    "type": "file_uploaded",
+    "file": {
+      "bucket": "my-s3-bucket",
+      "key": "masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf",
+      "s3_uri": "s3://my-s3-bucket/masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf",
+      "presigned_url": "https://s3.amazonaws.com/my-s3-bucket/masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf?AMAZONPARAMS...",
+      "presigned_expires_at": "2023-11-22T08:30:00.000000Z"
+    },
+    "next_action": "send_instruction"
+  },
+  "intent": {
+    "intent": "file_uploaded"
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "initial",
+  "file": true,
+  "fileName": "report.pdf",
+  "fileUrl": "https://s3.amazonaws.com/my-s3-bucket/..."
+}
+```
+
+#### **Scenario 4: Pipeline Generated (Proposal)**
+
+**Response:**
+
+```json
+{
+  // This should also have the message id, as this is a msg from the LLM
+  "assistant_response": "🎯 **Pipeline Created: Document Summarization**\nHere's what I'll do:\n  1. extract_text\n  2. summarize_text\n**Ready to proceed?**\n- Type 'approve' or 'yes' to execute\n- Type 'reject' or 'no' to cancel\n- Describe changes to modify the plan",
+  "output": {
+    "pipeline_id": "pipe_123abc",
+    "pipeline_name": "Document Summarization",
+    "steps_count": 2,
+    "tools": ["extract_text", "summarize_text"]
+  },
+  "final_output": null,
+  "exception": null,
+  "api_response": {
+    "type": "pipeline_generated",
+    "message": "Pipeline successfully created",
+    "pipeline": {
+      "pipeline_id": "pipe_123abc",
+      "pipeline_name": "Document Summarization",
+      "session_id": "550e8400-e29b-41d4-a716-446655440000",
+      "created_at": "2023-11-15T08:35:00Z",
+      "_generator": "Claude 3.5 Sonnet",
+      "_model": "claude-3-5-sonnet-20240620",
+      // Please provide a component ID to unique identify each
+      "components": [
+        {
+          "tool_name": "extract_text",
+          "args": { "pages": "all" }
+        },
+        {
+          "tool_name": "summarize_text",
+          "args": { "style": "brief" }
+        }
+      ],
+      "pipeline_steps": [
+        {
+          "tool_name": "extract_text",
+          "args": { "pages": "all" }
+        },
+        {
+          "tool_name": "summarize_text",
+          "args": { "style": "brief" }
+        }
+      ]
+    },
+    "pipeline_summary": {
+      "name": "Document Summarization",
+      "total_steps": 2,
+      "steps": [
+        {
+          "tool_name": "extract_text",
+          "args": { "pages": "all" }
+        },
+        {
+          "tool_name": "summarize_text",
+          "args": { "style": "brief" }
+        }
+      ],
+      "generator": "Claude 3.5 Sonnet",
+      "model": "claude-3-5-sonnet-20240620"
+    },
+    "required_action": "approval",
+    "next_steps": {
+      "approve": "Type 'approve' or 'yes'",
+      "reject": "Type 'reject' or 'no'",
+      "modify": "Describe your changes"
+    }
+  },
+  "intent": {
+    "intent": "pipeline_request",
+    "requires_pipeline": true,
+    "confidence": 0.99
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "pipeline_proposed",
+  "file": true,
+  "fileName": "report.pdf",
+  "fileUrl": "https://s3.amazonaws.com/..."
+}
+```
+
+#### **Scenario 5: Pipeline Completed (Execution Success)**
+
+**Response:**
+
+```json
+{
+  // This should also have the message id, as this is a msg from the LLM
+  "assistant_response": "🎉 Pipeline completed successfully!",
+  // send hasError, if it has then the error should be provide in the exception if not this will be null and hasError will be false
+  "output": {
+    "component_summary": "Pipeline executed successfully",
+    "steps": 2
+  },
+  // final_output should have data only if the LLM has run the pipeline and completed with success. Then populate the final output here
+  "final_output": {
+    // Please add output id for which the user can download the output if he wants. The output id will be used to downalod using a separate endpoint.
+    // Optional: check if you can send the download url in here as well for downalod output. if not the output id will work as of now.
+    "text": "The Q3 financial report highlights a strong performance with a 15% revenue increase driven by the new product line launch. Operating expenses were reduced by 5% due to efficiency improvements. The outlook for Q4 is positive with projected growth of 10%.",
+
+    // This result is not needed as this should be in the component level
+    "result": {
+      "summary": "The Q3 financial report highlights a strong performance with a 15% revenue increase driven by the new product line launch. Operating expenses were reduced by 5% due to efficiency improvements. The outlook for Q4 is positive with projected growth of 10%.",
+      "metadata": {
+        "source_file": "report.pdf",
+        "processed_at": "2023-11-15T08:36:00Z"
+      }
+    }
+  },
+  "exception": null,
+  "api_response": {
+    "type": "pipeline_completed",
+    "result": {
+      "summary": "The Q3 financial report highlights a strong performance with a 15% revenue increase driven by the new product line launch. Operating expenses were reduced by 5% due to efficiency improvements. The outlook for Q4 is positive with projected growth of 10%.",
+      "metadata": {
+        "source_file": "report.pdf",
+        "processed_at": "2023-11-15T08:36:00Z"
+      }
+    },
+    "pipeline": {
+      "pipeline_id": "pipe_123abc",
+      "pipeline_name": "Document Summarization",
+      // Please provide a component ID to unique identify each
+      // Please provide the status of each component, like status: success, failed, or running
+      // If success send the result of this component run. like component_output: This will have the output of the component
+      // Please send hasError, and error details where if the component is failed or has error the error should be provided. If the component is passed then this will be null and hasError false
+      // Send the component meta data if present like the duration run, token consumed, etc (This is optional)
+      "components": [
+        { "tool_name": "extract_text" },
+        { "tool_name": "summarize_text" }
+      ]
+    }
+  },
+  "intent": {
+    "intent": "pipeline_execute"
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "initial",
+  "file": true,
+  "fileName": "report.pdf",
+  "fileUrl": "https://s3.amazonaws.com/..."
+}
+```
+
+#### **Scenario 6: Error**
+
+**Response:**
+
+```json
+{
+  // This should also have the message id, as this is a msg from the LLM
+  "assistant_response": "❌ Pipeline execution failed: ValueError: Input file is empty.",
+  "output": {},
+  "final_output": null,
+  // send hasError, if it has then the error should be provide in the exception if not this will be null and hasError will be false
+  "exception": "ValueError: Input file is empty.",
+  "api_response": {
+    // Dont change the api_response format, keep it same
+    // If the error is in a particular component then send error in the component level
+    "type": "error",
+    "error_code": "PIPELINE_EXECUTION_FAILED",
+    "message": "ValueError: Input file is empty."
+  },
+  "intent": {
+    "intent": "pipeline_execute"
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "initial",
+  "file": true,
+  "fileName": "report.pdf",
+  "fileUrl": "https://s3.amazonaws.com/..."
+}
+```
+
+---
+
+## 3. **Unified Chat (Streaming)**
+
+### `POST /api/v2/chat/unified/stream`
+
+**Description:** Streaming version of the unified chat. Returns **NDJSON** (Newlines Delimited JSON). Each line is a JSON object.
+
+**Event Type: `status`**
+
+```json
+{
+  "type": "status",
+  "message": "Analyzing request and creating a pipeline...",
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "initial"
+}
+```
+
+**Event Type: `assistant_final` (Typical Chat Response)**
+
+```json
+{
+  "type": "assistant_final",
+  "content": "Hello! How can I help you today?",
+  "intent": {
+    "intent": "casual_chat",
+    "confidence": 0.99
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "initial"
+}
+```
+
+**Event Type: `assistant_final` (Pipeline Proposed)**
+
+```json
+{
+  "type": "assistant_final",
+  "content": "🎯 **Pipeline Created: Document Summarization**\nHere's what I'll do:\n  1. extract_text\n  2. summarize_text\n...",
+  "pipeline": {
+    "pipeline_id": "pipe_123abc",
+    "pipeline_name": "Document Summarization",
+    "components": [
+      { "tool_name": "extract_text" },
+      { "tool_name": "summarize_text" }
+    ]
+  },
+  "output": {
+    "pipeline_id": "pipe_123abc",
+    "pipeline_name": "Document Summarization",
+    "steps_count": 2,
+    "tools": ["extract_text", "summarize_text"]
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "pipeline_proposed"
+}
+```
+
+**Event Type: `assistant_delta` (Streaming Execution Output)**
+
+```json
+{
+  "type": "assistant_delta",
+  "content": "✅ Approved! Starting execution of: **Document Summarization**\n\n🚀 Processing, please wait...\n\n⏳ Step 1: extract_text - Processing...",
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "executing"
+}
+```
+
+**Event Type: `assistant_final` (Execution Completed)**
+
+```json
+{
+  "type": "assistant_final",
+  "content": "🎉 Pipeline Completed Successfully!\n- Pipeline: Document Summarization\n- Total Steps: 2\n- Successful: 2\n- Executor: Bedrock Agent\n\nThe Q3 financial report highlights...",
+  "result": {
+    "summary": "The Q3 financial report highlights...",
+    "full_text": "..."
+  },
+  "output": {
+    "component_summary": "Executed 2 steps successfully",
+    "steps_completed": 2,
+    "total_steps": 2
+  },
+  "final_output": {
+    "text": "The Q3 financial report highlights...",
+    "result": {
+      "summary": "The Q3 financial report highlights...",
+      "full_text": "..."
+    }
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "initial"
+}
+```
+
+**Event Type: `assistant_final` (Error)**
+
+```json
+{
+  "type": "assistant_final",
+  "content": "❌ Pipeline Execution Failed\n\nError: Service Unavailable",
+  "error": "Service Unavailable",
+  "exception": "Service Unavailable",
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "state": "initial"
+}
+```
+
+---
+
+## 4. **File Management**
+
+### `POST /api/v2/chats/{chat_id}/upload`
+
+**Description:** Direct file upload endpoint.
+
+**Response:**
+
+```json
+{
+  "status": "success",
+  "message": "File uploaded to S3",
+  "file": {
+    "bucket": "my-s3-bucket",
+    "key": "masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf",
+    "s3_uri": "s3://my-s3-bucket/masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf",
+    "presigned_url": "https://s3.amazonaws.com/my-s3-bucket/masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf?AMAZONPARAMS...",
+    "presigned_expires_at": "2023-11-22T08:30:00.000000Z"
+  },
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000",
+  "next_action": "💬 Now tell me what you'd like to do with this document"
+}
+```
+
+### `GET /api/v2/files/{file_id}/url`
+
+**Description:** Regenerate a temporary presigned URL for a file.
+
+**Response:**
+
+```json
+{
+  "file_id": "masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf",
+  "presigned_url": "https://s3.amazonaws.com/my-s3-bucket/masterllm/550e8400-e29b-41d4-a716-446655440000/report.pdf?AMAZONPARAMS...",
+  "expires_at": "2023-11-23T08:30:00.000000Z"
+}
+```
+
+---
+
+## 5. **Workflows**
+
+### `GET /api/v2/workflows`
+
+**Description:** List saved workflows.
+
+**Response:**
+
+```json
+{
+  "workflows": [
+    {
+      "workflow_id": "flow_888",
+      "name": "Quarterly Report Analyzer",
+      "created_at": "2023-10-01T12:00:00Z",
+      "last_used": "2023-11-01T10:00:00Z",
+      "steps_count": 3
+    }
+  ],
+  "count": 1,
+  "total": 1
+}
+```
+
+### `GET /api/v2/workflows/{workflow_id}`
+
+**Description:** Get a single workflow definition.
+
+**Response:**
+
+```json
+{
+  "workflow_id": "flow_888",
+  "name": "Quarterly Report Analyzer",
+  "description": "Extracts text, summarizes key points, and extracts financial tables.",
+  "created_at": "2023-10-01T12:00:00Z",
+  "updated_at": "2023-10-05T09:00:00Z",
+  "definition": {
+    "pipeline_name": "Quarterly Report Analyzer",
+    // Please provide a component ID to unique identify each
+    // Please provide the status of each component, like status: success, failed, or running
+    // If success send the result of this component run. like component_output: This will have the output of the component
+    // Please send hasError, and error details where if the component is failed or has error the error should be provided. If the component is passed then this will be null and hasError false
+    // Send the component meta data if present like the duration run, token consumed, etc (This is optional)
+    "components": [
+      { "tool_name": "extract_text", "args": {} },
+      { "tool_name": "summarize", "args": { "focus": "financials" } },
+      { "tool_name": "extract_tables", "args": {} }
+    ]
+  },
+  "source_pipeline_id": "pipe_old_123",
+  "usage_count": 15
+}
+```
+
+### `POST /api/v2/workflows/save`
+
+**Description:** Save an existing pipeline as a reusable workflow.
+**Parameters:** `pipeline_id` (form), `workflow_name` (form, optional)
+
+**Response:**
+
+```json
+{
+  "workflow_id": "flow_999",
+  "pipeline_name": "New Saved Workflow",
+  "source_pipeline_id": "pipe_123abc",
+  "pipeline_status": "completed",
+  "message": "Workflow saved successfully"
+}
+```
+
+---
+
+## 6. **System**
+
+### `POST /api/v2/chats`
+
+**Description:** Create a new empty chat session.
+
+**Response:**
+
+```json
+{
+  "chat_id": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+### `GET /api/v2/health`
+
+**Description:** Health check.
+
+**Response:**
+
+```json
+{
+  "status": "ok",
+  "service": "MasterLLM v2.0",
+  "time": "2023-11-15T08:30:00.000000Z"
+}
+```

api_routes_v2.py

@@ -72,11 +72,16 @@ def _get_conversation_s3_key(session_id: str) -> str:
     """Return the canonical S3 key for a session's conversation."""
     return f"{S3_PREFIX}/conversations/{session_id}.json"
 
-def _save_conversation_to_s3(session_id: str, messages: List[Dict[str, Any]]):
+def _save_conversation_to_s3(session_id: str, messages: List[Dict[str, Any]], update_activity: bool = False):
     """
     V3 RULE: Persist full conversation history to S3.
     MongoDB stores metadata only.
     This overwrites the existing file on every new message (simple append architecture).
+    
+    Args:
+        session_id: Session ID
+        messages: List of messages to save
+        update_activity: If True, update last_activity timestamp (only for user messages)
     """
     key = _get_conversation_s3_key(session_id)
     try:
@@ -86,14 +91,19 @@ def _save_conversation_to_s3(session_id: str, messages: List[Dict[str, Any]]):
             Body=json.dumps(messages, ensure_ascii=False),
             ContentType="application/json"
         )
-        # Update MongoDB with reference and stats (idempotent)
-        session_manager.update_session(session_id, {
+        # Update MongoDB with reference and stats
+        updates = {
             "conversation_s3_key": key,
             "last_message_count": len(messages),
-            "last_activity": datetime.utcnow().isoformat() + "Z",
             "last_updated": datetime.utcnow().isoformat() + "Z",
             "stats.message_count": len(messages)
-        })
+        }
+        
+        # Only update last_activity if explicitly requested (for user messages)
+        if update_activity:
+            updates["last_activity"] = datetime.utcnow().isoformat() + "Z"
+        
+        session_manager.update_session(session_id, updates, update_activity=False)
     except Exception as e:
         print(f"CRITICAL ERROR saving conversation to S3: {e}")
         # In a real system, we might want to retry or circuit break
@@ -141,14 +151,14 @@ def _validate_conversation_integrity(session_id: str) -> Dict[str, Any]:
             if msgs:
                 # Auto-migrate old session to V3
                 try:
-                    _save_conversation_to_s3(session_id, msgs)
+                    _save_conversation_to_s3(session_id, msgs, update_activity=False)
                     # Clear old MongoDB messages after successful migration
                     session_manager.update_session(session_id, {"messages": []})
                     return {"valid": True, "note": "Migrated old MongoDB messages to S3"}
                 except Exception as e:
                     return {"valid": False, "error": f"Migration failed: {str(e)}"}
             # New empty session - initialize S3
-            _save_conversation_to_s3(session_id, [])
+            _save_conversation_to_s3(session_id, [], update_activity=False)
             return {"valid": True, "note": "Initialized new session"}
 
     try:
@@ -547,7 +557,7 @@ def _get_session_or_init(chat_id: str):
         # Create new session (metadata in Mongo)
         session_manager.update_session(chat_id, {"state": "initial"})
         # Initialize S3 conversation file (Source of Truth)
-        _save_conversation_to_s3(chat_id, [])
+        _save_conversation_to_s3(chat_id, [], update_activity=False)
         return session_manager.get_session(chat_id) or {"state": "initial"}
 
     # Validate integrity of existing session
@@ -586,6 +596,7 @@ def _add_and_mirror_message(chat_id: str, role: str, content: str, file_metadata
     """
     V3 RULE: Append message to S3 conversation.
     MongoDB metadata updated via _save_conversation_to_s3.
+    Only updates last_activity for user messages.
     """
     # 1. Load existing
     current_messages = _load_conversation_from_s3(chat_id)
@@ -609,8 +620,8 @@ def _add_and_mirror_message(chat_id: str, role: str, content: str, file_metadata
     
     current_messages.append(new_msg)
     
-    # 3. Save to S3 (this updates MongoDB metadata too)
-    _save_conversation_to_s3(chat_id, current_messages)
+    # 3. Save to S3 - only update last_activity for user messages
+    _save_conversation_to_s3(chat_id, current_messages, update_activity=(role == "user"))
     
     # 4. Auto-generate chat name after first user message
     if role == "user":

services/session_manager.py

@@ -244,20 +244,11 @@ class SessionManager:
         return messages
     
     def get_session(self, session_id: str) -> Optional[Dict[str, Any]]:
-        """Get session metadata by ID"""
+        """Get session metadata by ID (read-only, does not update last_activity)"""
         session = self.sessions_collection.find_one(
             {"session_id": session_id},
             {"_id": 0}
         )
-        
-        if session:
-            # Update last_activity timestamp
-            now = datetime.utcnow()
-            self.sessions_collection.update_one(
-                {"session_id": session_id},
-                {"$set": {"last_activity": now.isoformat() + "Z"}}
-            )
-        
         return session
     
     def get_all_sessions(
@@ -285,7 +276,8 @@ class SessionManager:
     def update_session(
         self,
         session_id: str,
-        updates: Dict[str, Any]
+        updates: Dict[str, Any],
+        update_activity: bool = False
     ) -> bool:
         """
         Update session metadata
@@ -293,12 +285,14 @@ class SessionManager:
         Args:
             session_id: Session ID
             updates: Fields to update
+            update_activity: If True, also update last_activity timestamp
         
         Returns:
             True if successful
         """
-        # Always update last_activity
-        updates["last_activity"] = datetime.utcnow().isoformat() + "Z"
+        # Only update last_activity if explicitly requested
+        if update_activity and "last_activity" not in updates:
+            updates["last_activity"] = datetime.utcnow().isoformat() + "Z"
         
         result = self.sessions_collection.update_one(
             {"session_id": session_id},