pyzotero

Visão geral do skill pyzotero

O que o pyzotero faz

pyzotero é um cliente Python para a Zotero Web API v3. O skill pyzotero ajuda a ler, criar, atualizar e excluir itens, coleções, tags, anexos e exportações de citações do Zotero sem precisar montar chamadas de API manualmente.

Quem deve usar

É ideal para quem faz gestão automatizada de referências, fluxos de trabalho de literatura ou manutenção de bibliotecas no estilo Zoterosync — especialmente pyzotero para Academic Research, limpeza de bibliografias via script e pipelines de pesquisa que precisam de integração confiável com o Zotero.

Por que vale a pena instalar este skill

O principal valor do skill pyzotero é transformar o Zotero em um backend de biblioteca programável. Em vez de um prompt pontual, você ganha uma forma repetível de consultar metadados, gerenciar bibliotecas pessoais ou de grupos, buscar anexos e exportar formatos de citação com menos chance de erro de API.

Como usar o skill pyzotero

Instale o pyzotero

Use o pacote Python diretamente e adicione o extra da CLI apenas se você precisar da busca local no Zotero Desktop:

uv add pyzotero
uv add "pyzotero[cli]"

Se você está avaliando opções de instalação do pyzotero, a CLI só faz sentido quando você quer pesquisar um aplicativo Zotero local em execução; para trabalho remoto via API, ela não é necessária.

Comece com os inputs certos

Uma boa solicitação de uso do pyzotero deve incluir:

• tipo de biblioteca: user ou group
• a operação: read, create, update, delete, export ou search
• o objeto de destino: key do item, key da coleção, tag, anexo ou saved search
• o formato de saída: objetos Python, JSON, BibTeX, CSL-JSON ou citações em HTML

Exemplo de estrutura de prompt:

Use pyzotero to list items in my group library, filter to journal articles tagged reviewed, and export the results as CSL-JSON.

Leia os arquivos nesta ordem

Para uma configuração prática, leia primeiro SKILL.md e depois os materiais de referência mais específicos da sua tarefa:

• references/authentication.md para API keys, user IDs e modo local
• references/read-api.md e references/search-params.md para obtenção e filtragem
• references/write-api.md para fluxos de create/update/delete
• references/files-attachments.md e references/full-text.md para PDFs e indexação
• references/exports.md para BibTeX, CSL-JSON e saída de citações
• references/error-handling.md para rate limits, conflitos e campos inválidos

Fluxo prático para usar melhor o pyzotero

1. Confirme se você precisa de acesso remoto à API ou apenas de busca local.
2. Configure as credenciais para a biblioteca correta antes de chamar os métodos.
3. Teste primeiro uma chamada de leitura e só depois expanda para ações em lote.
4. Use keys, não títulos, para updates e deletes.
5. Adicione paginação ou limites de saída cedo para que o resultado seja utilizável.

Perguntas frequentes sobre o skill pyzotero

O pyzotero é só para programadores?

Não. Ele é mais útil em fluxos de trabalho Python, mas ainda é acessível para não especialistas que consigam seguir uma instalação curta e fornecer inputs estruturados. Se você só precisa exportar citações manualmente de vez em quando, um prompt comum do Zotero pode ser mais simples.

O pyzotero funciona com bibliotecas pessoais e de grupos?

Sim. O skill pyzotero dá suporte aos dois casos, mas uma única instância de Zotero fica vinculada a uma biblioteca só. Isso importa quando você precisa alternar entre uma biblioteca pessoal e uma biblioteca compartilhada de laboratório ou equipe.

Quando eu não deveria usar o pyzotero?

Não use o pyzotero se você só quer formatação rápida e pontual de citações dentro do próprio Zotero, ou se precisa de busca por texto completo sem um aplicativo Zotero Desktop local. A CLI depende do Zotero local; a API não oferece o mesmo comportamento de busca local por texto completo.

O pyzotero é bom para Academic Research?

Sim, especialmente para gestão em lote de literatura, limpeza de referências, tratamento de anexos e exportações reproduzíveis. Ele ajuda menos quando sua tarefa é mais ler artigos do que organizar ou transformar dados do Zotero.

Como melhorar o skill pyzotero

Dê ao skill os detalhes de biblioteca que estão faltando

O maior ganho de qualidade vem de especificar logo de início o contexto da biblioteca. No caso do pyzotero, inclua o library ID, se a biblioteca é user ou group e se você quer modo local ou a API remota. Sem isso, as saídas tendem a ficar genéricas ou a escolher o caminho de acesso errado.

Seja explícito sobre a forma dos dados que você quer

Diga se você quer um único item, uma lista de itens, uma árvore de coleções, metadados de anexos ou um arquivo de exportação. Bons inputs para o pyzotero parecem com:

• “return only keys and titles”
• “update the abstractNote for these item keys”
• “export the top 50 results as BibTeX”
• “find PDFs whose full text mentions gene editing”

Fique atento aos modos de falha mais comuns

Os erros mais comuns no pyzotero são usar títulos em vez de keys, pular a configuração de autenticação e tentar fazer write em lote demais de uma vez. Outro problema frequente é esperar busca local por texto completo só com a API. Se o resultado vier estranho, verifique se a consulta deveria usar metadados do item, texto completo ou filtros de coleção.

Itere depois da primeira passagem

Se a primeira saída vier ampla demais, refine adicionando tipo de item, lógica de tags, key da coleção ou intervalo de datas. Se o primeiro write/update parecer arriscado, peça ao pyzotero para simular o payload ou mostrar os campos exatos do item antes de aplicar as mudanças. Essa é a forma mais rápida de melhorar o uso do pyzotero em fluxos reais de pesquisa.