{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://traigent.ai/schemas/hybrid-mode/v1.0.0",
  "title": "Traigent Hybrid Mode API Schemas",
  "description": "JSON Schema definitions for Traigent Hybrid Mode API DTOs",
  "definitions": {
    "ServiceCapabilities": {
      "type": "object",
      "title": "ServiceCapabilities",
      "description": "Service capabilities discovered via handshake",
      "required": ["version"],
      "properties": {
        "version": {
          "type": "string",
          "description": "API version",
          "examples": ["1.0"]
        },
        "supports_evaluate": {
          "type": "boolean",
          "description": "Whether separate evaluate endpoint is available",
          "default": false
        },
        "supports_keep_alive": {
          "type": "boolean",
          "description": "Whether keep-alive heartbeat is supported",
          "default": false
        },
        "supports_streaming": {
          "type": "boolean",
          "description": "Whether streaming responses are supported",
          "default": false
        },
        "max_batch_size": {
          "type": "integer",
          "description": "Maximum inputs per execute request",
          "default": 100,
          "minimum": 1
        },
        "max_payload_bytes": {
          "type": ["integer", "null"],
          "description": "Maximum request payload size (null = unlimited)"
        },
        "tunable_ids": {
          "type": "array",
          "description": "Optional list of capability IDs supported by this service",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "TunableDefinition": {
      "type": "object",
      "title": "TunableDefinition",
      "description": "Tunable variable definition following TVL 0.9 specification",
      "required": ["name", "type"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Variable name (must be valid Python identifier)",
          "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
        },
        "type": {
          "type": "string",
          "description": "Variable type",
          "enum": ["bool", "int", "float", "str", "enum"]
        },
        "domain": {
          "$ref": "#/definitions/TunableDomain"
        },
        "default": {
          "description": "Default value (type depends on tunable type)"
        },
        "agent": {
          "type": "string",
          "description": "Agent name for multi-agent grouping"
        },
        "is_tool": {
          "type": "boolean",
          "description": "True if this tunable configures an MCP tool",
          "default": false
        },
        "constraints": {
          "type": "array",
          "description": "Conditional constraints",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "TunableDomain": {
      "type": "object",
      "title": "TunableDomain",
      "description": "Domain specification for tunable variable",
      "properties": {
        "values": {
          "type": "array",
          "description": "Allowed values (for enum and str types)",
          "items": {}
        },
        "range": {
          "type": "array",
          "description": "[min, max] range (for int and float types)",
          "items": {
            "type": "number"
          },
          "minItems": 2,
          "maxItems": 2
        },
        "resolution": {
          "type": "number",
          "description": "Step size for float types"
        }
      },
      "additionalProperties": false
    },
    "ConfigSpaceResponse": {
      "type": "object",
      "title": "ConfigSpaceResponse",
      "description": "Response from config-space discovery endpoint",
      "required": ["schema_version", "tunable_id", "tunables"],
      "properties": {
        "schema_version": {
          "type": "string",
          "description": "TVL schema version",
          "examples": ["0.9"]
        },
        "tunable_id": {
          "type": "string",
          "description": "Identifier for the capability"
        },
        "tunables": {
          "type": "array",
          "description": "List of tunable variable definitions",
          "items": {
            "$ref": "#/definitions/TunableDefinition"
          }
        },
        "tvars": {
          "type": "array",
          "description": "Alias for tunables (backward compatibility)",
          "items": {
            "$ref": "#/definitions/TunableDefinition"
          }
        },
        "constraints": {
          "description": "Structural and behavioral constraints (legacy textual or typed TVL 0.9)",
          "oneOf": [
            {
              "type": "object",
              "minProperties": 1,
              "additionalProperties": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            {
              "$ref": "#/definitions/TypedConstraints"
            },
            {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": true
              }
            }
          ]
        },
        "objectives": {
          "type": "array",
          "description": "Optional objective definitions (TVL 0.9 compatible JSON)",
          "items": {
            "$ref": "#/definitions/ObjectiveDefinition"
          }
        },
        "exploration": {
          "$ref": "#/definitions/ExplorationConfig"
        },
        "promotion_policy": {
          "$ref": "#/definitions/PromotionPolicy"
        },
        "defaults": {
          "type": "object",
          "description": "Optional default configuration values",
          "additionalProperties": true
        },
        "measures": {
          "type": "array",
          "description": "Optional list of metric names produced by the service",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "ObjectiveDefinition": {
      "type": "object",
      "title": "ObjectiveDefinition",
      "description": "Objective definition compatible with TVL 0.9 objectives section",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Objective name",
          "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
        },
        "direction": {
          "type": "string",
          "description": "Objective orientation",
          "enum": ["maximize", "minimize", "band"]
        },
        "weight": {
          "type": "number",
          "description": "Objective weight",
          "default": 1.0
        },
        "unit": {
          "type": "string",
          "description": "Optional objective unit"
        },
        "band": {
          "$ref": "#/definitions/BandTarget"
        }
      },
      "additionalProperties": false
    },
    "BandTarget": {
      "type": "object",
      "title": "BandTarget",
      "description": "Banded objective target definition",
      "required": ["target"],
      "properties": {
        "target": {
          "type": "array",
          "description": "Lower/upper target band",
          "items": {
            "type": "number"
          },
          "minItems": 2,
          "maxItems": 2
        },
        "test": {
          "type": "string",
          "description": "Statistical band test",
          "enum": ["TOST"],
          "default": "TOST"
        },
        "alpha": {
          "type": "number",
          "description": "Significance level for band test",
          "minimum": 0,
          "maximum": 1,
          "default": 0.05
        }
      },
      "additionalProperties": false
    },
    "ExplorationConfig": {
      "type": "object",
      "title": "ExplorationConfig",
      "description": "Exploration strategy and budget controls (TVL 0.9 exploration section)",
      "properties": {
        "strategy": {
          "description": "Exploration strategy",
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            }
          ]
        },
        "budgets": {
          "$ref": "#/definitions/ExplorationBudgets"
        },
        "convergence": {
          "$ref": "#/definitions/ConvergenceCriteria"
        },
        "parallelism": {
          "type": "object",
          "properties": {
            "max_parallel_trials": {
              "type": "integer",
              "minimum": 1
            }
          },
          "additionalProperties": true
        }
      },
      "additionalProperties": false
    },
    "ExplorationBudgets": {
      "type": "object",
      "title": "ExplorationBudgets",
      "description": "Exploration budget limits",
      "properties": {
        "max_trials": {
          "type": "integer",
          "minimum": 1
        },
        "max_spend_usd": {
          "type": "number",
          "minimum": 0
        },
        "max_wallclock_s": {
          "type": "number",
          "minimum": 0
        }
      },
      "additionalProperties": false
    },
    "ConvergenceCriteria": {
      "type": "object",
      "title": "ConvergenceCriteria",
      "description": "Convergence stop criteria",
      "required": ["metric", "window", "threshold"],
      "properties": {
        "metric": {
          "type": "string"
        },
        "window": {
          "type": "integer",
          "minimum": 1
        },
        "threshold": {
          "type": "number",
          "minimum": 0
        }
      },
      "additionalProperties": false
    },
    "TypedConstraints": {
      "type": "object",
      "title": "TypedConstraints",
      "description": "Typed TVL 0.9 constraints section",
      "properties": {
        "structural": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "derived": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "additionalProperties": false
    },
    "PromotionPolicy": {
      "type": "object",
      "title": "PromotionPolicy",
      "description": "Promotion policy for epsilon-Pareto selection",
      "properties": {
        "dominance": {
          "type": "string",
          "enum": ["epsilon_pareto"],
          "default": "epsilon_pareto"
        },
        "alpha": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "default": 0.05
        },
        "min_effect": {
          "type": "object",
          "additionalProperties": {
            "type": "number"
          }
        },
        "adjust": {
          "type": "string",
          "enum": ["none", "BH"],
          "default": "none"
        },
        "chance_constraints": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ChanceConstraint"
          }
        },
        "tie_breakers": {
          "type": "object",
          "additionalProperties": {
            "type": "string",
            "enum": ["min_abs_deviation", "custom"]
          }
        }
      },
      "additionalProperties": false
    },
    "ChanceConstraint": {
      "type": "object",
      "title": "ChanceConstraint",
      "required": ["name", "threshold", "confidence"],
      "properties": {
        "name": {
          "type": "string"
        },
        "threshold": {
          "type": "number"
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      },
      "additionalProperties": false
    },
    "BatchOptions": {
      "type": "object",
      "title": "BatchOptions",
      "description": "Options for batch execution control",
      "properties": {
        "parallelism": {
          "type": "integer",
          "description": "Maximum concurrent executions within batch",
          "default": 1,
          "minimum": 1
        },
        "fail_fast": {
          "type": "boolean",
          "description": "Stop batch on first failure",
          "default": false
        },
        "timeout_per_item_ms": {
          "type": "integer",
          "description": "Per-item timeout (0 = use request timeout)",
          "default": 0,
          "minimum": 0
        }
      },
      "additionalProperties": false
    },
    "ExampleItem": {
      "type": "object",
      "title": "ExampleItem",
      "description": "Single example item for execution. For privacy-preserving mode, only example_id is required - the service retrieves data locally using the ID.",
      "required": ["example_id"],
      "properties": {
        "example_id": {
          "type": "string",
          "description": "Unique identifier for this input. In privacy-preserving mode, the service uses this to retrieve locally-stored input data."
        },
        "data": {
          "type": "object",
          "description": "Input data (optional in privacy-preserving mode). Structure defined by your agent.",
          "additionalProperties": true
        }
      },
      "additionalProperties": false
    },
    "ExecuteRequest": {
      "type": "object",
      "title": "ExecuteRequest",
      "description": "Request to execute agent with configuration on examples",
      "required": ["tunable_id", "config", "examples"],
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid",
          "description": "Idempotency key for retry safety (same request_id + different payload should return 400)"
        },
        "tunable_id": {
          "type": "string",
          "description": "Identifier for the agent capability to invoke"
        },
        "config": {
          "type": "object",
          "description": "Configuration parameters (tunable values)",
          "additionalProperties": true
        },
        "examples": {
          "type": "array",
          "description": "List of examples to process",
          "items": {
            "$ref": "#/definitions/ExampleItem"
          },
          "minItems": 1
        },
        "session_id": {
          "type": ["string", "null"],
          "description": "Session ID for stateful agents"
        },
        "batch_options": {
          "$ref": "#/definitions/BatchOptions"
        },
        "timeout_ms": {
          "type": "integer",
          "description": "Request timeout in milliseconds",
          "default": 30000,
          "minimum": 1000
        }
      },
      "additionalProperties": false
    },
    "OutputItem": {
      "type": "object",
      "title": "OutputItem",
      "description": "Output for a single input. For privacy-preserving mode, output_id can be returned instead of output content - the service stores output data locally.",
      "required": ["example_id"],
      "additionalProperties": true,
      "properties": {
        "example_id": {
          "type": "string",
          "description": "Matching example identifier"
        },
        "output": {
          "type": "object",
          "description": "Agent output (optional in privacy-preserving mode). Structure defined by your agent.",
          "additionalProperties": true
        },
        "output_id": {
          "type": "string",
          "description": "Unique identifier for this output (privacy-preserving mode). The service stores the actual output data locally and only transmits this ID."
        },
        "cost_usd": {
          "type": "number",
          "description": "Cost for this input in USD"
        },
        "latency_ms": {
          "type": "number",
          "description": "Latency for this input in milliseconds"
        },
        "metrics": {
          "type": "object",
          "description": "Optional per-input quality metrics (combined execute+evaluate mode)",
          "additionalProperties": {
            "type": "number"
          }
        },
        "error": {
          "type": "string",
          "description": "Error message for this input when execution partially fails"
        }
      }
    },
    "OperationalMetrics": {
      "type": "object",
      "title": "OperationalMetrics",
      "description": "Aggregate operational metrics from execution",
      "required": ["total_cost_usd"],
      "properties": {
        "total_cost_usd": {
          "type": "number",
          "description": "Total cost in USD"
        },
        "cost_usd": {
          "type": "number",
          "description": "Alias for total_cost_usd"
        },
        "latency_ms": {
          "type": "number",
          "description": "Total latency in milliseconds"
        },
        "tokens_used": {
          "type": "integer",
          "description": "Total tokens consumed"
        },
        "tokens_input": {
          "type": "integer",
          "description": "Input tokens"
        },
        "tokens_output": {
          "type": "integer",
          "description": "Output tokens"
        },
        "cache_hits": {
          "type": "integer",
          "description": "Number of cache hits"
        },
        "retry_count": {
          "type": "integer",
          "description": "Number of retries"
        }
      },
      "additionalProperties": {
        "description": "Custom operational metrics",
        "anyOf": [
          {
            "type": "number"
          },
          {
            "type": "string"
          },
          {
            "type": "boolean"
          }
        ]
      }
    },
    "ExecutionError": {
      "type": ["object", "null"],
      "title": "ExecutionError",
      "description": "Execution error details",
      "properties": {
        "code": {
          "type": "string",
          "description": "Error code"
        },
        "message": {
          "type": "string",
          "description": "Error message"
        },
        "failed_examples": {
          "type": "array",
          "description": "List of failed example IDs",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "ExecuteResponse": {
      "type": "object",
      "title": "ExecuteResponse",
      "description": "Response from agent execution",
      "required": ["request_id", "execution_id", "status", "outputs", "operational_metrics"],
      "properties": {
        "request_id": {
          "type": "string",
          "description": "Echoed request ID for correlation"
        },
        "execution_id": {
          "type": "string",
          "description": "Unique ID for this execution (used in evaluate)"
        },
        "status": {
          "type": "string",
          "description": "Execution status",
          "enum": ["completed", "partial", "failed"]
        },
        "outputs": {
          "type": "array",
          "description": "Per-input results",
          "items": {
            "$ref": "#/definitions/OutputItem"
          }
        },
        "operational_metrics": {
          "$ref": "#/definitions/OperationalMetrics"
        },
        "quality_metrics": {
          "type": ["object", "null"],
          "description": "Quality metrics if using combined mode",
          "additionalProperties": {
            "type": "number"
          }
        },
        "session_id": {
          "type": ["string", "null"],
          "description": "Session ID for stateful agents"
        },
        "error": {
          "$ref": "#/definitions/ExecutionError"
        }
      },
      "additionalProperties": false
    },
    "EvaluationItem": {
      "type": "object",
      "title": "EvaluationItem",
      "description": "Single evaluation item with output and target. For privacy-preserving mode, use output_id and target_id instead of content - the service retrieves data locally using session context.",
      "required": ["example_id"],
      "properties": {
        "example_id": {
          "type": "string",
          "description": "Matching example identifier"
        },
        "output": {
          "type": "object",
          "description": "Agent output to evaluate (optional in privacy-preserving mode)",
          "additionalProperties": true
        },
        "output_id": {
          "type": "string",
          "description": "Reference to output by ID (privacy-preserving mode). The service retrieves output data locally using this ID and the session context."
        },
        "target": {
          "type": "object",
          "description": "Expected/reference output (optional in privacy-preserving mode)",
          "additionalProperties": true
        },
        "target_id": {
          "type": "string",
          "description": "Reference to target by ID (privacy-preserving mode). The service retrieves target data locally using this ID."
        }
      },
      "additionalProperties": false
    },
    "EvaluateRequest": {
      "type": "object",
      "title": "EvaluateRequest",
      "description": "Request to evaluate outputs against targets",
      "required": ["tunable_id"],
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid",
          "description": "Idempotency key for retry safety (same request_id + different payload should return 400)"
        },
        "tunable_id": {
          "type": "string",
          "description": "Identifier for the evaluation capability"
        },
        "execution_id": {
          "type": ["string", "null"],
          "description": "Reference to previous execute (for caching)"
        },
        "evaluations": {
          "type": "array",
          "description": "List of output+target pairs to evaluate",
          "items": {
            "$ref": "#/definitions/EvaluationItem"
          }
        },
        "config": {
          "type": ["object", "null"],
          "description": "Optional config for evaluation parameters",
          "additionalProperties": true
        },
        "session_id": {
          "type": ["string", "null"],
          "description": "Session ID for stateful agents"
        },
        "timeout_ms": {
          "type": "integer",
          "description": "Optional request timeout in milliseconds (wrapper returns 408 on timeout)",
          "minimum": 1000
        }
      },
      "additionalProperties": false
    },
    "AggregateMetricStats": {
      "type": "object",
      "title": "AggregateMetricStats",
      "description": "Aggregated statistics for a metric",
      "required": ["mean", "std", "n"],
      "properties": {
        "mean": {
          "type": "number",
          "description": "Mean value across all examples"
        },
        "std": {
          "type": "number",
          "description": "Standard deviation"
        },
        "n": {
          "type": "integer",
          "description": "Number of examples"
        }
      },
      "additionalProperties": false
    },
    "EvaluationResult": {
      "type": "object",
      "title": "EvaluationResult",
      "description": "Evaluation result for a single example",
      "required": ["example_id", "metrics"],
      "properties": {
        "example_id": {
          "type": "string",
          "description": "Matching example identifier"
        },
        "metrics": {
          "type": "object",
          "description": "Quality metrics for this example",
          "additionalProperties": {
            "type": "number"
          }
        },
        "error": {
          "type": "string",
          "description": "Optional error message for this example when evaluation partially fails"
        }
      },
      "additionalProperties": false
    },
    "EvaluateResponse": {
      "type": "object",
      "title": "EvaluateResponse",
      "description": "Response from evaluation",
      "required": ["request_id", "status", "results", "aggregate_metrics"],
      "properties": {
        "request_id": {
          "type": "string",
          "description": "Echoed request ID"
        },
        "status": {
          "type": "string",
          "description": "Evaluation status",
          "enum": ["completed", "partial", "failed"]
        },
        "results": {
          "type": "array",
          "description": "Per-example evaluation results",
          "items": {
            "$ref": "#/definitions/EvaluationResult"
          }
        },
        "aggregate_metrics": {
          "type": "object",
          "description": "Aggregated statistics per metric",
          "additionalProperties": {
            "$ref": "#/definitions/AggregateMetricStats"
          }
        },
        "error": {
          "$ref": "#/definitions/ExecutionError"
        }
      },
      "additionalProperties": false
    },
    "HealthCheckResponse": {
      "type": "object",
      "title": "HealthCheckResponse",
      "description": "Response from health check endpoint",
      "required": ["status"],
      "properties": {
        "status": {
          "type": "string",
          "description": "Health status",
          "enum": ["healthy", "degraded", "unhealthy"]
        },
        "version": {
          "type": "string",
          "description": "Service version"
        },
        "uptime_seconds": {
          "type": "number",
          "description": "Service uptime in seconds"
        },
        "details": {
          "type": "object",
          "description": "Additional health details",
          "additionalProperties": true
        }
      },
      "additionalProperties": false
    },
    "KeepAliveRequest": {
      "type": "object",
      "title": "KeepAliveRequest",
      "description": "Request body for session heartbeat",
      "required": ["session_id"],
      "properties": {
        "session_id": {
          "type": "string",
          "description": "Session identifier"
        }
      },
      "additionalProperties": false
    },
    "KeepAliveResponse": {
      "type": "object",
      "title": "KeepAliveResponse",
      "description": "Response body for successful session heartbeat",
      "required": ["status", "session_id"],
      "properties": {
        "status": {
          "type": "string",
          "enum": ["alive"],
          "description": "Session heartbeat status"
        },
        "session_id": {
          "type": "string",
          "description": "Session identifier"
        }
      },
      "additionalProperties": false
    },
    "ErrorDetails": {
      "type": "object",
      "title": "ErrorDetails",
      "description": "Structured error details",
      "required": ["code", "message"],
      "properties": {
        "code": {
          "type": "string",
          "description": "Error code"
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message"
        },
        "details": {
          "type": "object",
          "description": "Additional error details",
          "additionalProperties": true
        }
      },
      "additionalProperties": false
    },
    "ErrorResponse": {
      "type": "object",
      "title": "ErrorResponse",
      "description": "Error response wrapper",
      "required": ["error"],
      "properties": {
        "error": {
          "$ref": "#/definitions/ErrorDetails"
        }
      },
      "additionalProperties": false
    }
  }
}