🦅 IcarusBot

Bot assíncrono para Telegram desenvolvido em Python, com uma interface interativa para consultar informações em tempo real, organizar tarefas e conversar com um modelo de inteligência artificial. Esta é a versão v2.1.1 (Patch Release), com uma suíte completa de testes automatizados para os serviços do sistema.

Funcionalidades

• Consulta de clima por cidade: o usuário escolhe a opção de clima no menu e o bot utiliza automaticamente a cidade padrão salva no perfil via /setcidade, sem solicitar entrada manual.
• Painel de cotações expandido: o antigo módulo de dólar foi atualizado para o money.py, um painel financeiro completo que exibe Dólar (USD), Euro (EUR) e Bitcoin (BTC) em uma única consulta otimizada à AwesomeAPI, com valores de compra, venda, máxima e mínima.
• Notícias em tempo real: utiliza Playwright com Chromium em modo headless para acessar o G1, coletar as cinco primeiras manchetes e retornar os respectivos links.
• Bate-papo inteligente: integra a API do Google Gemini por meio do Google GenAI SDK, mantendo uma sessão de chat por usuário. Falhas HTTP 503 são tratadas com novas tentativas e espera progressiva (retry/backoff).
• Processamento de mensagens de voz: interpreta áudios por meio da API multimodal do Google Gemini, usando a mesma sessão de chat e o mesmo contexto do usuário.
• Gestor de tarefas (To-Do List): organiza tarefas por chat_id, permitindo adicionar, alternar entre concluída e pendente e remover tarefas, com persistência local em JSON.
• Menu interativo reformulado: oferece navegação aprimorada com botões inline, navegação por estados e o botão Voltar ao Menu para facilitar o uso.
• Persistência relacional com SQLite: cadastra e gerencia perfis em src/database/users.db, usando o chat_id como chave primária.
• Gerenciamento de perfil: permite consultar e personalizar os dados do usuário com /perfil, /setcidade, /setmoeda e /settelefone.
• Personalização dinâmica da IA: o Gemini recebe as preferências persistidas do usuário (nome, cidade padrão e moeda) nas instruções do sistema, mantendo as respostas contextualizadas sem reapresentação.
• Arquitetura modular: os handlers foram separados por domínio em src/handlers/ e são registrados centralmente por __init__.py.
• Alertas e triggers: um worker assíncrono envia diariamente o resumo matinal de clima e finanças; o envio pode ser validado manualmente com /teste_alerta.
• Observabilidade e logging estruturado: registra eventos com o módulo nativo logging, salva os registros em logs/icarusbot.log e reduz a verbosidade de bibliotecas de terceiros.

Changelog v2.1.1 🚀

• Suíte completa de testes automatizados: implementação de testes unitários e de integração com pytest e pytest-asyncio, cobrindo 100% dos serviços em src/services/:
  • test_db.py: validação do fluxo CRUD e do mapeamento de perfis no SQLite.
  • test_todo.py: teste de integração do ciclo de vida de tarefas (adicionar, alternar status e excluir).
  • test_weather.py: validação do contrato do serviço de previsão do tempo.
  • test_money.py: teste de formatação e integridade do resumo financeiro.
  • test_news.py: validação assíncrona da busca e do parsing do feed de notícias.
  • test_gemini.py: teste de inicialização e injeção de contexto/System Instructions do Gemini SDK.
  • test_triggers.py: teste de montagem e disparo do resumo matinal em segundo plano com mocks de bot.

Changelog v2.1 🚀

• Observabilidade e logging estruturado: substituição dos prints por logs estruturados usando o módulo nativo logging do Python, centralizado em src/services/logger.py.
• Persistência dos logs: criação automática da pasta logs/ e salvamento dos registros em logs/icarusbot.log, com supressão de logs ruidosos de bibliotecas de terceiros.
• Clima integrado ao perfil: a opção opt_1 do menu consulta get_user no SQLite para recuperar a cidade padrão definida via /setcidade e retorna a previsão imediatamente, sem pedir uma nova entrada.

Changelog v2.0 🚀

• Persistência relacional com SQLite: cadastro e gestão de perfis de usuário em users.db, com chat_id como chave primária.
• Gerenciamento de perfil: novos comandos /perfil, /setcidade, /setmoeda e /settelefone.
• Personalização dinâmica da IA: as preferências salvas são incorporadas às System Instructions do Gemini.
• Arquitetura modular: handlers de comandos, menu, tarefas e IA separados em src/handlers/.
• Sistema de alertas: agendador em segundo plano em src/services/triggers.py, com resumo diário de clima e finanças e comando /teste_alerta.

