chatgraph 1.3.0__tar.gz → 1.4.0__tar.gz

{chatgraph-1.3.0 → chatgraph-1.4.0}/.env.example

@@ -36,9 +36,35 @@ ROUTER_API_PASSWORD=f078b1cf-b4c8-11f0-b4fe-0242ac140002
 TEST_USER_ID=6107
 TEST_COMPANY_ID=business-tech
 
+# ====================================
+# Agentes de IA (extra opcional: pip install chatgraph[agent])
+# ====================================
+# OpenRouter (provedor de LLM)
+OPENROUTER_API_KEY=sk-or-...
+# OPENROUTER_BASE_URL=https://openrouter.ai/api/v1  # opcional
+
+# Modelo usado pelo Agent (qualquer modelo do OpenRouter)
+AGENT_MODEL=openai/gpt-4o-mini
+# AGENT_TEMPERATURE=0.7        # opcional (default 0.7)
+# AGENT_MAX_TOKENS=2048        # opcional (default 2048)
+# AGENT_MAX_TOOL_LOOPS=5       # opcional (default 5)
+# AGENT_HISTORY_LIMIT=20       # opcional (default 20)
+# AGENT_SYSTEM_PROMPT_FILE=prompts/personalidade.md  # opcional
+
+# Diagnóstico: loga o AgentContext COMPLETO (inclui dados do usuário
+# na observation). Use apenas em debug local.
+# LOG_AGENT_CONTEXT=1
+
+# Bots com agente: um turno de LLM pode levar vários segundos; com
+# RABBIT_PREFETCH=1 o consumer processa 1 mensagem por vez e a fila
+# serializa. Considere aumentar (com o caveat de ordenação por chat).
+# RABBIT_PREFETCH=4
+
 # Log Publisher (RabbitMQ - opcional)
 # Defina LOG_RABBIT_QUEUE para ativar o envio de logs de erro para fila RabbitMQ.
 # O exchange e routing key padrão seguem o padrão do Go: exchange = vhost, routing key = chatbot.{queue}
+# Com RABBIT_VHOST='/' não existe exchange homônima: cai na exchange
+# default do AMQP e a routing key passa a ser o próprio nome da fila.
 LOG_RABBIT_QUEUE=logs
 LOG_RABBIT_EXCHANGE=chatbot-hml
 # LOG_RABBIT_ROUTING_KEY=chatbot.logs  # opcional: default = chatbot.{LOG_RABBIT_QUEUE}

{chatgraph-1.3.0 → chatgraph-1.4.0}/.github/skills/chatgraph-framework/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: chatgraph-framework
-description: "Use when: implementing a chatbot with chatgraph, creating routes with @app.route or @router.route, using UserCall, Route, Message, File, Button, EndChatResponse, RedirectResponse, TransferToMenu, TransferToHuman, BackgroundTask, setting up ChatbotApp, ChatbotRouter, include_router, configuring RabbitMQ consumer, adding per-user file logging with UserLoggerManager, integrating chatgraph in a new Python project."
+description: "Use when: implementing a chatbot with chatgraph, creating routes with @app.route or @router.route, using UserCall, Route, Message, File, Button, EndChatResponse, RedirectResponse, TransferToMenu, BackgroundTask, setting up ChatbotApp, ChatbotRouter, include_router, configuring RabbitMQ consumer, adding per-user file logging with UserLoggerManager, integrating chatgraph in a new Python project."
 argument-hint: "Descreva o fluxo de rotas que deseja implementar (opcional)"
 ---
 
@@ -200,22 +200,28 @@ return RedirectResponse('choice_start')
 return Route('aguardando_resposta')
 ```
 
-### `EndChatResponse(end_chat_id, end_chat_name?, observations?)` — Encerra o chat
+### `EndChatResponse(end_chat_id, end_chat_name?, observations?)` — Encerra o chat OU transfere para humano
+No chatbot-router, encerrar o atendimento e transferir para um atendente humano são a
+**mesma operação**: uma tabulação de encerramento com ID/nome próprio. Não existe um tipo de
+retorno separado para "transferir para humano" — use `EndChatResponse` com a end action de
+atendimento humano configurada no router.
 ```python
 return EndChatResponse('voll_ended')
 return EndChatResponse('', end_chat_name='Encerrado pelo usuário', observations='motivo')
