@ailib-official/ai-protocol 0.8.4

package/schemas/v2/provider-contract.json

@@ -0,0 +1,317 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/ailib-official/ai-protocol/main/schemas/v2/provider-contract.json",
+  "title": "AI-Protocol V2 Provider Contract",
+  "description": "Defines the runtime contract between AI-Protocol and provider implementations. Specifies capability matrices, request/response mapping, degradation strategies, and API behavioral guarantees. This schema drives the ProviderDriver abstraction in both Rust and Python runtimes.",
+  "type": "object",
+  "required": ["contract_version", "provider_id", "api_style", "request_mapping", "response_mapping"],
+  "properties": {
+    "contract_version": {
+      "type": "string",
+      "const": "1.0",
+      "description": "Contract schema version"
+    },
+    "provider_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-_]{1,63}$",
+      "description": "Must match the provider manifest id"
+    },
+    "api_style": {
+      "type": "string",
+      "enum": ["openai_compatible", "anthropic_messages", "gemini_generate", "custom"],
+      "description": "Primary API style determines the base request/response transformation"
+    },
+    "api_version": {
+      "type": "string",
+      "description": "Provider API version string (e.g. '2023-06-01' for Anthropic)"
+    },
+    "request_mapping": {
+      "type": "object",
+      "description": "How to transform a UnifiedRequest into provider-specific format",
+      "required": ["message_format", "role_mapping"],
+      "properties": {
+        "message_format": {
+          "type": "string",
+          "enum": ["openai_messages", "anthropic_messages", "gemini_contents", "custom"],
+          "description": "Message array format style"
+        },
+        "role_mapping": {
+          "type": "object",
+          "description": "Maps AI-Protocol roles to provider-specific roles",
+          "properties": {
+            "system": { "type": "string", "default": "system" },
+            "user": { "type": "string", "default": "user" },
+            "assistant": { "type": "string", "default": "assistant" },
+            "tool": { "type": "string", "default": "tool" }
+          },
+          "additionalProperties": { "type": "string" }
+        },
+        "system_message_handling": {
+          "type": "string",
+          "enum": ["inline", "top_level_field", "prepend_to_user", "not_supported"],
+          "default": "inline",
+          "description": "How system messages are placed: inline in messages array, as a top-level 'system' field, prepended to first user message, or not supported"
+        },
+        "content_block_mapping": {
+          "type": "object",
+          "description": "Maps ContentBlock types to provider format",
+          "properties": {
+            "text": {
+              "type": "object",
+              "properties": {
+                "field": { "type": "string", "default": "content" },
+                "wrapper": { "type": "string", "enum": ["string", "array_of_parts", "content_blocks"] }
+              }
+            },
+            "image": {
+              "type": "object",
+              "properties": {
+                "format": { "type": "string", "enum": ["openai_url", "anthropic_source", "gemini_inline_data"] },
+                "base64_field": { "type": "string" },
+                "url_field": { "type": "string" }
+              }
+            },
+            "audio": {
+              "type": "object",
+              "properties": {
+                "format": { "type": "string" },
+                "supported": { "type": "boolean", "default": false }
+              }
+            },
+            "video": {
+              "type": "object",
+              "properties": {
+                "format": { "type": "string" },
+                "supported": { "type": "boolean", "default": false }
+              }
+            },
+            "tool_use": {
+              "type": "object",
+              "properties": {
+                "format": { "type": "string", "enum": ["openai_tool_calls", "anthropic_tool_use", "gemini_function_call"] },
+                "id_field": { "type": "string" },
+                "name_field": { "type": "string" },
+                "arguments_field": { "type": "string" }
+              }
+            },
+            "tool_result": {
+              "type": "object",
+              "properties": {
+                "format": { "type": "string", "enum": ["openai_tool_message", "anthropic_tool_result", "gemini_function_response"] },
+                "id_field": { "type": "string" },
+                "content_field": { "type": "string" }
+              }
+            }
+          },
+          "additionalProperties": false
+        },
+        "parameter_aliases": {
+          "type": "object",
+          "description": "Maps unified parameter names to provider-specific names",
+          "additionalProperties": { "type": "string" }
+        },
+        "required_headers": {
+          "type": "array",
+          "description": "Headers that must be included in every request",
+          "items": {
+            "type": "object",
+            "required": ["name", "value"],
+            "properties": {
+              "name": { "type": "string" },
+              "value": { "type": "string" },
+              "condition": { "type": "string", "description": "Capability condition (e.g. 'computer_use', 'mcp')" }
+            }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "response_mapping": {
+      "type": "object",
+      "description": "How to extract unified response from provider-specific format",
+      "required": ["content_path", "finish_reason_path"],
+      "properties": {
+        "content_path": {
+          "type": "string",
+          "description": "JSONPath to extract text content from non-streaming response"
+        },
+        "finish_reason_path": {
+          "type": "string",
+          "description": "JSONPath to extract finish reason"
+        },
+        "usage_path": {
+          "type": "string",
+          "description": "JSONPath to extract token usage"
+        },
+        "tool_calls_path": {
+          "type": "string",
+          "description": "JSONPath to extract tool calls"
+        },
+        "finish_reason_mapping": {
+          "type": "object",
+          "description": "Maps provider finish reasons to unified reasons",
+          "additionalProperties": { "type": "string" }
+        },
+        "error_extraction": {
+          "type": "object",
+          "properties": {
+            "type_path": { "type": "string" },
+            "message_path": { "type": "string" },
+            "code_path": { "type": "string" }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "capability_contracts": {
+      "type": "object",
+      "description": "Per-capability behavioral contracts and feature negotiation",
+      "properties": {
+        "streaming": {
+          "type": "object",
+          "properties": {
+            "protocol": { "type": "string", "enum": ["sse", "ndjson", "websocket"] },
+            "supports_usage_in_stream": { "type": "boolean", "default": false },
+            "supports_tool_streaming": { "type": "boolean", "default": false },
+            "done_signal": { "type": "string" }
+          }
+        },
+        "tools": {
+          "type": "object",
+          "properties": {
+            "definition_format": { "type": "string", "enum": ["openai_functions", "anthropic_tools", "gemini_declarations"] },
+            "supports_parallel": { "type": "boolean", "default": false },
+            "supports_forced_tool": { "type": "boolean", "default": false },
+            "max_tools": { "type": "integer" }
+          }
+        },
+        "structured_output": {
+          "type": "object",
+          "properties": {
+            "json_mode": { "type": "boolean", "default": false },
+            "json_schema_mode": { "type": "boolean", "default": false },
+            "response_format_field": { "type": "string" }
+          }
+        },
+        "mcp": {
+          "type": "object",
+          "properties": {
+            "integration_method": { "type": "string", "enum": ["native_api", "tool_bridge", "not_supported"] },
+            "tool_injection_format": { "type": "string" },
+            "requires_beta_header": { "type": "string" }
+          }
+        },
+        "computer_use": {
+          "type": "object",
+          "properties": {
+            "integration_method": { "type": "string", "enum": ["native_tool", "sdk_config", "not_supported"] },
+            "action_format": { "type": "string" },
+            "requires_beta_header": { "type": "string" }
+          }
+        },
+        "generative": {
+          "type": "object",
+          "description": "Generative LLM capability contract for token reporting, reasoning, and output modes",
+          "properties": {
+            "token_usage_format": {
+              "type": "string",
+              "enum": ["openai_usage", "anthropic_usage", "gemini_usage", "custom"],
+              "description": "Provider-specific token usage response format"
+            },
+            "token_usage_fields": {
+              "type": "object",
+              "description": "JSONPath mappings for token usage extraction",
+              "properties": {
+                "prompt_tokens": { "type": "string" },
+                "completion_tokens": { "type": "string" },
+                "total_tokens": { "type": "string" },
+                "reasoning_tokens": { "type": "string" },
+                "cache_read_tokens": { "type": "string" },
+                "cache_creation_tokens": { "type": "string" }
+              },
+              "additionalProperties": { "type": "string" }
+            },
+            "reasoning_mode": {
+              "type": "object",
+              "description": "Extended thinking / reasoning mode contract",
+              "properties": {
+                "supported": { "type": "boolean", "default": false },
+                "activation_method": {
+                  "type": "string",
+                  "enum": ["parameter", "header", "model_suffix", "not_supported"],
+                  "description": "How to activate reasoning/thinking mode"
+                },
+                "activation_field": { "type": "string", "description": "Field name or header to set" },
+                "thinking_block_format": {
+                  "type": "string",
+                  "enum": ["content_block", "separate_field", "interleaved"],
+                  "description": "How thinking content appears in response"
+                },
+                "supports_streaming_thinking": { "type": "boolean", "default": false }
+              }
+            },
+            "context_window_contract": {
+              "type": "object",
+              "description": "Context window limits and overflow behavior",
+              "properties": {
+                "max_context_tokens_field": { "type": "string", "description": "Where max context is declared per model" },
+                "overflow_error_code": { "type": "string", "description": "Provider error code for context overflow" },
+                "overflow_ai_protocol_code": { "type": "string", "default": "E1003", "description": "AI-Protocol error code mapping" }
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "degradation": {
+      "type": "object",
+      "description": "Defines graceful degradation when capabilities are unavailable",
+      "properties": {
+        "strategy": {
+          "type": "string",
+          "enum": ["error", "fallback", "silent_skip"],
+          "default": "error",
+          "description": "Default degradation strategy"
+        },
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["capability", "action"],
+            "properties": {
+              "capability": { "type": "string" },
+              "action": {
+                "type": "string",
+                "enum": ["error", "fallback_text", "strip_content", "convert_to_text"]
+              },
+              "message": { "type": "string", "description": "Human-readable degradation message" }
+            }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "rate_limit_contract": {
+      "type": "object",
+      "description": "Rate limit behavioral contract",
+      "properties": {
+        "supports_header_parsing": { "type": "boolean", "default": false },
+        "retry_after_source": { "type": "string", "enum": ["header", "body", "none"] },
+        "quota_tracking": { "type": "boolean", "default": false }
+      }
+    },
+    "authentication_contract": {
+      "type": "object",
+      "description": "Authentication behavioral contract",
+      "properties": {
+        "method": { "type": "string", "enum": ["bearer", "api_key_header", "query_param", "oauth2"] },
+        "token_refresh": { "type": "boolean", "default": false },
+        "multi_key_support": { "type": "boolean", "default": false }
+      }
+    }
+  },
+  "additionalProperties": false
+}
+

package/schemas/v2/provider.json

@@ -0,0 +1,203 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/ailib-official/ai-protocol/main/schemas/v2/provider.json",
+  "title": "AI Protocol V2 Provider Manifest",
+  "description": "Complete provider manifest schema for AI-Protocol V2. Supports the three-ring concentric circle model: Ring 1 (Core Skeleton), Ring 2 (Capability Mapping), Ring 3 (Advanced Extensions).",
+  "type": "object",
+  "required": [
+    "id",
+    "protocol_version",
+    "endpoint",
+    "error_classification",
+    "capabilities"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Schema reference URL"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-_]{1,63}$",
+      "description": "Stable provider identifier (lowercase, alphanumeric, hyphens, underscores)"
+    },
+    "protocol_version": {
+      "type": "string",
+      "description": "AI-Protocol version this manifest conforms to"
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable provider name"
+    },
+    "version": {
+      "type": "string",
+      "description": "Provider API version"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["stable", "beta", "deprecated"],
+      "default": "stable",
+      "description": "Provider status"
+    },
+    "category": {
+      "type": "string",
+      "enum": ["ai_provider", "model_provider", "third_party_aggregator"],
+      "description": "Provider category"
+    },
+    "official_url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Official documentation website"
+    },
+    "support_contact": {
+      "type": "string",
+      "format": "uri",
+      "description": "Support or feedback link"
+    },
+    "endpoint": {
+      "$ref": "./endpoint.json"
+    },
+    "availability": {
+      "$ref": "./availability.json"
+    },
+    "capabilities": {
+      "$ref": "./capabilities.json"
+    },
+    "error_classification": {
+      "type": "object",
+      "description": "Error classification mappings for this provider",
+      "properties": {
+        "by_http_status": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "by_error_code": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        },
+        "retry_after_extraction": {
+          "type": "object",
+          "description": "Optional pattern to extract Retry-After from error response body when header is absent",
+          "properties": {
+            "pattern": { "type": "string", "description": "Regex with capture group for numeric value" },
+            "unit": { "type": "string", "enum": ["seconds", "milliseconds"], "default": "seconds" }
+          }
+        },
+        "notes": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "parameters": {
+      "type": "object",
+      "description": "Standard parameter definitions for this provider",
+      "additionalProperties": true
+    },
+    "streaming": {
+      "type": "object",
+      "description": "Streaming configuration (decoder, event_map, accumulator, candidate)",
+      "additionalProperties": true
+    },
+    "api_families": {
+      "oneOf": [
+        { "type": "array", "items": { "type": "string" } },
+        { "type": "object", "additionalProperties": true }
+      ],
+      "description": "API family declarations"
+    },
+    "default_api_family": {
+      "type": "string",
+      "description": "Default API family to use"
+    },
+    "endpoints": {
+      "type": "object",
+      "description": "Named endpoint definitions",
+      "additionalProperties": true
+    },
+    "services": {
+      "type": "object",
+      "description": "Service endpoint definitions (list_models, etc.)",
+      "additionalProperties": true
+    },
+    "rate_limit_headers": {
+      "type": "object",
+      "description": "Rate limit header mappings",
+      "additionalProperties": true
+    },
+    "retry_policy": {
+      "type": "object",
+      "description": "Retry policy configuration",
+      "properties": {
+        "strategy": {
+          "type": "string",
+          "enum": ["exponential_backoff", "linear_backoff", "fixed_delay"]
+        },
+        "max_retries": { "type": "integer", "minimum": 0 },
+        "min_delay_ms": { "type": "integer", "minimum": 0 },
+        "max_delay_ms": { "type": "integer", "minimum": 0 },
+        "jitter": { "type": "string", "enum": ["full", "equal", "none"] },
+        "retry_on_http_status": {
+          "type": "array",
+          "items": { "type": "integer" }
+        }
+      }
+    },
+    "termination": {
+      "type": "object",
+      "description": "Termination reason normalization",
+      "properties": {
+        "source_field": { "type": "string" },
+        "mapping": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    },
+    "guardrails": {
+      "type": "object",
+      "description": "Input/output guardrail configuration",
+      "additionalProperties": true
+    },
+    "features": {
+      "type": "object",
+      "description": "Protocol-level feature flags",
+      "additionalProperties": { "type": "boolean" }
+    },
+    "multimodal": {
+      "$ref": "./multimodal.json",
+      "description": "Extended multimodal capability configuration (Ring 2)"
+    },
+    "computer_use": {
+      "$ref": "./computer-use.json",
+      "description": "Computer Use / GUI automation configuration (Ring 2)"
+    },
+    "mcp": {
+      "$ref": "./mcp.json",
+      "description": "Model Context Protocol integration configuration (Ring 2)"
+    },
+    "context_policy": {
+      "$ref": "./context-policy.json",
+      "description": "Context window management policy configuration (Ring 3)"
+    },
+    "provider_contract": {
+      "$ref": "./provider-contract.json",
+      "description": "Runtime provider driver contract specification (Ring 3)"
+    },
+    "capability_profile": {
+      "$ref": "./capability-profile.json",
+      "description": "Experimental I/O/P/S/C capability profile metadata (design-stage, optional)"
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Additional provider-specific metadata"
+    },
+    "pricing": {
+      "$ref": "./pricing.json",
+      "description": "Optional pricing for cost estimation (per 1k tokens)"
+    }
+  },
+  "additionalProperties": false
+}
+

package/schemas/v2/regions.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/ailib-official/ai-protocol/main/schemas/v2/regions.json",
+  "title": "Region Definitions",
+  "description": "Standard region identifiers for provider availability",
+  "type": "array",
+  "minItems": 1,
+  "items": {
+    "type": "string",
+    "enum": ["cn", "global", "us", "eu"]
+  },
+  "uniqueItems": true
+}
+

package/v1/models/ai21.yaml

@@ -0,0 +1,97 @@
+$schema: "https://raw.githubusercontent.com/ailib-official/ai-protocol/main/schemas/v1.json"
+protocol_version: "1.1"
+
+# AI21 Labs Model Instances
+#
+# VERIFIED_AT: 2026-01-29 (based on public AI21 documentation)
+#
+# Notes:
+# - AI21 Labs is known for Jamba models (SSM-Transformer hybrid).
+# - Jamba models support very long context windows.
+
+models:
+  # Jamba 1.5 models
+  jamba-1.5-mini:
+    provider: ai21
+    model_id: "jamba-1.5-mini"
+    display_name: "Jamba 1.5 Mini"
+    verification:
+      status: unverified
+      verified_at: "2026-01-29"
+      source: "documentation"
+      notes: "Based on public documentation. Runtime verification recommended."
+    context_window: 256000
+    capabilities: [chat, tools, streaming]
+    status: active
+    tags: ["ai21", "jamba", "ssm", "long_context"]
+    pricing:
+      input_per_token: 0.0000002
+      output_per_token: 0.0000004
+
+  jamba-1.5-large:
+    provider: ai21
+    model_id: "jamba-1.5-large"
+    display_name: "Jamba 1.5 Large"
+    verification:
+      status: unverified
+      verified_at: "2026-01-29"
+      source: "documentation"
+    context_window: 256000
+    capabilities: [chat, tools, streaming]
+    status: active
+    tags: ["ai21", "jamba", "ssm", "long_context", "flagship"]
+    pricing:
+      input_per_token: 0.000002
+      output_per_token: 0.000008
+
+  # Jamba Instruct (older version)
+  jamba-instruct:
+    provider: ai21
+    model_id: "jamba-instruct"
+    display_name: "Jamba Instruct"
+    verification:
+      status: unverified
+      verified_at: "2026-01-29"
+      source: "documentation"
+    context_window: 256000
+    capabilities: [chat, streaming]
+    status: active
+    tags: ["ai21", "jamba", "ssm", "instruct"]
+    pricing:
+      input_per_token: 0.0000005
+      output_per_token: 0.0000007
+
+  # Jurassic-2 models (legacy but still available)
+  j2-ultra:
+    provider: ai21
+    model_id: "j2-ultra"
+    display_name: "Jurassic-2 Ultra"
+    verification:
+      status: unverified
+      verified_at: "2026-01-29"
+      source: "documentation"
+      notes: "Legacy model; Jamba recommended for new projects."
+    context_window: 8192
+    capabilities: [completion, streaming]
+    status: deprecated
+    tags: ["ai21", "jurassic", "legacy"]
+    pricing:
+      input_per_token: 0.000015
+      output_per_token: 0.000015
+
+  j2-mid:
+    provider: ai21
+    model_id: "j2-mid"
+    display_name: "Jurassic-2 Mid"
+    verification:
+      status: unverified
+      verified_at: "2026-01-29"
+      source: "documentation"
+      notes: "Legacy model; Jamba recommended for new projects."
+    context_window: 8192
+    capabilities: [completion, streaming]
+    status: deprecated
+    tags: ["ai21", "jurassic", "legacy"]
+    pricing:
+      input_per_token: 0.00001
+      output_per_token: 0.00001