bibliotecario-pedro-cao 0.1.0
Assistente de pesquisa que integra Google Drive, buscas acadêmicas e IA Gemini.
Requires Python: >=3.10
Keywords: research, google-drive, worldcat, gemini, mcp

# Bibliotecário Pedro Cão

Assistente de pesquisa que integra sua biblioteca do Google Drive com buscas acadêmicas e IA Gemini.

## Requisitos
- Python 3.10+
- Conta Google para OAuth (Drive)
- Chaves de API: WorldCat (opcional), Gemini

## Configuração
1. Copie `.env.example` para `.env` e preencha:
   - `GOOGLE_DRIVE_FOLDER_ID`
   - `WORLDCAT_API_KEY` (opcional)
   - `GEMINI_API_KEY`
   - `GEMINI_MODEL` (opcional, padrão: gemini-2.5-flash)
   - `LOG_LEVEL` (opcional, padrão: INFO)
   - `LOG_JSON` (opcional, padrão: false)
2. Coloque `credentials.json` (OAuth do Google) na raiz do projeto OU no caminho seguro por plataforma:
   - Windows: `%APPDATA%\PedroCao\credentials.json`
   - macOS: `~/Library/Application Support/PedroCao/credentials.json`
   - Linux: `~/.config/pedrocao/credentials.json`
3. Primeiro run criará `token.json`. Por padrão será salvo no caminho seguro por plataforma (acima). Se `token.json` existir na raiz, será usado.

## Execução (Windows)
Use o executável de conveniência:
```
Executar_Pedro_Cao.bat
```
Ou manualmente:
```
python -m venv .venv
.venv\\Scripts\\activate
python -m pip install -r requirements.txt
python main.py
```
No script `.bat`, se `requirements.lock` existir, será usado como constraints automaticamente.

### Opções de menu úteis
- 5: Ver Configuração de Rede (timeout/retries/backoff atuais)
- 6: Verificar/Mover Credenciais para local seguro (ajuda a tirar `credentials.json`/`token.json` da raiz)

### Modo não-interativo (CLI)
```
python main.py --drive-search "minha busca"
python main.py --worldcat "história de portugal"
python main.py --ask "Quem foi Camilo Castelo Branco?"
python main.py --solve "Explique o conceito de metadados"
python main.py --debug-config
python main.py --move-credentials
```

## MCP Server (Model Context Protocol)
Este projeto inclui um servidor MCP via stdio para expor as ferramentas do Bibliotecário.

### Executar o servidor MCP
```bash
python mcp_server.py
```
Ou usando o entrypoint:
```bash
pedro-cao-mcp
```

### Ferramentas MCP disponíveis
- `search_drive` (query, limit)
- `search_worldcat` (query)
- `search_web` (query)
- `search_academic` (query)
- `ask_pedro_cao` (question, context)
- `debug_config` ()
- `credentials_status` ()

### Cliente MCP (Claude Desktop)
Existe um exemplo de configuração para Claude Desktop em [mcp/claude_desktop_config.json](bibliotecario_pedro_cao/mcp/claude_desktop_config.json).
Atualize os caminhos do Python e do arquivo do servidor MCP conforme sua máquina e copie o conteúdo para o arquivo de configuração do cliente.

### Organização de arquivos misturados
Se você adicionou pastas/arquivos de outro projeto por engano, use o script de organização para mover itens não essenciais para `misc/`:
```
./organize.ps1
```
Ele lista o que não pertence ao núcleo do projeto e pergunta se deseja mover.

## Segurança
- NUNCA faça commit de `.env`, `credentials.json` ou `token.json`.
- Rode o `test_gemini.py` sem imprimir a chave.
- Em caso de vazamento, ROTACIONE as credenciais:
  - Regenerar `client_secret` e revogar `refresh_token` no Google Cloud Console.
  - Gerar nova `GEMINI_API_KEY`.
 - Veja o guia detalhado em [SECURITY_ROTATION.md](SECURITY_ROTATION.md).

## Dependências
Veja `requirements.txt` (versões fixadas). Para garantir sub-dependências no deploy, use o constraints:
```
pip install -r requirements.txt -c requirements.lock
```

## Observações
- Escopos de Drive são somente leitura.
- Chamadas HTTP têm `timeout=10` para evitar travamentos.
 - Veja a descrição detalhada em [ARCHITECTURE.md](ARCHITECTURE.md).

## Cache e Rate Limiting (opcional)
Configure no `.env`:
```
CACHE_TTL_SECONDS=3600
RATE_LIMIT_SECONDS=0
```

## Contribuição
Veja as diretrizes em [CONTRIBUTING.md](CONTRIBUTING.md) e o [Plano de Implementação](IMPLEMENTATION_PLAN.md) para tarefas e prioridades.

### Dev Quickstart
```
# Windows PowerShell
./dev.ps1 -Install -Test

# Manual
python -m venv .venv
.venv\\Scripts\\activate
pip install -r requirements.txt -c requirements.lock
pip install -r requirements-dev.txt
pytest -q
```

## Distribuição (build e publicação)
1. Instale dependências de build:
```
pip install -r requirements-dev.txt
```
2. Gere os artefatos:
```
python -m build
```
3. Verifique os pacotes:
```
twine check dist/*
```
4. Publicação (se aplicável):
```
twine upload dist/*
```