Máquina de Estados - Detalhes

24 min

Este é um manual mais avançado das capacidades da máquina de estados. Os exemplos mostrados aqui pertencem ao editor de código de uma skill.

# Adiciona um comentário;
/ Caractere de escape
@ Estado local;
@+ Espera por um input;
@@ Estado global;
- Adiciona um texto;
= Adiciona um exemplo;
% Exemplo externo;
> Avança para um estado;
! Frase apresentada, caso não haja um entendimento;
? Frase apresentada, caso haja uma desambiguação;
^ Permite ocultar menu (botão);
{{VARIAVEL DE AMBIENTE}} Variáveis de ambiente;
$PIPELINE_INTERCEPTOR: PASTA_DO CLIENTE/NOME_DA_PIPELINE/ Chamada de pipeline;
$HUMAN_ATTENDANCE_INTERCEPTOR:ID_FILA Chamada de fila de atendimento humano;
Paginação
- more_options_label Configura mensagem para ver mais opções;
- max_menu_options Quantidade de menus apresentada por vez;
min_word_size Tamanho mínimo para ser considerado uma palavra;

Estado ou Intenções

Operadores Especiais

Não entendimento (!)

O operador (!), mostrará de forma aleatória uma das frases apresentadas, caso não haja um entendimento.

Desambiguação (?)

Outro operador muito similar ao similar ao anterior, é operador (?), onde este mostrará de forma aleatória uma das frases apresentadas, caso haja uma desambiguação.

Texto (-)

Para adicionar um texto a um fluxo, use o operador (-). Vale lembrar que se o fluxo tiver mais de um operador de texto (-), um abaixo do outro, todos no início da linha. A máquina de estados escolherá de forma aleatória um dos textos.

@start
= um exemplo aleatorio

- Olá, Seja bem-vindo(a)!
Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar?
> end

@end 
# Se seu fluxo tiver mais de um operador de texto ( - ), um abaixo do outro 
como no exemplo. A máquina de estados escolherá de forma aleatória um dos textos.
- Se precisar de ajuda, basta me chamar.
Reduce xyz agradece o contato!
- Reduce xyz está sempre a disposição para ajudar e agradecemos o contato!

~/codes/cetralit/wanderson  on master ?3  wanderson examples/operador    
                                                                                
                                                        
- Olá, Seja bem-vindo(a)!
Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar?

- Reduce xyz está sempre a disposição para ajudar e agradecemos o contato!

start..end 1.000
 ~/codes/cetralit/wanderson  on master ?3  wanderson examples/operador 
                                                                                
                                                       

- Olá, Seja bem-vindo(a)!
Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar?

- Se precisar de ajuda, basta me chamar.
Reduce xyz agradece o contato!

start..end 1.000

Exemplo (=)

O operador de exemplo (=) permite cadastrar exemplos a intenções e entidades para serem analisados e interpretados pela nossa NLU.

Exemplo Externo (%)

O operador de exemplo externo (%), permite cadastrar de forma externa exemplos (=), que podem ser utilizados por mais de uma intenção ou entidade. Através do caractere (&).

Utilizar essa abordagem reduz o número de linhas e facilita a adesão de novos exemplos, após o processo de curadoria.

Exemplos Externos devem ser cadastrados em uma única pasta, todos os arquivos nesta pasta devem conter apenas, este operador.

%chit_chat_saudacao
= Alô
= Boa noite
= Boa tarde
= Bom dia
= Bom dia, prezados
= Hello
= Hi
= Oi
= Olá
= Saudação

@start
# Uso do exemplo externo ( % )
&chit_chat_saudacao
= um exemplo aleatório

- Olá, Seja bem-vindo(a)!
Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar?
> end

@end
 &chit_chat_saudacao
- Se precisar de ajuda, basta me chamar.
Reduce xyz agradece o contato!
- Reduce xyz está sempre a disposição para ajudar e agradecemos o contato!

Variável de ambiente ({{variavel_ambiente}})

Este é um operador que permite acessar variáveis externas de clientes, para incorporar ao nosso fluxo de conversa. O exemplo mais comum é a variável, {{username}} do Citsmart.

Caractere de escape (/)

