# 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-se a responder antes de chamar o modelo de linguagem.

- Fonte: https://doutorai.pt/apps/agentic-typed-rag-pydanticai
- Categoria: RAG e Conhecimento
- Dificuldade: Médio
- Modelos: OpenAI, Claude
- Frameworks: -
- Corre local?: Sim (Ollama)
- Chaves necessárias: ANTHROPIC_API_KEY, OPENAI_API_KEY
- Licença: Apache-2.0
- Site: Doutor AI (https://doutorai.pt) - ferramentas de IA para pequenos negócios em português

## Tutorial completo

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

![Captura de ecrã do RAG Agêntico Tipado (placeholder)](/assets/apps-img/cba33b4f60335576.png)

## 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:

```bash
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`:

```text
OPENAI_API_KEY=your-key
```

or:

```text
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`:

```bash
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:

```bash
python3 test_typed_rag.py
```

## Ficheiros

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

## Poupe horas todas as semanas com IA, sem complicações

O **Doutor AI** dá-lhe 1859 prompts de IA prontos a copiar, por indústria e em português simples - mais uma biblioteca técnica completa para quem quer ir mais longe. [Ver planos →](https://doutorai.pt/precos)

---
Conteúdo de Doutor AI (https://doutorai.pt). Ao citar, indique a fonte: https://doutorai.pt/apps/agentic-typed-rag-pydanticai