@ailib-official/ai-protocol 0.8.4

package/v1/providers/fireworks.yaml

@@ -0,0 +1,187 @@
+$schema: "https://raw.githubusercontent.com/ailib-official/ai-protocol/main/schemas/v1.json"
+
+id: fireworks
+protocol_version: "1.5"
+
+name: Fireworks AI
+version: "v1"
+status: stable
+category: ai_provider
+official_url: "https://docs.fireworks.ai"
+support_contact: "https://fireworks.ai/contact"
+
+endpoint:
+  base_url: "https://api.fireworks.ai/inference/v1"
+  protocol: https
+  timeout_ms: 30000
+
+auth:
+  type: bearer
+  token_env: "FIREWORKS_API_KEY"
+
+payload_format: "openai_style"
+
+# OpenAI-compatible API families
+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"
+    content_filter: "refusal"
+  notes:
+    - "OpenAI-compatible: finish_reason is reported per candidate."
+
+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 format."
+
+rate_limit_headers:
+  requests_limit: "x-ratelimit-limit-requests"
+  requests_remaining: "x-ratelimit-remaining-requests"
+  tokens_limit: "x-ratelimit-limit-tokens"
+  tokens_remaining: "x-ratelimit-remaining-tokens"
+
+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:
+    - "Fireworks AI uses standard rate limiting with exponential backoff."
+
+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:
+  - "function_calling"
+  - "json_mode"
+  - "serverless_inference"

package/v1/providers/gemini.yaml