O caractere de escape permite, anular um operador da máquina de estados que seria interpretado de alguma maneira, para ser usado num texto.

@start 
- {{saudacao_tempo}}
Olá {{user_name}}. Como vai você?
Por favor acesse o perfil \@CentralIT

> end

@end
- Até a próxima!

- Bom dia
Olá user_name. Como vai você?
ePor favor acesse o perfil @CentralIT

- Até a próxima!


start..end 1.000

Intenções Locais (@)

Intenções ou estados locais são estados que só podem ser acessados quando um jump (>) a partir do estado atual os aponta. São categorizados pelo @nome_qualquer: titulo do menu e possuem a seguinte estrutura:

@start
- Olá, Seja bem-vindo(a)!
Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar?
> atendente 
> status

@atendente: Atendente 
= atendente
- Um atendente irá te ajuda
> end

@status: ^ status
= status
- Seu status está OK
> end

@reduce: Reduce
= reduce
- impossivel entrar no reduce, pois nenhum estado, da jump para ele
> end

@end
- acabou

- Olá, Seja bem-vindo(a)!
Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar?
1. map

start..start 1.000 > status
- Seu status está OK

- acabou

filter..end 1.000
 ~/codes/cetralit/wanderson  on master ?3  wanderson examples/operador
                                                                                
                                                       
- Olá, Seja bem-vindo(a)!
Eu sou o assistente virtual da Reduce XYZ. Como posso ajudar?
1. atendente

start..start 1.000 > reduce
- Não compreendi o que você deseja
1. atendente

start..start 0.000 >

Perceba que apesar de a intenção @reduce existir e não estar ocultada, pelo operador (^). Ela não aparece de forma alguma no fluxo conversacional. Isso porque o estado atual não aponta para o reduce.

Aguarde por input (@+)

Aguarde por input, faz com que o próximo jump, só seja executado caso o usuário digite o próximo passo. Perfeito para criar listas passo a passo. Veja o exemplo:

@start 
- oi
> passo1

@+passo1
- passo 1
> passo2

@+passo2: passo 2
- passo 2
> passo3

@passo3: passo 3
- passo 3
> end

@end
- tchau

~/codes/cetralit/wanderson  on master ?3  wanderson examples/operador
                                                                                
                                                        
- oi

- passo 1
1. passo 2

start..passo1 1.000 > 1
- passo 2
1. passo 3

passo2..passo2 1.000 > 1
- passo 3

- tchau

passo3..end 1.000

Intenções Globais ( @@ )

Intenções ou estados globais, como proprio nome sugere, podem ser acessados de qualquer etapada da conversa. São categorizados pelo @@nome_qualquer: titulo do menu e possuem a seguinte estrtura:

@start
- Olá {{username}}! Seja bem-vindo(a)!
Eu sou o assistente virtual do Reduce. Como posso ajudar?

> map 
> filter

#fluxo local 
@map: map 
= map
> end

#fluxo local
@filter: filter
= filter
> end

# fluxo global
@@fluxo_global_oculto: ^ fluxo global oculto
= fluxo global oculto
- todo fluxo global, se não ocultado pelo operador (^). Conforme a cima, 
aparecera nos menus do @start
Este é o caso, do fluxo_global_não_oculto
> end

#fluxo global
@@fluxo_global_nao_oculto: fluxo global nao oculto
= fluxo global não oculto
- todo fluxo global, se não ocultado pelo operador (^). Conforme a cima, 
aparecera nos menus do @start
> end

@end
- acabou

~/codes/cetralit/wanderson  on master ?3  wanderson examples/operador    
                                                                                
                                                        
- Olá username! Seja bem-vindo(a)!
Eu sou o assistente virtual do Reduce. Como posso ajudar?
1. map
2. filter
3. fluxo global nao oculto

start..start 1.000 > fluxo global

start..start 0.683 > 
 ~/codes/cetralit/wanderson  on master ?3  wanderson examples/operador  
                                                                                
                                                       
- Olá username! Seja bem-vindo(a)!
Eu sou o assistente virtual do Reduce. Como posso ajudar?
1. map
2. filter
3. fluxo global nao oculto

start..start 1.000 > 
 ~/codes/cetralit/wanderson  on master ?3  wanderson examples/operador  
                                                                                
                                                       
