Arquitetura¶

O alberto-research separa deliberadamente o trabalho determinístico, feito em Python, do trabalho de julgamento, delegado a LLMs. Essa divisão é a decisão de arquitetura mais importante do projeto: ela mantém o comportamento auditável, barato e reproduzível, e concentra o não determinismo em pontos com contrato explícito.

Mapa de módulos¶

Módulos auxiliares completam o quadro: dedupe (deduplicação de registros), feedback (registro do retorno do leitor), models e enums (tipos de domínio), logging (configuração de log a partir de LOG_LEVEL) e os módulos de integração com bibliotecas sombra, que ficam isolados do caminho padrão.

Divisão entre determinístico e LLM¶

O critério é simples: se a resposta correta é única e verificável, fica em Python; se exige interpretação, vai para o LLM.

A consequência prática: os pontos de contato com o LLM são poucos e cada um tem um contrato de entrada e saída. A triagem produz uma pontuação; a leitura produz um objeto JSON que precisa satisfazer READER_OUTPUT_SCHEMA — com campos como access_level, central_argument, methodology, major_findings, relevance_to_project, disagreements e confidence — antes de chegar ao banco.

Cadeia de resolvedores de texto completo¶

A resolução percorre os resolvedores na ordem declarada em fulltext.resolver_order:

flowchart LR
    Z[zotero] --> U[unpaywall]
    U --> O[openalex]
    O --> C[core]
    C --> D[doaj]
    D --> E[europepmc]
    E --> P[provider_url]

Regras da cadeia:

• A ordem declarada tem prioridade. Nomes desconhecidos ou resolvedores indisponíveis são ignorados.
• Resolvedores que não aparecem em resolver_order são anexados ao final, na ordem interna do pacote — por isso a lista configurada não precisa ser exaustiva.
• zotero vem primeiro por ser o mais barato: se o PDF já está na sua biblioteca, nenhuma requisição externa é necessária.
• unpaywall depende de unpaywall_email; sem endereço de contato, o resolvedor não é usado.
• core depende de core_api_key; sem chave, é ignorado.
• provider_url usa links de PDF oferecidos pelos próprios metadados.
• Os resolvedores de bibliotecas sombra ficam fora dessa cadeia padrão e desligados; quando habilitados, desativam a verificação de certificado TLS.

O primeiro resolvedor que devolve um documento utilizável vence, e o resultado é gravado no cache local (fulltext.cache_dir), respeitando fulltext.max_fulltext_bytes e fulltext.download_timeout.

Fronteira de confiança¶

Tudo o que vem de fora é tratado como hostil: títulos, abstracts, metadados, páginas HTML e, principalmente, o texto extraído dos PDFs. Um artigo pode conter instruções maliciosas destinadas a sequestrar o comportamento do modelo — a chamada injeção de prompt.

O desenho da fronteira:

flowchart LR
    X[Conteúdo externo hostil] --> R[reader: sandbox de leitura]
    R --> V[schemas: validação JSON Schema]
    V --> S[(SQLite: fonte de verdade)]
    S --> W[workflow e digest]

• O conteúdo externo entra somente pelo módulo reader, que monta o prompt explicitamente instruindo o modelo a devolver apenas o JSON do schema, sem executar nem repetir instruções encontradas no documento.
• A saída do modelo é validada contra o JSON Schema, e chaves proibidas (tool_calls, commands, shell, email, secrets, credentials, delete_files) são rejeitadas.
• Só depois da validação os dados são persistidos no SQLite.
• O agente de leitura roda isolado, sem acesso a finanças, ao sistema de arquivos amplo, a e-mail, a ferramentas destrutivas, a cookies de navegador ou a segredos não relacionados.

Detalhes do modelo de ameaças e do tratamento de injeção de prompt estão em Segurança.

Fonte de verdade e integrações¶

O SQLite é a fonte de verdade operacional. Zotero e Notion são integrações opcionais e unidirecionais a partir do estado local: o fluxo nunca depende delas para funcionar, e uma indisponibilidade dessas APIs não corrompe o histórico. As migrações SQL viajam dentro do pacote, então atualizar o código e aplicar db migrate mantém o banco alinhado.

Para a referência gerada a partir do código, veja Referência da API.