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

# Reportar uma execução

> As execuções que o seu CI rodou; a resposta traz o veredito estatístico já decidido: `pass`, `flaky`, `regression`, `pin_mismatch` ou `infrastructure_error`.



## OpenAPI

````yaml openapi/pt/cell.json POST /v1/scenario-runs
openapi: 3.1.0
info:
  title: API de dados da Niadra
  version: '1'
  description: >-
    Escrita, contexto, histórico, objetos, identidade, privacidade e governança
    de um espaço. Cada espaço tem um endereço estável, com o espaço e a região
    no nome.
servers:
  - url: https://{space}.{region}.api.niadra.com
    variables:
      space:
        default: acme-prod
        description: O espaço, que vem na chave de fonte.
      region:
        default: us-east-2
        description: A região do espaço, que também vem na chave.
security: []
paths:
  /v1/scenario-runs:
    post:
      tags:
        - turns
      summary: Reportar uma execução
      description: >-
        As execuções que o CI da empresa rodou; a resposta leva o veredito já
        decidido.


        **Autenticação.** Chave de fonte com o escopo `replay`, ou token de
        pessoa do Console com o papel `integration`, `security` (ou admin). Só
        responde num espaço com a funcionalidade `turns` ligada (o documento
        `features`); num espaço sem ela, 404.
      operationId: create_scenario_run_v1_scenario_runs_post
      parameters:
        - in: header
          name: Idempotency-Key
          required: true
          schema:
            maxLength: 256
            minLength: 1
            title: Idempotency-Key
            type: string
          description: >-
            Obrigatório. Guardado por 24 horas com o hash do corpo: a mesma
            chave com o mesmo corpo devolve a primeira resposta, e a mesma chave
            com outro corpo devolve 409 `conflict`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScenarioRunCreate'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScenarioRun'
          description: A execução, com o veredito decidido.
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: O pedido não bate com o contrato.
      security:
        - sourceKey: []
        - personToken: []
      x-codeSamples:
        - lang: python
          label: Python
          source: >-
            # The Replayer reports the run for you and returns Niadra's verdict

            run = Replayer(niadra, build_agent, build=BUILD).run(["sc_01J9..."],
            runs=5, vary=["prompts"])

            print(run.verdict)  # pass, flaky, regression, pin_mismatch or
            infrastructure_error
        - lang: typescript
          label: TypeScript
          source: >-
            // The Replayer reports the run for you and resolves with Niadra's
            verdict

            const run = await new Replayer(niadra, buildAgent, { build: BUILD
            }).run(["sc_01J9..."], { runs: 5, vary: ["prompts"] });

            console.log(run.verdict); // pass, flaky, regression, pin_mismatch
            or infrastructure_error
