@ailib-official/ai-protocol 0.8.4

package/v1/providers/spark.yaml

@@ -0,0 +1,167 @@
+$schema: "https://raw.githubusercontent.com/ailib-official/ai-protocol/main/schemas/v1.json"
+
+id: spark
+protocol_version: "1.5"
+
+name: 讯飞星火 (iFlytek Spark)
+version: "v1"
+status: stable
+category: ai_provider
+official_url: "https://www.xfyun.cn/doc/spark/Web.html"
+support_contact: "https://www.xfyun.cn/services"
+
+endpoint:
+  base_url: "https://spark-api-open.xf-yun.com/v1"
+  protocol: https
+  timeout_ms: 60000
+
+auth:
+  type: bearer
+  token_env: "SPARK_API_KEY"
+
+payload_format: "openai_style"
+
+# Spark uses OpenAI-compatible API
+api_families: ["chat_completions"]
+default_api_family: "chat_completions"
+
+endpoints:
+  chat:
+    path: "/chat/completions"
+    method: "POST"
+    adapter: "openai"
+
+services:
+  list_models:
+    path: "/models"
+    method: "GET"
+    response_binding: "data"
+
+termination:
+  source_field: "finish_reason"
+  mapping:
+    stop: "end_turn"
+    length: "max_tokens"
+    tool_calls: "tool_use"
+  notes:
+    - "OpenAI-compatible finish_reason."
+    - "星火大模型 (Spark) is iFlytek's flagship LLM series."
+
+tooling:
+  source_model: "openai_tool_calls"
+  tool_use:
+    id_path: "id"
+    name_path: "function.name"
+    input_path: "function.arguments"
+    input_format: "json_string"
+  notes:
+    - "Supports OpenAI-compatible function calling."
+
+retry_policy:
+  strategy: "exponential_backoff"
+  max_retries: 3
+  min_delay_ms: 1000
+  max_delay_ms: 30000
+  jitter: "full"
+  retry_on_http_status: [429, 500, 502, 503]
+
+error_classification:
+  by_http_status:
+    "400": "invalid_request"
+    "401": "authentication"
+    "403": "permission_denied"
+    "404": "not_found"
+    "429": "rate_limited"
+    "500": "server_error"
+    "503": "overloaded"
+
+parameter_mappings:
+  temperature: "temperature"
+  max_tokens: "max_tokens"
+  stream: "stream"
+  top_k: "top_k"
+  tools: "tools"
+  tool_choice: "tool_choice"
+
+response_format: "openai_style"
+
+response_paths:
+  content: "choices[0].message.content"
+  tool_calls: "choices[0].message.tool_calls"
+  usage: "usage"
+  finish_reason: "choices[0].finish_reason"
+
+streaming:
+  event_format: "data_lines"
+  decoder:
+    format: "sse"
+    delimiter: "\n\n"
+    prefix: "data: "
+    done_signal: "[DONE]"
+  content_path: "choices[0].delta.content"
+  tool_call_path: "choices[0].delta.tool_calls"
+  usage_path: "usage"
+  frame_selector: "exists($.choices) || exists($.error)"
+  event_map:
+    - match: "exists($.choices[*].delta.content)"
+      emit: "PartialContentDelta"
+      fields:
+        content: "$.choices[*].delta.content"
+    - match: "exists($.choices[*].delta.tool_calls[*].function.name)"
+      emit: "ToolCallStarted"
+      fields:
+        tool_call_id: "$.choices[*].delta.tool_calls[*].id"
+        tool_name: "$.choices[*].delta.tool_calls[*].function.name"
+        index: "$.choices[*].delta.tool_calls[*].index"
+    - match: "exists($.choices[*].delta.tool_calls[*].function.arguments)"
+      emit: "PartialToolCall"
+      fields:
+        arguments: "$.choices[*].delta.tool_calls[*].function.arguments"
+        index: "$.choices[*].delta.tool_calls[*].index"
+    - match: "exists($.usage)"
+      emit: "Metadata"
+      fields:
+        usage: "$.usage"
+    - match: "exists($.choices[*].finish_reason)"
+      emit: "FinalCandidate"
+      fields:
+        finish_reason: "$.choices[*].finish_reason"
+  stop_condition: "$.choices[0].finish_reason != null"
+
+features:
+  multi_candidate:
+    support_type: "simulated"
+    max_concurrent: 1
+  response_mapping:
+    tool_calls:
+      path: "choices[0].message.tool_calls"
+      fields:
+        id: "id"
+        name: "function.name"
+        args: "function.arguments"
+    error:
+      message_path: "error.message"
+      code_path: "error.code"
+
+capabilities:
+  streaming: true
+  tools: true
+  vision: true
+  agentic: true
+  parallel_tools: false
+  reasoning: false
+
+availability:
+  required: false
+  regions:
+    - cn
+  check:
+    method: GET
+    path: "/models"
+    expected_status: [200, 401]
+    timeout_ms: 5000
+
+experimental_features:
+  - "document_qa"
+  - "image_generation"
+  - "speech_synthesis"