Tecnologias utilizadas

Tecnologia	Uso
Python 3	Linguagem principal e execução assíncrona
pyTelegramBotAPI (AsyncTeleBot)	Integração com a API do Telegram
Playwright	Automação do Chromium e scraping das notícias do G1
Google GenAI SDK (Gemini API)	Conversas multimodais com o Gemini (texto e áudio), mantendo sessões por usuário
python-dotenv	Carregamento das variáveis do arquivo .env
requests	Requisições HTTP para serviços externos, como a AwesomeAPI
PyOWM	Consulta dos dados meteorológicos
SQLite	Persistência relacional dos perfis de usuário por chat_id
JSON local	Persistência da To-Do List por chat_id

As versões exatas das dependências estão registradas em requirements.txt.

Estrutura do projeto

Na v2.1.1, o registro dos handlers continua centralizado em src/handlers/__init__.py, enquanto os teclados, serviços, testes, logs e dados persistidos estão organizados em seus respectivos módulos.

.
├── main.py                         # Inicialização do bot e do worker de alertas
├── requirements.txt                # Dependências Python fixadas
├── .env.example                    # Modelo de configuração local
├── .gitignore
├── logs/                           # Logs gerados em execução (ignorada pelo Git)
│   └── icarusbot.log              # Arquivo de log estruturado
├── tests/                          # Suíte de testes unitários e de integração
│   ├── test_db.py                  # CRUD e mapeamento de perfis no SQLite
│   ├── test_gemini.py              # Inicialização e contexto do Gemini SDK
│   ├── test_money.py               # Formatação e integridade financeira
│   ├── test_news.py                # Busca e parsing assíncrono de notícias
│   ├── test_todo.py                # Ciclo de vida das tarefas
│   ├── test_triggers.py            # Resumo matinal em segundo plano
│   └── test_weather.py             # Contrato do serviço meteorológico
└── src/
    ├── __init__.py
    ├── database/
    │   ├── users.db                # Perfis de usuário persistidos no SQLite
    │   └── todo.json               # Persistência local das tarefas por chat_id
    ├── handlers/
    │   ├── __init__.py             # Registro central dos handlers
    │   ├── ai_handler.py           # Mensagens de texto e voz para o Gemini
    │   ├── command_handler.py      # Comandos, perfis e alertas de teste
    │   ├── menu_handler.py         # Menu interativo e consulta de clima
    │   └── todo_handler.py         # Comandos e callbacks da To-Do List
    ├── keyboards/
    │   ├── __init__.py
    │   └── menu.py                 # Menus inline e botões de navegação
    └── services/
        ├── __init__.py
        ├── db.py                   # Cadastro e consulta de perfis no SQLite
        ├── gemini.py               # Sessão Gemini e retry para erros 503
        ├── logger.py               # Configuração do logging estruturado
        ├── money.py                # Painel USD, EUR e BTC via AwesomeAPI
        ├── news.py                 # Scraping assíncrono do G1 com Playwright
        ├── todo.py                 # Operações da To-Do List em JSON
        ├── triggers.py             # Agendador e resumo matinal diário
        └── weather.py              # Consulta meteorológica por cidade

Pré-requisitos

• Python 3 instalado (recomenda-se Python 3.10 ou superior).
• Um bot criado no BotFather, com o respectivo token.
• Uma chave de API do Google AI Studio para usar o Gemini.
• Conexão com a internet para acessar o Telegram, a AwesomeAPI, o G1 e a API do Gemini.

Instalação e execução

1. Clone o repositório

git clone <URL_DO_REPOSITORIO>
cd bot-telegram

2. Crie e ative um ambiente virtual

No Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

No Windows usando cmd:

python -m venv .venv
.venv\Scripts\activate.bat

No Linux ou macOS:

python3 -m venv .venv
source .venv/bin/activate

3. Instale as dependências

pip install -r requirements.txt

4. Instale o navegador do Playwright

O scraping de notícias depende do Chromium em modo headless:

playwright install chromium

5. Configure as variáveis de ambiente

Copie o arquivo de exemplo para .env:

Copy-Item .env.example .env

No Linux ou macOS:

