chatbot-flow 0.1.0

Biblioteca para controle de fluxos de conversa em chatbots

Documentação do Módulo ChatbotFlow

Visão Geral

ChatbotFlow é uma biblioteca Python para gerenciar fluxos de conversas em chatbots. A biblioteca permite definir fluxos de conversa usando estruturas JSON, facilitando a criação de chatbots com comportamentos complexos sem a necessidade de programação avançada.

Recursos Principais

• Definição de fluxos de conversa baseados em JSON
• Sistema de estados e transições para controlar o diálogo
• Suporte a padrões regex para identificar intenções do usuário
• Hooks para personalizar o comportamento do chatbot
• Gerenciamento de contexto para conversas com estado
• Suporte a ações e botões para interfaces ricas

Instalação

pip install chatbot-flow

Ou para instalar a partir do código fonte:

git clone https://github.com/seuusuario/chatbot-flow.git
cd chatbot-flow
pip install -e .

Uso Básico

from chatbot_flow import Chatbot
from chatbot_flow.utils import load_flow_from_file

# Carregar fluxo de um arquivo JSON
flow = load_flow_from_file("meu_fluxo.json")

# Criar um chatbot
bot = Chatbot(flow)

# Processar uma mensagem do usuário
resposta = bot.process_message("Olá, como vai?")

# Exibir a resposta
print(resposta["text"])

Estrutura do Fluxo JSON

Um fluxo é definido como um objeto JSON com a seguinte estrutura:

{
  "name": "Nome do Fluxo",
  "version": "1.0",
  "states": {
    "state1": {
      "responses": ["Resposta 1", "Resposta 2"],
      "transitions": [
        {
          "condition": {
            "pattern": "regex_pattern"
          },
          "target": "state2"
        }
      ]
    },
    "state2": {
      "responses": ["Outra resposta"]
    }
  },
  "intents": {
    "saudacao": ["olá", "oi", "bom dia"]
  }
}

Elementos Principais

• states: Define os estados possíveis do chatbot
• responses: Lista de possíveis respostas para um estado
• transitions: Regras para mudança de estado
• condition: Condições para acionar uma transição
• target: Estado de destino para a transição
• intents: Agrupamento de palavras-chave por intenção

Classes Principais

Chatbot

A classe principal que gerencia o fluxo de conversa.

bot = Chatbot(flow_definition, initial_state="start")

Métodos

• process_message(message): Processa uma mensagem do usuário e retorna uma resposta
• reset(initial_state="start"): Reinicia o chatbot para o estado inicial
• save_state(): Salva o estado atual do chatbot
• load_state(state_data): Carrega um estado previamente salvo
• register_hook(event_name, callback): Registra um hook para eventos específicos

FlowManager

Gerencia o fluxo de conversa com base na definição JSON.

flow_manager = FlowManager(flow_definition)

Métodos

• state_exists(state_name): Verifica se um estado existe no fluxo
• determine_transition(current_state, message, context): Determina a próxima transição
• register_hook(event_name, callback): Registra um hook para eventos específicos

Utilitários

load_flow_from_file(file_path)

Carrega um fluxo de conversa a partir de um arquivo JSON.

save_flow_to_file(flow, file_path)

Salva um fluxo de conversa em um arquivo JSON.

create_simple_flow(welcome_message, fallback_message, goodbye_message)

Cria um fluxo simples com estados básicos.

Exemplo de Fluxo Completo

Veja um exemplo de fluxo para um bot de atendimento de pedidos:

{
  "name": "Atendimento de Pedidos",
  "version": "1.0",
  "states": {
    "start": {
      "responses": [
        "Olá! Bem-vindo ao nosso atendimento. Como posso ajudar você hoje?"
      ],
      "transitions": [
        {
          "condition": {
            "pattern": "\\b(fazer|realizar|quero)\\s+(um\\s+)?pedido\\b"
          },
          "target": "new_order"
        },
        {
          "condition": {
            "pattern": "\\b(status|andamento|situação)\\s+(do\\s+)?pedido\\b"
          },
          "target": "check_order"
        }
      ]
    },
    "new_order": {
      "responses": [
        "Claro! Vamos fazer seu pedido. Qual produto você deseja?"
      ],
      "transitions": [
        {
          "target": "order_product"
        }
      ]
    },
    "order_product": {
      "responses": [
        "Ótima escolha! Qual a quantidade desejada?"
      ],
      "transitions": [
        {
          "target": "order_quantity"
        }
      ]
    }
  }
}

Hooks e Personalização

É possível personalizar o comportamento do chatbot usando hooks:

def before_transition_hook(current_state, message, context):
    print(f"Transitando do estado {current_state} com a mensagem: {message}")

bot.register_hook("before_transition", before_transition_hook)

Hooks disponíveis:

• before_transition: Chamado antes de uma transição
• after_transition: Chamado depois de uma transição
• on_error: Chamado quando ocorre um erro

Casos de Uso

• Chatbots de atendimento ao cliente
• Assistentes virtuais
• Bots para coleta de informações
• Sistemas de FAQ interativos
• Chatbots para redes sociais e messengers

Limitações Atuais

• Não possui integração nativa com processamento de linguagem natural (NLP)
• Suporte limitado a contexto em conversas longas
• Sem memória de longo prazo para o usuário

Contribuição

Contribuições são bem-vindas! Por favor, sinta-se à vontade para enviar pull requests.

Licença

Este projeto está licenciado sob a licença MIT - veja o arquivo LICENSE para detalhes.