@ailib-official/ai-protocol 0.8.4

package/v1/providers/huggingface.yaml

@@ -0,0 +1,157 @@
+$schema: "https://raw.githubusercontent.com/ailib-official/ai-protocol/main/schemas/v1.json"
+
+id: huggingface
+protocol_version: "1.5"
+
+name: Hugging Face Inference
+version: "v1"
+status: stable
+category: model_provider
+official_url: "https://huggingface.co/docs/api-inference"
+support_contact: "https://huggingface.co/support"
+
+# Structured endpoint definition (v1.1+ extension)
+endpoint:
+  base_url: "https://api-inference.huggingface.co/models"
+  protocol: https
+  timeout_ms: 60000
+
+auth:
+  type: bearer
+  token_env: "HUGGINGFACE_API_KEY"
+  payload_format: "inference_api"
+
+# Hugging Face supports multiple inference modes
+api_families: ["text_generation", "image_generation", "embeddings", "audio"]
+default_api_family: "text_generation"
+endpoints:
+  chat:
+    path: "/{model_id}"
+    method: "POST"
+    adapter: "huggingface"
+  embeddings:
+    path: "/{model_id}"
+    method: "POST"
+    adapter: "huggingface"
+  image:
+    path: "/{model_id}"
+    method: "POST"
+    adapter: "huggingface"
+
+# V1.5 Service Endpoints
+services:
+  list_models:
+    path: "https://huggingface.co/api/models"
+    method: "GET"
+    response_binding: "null"
+
+# Termination reason normalization
+termination:
+  source_field: "finish_reason"
+  mapping:
+    stop: "end_turn"
+    length: "max_tokens"
+  notes:
+    - "finish_reason varies by model"
+    - "not all models support explicit finish_reason"
+
+# Tool invocation normalization
+tooling:
+  source_model: "unknown"
+  notes:
+    - "Hugging Face serverless inference does not natively support tool calling"
+    - "Deployed custom models may implement tool calling via custom logic"
+
+# 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:
+    - "Hugging Face free tier has cold starts; retry recommended"
+    - "503 is common during model loading"
+
+# 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"
+    "503": "overloaded"
+  notes:
+    - "503 often indicates model is loading (cold start)"
+    - "404 may indicate model not found or removed"
+
+parameter_mappings:
+  temperature: "temperature"
+  max_tokens: "max_new_tokens"
+  stream: "stream"
+  top_p: "top_p"
+  stop_sequences: "stop"
+  top_k: "top_k"
+  repetition_penalty: "repetition_penalty"
+
+response_format: "huggingface_style"
+response_paths:
+  content: "output_text"
+  generated_text: "generated_text"
+  usage: "details"
+
+streaming:
+  event_format: "inference_api"
+  decoder:
+    format: "sse"
+    delimiter: "\n"
+    prefix: ""
+    done_signal: ""
+  frame_selector: "exists($.token) || exists($.generated_text)"
+  event_map:
+    - match: "exists($.token)"
+      emit: "PartialContentDelta"
+      fields:
+        content: "$.token.text"
+        token_id: "$.token.id"
+    - match: "exists($.generated_text)"
+      emit: "FinalCandidate"
+      fields:
+        content: "$.generated_text"
+  stop_condition: "exists($.finish_reason) || length > 0 && !exists($.token)"
+  extra_metadata_path: "$.details"
+  content_path: "$.output_text"
+
+capabilities:
+  streaming: true
+  tools: false
+  vision: true
+  agentic: false
+  parallel_tools: false
+  reasoning: false
+
+experimental_features:
+  - "model_selection"
+  - "serverless_inference"
+  - "custom_deployment"
+
+# Connection vars for dynamic model selection
+connection_vars:
+  model_id: "model"
+
+# Availability and health checking (v1.1+ extension)
+availability:
+  required: false
+  regions:
+    - global
+  check:
+    method: GET
+    path: "/meta-llama/Llama-2-7b-chat-hf"
+    expected_status: [200]
+    timeout_ms: 5000
+  notes:
+    - "Check against a popular model (Llama-2) to verify service availability"
+    - "Model-specific endpoint: /models/{model_id}"

package/v1/providers/hunyuan.yaml