package/v1/providers/stability.yaml

@@ -0,0 +1,185 @@
+$schema: "https://raw.githubusercontent.com/ailib-official/ai-protocol/main/schemas/v1.json"
+
+id: stability
+protocol_version: "1.5"
+
+name: Stability AI
+version: "v1"
+status: stable
+category: ai_provider
+official_url: "https://platform.stability.ai/docs"
+support_contact: "https://stability.ai/contact"
+
+# Structured endpoint definition (v1.1+ extension)
+endpoint:
+  base_url: "https://api.stability.ai"
+  protocol: https
+  timeout_ms: 60000
+
+auth:
+  type: bearer
+  token_env: "STABILITY_API_KEY"
+  extra_headers:
+    - name: "Content-Type"
+      value: "application/json"
+    - name: "Accept"
+      value: "application/json"
+  payload_format: "stability_api"
+
+# Stability AI supports multiple creative AI APIs
+api_families: ["text_to_image", "image_to_image", "image_to_image_masking", "inpainting", "outpainting", "image_upscale", "video_generation"]
+default_api_family: "text_to_image"
+endpoints:
+  text_to_image:
+    path: "/v2beta/stable-image/generate/sd3"
+    method: "POST"
+    adapter: "stability"
+  image_to_image:
+    path: "/v2beta/stable-image/generate/sd3"
+    method: "POST"
+    adapter: "stability"
+  image_edit:
+    path: "/v2beta/stable-image/edit/erase"
+    method: "POST"
+    adapter: "stability"
+  image_search_and_replace:
+    path: "/v2beta/stable-image/edit/search-and-replace"
+    method: "POST"
+    adapter: "stability"
+  upscale:
+    path: "/v2beta/stable-image/upscale/conservative"
+    method: "POST"
+    adapter: "stability"
+
+# V1.5 Service Endpoints
+services:
+  list_models:
+    path: "/v2beta/models/list"
+    method: "GET"
+    response_binding: "data"
+
+# Stability AI doesn't use finish_reason in the same way as LLMs
+termination:
+  source_field: "finish"
+  mapping:
+    complete: "completed"
+    failed: "error"
+  notes:
+    - "Image generation uses async workflow with job IDs"
+    - "finish_field indicates completion status"
+
+# Tool invocation normalization
+tooling:
+  source_model: "unknown"
+  notes:
+    - "Stability AI is not designed for text-based tool calling"
+    - "Focuses on image/video generation workflows"
+
+# Retry policy
+retry_policy:
+  strategy: "exponential_backoff"
+  max_retries: 3
+  min_delay_ms: 1000
+  max_delay_ms: 10000
+  jitter: "full"
+  retry_on_http_status: [429, 500, 502, 503]
+  notes:
+    - "Image generation can be resource-intensive"
+    - "502/503 common during high load"
+    - "429 indicates rate limit exceeded"
+
+# Error classification hints
+error_classification:
+  by_http_status:
+    "400": "invalid_request"
+    "401": "authentication"
+    "403": "permission_denied"
+    "404": "not_found"
+    "429": "rate_limited"
+    "500": "server_error"
+    "502": "overloaded"
+    "503": "overloaded"
+  notes:
+    - "502/503 often indicate generation queue or resource constraints"
+    - "Error messages may include quota information"
+
+parameter_mappings:
+  prompt: "prompt"
+  negative_prompt: "negative_prompt"
+  aspect_ratio: "aspect_ratio"
+  seed: "seed"
+  steps: "steps"
+  cfg_scale: "cfg_scale"
+  mode: "mode"
+  output_format: "output_format"
+  strength: "strength"
+  image: "image"
+  init_image_mode: "init_image_mode"
+
+response_format: "stability_image"
+response_paths:
+  content: "image"
+  artifacts: "artifacts"
+  finish_reason: "finish"
+  image_url: "image"
+
+streaming:
+  event_format: "stability_async"
+  decoder:
+    format: "sse"
+    delimiter: "\n\n"
+    prefix: "data: "
+    done_signal: "[DONE]"
+  # Stability uses job-based async generation
+  frame_selector: "exists($.id) || exists($.image) || exists($.artifacts)"
+  event_map:
+    - match: "exists($.id) && !exists($.image)"
+      emit: "Metadata"
+      fields:
+        job_id: "$.id"
+        status: "$.status"
+        timestamp: "$.timestamp"
+    - match: "exists($.image)"
+      emit: "FinalCandidate"
+      fields:
+        image: "$.image"
+        finish_reason: "finish"
+    - match: "exists($.artifacts)"
+      emit: "FinalCandidate"
+      fields:
+        artifacts: "$.artifacts"
+        finish: "$.finish"
+  stop_condition: "exists($.image) || exists($.artifacts) || exists($.finish) && $.finish == 'complete'"
+  extra_metadata_path: "$.finish"
+
+capabilities:
+  streaming: false
+  tools: false
+  vision: true
+  agentic: false
+  parallel_tools: false
+  reasoning: false
+
+experimental_features:
+  - "async_generation"
+  - "video_generation"
+  - "3d_generation"
+  - "inpainting"
+  - "outpainting"
+
+# Connection vars for model selection
+connection_vars:
+  model: "model_id"
+
+# Availability and health checking (v1.1+ extension)
+availability:
+  required: false
+  regions:
+    - global
+  check:
+    method: GET
+    path: "/v2beta/models/list"
+    expected_status: [200]
+    timeout_ms: 5000
+  notes:
+    - "Check models/list endpoint to verify service health"