+return EndChatResponse('ea_atendimento_humano')  # transferência para humano é um end_chat_id específico
 ```
 
-### `TransferToMenu(menu, user_message, route?)` — Transfere para outro menu
+### `TransferToMenu(menu, user_message, route?)` — Transfere para OUTRO BOT (menu)
+`TransferToMenu` é só bot→bot (outro menu/robô configurado no router). **Nunca** use para chegar a
+um atendente humano — isso é `EndChatResponse` (ver acima). Confundir os dois faz o handler prometer
+uma transferência que o router rejeita, porque o "menu" de atendimento humano não existe como menu.
 ```python
 return TransferToMenu('p0299_suporte_ti', 'Transferindo...')
 return TransferToMenu('p0299_suporte_ti', 'Transferindo...', route='etapa_inicial')  # inicia em rota específica
 ```
 
-### `TransferToHuman(campaign_id?, campaign_name?, observations?)` — Transfere para humano
-```python
-return TransferToHuman(campaign_name='Suporte N2')
-```
+> `TransferToHuman` (`chatgraph.types.end_types`) é **obsoleto**: não tem efeito no pipeline HTTP
+> (só existia no caminho gRPC legado). Não é mais exportado por `chatgraph/__init__.py`.
 
 ### `BackgroundTask(async_func, *args, **kwargs)` — Executa tarefa em background e encadeia o retorno
 ```python