cp .env.example .env

Edite o .env e preencha os valores reais:

TELEGRAM_BOT_TOKEN=seu_token_do_botfather
GEMINI_API_KEY=sua_chave_da_api_do_google

Importante: nunca versione nem compartilhe o arquivo .env. As credenciais devem permanecer somente no ambiente local ou no gerenciador de secrets da plataforma de hospedagem.

6. Execute o bot

Com o ambiente virtual ativado:

python main.py

Abra a conversa com o bot no Telegram e use /start ou /help. Em seguida, use /menu para acessar clima, painel de cotações e notícias. Mensagens de texto ou voz que não estiverem em um fluxo interativo são encaminhadas ao Gemini.

Testes automatizados

Instale as dependências de testes e execute a suíte completa em modo verboso:

# Instalar dependências de testes
pip install pytest pytest-asyncio

# Executar a suíte de testes em modo verboso
pytest -v

Comandos disponíveis

Comando	Descrição
/start	Apresenta o bot
/help	Exibe a mensagem de ajuda
/menu	Abre o menu de funcionalidades
/perfil	Exibe os dados do perfil persistido
/setcidade <cidade>	Define a cidade padrão do usuário
/setmoeda <código>	Define a moeda preferida (por exemplo, BRL ou USD)
/settelefone <número>	Salva ou atualiza o telefone do usuário
/teste_alerta	Envia imediatamente um resumo matinal de teste
/task <descrição> ou /tarefa <descrição>	Adiciona uma tarefa ao chat
/tasks ou /tarefas	Exibe a lista interativa de tarefas

Variáveis de ambiente

O arquivo .env.example contém a estrutura mínima necessária:

Variável	Obrigatória	Descrição
TELEGRAM_BOT_TOKEN	Sim	Token do bot obtido no BotFather
GEMINI_API_KEY	Sim	Chave para autenticação na Gemini API

Não coloque chaves, tokens ou outros segredos diretamente no código-fonte. O arquivo .env já está ignorado pelo Git.

Observações da v2.1.1

• A disponibilidade e o formato das notícias dependem do HTML atual do G1 e podem exigir ajustes caso o site mude seus seletores.
• As cotações, as notícias e a interpretação de áudios dependem de serviços externos e podem sofrer indisponibilidade ou limitação temporária.
• As sessões ativas do Gemini e os estados dos menus são mantidos em memória; reiniciar o processo encerra essas sessões, mas não remove os perfis do SQLite.
• O cadastro de perfil é criado automaticamente no primeiro uso de /start e fica persistido em src/database/users.db.
• A opção de clima do menu usa a cidade padrão do perfil; configure-a antes com /setcidade <cidade>.
• As tarefas são persistidas localmente em src/database/todo.json e permanecem associadas ao chat_id.
• Os logs são gravados em logs/icarusbot.log. A pasta logs/ é ignorada pelo Git e deve ser criada automaticamente durante a execução.
• O resumo matinal é disparado pelo worker em segundo plano às 08:00, no horário local da máquina que executa o bot.
• O bot utiliza polling, portanto o processo precisa permanecer em execução para receber atualizações.

Próximos passos

• Handlers Separar os handlers por domínio em src/handlers/.
• Testes Automatizados Cobertura unitária e de integração dos serviços com pytest e pytest-asyncio.
• Perfis de usuário Persistir preferências e dados de cadastro em SQLite.
• Logging Adicionar observabilidade, logging estruturado e uma estratégia de deploy.
• Sistema de Cadastro e Autenticação: Persistência e gestão de perfis de utilizadores para personalizar a experiência.
• Sistema de Alertas e Monitorização (Triggers): Resumo matinal diário com clima e finanças, além do comando /teste_alerta.
• Gestor de Tarefas (To-Do List por chat_id): Organização de tarefas individuais vinculadas ao ID de cada chat no Telegram.
• Contentorização com Docker: Criação do Dockerfile e docker-compose.yml para simplificar a implantação e padronizar o ambiente de execução.
• Deploy em VPS Linux com Webhooks & API: Substituição do modo polling por uma arquitetura assíncrona orientada a eventos, configurando Webhooks no Telegram integrados a um backend em Flask ou FastAPI.
• Expansão de Ferramentas da IA: Utilização de Function Calling no Gemini para permitir que o bot execute comandos do sistema e consultas em APIs externas de forma autónoma.

Licença

MIT License