package/v1/providers/tiangong.yaml

@@ -0,0 +1,170 @@
+$schema: "https://raw.githubusercontent.com/ailib-official/ai-protocol/main/schemas/v1.json"
+
+id: tiangong
+protocol_version: "1.5"
+
+name: 昆仑万维天工 (Kunlun Tiangong)
+version: "v1"
+status: stable
+category: ai_provider
+official_url: "https://model-platform.tiangong.cn/api-reference"
+support_contact: "https://www.kunlun.com/contact"
+
+endpoint:
+  base_url: "https://sky-api.singularity-ai.com/saas/api/v4"
+  protocol: https
+  timeout_ms: 60000
+
+auth:
+  type: bearer
+  token_env: "TIANGONG_API_KEY"
+
+payload_format: "openai_style"
+
+# Tiangong uses OpenAI-compatible API
+api_families: ["chat_completions"]
+default_api_family: "chat_completions"
+
+endpoints:
+  chat:
+    path: "/chat/completions"
+    method: "POST"
+    adapter: "openai"
+
+services:
+  list_models:
+    path: "/models"
+    method: "GET"
+    response_binding: "data"
+
+termination:
+  source_field: "finish_reason"
+  mapping:
+    stop: "end_turn"
+    length: "max_tokens"
+    tool_calls: "tool_use"
+  notes:
+    - "OpenAI-compatible finish_reason."
+    - "天工 (Tiangong) is Kunlun's flagship AI assistant."
+
+tooling:
+  source_model: "openai_tool_calls"
+  tool_use:
+    id_path: "id"
+    name_path: "function.name"
+    input_path: "function.arguments"
+    input_format: "json_string"
+  notes:
+    - "Supports OpenAI-compatible function calling."
+
+retry_policy:
+  strategy: "exponential_backoff"
+  max_retries: 3
+  min_delay_ms: 1000
+  max_delay_ms: 30000
+  jitter: "full"
+  retry_on_http_status: [429, 500, 502, 503]
+
+error_classification:
+  by_http_status:
+    "400": "invalid_request"
+    "401": "authentication"
+    "403": "permission_denied"
+    "404": "not_found"
+    "429": "rate_limited"
+    "500": "server_error"
+    "503": "overloaded"
+
+parameter_mappings:
+  temperature: "temperature"
+  max_tokens: "max_tokens"
+  stream: "stream"
+  top_p: "top_p"
+  stop_sequences: "stop"
+  tools: "tools"
+  tool_choice: "tool_choice"
+  frequency_penalty: "frequency_penalty"
+  presence_penalty: "presence_penalty"
+
+response_format: "openai_style"
+
+response_paths:
+  content: "choices[0].message.content"
+  tool_calls: "choices[0].message.tool_calls"
+  usage: "usage"
+  finish_reason: "choices[0].finish_reason"
+
+streaming:
+  event_format: "data_lines"
+  decoder:
+    format: "sse"
+    delimiter: "\n\n"
+    prefix: "data: "
+    done_signal: "[DONE]"
+  content_path: "choices[0].delta.content"
+  tool_call_path: "choices[0].delta.tool_calls"
+  usage_path: "usage"
+  frame_selector: "exists($.choices) || exists($.error)"
+  event_map:
+    - match: "exists($.choices[*].delta.content)"
+      emit: "PartialContentDelta"
+      fields:
+        content: "$.choices[*].delta.content"
+    - match: "exists($.choices[*].delta.tool_calls[*].function.name)"
+      emit: "ToolCallStarted"
+      fields:
+        tool_call_id: "$.choices[*].delta.tool_calls[*].id"
+        tool_name: "$.choices[*].delta.tool_calls[*].function.name"
+        index: "$.choices[*].delta.tool_calls[*].index"
+    - match: "exists($.choices[*].delta.tool_calls[*].function.arguments)"
+      emit: "PartialToolCall"
+      fields:
+        arguments: "$.choices[*].delta.tool_calls[*].function.arguments"
+        index: "$.choices[*].delta.tool_calls[*].index"
+    - match: "exists($.usage)"
+      emit: "Metadata"
+      fields:
+        usage: "$.usage"
+    - match: "exists($.choices[*].finish_reason)"
+      emit: "FinalCandidate"
+      fields:
+        finish_reason: "$.choices[*].finish_reason"
+  stop_condition: "$.choices[0].finish_reason != null"
+
+features:
+  multi_candidate:
+    support_type: "native"
+    param_name: "n"
+  response_mapping:
+    tool_calls:
+      path: "choices[0].message.tool_calls"
+      fields:
+        id: "id"
+        name: "function.name"
+        args: "function.arguments"
+    error:
+      message_path: "error.message"
+      code_path: "error.code"
+
+capabilities:
+  streaming: true
+  tools: true
+  vision: true
+  agentic: true
+  parallel_tools: true
+  reasoning: false
+
+availability:
+  required: false
+  regions:
+    - cn
+  check:
+    method: GET
+    path: "/models"
+    expected_status: [200, 401]
+    timeout_ms: 5000
+
+experimental_features:
+  - "web_search"
+  - "music_generation"
+  - "image_generation"

