Assistente IA (Background)

Assistente multiplataforma que captura uma imagem (print da questão), envia ao Google Gemini e devolve a resposta em notificação nativa. Roda em segundo plano com atalho global Ctrl+Alt+Q.

Há dois modos de configuração:

• Distribuição (padrão): a chave não vai no executável — na primeira execução uma janela pede chave e modelo e salva em settings.json no diretório do usuário.
• Uso pessoal (opcional): build com build_personal.bat embute um .env local no .exe e o programa inicia direto em background, sem tela inicial.

Arquitetura

Módulo	Responsabilidade
main.py	Entrada: logging, primeiro acesso, inicia background
ui_setup.py	Janela tkinter para chave da API
config.py	settings.json do usuário ou .env embutido no exe (uso pessoal)
background.py	Atalho global + fluxo clipboard → Gemini
gemini_solver.py	Google Gen AI SDK (google.genai)
clipboard_img.py	Clipboard Wayland/X11/Windows + fallback Pictures
hotkeys.py	keyboard (Windows) / pynput (Linux)
notifications.py	Notificações via plyer

Onde a configuração é salva

SO	Diretório
Windows	%APPDATA%\AssistenteIA\settings.json
Linux	~/.config/AssistenteIA/settings.json

Logs: %APPDATA%\AssistenteIA\logs\ (Windows) ou ~/.local/share/AssistenteIA/logs/ (Linux).

Requisitos

• Python 3.10+
• Chave em Google AI Studio

Linux (dependências de sistema)

# Manjaro/Arch
sudo pacman -S wl-clipboard libnotify python-tkinter

# Debian/Ubuntu
sudo apt install wl-clipboard xclip libnotify-bin python3-tk

• Wayland: wl-clipboard (wl-paste)
• X11: xclip (alternativa)
• Notificações: libnotify
• Primeira configuração: tkinter
• KDE Print Screen: costuma salvar só em ~/Pictures — o app usa o screenshot mais recente (últimos 120 s) automaticamente

Windows

• Notificações: pop-up discreto no canto inferior esquerdo (não usa o toast do sistema, que não permite posição fixa)
• Se o atalho não registrar, execute como Administrador uma vez

Instalação e execução local

Windows (rápido)

cd QuickResponse
setup_windows.bat
notepad .env
run_windows.bat

Use py se python não estiver no PATH (instalador oficial em python.org).

Linux / manual

cd QuickResponse
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt
python main.py

Na primeira vez, informe a chave e escolha o modelo (lista ou nome digitado, ex. gemini-3.1-pro-preview ou gemini-2.5-flash) e clique em Iniciar. Se existir .env com GEMINI_API_KEY / GEMINI_MODEL, os valores são importados para settings.json. Depois o app fica em background (sem janela).

Configuração (settings.json)

Exemplo após o primeiro acesso (edite com o app fechado):

{
  "gemini_api_key": "sua_chave",
  "gemini_model": "gemini-2.5-flash",
  "hotkey": "ctrl+alt+q",
  "hotkey_backend": "auto",
  "gemini_verify": true,
  "screenshot_fallback": true,
  "screenshot_fallback_max_age": 120,
  "screenshot_dirs": "",
  "custom_prompt": ""
}

Campo	Descrição
gemini_model	Definido na primeira tela; padrão gemini-2.5-flash (modelos 1.5 são migrados automaticamente)
gemini_verify	Dupla análise antes da resposta curta
hotkey_backend	auto, pynput ou keyboard
screenshot_fallback	Usa último PNG/JPG em Pictures se o clipboard não tiver imagem

Compilar executável

No Windows, build_windows.bat e build_personal.bat usam o venv do projeto e instalam o PyInstaller automaticamente (requirements-dev.txt) se ainda não existir.

Windows

build_windows.bat

Saída: dist\AssistenteIA.exe (sem console).

Não inclua chave no build. Distribua só o binário; cada usuário configura na primeira execução.

Windows — uso pessoal (chave embutida)

Para um executável só seu, com chave e modelo já dentro do .exe (pula a tela de configuração):

1. Copie o template e preencha com seus dados:

copy env.personal.example .env
notepad .env

Exemplo de .env:

GEMINI_API_KEY=sua_chave_aqui
GEMINI_MODEL=gemini-3.1-pro-preview

2. Gere o executável:

build_personal.bat

Saída: dist\AssistenteIA-Personal.exe

Item	Detalhe
.env no build	Embutido via PyInstaller (--add-data ".env;.") em sys._MEIPASS
Primeira execução	Vai direto para background (sem tkinter / sem AppData)
Segurança	Não commite o .env, não compartilhe o .exe — contém sua chave
Build normal	Se o .exe não tiver .env embutido, o fluxo padrão (janela + settings.json) continua valendo

Linux

chmod +x build_linux.sh
./build_linux.sh

Saída: dist/AssistenteIA

Uso

1. Copie o print (ou tire Print Screen no KDE e use o atalho em até 2 min).
2. Pressione Ctrl+Alt+Q.
3. Leia a resposta na notificação (formato curto) quando houver alternativas).

Solução de problemas

Problema	Ação
Sem imagem no clipboard	wl-clipboard instalado; Print Screen recente; ou Spectacle → copiar imagem
Atalho não funciona (Linux)	Wayland: use pynput (padrão); ou hotkey_backend: keyboard + sudo
Sem notificação (Linux)	libnotify / python-dbus
Erro de API	Verifique chave e cota no AI Studio
Janela inicial não abre	Instale python-tkinter / python3-tk

Licença

Uso pessoal. Respeite os termos da API Google.