> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outerproduct.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create training job

> Compile the training graph and hand it to the scheduler.

The router's responsibility ends at "ship the DTO": validate the request
(RBAC + spec coherence), build the dataset and check it against the
caller's role-shape limits, then hand the built dataset to
:func:`_submit_training_run`, which compiles the graph, cloudpickles the
context to S3, and ``put``s a :class:`RequestToComputeGraph` on the
in-process inbox. The scheduler owns the ``jobs`` and ``computation_node``
tables and INSERTs both atomically; the router awaits the one-shot reply
future on the submission for the minted ``job_id`` and returns that
resource id.

All validation/assertion lives here, before the submit — the submit step
only submits.



## OpenAPI

````yaml https://api.outerproduct.com/openapi.json post /v1/training_jobs
openapi: 3.1.0
info:
  title: OuterProduct API
  description: >-
    Public-facing REST API for OuterProduct model distillation, prediction, and
    explanation.
  version: 0.1.8
servers: []
security: []
paths:
  /v1/training_jobs:
    post:
      tags:
        - training
      summary: Create training job
      description: >-
        Compile the training graph and hand it to the scheduler.


        The router's responsibility ends at "ship the DTO": validate the request

        (RBAC + spec coherence), build the dataset and check it against the

        caller's role-shape limits, then hand the built dataset to

        :func:`_submit_training_run`, which compiles the graph, cloudpickles the

        context to S3, and ``put``s a :class:`RequestToComputeGraph` on the

        in-process inbox. The scheduler owns the ``jobs`` and
        ``computation_node``

        tables and INSERTs both atomically; the router awaits the one-shot reply

        future on the submission for the minted ``job_id`` and returns that

        resource id.


        All validation/assertion lives here, before the submit — the submit step

        only submits.
      operationId: createTrainingJobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTrainingJobRequest-Input'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTrainingJobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - BearerAuth: []