- Olá username! Seja bem-vindo(a)!
Eu sou o assistente virtual do Reduce. Como posso ajudar?
1. map
2. filter
3. fluxo global nao oculto

start..start 1.000 > fluxo global não oculto

- todo fluxo global, se não ocultado pelo operador (^). Conforme a cima, 
aparecera nos menus do @start

- acabou

fluxo_global_nao_oculto..end 1.000

Vale lembrar que todo fluxo global, se não ocultado pelo operador (^). Conforme a cima, aparecerá nos menus do @start Este é o caso, do fluxo_global_não_oculto

Entidades

Entidades na máquina de estados (*)

O operador que caracteriza uma Entidade (*), seguido de seu nome *nome. Para um melhor uso dessa entidade, você deve pegar exemplos (=) que são muito próximos e cadastrá-los numa mesma entidade. Veja a seguinte estrutura.

Entidades devem ser cadastrados em uma única pasta, todos os arquivos dessa pasta devem conter apenas, este operador. Vale lembrar também, que a ordem das Entidades (*) importa nos exemplos (=).

*veiculo
= carro
= moto
= caminhao

*marca_veiculo
= honda
= bmw
= ford
= fiat

*posse
= meu
= minha

*ipva
= imposto propriedade veículo automotor
= imposto propriedade veículos automotores
= ipva

*vontade
= quero
= preciso
= gostaria de

@start 
- oi
> pagar_ipva
> transferir_carro
> end

@pagar_ipva
= *ipva *posse
- ipva

> end

@transferir_carro
# a ordem das Entidades ( * ) importa nos exemplos ( = )
= *ipva *marca_veiculo
- transferir carro

> end

@end
- tchau

Interceptadores ( $ )

Pipeline

De forma bem resumida e abrangente o conceito de pipeline, representa as etapas do processo pelas quais algo passa até cumprir um objetivo.

Na equipe Gia, se utiliza muito pipelines para acessar api's do Citsmart para abrir chamados, preenchendo formulários via pipeline.

Como usar?

Basta colocar no fluxo que deseja invocar uma pipeline: “$ PIPELINE_INTERCEPTOR: PASTA_DO CLIENTE/NOME_DA_PIPELINE/"

O nome da pasta do cliente bem como nome da pipeline pode ser encontrado no CITBot - Filebrowser

File Browser

@@mapear_pasta_rede: ^ Conceder Acesso/Mapear pasta de rede
= Acesso a pasta de rede
- Entendi que deseja atendimento sobre concessão de acesso/mapeamento de pasta 
de rede. está correto?

> mapear_pasta_rede_sim
> mapear_pasta_rede_nao

@mapear_pasta_rede_sim: ^ Sim
&navigation_sim

# INVOCANDO PIPELINE
$ PIPELINE_INTERCEPTOR: PASTA_DO CLIENTE/NOME_DA_PIPELINE/

> finalizacao_fluxo_padrao

@mapear_pasta_rede_nao: ^ Não
&navigation_nao
> finalizacao_de_fluxo_em_caso_de_entendimento_incorreto

Atendimento Humano

A plataforma Aura permite que o bot, transfira para uma fila de atendimento humano. Bastando colocar no fluxo que deseja invocar um atendimento humano $HUMAN_ATTENDANCE_INTERCEPTOR:ID_FILA.

Para conseguir o ID_FILA, acesse a plataforma aura ou consulte seu manual respectivamente.

Citbot

Citbot Manual

@@atendimento_humano: ^  Atendimento Humano
- Gostaria de falar com um de nossos analistas?
&atendimento_humano
&demanda_nao_resolvida
&nenhuma_das_opcoes
> atendimento_humano_sim
> atendimento_humano_nao

@atendimento_humano_sim: ^ Sim
&navigation_sim

# INVOCANDO ATENDIMENTO HUMANO
$HUMAN_ATTENDANCE_INTERCEPTOR:ID_FILA

> finalizacao_fluxo_padrao

@atendimento_humano_nao: ^ Não
&navigation_nao
> finalizacao_fluxo_padrao

Parametros de configuração

