44 · Respostas fundamentadas nas suas fontes

Idiomas

O seletor lê turnos escritos em inglês e em português do Brasil (pt-BR). O idioma é escolhido, nunca adivinhado a partir do turno: na página Settings do console (Language the selector reads), em language numa requisição de plano, ou no settings.language do seu arquivo de vocabulário; sem nenhum deles, inglês. Um turno em português pode ser digitado com os acentos ou sem eles. O português europeu não é uma gramática que o seletor tenha, e um turno em qualquer outra língua não é lido.

Alguns turnos só pedem informação -- how long does a refund take? -- e nenhuma ferramenta os responde. Com on_unread: answer, uma pergunta assim é respondida a partir dos seus próprios documentos: as passagens que casam com ela são encontradas na sua máquina, a resposta é feita do que elas dizem, e cada frase carrega a passagem de onde veio. Uma frase que nenhuma passagem sustenta é removida, e quando nada sobra o agente diz que não tem resposta.

Os seus documentos, indexados na sua máquina

stalwart sources build lê os seus documentos e escreve um índice, aqui, com o runtime licenciado:

$ stalwart sources build docs/delivery.md docs/refunds.md --out sources.json
Indexed 2 document(s), 3 passage(s), into sources.json (9c26747cc5c5).
$ echo $?
0
$ stalwart sources ask "Quanto tempo leva um estorno?" --index sources.json
Um estorno chega ao cartão com que o pedido foi pago em três a cinco dias úteis.  [refunds.md > Quanto tempo leva um estorno]
$ echo $?
0

• Markdown (.md) e HTML (.html, .htm) são divididos nos seus títulos e depois nas linhas em branco: cada parágrafo é uma passagem, sob o título acima dele. Texto simples é dividido nas linhas em branco. O texto de um PDF é lido quando o pypdf está instalado.
• Cada passagem é indexada pelas suas palavras e pelas palavras do seu título; um arquivo de vocabulário (--vocabulary) acrescenta os termos e parentescos que o seu vocabulário declara, para que uma pergunta nas palavras dos seus clientes encontre uma passagem nas suas.
• Reindexar é construir de novo: o índice é um arquivo, com o seu digest impresso, e o agente lê o arquivo que recebe.
• Um arquivo que não pode ser lido -- ausente, vazio, fora de UTF-8, um PDF sem pypdf -- para a construção com o seu nome e status de saída 2.

stalwart sources ask responde a uma pergunta a partir do índice como o agente responderia com o compositor extract, cada frase com o documento e o título de onde veio, para que você veja o que os seus usuários vão ouvir.

Os documentos e o índice ficam na sua máquina. Os servidores da Stalwart nunca os recebem.

Respondendo no agente

Um agente responde a partir do índice quando o seu on_unread é answer -- a terceira escolha ao lado de refuse e de repassar o turno (capítulo 45) -- e answers: nomeia o índice:

desk = Agent("desk", tools=[get_order, charge_card], model="anthropic:claude-sonnet-5-5",
             on_unread="answer", answers={"index": "sources.json", "composer": "extract"})

for text in ("Quanto tempo leva um estorno?",
             "Um vale-presente pode ser estornado?",
             "cobre 40,00 do pedido 4411"):
    reply = desk.chat(text, user="u-17")
    shown = reply.waiting[0].wording if reply.waiting else reply.text
    print(f"{text}\n  -> {shown}")

Quanto tempo leva um estorno?
  -> Um estorno chega ao cartão com que o pedido foi pago em três a cinco dias úteis.
Um vale-presente pode ser estornado?
  -> Um pedido pode ser estornado em até 30 dias após a entrega. Um vale-presente não pode ser estornado.
cobre 40,00 do pedido 4411
  -> Executar charge_card?

As duas perguntas foram respondidas a partir das passagens; cobre 40,00 do pedido 4411 pede que algo seja feito, então foi para a cobrança e a sua confirmação, e nunca para os documentos. Uma ação nunca é respondida com documentação: uma passagem que descreve como funciona um reembolso não é um reembolso. Uma pergunta feita ao lado de uma ação -- estorne o pedido 4411 e me diga quanto tempo leva -- é respondida depois que a ação rodou.

answers: aceita index, k (no máximo essa quantidade de passagens, 3 por padrão), floor (nenhuma passagem com pontuação abaixo dele, 0,3 por padrão, numa escala de 0 a 1) e composer. Os que um agente não informa vêm da página Configurações do seu console, no primeiro turno da conversa.

Os compositores

• extract: a resposta são as próprias frases das passagens que compartilham um termo com a pergunta, na ordem de classificação. Nenhum modelo é chamado, e cada frase é sustentada por construção.
• compose: o próprio modelo do seu agente escreve a resposta a partir das passagens numeradas, com a sua chave, marcando cada frase com as passagens de que depende. Cada chamada ao modelo conta como um answer_calls. Uma resposta que fica sem nenhuma frase depois da verificação ganha uma segunda tentativa.

Quais planos incluem cada um, gerado a partir das linhas dos planos:

Compositor	Gratuito	Pago	Enterprise
extract	✓	✓	✓
compose	—	incluído, 20.000 answer_calls por mês	incluído, answer_calls sem limite

De qualquer forma, o runtime confere cada frase com as passagens que ela cita: cada número, data, valor, nome e negação nela precisa estar numa delas. Uma frase que falha é removida. A recuperação e a verificação rodam no runtime, sem nenhuma chamada de rede; compose chama o seu modelo, e nada mais.

Citações

Cada frase de uma resposta fica ligada às suas passagens: o documento, o título e, quando o documento deu um, o seu link. stalwart sources ask as imprime, como acima, e a interface do stalwart serve as mostra abaixo da resposta (capítulo 35). Uma regra do capítulo 43 pode acrescentar uma frase sempre que uma passagem com uma dada etiqueta for citada.

Sem resposta fundamentada

Quando nenhuma passagem tem pontuação acima do piso, ou nenhuma frase sobrevive à verificação, o resultado é no_grounded_answer, e o agente segue como se on_unread fosse refuse: a pessoa é convidada uma vez a dizer de novo, e depois ouve que aquilo não pode ser feito. Aqui o documento de reembolsos é apagado e o índice é construído de novo:

$ rm docs/refunds.md
$ stalwart sources build docs/delivery.md --out sources.json
Indexed 1 document(s), 1 passage(s), into sources.json (360ee6cde035).
$ echo $?
0
$ stalwart sources ask "Quanto tempo leva um estorno?" --index sources.json
No grounded answer: no passage scores above the floor. The agent would refuse or hand the turn off.
$ echo $?
1

O comando sai com 1 quando não há resposta fundamentada.

O que é guardado, e onde

Nada disso é guardado por nós. Os documentos, o índice, as perguntas e as respostas ficam na sua máquina e no seu armazenamento. Só a contagem de answer_calls é relatada, com os outros medidores da sua licença.

Os limites

• Uma frase sustentada concorda com a sua passagem. Isso não torna a passagem verdadeira, nem atual: um documento desatualizado dá respostas desatualizadas.
• A recuperação casa palavras, pesadas por quão raras elas são nos seus documentos. Uma passagem que compartilha palavras suficientes de uma pergunta para ficar acima do piso é usada, seja ou não sobre a pergunta; o piso e o k são o quanto ela é exigente.
• A verificação confere números, datas, valores, nomes e negações com as passagens. Uma frase que reescreve uma passagem e muda o seu sentido com outras palavras pode passar por ela.