Citações

Quando você faz um explicador pela API a partir dos seus próprios arquivos, pode fazer a narração citá-los. Cada linha falada registra então de qual parte de qual arquivo ela ensina, e você lê isso de volta como dados.

Use isso para mostrar a fonte ao lado do vídeo, para conferir a aula contra o arquivo de onde ela veio, ou para ligar uma frase da narração às linhas exatas que ela descreve.

Ativando as citações

Envie cite_attachments: true com a requisição de criação, junto com pelo menos um anexo de texto. O explicador é escrito com as citações no lugar; nada muda na página dele.

curl -s "$SCRIMBA/api/v1/explainers" \
  -H "Authorization: Bearer $SCRIMBA_KEY" \
  -F "prompt=Walk through how this handler checks the token" \
  -F "cite_attachments=true" \
  -F "[email protected]"

Só arquivos de texto e código são citados, nunca imagens ou PDFs. Sem cite_attachments, o explicador é feito como sempre e toda lista de citações fica vazia. Um valor que não seja true nem false responde 400 invalid_cite_attachments.

Lendo as citações

Quando o explicador está pronto, GET /api/v1/explainers/:id/transcript retorna a narração como uma lista de entradas, uma por trecho falado em ordem de reprodução. Cada entrada carrega suas citações em references.

{
  "index": 3,
  "slide": 2,
  "title": "Checking the token",
  "text": "The handler reads the token from the header, then compares it to the stored secret.",
  "references": [
    {
      "text": "reads the token from the header",
      "text_start": 12,
      "text_end": 43,
      "attachment": 1,
      "offset": 412,
      "length": 39,
      "lines": [10, 10],
      "cited_text": "const token = req.headers.authorization"
    }
  ]
}

Uma citação liga palavras da narração a uma parte de um arquivo:

• text, text_start e text_end são as palavras da entrada que a citação sustenta, e onde elas ficam no text da entrada.
• attachment é o arquivo, pelo número ref que o objeto explicador lista em attachments.
• offset, length, lines e cited_text são a parte citada desse arquivo: a posição dela em caracteres, a primeira e a última linha contadas a partir de 1, e o texto em si.

Enquanto o explicador ainda está gerando, ou depois que ele falhou, o endpoint responde 409 not_ready.

O que esperar

O modelo decide o que citar. Ele cita a frase, o valor ou o trecho de onde um ponto vem, a menor parte útil, e um trecho pode carregar várias citações para um arquivo ou vários. Uma linha que não ensina nada dos arquivos não tem nenhuma.

• text_start e text_end são null quando a narração não fala as palavras citadas exatamente como estão escritas; nesse caso, procure você mesmo em text.
• Um arquivo de texto é lido até 30.000 caracteres, e offset conta dentro do que foi lido.
• Uma citação cuja parte citada não é encontrada no arquivo é deixada de fora.

Para a referência campo a campo, veja A API de explicadores.