@@ -0,0 +1,229 @@
+$schema: "https://raw.githubusercontent.com/ailib-official/ai-protocol/main/schemas/v1.json"
+
+id: gemini
+protocol_version: "1.5"
+
+name: Google Gemini
+version: "v1beta"
+status: stable
+category: ai_provider
+official_url: "https://ai.google.dev/docs"
+support_contact: "https://support.google.com/gemini"
+
+endpoint:
+  base_url: "https://generativelanguage.googleapis.com/v1beta"
+  protocol: https
+  timeout_ms: 10000
+auth:
+  type: query_param
+  param_name: "key"
+  token_env: "GEMINI_API_KEY"
+payload_format: "gemini_style"
+
+# Gemini native API families
+api_families: ["generate_content"]
+default_api_family: "generate_content"
+endpoints:
+  chat:
+    path: "/models/{model}:generateContent"
+    method: "POST"
+    adapter: "gemini"
+
+# V1.5 Service Endpoints
+services:
+  list_models:
+    path: "/models"
+    method: "GET"
+    response_binding: "models"
+  list_files:
+    path: "/files"
+    method: "GET"
+    response_binding: "files"
+  get_model:
+    path: "/models/{model}"
+    method: "GET"
+termination:
+  # Gemini response field is typically named finishReason (provider-defined enum).
+  source_field: "finishReason"
+  mapping:
+    FINISH_REASON_UNSPECIFIED: "other"
+    STOP: "end_turn"
+    MAX_TOKENS: "max_tokens"
+    SAFETY: "refusal"
+    RECITATION: "refusal"
+    LANGUAGE: "refusal"
+    OTHER: "other"
+    BLOCKLIST: "refusal"
+    PROHIBITED_CONTENT: "refusal"
+    SPII: "refusal"
+    MALFORMED_FUNCTION_CALL: "other"
+    IMAGE_SAFETY: "refusal"
+    IMAGE_PROHIBITED_CONTENT: "refusal"
+    IMAGE_OTHER: "other"
+    NO_IMAGE: "other"
+    IMAGE_RECITATION: "refusal"
+    UNEXPECTED_TOOL_CALL: "other"
+    TOO_MANY_TOOL_CALLS: "other"
+    MISSING_THOUGHT_SIGNATURE: "other"
+  notes:
+    - "finishReason enum is VERIFIED in research/providers/gemini.md (from official generate-content reference)."
+    - "STOP covers both natural stop and provided stop sequence; this mapping chooses end_turn because stop_sequence cannot be distinguished from finishReason alone."
+tooling:
+  source_model: "gemini_function_call"
+  tool_use:
+    name_path: "functionCall.name"
+    input_path: "functionCall.args"
+    input_format: "json_object"
+  tool_result:
+    id_path: "functionResponse.id"
+    name_path: "functionResponse.name"
+    response_path: "functionResponse.response"
+    output_path: "functionResponse.response.output"
+    error_path: "functionResponse.response.error"
+    format: "json_object"
+  notes:
+    - "Gemini represents tool invocations via functionCall in content parts; normalization to tool_use/tool_result should follow the runtime's part-parsing logic."
+
+# Retry policy (VERIFIED evidence in research/providers/gemini.md via Vertex AI errors docs)
+retry_policy:
+  strategy: "exponential_backoff"
+  max_retries: 2
+  min_delay_ms: 1000
+  max_delay_ms: 8000
+  jitter: "full"
+  retry_on_http_status: [429, 503, 504]
+  retry_on_error_status: ["RESOURCE_EXHAUSTED", "UNAVAILABLE", "DEADLINE_EXCEEDED"]
+  notes:
+    - "On 429/RESOURCE_EXHAUSTED: retry after a few seconds; recommend no more than two retries; min 1s with exponential backoff."
+
+# Error classification hints (see v1/spec.yaml: standard_schema.error_handling.error_classes)
+error_classification:
+  by_http_status:
+    "400": "invalid_request"
+    "403": "permission_denied"
+    "404": "not_found"
+    "429": "rate_limited"
+    "499": "cancelled"
+    "500": "server_error"
+    "503": "overloaded"
+    "504": "timeout"
+  by_error_status:
+    "INVALID_ARGUMENT": "invalid_request"
+    "FAILED_PRECONDITION": "invalid_request"
+    "PERMISSION_DENIED": "permission_denied"
+    "NOT_FOUND": "not_found"
+    "RESOURCE_EXHAUSTED": "rate_limited"
+    "CANCELLED": "cancelled"
+    "UNKNOWN": "server_error"
+    "INTERNAL": "server_error"
+    "UNAVAILABLE": "overloaded"
+    "DEADLINE_EXCEEDED": "timeout"
+  notes:
+    - "Vertex/Gemini follows the Google Cloud API error model; prefer mapping by canonical error.status when present."
+parameter_mappings:
+  temperature: "generationConfig.temperature"
+  max_tokens: "generationConfig.maxOutputTokens"
+  top_p: "generationConfig.topP"
+  top_k: "generationConfig.topK"
+  stop_sequences: "stopSequences"
+  tools: "tools"
+  tool_choice: "toolConfig"
+response_format: "gemini_style"
+response_paths:
+  content: "candidates[0].content.parts[0].text"
+  tool_calls: "candidates[0].content.parts[0].functionCall"
+  usage: "usageMetadata"
+  finish_reason: "candidates[0].finishReason"
+streaming:
+  event_format: "sse_data_lines"
+  decoder:
+    format: "sse"
+    delimiter: "\n\n"
+    prefix: "data: "
+  # Stream may contain normal candidate frames or error frames.
+  frame_selector: "exists($.candidates) || exists($.error)"
+  candidate:
+    candidate_id_path: "$.candidates[*].index"
+    fan_out: true
+  event_map:
+    # Stream-level error delivered as SSE data JSON
+    - match: "exists($.error)"
+      emit: "StreamError"
+      fields:
+        error: "$.error"
+        model_version: "$.modelVersion"
+    # Text content (supports multi-candidate via array fan-out)
+    - match: "exists($.candidates[*].content.parts[*].text)"
+      emit: "PartialContentDelta"
+      fields:
+        content: "$.candidates[*].content.parts[*].text"
+    # Function call start (Gemini returns complete function call in one chunk)
+    - match: "exists($.candidates[*].content.parts[*].functionCall.name)"
+      emit: "ToolCallStarted"
+      fields:
+        tool_name: "$.candidates[*].content.parts[*].functionCall.name"
+        tool_call_id: "_generate_uuid"
+    # Function call arguments
+    - match: "exists($.candidates[*].content.parts[*].functionCall.args)"
+      emit: "PartialToolCall"
+      fields:
+        arguments: "$.candidates[*].content.parts[*].functionCall.args"
+        tool_name: "$.candidates[*].content.parts[*].functionCall.name"
+        tool_call_id: "_generate_uuid"
+    # Usage metadata
+    - match: "exists($.usageMetadata)"
+      emit: "Metadata"
+      fields:
+        usage: "$.usageMetadata"
+        prompt_tokens: "$.usageMetadata.promptTokenCount"
+        completion_tokens: "$.usageMetadata.candidatesTokenCount"
+    # Finish with reason
+    - match: "exists($.candidates[*].finishReason)"
+      emit: "FinalCandidate"
+      fields:
+        finish_reason: "$.candidates[*].finishReason"
+        candidate_index: "$.candidates[*].index"
+  stop_condition: "exists($.candidates[*].finishReason)"
+  extra_metadata_path: "$.usageMetadata"
+  content_path: "candidates[0].content.parts[0].text"
+  tool_call_path: "candidates[0].content.parts[0].functionCall.args"
+features:
+  multi_candidate:
+    support_type: "native"
+    param_name: "candidateCount"
+  response_mapping:
+    tool_calls:
+      path: "candidates[0].content.parts"
+      filter: "exists(functionCall)"
+      fields:
+        id: "_generate_uuid"
+        name: "functionCall.name"
+        args: "functionCall.args"
+        id_strategy: "generate_uuid"
+      array_fan_out: true
+    error:
+      # Vertex / Gemini HTTP error envelope: { "error": { code, message, status, errors[] } }
+      message_path: "error.message"
+      code_path: "error.code"
+      status_path: "error.status"
+      errors_path: "error.errors"
+capabilities:
+  streaming: true
+  tools: true
+  vision: true
+  agentic: false
+  parallel_tools: false
+  reasoning: false
+
+availability:
+  required: false
+  regions:
+    - global
+  check:
+    method: GET
+    path: "/models"
+    expected_status: [200, 401]
+    timeout_ms: 3000
+experimental_features:
+  - "multimodal_video"
+  - "multimodal_audio"