components:
  schemas:
    CreateTrainingJobRequest-Input:
      properties:
        dataframe:
          $ref: '#/components/schemas/WireDataFrame-Input'
          description: >-
            Serialized DataFrame plan over the org's registered sources. The
            server rebuilds the org's Context, deserializes this against it, and
            materializes the (possibly filtered/derived) training rows. The leaf
            source must be a registered source_table.
        job_tags:
          additionalProperties:
            type: string
          type: object
          title: Job Tags
          description: Caller-supplied tags echoed on the training job resource.
        task:
          anyOf:
            - oneOf:
                - $ref: '#/components/schemas/Regression'
                - $ref: '#/components/schemas/Binclass'
                - $ref: '#/components/schemas/Multiclass'
                - $ref: '#/components/schemas/Forecasting'
                - $ref: '#/components/schemas/SequenceRegression'
                - $ref: '#/components/schemas/SequenceBinclass'
                - $ref: '#/components/schemas/SequenceMulticlass'
              discriminator:
                propertyName: task_kind
                mapping:
                  binclass:
                    $ref: '#/components/schemas/Binclass'
                  forecasting:
                    $ref: '#/components/schemas/Forecasting'
                  multiclass:
                    $ref: '#/components/schemas/Multiclass'
                  regression:
                    $ref: '#/components/schemas/Regression'
                  sequence_binclass:
                    $ref: '#/components/schemas/SequenceBinclass'
                  sequence_multiclass:
                    $ref: '#/components/schemas/SequenceMulticlass'
                  sequence_regression:
                    $ref: '#/components/schemas/SequenceRegression'
            - type: 'null'
          title: Task
          description: >-
            Learning task and its target columns (a discriminated union on
            ``task_kind``). Required for supervised training.
        hpo_space:
          anyOf:
            - $ref: '#/components/schemas/HPOSpace'
            - type: 'null'
          description: >-
            The search space: candidate model families and, per family, which
            hyperparameters are fixed vs searched
            (Float/Int/Categorical/Mixture). If omitted, the server picks a
            default space based on dataset shape.
        metrics:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Metrics
          description: >-
            Metric names to optimise, e.g. ['auc'] or ['auc',
            'neg_class_error']. A list of metrics is optimised jointly via
            Optuna's native multi-objective (Pareto) search, with no metric
            privileged. Custom Python callables are not supported in v1.
        optimizer:
          anyOf:
            - $ref: '#/components/schemas/Optimizer'
            - type: 'null'
          description: >-
            How to search the space: sampler ('tpe'/'random'/'cmaes') and a
            round-structured trial budget (n_trials_per_step proposed per round
            x n_steps rounds). If omitted, the server uses a default optimizer.
        n_cv_splits:
          anyOf:
            - type: integer
            - type: 'null'
          title: N Cv Splits
          description: K-fold cross-validation folds. None means a single holdout split.
        ensemble:
          type: boolean
          title: Ensemble
          description: >-
            If true, build a Caruana-style ensemble across stage-1 fold/trial
            models instead of refitting the winner on full data.
          default: false
        random_state:
          type: integer
          title: Random State
          default: 42
      type: object
      required:
        - dataframe
      title: CreateTrainingJobRequest
    CreateTrainingJobResponse:
      properties:
        id:
          $ref: '#/components/schemas/ID'
      type: object
      required:
        - id
      title: CreateTrainingJobResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    WireDataFrame-Input:
      properties:
        version:
          type: integer
          const: 1
          title: Version
          default: 1
        plan:
          additionalProperties: true
          type: object
          title: Plan
        columns:
          items:
            $ref: '#/components/schemas/FieldDef-Input'
          type: array
          title: Columns
      additionalProperties: false
      type: object
      required:
        - plan
        - columns
      title: WireDataFrame
    Regression:
      properties:
        task_kind:
          type: string
          const: regression
          title: Task Kind
          default: regression
        label_column:
          type: string
          title: Label Column
          description: Target column name within the dataset.
      type: object
      required:
        - label_column
      title: Regression
    Binclass:
      properties:
        task_kind:
          type: string
          const: binclass
          title: Task Kind
          default: binclass
        label_column:
          type: string
          title: Label Column
          description: Target column name within the dataset.
      type: object
      required:
        - label_column
      title: Binclass
    Multiclass:
      properties:
        task_kind:
          type: string
          const: multiclass
          title: Task Kind
          default: multiclass
        label_column:
          type: string
          title: Label Column
          description: Target column name within the dataset.
      type: object
      required:
        - label_column
      title: Multiclass
    Forecasting:
      properties:
        task_kind:
          type: string
          const: forecasting
          title: Task Kind
          default: forecasting
        label_column:
          type: string
          title: Label Column
          description: Target column whose future values are forecast.
        id_column:
          type: string
          title: Id Column
          description: Series/entity identifier column.
        timestamp_column:
          type: string
          title: Timestamp Column
          description: Within-series ordering timestamp column.
        horizon:
          type: integer
          minimum: 1
          title: Horizon
          description: Number of steps ahead to forecast.
        lookback:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Lookback
          description: History window length; None uses all available history.
      type: object
      required:
        - label_column
        - id_column
        - timestamp_column
        - horizon
      title: Forecasting
    SequenceRegression:
      properties:
        label_column:
          type: string
          title: Label Column
          description: Per-entity target column.
        id_column:
          type: string
          title: Id Column
          description: Entity identifier; one label per entity.
        timestamp_column:
          type: string
          title: Timestamp Column
          description: Within-entity ordering column.
        tabular_columns:
          items:
            type: string
          type: array
          title: Tabular Columns
          description: >-
            Static per-entity feature columns (constant within an entity),
            modeled as one per-entity token each. Every other column that is not
            the id, timestamp, or label is a per-step sequence feature.
        task_kind:
          type: string
          const: sequence_regression
          title: Task Kind
          default: sequence_regression
      type: object
      required:
        - label_column
        - id_column
        - timestamp_column
      title: SequenceRegression
    SequenceBinclass:
      properties:
        label_column:
          type: string
          title: Label Column
          description: Per-entity target column.
        id_column:
          type: string
          title: Id Column
          description: Entity identifier; one label per entity.
        timestamp_column:
          type: string
          title: Timestamp Column
          description: Within-entity ordering column.
        tabular_columns:
          items:
            type: string
          type: array
          title: Tabular Columns
          description: >-
            Static per-entity feature columns (constant within an entity),
            modeled as one per-entity token each. Every other column that is not
            the id, timestamp, or label is a per-step sequence feature.
        task_kind:
          type: string
          const: sequence_binclass
          title: Task Kind
          default: sequence_binclass
      type: object
      required:
        - label_column
        - id_column
        - timestamp_column
      title: SequenceBinclass
    SequenceMulticlass:
      properties:
        label_column:
          type: string
          title: Label Column
          description: Per-entity target column.
        id_column:
          type: string
          title: Id Column
          description: Entity identifier; one label per entity.
        timestamp_column:
          type: string
          title: Timestamp Column
          description: Within-entity ordering column.
        tabular_columns:
          items:
            type: string
          type: array
          title: Tabular Columns
          description: >-
            Static per-entity feature columns (constant within an entity),
            modeled as one per-entity token each. Every other column that is not
            the id, timestamp, or label is a per-step sequence feature.
        task_kind:
          type: string
          const: sequence_multiclass
          title: Task Kind
          default: sequence_multiclass
      type: object
      required:
        - label_column
        - id_column
        - timestamp_column
      title: SequenceMulticlass
    HPOSpace:
      properties:
        models:
          items:
            $ref: '#/components/schemas/ModelParamSpace'
          type: array
          title: Models
      type: object
      title: HPOSpace
    Optimizer:
      properties:
        kind:
          type: string
          enum:
            - tpe
            - random
            - cmaes
          title: Kind
          default: tpe
        n_trials_per_step:
          type: integer
          minimum: 1
          title: N Trials Per Step
          description: Trials proposed and evaluated per optimization round.
          default: 2
        n_steps:
          type: integer
          minimum: 1
          title: N Steps
          description: Number of sequential optimization rounds.
          default: 2
      type: object
      title: Optimizer
    ID:
      anyOf:
        - type: string
          format: uuid
        - type: string
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    FieldDef-Input:
      properties:
        name:
          type: string
          title: Name
        datatype:
          $ref: '#/components/schemas/DataType-Input'
      additionalProperties: false
      type: object
      required:
        - name
        - datatype
      title: FieldDef
    ModelParamSpace:
      properties:
        family:
          type: string
          title: Family
        search:
          additionalProperties:
            oneOf:
              - $ref: '#/components/schemas/Float'
              - $ref: '#/components/schemas/Int'
              - $ref: '#/components/schemas/Categorical'
              - $ref: '#/components/schemas/Mixture'
            discriminator:
              propertyName: kind
              mapping:
                categorical:
                  $ref: '#/components/schemas/Categorical'
                float:
                  $ref: '#/components/schemas/Float'
                int:
                  $ref: '#/components/schemas/Int'
                mixture:
                  $ref: '#/components/schemas/Mixture'
          type: object
          title: Search
        fixed:
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          type: object
          title: Fixed
      type: object
      required:
        - family
      title: ModelParamSpace
    DataType-Input:
      oneOf:
        - $ref: '#/components/schemas/String'
        - $ref: '#/components/schemas/Boolean'
        - $ref: '#/components/schemas/CategoricalString'
        - $ref: '#/components/schemas/CategoricalInteger'
        - $ref: '#/components/schemas/Integer'
        - $ref: '#/components/schemas/Real'
        - $ref: '#/components/schemas/Datetime-Input'
      discriminator:
        propertyName: kind
        mapping:
          boolean:
            $ref: '#/components/schemas/Boolean'
          categorical_integer:
            $ref: '#/components/schemas/CategoricalInteger'
          categorical_string:
            $ref: '#/components/schemas/CategoricalString'
          datetime:
            $ref: '#/components/schemas/Datetime-Input'
          integer:
            $ref: '#/components/schemas/Integer'
          real:
            $ref: '#/components/schemas/Real'
          string:
            $ref: '#/components/schemas/String'
    Float:
      properties:
        kind:
          type: string
          const: float
          title: Kind
          default: float
        low:
          type: number
          title: Low
        high:
          type: number
          title: High
        log:
          type: boolean
          title: Log
          default: false
      type: object
      required:
        - low
        - high
      title: Float
    Int:
      properties:
        kind:
          type: string
          const: int
          title: Kind
          default: int
        low:
          type: integer
          title: Low
        high:
          type: integer
          title: High
        log:
          type: boolean
          title: Log
          default: false
      type: object
      required:
        - low
        - high
      title: Int
    Categorical:
      properties:
        kind:
          type: string
          const: categorical
          title: Kind
          default: categorical
        choices:
          items:
            $ref: '#/components/schemas/JsonValue'
          type: array
          title: Choices
      type: object
      required:
        - choices
      title: Categorical
    Mixture:
      properties:
        kind:
          type: string
          const: mixture
          title: Kind
          default: mixture
        spike:
          type: number
          title: Spike
          default: 0
        inner:
          oneOf:
            - $ref: '#/components/schemas/Float'
            - $ref: '#/components/schemas/Int'
            - $ref: '#/components/schemas/Categorical'
          title: Inner
          discriminator:
            propertyName: kind
            mapping:
              categorical:
                $ref: '#/components/schemas/Categorical'
              float:
                $ref: '#/components/schemas/Float'
              int:
                $ref: '#/components/schemas/Int'
      type: object
      required:
        - inner
      title: Mixture
    JsonValue: {}
    String:
      properties:
        kind:
          type: string
          const: string
          title: Kind
          default: string
      additionalProperties: false
      type: object
      title: String
    Boolean:
      properties:
        kind:
          type: string
          const: boolean
          title: Kind
          default: boolean
      additionalProperties: false
      type: object
      title: Boolean
    CategoricalString:
      properties:
        kind:
          type: string
          const: categorical_string
          title: Kind
          default: categorical_string
        values:
          items:
            type: string
          type: array
          title: Values
      additionalProperties: false
      type: object
      required:
        - values
      title: CategoricalString
    CategoricalInteger:
      properties:
        kind:
          type: string
          const: categorical_integer
          title: Kind
          default: categorical_integer
        values:
          items:
            type: integer
          type: array
          title: Values
      additionalProperties: false
      type: object
      required:
        - values
      title: CategoricalInteger
    Integer:
      properties:
        kind:
          type: string
          const: integer
          title: Kind
          default: integer
        bits:
          type: integer
          enum:
            - 8
            - 16
            - 32
            - 64
          title: Bits
        signed:
          type: boolean
          title: Signed
          default: true
        range:
          anyOf:
            - $ref: '#/components/schemas/Range_int_'
            - type: 'null'
      additionalProperties: false
      type: object
      required:
        - bits
      title: Integer
    Real:
      properties:
        kind:
          type: string
          const: real
          title: Kind
          default: real
        bits:
          type: integer
          enum:
            - 16
            - 32
            - 64
          title: Bits
        range:
          anyOf:
            - $ref: '#/components/schemas/Range_float_'
            - type: 'null'
      additionalProperties: false
      type: object
      required:
        - bits
      title: Real
    Datetime-Input:
      properties:
        kind:
          type: string
          const: datetime
          title: Kind
          default: datetime
      additionalProperties: false
      type: object
      title: Datetime
    Range_int_:
      properties:
        min:
          anyOf:
            - type: integer
            - type: 'null'
          title: Min
        max:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max
      additionalProperties: false
      type: object
      title: Range[int]
    Range_float_:
      properties:
        min:
          anyOf:
            - type: number
            - type: 'null'
          title: Min
        max:
          anyOf:
            - type: number
            - type: 'null'
          title: Max
      additionalProperties: false
      type: object
      title: Range[float]
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key or OAuth2/OIDC access token
      description: >-
        An API key or OAuth2/OIDC access token sent as `Authorization: Bearer
        <token>`.

````