> ## 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 reasoning job

> Submit a reasoning fit job and return its resource id.

Reasoning reuses the training ``optimize`` loop over the surrogate search
space: build the ``OptimizationContext`` + bootstrap the optimizer, emit round 0 of
a ``training/fit`` ×(n_trials_per_step) → ``training/reduce`` graph (run for
``n_steps`` rounds), pickle the context (+ flat finalize plan, + the terminal
``reasoning/finalize`` spec) to S3, and ``put`` a
:class:`RequestToComputeGraph` on the scheduler's in-process inbox. The
terminal reduce appends ``reasoning/finalize`` once the optimizer is done.
The router never touches ``jobs`` or ``computation_node`` — it only builds +
ships. Synthetic-data generation and teacher distillation were removed from
the API server.



## OpenAPI

````yaml https://api.outerproduct.com/openapi.json post /v1/reasoning_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/reasoning_jobs:
    post:
      tags:
        - reasoning
      summary: Create reasoning job
      description: >-
        Submit a reasoning fit job and return its resource id.


        Reasoning reuses the training ``optimize`` loop over the surrogate
        search

        space: build the ``OptimizationContext`` + bootstrap the optimizer, emit
        round 0 of

        a ``training/fit`` ×(n_trials_per_step) → ``training/reduce`` graph (run
        for

        ``n_steps`` rounds), pickle the context (+ flat finalize plan, + the
        terminal

        ``reasoning/finalize`` spec) to S3, and ``put`` a

        :class:`RequestToComputeGraph` on the scheduler's in-process inbox. The

        terminal reduce appends ``reasoning/finalize`` once the optimizer is
        done.

        The router never touches ``jobs`` or ``computation_node`` — it only
        builds +

        ships. Synthetic-data generation and teacher distillation were removed
        from

        the API server.
      operationId: createReasoningJobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReasoningJobRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateReasoningJobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - BearerAuth: []
components:
  schemas:
    CreateReasoningJobRequest:
      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) fit 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 reasoning 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.
        metrics:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Metrics
          description: >-
            HPO objective metric names (e.g. 'neg_rmse', 'neg_class_error',
            'auc'). Order is objective order; passing more than one runs
            multi-objective (Pareto) search. If omitted, the server uses the
            task default (neg_rmse for regression, neg_class_error otherwise).
        hpo_space:
          anyOf:
            - $ref: '#/components/schemas/HPOSpace'
            - type: 'null'
          description: >-
            The surrogate search space, which also selects the model families to
            search over. May contain multiple families; HPO returns the single
            best surrogate (reasoning does not build ensembles). Each family
            must be one of ['tabm', 'tabicl', 'xrfm']. If omitted, the server
            fits tabm.
        optimizer:
          anyOf:
            - $ref: '#/components/schemas/Optimizer'
            - type: 'null'
          description: >-
            How to search the surrogate space: sampler ('tpe'/'random'/'cmaes')
            and a round-structured trial budget (n_trials_per_step x n_steps).
            If omitted, the server uses a default.
        random_state:
          type: integer
          title: Random State
          default: 42
      type: object
      required:
        - dataframe
      title: CreateReasoningJobRequest
    CreateReasoningJobResponse:
      properties:
        id:
          $ref: '#/components/schemas/ID'
      type: object
      required:
        - id
      title: CreateReasoningJobResponse
    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>`.

````