@@ -526,3 +532,191 @@ async def aguardar_escolha(usercall: UserCall):
 
 app.start()
 ```
+
+## 14. Agentes de IA (`chatgraph.agent`)
+
+Requer o extra opcional: `pip install chatgraph[agent]` (pydantic>=2).
+Port do protocolo single-agent do `chatgraph-go`: uma chamada de LLM
+decide navegação E escreve a resposta, com tool calling declarativo.
+
+### Conceitos
+
+- **`Agent`**: configura LLM client, modelo, prompt de personalidade,
+  tools locais, menus, end actions e o modelo pydantic da observation.
+- **`description` da rota é o prompt de comportamento** daquela rota —
+  injetada no system prompt do protocolo. `ai_visible=True` expõe a
+  rota ao roteamento do agente.
+- **Tools locais** (`@agent.tool`): o modelo as chama via ação
+  `call_tool`; o resultado entra na observation sob `result_key` e o
+  agente decide de novo (até `max_tool_loops`, default 5).
+- **Ações do protocolo** mapeiam nos tipos de retorno existentes:
+  `send_message`→`Message`, `next_route`→`Route`,
+  `redirect`→`RedirectResponse`, `set_observation`→merge aditivo na
+  observation.
+- **`end_session`→`EndChatResponse`** cobre TANTO encerrar o
+  atendimento QUANTO transferir para um atendente humano — no
+  chatbot-router as duas são a mesma operação (uma tabulação de
+  encerramento). Seleção por **name** do `EndActionInfo` configurado
+  em `Agent(end_actions=[...])`.
+- **`transfer_menu`→`TransferToMenu`** é só bot→bot (seleção por
+  **name** do `MenuInfo`). **Nunca** configure um menu para representar
+  "atendimento humano" — isso pertence a `end_actions`/`end_session`.
+  Confundir os dois faz o agente prometer uma transferência que o
+  router rejeita (o "menu" de humano não existe como menu).
+- **Histórico**: com `history_store` configurado no `ChatbotApp`, o
+  agente recebe a conversa (janela `history_limit`, default 20) com o
+  pareamento assistant/tool preservado.
+- **Ação inválida do modelo** (menu/end_action_id que não existe na
+  lista configurada) dispara um re-prompt corretivo automático (1
+  tentativa por turno, via `AgentContext.last_action_error`); se a
+  correção também falhar, o turno termina com uma mensagem neutra em
+  vez de silêncio ou uma promessa que não vai se cumprir.
+
+### Env vars
+
+```
+OPENROUTER_API_KEY=sk-or-...   # obrigatória p/ OpenRouterClient
+OPENROUTER_BASE_URL=...        # opcional
+AGENT_MODEL=openai/gpt-4o-mini # obrigatória p/ Agent.load_dotenv
+AGENT_TEMPERATURE / AGENT_MAX_TOKENS / AGENT_MAX_TOOL_LOOPS /
+AGENT_HISTORY_LIMIT / AGENT_SYSTEM_PROMPT_FILE   # opcionais
+LOG_AGENT_CONTEXT=1            # debug: loga contexto completo (PII!)
+```
+
+### Exemplo
+
+```python
+from pydantic import BaseModel
+from chatgraph import (
+    Agent, ChatbotApp, EndActionInfo, MenuInfo, OpenRouterClient, Route,
+    UserCall,
+)
+from chatgraph.history.store import MemoryHistoryStore
+
+
+class PedidoObs(BaseModel):
+    cpf: str = ''
+    numero_pedido: str = ''
+
+
+agent = Agent(
+    llm_client=OpenRouterClient.load_dotenv(),
+    model='openai/gpt-4o-mini',
+    system_prompt='Você é o assistente da loja. Responda em pt-BR.',
+    observation_model=PedidoObs,
+    # transfer_menu: só bot→bot (outro robô configurado no router).
+    menus=[MenuInfo(name='suporte_ti', description='Bot de suporte técnico.')],
+    # end_session: encerrar OU transferir para atendente humano — NÃO
+    # é um menu. "id" é opcional (o seletor por name já basta).
+    end_actions=[
+        EndActionInfo(name='humano', description='Atendente humano.'),
+        EndActionInfo(name='resolvido', description='Atendimento concluído.'),
+    ],
+)
+
+# Opcional, no boot do bot (fora do caminho de mensagem): confirma que
+# os menus/end_actions acima existem de verdade no chatbot-router,
+# falhando cedo em vez de só na primeira transferência de um usuário.
+# await agent.validate_config(router_client)
+
+
+@agent.tool(
+    description='Consulta pedido por CPF e número.',
+    parameters={
+        'type': 'object',
+        'properties': {
+            'cpf': {'type': 'string'},
+            'numero_pedido': {'type': 'string'},
+        },
+        'required': ['cpf', 'numero_pedido'],
+    },
+)
+async def consultar_pedido(cpf: str, numero_pedido: str) -> dict:
+    return {'status': 'Entregue'}
+
+
+app = ChatbotApp(history_store=MemoryHistoryStore())
+
+
+@app.route(
+    'buscar_pedido',
+    description="Order lookup — collect cpf and numero_pedido. Call "
+        "consultar_pedido with result_key='dados_pedido', then "
+        'redirect to exibir_pedido.',
+    ai_visible=True,
+)
+async def buscar_pedido(call: UserCall, route: Route):
+    return await agent.execute(call, route)
+```
+
+### Regras e cuidados
+
+- Handlers com agente devem ser `async` (sync roda em thread e não
+  pode `await`).
+- Um turno de agente pode levar vários segundos (até `max_tool_loops`
+  chamadas de LLM). Com `RABBIT_PREFETCH=1` a fila serializa —
+  considere aumentar o prefetch para bots com agente.
+- Redirects têm limite global (`MAX_REDIRECT_DEPTH=5` em
+  `chatbot_model.py`): um agente que redirecionar em ciclo é
+  interrompido com erro no log.
+- `await agent.validate_config(router_client)` é opcional e não é
+  chamado automaticamente — confere no boot se os `menus`/`end_actions`
+  configurados existem de verdade no chatbot-router. Chame fora do
+  caminho de mensagem (uma vez, ao subir o bot).
+- Proteções do executor (port do Go): dedup de tool por `result_key`,
+  máx. 2 tentativas por tool com degradação, self-redirect vira
+  "none", alvo de rota desconhecido vira "none" com warning, redirect
+  é silencioso (a rota destino responde), transfer inválido falha
+  ANTES de qualquer side effect.
+- Exemplo completo: `examples/agents_bot.py`.
+
+## 15. Geração de conteúdo desacoplada (`generate_content`)
+
+Requer o mesmo extra opcional: `pip install chatgraph[agent]`.
+
+**Para dados internos do bot, não para turno de chat.** Caso de uso:
+o bot tem acesso a uma base interna (ex.: uma consulta a banco) e
+precisa que a IA analise esse conteúdo e devolva um insight — não é
+uma mensagem de cliente, não tem rota, não tem menu, não passa por
+`UserCall`/`Route`/`AgentContext`. `generate_content` é uma função
+solta, independente de `Agent`: funciona com qualquer `LLMClient`
+(inclusive `OpenRouterClient` já existente), sem exigir menus, tools,
+observation_model ou histórico de conversa configurados.
+
+```python
+import json
+
+from pydantic import BaseModel
+from chatgraph import OpenRouterClient, generate_content
+
+
+class VendasInsight(BaseModel):
+    resumo: str
+    tendencia: str
+    produtos_em_alerta: list[str] = []
+
+
+async def gerar_relatorio(dados_do_banco: list[dict]) -> VendasInsight | None:
+    result = await generate_content(
+        OpenRouterClient.load_dotenv(),
+        model='openai/gpt-4o-mini',
+        content=json.dumps(dados_do_banco, ensure_ascii=False),
+        system_prompt='Você é um analista de vendas. Responda em pt-BR.',
+        response_model=VendasInsight,  # opcional; sem ele, result.data é None
+    )
+    return result.data  # ou result.text, se response_model não foi passado
+```
+
+- **`content`** é uma string já serializada pelo chamador (JSON, CSV,
+  texto) — a função não sabe de onde o dado vem.
+- **`response_model`** opcional (mesmo padrão do `observation_model` do
+  `Agent`): com ele, o Structured Output usa o schema fechado do
+  modelo e `result.data` vem parseado; sem ele, só `result.text`.
+- **`history`** opcional para follow-up sobre o mesmo conteúdo (ex.:
+  uma segunda pergunta sobre o mesmo relatório) — sem `HistoryStore`,
+  cada chamada é isolada por padrão.
+- **O retorno não passa pelo pipeline** (`Message`/`Route`/etc.): é
+  consumido diretamente por quem chamou — envie via `usercall.send(...)`
+  se estiver dentro de um handler, ou grave em log/banco se for um job
+  agendado sem turno de chat nenhum.
+- Exemplo completo: `examples/content_insight.py`.

{chatgraph-1.3.0 → chatgraph-1.4.0}/.gitignore

@@ -184,4 +184,8 @@ ROADMAP.md
 *.pdf
 *jpg
 *.jpeg
-*.png
+*.png
+
+# credenciais e configuração local (não versionar)
+kubeconfig
+.claude/

chatgraph-1.4.0/CLAUDE.md

@@ -0,0 +1,130 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+`chatgraph` é uma **biblioteca** (não uma aplicação) para construir chatbots orientados a rotas.
+Este arquivo trata de desenvolver a biblioteca. Para *usá-la* em um bot, a referência de API
+está em `.github/skills/chatgraph-framework/SKILL.md`.
+
+## Comandos
+
+O ambiente real de trabalho é o `.venv/` do repositório. `taskipy` **não** está instalado nele,
+então as tasks `poetry run task test|lint|format` documentadas no README e no PROGRESS.md não
+funcionam — use os binários diretamente:
+
+```bash
+.venv/bin/python -m pytest tests/unit -q            # suíte rápida (500 testes, ~20s)
+.venv/bin/python -m pytest tests/unit/test_agent_executor.py -v          # um arquivo
+.venv/bin/python -m pytest tests/unit/test_agent_executor.py::TestNome::test_caso -v   # um teste
+.venv/bin/python -m pytest -m integration -v        # integração (auto-skip sem env vars)
+.venv/bin/ruff check chatgraph                      # lint
+.venv/bin/ruff format .                             # format (aspas simples, linha 79)
+```
+
+`pytest-asyncio` roda em modo strict (sem `asyncio_mode` no `pyproject.toml`): todo teste async
+precisa de `@pytest.mark.asyncio` explícito.
+
+**O lint não está limpo e isso é pré-existente.** Em 2026-08-14, `ruff check .` reportava 775
+erros (174 em `chatgraph/`, 590 em `tests/`), dominados por `PLR6301` (no-self-use nos testes) e
+`E501`; `ruff format --check` acusava 7 arquivos. Não trate esses erros como regressão da sua
+mudança, e não faça um mutirão de correção junto com uma feature — verifique apenas os arquivos
+que você tocou.
+
+Testes de integração leem `ROUTER_API_BASE_URL` (+ `_USERNAME`/`_PASSWORD`) e são **pulados
+silenciosamente** se ela não estiver definida — um "tudo verde" pode significar "nada rodou".
+A lista completa de env vars está em `.env.example`.
+
+## Arquitetura
+
+Pipeline de um turno:
+
+```
+RabbitMQ → MessageConsumer → ChatbotApp.process_message → default_functions (regex)
+        → guard (auth_level) → handler da rota → __process_func_response → UserCall → RouterHTTPClient
+```
+
+Pontos que não se deduzem lendo um arquivo só:
+
+- **O despacho usa apenas o último segmento da rota.** `process_message` calcula
+  `route.split('.')[-1]` e busca essa chave em `self.__routes`, enquanto os decorators registram
+  o nome literal passado. Ou seja: registre handlers com o **nome folha** (`@app.route('choice')`),
+  nunca com o caminho pontuado (`'start.choice'` fica inalcançável). O caminho pontuado é a
+  *posição* do usuário, mantida no backend — não a chave de registro. O README ainda mostra o
+  formato antigo com ponto; ele está desatualizado.
+- **O retorno do handler é a API de efeitos.** `__process_func_response` faz dispatch por tipo:
+  `Message`/`File` envia, `Route` avança e espera nova mensagem, `RedirectResponse` reexecuta o
+  pipeline no mesmo turno, `EndChatResponse`/`TransferToMenu` encerram, `BackgroundTask` roda e
+  encadeia o próprio retorno, `list`/`tuple` processa em sequência. Retornar `None`/falsy
+  **duplica o último segmento** da rota atual (mecanismo de "fica no nó"); `Route.get_previous()`
+  desduplica segmentos repetidos ao voltar. Adicionar um novo tipo de resposta = adicionar um
+  ramo aqui, e não lógica no handler.
+- **`MAX_REDIRECT_DEPTH = 5`** (`bot/chatbot_model.py`) corta cadeias de `RedirectResponse` no
+  mesmo turno. Sem isso um handler (ou agente de IA) em ciclo recursa até estourar a pilha e
+  travar o consumer. `MESSAGE_IN` só é gravado no histórico em `_redirect_depth == 0`, senão a
+  mesma mensagem entraria várias vezes com rotas diferentes.
+- **Handlers podem ser sync ou async.** Sync roda em `run_in_executor`, então um handler sync
+  **não pode** `await` — handlers com agente de IA precisam ser `async`.
+- **Injeção de parâmetros é por anotação de tipo**, não por nome: `build_route_entry`
+  (`bot/route_registry.py`) mapeia `{tipo: nome_do_param}`. Dois parâmetros com a mesma anotação
+  colidem (o último vence) — limitação conhecida e documentada no módulo.
+- **Não existe estado local.** Todo estado de usuário/sessão vive na API externa via
+  `RouterHTTPClient`; `Container.get_router_client()` é o singleton (lê `ROUTER_URL`/`ROUTER_TOKEN`).
+  Não introduza cache nem banco local sem decisão explícita.
+- **Histórico e log de erro são fire-and-forget.** Os hooks de `HistoryStore` e o `LogPublisher`
+  capturam `BaseException` e só emitem warning — observabilidade nunca derruba o turno. Se você
+  adicionar um hook, mantenha esse contrato. `history_store=None` e `LogPublisher` sem
+  `LOG_RABBIT_QUEUE` são no-ops válidos (retrocompatibilidade).
+
+### `chatgraph/agent/` — extra opcional
+
+Port fiel do protocolo **single-agent** do projeto irmão `chatgraph-go` (uma chamada de LLM decide
+navegação *e* escreve a resposta). Regras que orientam mudanças aqui:
+
+- `pydantic` é dependência **só** deste módulo (extra `chatgraph[agent]`). Os símbolos de agente
+  são exportados de forma lazy no `chatgraph/__init__.py` via `__getattr__` (PEP 562), para que
+  quem não instalou o extra não pague o custo nem quebre. Ao adicionar um export de agente,
+  registre-o em `_AGENT_EXPORTS` **e** em `__all__` (o `# ruff: noqa: F822` no topo existe por isso).
+- O executor **não executa efeitos**: ele devolve uma lista dos tipos de retorno já existentes do
+  framework, que o pipeline processa sem alteração. Preserve essa separação.
+- Paridade com o Go é o critério de projeto: `prompts.py` e `schema.py` são ports literais.
+  Divergências devem ser conscientes e registradas (a atual: `transfer_menu` seleciona menu por
+  **name**, porque o client Python não transfere por queue).
+- Proteções do turno que existem por motivo específico, não as remova sem substituto: dedup de
+  tool por `result_key`, `MAX_ATTEMPTS_PER_TOOL = 2`, guard de self-redirect, alvo de rota
+  desconhecido vira "none", transfer inválido falha **antes** de qualquer side effect.
+
+## Convenções
+
+- **Commits em português do Brasil**, Conventional Commits (`feat`, `fix`, `chore`, `refactor`,
+  `test`, `docs`, `style`, `perf`) — ex.: `feat(agent): adiciona guardrails de saída`.
+- **Logs sempre via `UserLoggerManager`**, nunca `print`: dentro de rota use `usercall.logger`
+  (vai para `chatgraph_logs/{user_id}_{company_id}.log`); fora de rota,
+  `UserLoggerManager.get_system_logger()`.
+- **Injeção de dependência manual** por construtor; sem framework de DI, sem prefixo `I` em
+  interfaces. Contratos plugáveis usam `typing.Protocol` (ex.: `HistoryStore`), não ABC.
+- **Docstrings e comentários em português**, seguindo o código existente. Comentário bom aqui
+  explica *por que* a proteção existe (ver `MAX_REDIRECT_DEPTH`), não o que a linha faz.
+- Testes agrupados em classes por unidade sob teste (`Test<Nome>`), fixtures em `conftest.py`,
+  HTTP mockado com `respx`, marcadores `@pytest.mark.unit` / `@pytest.mark.integration`.
+
+## Notas do repositório
+
+- **A CLI não está instalada.** `[project.scripts]` no `pyproject.toml` está comentado, então o
+  comando `chatgraph` documentado no README não existe; `chatgraph/cli/` só roda via
+  `python -m` / import direto. Também é o módulo mais antigo (usa gRPC, imports fora do padrão).
+- `[project] dev-dependencies` no `pyproject.toml` é um campo **não padrão** e ignorado pelos
+  instaladores; as dev deps efetivas estão em `[dependency-groups] dev`. Existem `poetry.lock` e
+  `uv.lock` no repo — confirme qual gerenciador está sendo usado antes de mexer em dependências.
+- Não há CI configurado (`.github/workflows/` não existe): a validação antes de commitar é manual.
+- `chatgraph/pb/` é **gerado** a partir do protobuf — não edite à mão.
+
+## Contexto adicional
+
+- `PROGRESS.md` — linha do tempo, decisões técnicas com justificativa e backlog priorizado.
+  Mantenha-o atualizado ao concluir uma área.
+- `docs/gaps-go-to-python.md` e `docs/gaps-python-to-go.md` — paridade com o `chatgraph-go`; é a
+  fonte de verdade sobre o que falta portar (timeout por rota, route triggers, `validate_routes`,
+  helper de teste tipo `EngineTester`).
+- `.github/copilot-instructions.md` define um fluxo de agentes (Architect → Developer →
+  CodeReviewer, definidos em `.github/agents/`) usado pelo Copilot; não é carregado pelo Claude
+  Code, mas as convenções de código e commit dele são as mesmas resumidas acima.

{chatgraph-1.3.0 → chatgraph-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: chatgraph
-Version: 1.3.0
+Version: 1.4.0
 Summary: A user-friendly chatbot library
 Project-URL: Homepage, https://github.com/irissonnlima/chatgraph
 Project-URL: Repository, https://github.com/irissonnlima/chatgraph
@@ -20,6 +20,8 @@ Requires-Dist: protobuf>=6.31.1
 Requires-Dist: python-dotenv>=1.0.1
 Requires-Dist: rich>=13.8.1
 Requires-Dist: typer>=0.12.5
+Provides-Extra: agent
+Requires-Dist: pydantic>=2; extra == 'agent'
 Description-Content-Type: text/markdown
 
 ### **README - ChatGraph**