components:
  schemas:
    ScenarioRunCreate:
      additionalProperties: false
      description: >-
        O que o CI da empresa reporta depois de rodar os cenários N vezes: a
        estatística fica com a Niadra. Todo pino que a gravação exige precisa
        bater com a build gravada de cada cenário, menos os de `vary`.
      properties:
        build:
          $ref: '#/components/schemas/TurnBuild'
        mode:
          default: hermetic_turn
          enum:
            - hermetic_turn
            - hermetic_conversation
            - era_memory
          title: Mode
          type: string
        results:
          items:
            $ref: '#/components/schemas/ReplayResult-Input'
          maxItems: 5000
          minItems: 1
          title: Results
          type: array
        runs:
          anyOf:
            - maximum: 100
              minimum: 1
              type: integer
            - type: 'null'
          title: Runs
        scenario_ids:
          items:
            maxLength: 512
            minLength: 1
            type: string
          maxItems: 200
          minItems: 1
          title: Scenario Ids
          type: array
        vary:
          items:
            enum:
              - prompts
              - corpus_digest
              - model
              - assembler
              - tool_schemas
            type: string
          maxItems: 5
          title: Vary
          type: array
      required:
        - scenario_ids
        - build
        - results
      title: ScenarioRunCreate
      type: object
    ScenarioRun:
      additionalProperties: false
      properties:
        build:
          $ref: '#/components/schemas/TurnBuild'
        created_at:
          format: date-time
          title: Created At
          type: string
        mode:
          enum:
            - hermetic_turn
            - hermetic_conversation
            - era_memory
          title: Mode
          type: string
        run_id:
          maxLength: 512
          minLength: 1
          title: Run Id
          type: string
        status:
          enum:
            - pending
            - done
          title: Status
          type: string
        summary:
          $ref: '#/components/schemas/ScenarioRunSummary'
        vary:
          items:
            enum:
              - prompts
              - corpus_digest
              - model
              - assembler
              - tool_schemas
            type: string
          title: Vary
          type: array
        verdict:
          anyOf:
            - enum:
                - pass
                - flaky
                - infrastructure_error
                - pin_mismatch
                - regression
              type: string
            - type: 'null'
          description: O pior dos vereditos dos cenários.
          title: Verdict
      required:
        - run_id
        - status
        - mode
        - build
        - summary
        - created_at
      title: ScenarioRun
      type: object
    Problem:
      additionalProperties: false
      description: >-
        Detalhes do problema no formato da RFC 9457; `code` vem do catálogo de
        erros versionado.
      properties:
        code:
          title: Code
          type: string
        detail:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Detail
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Request Id
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          default: about:blank
          title: Type
          type: string
      required:
        - title
        - status
        - code
      title: Problem
      type: object
    TurnBuild:
      additionalProperties: false
      properties:
        adapter:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          description: O adaptador de framework e a versão dele, se houver.
          title: Adapter
        pins:
          $ref: '#/components/schemas/TurnPins'
        sdk:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          description: Por exemplo `niadra-python/0.7.0`.
          title: Sdk
      title: TurnBuild
      type: object
    ReplayResult-Input:
      additionalProperties: false
      description: >-
        Uma execução de um caso. `infrastructure_error` (o agente lançou erro,
        um blob não pôde ser lido ou não bateu com o digest, um tempo esgotado)
        é contado à parte e nunca derruba uma asserção; `pin_mismatch` é um caso
        que o executor parou na conferência dos pinos.
      properties:
        assertions:
          items:
            $ref: '#/components/schemas/AssertionOutcome'
          maxItems: 50
          title: Assertions
          type: array
        case_id:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          title: Case Id
        divergent_calls:
          default: 0
          minimum: 0
          title: Divergent Calls
          type: integer
        error:
          anyOf:
            - maxLength: 500
              type: string
            - type: 'null'
          title: Error
        latency_ms:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          title: Latency Ms
        paraphrase:
          default: false
          description: A entrada da execução foi uma paráfrase da gravada.
          title: Paraphrase
          type: boolean
        run:
          maximum: 100
          minimum: 1
          title: Run
          type: integer
        scenario_id:
          maxLength: 512
          minLength: 1
          title: Scenario Id
          type: string
        status:
          enum:
            - completed
            - pin_mismatch
            - infrastructure_error
          title: Status
          type: string
        turn_id:
          pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
          title: Turn Id
          type: string
      required:
        - scenario_id
        - turn_id
        - run
        - status
      title: ReplayResult
      type: object
    ScenarioRunSummary:
      additionalProperties: false
      properties:
        scenarios:
          items:
            $ref: '#/components/schemas/ScenarioVerdict'
          title: Scenarios
          type: array
      title: ScenarioRunSummary
      type: object
    TurnPins:
      additionalProperties: false
      description: >-
        O que precisa ser igual para um replay reproduzir este turno. O
        documento de gravação diz quais são exigidos; um turno sem um deles é
        guardado, marcado como não reproduzível.
      properties:
        assembler:
          anyOf:
            - maxLength: 128
              minLength: 1
              type: string
            - type: 'null'
          description: A versão do montador de contexto da própria empresa.
          title: Assembler
        corpus_digest:
          anyOf:
            - pattern: ^sha256:[0-9a-f]{64}$
              type: string
            - type: 'null'
          description: >-
            Digest dos arquivos que o agente consulta, calculado no SDK; nunca
            os arquivos.
          title: Corpus Digest
        model:
          anyOf:
            - maxLength: 128
              minLength: 1
              type: string
            - type: 'null'
          description: O modelo exato que o agente chamou.
          title: Model
        niadra:
          anyOf:
            - $ref: '#/components/schemas/TurnCompilerPins'
            - type: 'null'
        prompts:
          additionalProperties:
            maxLength: 128
            minLength: 1
            type: string
          description: Nome do prompt -> versão, por exemplo `core` -> `v16`.
          maxProperties: 50
          propertyNames:
            maxLength: 256
            minLength: 1
          title: Prompts
          type: object
        tool_schemas:
          additionalProperties:
            pattern: ^sha256:[0-9a-f]{64}$
            type: string
          description: Nome da ferramenta -> hash do esquema dela.
          maxProperties: 200
          propertyNames:
            maxLength: 256
            minLength: 1
          title: Tool Schemas
          type: object
      title: TurnPins
      type: object
    AssertionOutcome:
      additionalProperties: false
      properties:
        detail:
          anyOf:
            - maxLength: 500
              type: string
            - type: 'null'
          title: Detail
        id:
          pattern: ^[a-z0-9][a-z0-9_.-]{0,63}$
          title: Id
          type: string
        kind:
          enum:
            - tool_called
            - tool_not_called
            - hard_respected
            - no_denial_with_results
            - claims_traced
            - claims_match_state
            - no_promise_without_action
            - expected_in_topk
            - handoff_when
            - effect_once
            - budget
            - lexicon
            - tools_offered_match
          title: Kind
          type: string
        outcome:
          enum:
            - pass
            - fail
            - not_checked
          title: Outcome
          type: string
      required:
        - id
        - kind
        - outcome
      title: AssertionOutcome
      type: object
    ScenarioVerdict:
      additionalProperties: false
      properties:
        assertions:
          items:
            $ref: '#/components/schemas/AssertionStats'
          title: Assertions
          type: array
        baseline_run_id:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          description: A execução anterior comparada; nenhuma quando foi a gravação.
          title: Baseline Run Id
        completed:
          title: Completed
          type: integer
        infrastructure_errors:
          title: Infrastructure Errors
          type: integer
        needs_paraphrase:
          description: >-
            Uma asserção passou e falhou entre as execuções: a próxima execução
            dela precisa incluir paráfrases.
          title: Needs Paraphrase
          type: boolean
        pin_mismatches:
          title: Pin Mismatches
          type: integer
        scenario_id:
          maxLength: 512
          minLength: 1
          title: Scenario Id
          type: string
        verdict:
          enum:
            - pass
            - flaky
            - infrastructure_error
            - pin_mismatch
            - regression
          title: Verdict
          type: string
      required:
        - scenario_id
        - verdict
        - completed
        - infrastructure_errors
        - pin_mismatches
        - needs_paraphrase
        - assertions
      title: ScenarioVerdict
      type: object
    TurnCompilerPins:
      additionalProperties: false
      properties:
        compiler:
          anyOf:
            - maxLength: 128
              minLength: 1
              type: string
            - type: 'null'
          description: A versão do compilador de contexto, do contexto lido.
          title: Compiler
        pack_hash:
          anyOf:
            - maxLength: 128
              minLength: 1
              type: string
            - type: 'null'
          description: O hash do contexto que este turno leu.
          title: Pack Hash
      title: TurnCompilerPins
      type: object
    AssertionStats:
      additionalProperties: false
      description: >-
        Uma asserção sobre as execuções concluídas da execução, contra a linha
        de base dela. `p_value` é o teste exato de Fisher unilateral de que a
        execução passa menos vezes que a linha de base, arredondado a 6
        decimais.
      properties:
        baseline_failed:
          title: Baseline Failed
          type: integer
        baseline_passed:
          title: Baseline Passed
          type: integer
        drop:
          description: A taxa de aprovação da linha de base menos a da execução.
          title: Drop
          type: number
        failed:
          title: Failed
          type: integer
        flaky:
          title: Flaky
          type: boolean
        id:
          pattern: ^[a-z0-9][a-z0-9_.-]{0,63}$
          title: Id
          type: string
        not_checked:
          title: Not Checked
          type: integer
        p_value:
          title: P Value
          type: number
        passed:
          title: Passed
          type: integer
        regression:
          title: Regression
          type: boolean
      required:
        - id
        - passed
        - failed
        - not_checked
        - baseline_passed
        - baseline_failed
        - drop
        - p_value
        - regression
        - flaky
      title: AssertionStats
      type: object
  securitySchemes:
    sourceKey:
      type: http
      scheme: bearer
      description: nia_sk_...
    personToken:
      type: http
      scheme: bearer
      bearerFormat: JWT

````