@ailib-official/ai-protocol 0.8.4

package/dist/v1/providers/gemini.json

@@ -0,0 +1,279 @@
+{
+  "$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",
+  "api_families": [
+    "generate_content"
+  ],
+  "default_api_family": "generate_content",
+  "endpoints": {
+    "chat": {
+      "path": "/models/{model}:generateContent",
+      "method": "POST",
+      "adapter": "gemini"
+    }
+  },
+  "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": {
+    "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": {
+    "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": {
+    "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: "
+    },
+    "frame_selector": "exists($.candidates) || exists($.error)",
+    "candidate": {
+      "candidate_id_path": "$.candidates[*].index",
+      "fan_out": true
+    },
+    "event_map": [
+      {
+        "match": "exists($.error)",
+        "emit": "StreamError",
+        "fields": {
+          "error": "$.error",
+          "model_version": "$.modelVersion"
+        }
+      },
+      {
+        "match": "exists($.candidates[*].content.parts[*].text)",
+        "emit": "PartialContentDelta",
+        "fields": {
+          "content": "$.candidates[*].content.parts[*].text"
+        }
+      },
+      {
+        "match": "exists($.candidates[*].content.parts[*].functionCall.name)",
+        "emit": "ToolCallStarted",
+        "fields": {
+          "tool_name": "$.candidates[*].content.parts[*].functionCall.name",
+          "tool_call_id": "_generate_uuid"
+        }
+      },
+      {
+        "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"
+        }
+      },
+      {
+        "match": "exists($.usageMetadata)",
+        "emit": "Metadata",
+        "fields": {
+          "usage": "$.usageMetadata",
+          "prompt_tokens": "$.usageMetadata.promptTokenCount",
+          "completion_tokens": "$.usageMetadata.candidatesTokenCount"
+        }
+      },
+      {
+        "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": {
+        "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/dist/v1/providers/groq.json

@@ -0,0 +1,218 @@
+{
+  "$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",
+  "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_calls.function.arguments is typically a JSON string; runtimes SHOULD parse it into an object when normalizing."
+    ]
+  },
+  "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": {
+    "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": [
+      {
+        "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": "$.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"
+  ]
+}

package/dist/v1/providers/huggingface.json

@@ -0,0 +1,181 @@
+{
+  "$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",
+  "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"
+  },
+  "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"
+    }
+  },
+  "services": {
+    "list_models": {
+      "path": "https://huggingface.co/api/models",
+      "method": "GET",
+      "response_binding": "null"
+    }
+  },
+  "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"
+    ]
+  },
+  "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": {
+    "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": {
+    "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": {
+    "model_id": "model"
+  },
+  "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}"
+    ]
+  }
+}