{
  "openapi": "3.1.0",
  "info": {
    "title": "api-gateway",
    "description": "",
    "license": {
      "name": ""
    },
    "version": "0.1.0"
  },
  "paths": {
    "/api/v1/configs/analysis_template_sets": {
      "get": {
        "tags": [
          "api"
        ],
        "summary": "[GET /api/v1/configs/analysis_template_sets]",
        "operationId": "get_analysis_template_sets",
        "responses": {
          "200": {
            "description": "Analysis template sets configuration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalysisTemplateSets"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "api"
        ],
        "summary": "[PUT /api/v1/configs/analysis_template_sets]",
        "operationId": "update_analysis_template_sets",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnalysisTemplateSets"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Updated analysis template sets configuration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalysisTemplateSets"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/configs/data_sources": {
      "get": {
        "tags": [
          "api"
        ],
        "summary": "[GET /api/v1/configs/data_sources]",
        "operationId": "get_data_sources_config",
        "responses": {
          "200": {
            "description": "Data sources configuration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataSourcesConfig"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "api"
        ],
        "summary": "[PUT /api/v1/configs/data_sources]",
        "operationId": "update_data_sources_config",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DataSourcesConfig"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Updated data sources configuration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataSourcesConfig"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/configs/llm/test": {
      "post": {
        "tags": [
          "api"
        ],
        "summary": "[POST /v1/configs/llm/test]",
        "operationId": "test_llm_config",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TestLlmConfigRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "LLM config test result (JSON)"
          }
        }
      }
    },
    "/api/v1/configs/llm_providers": {
      "get": {
        "tags": [
          "api"
        ],
        "summary": "[GET /api/v1/configs/llm_providers]",
        "operationId": "get_llm_providers_config",
        "responses": {
          "200": {
            "description": "LLM providers configuration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LlmProvidersConfig"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "api"
        ],
        "summary": "[PUT /api/v1/configs/llm_providers]",
        "operationId": "update_llm_providers_config",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LlmProvidersConfig"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Updated LLM providers configuration",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LlmProvidersConfig"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/configs/test": {
      "post": {
        "tags": [
          "api"
        ],
        "summary": "[POST /api/v1/configs/test]\nForwards a configuration test request to the appropriate downstream service.",
        "operationId": "test_data_source_config",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TestConfigRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Configuration test result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestConnectionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/discover-models": {
      "post": {
        "tags": [
          "api"
        ],
        "summary": "[POST /api/v1/discover-models]\nPreview discovery without persisting provider configuration.",
        "operationId": "discover_models_preview",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DiscoverPreviewRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Discovered models (JSON)"
          },
          "502": {
            "description": "Provider error"
          }
        }
      }
    },
    "/api/v1/discover-models/{provider_id}": {
      "get": {
        "tags": [
          "api"
        ],
        "summary": "[GET /api/v1/discover-models/:provider_id]",
        "operationId": "discover_models",
        "parameters": [
          {
            "name": "provider_id",
            "in": "path",
            "description": "Provider ID to discover models for",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Discovered models (JSON)"
          },
          "404": {
            "description": "Provider not found"
          },
          "502": {
            "description": "Provider error"
          }
        }
      }
    },
    "/api/v1/registry/providers": {
      "get": {
        "tags": [
          "api"
        ],
        "summary": "[GET /api/v1/registry/providers]\nReturns metadata for all registered data providers.",
        "operationId": "get_registered_providers",
        "responses": {
          "200": {
            "description": "Registered providers metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ProviderMetadata"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tools/resolve-symbol": {
      "post": {
        "tags": [
          "api"
        ],
        "summary": "[POST /v1/tools/resolve-symbol]\nResolves and normalizes a symbol without starting a workflow.",
        "operationId": "resolve_symbol",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SymbolResolveRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Symbol resolved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SymbolResolveResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/workflow/start": {
      "post": {
        "tags": [
          "api"
        ],
        "summary": "[POST /v1/workflow/start]\nInitiates a new analysis workflow via the Orchestrator.",
        "operationId": "start_workflow",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DataRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Workflow started",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequestAcceptedResponse"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": [
          "api"
        ],
        "operationId": "health_check",
        "responses": {
          "200": {
            "description": "Service healthy"
          }
        }
      }
    },
    "/tasks/{request_id}": {
      "get": {
        "tags": [
          "api"
        ],
        "summary": "[GET /v1/tasks/:request_id]\nAggregates task progress from all downstream provider services.",
        "operationId": "get_task_progress",
        "parameters": [
          {
            "name": "request_id",
            "in": "path",
            "description": "Request ID to query tasks for",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Task progress list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/TaskProgress"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Tasks not found"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AnalysisModuleConfig": {
        "type": "object",
        "required": [
          "name",
          "dependencies",
          "context_selector",
          "analysis_prompt",
          "output_type"
        ],
        "properties": {
          "analysis_prompt": {
            "type": "string"
          },
          "context_selector": {
            "$ref": "#/components/schemas/ContextSelectorConfig"
          },
          "dependencies": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "id": {
            "type": [
              "string",
              "null"
            ]
          },
          "llm_config": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/LlmConfig"
              }
            ]
          },
          "name": {
            "type": "string"
          },
          "output_type": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "AnalysisTemplateSet": {
        "type": "object",
        "description": "A single, self-contained set of analysis modules representing a complete workflow.\ne.g., \"Standard Fundamental Analysis\"",
        "required": [
          "name",
          "modules"
        ],
        "properties": {
          "modules": {
            "type": "object",
            "description": "All analysis modules contained within this template set.\nKey: Module ID (e.g., \"fundamental_analysis\")",
            "additionalProperties": {
              "$ref": "#/components/schemas/AnalysisModuleConfig"
            },
            "propertyNames": {
              "type": "string"
            }
          },
          "name": {
            "type": "string",
            "description": "Human-readable name for the template set."
          }
        },
        "additionalProperties": false
      },
      "AnalysisTemplateSets": {
        "type": "object",
        "description": "Top-level configuration object for all analysis templates.\nKey: Template ID (e.g., \"standard_fundamentals\")",
        "additionalProperties": {
          "$ref": "#/components/schemas/AnalysisTemplateSet"
        },
        "propertyNames": {
          "type": "string"
        }
      },
      "CanonicalSymbol": {
        "type": "string",
        "description": "CanonicalSymbol 是系统内部唯一的股票代码标识符类型\n它封装了一个标准化的字符串（遵循 Yahoo Finance 格式）\n使用 newtype 模式防止与普通 String 混淆",
        "example": "600519.SS"
      },
      "ConfigFieldSchema": {
        "type": "object",
        "description": "单个配置字段的定义",
        "required": [
          "key",
          "label",
          "field_type",
          "required"
        ],
        "properties": {
          "default_value": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "field_type": {
            "$ref": "#/components/schemas/FieldType"
          },
          "key": {
            "$ref": "#/components/schemas/ConfigKey"
          },
          "label": {
            "type": "string"
          },
          "options": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Options for 'Select' type"
          },
          "placeholder": {
            "type": [
              "string",
              "null"
            ]
          },
          "required": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      },
      "ConfigKey": {
        "type": "string",
        "description": "配置键枚举 - 强类型定义所有可能的配置项",
        "enum": [
          "ApiKey",
          "ApiToken",
          "ApiUrl",
          "BaseUrl",
          "SecretKey",
          "Username",
          "Password",
          "SandboxMode",
          "Region"
        ]
      },
      "ContextSelectorConfig": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SelectionMode"
          }
        ]
      },
      "DataRequest": {
        "type": "object",
        "required": [
          "symbol",
          "template_id"
        ],
        "properties": {
          "market": {
            "type": [
              "string",
              "null"
            ]
          },
          "symbol": {
            "type": "string"
          },
          "template_id": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "DataSourceConfig": {
        "type": "object",
        "required": [
          "provider",
          "enabled"
        ],
        "properties": {
          "api_key": {
            "type": [
              "string",
              "null"
            ]
          },
          "api_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "enabled": {
            "type": "boolean"
          },
          "provider": {
            "$ref": "#/components/schemas/DataSourceProvider"
          }
        },
        "additionalProperties": false
      },
      "DataSourceProvider": {
        "type": "string",
        "enum": [
          "Tushare",
          "Finnhub",
          "Alphavantage",
          "Yfinance"
        ]
      },
      "DataSourcesConfig": {
        "type": "object",
        "additionalProperties": {
          "$ref": "#/components/schemas/DataSourceConfig"
        },
        "propertyNames": {
          "type": "string"
        }
      },
      "DiscoverPreviewRequest": {
        "type": "object",
        "required": [
          "api_base_url",
          "api_key"
        ],
        "properties": {
          "api_base_url": {
            "type": "string"
          },
          "api_key": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "FieldType": {
        "type": "string",
        "description": "字段类型枚举",
        "enum": [
          "Text",
          "Password",
          "Url",
          "Boolean",
          "Select"
        ]
      },
      "HealthStatus": {
        "type": "object",
        "required": [
          "module_id",
          "status",
          "version",
          "details"
        ],
        "properties": {
          "details": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "propertyNames": {
              "type": "string"
            }
          },
          "module_id": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/ServiceStatus"
          },
          "version": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "LlmConfig": {
        "type": "object",
        "properties": {
          "max_tokens": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32",
            "minimum": 0
          },
          "model_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "temperature": {
            "type": [
              "number",
              "null"
            ],
            "format": "float"
          }
        },
        "additionalProperties": false
      },
      "LlmModel": {
        "type": "object",
        "required": [
          "model_id",
          "is_active"
        ],
        "properties": {
          "is_active": {
            "type": "boolean"
          },
          "model_id": {
            "type": "string"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "additionalProperties": false
      },
      "LlmProvider": {
        "type": "object",
        "required": [
          "name",
          "api_base_url",
          "api_key",
          "models"
        ],
        "properties": {
          "api_base_url": {
            "type": "string"
          },
          "api_key": {
            "type": "string"
          },
          "models": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LlmModel"
            }
          },
          "name": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "LlmProvidersConfig": {
        "type": "object",
        "additionalProperties": {
          "$ref": "#/components/schemas/LlmProvider"
        },
        "propertyNames": {
          "type": "string"
        }
      },
      "ObservabilityTaskStatus": {
        "type": "string",
        "enum": [
          "Queued",
          "InProgress",
          "Completed",
          "Failed"
        ]
      },
      "ProviderMetadata": {
        "type": "object",
        "description": "服务元数据",
        "required": [
          "id",
          "name_en",
          "name_cn",
          "description",
          "config_schema",
          "supports_test_connection"
        ],
        "properties": {
          "config_schema": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConfigFieldSchema"
            },
            "description": "该服务需要的配置字段列表"
          },
          "description": {
            "type": "string"
          },
          "icon_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "type": "string"
          },
          "name_cn": {
            "type": "string"
          },
          "name_en": {
            "type": "string"
          },
          "supports_test_connection": {
            "type": "boolean",
            "description": "是否支持“测试连接”功能"
          }
        },
        "additionalProperties": false
      },
      "RequestAcceptedResponse": {
        "type": "object",
        "required": [
          "request_id",
          "symbol",
          "market"
        ],
        "properties": {
          "market": {
            "type": "string"
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          },
          "symbol": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "SelectionMode": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "Manual"
            ],
            "properties": {
              "Manual": {
                "type": "object",
                "required": [
                  "rules"
                ],
                "properties": {
                  "rules": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          {
            "type": "object",
            "required": [
              "Auto"
            ],
            "properties": {
              "Auto": {
                "type": "object",
                "properties": {
                  "llm_config": {
                    "oneOf": [
                      {
                        "type": "null"
                      },
                      {
                        "$ref": "#/components/schemas/LlmConfig"
                      }
                    ]
                  }
                }
              }
            }
          },
          {
            "type": "object",
            "required": [
              "Hybrid"
            ],
            "properties": {
              "Hybrid": {
                "type": "object",
                "required": [
                  "selection_prompt"
                ],
                "properties": {
                  "llm_config": {
                    "oneOf": [
                      {
                        "type": "null"
                      },
                      {
                        "$ref": "#/components/schemas/LlmConfig"
                      }
                    ]
                  },
                  "selection_prompt": {
                    "type": "string"
                  }
                }
              }
            }
          }
        ]
      },
      "ServiceStatus": {
        "type": "string",
        "enum": [
          "Ok",
          "Degraded",
          "Unhealthy"
        ]
      },
      "StartWorkflowCommand": {
        "type": "object",
        "description": "Command to initiate a new workflow.\nPublished by: `api-gateway`\nConsumed by: `workflow-orchestrator`",
        "required": [
          "request_id",
          "symbol",
          "market",
          "template_id"
        ],
        "properties": {
          "market": {
            "type": "string"
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          },
          "symbol": {
            "$ref": "#/components/schemas/CanonicalSymbol"
          },
          "template_id": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "SymbolResolveRequest": {
        "type": "object",
        "required": [
          "symbol"
        ],
        "properties": {
          "market": {
            "type": [
              "string",
              "null"
            ]
          },
          "symbol": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "SymbolResolveResponse": {
        "type": "object",
        "required": [
          "symbol",
          "market"
        ],
        "properties": {
          "market": {
            "type": "string"
          },
          "symbol": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "TaskDependency": {
        "type": "object",
        "required": [
          "from",
          "to"
        ],
        "properties": {
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "TaskNode": {
        "type": "object",
        "required": [
          "id",
          "name",
          "type",
          "initial_status"
        ],
        "properties": {
          "display_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "type": "string"
          },
          "initial_status": {
            "$ref": "#/components/schemas/TaskStatus"
          },
          "name": {
            "type": "string"
          },
          "type": {
            "$ref": "#/components/schemas/TaskType"
          }
        },
        "additionalProperties": false
      },
      "TaskProgress": {
        "type": "object",
        "required": [
          "request_id",
          "task_name",
          "status",
          "progress_percent",
          "details",
          "started_at"
        ],
        "properties": {
          "details": {
            "type": "string"
          },
          "progress_percent": {
            "type": "integer",
            "format": "int32",
            "minimum": 0
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          },
          "started_at": {
            "type": "string",
            "format": "date-time"
          },
          "status": {
            "$ref": "#/components/schemas/ObservabilityTaskStatus"
          },
          "task_name": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "TaskStatus": {
        "type": "string",
        "enum": [
          "Pending",
          "Scheduled",
          "Running",
          "Completed",
          "Failed",
          "Skipped"
        ]
      },
      "TaskType": {
        "type": "string",
        "enum": [
          "DataFetch",
          "DataProcessing",
          "Analysis"
        ]
      },
      "TestConfigRequest": {
        "type": "object",
        "required": [
          "type",
          "data"
        ],
        "properties": {
          "data": {},
          "type": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "TestConnectionResponse": {
        "type": "object",
        "required": [
          "success",
          "message"
        ],
        "properties": {
          "message": {
            "type": "string"
          },
          "success": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      },
      "TestLlmConfigRequest": {
        "type": "object",
        "required": [
          "api_base_url",
          "api_key",
          "model_id"
        ],
        "properties": {
          "api_base_url": {
            "type": "string"
          },
          "api_key": {
            "type": "string"
          },
          "model_id": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "WorkflowDag": {
        "type": "object",
        "required": [
          "nodes",
          "edges"
        ],
        "properties": {
          "edges": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaskDependency"
            }
          },
          "nodes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaskNode"
            }
          }
        },
        "additionalProperties": false
      },
      "WorkflowEvent": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "payload",
              "type"
            ],
            "properties": {
              "payload": {
                "type": "object",
                "required": [
                  "timestamp",
                  "task_graph"
                ],
                "properties": {
                  "task_graph": {
                    "$ref": "#/components/schemas/WorkflowDag"
                  },
                  "timestamp": {
                    "type": "integer",
                    "format": "int64"
                  }
                }
              },
              "type": {
                "type": "string",
                "enum": [
                  "WorkflowStarted"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "payload",
              "type"
            ],
            "properties": {
              "payload": {
                "type": "object",
                "required": [
                  "task_id",
                  "task_type",
                  "status",
                  "timestamp"
                ],
                "properties": {
                  "input_commit": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "message": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "output_commit": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "progress": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "format": "int32",
                    "minimum": 0
                  },
                  "status": {
                    "$ref": "#/components/schemas/TaskStatus"
                  },
                  "task_id": {
                    "type": "string"
                  },
                  "task_type": {
                    "$ref": "#/components/schemas/TaskType"
                  },
                  "timestamp": {
                    "type": "integer",
                    "format": "int64"
                  }
                }
              },
              "type": {
                "type": "string",
                "enum": [
                  "TaskStateChanged"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "payload",
              "type"
            ],
            "properties": {
              "payload": {
                "type": "object",
                "required": [
                  "task_id",
                  "content_delta",
                  "index"
                ],
                "properties": {
                  "content_delta": {
                    "type": "string"
                  },
                  "index": {
                    "type": "integer",
                    "format": "int32",
                    "minimum": 0
                  },
                  "task_id": {
                    "type": "string"
                  }
                }
              },
              "type": {
                "type": "string",
                "enum": [
                  "TaskStreamUpdate"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "payload",
              "type"
            ],
            "properties": {
              "payload": {
                "type": "object",
                "required": [
                  "task_id",
                  "level",
                  "message",
                  "timestamp"
                ],
                "properties": {
                  "level": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "task_id": {
                    "type": "string"
                  },
                  "timestamp": {
                    "type": "integer",
                    "format": "int64"
                  }
                }
              },
              "type": {
                "type": "string",
                "enum": [
                  "TaskLog"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "payload",
              "type"
            ],
            "properties": {
              "payload": {
                "type": "object",
                "required": [
                  "end_timestamp"
                ],
                "properties": {
                  "end_timestamp": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "result_summary": {}
                }
              },
              "type": {
                "type": "string",
                "enum": [
                  "WorkflowCompleted"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "payload",
              "type"
            ],
            "properties": {
              "payload": {
                "type": "object",
                "required": [
                  "reason",
                  "is_fatal",
                  "end_timestamp"
                ],
                "properties": {
                  "end_timestamp": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "is_fatal": {
                    "type": "boolean"
                  },
                  "reason": {
                    "type": "string"
                  }
                }
              },
              "type": {
                "type": "string",
                "enum": [
                  "WorkflowFailed"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "payload",
              "type"
            ],
            "properties": {
              "payload": {
                "type": "object",
                "required": [
                  "timestamp",
                  "task_graph",
                  "tasks_status",
                  "tasks_output"
                ],
                "properties": {
                  "task_graph": {
                    "$ref": "#/components/schemas/WorkflowDag"
                  },
                  "tasks_output": {
                    "type": "object",
                    "additionalProperties": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "propertyNames": {
                      "type": "string"
                    }
                  },
                  "tasks_status": {
                    "type": "object",
                    "additionalProperties": {
                      "$ref": "#/components/schemas/TaskStatus"
                    },
                    "propertyNames": {
                      "type": "string"
                    }
                  },
                  "timestamp": {
                    "type": "integer",
                    "format": "int64"
                  }
                }
              },
              "type": {
                "type": "string",
                "enum": [
                  "WorkflowStateSnapshot"
                ]
              }
            }
          }
        ],
        "description": "Unified event stream for frontend consumption."
      }
    }
  },
  "tags": [
    {
      "name": "workflow",
      "description": "Workflow management endpoints"
    },
    {
      "name": "config",
      "description": "Configuration management endpoints"
    },
    {
      "name": "tools",
      "description": "Utility tools"
    },
    {
      "name": "observability",
      "description": "System observability"
    }
  ]
}