package/v1/providers/groq.yaml

@@ -0,0 +1,181 @@
+$schema: "https://raw.githubusercontent.com/ailib-official/ai-protocol/main/schemas/v1.json"
+
+id: groq
+protocol_version: "1.5"
+
+name: Groq
+version: "v1"
+status: stable
+category: ai_provider
+official_url: "https://console.groq.com/docs"
+support_contact: "https://support.groq.com"
+
+endpoint:
+  base_url: "https://api.groq.com/openai/v1"
+  protocol: https
+  timeout_ms: 10000
+auth:
+  type: bearer
+  token_env: "GROQ_API_KEY"
+payload_format: "openai_style"
+
+# OpenAI-compatible API families
+api_families: ["chat_completions", "completions"]
+default_api_family: "chat_completions"
+endpoints:
+  # Runtime uses UnifiedRequest.operation (currently "chat") to resolve endpoints.
+  # Keep keys aligned with runtime expectations.
+  chat:
+    path: "/chat/completions"
+    method: "POST"
+    adapter: "openai"
+  completions:
+    path: "/completions"
+    method: "POST"
+    adapter: "openai"
+
+# Optional service endpoints (OpenAI-compatible).
+services:
+  list_models:
+    path: "/models"
+    method: "GET"
+    response_binding: "data"
+
+# Termination reason normalization (see v1/spec.yaml: standard_schema.streaming_events.termination_reasons)
+termination:
+  source_field: "finish_reason"
+  mapping:
+    stop: "end_turn"
+    length: "max_tokens"
+    tool_calls: "tool_use"
+    content_filter: "refusal"
+  notes:
+    - "OpenAI-compatible: finish_reason is reported per candidate."
+
+# Tool invocation normalization (see v1/spec.yaml: standard_schema.content_blocks)
+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_calls.function.arguments is typically a JSON string; runtimes SHOULD parse it into an object when normalizing."
+
+# Rate limits (OpenAI-compatible; see OpenAI rate limits guide)
+rate_limit_headers:
+  requests_limit: "x-ratelimit-limit-requests"
+  requests_remaining: "x-ratelimit-remaining-requests"
+  requests_reset: "x-ratelimit-reset-requests"
+  tokens_limit: "x-ratelimit-limit-tokens"
+  tokens_remaining: "x-ratelimit-remaining-tokens"
+  tokens_reset: "x-ratelimit-reset-tokens"
+  retry_after: "retry-after"
+
+# Retry policy (OpenAI-compatible guidance: exponential backoff for 429; retry 5xx after brief wait)
+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]
+  notes:
+    - "OpenAI-compatible: exponential backoff is recommended for rate limit errors (429)."
+    - "Retry 500 after a brief wait."
+parameter_mappings:
+  temperature: "temperature"
+  max_tokens: "max_tokens"
+  stream: "stream"
+  stop_sequences: "stop"
+  tools: "tools"
+  tool_choice: "tool_choice"
+  frequency_penalty: "frequency_penalty"
+  presence_penalty: "presence_penalty"
+  logprobs: "logprobs"
+  top_logprobs: "top_logprobs"
+  seed: "seed"
+response_format: "openai_style"
+response_paths:
+  content: "choices[0].message.content"
+  tool_calls: "choices[0].message.tool_calls"
+  usage: "usage"
+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:
+    # Text content delta
+    - match: "exists($.choices[*].delta.content)"
+      emit: "PartialContentDelta"
+      fields:
+        content: "$.choices[*].delta.content"
+    # Tool call start
+    - 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"
+    # Tool call arguments streaming
+    - match: "exists($.choices[*].delta.tool_calls[*].function.arguments)"
+      emit: "PartialToolCall"
+      fields:
+        arguments: "$.choices[*].delta.tool_calls[*].function.arguments"
+        index: "$.choices[*].delta.tool_calls[*].index"
+    # Usage metadata
+    - match: "exists($.usage)"
+      emit: "Metadata"
+      fields:
+        usage: "$.usage"
+    # Stream end with finish reason
+    - match: "$.choices[*].finish_reason != null"
+      emit: "StreamEnd"
+      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"
+      type_path: "error.type"
+      param_path: "error.param"
+capabilities:
+  streaming: true
+  tools: true
+  vision: false
+  agentic: true
+  parallel_tools: true
+  reasoning: false
+
+availability:
+  required: false
+  regions:
+    - global
+  check:
+    method: GET
+    path: "/models"
+    expected_status: [200, 401]
+    timeout_ms: 3000
+experimental_features:
+  - "builtin_search"
+  - "code_execution"
+  - "fast_inference"