A viagem de uma busca assistida

# (C) 2026 Rodrigo Rodrigues da Silva <rodrigo@flowlexi.com>
# SPDX-License-Identifier: AGPL-3.0-or-later

FLOW:
  DECL: bncc-map
  DESC: BNCC Click neutral assisted search with cited results
  ROLE: kernel

  INPS:
    - briefing
    # Texto completo opcional, enviado somente pelo gateway web.
    - plano
    - ano
    - disciplina
    - escopo
    # Identidade e referência vêm dos canais; nunca do texto do plano.
    - usuario_gw
    - ref
    - telegram_user

  FORM:
    briefing:
      type: string
      required: true
      label: Planejamento
      prompt: "Descreva a aula ou unidade para buscar habilidades."
      validators:
        - rule: {min_length: 20}
        - rule: {max_length: 2000}

    ano:
      type: integer
      required: true
      label: Ano
      prompt: "Em qual ano (1 a 9)?"
      validators:
        - rule: {between: [1, 9]}
          message: "Informe um ano entre 1 e 9."

    disciplina:
      type: string
      required: true
      label: Disciplina
      prompt: "Disciplina?"
      validators:
        - rule:
            enum:
              - Arte
              - Ciências
              - Educação Física
              - Ensino Religioso
              - Geografia
              - História
              - Língua Inglesa
              - Língua Portuguesa
              - Matemática
              - Computação
          message: "Informe uma disciplina válida."

    escopo:
      type: string
      required: true
      label: Escopo
      prompt: "É uma aula ou uma unidade/sequência?"
      validators:
        - rule: {enum: [aula, unidade]}

  BANK:
    ano_label: "{{ano}}º"
    # neutral: rótulo do log; não muda a busca.
    perfil_institucional: neutral
    min_relevance_score: 0.35

  STEP:
    # Três conjuntos sem sobreposição: componente selecionado,
    # apoio de linguagem e demais componentes.
    - DECL: build_core_query
      USE: template
      WITH: {file: templates/search_query.md}
      RETS: busca_nucleo

    - DECL: search_nucleo
      USE: bncc
      WITH:
        q: "{{busca_nucleo}}"
      RETS: nucleo

    - DECL: search_linguagem
      MUX: disciplina
      STEP:
        - MAT: Língua Portuguesa
          STEP:
            - USE: bncc
              WITH:
                q: >-
                  English language reading writing speaking listening.
                  {{briefing}}
                filters:
                  Disciplina: Língua Inglesa
              RETS: linguagem
        # ... Língua Inglesa busca apoio em Língua Portuguesa.
      # Outros componentes: busca nas duas línguas.
      ELSE:
        - USE: bncc
          WITH:
            q: >-
              leitura escrita oralidade English reading writing speaking.
              {{briefing}}
            filters:
              Disciplina:
                - Língua Portuguesa
                - Língua Inglesa
          RETS: linguagem

    - DECL: search_travessia
      MUX: disciplina
      STEP:
        # Exemplo: Matemática; há um ramo por componente.
        - MAT: Matemática
          STEP:
            - USE: bncc
              WITH:
                filters:
                  Disciplina:
                    - Arte
                    - Ciências
                    - Computação
                    - Educação Física
                    - Ensino Religioso
                    - Geografia
                    - História
              RETS: travessia
        # ... outros ramos excluem o componente selecionado.

    # As três listas recuperadas são reordenadas em paralelo.
    # Se um falhar, ERR: skip preserva a ordem do PaveDB.
    - DECL: rerank_candidates
      PAR: 3
      STEP:
        - DECL: rerank_nucleo
          USE: rerank
          WITH: {from: nucleo, query: "{{briefing}}"}
          RETS: nucleo
          ERR: skip
        - DECL: rerank_linguagem
          USE: rerank
          WITH: {from: linguagem, query: "{{briefing}}"}
          RETS: linguagem
          ERR: skip
        - DECL: rerank_travessia
          USE: rerank
          WITH: {from: travessia, query: "{{briefing}}"}
          RETS: travessia
          ERR: skip

    # ... três templates produzem *_count com base no escopo e
    # na pontuação técnica de correspondência ...
    - DECL: calibrate_habilidades
      USE: merge
      WITH:
        nucleo:
          take: "{{nucleo_count}}"
          pluck: [text, bars, meta]
        transversal:
          concat:
            - from: linguagem
              take: "{{linguagem_count}}"
              pluck: [text, bars, meta]
            - from: travessia
              take: "{{travessia_count}}"
              pluck: [text, bars, meta]
      RETS: habilidades

    # A geração vem depois da seleção e nunca altera habilidades.
    # ... um template produz avaliacao_prompt só com briefing e
    # textos oficiais selecionados ...
    - DECL: assess_plan
      USE: judge
      WITH:
        temperature: 0
        max_tokens: 180
        prompt: "{{avaliacao_prompt}}"
      RETS: avaliacao_raw
      ERR: {default: {json: {comentario: ""}}}

    # ... a renderização segura produz avaliacao ...
    - DECL: log_to_sheets
      PSH: sheetslog
      WITH:
        values:
          ano: "{{ano_label}}"
          disciplina: "{{disciplina}}"
          escopo: "{{escopo}}"
          perfil: "{{perfil_institucional}}"
          briefing: "{{briefing}}"
          habilidades: "{{habilidades}}"
          comentario: "{{avaliacao}}"
      ERR: skip

  OUTS:
    - briefing
    - ano
    - ano_label
    - disciplina
    - escopo
    - habilidades
    - avaliacao