@@ -0,0 +1,162 @@
+$schema: "https://raw.githubusercontent.com/ailib-official/ai-protocol/main/schemas/v1.json"
+
+id: hunyuan
+protocol_version: "1.5"
+
+name: 腾讯混元 (Tencent Hunyuan)
+version: "v1"
+status: stable
+category: ai_provider
+official_url: "https://cloud.tencent.com/document/product/1729"
+support_contact: "https://cloud.tencent.com/online-service"
+
+endpoint:
+  base_url: "https://hunyuan.tencentcloudapi.com"
+  protocol: https
+  timeout_ms: 60000
+
+auth:
+  type: bearer
+  token_env: "HUNYUAN_API_KEY"
+
+payload_format: "openai_style"
+
+# Hunyuan supports OpenAI-compatible API
+api_families: ["chat_completions"]
+default_api_family: "chat_completions"
+
+endpoints:
+  chat:
+    path: "/v1/chat/completions"
+    method: "POST"
+    adapter: "openai"
+
+termination:
+  source_field: "finish_reason"
+  mapping:
+    stop: "end_turn"
+    length: "max_tokens"
+    tool_calls: "tool_use"
+    sensitive: "refusal"
+  notes:
+    - "OpenAI-compatible finish_reason."
+    - "混元大模型 (Hunyuan) is Tencent's flagship LLM."
+
+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"
+  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: "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: true
+
+availability:
+  required: false
+  regions:
+    - cn
+  check:
+    method: GET
+    path: "/v1/models"
+    expected_status: [200, 401]
+    timeout_ms: 5000
+
+experimental_features:
+  - "search_enhancement"
+  - "image_understanding"
+  - "role_play"

package/v1/providers/jina.yaml

@@ -0,0 +1,171 @@
+$schema: "https://raw.githubusercontent.com/ailib-official/ai-protocol/main/schemas/v1.json"
+
+id: jina
+protocol_version: "1.5"
+
+name: Jina AI
+version: "v1"
+status: stable
+category: ai_provider
+official_url: "https://jina.ai/docs"
+support_contact: "https://jina.ai/contact"
+
+# Structured endpoint definition (v1.1+ extension)
+endpoint:
+  base_url: "https://api.jina.ai"
+  protocol: https
+  timeout_ms: 30000
+
+auth:
+  type: bearer
+  token_env: "JINA_API_KEY"
+  payload_format: "jina_api"
+
+# Jina AI supports embeddings and search APIs
+api_families: ["embeddings", "rerank", "reader", "search"]
+default_api_family: "embeddings"
+endpoints:
+  embeddings:
+    path: "/v1/embeddings"
+    method: "POST"
+    adapter: "openai"
+  rerank:
+    path: "/v1/rerank"
+    method: "POST"
+    adapter: "jina"
+  reader:
+    path: "/v1/reader"
+    method: "POST"
+    adapter: "jina"
+
+# V1.5 Service Endpoints
+services:
+  list_models:
+    path: "/v1/models"
+    method: "GET"
+    response_binding: "data"
+
+# Termination reason normalization
+termination:
+  source_field: "finish_reason"
+  mapping:
+    stop: "end_turn"
+    length: "max_tokens"
+  notes:
+    - "Jina Reader uses finish_reason for completion"
+    - "Embeddings API does not use finish_reason"
+
+# Tool invocation normalization
+tooling:
+  source_model: "unknown"
+  notes:
+    - "Jina AI is primarily embeddings and search"
+    - "Does not support traditional tool calling"
+
+# Retry policy
+retry_policy:
+  strategy: "exponential_backoff"
+  max_retries: 3
+  max_delay_ms: 30000
+  min_delay_ms: 1000
+  jitter: "full"
+  retry_on_http_status: [429, 500, 502, 503]
+  notes:
+    - "Jina API is generally fast but may experience spikes"
+    - "Exponential backoff recommended for rate limits"
+
+# 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:
+    - "Jina returns clear error messages in JSON format"
+    - "Rate limit info included in error responses"
+
+parameter_mappings:
+  model: "model"
+  input: "input"
+  encoding_format: "encoding_format"
+  dimensions: "dimensions"
+  top_n: "top_n"
+  query: "query"
+  documents: "documents"
+  return_documents: "return_documents"
+  url: "url"
+  question: "question"
+
+response_format: "jina_style"
+response_paths:
+  content: "output"
+  embedding: "data.embedding"
+  data: "data"
+  results: "results"
+
+streaming:
+  event_format: "jina_stream"
+  decoder:
+    format: "sse"
+    delimiter: "\n\n"
+    prefix: "data: "
+    done_signal: "[DONE]"
+  frame_selector: "exists($.delta) || exists($.embedding) || exists($.results)"
+  event_map:
+    - match: "exists($.delta)"
+      emit: "PartialContentDelta"
+      fields:
+        content: "$.delta.content"
+    - match: "exists($.embedding)"
+      emit: "Metadata"
+      fields:
+        embedding: "$.embedding"
+        index: "$.index"
+    - match: "exists($.results)"
+      emit: "FinalCandidate"
+      fields:
+        results: "$.results"
+  stop_condition: "exists($.finish_reason) || exists($.results)"
+  extra_metadata_path: "$.usage"
+
+features:
+  multi_candidate:
+    support_type: "native"
+    param_name: "top_n"
+  response_mapping:
+    error:
+      message_path: "message"
+      code_path: "code"
+      type_path: "error"
+
+capabilities:
+  streaming: false
+  tools: false
+  vision: false
+  agentic: false
+  parallel_tools: false
+  reasoning: false
+
+experimental_features:
+  - "rerank_api"
+  - "reader_api"
+  - "multimodal_embeddings"
+  - "code_embeddings"
+
+# Availability and health checking (v1.1+ extension)
+availability:
+  required: false
+  regions:
+    - global
+  check:
+    method: GET
+    path: "/v1/models"
+    expected_status: [200]
+    timeout_ms: 3000
+  notes:
+    - "Check v1/models endpoint to verify service health"

