Tais - Assistente Virtual da Cultura

A Taís é uma assistente virtual desenvolvida pelo LAPPIS - Laboratório Avançado de Produção, Pesquisa e Inovação em Software (FGA/UnB), em parceria com o Ministério da Cultura. O nome é uma sigla para Tecnologia de Aprendizado Interativo do Salic.

Esse repositório contém o código do framework do chatbot Tais, composto por:

Bot: Inteligencia artificial do próprio bot, feito em Rasa.
Analytics: Sistema de análise das conversas dos usuários com o chatbot, feito com o Kibana.
Notebooks: Notebooks Jupyter para a análise da estrutura do chatbot.
Web: Página com verificação de usuário para Beta Testers.

O que é a Tais? 🤔 Conheça a Tais
Quero ler a documentação! 📚 Acesse nosso GitHub Pages e veja a nossa wiki
O que é o Lappis? ✏️ Conheça o Lappis
Estou preparado para testar a Tais! 💻 Teste a tais em produção no Portal da Lei Rouanet ou veja ela em produção em nosso github pages
Como posso rodar a Tais no meu computador? ⚙️ Veja e entenda como subir cada parte do ambiente de desenvolvimento da Taís ou simplesmente rode os comandos do QuickStart
Estou com dúvidas... ❓ Veja como conseguir ajuda
Gostaria de Contribuir! 🤗 Veja como contribuir

O que é a Tais?

A Tais é um chatbot desenvolvido pelo LAPPIS junto com a Secretaria Especial da Cultura para o projeto da Lei Rouanet. A Lei Rouanet é o principal mecanismo de fomento a cultura do Brasil, e a Tais tem o objetivo de ajudar os proponentes nos momentos de dúvida. Para saber mais sobre o que é a Lei Rouanet, SALIC e como funciona todo o processo acesse o Portal da Lei Rouanet lá Tais está em produção e também pode explicar esses conceitos.

Entenda a Arquitetura

É utilizado na Tais diversas tecnologias que interagem entre si para obter um melhor resultado. Veja a arquitetura implementada:

O usuário interage com a Tais via RocketChat ou Telegram, que manda as mensagens para o Rasa NLU através de conectores, onde ele identifica a intent, e responde pelo Rasa Core, de acordo com as stories e actions. As models utilizadas para a conversação foram geradas pelo módulo trainer e depois transferidas para o bot, estes modelos podem ser versionados e evoluídos entre bots. Os notebooks avaliam o funcionamento de acordo com o formato das intents e stories. O elasticsearch coleta os dados da conversa e armazena para a análise feita pelo kibana, que gera gráficos para avaliação das conversas dos usuários e da Tais.

Como Rodar a TAIS

Subindo o chatbot

RocketChat

Para testar a Tais utilizando da plataforma do RocketChat, siga os seguintes comandos para subir os containers em seu computador:

sudo docker-compose up -d rocketchat
# aguarde o container subir
sudo docker-compose up bot

Após esses comandos o RocketChat deve estar disponível na porta 3000 do seu computador. Entre em http://localhost:3000 para acessar. Será pedido que faça login. Por padrão é gerado um usuário admin: username: admin senha: admin

Instalação

Para colocar a Tais em um site você precisa inserir o seguinte código em Javascript na sua página:

<!-- Start of Rocket.Chat Livechat Script -->
<script type="text/javascript">
(function(w, d, s, u) {

    // !!! Mudar para o seu host AQUI !!!
    host = 'http://localhost:3000';
    // !!! ^^^^^^^^^^^^^^^^^^^^^^^^^^ !!!

    w.RocketChat = function(c) { w.RocketChat._.push(c) }; w.RocketChat._ = []; w.RocketChat.url = u;
    var h = d.getElementsByTagName(s)[0], j = d.createElement(s);
    j.async = true; j.src = host + '/packages/rocketchat_livechat/assets/rocketchat-livechat.min.js?_=201702160944';
    h.parentNode.insertBefore(j, h);
})(window, document, 'script', host + '/livechat');
</script>
<!-- End of Rocket.Chat Livechat Script -->

Atenção: Você precisa alterar a variável host dentro do código acima para a url do site onde estará o seu RocketChat.

Console

Para testar somente o diálogo com o bot, não é necessário rodar o RocketChat. Caso queira apenas rodar a Tais pelo seu terminal, rode os seguintes comandos:

sudo docker-compose run --rm bot make run-console

Essa forma de rodar trás também os logs e previsão de intents do Rasa.

Treinamento

Caso precise atualizar os dialogos com o bot após modificações nas intents e stories (coach/data/intents e stories), utilize o seguinte comando na pasta raiz do projeto para treinar o bot novamente:

make train

Caso queira atualizar o treinamento padrão da aplicação, será necessário atualizar a versão da imagem Coach no dockerhub do lappis:

make train
sudo docker push lappis/coach:latest

Site do Beta

Nesse repositório temos também o site para beta testers da Tais. Ele se conecta com a Tais via RocketChat, então para ela estar hospedada é necessário subir o RocketChat.

