# Annotated review companion for justinchuby/onnx-genai-example-esm2-t6-8m.
# Model form: ESM-2 protein embeddings.
# Canonical authority: inference_metadata.yaml at revision d1e2ada5086f6ef0d1bfffb4099a5292104dbc1b.
# Comments explain authored semantics, derived structure, and fail-closed omissions.
# After YAML parsing this file is mechanically equal to the canonical metadata; comments do not create a second contract.
# Backend implementation, recorded execution, and performance evidence remain separate from this portable metadata.
# Schema spelling `v1` normalizes under the current reader; versioning gates unknown fields before typed parsing. No component authors batch_capacity, so independent requests must execute per item at every component.
schema_version: v1
# Profiles define required API interpretation of workflow tensors. They are authored semantics, not proof that every backend implements the profile.
profiles:
  # Profile `embedding` maps encoder hidden states to embedding output and authored pooling semantics; a required unsupported profile must be refused.
  embedding:
    kind: embedding
    version: '1.0'
    # `required` forbids silently returning uninterpreted tensors when this profile cannot execute.
    requirement: required
    # These bindings map profile roles to exact workflow output names.
    outputs:
      last_hidden_state: last_hidden_state
    # Pooling is authored output semantics: {kind=mean, axis=1, normalize=False}.
    pooling:
      kind: mean
      axis: 1
      normalize: false
# The pipeline contains executable package semantics. Deployment/QoS policy and backend-derived execution plans live outside this portable contract.
pipeline:
  # This typed SSA workflow is the authoritative execution contract for the package.
  workflow:
    # Manifest vocabulary declares interpreter/adapter ABI requirements. It is not ORT/native readiness or performance evidence.
    manifest:
      # Current v1 capability strings mirror typed workflow structure; the structure remains the semantic source of truth.
      capabilities:
      - workflow_ssa
      - linear_effects
      - typed_emit
    # Effect contracts govern retry and speculative safety. They are correctness requirements used for admission, not performance hints.
    effects:
      # Effect `encode` declares retry=pure and speculation safety={kind=clonable}.
      encode:
        retry: pure
        speculation_safety:
          kind: clonable
    # Workflow inputs are the complete typed boundary. Roles and sources are authored; absent required values must fail before execution.
    inputs:
      # Input `request.input_ids` is required, provided by the request through a typed runtime role, and carries runtime role prompt_tokens@1.0. Unsupported required roles must fail closed.
      request.input_ids:
        # Authored tensor ABI: dtype int64, rank 2, shape [batch, sequence_len]. Request rows stay aligned on axis 0; this preserves identity but does not by itself authorize grouping independent requests.
        contract:
          dtype: int64
          rank: 2
          shape:
          - batch
          - sequence_len
          # Tensor row layout is structural. Only component batch_capacity can authorize grouping independent requests.
          batch_layout:
            kind: request_aligned
            axis: 0
        # Role identifies runtime semantics without relying on a model-family name.
        role:
          kind: runtime
          version: '1.0'
          role: prompt_tokens
        # Source states who must provide this value; the runtime must not invent application data.
        source:
          kind: request
        # Required values fail closed when absent; optional values may use only their authored default/presence rule.
        required: true
      # Input `request.attention_mask` is required, provided by the application as request.attention_mask, and carries opaque. Unsupported required roles must fail closed.
      request.attention_mask:
        # Authored tensor ABI: dtype int64, rank 2, shape [batch, sequence_len]. Request rows stay aligned on axis 0; this preserves identity but does not by itself authorize grouping independent requests.
        contract:
          dtype: int64
          rank: 2
          shape:
          - batch
          - sequence_len
          # Tensor row layout is structural. Only component batch_capacity can authorize grouping independent requests.
          batch_layout:
            kind: request_aligned
            axis: 0
        # Role identifies runtime semantics without relying on a model-family name.
        role:
          kind: opaque
        # Source states who must provide this value; the runtime must not invent application data.
        source:
          kind: application
          name: request.attention_mask
        # Required values fail closed when absent; optional values may use only their authored default/presence rule.
        required: true
    # Workflow outputs are the complete public result boundary and retain explicit tensor contracts.
    outputs:
      # Output `last_hidden_state` publishes the authored tensor result at the post_adapter stage; it is not backend-readiness evidence.
      last_hidden_state:
        # Authored tensor ABI: dtype float32, rank 3, shape [batch, sequence_len, 320]. Request rows stay aligned on axis 0; this preserves identity but does not by itself authorize grouping independent requests.
        contract:
          dtype: float32
          rank: 3
          shape:
          - batch
          - sequence_len
          - 320
          # Tensor row layout is structural. Only component batch_capacity can authorize grouping independent requests.
          batch_layout:
            kind: request_aligned
            axis: 0
        role: tensor
        # Stage records whether adapters/postprocessing have run before this value is exposed.
        stage: post_adapter
    # Components are the executable artifacts and semantic policy programs. Their presence does not prove ORT/native readiness or performance.
    components:
      # Component `encoder` is an encoder compute graph using onnx from `model.onnx`. No batch_capacity is authored, so the runtime must not group independent requests at this component.
      encoder:
        # Selects a packaged implementation/artifact only; provider/backend readiness requires separate recorded evidence.
        implementation:
          kind: onnx
          artifact: model.onnx
        # Ports bind workflow names to the artifact's exact graph ABI; model-family inference is forbidden.
        ports:
          # Semantic port roles identify tokens, logits, positions, masks, caches, or media without architecture-name conditionals.
          roles:
            input_ids: token_ids
            attention_mask: attention_mask
            last_hidden_state: hidden_states
    # The ordered SSA program defines actual execution and dataflow; capability strings are not a substitute for these steps.
    steps:
      # Invoke component `encoder` with explicit SSA input/output bindings; this is executable tensor computation, not a host-side capability flag.
    - kind: invoke
      component: encoder
      # SSA bindings supply exact values to this step; no implicit tensor discovery occurs.
      inputs:
        input_ids: request.input_ids
        attention_mask: request.attention_mask
      # SSA output names become the only values subsequent steps may consume.
      outputs:
        last_hidden_state: encoder.last_hidden_state
      # Publish `encoder.last_hidden_state` as output `last_hidden_state` using replace semantics.
    - kind: emit
      value: encoder.last_hidden_state
      output: last_hidden_state
      # Emit/update mode is semantic replacement/append behavior, not a buffering optimization.
      mode: replace