syntax = "v1"

type (
	AIMessage {
		Role    string `json:"role" validate:"required,oneof=system user assistant"` // 訊息角色
		Content string `json:"content" validate:"required"` // 訊息內容
	}
	AIChatReq {
		Provider    string      `json:"provider" validate:"required,oneof=opencode-go xai"` // AI provider
		Model       string      `json:"model" validate:"required"` // 模型 ID
		System      string      `json:"system,optional"` // system prompt
		Messages    []AIMessage `json:"messages" validate:"required,min=1,dive"` // 對話訊息
		Temperature *float64    `json:"temperature,optional"` // 溫度
		MaxTokens   *int        `json:"max_tokens,optional"` // 最大輸出 token
	}
	AIProviderOption {
		ID      string `json:"id"`
		Label   string `json:"label"`
		Streams bool   `json:"streams"`
	}
	AIProvidersData {
		Providers []AIProviderOption `json:"providers"`
	}
	AIProviderPath {
		Provider string `path:"provider" validate:"required,oneof=opencode-go xai"` // 要查模型的 provider
	}
	AIProviderModelsData {
		ID      string   `json:"id"`
		Label   string   `json:"label"`
		Models  []string `json:"models"`
		Streams bool     `json:"streams"`
		Error   string   `json:"error,optional"` // 拉 models 失敗時的摘要
	}
	AIChatData {
		Text         string `json:"text"`
		FinishReason string `json:"finish_reason,optional"`
	}
	IslanderChatReq {
		Messages []AIMessage `json:"messages" validate:"required,min=1,dive"` // 對話訊息
		Context  string      `json:"context,optional"` // 目前頁面與站內導覽快照
	}
)

@server (
	group:   ai
	prefix:  /api/v1/ai
	tags:    "AI - Provider Streaming"
	summary: "Public AI provider catalog"
)
service gateway {
	@handler listAiProviders
	get /providers returns (AIProvidersData)
}

@server (
	group:      ai
	prefix:     /api/v1/ai
	middleware: MemberAuth
	tags:       "AI - Provider Streaming (member)"
	summary:    "Chat/stream/models; member JWT via X-Member-Authorization; provider API key via Authorization"
)
service gateway {
	@handler listAiProviderModels
	post /providers/:provider/models (AIProviderPath) returns (AIProviderModelsData)

	@handler chat
	post /chat (AIChatReq) returns (AIChatData)

	@handler chatStream
	post /chat/stream (AIChatReq)
}

@server (
	group:      ai
	prefix:     /api/v1/ai
	middleware: Auth
	tags:       "AI - Islander Guide"
	summary:    "Floating islander chat; member JWT via Authorization; AI key from member settings"
)
service gateway {
	@handler islanderChatStream
	post /islander/chat/stream (IslanderChatReq)
}