Setup

Antes de rodá-lo é necessário fazer algumas configurações e criar um usuário. Para isso rode os comandos abaixo e crie o seu usuário.

sudo docker-compose run --rm web python manage.py migrate
sudo docker-compose run --rm web python manage.py createsuperuser

Execução

Para rodar o site em localhost suba o container com esse comando:

sudo docker-compose up -d web

Você pode acessar o site por padrão na url http://localhost:8000. Será necessário fazer o login, com o usuário criado, esse usuário é um super usuário, então ele tem acesso a parte admin, que poderá ser acessada em http://localhost:8000/admin/ e poderá criar novos usuários.

Dashboards Visualização

Dashboards que disponibilizamos para a Secretaria Especial da Cultura.

Setup

sudo docker-compose run --rm kibana-web python manage.py migrate
sudo docker-compose run --rm kibana-web python manage.py createsuperuser

Execução

sudo docker-compose up -d kibana-web

Você pode acessar o site por padrão na url localhost:8080

Analytics

Para a análise dos dados das conversas com o usuário, utilize o kibana, e veja como os usuários estão interagindo com o bot, os principais assuntos, média de usuários e outras informações da análise de dados. As mensagens são inseridas no cluster do Elastic Search utilizando o broker RabbitMQ.

Setup

Setup ElasticSearch

Para subir o ambiente do ElasticSearch rode os seguintes comandos:

sudo docker-compose up -d elasticsearch
sudo docker-compose run --rm -v $PWD/analytics:/analytics bot python /analytics/setup_elastic.py

Para habilitar o backup rode o seguinte comando:

sudo docker exec -it tais_elasticsearch_1 curl -XPUT -H "Content-Type: application/json;charset=UTF-8" 'http://localhost:9200/_snapshot/backup' -d '{
  "type": "fs",
  "settings": {
     "location": "/elasticseacrh/backup",
     "compress": true
  }
}'

# A resposta esperada é: {"acknowledged": true}

Setup RabbitMQ

Inicie o serviço do servidor do RabbitMQ:

sudo docker-compose up -d rabbitmq

Inicie o serviço do consumidor do RabbitMQ, que ficará responsável por enviar as mensagens para o ElasticSearch:

sudo docker-compose up -d rabbitmq-consumer

Lembre-se de configurar as seguintes variáveis de ambiente do serviço rabbitmq-consumer no docker-compose.

ENVIRONMENT_NAME=localhost
BOT_VERSION=last-commit-hash
RABBITMQ_DEFAULT_USER=admin
RABBITMQ_DEFAULT_PASS=admin

Sendo que as configurações de RABBITMQ_DEFAULT_USER e RABBITMQ_DEFAULT_PASS devem ser as mesmas definidas no serviço do rabbitmq.

Visualização

Para visualização do site rode o comando:

sudo docker-compose up -d kibana

Para acesso do site é necessário fazer o login. Por padrão o usuário criado é admin e a senha é admin

Você pode acessar o kibana no http://locahost:5601

Para visualização dos Dashboards básico

Visualizações de métricas importantes para o desenvolvimento de chatbots, estão disponibilizados para este contexto. Para usar estes templates execute os seguintes passos:

Suba o container do Kibana e acesse http://locahost:5601;
Na interface, acesse Management e clique em Saved Objects;
Clique em Import;
Utilize o arquivo export.json na pasta elasticsearch/ do projeto.

Execução

Existem duas formas para executar a Tais com o broker. A primeira delas é via linha de comando. Para utilizar esta forma é preciso definir Dentro do arquivo endpoints.yml as configurações do broker:

event_broker:
  url: rabbitmq
  username: admin
  password: admin
  queue: bot_messages

Depois basta executar o bot:

sudo docker-compose run --rm bot make run-console-broker

A segunda forma é utilizando o script run-rocketchat que é utilizado quando o bot é executado com o RocketChat como canal. Para isso, as mesmas variáveis devem ser configuradas no arquivo docker/bot/bot.env. Lembre-se também de configurar como True a seguinte variável do serviço bot no docker-compose.

# Analytics config
ENABLE_ANALYTICS=True

# Broker config
BROKER_URL=rabbitmq
BROKER_USERNAME=admin
BROKER_PASSWORD=admin
QUEUE_NAME=bot_messages

Dashboards Visualização do Kibana

Dashboards mais básicos do Analytics, sem permissão de admin, que disponibilizamos para a Secretaria Especial da Cultura.

Setup

Rode as configurações:

sudo docker-compose run --rm kibana-web python manage.py migrate
sudo docker-compose run --rm kibana-web python manage.py createsuperuser

Execução

Para visualização do site, rode o comando:

sudo docker-compose up -d kibana-web

Você pode acessar o site por padrão na url http://localhost:8080

Notebooks - Análise de dados

Para análise de como estão as intents e stories construidas, se está havendo alguma confusão por intents similares ou outros problemas, utilize os notebooks para gerar os gráficos de matriz de confusão e diagrama da estrutura das stories.

