{"id":19988206,"url":"https://github.com/gabrielogregorio/tereza","last_synced_at":"2026-06-13T14:07:15.529Z","repository":{"id":103715306,"uuid":"368684803","full_name":"gabrielogregorio/tereza","owner":"gabrielogregorio","description":"🤖 Chatbot experimental baseado em extensões, projeto desenvolvido para o trabalho de graduação (TG) na Fatec Araçatuba.","archived":false,"fork":false,"pushed_at":"2021-07-08T21:04:29.000Z","size":803,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-01T21:25:54.528Z","etag":null,"topics":["python","telegram"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gabrielogregorio.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2021-05-18T22:48:16.000Z","updated_at":"2023-10-31T00:37:56.000Z","dependencies_parsed_at":"2023-06-26T01:46:45.409Z","dependency_job_id":null,"html_url":"https://github.com/gabrielogregorio/tereza","commit_stats":null,"previous_names":["ogregorio0/tereza","gabrielogregorio/tereza"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gabrielogregorio/tereza","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielogregorio%2Ftereza","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielogregorio%2Ftereza/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielogregorio%2Ftereza/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielogregorio%2Ftereza/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gabrielogregorio","download_url":"https://codeload.github.com/gabrielogregorio/tereza/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrielogregorio%2Ftereza/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34287105,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python","telegram"],"created_at":"2024-11-13T04:41:57.299Z","updated_at":"2026-06-13T14:07:15.524Z","avatar_url":"https://github.com/gabrielogregorio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tereza Chatbot Experimental   \n\u003e Documentação em desenvolvimento   \n\n![images](images/interacao.png)   \nO chatbot tereza é um sistema desenvolvido usando a linguagem Python, o conceito dele é permitir que as interações sejam montadas de acordo com um conceito chamado de extensões. As extensões neste projeto são arquivos próprios e independentes que podem usar de todos os recursos da linguagem Python.\n\nCada extensão precisa seguir uma padronização para que o sistema a reconheça como legitima. Após esse reconhecimento, uma classe será instanciada e inicializada de cada extensão.\n\nAs extensões precisam fornecer informações que serão explicadas mais adiante. Basicamente as informações se referem a perguntas que uma extensão consegue responder. Exemplificando, podemos ter uma extensão que responde o horário da aula, para isso, será criado os arquivos da extensão seguindo um padrão e a extensão deverá fornecer quais perguntas ela pode responder.\n\nQuando o usuário realizar uma pergunta, o sistema irá verificar quais extensões tem o potencial de fornecer uma resposta e irá encaminhar o usuário para interagir com uma extensão que possa ajuda-lo. Novamente reforçando, a extensão tem acesso total a linguagem python e pode realizar as ações que precisar para fornecer uma resposta ao usuário.\n\n## Configurando o ambiente pela primeira vez\n\nA primeira vez que você for usar o chatbot, precisará realizar as seguintes configurações:\n\n1. Instalar o [python 3.7](https://www.python.org/downloads/release/python-377/) \n2. Crie um ambiente virtual\n```shell\npython -m venv ambiente\n```   \n3. Ativar o ambiente virtual\n```shell\n# Linux\n.\\ambiente\\Scripts\\activate source\n\n# Windows\n.\\ambiente\\Scripts\\activate\n```    \n4. Instalar os requisitos do chatbot\n```shell\npython -m pip install -r .\\\\requirements.txt\n```     \n5. Use o comando abaixo para substituir um arquivo do telegram que causa instabilidade após ~15 minutos sem interação\n```shell\ncp .\\arquivos\\request.py .\\ambiente\\Lib\\site-packages\\telegram\\utils\\\n```\n6. Crie um arquivo .env na raiz do projeto e informe o token do chatbot. É importante você criar um bot no telegram, entre em contato com o https://telegram.me/BotFather\n```env\nTELEGRAM_TOKEN=\nNAME_DATABASE=REGISTROS.db\nNAME_TABLE=REGISTROS_TEREZA\n```\n7. Execute o bot sempre dentro do ambiente virtual\n\n```sheel\npython bot.py\n```\n\n## Primeira interação de um usuário\nA primeira vez que alguém enviar uma mensagem ao bot, o sistema irá redirecionar para uma extensão que cuida exclusivamente de registrar o usuário em um arquivo .json\n\n\n## Criando uma extensão\nAs extensões são um conjunto de dois arquivos que ficam dentro da seguinte estrutura de pastas que você pode personalizar:\n```text\nextensoes/NOME_ESCOLA/NOME_CURSO/NOME_DISCIPLINA/TEMA_EXTENSAO/config.json\nextensoes/NOME_ESCOLA/NOME_CURSO/NOME_DISCIPLINA/TEMA_EXTENSAO/extensao.py\n\n```\n### Arquivo de configuração\nO arquivo config.json precisa ter a seguinte estrutura:\n```json\n{\n    \"configuracoes\":{\n        \"precisao\":80,\n        \"timeout\":\"00:05:00\",\n        \"tentativas\":3,\n        \"mensagens_tentativas\":[\n            \"Mensagem quando esgotar o limite de tentativas\"\n        ]\n    },\n    \"variaveis\":{\n        \"cep\":\"(\\\\d{8})\",\n        \"cursos\":[\n            \"/analiseDesenvolvimentoDeSistemas\",\n            \"/biocombustiveis\"\n        ]\n    },\n    \"principal\":[\n        \"/escolher_curso\",\n        \"Eu quero fazer um curso ai\"\n    ],\n    \"perguntar_qual_curso\":[\n        \"Qual curso você quer fazer? $.cursos\"\n    ],\n    \"obter_curso_escolido\":[\n        \"$cursos\"\n    ],\n    \"finalizar_interacao\":[\n        \"Ok, muito obrigado, vou te registrar no curso $cursos\"\n    ]\n}\n```\n\nSendo a seguinte relação para cada chave:\n| Chave | Descrição |\n|----------|--------------|\n| variáveis | Objeto json que será explicado melhor abaixo |\n| principal | Lista de questões que a extensão sabe responder |\n| finalizar_interacao | Resposta genérica que sinaliza o fim da interação de uma extensão com o usuário |\n| precisao | Semelhança da frase dita pelo usuário com a as frases da chave de uma interação, varia de 0 a 100 |\n| timeout | String de tempo que especifica o tempo que a extensão será desconectada caso fique sem interagir com o usuário |\n| tentativas | Valor inteiro, sendo o número de tentativas que a extensão pode fazer caso o usuário fique forçando uma entrada inesperada pela extensão |\n| mensagens_tentativas |Mensagem caso o usuário force uma entrada inesperada por um valor maior que o chave tentativas |\n\n#### Variáveis\n\nAs variáveis podem ser usadas para capturar valores que respeitam um padrão (Exemplo uma expressão regular de CPF) ou valores de escolha, como uma lista de cursos.\n\nAs variáveis são inseridas nas chaves de interação com o usuário, isto é, nas chaves “finalizar interação”, “principal” e nas intermediárias. As variáveis servem para capturar padrões ou valores dito pelo usuário, servindo também para retornar opções ao usuário.\n\nVariáveis devem ser declaradas na chave “variáveis” e sendo chamadas nas chaves de interação através do “$”, exemplo “$nome”.\n\nVariáveis podem ser uma expressão regular, exemplo para capturar o cep quando o usuário digitar algo próximo de “meu cep é 10912900”, podemos ter uma chave que espera a seguinte entrada “o cep meu é $cep”. Variável também podem ser uma lista, conforme o exemplo \"Qual curso você quer fazer? $.cursos\".\n\n\n#### Formas de chamar uma variável\n\n| forma | Contexto | Efeito |\n|---------|---------|---------|\n| $variavel | Retornar uma resposta ao usuário | Retorna o valor obtido da variável |\n| $variavel | Esperar uma resposta do usuário | Faz o sistema interpretar que a extensão precisa coletar algo no padrão da variável |\n| $.variavel | Retornar uma resposta ao usuário | Exibe os valores que a variável pode assumir, se for uma lista retorna uma lista no padrão Telegram |\n\nExemplo do uso do recurso na prática:  \n\n![images](images/interacao2.png)   \n\n### Arquivo da extensão \nO arquivo da extensão se trata do “extensao.py”, ele precisa ter a seguinte estrutura:\n```python\nfrom random import choice\nimport re\nfrom src.Extensao import Extensao\n\nclass main(Extensao):\n    def __init__(self, dict_extensao):\n        Extensao.__init__(self, dict_extensao)\n\n    def entrada(self, dados:dict, prox_ponto_referencia:str, chat_id) -\u003e dict:\n        self.carregar_variaveis(dados, chat_id)\n    \n        if prox_ponto_referencia == \"principal\": # Principal\n            resposta = choice(dados['config'][\"finalizar_interacao\"]) # Pergunta\n            return self.responder(resposta=resposta, chat_id=chat_id, prox_ponto_referencia=\"\", liberar=True) # Esperar Resposta\n```\nEste é o código mínimo de uma extensão Python, todos esses parâmetros demonstrados são obrigatórios, porém, você pode adicionar quantas classes e objetos desejar a mais na sua extensão. A extensão pode consultar APIS, banco de dados e todos os recursos da linguagem Python.\nA função “self.responder” precisa ser usadas para retornar algo ao usuário e ela precisa ter as seguintes chaves:\n\n| Parametro | Descricao |\n|-------|---------|\n| Resposta | Uma resposta ao usuário, pode ou não ser do arquivo config.json |\n| Chat_id | Identificador do usuário no Telegram |\n| prox_ponto_referencia | Nome da chave no arquivo “config.json” que o chatbot espera que a entrada do usuário seja similar. |\n| liberar | Se verdadeiro, sinaliza ao sistema para desconectar o usuário da extensão |\n\n\n## Linguagem natural\nO entendimento de linguagem natural acontece através de uma série de etapas em combinação com a biblioteca [Pyanalise]( https://github.com/gabrielogregorio/Pyanalise). O processamento de linguagem natural possui duas etapas macros. A primeira etapa se baseia nos seguintes passos:\n1. Através da biblioteca Unicode os acentos das frases são removidos.\n2. Alguns caracteres especiais como “?” e “!” são substituídos por espaços.\n3. Espaços múltiplos serão removidos de ambas as frases\n4. Todas as palavras serão transformadas em minúsculas\n5. Palavras sinônimos serão transformadas para uma mesma palavra\n6. Ambas as frases serão analisadas letra a letra e será retornado uma semelhança de 0 a 100%\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabrielogregorio%2Ftereza","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgabrielogregorio%2Ftereza","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabrielogregorio%2Ftereza/lists"}