chatgraph 0.1.1__tar.gz

chatgraph-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Irisson Lima
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chatgraph-0.1.1/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.1
+Name: chatgraph
+Version: 0.1.1
+Summary: A user-friendly chatbot library
+Home-page: https://github.com/irissonnlima/chatgraph
+License: MIT
+Keywords: chatbot,rabbitmq,messaging,routing,chatgraph,python
+Author: Irisson N. Lima
+Author-email: irisson.lima@verdecard.com.br
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: pika (>=1.3.2,<2.0.0)
+Project-URL: Repository, https://github.com/irissonnlima/chatgraph
+Description-Content-Type: text/markdown
+
+# ChatGraph
+
+**ChatGraph** é uma biblioteca Python projetada para facilitar a construção e gerenciamento de chatbots com roteamento flexível. 
+
+Ela oferece uma estrutura para definir rotas de chatbot, processar mensagens e gerenciar o estado do usuário de maneira eficiente.
+
+## Instalação
+
+Você pode instalar o ChatGraph diretamente do PyPI:
+
+```bash
+pip install chatgraph
+```
+
+Link do PyPI: [ChatGraph no PyPI](https://pypi.org/project/chatgraph/)
+
+## Estrutura da Biblioteca
+
+### 1. `ChatbotApp`
+
+A classe `ChatbotApp` é o núcleo da aplicação do chatbot. Ela gerencia as rotas definidas, processa as mensagens recebidas e lida com a lógica de navegação dentro do chatbot.
+
+- **Métodos principais:**
+  - `include_router`: Inclui um conjunto de rotas (definido por `ChatbotRouter`) na aplicação.
+  - `route`: Decorador para associar funções a rotas específicas.
+  - `start`: Inicia o consumo de mensagens do RabbitMQ.
+  - `process_message`: Processa a mensagem recebida e executa a função correspondente à rota atual do usuário.
+
+### 2. `ChatbotRouter`
+
+A classe `ChatbotRouter` permite definir e agrupar rotas que podem ser facilmente incluídas na aplicação principal do chatbot.
+
+- **Métodos principais:**
+  - `route`: Decorador para adicionar uma função como uma rota no roteador.
+  - `include_router`: Inclui outro roteador dentro do roteador atual, permitindo a construção modular das rotas.
+
+### 3. `MessageConsumer` e `RabbitMessageConsumer`
+
+A classe abstrata `MessageConsumer` define a interface para consumidores de mensagens no sistema do chatbot. A implementação concreta `RabbitMessageConsumer` consome mensagens de uma fila RabbitMQ, processa essas mensagens e envia respostas de acordo.
+
+- **Métodos principais:**
+  - `start_consume`: Inicia o consumo de mensagens do RabbitMQ.
+  - `on_request`: Processa uma mensagem recebida e envia a resposta correspondente.
+  - `load_dotenv`: Carrega as configurações do RabbitMQ a partir de variáveis de ambiente.
+
+### 4. `UserState` e `SimpleUserState`
+
+A classe abstrata `UserState` define a interface para o gerenciamento do estado do usuário. A implementação `SimpleUserState` usa um dicionário em memória para armazenar o estado atual do menu para cada usuário.
+
+- **Métodos principais:**
+  - `get_menu`: Retorna o menu atual associado a um ID de cliente.
+  - `set_menu`: Define o menu atual para um ID de cliente.
+
+### 5. `Message`
+
+A classe `Message` encapsula os dados de uma mensagem enviada ou recebida pelo chatbot.
+
+- **Atributos:**
+  - `type`: Tipo da mensagem (ex. texto, imagem).
+  - `text`: Conteúdo da mensagem.
+  - `customer_id`: ID do cliente que enviou ou recebeu a mensagem.
+  - `channel`: Canal de comunicação utilizado (ex. WhatsApp, SMS).
+  - `customer_phone`: Número de telefone do cliente.
+  - `company_phone`: Número de telefone da empresa.
+  - `status`: Status da mensagem (opcional).
+
+### 6. `ChatbotResponse` e `RedirectResponse`
+
+Essas classes são usadas para definir a resposta do chatbot após o processamento de uma mensagem.
+
+- **`ChatbotResponse`**: Contém uma mensagem de resposta e uma rota opcional.
+- **`RedirectResponse`**: Define uma rota para a qual o chatbot deve redirecionar o fluxo.
+
+### 7. `Route` e `RouteError`
+
+A classe `Route` gerencia a navegação entre diferentes partes do fluxo do chatbot, permitindo obter a rota anterior e calcular a próxima rota com base na entrada do usuário.
+
+- **Métodos principais:**
+  - `get_previous`: Retorna o caminho anterior ao atual.
+  - `get_next`: Monta e retorna o próximo caminho com base em uma parte fornecida.
+
+A classe `RouteError` é uma exceção personalizada usada para indicar problemas relacionados à navegação nas rotas.
+
+## Exemplo de Uso
+
+Aqui está um exemplo básico de como configurar e utilizar o ChatGraph:
+
+```python
+from chatgraph import ChatbotApp, ChatbotRouter, SimpleUserState, RabbitMessageConsumer, ChatbotResponse
+
+# Definindo rotas com ChatbotRouter
+router = ChatbotRouter()
+
+@router.route("START")
+def say_hello():
+    return ChatbotResponse(message="Hello! How can I assist you today?", route="HELP")
+
+@router.route("/HELP")
+def provide_help():
+    return ChatbotResponse(message="Here are some things I can help with: ...")
+
+# Configurando a aplicação do chatbot
+user_state = SimpleUserState()
+message_consumer = RabbitMessageConsumer.load_dotenv()
+
+app = ChatbotApp(user_state=user_state, message_consumer=message_consumer)
+app.include_router(router, prefix="")
+
+# Iniciando o chatbot
+app.start()
+```
+
+Neste exemplo, o chatbot responde "Hello! How can I assist you today?" quando a rota `HELLO` é acessada e depois direciona o usuário para a rota `HELP`.
+
+## Contribuição
+
+Se você encontrar bugs ou tiver sugestões de melhorias, sinta-se à vontade para abrir uma issue ou enviar um pull request no repositório do projeto.
+
+## Licença
+
+Este projeto está licenciado sob a licença MIT. Consulte o arquivo LICENSE para obter mais detalhes.
+
+---
+
+Com **ChatGraph**, você tem a flexibilidade e a simplicidade necessárias para construir chatbots poderosos e altamente configuráveis, integrados, por enquanto, com RabbitMQ para um processamento robusto de mensagens.

chatgraph-0.1.1/README.md

@@ -0,0 +1,125 @@
+# ChatGraph
+
+**ChatGraph** é uma biblioteca Python projetada para facilitar a construção e gerenciamento de chatbots com roteamento flexível. 
+
+Ela oferece uma estrutura para definir rotas de chatbot, processar mensagens e gerenciar o estado do usuário de maneira eficiente.
+
+## Instalação
+
+Você pode instalar o ChatGraph diretamente do PyPI:
+
+```bash
+pip install chatgraph
+```
+
+Link do PyPI: [ChatGraph no PyPI](https://pypi.org/project/chatgraph/)
+
+## Estrutura da Biblioteca
+
+### 1. `ChatbotApp`
+
+A classe `ChatbotApp` é o núcleo da aplicação do chatbot. Ela gerencia as rotas definidas, processa as mensagens recebidas e lida com a lógica de navegação dentro do chatbot.
+
+- **Métodos principais:**
+  - `include_router`: Inclui um conjunto de rotas (definido por `ChatbotRouter`) na aplicação.
+  - `route`: Decorador para associar funções a rotas específicas.
+  - `start`: Inicia o consumo de mensagens do RabbitMQ.
+  - `process_message`: Processa a mensagem recebida e executa a função correspondente à rota atual do usuário.
+
+### 2. `ChatbotRouter`
+
+A classe `ChatbotRouter` permite definir e agrupar rotas que podem ser facilmente incluídas na aplicação principal do chatbot.
+
+- **Métodos principais:**
+  - `route`: Decorador para adicionar uma função como uma rota no roteador.
+  - `include_router`: Inclui outro roteador dentro do roteador atual, permitindo a construção modular das rotas.
+
+### 3. `MessageConsumer` e `RabbitMessageConsumer`
+
+A classe abstrata `MessageConsumer` define a interface para consumidores de mensagens no sistema do chatbot. A implementação concreta `RabbitMessageConsumer` consome mensagens de uma fila RabbitMQ, processa essas mensagens e envia respostas de acordo.
+
+- **Métodos principais:**
+  - `start_consume`: Inicia o consumo de mensagens do RabbitMQ.
+  - `on_request`: Processa uma mensagem recebida e envia a resposta correspondente.
+  - `load_dotenv`: Carrega as configurações do RabbitMQ a partir de variáveis de ambiente.
+
+### 4. `UserState` e `SimpleUserState`
+
+A classe abstrata `UserState` define a interface para o gerenciamento do estado do usuário. A implementação `SimpleUserState` usa um dicionário em memória para armazenar o estado atual do menu para cada usuário.
+
+- **Métodos principais:**
+  - `get_menu`: Retorna o menu atual associado a um ID de cliente.
+  - `set_menu`: Define o menu atual para um ID de cliente.
+
+### 5. `Message`
+
+A classe `Message` encapsula os dados de uma mensagem enviada ou recebida pelo chatbot.
+
+- **Atributos:**
+  - `type`: Tipo da mensagem (ex. texto, imagem).
+  - `text`: Conteúdo da mensagem.
+  - `customer_id`: ID do cliente que enviou ou recebeu a mensagem.
+  - `channel`: Canal de comunicação utilizado (ex. WhatsApp, SMS).
+  - `customer_phone`: Número de telefone do cliente.
+  - `company_phone`: Número de telefone da empresa.
+  - `status`: Status da mensagem (opcional).
+
+### 6. `ChatbotResponse` e `RedirectResponse`
+
+Essas classes são usadas para definir a resposta do chatbot após o processamento de uma mensagem.
+
+- **`ChatbotResponse`**: Contém uma mensagem de resposta e uma rota opcional.
+- **`RedirectResponse`**: Define uma rota para a qual o chatbot deve redirecionar o fluxo.
+
+### 7. `Route` e `RouteError`
+
+A classe `Route` gerencia a navegação entre diferentes partes do fluxo do chatbot, permitindo obter a rota anterior e calcular a próxima rota com base na entrada do usuário.
+
+- **Métodos principais:**
+  - `get_previous`: Retorna o caminho anterior ao atual.
+  - `get_next`: Monta e retorna o próximo caminho com base em uma parte fornecida.
+
+A classe `RouteError` é uma exceção personalizada usada para indicar problemas relacionados à navegação nas rotas.
+
+## Exemplo de Uso
+
+Aqui está um exemplo básico de como configurar e utilizar o ChatGraph:
+
+```python
+from chatgraph import ChatbotApp, ChatbotRouter, SimpleUserState, RabbitMessageConsumer, ChatbotResponse
+
+# Definindo rotas com ChatbotRouter
+router = ChatbotRouter()
+
+@router.route("START")
+def say_hello():
+    return ChatbotResponse(message="Hello! How can I assist you today?", route="HELP")
+
+@router.route("/HELP")
+def provide_help():
+    return ChatbotResponse(message="Here are some things I can help with: ...")
+
+# Configurando a aplicação do chatbot
+user_state = SimpleUserState()
+message_consumer = RabbitMessageConsumer.load_dotenv()
+
+app = ChatbotApp(user_state=user_state, message_consumer=message_consumer)
+app.include_router(router, prefix="")
+
+# Iniciando o chatbot
+app.start()
+```
+
+Neste exemplo, o chatbot responde "Hello! How can I assist you today?" quando a rota `HELLO` é acessada e depois direciona o usuário para a rota `HELP`.
+
+## Contribuição
+
+Se você encontrar bugs ou tiver sugestões de melhorias, sinta-se à vontade para abrir uma issue ou enviar um pull request no repositório do projeto.
+
+## Licença
+
+Este projeto está licenciado sob a licença MIT. Consulte o arquivo LICENSE para obter mais detalhes.
+
+---
+
+Com **ChatGraph**, você tem a flexibilidade e a simplicidade necessárias para construir chatbots poderosos e altamente configuráveis, integrados, por enquanto, com RabbitMQ para um processamento robusto de mensagens.

chatgraph-0.1.1/chatgraph/__init__.py

@@ -0,0 +1,20 @@
+from .auth.credentials import Credential
+from .bot.chatbot_model import ChatbotApp
+from .bot.chatbot_router import ChatbotRouter
+from .messages.rabbitMQ_message_consumer import RabbitMessageConsumer
+from .types.message_types import Message
+from .types.output_state import ChatbotResponse, RedirectResponse
+from .types.route import Route
+from .types.user_state import SimpleUserState
+
+__all__ = [
+    'ChatbotApp',
+    'Credential',
+    'SimpleUserState',
+    'Message',
+    'ChatbotRouter',
+    'ChatbotResponse',
+    'RedirectResponse',
+    'RabbitMessageConsumer',
+    'Route',
+]

chatgraph-0.1.1/chatgraph/auth/credentials.py

@@ -0,0 +1,71 @@
+import os
+
+
+class Credential:
+    """
+    Classe para gerenciar credenciais de usuário e senha, com suporte a variáveis de ambiente.
+    """
+
+    def __init__(self, username: str | None = None, password: str | None = None):
+        """
+        Inicializa a classe Credential com um nome de usuário e senha.
+
+        Args:
+            username (str | None): O nome de usuário. Pode ser None se for carregado de uma variável de ambiente.
+            password (str | None): A senha do usuário. Pode ser None se for carregada de uma variável de ambiente.
+        """
+        self.__username = username
+        self.__password = password
+
+    @property
+    def password(self) -> str:
+        """
+        Retorna a senha do usuário.
+
+        Raises:
+            ValueError: Se a senha não estiver definida.
+
+        Returns:
+            str: A senha do usuário.
+        """
+        if not self.__password:
+            raise ValueError('Senha vazia!')
+        return self.__password
+
+    @property
+    def username(self) -> str:
+        """
+        Retorna o nome de usuário.
+
+        Raises:
+            ValueError: Se o nome de usuário não estiver definido.
+
+        Returns:
+            str: O nome de usuário.
+        """
+        if not self.__username:
+            raise ValueError('Usuário vazio!')
+        return self.__username
+
+    @classmethod
+    def load_dotenv(cls, user_env: str = 'CHATBOT_USER', pass_env: str = 'CHATBOT_PASS') -> 'Credential':
+        """
+        Carrega as credenciais de variáveis de ambiente e retorna uma instância da classe Credential.
+
+        Args:
+            user_env (str): Nome da variável de ambiente que armazena o nome de usuário. Padrão é 'CHATBOT_USER'.
+            pass_env (str): Nome da variável de ambiente que armazena a senha. Padrão é 'CHATBOT_PASS'.
+
+        Raises:
+            ValueError: Se o nome de usuário ou a senha não estiverem definidas nas variáveis de ambiente.
+
+        Returns:
+            Credential: Uma instância da classe Credential com as credenciais carregadas.
+        """
+        username = os.getenv(user_env)
+        password = os.getenv(pass_env)
+
+        if not username or not password:
+            raise ValueError('Corrija as variáveis de ambiente!')
+
+        return cls(username=username, password=password)

chatgraph-0.1.1/chatgraph/bot/chatbot_model.py

@@ -0,0 +1,171 @@
+import inspect
+from abc import ABC
+from functools import wraps
+from logging import debug
+
+from ..error.chatbot_error import ChatbotError, ChatbotMessageError
+from ..messages.base_message_consumer import MessageConsumer
+from ..types.message_types import Message
+from ..types.output_state import ChatbotResponse, RedirectResponse
+from ..types.route import Route
+from ..types.user_state import UserState
+from .chatbot_router import ChatbotRouter
+
+
+class ChatbotApp(ABC):
+    """
+    Classe principal para a aplicação do chatbot, gerencia as rotas e a lógica de processamento de mensagens.
+    """
+
+    def __init__(self, user_state: UserState, message_consumer: MessageConsumer):
+        """
+        Inicializa a classe ChatbotApp com um estado de usuário e um consumidor de mensagens.
+
+        Args:
+            user_state (UserState): O estado do usuário, que contém informações persistentes sobre as interações do usuário.
+            message_consumer (MessageConsumer): O consumidor de mensagens que lida com a entrada de mensagens no sistema.
+        """
+        self.__message_consumer = message_consumer
+        self.__user_state = user_state
+        self.__routes = {}
+    
+    def include_router(self, router: ChatbotRouter, prefix: str):
+        """
+        Inclui um roteador de chatbot com um prefixo nas rotas da aplicação.
+
+        Args:
+            router (ChatbotRouter): O roteador contendo as rotas a serem adicionadas.
+            prefix (str): O prefixo a ser adicionado às rotas do roteador.
+
+        Raises:
+            ChatbotError: Se a rota 'START' não for encontrada no roteador.
+        """
+        if 'START' not in router.routes.keys():
+            raise ChatbotError('Erro ao incluir rota, START não encontrado!')
+
+        prefixed_routes = {
+            (
+                f'START{prefix.upper()}'
+                if key.upper() == 'START'
+                else f'START{prefix.upper()}{key.upper().replace("START", "")}'
+            ): value
+            for key, value in router.routes.items()
+        }
+        self.__routes.update(prefixed_routes)
+
+    def route(self, route_name: str):
+        """
+        Decorador para adicionar uma função como uma rota na aplicação do chatbot.
+
+        Args:
+            route_name (str): O nome da rota para a qual a função deve ser associada.
+
+        Returns:
+            function: O decorador que adiciona a função à rota especificada.
+        """
+        route_name = route_name.strip().upper()
+
+        if 'START' not in route_name:
+            route_name = f'START{route_name}'
+
+        def decorator(func):
+            params = dict()
+            signature = inspect.signature(func)
+            output_param = signature.return_annotation
+
+            for name, param in signature.parameters.items():
+                param_type = (
+                    param.annotation
+                    if param.annotation != inspect.Parameter.empty
+                    else 'Any'
+                )
+                params[param_type] = name
+                debug(f'Parameter: {name}, Type: {param_type}')
+
+            self.__routes[route_name] = {
+                'function': func,
+                'params': params,
+                'return': output_param,
+            }
+
+            @wraps(func)
+            def wrapper(*args, **kwargs):
+                return func(*args, **kwargs)
+
+            return wrapper
+
+        return decorator
+
+    def start(self):
+        """
+        Inicia o consumo de mensagens pelo chatbot, processando cada mensagem recebida.
+        """
+        self.__message_consumer.start_consume(self.process_message)
+
+    def process_message(self, message: Message):
+        """
+        Processa uma mensagem recebida, identificando a rota correspondente e executando a função associada.
+
+        Args:
+            message (Message): A mensagem a ser processada.
+
+        Raises:
+            ChatbotMessageError: Se nenhuma rota for encontrada para o menu atual do usuário.
+            ChatbotError: Se o tipo de retorno da função associada à rota for inválido.
+
+        Returns:
+            str: A resposta gerada pela função da rota, que pode ser uma mensagem ou o resultado de uma redireção.
+        """
+        customer_id = message.customer_id
+
+        menu = self.__user_state.get_menu(customer_id)
+        menu = menu.upper()
+        handler = self.__routes.get(menu, None)
+
+        if not handler:
+            raise ChatbotMessageError(
+                customer_id, f'Rota não encontrada para {menu}!'
+            )
+        func = handler['function']
+        message_name = handler['params'].get(Message, None)
+        route_state_name = handler['params'].get(Route, None)
+
+        kwargs = dict()
+        if message_name:
+            kwargs[message_name] = message
+        if route_state_name:
+            kwargs[route_state_name] = Route(menu, list(self.__routes.keys()))
+
+        message_response = func(**kwargs)
+
+        if type(message_response) in (str, float, int):
+            return message_response
+        elif type(message_response) == ChatbotResponse:
+            route = self.__adjust_route(message_response.route, menu)
+            self.__user_state.set_menu(customer_id, route)
+            return message_response.message
+        elif type(message_response) == RedirectResponse:
+            route = self.__adjust_route(message_response.route, menu)
+            self.__user_state.set_menu(customer_id, route)
+            return self.process_message(message)
+        else:
+            raise ChatbotError('Tipo de retorno inválido!')
+
+    def __adjust_route(self, route: str, absolute_route: str) -> str:
+        """
+        Ajusta a rota fornecida para incluir o prefixo necessário, se não estiver presente.
+
+        Args:
+            route (str): A rota que precisa ser ajustada.
+            absolute_route (str): A rota completa atual, usada como referência.
+
+        Returns:
+            str: A rota ajustada.
+        """
+        if not route:
+            return absolute_route
+
+        if 'START' not in route:
+            route = absolute_route + route
+
+        return route

chatgraph-0.1.1/chatgraph/bot/chatbot_router.py

@@ -0,0 +1,85 @@
+import inspect
+from functools import wraps
+from logging import debug
+
+from ..error.chatbot_error import ChatbotError
+
+
+class ChatbotRouter:
+    """
+    Classe responsável por gerenciar e registrar as rotas do chatbot, associando-as a funções específicas.
+    
+    Atributos:
+        routes (dict): Um dicionário que armazena as rotas do chatbot e suas funções associadas.
+    """
+
+    def __init__(self):
+        """
+        Inicializa a classe ChatbotRouter com um dicionário vazio de rotas.
+        """
+        self.routes = {}
+
+    def route(self, route_name: str):
+        """
+        Decorador para adicionar uma função como uma rota no roteador do chatbot.
+
+        Args:
+            route_name (str): O nome da rota para a qual a função deve ser associada.
+
+        Returns:
+            function: O decorador que adiciona a função à rota especificada.
+        """
+        if 'START' not in route_name:
+            route_name = f'START{route_name}'
+
+        def decorator(func):
+            params = dict()
+            signature = inspect.signature(func)
+            output_param = signature.return_annotation
+
+            for name, param in signature.parameters.items():
+                param_type = (
+                    param.annotation
+                    if param.annotation != inspect.Parameter.empty
+                    else 'Any'
+                )
+                params[param_type] = name
+                debug(f'Parameter: {name}, Type: {param_type}')
+
+            self.routes[route_name.strip().upper()] = {
+                'function': func,
+                'params': params,
+                'return': output_param,
+            }
+
+            @wraps(func)
+            def wrapper(*args, **kwargs):
+                return func(*args, **kwargs)
+
+            return wrapper
+
+        return decorator
+
+    def include_router(self, router: 'ChatbotRouter', prefix: str):
+        """
+        Inclui outro roteador com um prefixo nas rotas do roteador atual.
+
+        Args:
+            router (ChatbotRouter): O roteador contendo as rotas a serem adicionadas.
+            prefix (str): O prefixo a ser adicionado às rotas do roteador.
+
+        Raises:
+            ChatbotError: Se a rota 'START' não for encontrada no roteador fornecido.
+        """
+        if 'START' not in router.routes.keys():
+            raise ChatbotError('Erro ao incluir rota, START não encontrado!')
+
+        prefixed_routes = {
+            (
+                f'{prefix.upper()}'
+                if key.upper() == 'START'
+                else f'START{prefix.upper()}{key.upper().replace("START", "")}'
+            ): value
+            for key, value in router.routes.items()
+        }
+        self.routes.update(prefixed_routes)

chatgraph-0.1.1/chatgraph/error/chatbot_error.py

@@ -0,0 +1,57 @@
+class ChatbotError(Exception):
+    """
+    Exceção personalizada para erros gerais relacionados ao chatbot.
+
+    Atributos:
+        message (str): A mensagem de erro descrevendo o problema.
+    """
+
+    def __init__(self, message: str):
+        """
+        Inicializa a exceção ChatbotError com uma mensagem de erro.
+
+        Args:
+            message (str): A mensagem de erro descrevendo o problema.
+        """
+        self.message = message
+        super().__init__(self.message)
+
+    def __str__(self):
+        """
+        Retorna a representação em string da exceção ChatbotError.
+
+        Returns:
+            str: Uma string formatada que inclui o nome da exceção e a mensagem de erro.
+        """
+        return f'ChatbotError: {self.message}'
+
+
+class ChatbotMessageError(Exception):
+    """
+    Exceção personalizada para erros relacionados a mensagens de clientes no chatbot.
+
+    Atributos:
+        customer_id (str): O ID do cliente relacionado ao erro.
+        message (str): A mensagem de erro descrevendo o problema, incluindo o ID do cliente.
+    """
+
+    def __init__(self, customer_id: str, message: str):
+        """
+        Inicializa a exceção ChatbotMessageError com um ID de cliente e uma mensagem de erro.
+
+        Args:
+            customer_id (str): O ID do cliente relacionado ao erro.
+            message (str): A mensagem de erro descrevendo o problema.
+        """
+        self.customer_id = customer_id
+        self.message = f'{message} ID recebido: {customer_id}'
+        super().__init__(self.message)
+
+    def __str__(self):
+        """
+        Retorna a representação em string da exceção ChatbotMessageError.
+
+        Returns:
+            str: Uma string formatada que inclui o nome da exceção e a mensagem de erro.
+        """
+        return f'ChatbotMessageError: {self.message}'

chatgraph-0.1.1/chatgraph/error/route_error.py

@@ -0,0 +1,26 @@
+class RouteError(Exception):
+    """
+    Exceção personalizada para erros relacionados a rotas no sistema do chatbot.
+
+    Atributos:
+        message (str): A mensagem de erro descrevendo o problema.
+    """
+
+    def __init__(self, message: str):
+        """
+        Inicializa a exceção RouteError com uma mensagem de erro.
+
+        Args:
+            message (str): A mensagem de erro descrevendo o problema.
+        """
+        self.message = message
+        super().__init__(self.message)
+
+    def __str__(self):
+        """
+        Retorna a representação em string da exceção RouteError.
+
+        Returns:
+            str: Uma string formatada que inclui o nome da exceção e a mensagem de erro.
+        """
+        return f'RouteError: {self.message}'

chatgraph-0.1.1/chatgraph/messages/base_message_consumer.py

@@ -0,0 +1,33 @@
+from abc import ABC, abstractmethod
+from typing import Any, Callable
+
+
+class MessageConsumer(ABC):
+    """
+    Classe base abstrata para consumidores de mensagens no sistema do chatbot.
+
+    Esta classe define a interface que todos os consumidores de mensagens devem implementar para serem usados no sistema do chatbot.
+    """
+
+    @abstractmethod
+    def start_consume(self, process_message: Callable) -> Any:
+        """
+        Inicia o consumo de mensagens e processa cada mensagem usando a função fornecida.
+
+        Args:
+            process_message (Callable): Função de callback que processa cada mensagem recebida.
+
+        Returns:
+            Any: O resultado do processo de consumo de mensagens, dependendo da implementação concreta.
+        """
+        pass
+
+    @abstractmethod
+    def load_dotenv(self) -> 'MessageConsumer':
+        """
+        Carrega variáveis de ambiente para configurar o consumidor de mensagens.
+
+        Returns:
+            MessageConsumer: A instância do consumidor de mensagens configurado.
+        """
+        pass

chatgraph-0.1.1/chatgraph/messages/rabbitMQ_message_consumer.py

@@ -0,0 +1,172 @@
+import json
+from logging import debug, info
+import os
+import pika
+from typing import Callable
+from ..auth.credentials import Credential
+from ..types.message_types import Message
+from .base_message_consumer import MessageConsumer
+
+
+class RabbitMessageConsumer(MessageConsumer):
+    """
+    Implementação de MessageConsumer para consumir mensagens de uma fila RabbitMQ.
+
+    Atributos:
+        __virtual_host (str): O host virtual usado para a conexão RabbitMQ.
+        __prefetch_count (int): O número de mensagens pré-carregadas que o consumidor pode processar.
+        __queue_consume (str): O nome da fila de consumo.
+        __amqp_url (str): A URL de conexão AMQP do RabbitMQ.
+        __credentials (pika.PlainCredentials): Credenciais do RabbitMQ para autenticação.
+    """
+
+    def __init__(
+        self,
+        credential: Credential,
+        amqp_url: str,
+        queue_consume: str,
+        prefetch_count: int = 1,
+        virtual_host: str = '/',
+    ) -> None:
+        """
+        Inicializa o consumidor de mensagens RabbitMQ com as configurações fornecidas.
+
+        Args:
+            credential (Credential): Credenciais de autenticação para o RabbitMQ.
+            amqp_url (str): A URL de conexão AMQP do RabbitMQ.
+            queue_consume (str): O nome da fila de consumo.
+            prefetch_count (int, opcional): O número de mensagens pré-carregadas. Padrão é 1.
+            virtual_host (str, opcional): O host virtual do RabbitMQ. Padrão é '/'.
+        """
+        self.__virtual_host = virtual_host
+        self.__prefetch_count = prefetch_count
+        self.__queue_consume = queue_consume
+        self.__amqp_url = amqp_url
+        self.__credentials = pika.PlainCredentials(
+            credential.username, credential.password
+        )
+
+    @classmethod
+    def load_dotenv(
+        cls,
+        user_env: str = 'RABBIT_USER',
+        pass_env: str = 'RABBIT_PASS',
+        uri_env: str = 'RABBIT_URI',
+        queue_env: str = 'RABBIT_QUEUE',
+        prefetch_env: str = 'RABBIT_PREFETCH',
+        vhost_env: str = 'RABBIT_VHOST',
+    ) -> 'RabbitMessageConsumer':
+        """
+        Carrega as configurações do RabbitMQ a partir de variáveis de ambiente e retorna uma instância de RabbitMessageConsumer.
+
+        Args:
+            user_env (str): Nome da variável de ambiente para o usuário do RabbitMQ. Padrão é 'RABBIT_USER'.
+            pass_env (str): Nome da variável de ambiente para a senha do RabbitMQ. Padrão é 'RABBIT_PASS'.
+            uri_env (str): Nome da variável de ambiente para a URL do RabbitMQ. Padrão é 'RABBIT_URI'.
+            queue_env (str): Nome da variável de ambiente para a fila de consumo do RabbitMQ. Padrão é 'RABBIT_QUEUE'.
+            prefetch_env (str): Nome da variável de ambiente para o prefetch count. Padrão é 'RABBIT_PREFETCH'.
+            vhost_env (str): Nome da variável de ambiente para o host virtual do RabbitMQ. Padrão é 'RABBIT_VHOST'.
+
+        Raises:
+            ValueError: Se qualquer uma das variáveis de ambiente necessárias não estiver definida.
+
+        Returns:
+            RabbitMessageConsumer: Uma instância configurada do RabbitMessageConsumer.
+        """
+        username = os.getenv(user_env)
+        password = os.getenv(pass_env)
+        url = os.getenv(uri_env)
+        queue = os.getenv(queue_env)
+        prefetch = os.getenv(prefetch_env, 1)
+        vhost = os.getenv(vhost_env, '/')
+
+        if not username or not password or not url or not queue:
+            raise ValueError('Corrija as variáveis de ambiente!')
+
+        return cls(
+            credential=Credential(username=username, password=password),
+            amqp_url=url,
+            queue_consume=queue,
+            prefetch_count=int(prefetch),
+            virtual_host=vhost,
+        )
+
+    def start_consume(self, process_message: Callable) -> None:
+        """
+        Inicia o consumo de mensagens da fila RabbitMQ e processa cada mensagem usando a função fornecida.
+
+        Args:
+            process_message (Callable): Função de callback que processa cada mensagem recebida.
+
+        Raises:
+            pika.exceptions.StreamLostError: Se a conexão com o RabbitMQ for perdida, tentará reconectar automaticamente.
+        """
+        try:
+            connection = pika.BlockingConnection(
+                pika.ConnectionParameters(
+                    host=self.__amqp_url,
+                    virtual_host=self.__virtual_host,
+                    credentials=self.__credentials,
+                )
+            )
+            channel = connection.channel()
+
+            channel.basic_qos(prefetch_count=self.__prefetch_count)
+            channel.basic_consume(
+                queue=self.__queue_consume,
+                on_message_callback=lambda c, m, p, b: self.on_request(
+                    c, m, p, b, process_message
+                ),
+            )
+
+            info('[x] Aguardando solicitações RPC')
+            channel.start_consuming()
+        except pika.exceptions.StreamLostError as e:
+            debug(e)
+            self.start_consume(process_message)
+
+    def on_request(self, ch, method, props, body, process_message) -> None:
+        """
+        Processa uma mensagem recebida e publica a resposta de volta na fila especificada.
+
+        Args:
+            ch: Canal do RabbitMQ.
+            method: Método de entrega do RabbitMQ.
+            props: Propriedades da mensagem do RabbitMQ.
+            body: Corpo da mensagem recebida.
+            process_message (Callable): Função que processa a mensagem e retorna uma resposta.
+        """
+        message = body.decode()
+        message_json = json.loads(message)
+        pure_message = self.__transform_message(message_json)
+        response = process_message(pure_message)
+
+        ch.basic_publish(
+            exchange='',
+            routing_key=props.reply_to,
+            properties=pika.BasicProperties(
+                correlation_id=props.correlation_id
+            ),
+            body=str(response),
+        )
+        ch.basic_ack(delivery_tag=method.delivery_tag)
+
+    def __transform_message(self, message: dict) -> Message:
+        """
+        Transforma o dicionário JSON recebido em uma instância de Message.
+
+        Args:
+            message (dict): Dicionário contendo os dados da mensagem.
+
+        Returns:
+            Message: Uma instância da classe Message com os dados extraídos do dicionário.
+        """
+        return Message(
+            type=message.get('type', ''),
+            text=message.get('text', ''),
+            customer_id=message.get('customer_id', ''),
+            channel=message.get('channel', ''),
+            customer_phone=message.get('customer_phone', ''),
+            company_phone=message.get('company_phone', ''),
+            status=message.get('status'),
+        )

chatgraph-0.1.1/chatgraph/types/message_types.py

@@ -0,0 +1,25 @@
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class Message:
+    """
+    Representa uma mensagem recebida ou enviada pelo chatbot.
+
+    Atributos:
+        type (str): O tipo da mensagem (por exemplo, texto, imagem, etc.).
+        text (str): O conteúdo textual da mensagem.
+        customer_id (str): O ID do cliente que enviou ou recebeu a mensagem.
+        channel (str): O canal pelo qual a mensagem foi enviada ou recebida (por exemplo, WhatsApp, SMS, etc.).
+        customer_phone (str): O número de telefone do cliente.
+        company_phone (str): O número de telefone da empresa que está enviando ou recebendo a mensagem.
+        status (Optional[str]): O status da mensagem (por exemplo, enviada, recebida, lida, etc.). Este campo é opcional.
+    """
+    type: str
+    text: str
+    customer_id: str
+    channel: str
+    customer_phone: str
+    company_phone: str
+    status: Optional[str] = None

chatgraph-0.1.1/chatgraph/types/output_state.py

@@ -0,0 +1,42 @@
+from typing import Union
+
+messageTypes = Union[str, float, int, None]
+
+
+class ChatbotResponse:
+    """
+    Representa a resposta do chatbot, contendo a mensagem a ser enviada ao usuário e a rota a ser seguida.
+
+    Atributos:
+        message (messageTypes): A mensagem de resposta do chatbot. Pode ser uma string, um número, ou None.
+        route (str, opcional): A rota para a qual o chatbot deve direcionar após esta mensagem. Padrão é None.
+    """
+
+    def __init__(self, message: messageTypes = None, route: str = None) -> None:
+        """
+        Inicializa a resposta do chatbot com uma mensagem e uma rota opcional.
+
+        Args:
+            message (messageTypes, opcional): A mensagem a ser enviada ao usuário. Pode ser uma string, um número, ou None.
+            route (str, opcional): A rota para a qual o chatbot deve direcionar após esta mensagem. Padrão é None.
+        """
+        self.message = message
+        self.route = route
+
+
+class RedirectResponse:
+    """
+    Representa uma resposta que redireciona o fluxo do chatbot para uma nova rota.
+
+    Atributos:
+        route (str): A rota para a qual o chatbot deve redirecionar.
+    """
+
+    def __init__(self, route: str) -> None:
+        """
+        Inicializa a resposta de redirecionamento com a rota especificada.
+
+        Args:
+            route (str): A rota para a qual o chatbot deve redirecionar.
+        """
+        self.route = route

chatgraph-0.1.1/chatgraph/types/route.py

@@ -0,0 +1,75 @@
+from ..error.route_error import RouteError
+
+
+class Route:
+    """
+    Representa uma rota no sistema do chatbot, gerenciando a navegação entre diferentes partes do fluxo.
+
+    Atributos:
+        current (str): A rota atual.
+        routes (list[str]): A lista de todas as rotas disponíveis no fluxo.
+    """
+
+    def __init__(self, current: str, routes: list[str]):
+        """
+        Inicializa a rota com a rota atual e a lista de rotas disponíveis.
+
+        Args:
+            current (str): A rota atual.
+            routes (list[str]): A lista de todas as rotas disponíveis no fluxo.
+        """
+        self.current = current
+        self.routes = routes
+
+    def get_previous(self) -> str:
+        """
+        Retorna o caminho anterior ao caminho atual.
+
+        Raises:
+            RouteError: Se a rota atual for 'START', indicando que não há caminho anterior.
+
+        Returns:
+            str: O caminho anterior à rota atual.
+        """
+        if self.current == 'START':
+            raise RouteError('Não há caminho anterior ao START')
+
+        previous_route = '/'.join(self.current.split('/')[:-1])
+        return previous_route
+
+    def get_next(self, next_part: str) -> str:
+        """
+        Monta e retorna o próximo caminho com base na parte fornecida.
+
+        Args:
+            next_part (str): A parte do caminho a ser adicionada à rota atual.
+
+        Raises:
+            RouteError: Se a próxima rota montada não estiver na lista de rotas disponíveis.
+
+        Returns:
+            str: O próximo caminho construído a partir da rota atual e da parte fornecida.
+        """
+        next_part = next_part.strip().upper()
+        next_route = f"{self.current.rstrip('/')}{next_part}"
+        if next_route not in self.routes:
+            raise RouteError(f'Rota não encontrada: {next_route}')
+        return next_route
+
+    def __str__(self):
+        """
+        Retorna uma representação em string da rota atual.
+
+        Returns:
+            str: A representação em string da rota atual.
+        """
+        return f'Route(current={self.current})'
+
+    def __repr__(self):
+        """
+        Retorna a representação oficial da rota, que é a mesma que a representação em string.
+
+        Returns:
+            str: A representação oficial da rota.
+        """
+        return self.__str__()

chatgraph-0.1.1/chatgraph/types/user_state.py

@@ -0,0 +1,74 @@
+from abc import ABC, abstractmethod
+
+
+class UserState(ABC):
+    """
+    Classe abstrata para gerenciar o estado do usuário no fluxo do chatbot.
+
+    Esta classe define a interface para implementar o gerenciamento de estado do usuário, incluindo métodos para obter e definir o menu atual do usuário.
+    """
+
+    @abstractmethod
+    def get_menu(self, customer_id: str) -> str:
+        """
+        Retorna o menu atual para o ID de cliente fornecido.
+
+        Args:
+            customer_id (str): O ID do cliente.
+
+        Returns:
+            str: O menu atual associado ao cliente.
+        """
+        pass
+
+    @abstractmethod
+    def set_menu(self, customer_id: str, menu: str) -> None:
+        """
+        Define o menu atual para o ID de cliente fornecido.
+
+        Args:
+            customer_id (str): O ID do cliente.
+            menu (str): O menu a ser definido para o cliente.
+        """
+        pass
+
+
+class SimpleUserState(UserState):
+    """
+    Implementação simples de UserState que armazena o estado do usuário em um dicionário em memória.
+
+    Atributos:
+        states (dict): Dicionário que armazena o estado de menu atual para cada cliente.
+    """
+
+    def __init__(self):
+        """
+        Inicializa o estado do usuário com um dicionário vazio.
+        """
+        self.states = {}
+
+    def get_menu(self, customer_id: str) -> str:
+        """
+        Retorna o menu atual para o ID de cliente fornecido. Se o cliente não tiver um menu definido, define 'START' como padrão.
+
+        Args:
+            customer_id (str): O ID do cliente.
+
+        Returns:
+            str: O menu atual associado ao cliente.
+        """
+        menu = self.states.get(customer_id, 'START')
+        if menu == 'START':
+            self.set_menu(customer_id, menu)
+        return menu
+
+    def set_menu(self, customer_id: str, menu: str | None = None) -> None:
+        """
+        Define o menu atual para o ID de cliente fornecido. Converte o nome do menu para maiúsculas.
+
+        Args:
+            customer_id (str): O ID do cliente.
+            menu (str | None): O menu a ser definido para o cliente. Se None, não faz nenhuma alteração.
+        """
+        if menu:
+            self.states[customer_id] = menu.upper()

chatgraph-0.1.1/pyproject.toml

@@ -0,0 +1,46 @@
+[tool.poetry]
+name = "chatgraph"
+version = "0.1.1"
+description = "A user-friendly chatbot library"
+authors = ["Irisson N. Lima <irisson.lima@verdecard.com.br>"]
+readme = "README.md"
+homepage = "https://github.com/irissonnlima/chatgraph"
+repository = "https://github.com/irissonnlima/chatgraph"
+keywords = ["chatbot", "rabbitmq", "messaging", "routing", "chatgraph", "python"]
+license = "MIT"
+
+[tool.poetry.dependencies]
+python = "^3.12"
+pika = "^1.3.2"
+
+[tool.poetry.group.dev.dependencies]
+ruff = "^0.5.1"
+pytest = "^8.2.2"
+pytest-cov = "^5.0.0"
+taskipy = "^1.13.0"
+
+[tool.pytest.ini_options]
+pythonpath = "."
+addopts = "-p no:warnings"
+
+[tool.ruff]
+line-length = 79
+extend-exclude = ['migrations']
+
+[tool.ruff.lint]
+preview = true
+select = ['I', 'F', 'E', 'W', 'PL', 'PT']
+
+[tool.ruff.format]
+preview = true
+quote-style = 'single'
+
+[tool.taskipy.tasks]
+test = 'pytest --cov=chatgraph --cov-report=html'
+start_cov = 'start htmlcov/index.html'
+lint = 'ruff check . && ruff check . --diff'
+format = 'ruff format . && ruff check . --fix'
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"