openapi: 3.0.3
info:
  title: Traigent Hybrid Mode API
  description: |
    REST API contract for external agentic services integrating with Traigent optimization.

    Implement these endpoints to enable Traigent to optimize your service's configuration.
    Production integrations should use HTTPS with HTTP/2.
    Open-source releases of the Traigent SDK are licensed under AGPLv3.
    Commercial licenses are available separately from Traigent.
  version: 1.0.0
  contact:
    name: Traigent Support
    url: https://github.com/Traigent/Traigent
  license:
    name: AGPL-3.0-only
    url: https://www.gnu.org/licenses/agpl-3.0.en.html
servers:
  - url: http://127.0.0.1:8080
    description: Local development server
  - url: https://api.your-service.com
    description: Production server
  - url: https://staging.your-service.com
    description: Staging server
security:
  - bearerAuth: []
tags:
  - name: Discovery
    description: Service discovery and capability endpoints
  - name: Execution
    description: Agent execution endpoints
  - name: Evaluation
    description: Output evaluation endpoints
  - name: Health
    description: Health and session management
paths:
  /traigent/v1/capabilities:
    get:
      operationId: getCapabilities
      summary: Get service capabilities
      description: |
        Returns the service capabilities for the initial handshake.
        Traigent calls this first to discover what features your service supports.
      tags:
        - Discovery
      parameters:
        - $ref: '#/components/parameters/TraceParentHeader'
        - $ref: '#/components/parameters/TraceStateHeader'
      responses:
        '200':
          description: Service capabilities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceCapabilities'
              example:
                version: '1.0'
                supports_evaluate: true
                supports_evaluation_kwargs: true
                supports_keep_alive: false
                supports_streaming: false
                max_batch_size: 100
                tunable_ids:
                  - my_agent
        '401':
          description: Unauthorized (missing or invalid bearer token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UNAUTHORIZED
                  message: Bearer token is missing or invalid
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /traigent/v1/config-space:
    get:
      operationId: getConfigSpace
      summary: Get tunable configuration space
      description: |
        Returns tunable variable definitions. Traigent uses these to understand
        what parameters it can optimize for your service.
      tags:
        - Discovery
      parameters:
        - name: tunable_id
          in: query
          required: false
          description: |
            Select which tunable's config space to return.
            If omitted, the server returns the first (or only) tunable.
            Required when the service exposes multiple tunable_ids.
          schema:
            type: string
            maxLength: 256
        - $ref: '#/components/parameters/TraceParentHeader'
        - $ref: '#/components/parameters/TraceStateHeader'
      responses:
        '200':
          description: Configuration space with tunable definitions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigSpaceResponse'
              example:
                schema_version: '0.9'
                tunable_id: my_agent
                tunables:
                  - name: model
                    type: enum
                    domain:
                      values:
                        - gpt-4o
                        - claude-3-sonnet
                        - llama-70b
                    default: gpt-4o
                  - name: temperature
                    type: float
                    domain:
                      range:
                        - 0
                        - 2
                      resolution: 0.1
                    default: 0.7
                evaluation_kwargs:
                  - name: strict_mode
                    type: bool
                    description: Use the stricter grading rubric
                    default: false
        '401':
          description: Unauthorized (missing or invalid bearer token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UNAUTHORIZED
                  message: Bearer token is missing or invalid
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /traigent/v1/execute:
    post:
      operationId: execute
      summary: Execute agent with configuration
      description: |
        Execute the agent with a specific configuration on a batch of inputs.
        This is the main endpoint where your agent processes inputs using the provided configuration.

        **Server implementation (privacy-preserving mode):**
        1. For each input, use `example_id` to look up the actual query from your local dataset (e.g., an observability platform like Langfuse, an evaluation dataset, or any local data store)
        2. Run your agent with the provided `config` parameters
        3. Store the response locally, keyed by a generated `output_id`
        4. Return `output_id` + cost/latency per input (do NOT return response text)

        **Two-phase vs Combined mode:**
        - Return `quality_metrics: null` → Traigent calls `/traigent/v1/evaluate` separately (recommended)
        - Return `quality_metrics` with data → Traigent uses those metrics directly, skips `/traigent/v1/evaluate`
      tags:
        - Execution
      parameters:
        - $ref: '#/components/parameters/TraceParentHeader'
        - $ref: '#/components/parameters/TraceStateHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteRequest'
            example:
              request_id: 550e8400-e29b-41d4-a716-446655440000
              tunable_id: my_agent
              config:
                model: gpt-4o
                temperature: 0.5
              examples:
                - example_id: case_001
              timeout_ms: 30000
      responses:
        '200':
          description: Execution completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecuteResponse'
              example:
                request_id: 550e8400-e29b-41d4-a716-446655440000
                execution_id: exec_20240115_001
                status: completed
                outputs:
                  - example_id: case_001
                    output_id: out_001_run_abc
                    cost_usd: 0.0012
                    latency_ms: 245.5
                operational_metrics:
                  total_cost_usd: 0.0012
                  latency_ms: 245.5
                  tokens_used: 1250
                  tokens_input: 800
                  tokens_output: 450
                quality_metrics: null
        '400':
          description: Invalid request (e.g., empty examples, malformed payload, tunable mismatch)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid-request:
                  summary: Wrapper-level request validation failure
                  value:
                    error:
                      code: INVALID_REQUEST
                      message: examples must be a non-empty list
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '408':
          description: Request timeout exceeded timeout_ms budget
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            Idempotency conflict — request_id was already used with a different payload. Retrying with the same request_id and identical payload returns the cached 200 response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: IDEMPOTENCY_CONFLICT
                  message: request_id 550e8400-... already used with different payload
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable (temporary upstream/dependency outage)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /traigent/v1/evaluate:
    post:
      operationId: evaluate
      summary: Evaluate outputs against targets
      description: |
        Evaluate outputs against expected targets to measure quality.
        This endpoint is optional - only implement if supports_evaluate is true in capabilities.
        Request-level `kwargs` are evaluator-time controls only; they do not replace
        or override the tunable configuration sent in `/traigent/v1/execute.config`.
        `execution_id` is the correlation hook for implementations that want
        execute-time context during evaluation without re-sending execute config.

        **Server implementation (privacy-preserving mode):**
        1. For each evaluation item, use `output_id` to look up stored output locally
        2. Use `example_id` (and optional `target_id`) to resolve expected behavior from local data
        3. Compare output vs expected and compute per-example quality metrics
        4. Return per-example metrics and aggregate statistics (`mean`, `std`, `n`)
      tags:
        - Evaluation
      parameters:
        - $ref: '#/components/parameters/TraceParentHeader'
        - $ref: '#/components/parameters/TraceStateHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluateRequest'
            example:
              request_id: 660e8400-e29b-41d4-a716-446655440001
              tunable_id: my_agent
              execution_id: exec_123456
              kwargs:
                strict_mode: true
              evaluations:
                - example_id: case_001
                  output_id: out_001_run_abc
                  target_id: target_001
              timeout_ms: 30000
      responses:
        '200':
          description: Evaluation completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluateResponse'
              examples:
                with-execution-id:
                  summary: Evaluate with execution_id (typical two-phase flow)
                  value:
                    request_id: 660e8400-e29b-41d4-a716-446655440001
                    execution_id: exec_20240115_001
                    status: completed
                    results:
                      - example_id: case_001
                        metrics:
                          accuracy: 0.92
                          relevance: 0.88
                          fluency: 0.95
                    aggregate_metrics:
                      accuracy:
                        mean: 0.92
                        std: 0.05
                        'n': 10
                      relevance:
                        mean: 0.88
                        std: 0.07
                        'n': 10
                without-execution-id:
                  summary: Evaluate without execution_id (standalone evaluation)
                  value:
                    request_id: 770e8400-e29b-41d4-a716-446655440002
                    execution_id: null
                    status: completed
                    results:
                      - example_id: case_002
                        metrics:
                          accuracy: 0.89
                          relevance: 0.91
                    aggregate_metrics:
                      accuracy:
                        mean: 0.89
                        std: 0.03
                        'n': 5
                      relevance:
                        mean: 0.91
                        std: 0.04
                        'n': 5
        '400':
          description: Invalid request (e.g., malformed evaluations payload or invalid evaluation kwargs)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid-request:
                  summary: Wrapper-level request validation failure
                  value:
                    error:
                      code: INVALID_REQUEST
                      message: evaluations must be a list
                invalid-evaluation-kwargs:
                  summary: Unsupported evaluator parameter
                  value:
                    error:
                      code: INVALID_EVALUATION_KWARGS
                      message: Invalid evaluation kwargs provided for this service
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '408':
          description: Request timeout exceeded timeout_ms budget
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            Idempotency conflict — request_id was already used with a different payload. Retrying with the same request_id and identical payload returns the cached 200 response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: IDEMPOTENCY_CONFLICT
                  message: request_id 660e8400-... already used with different payload
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable (temporary upstream/dependency outage)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /traigent/v1/benchmarks:
    get:
      operationId: getBenchmarks
      summary: List available benchmarks
      description: |
        Returns the benchmarks available for optimization. Each benchmark contains
        a set of example IDs and is linked to one or more tunable IDs.
        Traigent calls this to discover which benchmarks are available for a tunable.
      tags:
        - Discovery
      parameters:
        - name: tunable_id
          in: query
          required: false
          description: |
            Filter benchmarks by tunable ID. If omitted, returns all benchmarks.
          schema:
            type: string
            maxLength: 256
        - $ref: '#/components/parameters/TraceParentHeader'
        - $ref: '#/components/parameters/TraceStateHeader'
      responses:
        '200':
          description: List of benchmarks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BenchmarksResponse'
              example:
                benchmarks:
                  - benchmark_id: spider_dev_v1
                    tunable_ids:
                      - my_agent
                    example_ids:
                      - case_001
                      - case_002
                      - case_003
                    name: Spider Dev Set v1
                benchmarks_revision: rev_20240115_001
        '401':
          description: Unauthorized (missing or invalid bearer token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /traigent/v1/health:
    get:
      operationId: getHealth
      summary: Health check
      description: Health check endpoint for monitoring and load balancer health checks.
      tags:
        - Health
      parameters:
        - $ref: '#/components/parameters/TraceParentHeader'
        - $ref: '#/components/parameters/TraceStateHeader'
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthCheckResponse'
              example:
                status: healthy
                version: 1.0.0
                uptime_seconds: 3600.5
        '401':
          description: Unauthorized (missing or invalid bearer token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UNAUTHORIZED
                  message: Bearer token is missing or invalid
        '503':
          description: Service unavailable (dependency outage)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /traigent/v1/keep-alive:
    post:
      operationId: keepAlive
      summary: Session heartbeat
      description: |
        Session heartbeat for stateful agents.
        Only implement if supports_keep_alive is true in capabilities.
      tags:
        - Health
      parameters:
        - $ref: '#/components/parameters/TraceParentHeader'
        - $ref: '#/components/parameters/TraceStateHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeepAliveRequest'
            example:
              session_id: sess_abc123
      responses:
        '200':
          description: Session alive
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeepAliveResponse'
              example:
                status: alive
                session_id: sess_abc123
        '400':
          description: Invalid request (e.g., missing session_id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: INVALID_REQUEST
                  message: session_id is required
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Session not found or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  parameters:
    TraceParentHeader:
      in: header
      name: traceparent
      required: false
      description: 'W3C Trace Context traceparent header for distributed tracing. Format: {version}-{trace-id}-{parent-id}-{trace-flags}. When present, create a child span for the endpoint handler and propagate the context to downstream calls (e.g., LLM APIs). See the OpenTelemetry Integration section in the README for recommended span names and attributes.'
      schema:
        type: string
      example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
    TraceStateHeader:
      in: header
      name: tracestate
      required: false
      description: W3C Trace Context tracestate header for vendor-specific trace state. Used for opaque routing keys only — not for high-cardinality customer or session identifiers (use span attributes instead).
      schema:
        type: string
      example: traigent=us-east-1
  schemas:
    ServiceCapabilities:
      type: object
      description: Service capabilities discovered via handshake
      additionalProperties: false
      required:
        - version
      properties:
        version:
          type: string
          description: API version (e.g., "1.0")
          maxLength: 16
          example: '1.0'
        supports_evaluate:
          type: boolean
          description: Whether separate evaluate endpoint is available
          default: false
          example: true
        supports_evaluation_kwargs:
          type: boolean
          description: |
            Whether `/traigent/v1/evaluate` accepts request-specific `kwargs`.
            If true, `/traigent/v1/config-space` must include a non-empty
            `evaluation_kwargs` array describing the accepted keys.
          default: false
          example: false
        supports_keep_alive:
          type: boolean
          description: Whether keep-alive heartbeat is supported
          default: false
          example: false
        supports_streaming:
          type: boolean
          description: Whether streaming responses are supported
          default: false
          example: false
        max_batch_size:
          type: integer
          description: Maximum inputs per execute request
          default: 100
          minimum: 1
          maximum: 100000
          example: 100
        max_payload_bytes:
          type: integer
          description: Maximum request payload size (null = unlimited)
          nullable: true
          example: 10485760
        tunable_ids:
          type: array
          description: Optional list of tunable IDs supported by this service
          maxItems: 100
          items:
            type: string
            maxLength: 256
    ErrorDetails:
      type: object
      description: Error details
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Error code
          maxLength: 64
          example: INVALID_CONFIG
        message:
          type: string
          description: Human-readable error message
          maxLength: 2048
          example: 'Invalid configuration: temperature must be between 0 and 2'
        details:
          type: object
          description: Additional error details (must not contain sensitive data such as API keys or stack traces)
          maxProperties: 20
          additionalProperties:
            type: string
            maxLength: 1024
    ErrorResponse:
      type: object
      description: Error response format
      required:
        - error
      properties:
        error:
          description: Structured error details
          $ref: '#/components/schemas/ErrorDetails'
    TunableDomain:
      type: object
      description: Domain specification for tunable variable
      properties:
        values:
          type: array
          description: Allowed values (for enum and str types)
          maxItems: 1000
          items:
            nullable: true
            oneOf:
              - type: string
              - type: number
              - type: boolean
          example:
            - gpt-4o
            - claude-3-sonnet
        range:
          type: array
          description: '[min, max] range (for int and float types)'
          items:
            type: number
          minItems: 2
          maxItems: 2
          example:
            - 0
            - 2
        resolution:
          type: number
          description: Step size for float types
          minimum: 0
          exclusiveMinimum: true
          example: 0.1
    TunableDefinition:
      type: object
      description: Tunable variable definition following TVL 0.9 specification
      additionalProperties: false
      required:
        - name
        - type
      properties:
        name:
          type: string
          description: Variable name (must be valid Python identifier)
          pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
          maxLength: 128
          example: temperature
        type:
          type: string
          description: Variable type
          enum:
            - bool
            - int
            - float
            - str
            - enum
          example: float
        domain:
          description: Domain specification defining the range of valid values
          $ref: '#/components/schemas/TunableDomain'
        default:
          description: Default value (type depends on tunable type)
        agent:
          type: string
          description: Agent name for multi-agent grouping
          maxLength: 128
          example: retriever
        is_tool:
          type: boolean
          description: True if this tunable configures an MCP tool
          default: false
          example: false
        constraints:
          type: array
          description: Conditional constraints
          maxItems: 20
          items:
            type: string
            maxLength: 512
          example:
            - requires model == gpt-4.1
    EvaluationKwargDefinition:
      type: object
      description: |
        Definition of an optional request-specific evaluator parameter accepted by
        `/traigent/v1/evaluate.kwargs`.
      additionalProperties: false
      required:
        - name
        - type
      properties:
        name:
          type: string
          description: Evaluation kwarg name
          pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
          maxLength: 128
          example: strict_mode
        type:
          type: string
          description: Evaluation kwarg type
          enum:
            - bool
            - int
            - float
            - str
            - enum
          example: bool
        description:
          type: string
          description: Optional human-readable description
          maxLength: 512
          nullable: true
          example: Use the stricter grading rubric
        domain:
          description: Optional allowed-values or numeric-range definition
          nullable: true
          $ref: '#/components/schemas/TunableDomain'
        default:
          description: Optional default value when the kwarg is omitted
          nullable: true
    TypedConstraints:
      type: object
      description: Typed TVL 0.9 constraints section
      properties:
        structural:
          type: array
          description: Structural constraints on tunable combinations (e.g., mutual exclusion, dependency)
          maxItems: 50
          items:
            type: object
            additionalProperties: true
        derived:
          type: array
          description: Derived constraints computed from tunable values (e.g., total cost bounds)
          maxItems: 50
          items:
            type: object
            additionalProperties: true
      additionalProperties: false
    BandTarget:
      type: object
      description: Banded objective target definition
      required:
        - target
      properties:
        target:
          type: array
          description: Lower/upper target band
          items:
            type: number
          minItems: 2
          maxItems: 2
          example:
            - 0.85
            - 0.95
        test:
          type: string
          description: Statistical band test
          enum:
            - TOST
          default: TOST
          example: TOST
        alpha:
          type: number
          description: Significance level for band test
          minimum: 0
          maximum: 1
          default: 0.05
          example: 0.05
    ObjectiveDefinition:
      type: object
      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_]*$
          maxLength: 128
          example: accuracy
        direction:
          type: string
          description: Objective orientation
          enum:
            - maximize
            - minimize
            - band
          example: maximize
        weight:
          type: number
          description: Objective weight
          minimum: 0
          default: 1
          example: 1
        unit:
          type: string
          description: Optional objective unit
          maxLength: 64
          example: percent
        band:
          description: Target band for banded objectives (required when direction is 'band')
          $ref: '#/components/schemas/BandTarget'
    ExplorationBudgets:
      type: object
      description: Exploration budget limits
      properties:
        max_trials:
          type: integer
          description: Maximum number of trial configurations to evaluate
          minimum: 1
          maximum: 100000
          example: 20
        max_spend_usd:
          type: number
          description: Maximum total spend in USD across all trials
          minimum: 0
          maximum: 100000
          example: 5
        max_wallclock_s:
          type: number
          description: Maximum wall-clock time in seconds for the optimization run
          minimum: 0
          maximum: 604800
          example: 3600
    ConvergenceCriteria:
      type: object
      description: Convergence stop criteria
      required:
        - metric
        - window
        - threshold
      properties:
        metric:
          type: string
          description: Name of the metric to monitor for convergence
          pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
          maxLength: 128
          example: accuracy
        window:
          type: integer
          description: Number of recent trials to evaluate for convergence
          minimum: 1
          maximum: 1000
          example: 5
        threshold:
          type: number
          description: Maximum allowed improvement within the window to declare convergence
          minimum: 0
          example: 0.01
    ExplorationConfig:
      type: object
      description: Exploration strategy and budget controls (TVL 0.9 exploration section)
      properties:
        strategy:
          description: Exploration strategy (string name or object with type and parameters)
          oneOf:
            - type: string
              example: bayesian
            - type: object
              properties:
                type:
                  type: string
              additionalProperties: true
        budgets:
          description: Budget limits for the exploration run
          $ref: '#/components/schemas/ExplorationBudgets'
        convergence:
          description: Convergence stop criteria for early termination
          $ref: '#/components/schemas/ConvergenceCriteria'
        parallelism:
          type: object
          description: Parallelism settings for trial execution
          properties:
            max_parallel_trials:
              type: integer
              description: Maximum number of trials to run concurrently
              minimum: 1
              maximum: 128
              example: 4
          additionalProperties: false
    ChanceConstraint:
      type: object
      description: Probabilistic constraint requiring a metric to meet a threshold with specified confidence
      required:
        - name
        - threshold
        - confidence
      properties:
        name:
          type: string
          description: Name of the metric this constraint applies to
          pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
          maxLength: 128
          example: accuracy
        threshold:
          type: number
          description: Minimum acceptable metric value
          example: 0.85
        confidence:
          type: number
          description: Required probability of meeting the threshold (0 to 1)
          minimum: 0
          maximum: 1
          example: 0.95
    PromotionPolicy:
      type: object
      description: Promotion policy for epsilon-Pareto selection
      properties:
        dominance:
          type: string
          description: Dominance criterion for comparing configurations
          enum:
            - epsilon_pareto
          default: epsilon_pareto
        alpha:
          type: number
          description: Significance level for statistical tests
          minimum: 0
          maximum: 1
          default: 0.05
          example: 0.05
        min_effect:
          type: object
          description: Minimum practical effect size per metric (metric_name → threshold)
          maxProperties: 50
          additionalProperties:
            type: number
        adjust:
          type: string
          description: Multiple comparison adjustment method
          enum:
            - none
            - BH
          default: none
        chance_constraints:
          type: array
          description: Probabilistic constraints on metric outcomes
          maxItems: 50
          items:
            $ref: '#/components/schemas/ChanceConstraint'
        tie_breakers:
          type: object
          description: Tie-breaking strategy per metric when configurations are statistically equivalent
          additionalProperties:
            type: string
            enum:
              - min_abs_deviation
              - custom
    ConfigSpaceResponse:
      type: object
      description: Response from config-space discovery endpoint
      additionalProperties: false
      required:
        - schema_version
        - tunable_id
        - tunables
      properties:
        schema_version:
          type: string
          description: TVL schema version
          maxLength: 16
          example: '0.9'
        tunable_id:
          type: string
          description: Identifier for the tunable
          maxLength: 256
          example: my_agent
        tunables:
          type: array
          description: List of tunable variable definitions
          maxItems: 200
          items:
            $ref: '#/components/schemas/TunableDefinition'
        tvars:
          type: array
          description: |
            Deprecated: Use 'tunables' instead. Alias for tunables (backward compatibility). Traigent accepts both keys.
          deprecated: true
          maxItems: 200
          items:
            $ref: '#/components/schemas/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: '#/components/schemas/TypedConstraints'
            - type: array
              items:
                type: object
                additionalProperties: true
        objectives:
          type: array
          description: Optional objective definitions (TVL 0.9 compatible JSON)
          maxItems: 50
          items:
            $ref: '#/components/schemas/ObjectiveDefinition'
        exploration:
          description: Exploration strategy, budgets, and convergence settings
          $ref: '#/components/schemas/ExplorationConfig'
        promotion_policy:
          description: Promotion policy for selecting optimal configurations
          $ref: '#/components/schemas/PromotionPolicy'
        defaults:
          type: object
          description: Optional default configuration values
          additionalProperties: true
          maxProperties: 200
        measures:
          type: array
          description: Optional list of metric names produced by the service
          maxItems: 50
          items:
            type: string
            maxLength: 128
        evaluation_kwargs:
          type: array
          description: |
            Optional request-specific evaluator parameters accepted by
            `/traigent/v1/evaluate.kwargs`. This field must be omitted when the
            service does not support evaluation kwargs.
          minItems: 1
          maxItems: 50
          items:
            $ref: '#/components/schemas/EvaluationKwargDefinition'
    ExampleItem:
      type: object
      description: |
        Single input item for execution.

        **Privacy-preserving mode**: Only `example_id` is required. Your service uses
        the ID to look up the actual input data locally. The input data is never
        transmitted to Traigent.

        **Full-content datasets**: Include `data` with the actual input content.
      required:
        - example_id
      properties:
        example_id:
          type: string
          description: |
            Unique identifier for this input. In privacy-preserving mode, your
            service uses this ID to look up the actual input data locally.
          maxLength: 256
          example: ex_001
        data:
          type: object
          description: |
            Input data (structure defined by your agent). Optional in privacy-preserving mode where the service looks up data by example_id.
          additionalProperties: true
          example:
            query: What is machine learning?
    BatchOptions:
      type: object
      description: Options for batch execution control
      properties:
        parallelism:
          type: integer
          description: Maximum concurrent executions within batch
          default: 1
          minimum: 1
          maximum: 128
          example: 4
        fail_fast:
          type: boolean
          description: Stop batch on first failure
          default: false
          example: false
        timeout_per_item_ms:
          type: integer
          description: Per-item timeout (0 = use request timeout)
          default: 0
          minimum: 0
          maximum: 600000
          example: 5000
    ExecuteRequest:
      type: object
      description: Request to execute agent with configuration on examples
      required:
        - request_id
        - tunable_id
        - config
        - examples
      properties:
        request_id:
          type: string
          format: uuid
          description: Idempotency key for retry safety. Required for all requests. Retrying with the same request_id and different payload returns 409.
          example: 550e8400-e29b-41d4-a716-446655440000
        tunable_id:
          type: string
          description: Identifier for the agent tunable to invoke
          maxLength: 256
          example: my_agent
        config:
          type: object
          description: Configuration parameters (tunable values matching config-space definitions)
          additionalProperties: true
        examples:
          type: array
          description: List of examples to process. Actual limit is enforced by max_batch_size from capabilities (default 100), not by a static schema cap.
          items:
            $ref: '#/components/schemas/ExampleItem'
          minItems: 1
        session_id:
          type: string
          description: Session ID for stateful agents
          maxLength: 256
          nullable: true
          example: sess_abc123
        batch_options:
          description: Optional batch processing configuration
          $ref: '#/components/schemas/BatchOptions'
        timeout_ms:
          type: integer
          description: Request timeout in milliseconds
          default: 30000
          minimum: 1000
          maximum: 600000
          example: 30000
    OutputItem:
      type: object
      description: |
        Output for a single input.

        **Privacy-preserving mode**: Return `output_id` instead of `output`. Your service stores the actual output locally and only shares the identifier. Traigent only sees the ID and associated metrics.

        **Full-content datasets**: Include `output` with the actual output content.
      required:
        - example_id
      properties:
        example_id:
          type: string
          description: Matching input identifier
          maxLength: 256
          example: case_001
        output:
          type: object
          description: |
            Agent output (structure defined by your agent). Optional in privacy-preserving mode where only output_id is returned.
          additionalProperties: true
        output_id:
          type: string
          description: |
            Unique identifier for this output. Used in privacy-preserving mode where
            the actual output content is stored locally by the service.
          maxLength: 256
          example: out_001_run_abc
        cost_usd:
          type: number
          description: Cost for this input in USD
          format: double
          minimum: 0
          example: 0.0012
        latency_ms:
          type: number
          description: Latency for this input in milliseconds
          format: double
          minimum: 0
          example: 245.5
        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
          maxLength: 2048
          example: Upstream timeout after 5000ms
    OperationalMetrics:
      type: object
      description: Aggregate operational metrics from execution
      required:
        - total_cost_usd
      properties:
        total_cost_usd:
          type: number
          description: Total cost in USD
          format: double
          minimum: 0
          example: 0.005
        cost_usd:
          type: number
          description: Alias for total_cost_usd (deprecated — use total_cost_usd)
          format: double
          minimum: 0
          deprecated: true
          example: 0.005
        latency_ms:
          type: number
          description: Total latency in milliseconds
          format: double
          minimum: 0
          example: 330
        tokens_used:
          type: integer
          description: Total tokens consumed
          minimum: 0
          example: 1250
        tokens_input:
          type: integer
          description: Input tokens
          minimum: 0
          example: 800
        tokens_output:
          type: integer
          description: Output tokens
          minimum: 0
          example: 450
        cache_hits:
          type: integer
          description: Number of cache hits
          minimum: 0
          example: 0
        retry_count:
          type: integer
          description: Number of retries
          minimum: 0
          example: 0
      additionalProperties:
        description: Custom operational metrics
        anyOf:
          - type: number
          - type: string
            maxLength: 256
          - type: boolean
    ExecutionError:
      type: object
      description: Execution error details
      nullable: true
      properties:
        code:
          type: string
          description: Error code
          maxLength: 64
          example: PARTIAL_FAILURE
        message:
          type: string
          description: Error message
          maxLength: 2048
          example: 2 of 5 inputs failed due to upstream timeout
        failed_examples:
          type: array
          description: List of failed example IDs. Length matches the failed subset of the request batch.
          items:
            type: string
            maxLength: 256
          example:
            - case_003
            - case_005
    ExecuteResponse:
      type: object
      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
          example: 550e8400-e29b-41d4-a716-446655440000
        execution_id:
          type: string
          description: Unique ID for this execution (used in evaluate)
          maxLength: 256
          example: exec_20240115_001
        status:
          type: string
          description: Execution status
          enum:
            - completed
            - partial
            - failed
        outputs:
          type: array
          description: Per-input results. Length matches the request batch size after wrapper validation.
          items:
            $ref: '#/components/schemas/OutputItem'
        operational_metrics:
          description: Aggregate operational metrics from the execution batch
          $ref: '#/components/schemas/OperationalMetrics'
        quality_metrics:
          type: object
          description: |
            Quality metrics from combined mode (execute + evaluate in one call).
            Controls whether the SDK calls `/traigent/v1/evaluate`:
            - null, omitted, or empty (`{}`) => SDK calls `/traigent/v1/evaluate` (two-phase, recommended)
            - non-empty object => SDK uses these metrics directly and skips `/traigent/v1/evaluate`
          additionalProperties:
            type: number
          nullable: true
        session_id:
          type: string
          description: Session ID for stateful agents
          maxLength: 256
          nullable: true
          example: sess_abc123
        error:
          description: Error details when status is partial or failed
          $ref: '#/components/schemas/ExecutionError'
    EvaluationItem:
      type: object
      description: |
        Single evaluation item with output and target.

        **Privacy-preserving mode**: Use `output_id` and `target_id` instead of actual content.
        Your service looks up the actual data locally using these IDs. This ensures that
        sensitive input/output content is never transmitted to Traigent.

        **Full-content datasets**: Include `output` and `target` with actual content.

        Note: You can mix modes - e.g., provide `output` content but use `target_id` for expected.
      required:
        - example_id
      properties:
        example_id:
          type: string
          description: Matching input identifier
          maxLength: 256
          example: case_001
        output:
          type: object
          description: |
            Agent output to evaluate. Optional if using output_id for privacy-preserving mode.
          additionalProperties: true
        output_id:
          type: string
          description: |
            Reference to output stored locally by the service. Used in privacy-preserving mode where actual output content is not transmitted. The service looks up the output by this ID when performing evaluation.
          maxLength: 256
          example: out_001_run_abc
        target:
          type: object
          description: |
            Expected/reference output. Optional if using target_id for privacy-preserving mode.
          additionalProperties: true
        target_id:
          type: string
          description: |
            Reference to expected output stored locally by the service. Used in privacy-preserving mode where actual target content is not transmitted. The service looks up the expected output by this ID when performing evaluation.
          maxLength: 256
          example: target_001
    EvaluateRequest:
      type: object
      description: Request to evaluate outputs against targets
      required:
        - request_id
        - tunable_id
        - evaluations
      properties:
        request_id:
          type: string
          format: uuid
          description: Idempotency key for retry safety. Required for all requests. Retrying with the same request_id and different payload returns 409.
          example: 660e8400-e29b-41d4-a716-446655440001
        tunable_id:
          type: string
          description: Identifier for the evaluation tunable
          maxLength: 256
          example: my_agent
        execution_id:
          type: string
          description: |
            Reference to a previous execute call for correlation. Implementations
            may use this to recover execute-time context during evaluation.
          maxLength: 256
          nullable: true
          example: exec_20240115_001
        evaluations:
          type: array
          description: List of output+target pairs to evaluate. Implementations should reject oversize batches at runtime instead of relying on a static schema cap.
          minItems: 1
          items:
            $ref: '#/components/schemas/EvaluationItem'
        kwargs:
          type: object
          description: |
            Optional evaluator-specific request parameters. These are evaluate-time
            controls only and do not replace or override `/execute.config`.
          additionalProperties: true
          nullable: true
        config:
          type: object
          description: Deprecated alias for `kwargs`
          additionalProperties: true
          nullable: true
          deprecated: true
        session_id:
          type: string
          description: Session ID for stateful agents
          maxLength: 256
          nullable: true
          example: sess_abc123
        timeout_ms:
          type: integer
          description: Optional request timeout in milliseconds (wrapper returns 408 on timeout)
          minimum: 1000
          maximum: 600000
          example: 30000
    EvaluationResult:
      type: object
      description: Evaluation result for a single example
      required:
        - example_id
        - metrics
      properties:
        example_id:
          type: string
          description: Matching input identifier
          maxLength: 256
          example: case_001
        metrics:
          type: object
          description: Quality metrics for this example
          additionalProperties:
            type: number
          example:
            accuracy: 0.92
            relevance: 0.88
            fluency: 0.95
        error:
          type: string
          description: Optional error message for this example when evaluation partially fails
          maxLength: 2048
          example: Target not found for input case_003
    AggregateMetricStats:
      type: object
      description: Aggregated statistics for a metric
      required:
        - mean
        - std
        - 'n'
      properties:
        mean:
          type: number
          description: Mean value across all examples
          format: double
          example: 0.92
        std:
          type: number
          description: Standard deviation
          format: double
          minimum: 0
          example: 0.05
        'n':
          type: integer
          description: Number of examples
          minimum: 0
          example: 10
        min:
          type: number
          description: Minimum value across all examples
          format: double
        max:
          type: number
          description: Maximum value across all examples
          format: double
    EvaluateResponse:
      type: object
      description: Response from evaluation
      required:
        - request_id
        - status
        - results
        - aggregate_metrics
      properties:
        request_id:
          type: string
          description: Echoed request ID
          example: 660e8400-e29b-41d4-a716-446655440001
        execution_id:
          type: string
          description: Echoed execution_id from the request, enabling trace correlation between execute and evaluate phases. When the request includes execution_id, the response MUST echo it back. When the request omits execution_id, this field is null.
          maxLength: 256
          nullable: true
          example: exec_20240115_001
        status:
          type: string
          description: Evaluation status
          enum:
            - completed
            - partial
            - failed
        results:
          type: array
          description: Per-example evaluation results. Length matches the evaluated request batch after wrapper validation.
          items:
            $ref: '#/components/schemas/EvaluationResult'
        aggregate_metrics:
          type: object
          description: Aggregated statistics per metric
          additionalProperties:
            $ref: '#/components/schemas/AggregateMetricStats'
        error:
          description: Error details when status is partial or failed
          $ref: '#/components/schemas/ExecutionError'
    BenchmarkEntry:
      type: object
      description: A single benchmark with its associated example IDs
      required:
        - benchmark_id
        - tunable_ids
        - example_ids
      properties:
        benchmark_id:
          type: string
          description: Unique identifier for this benchmark
          maxLength: 256
          example: spider_dev_v1
        tunable_ids:
          type: array
          description: Agents linked to this benchmark (sorted ASCII)
          items:
            type: string
            maxLength: 256
          minItems: 1
          maxItems: 100
          example:
            - my_agent
        example_ids:
          type: array
          description: Datapoint identifiers within this benchmark (sorted ASCII)
          items:
            type: string
            maxLength: 256
          minItems: 1
          maxItems: 100000
          example:
            - case_001
            - case_002
            - case_003
        name:
          type: string
          description: Optional display name for the benchmark
          maxLength: 512
          nullable: true
          example: Spider Dev Set v1
    BenchmarksResponse:
      type: object
      description: Response from benchmarks discovery endpoint
      required:
        - benchmarks
      properties:
        benchmarks:
          type: array
          description: List of benchmark entries (sorted by benchmark_id, ASCII)
          items:
            $ref: '#/components/schemas/BenchmarkEntry'
          maxItems: 1000
        benchmarks_revision:
          type: string
          description: Opaque revision token for stale-detection. Pass this value in execute/evaluate requests to detect benchmark changes.
          maxLength: 256
          nullable: true
          example: rev_20240115_001
    HealthCheckResponse:
      type: object
      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
          maxLength: 32
          example: 1.0.0
        uptime_seconds:
          type: number
          description: Service uptime in seconds
          format: double
          minimum: 0
          example: 86400.5
        details:
          type: object
          description: Additional health details
          additionalProperties: true
          maxProperties: 20
    KeepAliveRequest:
      type: object
      description: Request body for session heartbeat
      required:
        - session_id
      properties:
        session_id:
          type: string
          description: Session identifier
          maxLength: 256
          example: sess_abc123
    KeepAliveResponse:
      type: object
      description: Response body for successful session heartbeat
      required:
        - status
        - session_id
      properties:
        status:
          type: string
          enum:
            - alive
            - expired
          description: Session heartbeat status
        session_id:
          type: string
          description: Session identifier
          maxLength: 256
          example: sess_abc123
x-transport-requirements:
  production_scheme: https
  production_http_version: '2'
  local_development_exception: true