Hugging Face's logo

Spaces:
stellar413
/
masterllm
Sleeping

App Files Community
masterllm / API_RESPONSES.md
ganesh-vilje's picture
ganesh-vilje
Fix: Update last_activity only for user messages
6cb5907
preview code
|
raw
history blame contribute delete
20 kB

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):

{
  "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):

{
  "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:

{
  "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:

{
  "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:

{
  "status": "deleted",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

PUT /api/v2/sessions/{session_id}/rename

Description: Renames a session.

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

{
  "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)

{
  "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)

{
  "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:

{
  "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:

{
  "chat_id": "550e8400-e29b-41d4-a716-446655440000"
}

GET /api/v2/health

Description: Health check.

Response:

{
  "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:

{
  "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 ✅