package/v1/providers/lepton.yaml

@@ -0,0 +1,183 @@
+$schema: "https://raw.githubusercontent.com/ailib-official/ai-protocol/main/schemas/v1.json"
+
+id: lepton
+protocol_version: "1.5"
+
+name: Lepton AI
+version: "v1"
+status: stable
+category: ai_provider
+official_url: "https://www.lepton.ai/docs"
+support_contact: "https://www.lepton.ai/contact"
+
+endpoint:
+  base_url: "https://llama3-1-8b.lepton.run/api/v1"
+  protocol: https
+  timeout_ms: 30000
+
+# Dynamic base URL template for different models
+base_url_template: "https://{model_id}.lepton.run/api/v1"
+
+auth:
+  type: bearer
+  token_env: "LEPTON_API_TOKEN"
+
+payload_format: "openai_style"
+
+# OpenAI-compatible API
+api_families: ["chat_completions", "completions"]
+default_api_family: "chat_completions"
+
+endpoints:
+  chat:
+    path: "/chat/completions"
+    method: "POST"
+    adapter: "openai"
+  completions:
+    path: "/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."
+
+tooling:
+  source_model: "openai_tool_calls"
+  tool_use:
+    id_path: "id"
+    name_path: "function.name"
+    input_path: "function.arguments"
+    input_format: "json_string"
+  notes:
+    - "OpenAI-compatible tool calling for supported models."
+
+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]
+  notes:
+    - "Standard exponential backoff for rate limits and transient errors."
+
+error_classification:
+  by_http_status:
+    "400": "invalid_request"
+    "401": "authentication"
+    "403": "permission_denied"
+    "404": "not_found"
+    "429": "rate_limited"
+    "500": "server_error"
+    "502": "server_error"
+    "503": "overloaded"
+
+parameter_mappings:
+  temperature: "temperature"
+  max_tokens: "max_tokens"
+  stream: "stream"
+  top_p: "top_p"
+  stop_sequences: "stop"
+  frequency_penalty: "frequency_penalty"
+  presence_penalty: "presence_penalty"
+  tools: "tools"
+  tool_choice: "tool_choice"
+  seed: "seed"
+  top_k: "top_k"
+
+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"
+        candidate_index: "$.choices[*].index"
+  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"
+      type_path: "error.type"
+
+capabilities:
+  streaming: true
+  tools: true
+  vision: true
+  agentic: true
+  parallel_tools: true
+  reasoning: false
+
+availability:
+  required: false
+  regions:
+    - global
+  check:
+    method: GET
+    path: "/models"
+    expected_status: [200, 401]
+    timeout_ms: 5000
+
+experimental_features:
+  - "photon_deployment"
+  - "auto_scaling"
+  - "custom_models"