API_RESPONSES_correction.md

# 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"
}
```