@ailib-official/ai-protocol 0.8.4

package/schemas/v2/context-policy.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/ailib-official/ai-protocol/main/schemas/v2/context-policy.json",
+  "title": "AI-Protocol V2 Context Management Policy",
+  "description": "Context window management strategies for V2 provider manifests. Defines sliding window, summarization triggers, token budgets, and overflow handling. Provider-agnostic abstractions for managing limited context windows across varying provider capabilities.",
+  "type": "object",
+  "properties": {
+    "strategy": {
+      "type": "string",
+      "enum": ["sliding_window", "summarize", "truncate_oldest", "token_budget", "adaptive"],
+      "default": "sliding_window",
+      "description": "Primary context management strategy: sliding_window (drop oldest messages), summarize (compress old context), truncate_oldest (hard cut), token_budget (allocate per role), adaptive (auto-select based on context)"
+    },
+    "token_budget": {
+      "type": "object",
+      "description": "Token allocation budget configuration",
+      "properties": {
+        "max_context_tokens": {
+          "type": "integer",
+          "minimum": 1024,
+          "description": "Maximum tokens to use from the provider's context window (may be less than model max)"
+        },
+        "reserve_for_output": {
+          "type": "integer",
+          "minimum": 256,
+          "default": 4096,
+          "description": "Tokens reserved for model output generation"
+        },
+        "system_message_budget": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Maximum tokens for system messages (0 = unlimited within context)"
+        },
+        "tool_budget": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Maximum tokens for tool definitions and results"
+        }
+      },
+      "additionalProperties": false
+    },
+    "sliding_window": {
+      "type": "object",
+      "description": "Sliding window configuration",
+      "properties": {
+        "window_size": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Number of recent message pairs to keep"
+        },
+        "preserve_system": {
+          "type": "boolean",
+          "default": true,
+          "description": "Always keep system messages regardless of window position"
+        },
+        "preserve_tool_context": {
+          "type": "boolean",
+          "default": true,
+          "description": "Keep tool call/result pairs together (never split mid-tool-use)"
+        },
+        "anchor_messages": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0,
+          "description": "Number of initial messages to always preserve (after system)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "summarization": {
+      "type": "object",
+      "description": "Context summarization configuration",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Enable automatic summarization of old context"
+        },
+        "trigger_threshold": {
+          "type": "number",
+          "minimum": 0.1,
+          "maximum": 1.0,
+          "default": 0.8,
+          "description": "Context fill ratio that triggers summarization (0.8 = 80% full)"
+        },
+        "summary_max_tokens": {
+          "type": "integer",
+          "minimum": 100,
+          "default": 1024,
+          "description": "Maximum tokens for the summary message"
+        },
+        "summary_model": {
+          "type": "string",
+          "description": "Model to use for summarization (if different from main model, e.g. a faster model)"
+        },
+        "preserve_recent": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 5,
+          "description": "Number of recent message pairs to preserve unsummarized"
+        }
+      },
+      "additionalProperties": false
+    },
+    "overflow_handling": {
+      "type": "object",
+      "description": "What to do when context still exceeds limits after policy application",
+      "properties": {
+        "action": {
+          "type": "string",
+          "enum": ["error", "force_truncate", "retry_with_summary"],
+          "default": "error",
+          "description": "Action when context exceeds budget after policy application"
+        },
+        "error_code": {
+          "type": "string",
+          "const": "E1006",
+          "description": "Standard error code for context overflow (request_too_large)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "provider_specific": {
+      "type": "object",
+      "description": "Provider-specific context management features",
+      "properties": {
+        "supports_context_caching": {
+          "type": "boolean",
+          "default": false,
+          "description": "Provider supports context caching for repeated prefixes (Gemini, Anthropic)"
+        },
+        "supports_compaction_api": {
+          "type": "boolean",
+          "default": false,
+          "description": "Provider has a native context compaction API (Anthropic)"
+        },
+        "cache_ttl_seconds": {
+          "type": "integer",
+          "minimum": 60,
+          "description": "Cache time-to-live for context caching"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}
+

package/schemas/v2/endpoint.json

@@ -0,0 +1,2 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://raw.githubusercontent.com/ailib-official/ai-protocol/main/schemas/v2/endpoint.json","title":"Endpoint Definition","description":"Network-level endpoint configuration for V2 provider manifests","type":"object","required":["base_url"],"properties":{"base_url":{"type":"string","format":"uri","description":"Absolute base URL of the provider API"},"protocol":{"type":"string","enum":["https","http","ws","wss"],"default":"https","description":"Protocol used for communication"},"timeout_ms":{"type":"integer","minimum":100,"default":10000,"description":"Default timeout for requests in milliseconds"},"chat":{"type":"string","description":"Chat completions endpoint path (relative to base_url)"},"embeddings":{"type":"string","description":"Embeddings endpoint path (relative to base_url)"},"stt":{"type":"string","description":"Speech-to-text transcription endpoint path (relative to base_url)"},"tts":{"type":"string","description":"Text-to-speech synthesis endpoint path (relative to base_url)"},"rerank":{"type":"string","description":"Document reranking endpoint path (relative to base_url)"},"auth":{"type":"object","description":"Authentication configuration","properties":{"type":{"type":"string","enum":["bearer","custom_header","query_param"],"description":"Authentication method"},"header":{"type":"string","description":"HTTP header name for authentication"},"prefix":{"type":"string","description":"Prefix for the auth token (e.g., 'Bearer')"},"param_name":{"type":"string","description":"Query parameter name for query_param auth"},"token_env":{"type":"string","description":"Environment variable name for the API key"},"extra_headers":{"type":"array","description":"Additional headers to include in requests","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}}},"required":["type"]}},"additionalProperties":false}
+

package/schemas/v2/error-codes.yaml

@@ -0,0 +1,225 @@
+# AI-Protocol Standard Error Codes — Reference Data
+# This file provides the canonical error code definitions used by all runtimes.
+# See schemas/v2/errors.json for the JSON Schema definition.
+
+version: "2.0"
+last_updated: "2026-02-14"
+
+# ==============================================================================
+# Standard Error Codes
+# ==============================================================================
+# Numbering convention:
+#   E1xxx — Client errors (request-side, usually non-retryable)
+#   E2xxx — Rate/quota errors (transient, retryable with backoff)
+#   E3xxx — Server errors (provider-side, often retryable)
+#   E4xxx — Operational errors (lifecycle/state issues)
+#   E9xxx — Catch-all / unknown
+# ==============================================================================
+
+error_codes:
+  # --- Client Errors (1xxx) ---
+  E1001:
+    name: "invalid_request"
+    category: "client"
+    http_status: 400
+    retryable: false
+    fallbackable: false
+    description: "Malformed request, invalid parameters, or missing required fields"
+    recovery_hint: "Check request parameters against the provider's API documentation"
+
+  E1002:
+    name: "authentication"
+    category: "client"
+    http_status: 401
+    retryable: false
+    fallbackable: true
+    description: "Invalid, expired, or missing API key"
+    recovery_hint: "Verify API key is set correctly via environment variable or keyring"
+
+  E1003:
+    name: "permission_denied"
+    category: "client"
+    http_status: 403
+    retryable: false
+    fallbackable: false
+    description: "Valid credentials but insufficient permissions for the requested resource"
+    recovery_hint: "Check account permissions and model access policies"
+
+  E1004:
+    name: "not_found"
+    category: "client"
+    http_status: 404
+    retryable: false
+    fallbackable: false
+    description: "Requested model, endpoint, or resource does not exist"
+    recovery_hint: "Verify model ID and endpoint URL in the provider manifest"
+
+  E1005:
+    name: "request_too_large"
+    category: "client"
+    http_status: 413
+    retryable: false
+    fallbackable: false
+    description: "Input exceeds the model's context window or the API payload size limit"
+    recovery_hint: "Reduce input size or use a model with a larger context window"
+
+  # --- Rate/Quota Errors (2xxx) ---
+  E2001:
+    name: "rate_limited"
+    category: "rate"
+    http_status: 429
+    retryable: true
+    fallbackable: true
+    description: "Request rate limit exceeded (requests per second/minute)"
+    recovery_hint: "Retry with exponential backoff; check rate_limit_headers for timing"
+
+  E2002:
+    name: "quota_exhausted"
+    category: "rate"
+    http_status: 429
+    retryable: false
+    fallbackable: true
+    description: "Account usage quota or billing limit has been reached"
+    recovery_hint: "Upgrade plan or wait for quota reset; fallback to another provider"
+
+  # --- Server Errors (3xxx) ---
+  E3001:
+    name: "server_error"
+    category: "server"
+    http_status: 500
+    retryable: true
+    fallbackable: true
+    description: "Internal server error on the provider side"
+    recovery_hint: "Retry with backoff; if persistent, check provider status page"
+
+  E3002:
+    name: "overloaded"
+    category: "server"
+    http_status: 503
+    retryable: true
+    fallbackable: true
+    description: "Provider service is temporarily overloaded or under maintenance"
+    recovery_hint: "Retry with longer backoff; consider fallback to another provider"
+
+  E3003:
+    name: "timeout"
+    category: "server"
+    http_status: [504, 408]
+    retryable: true
+    fallbackable: true
+    description: "Request timed out before a response was received"
+    recovery_hint: "Increase timeout or reduce request complexity; retry may succeed"
+
+  # --- Operational Errors (4xxx) ---
+  E4001:
+    name: "conflict"
+    category: "operational"
+    http_status: 409
+    retryable: true
+    fallbackable: false
+    description: "State conflict, such as concurrent modification of the same resource"
+    recovery_hint: "Retry after a short delay"
+
+  E4002:
+    name: "cancelled"
+    category: "operational"
+    http_status: "N/A"
+    retryable: false
+    fallbackable: false
+    description: "Request was cancelled by the client"
+    recovery_hint: "No action needed — cancellation was intentional"
+
+  # --- Unknown (9xxx) ---
+  E9999:
+    name: "unknown"
+    category: "unknown"
+    http_status: "varies"
+    retryable: false
+    fallbackable: false
+    description: "Error could not be classified into a standard category"
+    recovery_hint: "Inspect the original provider error for details"
+
+# ==============================================================================
+# Provider-Specific Mappings
+# ==============================================================================
+# Each provider section maps their specific errors to standard error codes.
+# Runtimes use these mappings during error classification.
+# ==============================================================================
+
+provider_mappings:
+  openai:
+    by_http_status:
+      "400": "invalid_request"
+      "401": "authentication"
+      "403": "permission_denied"
+      "404": "not_found"
+      "429": "rate_limited"      # may also be quota_exhausted
+      "500": "server_error"
+      "503": "overloaded"
+    by_error_code:
+      "invalid_api_key": "authentication"
+      "model_not_found": "not_found"
+      "context_length_exceeded": "request_too_large"
+      "rate_limit_exceeded": "rate_limited"
+      "insufficient_quota": "quota_exhausted"
+      "server_error": "server_error"
+    by_error_message:
+      - pattern: "quota"
+        maps_to: "quota_exhausted"
+      - pattern: "billing"
+        maps_to: "quota_exhausted"
+
+  anthropic:
+    by_http_status:
+      "400": "invalid_request"
+      "401": "authentication"
+      "403": "permission_denied"
+      "404": "not_found"
+      "413": "request_too_large"
+      "429": "rate_limited"
+      "500": "server_error"
+      "529": "overloaded"
+    by_error_code:
+      "invalid_request_error": "invalid_request"
+      "authentication_error": "authentication"
+      "permission_error": "permission_denied"
+      "not_found_error": "not_found"
+      "request_too_large": "request_too_large"
+      "rate_limit_error": "rate_limited"
+      "api_error": "server_error"
+      "overloaded_error": "overloaded"
+
+  gemini:
+    by_http_status:
+      "400": "invalid_request"
+      "401": "authentication"
+      "403": "permission_denied"
+      "404": "not_found"
+      "429": "rate_limited"
+      "500": "server_error"
+      "503": "overloaded"
+    by_error_code:
+      "INVALID_ARGUMENT": "invalid_request"
+      "UNAUTHENTICATED": "authentication"
+      "PERMISSION_DENIED": "permission_denied"
+      "NOT_FOUND": "not_found"
+      "RESOURCE_EXHAUSTED": "rate_limited"
+      "INTERNAL": "server_error"
+      "UNAVAILABLE": "overloaded"
+      "DEADLINE_EXCEEDED": "timeout"
+
+  deepseek:
+    by_http_status:
+      "400": "invalid_request"
+      "401": "authentication"
+      "403": "permission_denied"
+      "404": "not_found"
+      "429": "rate_limited"
+      "500": "server_error"
+      "503": "overloaded"
+    by_error_code:
+      "invalid_request_error": "invalid_request"
+      "authentication_error": "authentication"
+      "rate_limit_reached": "rate_limited"
+      "insufficient_quota": "quota_exhausted"
+      "server_error": "server_error"

package/schemas/v2/errors.json

@@ -0,0 +1,250 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/ailib-official/ai-protocol/main/schemas/v2/errors.json",
+  "title": "AI-Protocol Standard Error Codes",
+  "description": "Unified error code system for cross-provider error normalization. All runtimes MUST map provider-specific errors to these standard codes.",
+  "type": "object",
+  "properties": {
+    "error_codes": {
+      "type": "object",
+      "description": "Standard error code definitions, grouped by category",
+      "properties": {
+        "client_errors": {
+          "type": "object",
+          "description": "Client-side errors (1xxx range) - caused by invalid requests",
+          "properties": {
+            "E1001": {
+              "$ref": "#/$defs/error_definition",
+              "const_name": "invalid_request",
+              "description": "Malformed request, invalid parameters, or missing required fields"
+            },
+            "E1002": {
+              "$ref": "#/$defs/error_definition",
+              "const_name": "authentication",
+              "description": "Invalid, expired, or missing API key"
+            },
+            "E1003": {
+              "$ref": "#/$defs/error_definition",
+              "const_name": "permission_denied",
+              "description": "Valid credentials but insufficient permissions"
+            },
+            "E1004": {
+              "$ref": "#/$defs/error_definition",
+              "const_name": "not_found",
+              "description": "Requested model or resource does not exist"
+            },
+            "E1005": {
+              "$ref": "#/$defs/error_definition",
+              "const_name": "request_too_large",
+              "description": "Input exceeds context window or payload size limit"
+            }
+          }
+        },
+        "rate_errors": {
+          "type": "object",
+          "description": "Rate and quota errors (2xxx range) - transient capacity limits",
+          "properties": {
+            "E2001": {
+              "$ref": "#/$defs/error_definition",
+              "const_name": "rate_limited",
+              "description": "Request rate limit exceeded; retry after backoff"
+            },
+            "E2002": {
+              "$ref": "#/$defs/error_definition",
+              "const_name": "quota_exhausted",
+              "description": "Usage quota or billing limit reached"
+            }
+          }
+        },
+        "server_errors": {
+          "type": "object",
+          "description": "Server-side errors (3xxx range) - provider infrastructure issues",
+          "properties": {
+            "E3001": {
+              "$ref": "#/$defs/error_definition",
+              "const_name": "server_error",
+              "description": "Internal provider server error"
+            },
+            "E3002": {
+              "$ref": "#/$defs/error_definition",
+              "const_name": "overloaded",
+              "description": "Provider service temporarily overloaded or unavailable"
+            },
+            "E3003": {
+              "$ref": "#/$defs/error_definition",
+              "const_name": "timeout",
+              "description": "Request timed out waiting for response"
+            }
+          }
+        },
+        "operational_errors": {
+          "type": "object",
+          "description": "Operational errors (4xxx range) - state and lifecycle issues",
+          "properties": {
+            "E4001": {
+              "$ref": "#/$defs/error_definition",
+              "const_name": "conflict",
+              "description": "State conflict (e.g., concurrent modification)"
+            },
+            "E4002": {
+              "$ref": "#/$defs/error_definition",
+              "const_name": "cancelled",
+              "description": "Request cancelled by client"
+            }
+          }
+        },
+        "unknown": {
+          "type": "object",
+          "description": "Catch-all for unclassified errors",
+          "properties": {
+            "E9999": {
+              "$ref": "#/$defs/error_definition",
+              "const_name": "unknown",
+              "description": "Unclassified or unexpected error"
+            }
+          }
+        }
+      }
+    },
+    "provider_mappings": {
+      "type": "object",
+      "description": "Provider-specific error-to-standard-code mappings",
+      "additionalProperties": {
+        "$ref": "#/$defs/provider_error_mapping"
+      }
+    }
+  },
+  "$defs": {
+    "error_definition": {
+      "type": "object",
+      "required": ["code", "name", "http_status", "retryable", "fallbackable"],
+      "properties": {
+        "code": {
+          "type": "string",
+          "pattern": "^E[0-9]{4}$",
+          "description": "Standard error code (E + 4 digits)"
+        },
+        "name": {
+          "type": "string",
+          "description": "Machine-readable error name (snake_case)"
+        },
+        "http_status": {
+          "oneOf": [
+            { "type": "integer", "minimum": 100, "maximum": 599 },
+            { "type": "array", "items": { "type": "integer" } },
+            { "type": "string", "enum": ["varies", "N/A"] }
+          ],
+          "description": "Associated HTTP status code(s)"
+        },
+        "retryable": {
+          "type": "boolean",
+          "description": "Whether the same request can be retried"
+        },
+        "fallbackable": {
+          "type": "boolean",
+          "description": "Whether the request can be sent to a different provider/model"
+        },
+        "category": {
+          "type": "string",
+          "enum": ["client", "rate", "server", "operational", "unknown"],
+          "description": "Error category for grouping"
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of the error"
+        },
+        "recovery_hint": {
+          "type": "string",
+          "description": "Suggested recovery action for developers"
+        }
+      }
+    },
+    "provider_error_mapping": {
+      "type": "object",
+      "description": "Maps provider-specific errors to standard error codes",
+      "properties": {
+        "by_http_status": {
+          "type": "object",
+          "description": "HTTP status code to standard error code mapping",
+          "additionalProperties": {
+            "type": "string",
+            "description": "Standard error name (e.g., 'invalid_request', 'rate_limited')"
+          }
+        },
+        "by_error_code": {
+          "type": "object",
+          "description": "Provider-specific error code to standard error code mapping",
+          "additionalProperties": {
+            "type": "string",
+            "description": "Standard error name"
+          }
+        },
+        "by_error_message": {
+          "type": "array",
+          "description": "Pattern-based error message classification",
+          "items": {
+            "type": "object",
+            "required": ["pattern", "maps_to"],
+            "properties": {
+              "pattern": {
+                "type": "string",
+                "description": "Regex pattern to match against error message"
+              },
+              "maps_to": {
+                "type": "string",
+                "description": "Standard error name to map to"
+              }
+            }
+          }
+        }
+      }
+    },
+    "error_response_envelope": {
+      "type": "object",
+      "description": "Standard error response format returned by runtimes",
+      "required": ["error"],
+      "properties": {
+        "error": {
+          "type": "object",
+          "required": ["code", "name", "message"],
+          "properties": {
+            "code": {
+              "type": "string",
+              "pattern": "^E[0-9]{4}$",
+              "description": "Standard error code"
+            },
+            "name": {
+              "type": "string",
+              "description": "Standard error name"
+            },
+            "message": {
+              "type": "string",
+              "description": "Human-readable error description"
+            },
+            "provider_error": {
+              "type": "object",
+              "description": "Original provider error details (for debugging)",
+              "properties": {
+                "status_code": { "type": "integer" },
+                "error_code": { "type": "string" },
+                "error_message": { "type": "string" },
+                "raw": { "description": "Raw provider error body" }
+              }
+            },
+            "retryable": { "type": "boolean" },
+            "fallbackable": { "type": "boolean" },
+            "retry_after_ms": {
+              "type": "integer",
+              "description": "Suggested retry delay in milliseconds"
+            },
+            "request_id": {
+              "type": "string",
+              "description": "Request ID for correlation"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+