Assistente de Inteligência Artificial para Windows integrado via Atalhos Globais e Bandeja do Sistema.
O gTray é uma ferramenta de produtividade desenvolvida em Python para Windows que permite utilizar modelos de Inteligência Artificial em qualquer aplicativo do seu computador (editores de código, navegadores, suítes office, mensageiros, terminais, etc.).
Basta selecionar um texto em qualquer campo editável e acionar uma combinação de teclas: o gTray captura a seleção, processa a solicitação através da IA configurada e cola a resposta no mesmo local instantaneamente.
- Visão Geral e Fluxo de Funcionamento
- Principais Funcionalidades
- Atalhos e Modos Pré-configurados
- Arquitetura do Projeto
- Pré-requisitos e Instalação
- Guia Rápido de Configuração
- Execução dos Testes Automatizados
- Segurança e Privacidade
- Licença
O gTray atua em segundo plano de forma não intrusiva. Quando um atalho ativo é pressionado, o seguinte fluxo é executado:
[ Qualquer Aplicativo do Windows ]
│
│ 1. Usuário seleciona o texto e pressiona a tecla de atalho
▼
[ handler.py ] ──▶ [ Engineer.py ] (Simula Ctrl+C e exibe "Processando...")
│
│ 2. Resolução da cadeia: Atalho ➔ Modelo ➔ Provedor ➔ API Key & Base URL
▼
[ IA.py ] ───────▶ [ Provedor LLM ] (OpenAI, DeepSeek, Groq, Ollama, etc.)
│
│ 3. Formatação da resposta (Extração de blocos / Comentários se configurado)
▼
[ Engineer.py ] ─▶ Cola o resultado in-place no aplicativo ativo (Simula Ctrl+V)
- Suporte a qualquer serviço compatível com a API padrão OpenAI: OpenAI, DeepSeek, Groq, Anthropic, OpenRouter, Together AI, Mistral, Google Gemini e modelos locais/auto-hospedados via Ollama e vLLM.
- URLs base (
base_url) detectadas automaticamente ou configuráveis manualmente por provedor.
- Cadastre e gerencie múltiplos modelos de linguagem (ex:
gpt-4o-mini,deepseek-chat,llama-3.3-70b-versatile). - Vincule livremente cada modelo ao provedor correspondente.
- Gravação Interativa de Teclas: Pressione o botão Gravar Tecla e acione a combinação desejada (ex:
F8,F9,Ctrl+Alt+T). - Pré-comando / System Prompt Customizado: Defina o papel e as instruções de sistema da IA individualmente para cada atalho (ex: "Apenas reescreva o texto sem explicações" ou "Traduza para inglês").
- Extração de Código (Modo Programação): Remove textos introdutórios e extrai apenas o código cercado por markdown, prefixando o nome do arquivo comentado.
- Caractere de Comentário Configurável: Defina o caractere adequado para cada contexto (
#,//,--, etc.). - Ativação / Desativação Seletiva (Checkbox "Atalho ativo"): Desative temporariamente um atalho sem precisar excluí-lo.
- Hot-Reload em Tempo Real: Alterações salvas na interface têm efeito imediato nas teclas registradas no sistema, sem precisar reiniciar a aplicação.
- Tema escuro (Dark Mode) com paleta profissional e design limpo.
- Sistema de Mensagens Flash temporizadas com feedback visual imediato no rodapé:
- 🟢 Verde: Operações realizadas com sucesso.
- 🟡 Amarelo: Alertas e avisos de preenchimento.
- 🔴 Vermelho: Erros ou confirmações de exclusão.
- Navegação organizada em abas: Atalhos, Modelos, Provedores e Configurações Gerais.
- Minimiza silenciosamente para a bandeja via
pystray. - Menu de contexto rápido com opções de Mostrar UI e Sair.
- Logs com formatação padronizada (
data/hora,nível de logenome do módulo). - Codificação explícita em UTF-8 para compatibilidade total com caracteres em português.
- Rotação automática de arquivos de log (
RotatingFileHandlerde até 10 MB) para preservar o disco. - Listagem detalhada no log ao iniciar a aplicação com todos os atalhos cadastrados, seus modelos, status (Ativo / Inativo) e flags.
| Modo | Tecla Padrão | Modelo Padrão | Descrição |
|---|---|---|---|
| upgrade | F8 / F9 |
gpt-4o-mini |
Melhoria direta de texto: Retorna diretamente o texto selecionado aprimorado, sem rodeios ou saudações. |
| generic | F7+Ctrl+X |
gpt-4o-mini |
Assistente geral: Envia a seleção para o modelo de IA e responde de forma abrangente. |
| python | F10 |
gpt-4o-mini |
Gerador de código Python: Lê referências a arquivos no texto (@@caminho/arquivo@@), gera soluções comentadas e estrutura múltiplos arquivos. |
| creation | F11 |
gpt-4o-mini |
Assistente de projetos: Abre a interface gráfica complementar para geração de estruturas de código e projetos. |
💡 Todos os nomes, teclas, modelos e instruções de sistema acima podem ser alterados ou novos atalhos podem ser criados a qualquer momento pela interface.
gTray/
├── GTray.py # Ponto de entrada e interface gráfica principal (PyQt5)
├── handler.py # Controlador de eventos globais, bandeja do sistema e hotkeys
├── gtray_data_manager.py # Camada de persistência JSON e resolução em cadeia de atalhos
├── ui_theme.py # Design system e folha de estilos QSS (Dark Theme)
│
├── pessoal/ # Módulos centrais de apoio e lógica de negócio
│ ├── Engineer.py # Automação de clipboard e emulação de teclado
│ ├── Escriba.py # Gerenciador estruturado de logs e rotação UTF-8
│ ├── IA.py # Integração agnóstica com clientes LLM compatíveis com OpenAI
│ ├── config_manager.py # Gerenciador de configurações baseado em gtray_data.json
│ └── Decorador.py # Decoradores de telemetria e tempo de resposta
│
├── assets/ # Recursos visuais e arquivos de configuração
│ ├── gtray_data.json # Base de dados única da aplicação (app, atalhos, modelos e provedores)
│ ├── favicon.png # Ícone do aplicativo
│ └── ...
│
├── cmd/ # Scripts auxiliares para execução em segundo plano
│ ├── run.bat # Inicia o gTray em modo background
│ └── run.vbs # Launcher sem janela de console
│
├── logs/ # Diretório de saída dos registros de execução
│ └── application.log # Arquivo de log rotativo gerado em tempo de execução
│
└── teste/ # Suíte completa de testes unitários automatizados
├── test_gtray_ui.py
├── test_gtray_data_manager.py
├── test_system_prompt_integration.py
├── test_escriba.py
└── ...
- Sistema Operacional: Windows 10 ou Windows 11.
- Python: Versão 3.10 ou superior.
- Chave de API: Uma chave de API válida de pelo menos um provedor de IA (OpenAI, DeepSeek, Groq, etc.) ou uma instância local do Ollama ativa.
-
Clone o repositório:
git clone https://github.com/Rox87/gTray.git cd gTray -
Crie e ative um ambiente virtual (recomendado):
python -m venv venv .\venv\Scripts\activate
-
Instale as dependências necessárias:
pip install -r requirements.txt
-
Inicie o gTray:
python GTray.py
- Abra a aplicação e selecione a aba Provedores.
- Clique em + Novo ou selecione um provedor existente (ex:
deepseekouopenai). - Digite o nome do provedor, sua Chave de API e, se aplicável, a Base URL (para provedores conhecidos como DeepSeek e Groq, a URL é preenchida automaticamente).
- Clique em Salvar Provedor.
- Vá para a aba Modelos.
- Digite o nome do modelo (ex:
deepseek-chat,gpt-4o-mini,llama-3.3-70b-versatile). - Selecione o provedor correspondente no menu suspenso.
- Clique em Salvar Modelo.
- Vá para a aba Atalhos.
- Selecione um atalho existente ou clique em + Novo.
- Defina o Nome do Atalho e clique em Gravar Tecla para capturar a combinação do teclado.
- Associe o Modelo de IA cadastrado.
- (Opcional) Preencha a Mensagem do Sistema com as instruções específicas para este atalho.
- (Opcional) Marque Modo Programação caso deseje extração limpa de código.
- Garanta que o checkbox Atalho ativo esteja marcado.
- Clique em Salvar Atalho.
- Clique no botão Iniciar.
- O gTray registrará os atalhos no Windows e se integrará à bandeja do sistema.
- Teste selecionando qualquer texto em um aplicativo e pressionando a tecla cadastrada!
O repositório possui cobertura completa de testes unitários para a interface gráfica, persistência de dados, telemetria, logs e injeção de atalhos.
Para executar toda a suíte de testes:
python -m unittest discover -s testePara executar um módulo de teste específico:
python -m unittest teste.test_gtray_ui
python -m unittest teste.test_gtray_data_manager
python -m unittest teste.test_system_prompt_integration- Armazenamento Local: Todas as chaves de API, credenciais e configurações são salvas exclusivamente de forma local no seu computador no arquivo
assets/gtray_data.json. - Comunicação Direta: As requisições de texto selecionado são enviadas diretamente da sua máquina para o endpoint do provedor de IA escolhido, sem intermediários.
- Controle de Versão: Arquivos contendo chaves locais e registros temporários estão devidamente protegidos no
.gitignore.
Distribuído sob a licença MIT. Consulte o arquivo LICENSE para mais informações.