RAG Agêntico Tipado com Pydantic AI

Esta aplicação Streamlit responde a perguntas a partir de PDFs carregados ou de um URL de documentação. Cada resposta é um objeto Answer validado, com citações exatas da fonte, IDs de chunks, uma pontuação de confiança e uma decisão answered. Se a recuperação for demasiado fraca, a aplicação recusa responder antes de chamar o modelo de linguagem.

Funcionalidades

• Agent e RunContext da Pydantic AI e injeção de dependências
• Uma ferramenta retrieve tipada, com metadados da fonte e pontuações de cosseno
• Modelos Pydantic para respostas, citações e evidências de recuperação
• Verificação de citações exatas contra os chunks indexados após a validação da saída do modelo
• Um mecanismo determinístico de recusa para perguntas fora do corpus
• Modelos de resposta da OpenAI ou da Anthropic
• Embeddings da OpenAI com um fallback local de hashing para configurações apenas com Anthropic
• Um armazenamento vetorial NumPy com âmbito de sessão, sem serviço de base de dados

Como funciona

1. O rag.py extrai texto de PDFs ou da web, divide-o em chunks sobrepostos, gera os respetivos embeddings e armazena os vetores normalizados em memória.
2. O agent.py injeta o armazenamento vetorial através de RagDependencies. O agente Pydantic AI tem de chamar a ferramenta retrieve tipada antes de produzir um Answer.
3. Uma pesquisa preliminar compara a melhor pontuação de cosseno com o limiar de recusa. Pontuações baixas devolvem answered=False sem qualquer pedido ao LLM.
4. Numa resposta efetiva, cada citação tem de corresponder a uma fonte armazenada, a um ID de chunk e a um trecho citado textualmente. Uma citação inválida ou em falta converte-se numa recusa.
5. O app.py apresenta a resposta, a confiança, as citações ou o estado de recusa.

Quando OPENAI_API_KEY está disponível, o modo Auto usa o Embedder OpenAI da Pydantic AI com text-embedding-3-small. Com apenas ANTHROPIC_API_KEY, o modo Auto usa o backend local de hashing, porque a Anthropic não disponibiliza uma API de embeddings. O backend local é mais adequado para demonstrações orientadas para palavras-chave. Selecione os embeddings da OpenAI para uma recuperação semântica entre paráfrases.

Pré-requisitos

• Python 3.12 ou superior
• Uma chave de API da OpenAI ou da Anthropic

Configuração

A partir da raiz do repositório:

cd rag_tutorials/agentic_typed_rag_pydanticai
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Adicione uma chave ao .env:

OPENAI_API_KEY=your-key

or:

ANTHROPIC_API_KEY=your-key

Os modelos de resposta predefinidos são openai:gpt-5.2 e

anthropic:claude-sonnet-4-6. Altere o campo do modelo na barra lateral ou

defina RAG_MODEL como outra string de modelo do Pydantic AI.

Executar

A partir de rag_tutorials/agentic_typed_rag_pydanticai:

streamlit run app.py

Carregue um ou mais PDFs, adicione, opcionalmente, um URL de documentação e selecione Build knowledge base. Faça uma pergunta relacionada com o corpus para ver uma resposta com citações. De seguida, faça uma pergunta sobre um tema não relacionado para ver o estado de recusa.

Testes

O conjunto de testes determinístico usa o TestModel do Pydantic AI, pelo que não faz pedidos ao fornecedor:

python3 test_typed_rag.py

Ficheiros

agentic_typed_rag_pydanticai/
├── app.py
├── agent.py
├── rag.py
├── test_typed_rag.py
├── requirements.txt
├── .env.example
└── assets/screenshot-placeholder.svg

Sob licença Apache-2.0, como parte de awesome-llm-apps.