chatgraph 1.2.2__tar.gz → 1.2.3__tar.gz

{chatgraph-1.2.2 → chatgraph-1.2.3}/.github/skills/chatgraph-framework/SKILL.md

@@ -169,6 +169,19 @@ menu = await usercall.get_menu(description='Suporte TI')   # por descrição
 # Setters diretos (síncronos — não persistem imediatamente, usam loop existente)
 usercall.observation = {'chave': 'valor'}  # dict — substitui toda a observação
 usercall.content_message = 'nova mensagem'  # str — sobrescreve o texto recebido
+
+# Carga/atualização de dados remotos
+identity = await usercall.load_identity()            # recarrega UserIdentity da API
+identity = await usercall.load_identity(cpf='cpf')   # força busca por CPF específico
+userstate = await usercall.load_userstate()          # recarrega UserState completo da API
+
+# Associação de CPF
+await usercall.associate_cpf(
+    cpf='00000000000',
+    source='nome_do_menu',   # origem da associação (ex: nome do menu)
+    phone='',                # telefone da empresa (opcional)
+    device_id='',            # ID do dispositivo (opcional)
+)
 ```
 
 ---
@@ -295,11 +308,14 @@ file.send_type = SendType.VIDEO
 | Fora de rota (startup, módulo) | `_logger = get_system_logger()` | `chatgraph_logs/system.log` |
 
 ```python
-from chatgraph.logger import get_system_logger, set_level
+from chatgraph.logger import get_system_logger, get_user_logger, set_level
 
 _logger = get_system_logger()
 _logger.info('App iniciada')
 
+# Logger de usuário fora de uma rota (raramente necessário — prefira usercall.logger dentro de rotas)
+user_log = get_user_logger('user123', 'empresa456')
+
 # Alterar nível de log em runtime (afeta todos os loggers existentes)
 set_level('DEBUG')   # ou logging.DEBUG
 # Equivalente: UserLoggerManager.set_level('DEBUG')
@@ -340,6 +356,12 @@ async def suporte(usercall: UserCall):
 async def aguardar(usercall: UserCall):
     await usercall.send(f'Você disse: {usercall.content_message}')
     return RedirectResponse('start')
+
+# auth_level também pode ser definido em rotas de router
+@router.route('area_rh', auth_level='internal')
+async def area_rh(usercall: UserCall):
+    await usercall.send(f'Olá, {usercall.user.internal.cargo}!')
+    return RedirectResponse('start')
 ```
 
 ```python

{chatgraph-1.2.2 → chatgraph-1.2.3}/.gitignore

@@ -184,5 +184,4 @@ ROADMAP.md
 *.pdf
 *jpg
 *.jpeg
-*.png
-docs/
+*.png

