bibliotecario-pedro-cao 0.1.0

Assistente de pesquisa que integra Google Drive, buscas acadêmicas e IA Gemini.

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

python mcp_server.py

Ou usando o entrypoint:

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. 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.

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.

Cache e Rate Limiting (opcional)

Configure no .env:

CACHE_TTL_SECONDS=3600
RATE_LIMIT_SECONDS=0

Contribuição

Veja as diretrizes em CONTRIBUTING.md e o Plano de Implementação 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/*