package/v1/providers/together.yaml

@@ -0,0 +1,156 @@
+$schema: ../../schemas/v1.json
+protocol_version: "1.5"
+id: "together"
+name: "Together AI"
+status: "stable"
+category: "model_provider"
+official_url: "https://www.together.ai/"
+support_contact: "https://www.together.ai/contact"
+
+endpoint:
+  base_url: "https://api.together.xyz/v1"
+  protocol: "https"
+  timeout_ms: 60000
+
+# Auth + payload format are required for online model fact-checking.
+auth:
+  type: bearer
+  token_env: "TOGETHER_API_KEY"
+payload_format: "openai_style"
+
+services:
+  list_models:
+    path: "/models"
+    method: "GET"
+    response_binding: "data"
+
+availability:
+  required: false
+  regions: ["global"]
+  check:
+    method: "GET"
+    path: "/models"
+    expected_status: [200]
+
+capabilities:
+  streaming: true
+  tools: true
+  vision: true
+  agentic: false
+  reasoning: false
+  parallel_tools: false
+
+# Together AI is OpenAI-compatible
+streaming:
+  event_format: "data_lines"
+  decoder:
+    format: "sse"
+    delimiter: "\n\n"
+    prefix: "data: "
+    done_signal: "[DONE]"
+  frame_selector: "exists($.choices) || exists($.error)"
+  candidate:
+    candidate_id_path: "$.choices[*].index"
+    fan_out: true
+  event_map:
+    - match: "exists($.error)"
+      emit: "StreamError"
+      fields:
+        error: "$.error"
+    - match: "exists($.choices[*].delta.content)"
+      emit: "PartialContentDelta"
+      fields:
+        content: "$.choices[*].delta.content"
+    - match: "exists($.choices[*].delta.tool_calls[*].function.name)"
+      emit: "ToolCallStarted"
+      fields:
+        tool_call_id: "$.choices[*].delta.tool_calls[*].id"
+        tool_name: "$.choices[*].delta.tool_calls[*].function.name"
+        index: "$.choices[*].delta.tool_calls[*].index"
+    - match: "exists($.choices[*].delta.tool_calls[*].function.arguments)"
+      emit: "PartialToolCall"
+      fields:
+        arguments: "$.choices[*].delta.tool_calls[*].function.arguments"
+        index: "$.choices[*].delta.tool_calls[*].index"
+    - match: "exists($.usage)"
+      emit: "Metadata"
+      fields:
+        usage: "$.usage"
+    - match: "exists($.choices[*].finish_reason)"
+      emit: "FinalCandidate"
+      fields:
+        finish_reason: "$.choices[*].finish_reason"
+        candidate_index: "$.choices[*].index"
+  stop_condition: "$.choices[0].finish_reason != null"
+  extra_metadata_path: "$.usage"
+  content_path: "$.choices[0].delta.content"
+  tool_call_path: "$.choices[0].delta.tool_calls"
+
+# Termination reason normalization (Together AI uses OpenAI-compatible finish_reason)
+termination:
+  source_field: "finish_reason"
+  mapping:
+    stop: "end_turn"
+    length: "max_tokens"
+    tool_calls: "tool_use"
+    content_filter: "refusal"
+  notes:
+    - "finish_reason is reported per candidate."
+
+# Tool invocation normalization (Together AI is OpenAI-compatible)
+tooling:
+  source_model: "openai_tool_calls"
+  tool_use:
+    id_path: "id"
+    name_path: "function.name"
+    input_path: "function.arguments"
+    input_format: "json_string"
+  notes:
+    - "Together AI tool_calls.function.arguments is typically a JSON string."
+
+features:
+  multi_candidate:
+    support_type: "native"
+    param_name: "n"
+  response_mapping:
+    tool_calls:
+      path: "choices[0].message.tool_calls"
+      fields:
+        id: "id"
+        name: "function.name"
+        args: "function.arguments"
+    error:
+      message_path: "error.message"
+      code_path: "error.code"
+      type_path: "error.type"
+
+response_paths:
+  content: "choices[0].message.content"
+  tool_calls: "choices[0].message.tool_calls"
+  usage: "usage"
+  finish_reason: "choices[0].finish_reason"
+
+parameter_mappings:
+  temperature: "temperature"
+  max_tokens: "max_tokens"
+  stream: "stream"
+  top_p: "top_p"
+  stop_sequences: "stop"
+  tools: "tools"
+  tool_choice: "tool_choice"
+
+retry_policy:
+  max_retries: 3
+  max_delay_ms: 30000
+  strategy: "exponential_backoff"
+  min_delay_ms: 1000
+  jitter: "full"
+  retry_on_http_status: [429, 500, 502, 503]
+
+error_classification:
+  by_http_status:
+    "400": "invalid_request"
+    "401": "authentication"
+    "429": "rate_limited"
+    "500": "server_error"
+    "503": "overloaded"