{chatgraph-1.2.2 → chatgraph-1.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chatgraph
-Version: 1.2.2
+Version: 1.2.3
 Summary: A user-friendly chatbot library
 Project-URL: Homepage, https://github.com/irissonnlima/chatgraph
 Project-URL: Repository, https://github.com/irissonnlima/chatgraph

{chatgraph-1.2.2 → chatgraph-1.2.3}/chatgraph/logger/__init__.py

@@ -8,3 +8,4 @@ logger_httpx.setLevel(logging.ERROR)
 get_system_logger = UserLoggerManager.get_system_logger
 get_user_logger = UserLoggerManager.get_user_logger
 set_level = UserLoggerManager.set_level
+remove_user_logger = UserLoggerManager.remove_user_logger

{chatgraph-1.2.2 → chatgraph-1.2.3}/chatgraph/logger/user_logger.py

@@ -52,6 +52,15 @@ class UserLoggerManager:
         cls._loggers[key] = logger
         return logger
 
+    @classmethod
+    def remove_user_logger(cls, user_id: str, company_id: str) -> None:
+        key = f"{user_id}_{company_id}"
+        logger = cls._loggers.pop(key, None)
+        if logger:
+            for handler in logger.handlers[:]:
+                handler.close()
+                logger.removeHandler(handler)
+
     @classmethod
     def get_system_logger(cls) -> logging.Logger:
         key = "chatgraph.system"

{chatgraph-1.2.2 → chatgraph-1.2.3}/chatgraph/messages/message_consumer.py

@@ -117,29 +117,22 @@ class MessageConsumer:
         return f'amqp://{user}:{pwd}@{self.__amqp_url}/{vhost}'
 
     async def __declare_queue(self, channel) -> aio_pika.abc.AbstractQueue:
-        try:
-            return await channel.declare_queue(
-                self.__queue_consume, passive=True
-            )
-        except aio_pika.exceptions.ChannelNotFoundEntity:
-            channel = await channel.connection.channel()
-            await channel.set_qos(prefetch_count=self.__prefetch_count)
-            arguments = {
-                'x-dead-letter-exchange': 'log_error',
-                'x-expires': 86400000,
-                'x-message-ttl': 300000,
-            }
-            queue = await channel.declare_queue(
-                self.__queue_consume,
-                durable=True,
-                arguments=arguments,
-            )
-            routing_key = f'chatbot.{self.__queue_consume}'
-            await queue.bind(
-                exchange=self.__virtual_host,
-                routing_key=routing_key,
-            )
-            return queue
+        arguments = {
+            'x-dead-letter-exchange': 'log_error',
+            'x-expires': 86400000,
+            'x-message-ttl': 300000,
+        }
+        queue = await channel.declare_queue(
+            self.__queue_consume,
+            durable=True,
+            arguments=arguments,
+        )
+        routing_key = f'chatbot.{self.__queue_consume}'
+        await queue.bind(
+            exchange=self.__virtual_host,
+            routing_key=routing_key,
+        )
+        return queue
 
     async def __connect_and_consume(
         self, amqp_url: str, process_message: Callable
@@ -175,6 +168,7 @@ class MessageConsumer:
             await self.cleanup()
 
     async def on_request(self, body: bytes, process_message: Callable):
+        pure_message = None
         try:
             message = body.decode()
             message_json = json.loads(message)
@@ -182,6 +176,9 @@ class MessageConsumer:
             await process_message(pure_message)
         except Exception as e:
             _logger.error(f'Erro ao processar mensagem: {e}')
+        finally:
+            if pure_message is not None:
+                UserLoggerManager.remove_user_logger(pure_message.user_id, pure_message.company_id)
 
     async def __transform_message(self, message: dict) -> UserCall:
         user_state = message.get('user_state', {})

chatgraph-1.2.3/docs/gaps-go-to-python.md

@@ -0,0 +1,150 @@
+# Lacunas: Go → Python
+
+Funcionalidades presentes no `chatgraph-go` que **não existem** no `chatgraph` (Python).
+Ordenadas por impacto estimado em produção.
+
+---
+
+## 1. Timeout automático de handler
+
+**Prioridade: Alta**
+
+No Go, cada rota possui um `TimeoutRouteOps{Duration, Route}`. Quando o handler ultrapassa a duração configurada, a execução é cancelada via `context.Context` e o usuário é redirecionado para uma rota de timeout.
+
+```go
+engine.RegisterRoute("slow_task", handler, chat.RouterHandlerOptions{
+    Timeout: &chat.TimeoutRouteOps{
+        Duration: 30 * time.Second,
+        Route:    "timeout_route",
+    },
+})
+```
+
+**O que falta no Python:**
+- Suporte a `timeout` por rota no decorador `@app.route()` / `@router.route()`
+- Cancelamento do handler assíncrono quando o timeout é atingido
+- Redirect automático para rota de fallback
+
+---
+
+## 2. Loop protection
+
+**Prioridade: Alta**
+
+No Go, o `Engine` rastreia quantas vezes consecutivas o mesmo redirect ocorreu. Se o limite for atingido (`LoopCountRouteOps{Count, Route}`), o usuário é enviado para uma rota de fallback.
+
+```go
+// Padrão: 3 visitas consecutivas → redireciona para "loop_route"
+engine.RegisterRoute("A", func(ctx *chat.Context[Obs]) chat.RouteReturn {
+    return &chat.RedirectResponse{TargetRoute: "A"} // loop detectado na 4ª vez
+})
+```
+
+**O que falta no Python:**
+- Contador de redirects consecutivos para a mesma rota em `UserCall` / `ChatbotApp`
+- Configuração de limite por rota ou global
+- Redirect automático para rota de fallback ao atingir o limite
+
+---
+
+## 3. Route Triggers (regex globais por rota)
+
+**Prioridade: Média-Alta**
+
+No Go, `RouteTrigger{Regex, Route}` permite que qualquer mensagem que bata com um padrão seja redirecionada para uma rota específica **antes** da execução normal. Pode ser configurado globalmente no `Engine` ou por rota.
+
+```go
+engine := chat.NewEngine[Obs](chat.RouterHandlerOptions{
+    Triggers: []chat.RouteTrigger{
+        {Regex: `(?i)^cancelar$`, Route: "cancelar_route"},
+        {Regex: `(?i)^ajuda$`,    Route: "help_route"},
+    },
+})
+```
+
+**O que existe no Python (parcial):**
+O `ChatbotApp` já possui `DEFAULT_FUNCTION` — um dicionário `{regex: callable}` executado antes das rotas (ex: `voltar`). Porém a implementação atual executa uma função diretamente em vez de redirecionar para uma rota nomeada, e não é configurável por rota individualmente.
+
+**O que falta:**
+- Suporte a triggers por rota individualmente
+- Semântica de redirect para rota nomeada (em vez de executar função inline)
+
+---
+
+## 4. Route validation
+
+**Prioridade: Média**
+
+No Go, `engine.ValidateRoutes()` verifica em tempo de inicialização que todas as rotas referenciadas (timeout, loop, protected, triggers) estão de fato registradas, evitando erros silenciosos em produção.
+
+```go
+if err := engine.ValidateRoutes(); err != nil {
+    log.Fatal(err)
+}
+```
+
+**O que falta no Python:**
+- Método `validate_routes()` no `ChatbotApp` que levanta erro se qualquer rota referenciada (em redirects, transfers, etc.) não estiver registrada
+
+---
+
+## 5. `EngineTester` — helper de teste para handlers
+
+**Prioridade: Média**
+
+No Go, `EngineTester` fornece um `mockExecutor` que captura todas as ações executadas pelo handler (mensagens enviadas, observações salvas, rotas definidas, arquivos buscados/enviados) e permite validá-las em assertions.
+
+```go
+tester := chat.NewEngineTester[Obs](t, engine)
+tester.Execute(
+    userState,
+    message,
+    []chat.ExpectedAction{
+        {Type: chat.ExecSendMessage, Message: &expectedMsg},
+        {Type: chat.ExecSetRoute, Route: "next_route"},
+    },
+    expectedReturn,
+)
+```
+
+**O que falta no Python:**
+- Classe `ChatbotTester` (ou similar) que mocka o `RouterHTTPClient` e captura chamadas em sequência
+- Tipos `ExpectedAction` para `send_message`, `set_observation`, `set_route`, `get_file`, `upload_file`
+- Integração com `pytest` e as fixtures existentes em `tests/unit/conftest.py`
+
+---
+
+## 6. Upload de arquivo a partir de bytes (`load_file_bytes`)
+
+**Prioridade: Baixa**
+
+No Go, `ctx.LoadFileBytes("nome.txt", []byte{...})` permite fazer upload de conteúdo gerado em memória sem precisar de um arquivo em disco.
+
+**O que falta no Python:**
+- Método equivalente em `UserCall` para upload a partir de `bytes` diretamente
+
+---
+
+## 7. Deduplicação de arquivos via SHA256
+
+**Prioridade: Baixa**
+
+No Go, o upload de um arquivo já enviado anteriormente retorna o registro cacheado (identificado por hash SHA256), evitando uploads duplicados.
+
+**O que falta no Python:**
+- Verificação de hash antes do upload em `RouterHTTPClient.upload_file()`
+
+---
+
+## 8. `DepartmentID` e `LastUpdate` em `EndChatResponse`
+
+**Prioridade: Baixa**
+
+O `EndAction` do Go possui dois campos extras que o `EndChatResponse` do Python não tem:
+
+| Campo | Go (`EndAction`) | Python (`EndChatResponse`) |
+|---|---|---|
+| `DepartmentID` | `int` | ❌ ausente |
+| `LastUpdate` | `string` (timestamp) | ❌ ausente |
+
+---

chatgraph-1.2.3/docs/gaps-python-to-go.md

@@ -0,0 +1,65 @@
+# Lacunas: Python → Go
+
+Funcionalidades presentes no `chatgraph` (Python) que **não existem** no `chatgraph-go`.
+Ordenadas por impacto estimado.
+
+---
+
+## 1. Sistema de autorização por rota (`auth_level` + `default_guard`)
+
+**Prioridade: Alta**
+
+No Python, cada rota pode declarar um nível de acesso mínimo. O `default_guard` verifica o `AuthLevel` do usuário e redireciona para `menu_id_positiva` se o acesso for insuficiente.
+
+```python
+@app.route("dados_sensiveis", auth_level="write")
+async def handler(usercall: UserCall):
+    ...
+```
+
+`AuthLevel` é um enum ordenado: `blocked < unknown < read < write`, com suporte especial para `internal` (verificação de vínculo interno).
+
+**O que existe no Go (parcial):**
+`ProtectedRouteOps{Route}` apenas redireciona para uma rota se o usuário "não tem acesso", mas não define o que é "ter acesso" — a lógica de verificação fica fora do framework.
+
+**O que falta:**
+- Enum `AuthLevel` com ordenação (`blocked < unknown < read < write`)
+- Campo `AuthLevel` em `UserState.User.Identity`
+- Lógica de `guard` configurável no `Engine` (equivalente ao `default_guard`)
+- Flag `internal` em `UserState.User`
+
+---
+
+## 2. Logger por usuário (`UserLoggerManager`)
+
+**Prioridade: Média**
+
+No Python, cada `UserCall` expõe um `logger` isolado por `(user_id, company_id)`, com suporte a log em arquivo por usuário via `UserLoggerManager`.
+
+```python
+usercall.logger.info("Usuário entrou na rota de pedidos")
+usercall.logger.debug(f"CPF={usercall.user.identity.cpf}")
+```
+
+**O que falta no Go:**
+- Logger estruturado por usuário acessível via `ctx`
+- Suporte a log em arquivo por usuário (ex: `chatgraph_logs/<user_id>.log`)
+- Nível de log configurável globalmente
+
+---
+
+## 3. `user_message` em `TransferToMenu`
+
+**Prioridade: Baixa**
+
+No Python, `TransferToMenu` recebe um `user_message` que é enviado automaticamente após a transferência.
+
+```python
+return TransferToMenu(menu="menu_principal", user_message="inicio")
+```
+
+**O que falta no Go:**
+- Campo `UserMessage string` na struct `TransferToMenu`
+- Envio automático da mensagem pelo adapter após a transferência
+
+---

chatgraph-1.2.3/example.py

@@ -0,0 +1,98 @@
+from chatgraph import (
+    ChatbotApp,
+    UserCall,
+    Route,
+    EndChatResponse,
+    RedirectResponse,
+    Message,
+    File,
+    Button,
+    User,
+    UserIdentity,
+    UserData,
+    UserInternal,
+    TextMessage,
+    UserState,
+    TransferToMenu,
+)
+from chatgraph.logger import get_system_logger
+from dotenv import load_dotenv
+from dataclasses import dataclass
+
+
+load_dotenv()
+_logger = get_system_logger()
+_logger.info('Aplicação inicializada')
+app = ChatbotApp()
+
+
+@dataclass
+class Teste:
+    atributo1: str
+    atributo2: int
+
+
+# Rota inicial com emojis
+@app.route('start')
+async def start(rota: Route, usercall: UserCall):
+    usercall.logger.info('Usuário entrou na rota start')
+    welcome_message = Message(
+        'Bem-vindo ao nosso chatbot! 😊🚀\n Vou te redirecionar para uma área restrita',
+    )
+
+    await usercall.send(welcome_message)
+    return RedirectResponse('perguntar_cpf')
+
+
+@app.route('perguntar_cpf')
+async def perguntar_cpf(rota: Route, usercall: UserCall):
+    usercall.logger.info('Usuário entrou na rota perguntar_cpf')
+    await usercall.send('Por favor, informe seu CPF:')
+    return Route('receber_cpf')
+
+
+@app.route('receber_cpf')
+async def receber_cpf(rota: Route, usercall: UserCall):
+    cpf = usercall.content_message
+    usercall.logger.info(f'CPF recebido: {cpf}')
+    await usercall.add_observation({'cpf': cpf})
+    await usercall.send(f'CPF {cpf} recebido com sucesso!')
+    return RedirectResponse('area_restrita')
+
+
+@app.route('area_restrita', auth_level='internal/read/write')
+async def area_restrita(usercall: UserCall):
+    usercall.logger.info('Usuário acessou área restrita')
+    await usercall.send('Você está em uma área protegida. Acesso autorizado!')
+    return RedirectResponse('choice_start')
+
+
+@app.route('enviar_btns')
+async def enviar_btns(usercall: UserCall):
+    usercall.logger.info('Usuário entrou na rota enviar_btns')
+    buttons = [
+        Button('Reiniciar'),
+        Button('Encerrar'),
+    ]
+    message = Message(text_message='Escolha uma opção:', buttons=buttons)
+    await usercall.send(message)
+    return Route('receber_btns')
+
+
+@app.route('receber_btns')
+async def receber_btns(usercall: UserCall):
+    usercall.logger.info('Usuário entrou na rota receber_btns')
+    choice = usercall.content_message
+
+    usercall.logger.info(f'Opção escolhida: {choice}')
+    if choice == 'Reiniciar':
+        return RedirectResponse('start')
+    elif choice == 'Encerrar':
+        await usercall.send('Encerrando o chat. Até mais!')
+        return EndChatResponse('voll_ended')
+    else:
+        await usercall.send('Opção inválida. Por favor, escolha novamente.')
+        return Route('enviar_btns')
+
+
+app.start()

{chatgraph-1.2.2 → chatgraph-1.2.3}/pyproject.toml

@@ -1,80 +1,80 @@
-[project]
-name = "chatgraph"
-version = "1.2.2"
-description = "A user-friendly chatbot library"
-authors = [
-    {name = "Irisson N. Lima", email = "irisson.lima@verdecard.com.br"}
-]
-readme = "README.md"
-requires-python = ">=3.12,<4.0"
-keywords = ["chatbot", "rabbitmq", "messaging", "routing", "chatgraph", "python"]
-license = {text = "MIT"}
-dependencies = [
-    "pika>=1.3.2",
-    "rich>=13.8.1",
-    "grpcio>=1.67.0",
-    "grpcio-tools>=1.67.0",
-    "python-dotenv>=1.0.1",
-    "typer>=0.12.5",
-    "matplotlib>=3.10.0",
-    "networkx>=3.4.2",
-    "protobuf>=6.31.1",
-    "httpx>=0.28.1",
-    "aio-pika>=9.5.8",
-]
-
-dev-dependencies = [
-    "ruff>=0.5.1",
-    "pytest>=8.2.2",
-    "pytest-cov>=5.0.0",
-    "taskipy>=1.13.0",
-    "pytest-asyncio>=1.3.0",
-    "respx>=0.22.0",
-    "pytest-httpx>=0.35.0",
-]
-
-
-[project.urls]
-Homepage = "https://github.com/irissonnlima/chatgraph"
-Repository = "https://github.com/irissonnlima/chatgraph"
-
-[project.scripts]
-  # chatgraph = "chatgraph.cli:main"
-
-
-[tool.pytest.ini_options]
-pythonpath = "."
-addopts = "-p no:warnings"
-testpaths = ["tests"]
-markers = [
-    "unit: marks tests as unit tests (fast, isolated, uses mocks)",
-    "integration: marks tests as integration tests (slow, requires external services)",
-]
-
-[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 = ["hatchling"]
-build-backend = "hatchling.build"
-
-[dependency-groups]
-dev = [
-    "pytest>=9.0.3",
-    "ruff>=0.15.12",
-]
+[project]
+name = "chatgraph"
+version = "1.2.3"
+description = "A user-friendly chatbot library"
+authors = [
+    {name = "Irisson N. Lima", email = "irisson.lima@verdecard.com.br"}
+]
+readme = "README.md"
+requires-python = ">=3.12,<4.0"
+keywords = ["chatbot", "rabbitmq", "messaging", "routing", "chatgraph", "python"]
+license = {text = "MIT"}
+dependencies = [
+    "pika>=1.3.2",
+    "rich>=13.8.1",
+    "grpcio>=1.67.0",
+    "grpcio-tools>=1.67.0",
+    "python-dotenv>=1.0.1",
+    "typer>=0.12.5",
+    "matplotlib>=3.10.0",
+    "networkx>=3.4.2",
+    "protobuf>=6.31.1",
+    "httpx>=0.28.1",
+    "aio-pika>=9.5.8",
+]
+
+dev-dependencies = [
+    "ruff>=0.5.1",
+    "pytest>=8.2.2",
+    "pytest-cov>=5.0.0",
+    "taskipy>=1.13.0",
+    "pytest-asyncio>=1.3.0",
+    "respx>=0.22.0",
+    "pytest-httpx>=0.35.0",
+]
+
+
+[project.urls]
+Homepage = "https://github.com/irissonnlima/chatgraph"
+Repository = "https://github.com/irissonnlima/chatgraph"
+
+[project.scripts]
+  # chatgraph = "chatgraph.cli:main"
+
+
+[tool.pytest.ini_options]
+pythonpath = "."
+addopts = "-p no:warnings"
+testpaths = ["tests"]
+markers = [
+    "unit: marks tests as unit tests (fast, isolated, uses mocks)",
+    "integration: marks tests as integration tests (slow, requires external services)",
+]
+
+[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 = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "ruff>=0.15.12",
+]