Setup

Levante o container notebooks

docker-compose up -d notebooks

Acesse o notebook em http://localhost:8888. Lá entre na pasta notebooks e vá para a pasta intents ou stories, dependendo do que quer analisar, e abra o arquivo .ipynb.

Testando Fluxos de Conversa

É possível testar os fluxos de conversação utilizando o Evaluation do Rasa Core. Para testá-los na Tais basta adicionar um arquivo dentro do diretório bot/e2e/ com as histórias a serem testadas. Essas histórias devem ser descritas normalmente, porém com exemplos de frases para cada uma das Intents sendo testadas, segundo o formato abaixo:

## História de teste 1
* definicao_tais: quem é a tais?
    - utter_definicao_tais
    - utter_objetivo
* afirmar: sim
    - utter_processo_como_funciona
* afirmar: sim
   - utter_cadastro_salic_video
   - utter_cadastro_salic_video
* afirmar: quero
    - utter_salic_cadastro_usuario
    - utter_continuar_conversa
* negar: não senhora
    - utter_despedir

Uma vez que os arquivos de teste foram adicionados ao diretório correto, basta rodar os testes com a task da TAIS:

sudo docker-compose run --rm bot make test-stories

QuickStart

A Tais, no ambiente de produção, consiste no Rasa, RocketChat, página para Beta Testers e o Kibana. Para levantar todo esse ambiente, use os seguintes comandos:

sudo docker-compose up -d rocketchat

sudo docker-compose run --rm web python manage.py migrate
sudo docker-compose run --rm web python manage.py createsuperuser
sudo docker-compose up -d web

sudo docker-compose up -d kibana
sudo docker-compose run --rm -v $PWD/analytics:/analytics bot python /analytics/setup_elastic.py

# aguarde os containers serem levantados
sudo docker-compose up -d bot

Documentação

A documentação feita está no github pages, veja no link: lappis-unb.github.io/tais A documentação se encontra na pasta docs deste repositório. É feita com Jekyll para o github pages. Para rodar a página em seu computador basta rodar o comando:

jekyll serve

Ou rode com docker (atualmente nem sempre funciona o mapeamento de porta - issue #441):

docker-compose up

Acesse a pagina em http://localhost:4000.

Passos necessários para gerar uma nova release

A criação de uma nova versão Release é bem simples. Os seguintes passos são necessários para lançar uma nova versão

edite o CHANGELOG.rst, crie uma nova seção para a release e crie uma nova master loggins section
Edite o guia de migração para dar assistência para usuários atualizarem para a nova versão
Commite todas as mudanças acima e gere uma tag para a nova versão usando

git tag -f 0.7.0 -m "Some helpful line describing the release"
git push origin 0.7.0

Tecnologias do Projeto:

Rasa - Inteligência Artificial do Bot
RocketChat - Mensageiro de comunicação do Bot
Django - Site para beta testers
Jupyter Notebook - Notebooks para análise da estrutura de intents e stories
Elasticsearch - Para coleta de dados para análise
Kibana - Análise dos dados coletados a partir das conversas
Docker - Os ambientes são todos dockerizados

Como Contribuir

Ficaremos muito felizes de receber e incorporar suas contribuições. Tem algumas informações adicionais sobre o estilo do código e a documentação.

Em geral o processo é bem simples:

Crie uma issue descrevendo uma feature que você queira trabalhar (ou olhe as issues com o label help-wanted e good-first-issue)
Escreva seu código, testes e documentação
Abra um pull request descrevendo as suas alterações propostas
Seu pull request será revisado por um dos mantenedores, que pode levantar questões para você sobre eventuais mudanças necessárias ou questões.

Leia o Guia de Contribuição para melhores informações.

Como conseguir ajuda

Parte da documentação técnica do framework da Tais está disponível na wiki do repositório. Caso não encontre sua resposta, abra uma issue com a tag duvida que tentaremos responder o mais rápido possível.

Em caso de dúvidas em relação ao Rasa, veja o grupo Telegram Rasa Stack Brasil, estamos lá também para ajudar.

Veja mais informações de contato em nosso site: https://lappis.rocks

Licença

Todo o framework da Tais é desenvolvido sob a licença GPL3

Veja a lista de dependências de licenças aqui

felippe-regazio/tais

Tais - Assistente Virtual da Cultura

O que é a Tais?

Entenda a Arquitetura

Como Rodar a TAIS

Subindo o chatbot

RocketChat

Instalação

Console

Treinamento

Site do Beta

Setup

Execução

Dashboards Visualização

Setup

Execução

Analytics

Setup

Setup ElasticSearch

Setup RabbitMQ

Visualização

Para visualização dos Dashboards básico

Execução

Dashboards Visualização do Kibana

Setup

Execução

Notebooks - Análise de dados

Setup

Testando Fluxos de Conversa

QuickStart

Documentação

Passos necessários para gerar uma nova release

Tecnologias do Projeto:

Como Contribuir

Como conseguir ajuda

Licença