awoooi/packages/awooop-contracts/schemas/policy_routing.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://awooop.platform/contracts/v1/policy_routing",
  "title": "Policy Routing Contract",
  "description": "AwoooP 路由/政策合約 — 定義 LLM 路由規則、fallback 順序與費用保護",
  "type": "object",
  "required": ["policy_id", "policy_name", "routing_rules"],
  "additionalProperties": false,
  "properties": {
    "policy_id": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9_-]{1,127}$",
      "description": "Policy 識別符"
    },
    "policy_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "description": "人類可讀政策名稱"
    },
    "routing_rules": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["rule_id", "priority", "provider", "model"],
        "additionalProperties": false,
        "properties": {
          "rule_id": {"type": "string"},
          "priority": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9999,
            "description": "數字越小優先級越高"
          },
          "provider": {
            "type": "string",
            "enum": ["anthropic", "openai", "ollama", "gemini", "nvidia", "openrouter"]
          },
          "model": {"type": "string"},
          "condition": {
            "type": "object",
            "description": "路由條件（task_type, token_budget, time_range 等）",
            "properties": {
              "task_types": {
                "type": "array",
                "items": {"type": "string"}
              },
              "max_prompt_tokens": {"type": "integer", "minimum": 1},
              "time_range": {
                "type": "object",
                "properties": {
                  "start_utc": {"type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$"},
                  "end_utc": {"type": "string", "pattern": "^[0-2][0-9]:[0-5][0-9]$"}
                }
              }
            }
          },
          "weight": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 100,
            "description": "同 priority 時的加權比例（用於 A/B 流量分割）"
          }
        }
      },
      "description": "路由規則清單（按 priority 升序評估）"
    },
    "fallback_provider": {
      "type": "string",
      "enum": ["anthropic", "openai", "ollama", "gemini", "nvidia", "openrouter"],
      "description": "所有規則 miss 時的最終 fallback"
    },
    "fallback_model": {
      "type": "string",
      "description": "fallback_provider 使用的模型"
    },
    "max_cost_per_run_usd": {
      "type": ["number", "null"],
      "minimum": 0,
      "description": "單次 run 費用上限；null = 無限制"
    },
    "retry_policy": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "max_retries": {
          "type": "integer",
          "minimum": 0,
          "maximum": 10,
          "default": 3
        },
        "backoff_base_seconds": {
          "type": "number",
          "minimum": 0.1,
          "maximum": 60,
          "default": 1.0
        },
        "retry_on_provider_errors": {
          "type": "boolean",
          "default": true
        }
      }
    },
    "effective_from": {
      "type": "string",
      "format": "date-time",
      "description": "政策生效起始時間（ISO 8601）"
    },
    "effective_to": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "政策生效結束時間；null = 永久有效"
    }
  }
}