Recomenda-se que os parâmetros citados nesse tópico, sejam passados num arquivo chamado: “01_settings”.

Paginação

Os parâmetros de paginação permitem, mostrar uma quantidade específica de menus na tela. Sendo o more_options_label, a mensagem que permite ver mais opções, max_menu_options, a quantidade de menus apresentada por vez.

# paginated
more_options_label = Ver mais
max_menu_options = 3

@start
? estou em dúvida entre as opções
! não entendi absolutamente nada
- Esses são os parametros de paginação, sendo o more_options_label, a 
mensagem que permite ver mais opções.
O max_menu_options, a quantidade de menus apresentada por vez.
 
> menu
> atendimento
> status
> reclamação
> novo_pedido

@manu: Menu
- Menu
= menu
> start

@atendimento: Atendimento
- Atendimento
= atendimento
> start

@status: Status
- Status
= status
> start

@reclamação: Reclamação
- Reclamação
= reclamacao
> start

@novo_pedido: Novo Pedido
- Novo pedido
= novo
= pedido
> start

@@end: Sair
= tchau
= bye
- tchau

- Esses são os parametros de paginação, sendo o more_options_label, a 
mensagem que permite ver mais opções.
O max_menu_options, a quantidade de menus apresentada por vez.
1. Menu
2. Atendimento
3. Status
4. Sair
5. Ver mais

start..start 1.000 > 5
- Opções:
1. Reclamação
2. Novo Pedido
4. Sair
5. Ver mais

start..start 1.000 > 4
- tchau

end..end 0.000

Tamanho minimo de palavra

Como o próprio nome sugere, o parâmetro min_word_size, especifica o número mínimo de letras, que uma palavra deve ter, para a máquina de estados considerar ela como válida.

Vale lembrar que por padrão o min_word_size é igual a 2, caso queira alterar esse valor, basta passar o parâmetro.

Emojis nos exemplos ( = )

Para passar emoji nos exemplos, min_word_size deve ser igual a 0.

min_word_size = 0

@start 
- Oi. Como você está? 🤔
> triste
> feliz

@triste: Triste
= 😢
- Que pena
> end

@feliz: Feliz
= 🙃
- um dia lindo um bom lugar pra ler um livro
> end

@end
- tchau 🦽

~/codes/cetralit/wanderson  on master !2 ?3  wanderson examples/emoji.pagode    
                                                                                
                                                        
- Oi. Como você está? 🤔
1. Triste
2. Feliz

start..start 1.000 > c
- - um dia lindo um bom lugar pra ler um livro

- tchau 🦽

feliz..end 1.000
 ~/codes/cetralit/wanderson  on master !2 ?3

Rank Options

A máquina de estados trabalha com referência por estado, palavras-chave e número de palavras. Dando uma nota para os inputs, colocados pelo usuário. Como mostra o exemplo do debug export WANDERSON_INFO=TRUE. Os Ranks abaixo permitem mudar isso.

~/codes/cetralit/wanderson  on master !2 ?3  wanderson examples/emoji.pagode    
                                                                                
                                                        
😢 => triste((1.0, 1))
🙃 => feliz((1.0, 1))

Referências por estado: 16
    end ////////////////////////////// 4
  feliz ////////////////////////////// 4
  start ////////////////////////////// 4
 triste ////////////////////////////// 4

Número de palavras chave: 2
 1 ////////////////////////////// 2

Número de estados relacionados a palavra chave: 2
 1 ////////////////////////////// 2

- Oi. Como você está? 🤔
1. Triste
2. Feliz

start..start 1.000 > 🙃
* 🙃
Rank: 1
  feliz ////////////////////////////// 1
 triste  0
- - um dia lindo um bom lugar pra ler um livro

- tchau 🦽

feliz..end 1.000

ignore_below

O valor padrão desse parâmetro fara com que a máquina de estados ignore tudo abaixo de ignore_below = 0.2

is_answer_above

O valor padrão desse parâmetro fara com que a máquina de estados somente considere como correto, tudo que for superior ou igual a is_answer_above = 0.8

parse_at_start

Esse paramtro define, se no @start, o bot vai começar mandando mensagem parse_at_start = false ou se ele vai esperar o usuario digitar parse_at_start = true.