PinRAG

PinRAG

Visão Geral

O PinRAG é para quando você quer aprender sobre algo e seus materiais estão espalhados—PDFs e ebooks, repositórios GitHub, vídeos do YouTube, discussões no Discord e anotações simples. Você indexa esses materiais em um único índice RAG compartilhado e então faz perguntas a partir do Cursor, VS Code (GitHub Copilot) ou qualquer assistente compatível com MCP e obtém respostas com citações apontando para páginas, timestamps, arquivos ou threads.

Por baixo dos panos, é Geração Aumentada por Recuperação construída com LangChain e exposta como um servidor MCP (Model Context Protocol): adicione documentos pelo editor, consulte em linguagem natural, liste ou remova o que você indexou. As entradas suportadas incluem PDFs, arquivos de texto locais e diretórios, exportações do Discord, YouTube (transcrição por URL, playlist ou ID) e URLs de repositórios GitHub. Para YouTube, você pode opcionalmente adicionar visão para que código na tela, diagramas e texto de interface sejam mesclados com a transcrição nos mesmos chunks—veja Enriquecimento de visão no YouTube.

Recursos

• Indexação multi-formato — PDF (.pdf), arquivos ou diretórios locais, texto simples (.txt), exportação do Discord (.txt), YouTube (URL de vídeo ou playlist, ou ID de vídeo), repositório GitHub (URL), sites de documentação web (URL)
• Visão opcional no YouTube — Desativada por padrão. Quando ativada, executa um modelo de visão (OpenAI, Anthropic ou vídeo nativo OpenRouter) e mescla contexto estruturado da tela com a transcrição, para que os chunks RAG carreguem nomes de código, rótulos e diagramas pesquisáveis—não apenas fala. O modo OpenRouter evita download local de ffmpeg/vídeo; openai/anthropic usam keyframes de cena e exigem pinrag[vision] + ffmpeg (veja Enriquecimento de visão no YouTube)
• RAG com citações — As respostas citam o contexto da fonte: página do PDF, timestamp do YouTube, nome do documento para texto simples e Discord, índice do chunk para repositórios GitHub, URL da fonte para documentação web
• Tags de documentos — Marque documentos no momento da indexação (ex.: AMIGA, PI_PICO) para busca filtrada
• Filtragem por metadados — query_tool suporta document_id, tag, document_type, page_min/page_max de PDF e response_style (detalhado ou conciso)
• Ferramentas MCP — add_document_tool, query_tool, list_documents_tool, remove_document_tool, set_document_tag_tool, list_collections_tool; collection opcional nas ferramentas substitui PINRAG_COLLECTION_NAME para aquela chamada
• Recursos MCP — pinrag://documents (documentos indexados) e pinrag://server-config (variáveis de ambiente e configuração); clique no painel MCP do Cursor para visualizar
• Prompt MCP — use_pinrag (parâmetro: solicitação) para consultar, indexar, listar ou remover documentos
• LLM configurável — OpenRouter (padrão, roteador openrouter/free gratuito), OpenAI, Anthropic ou Cerebras Inference (API compatível com OpenAI); definido via PINRAG_LLM_PROVIDER e PINRAG_LLM_MODEL no env do MCP ou no seu shell
• Embeddings locais — Nomic (PINRAG_EMBEDDING_MODEL, padrão nomic-embed-text-v1.5); sem chave de API; o primeiro uso baixa os pesos do modelo (~270 MB, em cache)
• Opções de recuperação e chunking — Chunking ciente de estrutura (ativado por padrão); re-ranking opcional com FlashRank, expansão multi-consulta e chunks pai-filho para PDFs (veja Configuração)
• Observabilidade — Notificações de ferramentas MCP (ctx.log) além de rastreamento opcional com LangSmith
• Construído com — LangChain, Chroma; OpenRouter, OpenAI, Anthropic, FlashRank opcionais

Instalação

Adicione o PinRAG como servidor MCP no seu editor. Instale uv e garanta que uvx esteja no seu PATH—isso executa o PinRAG a partir do PyPI sem um pip install prévio.

Cursor: adicione isto em mcpServers no ~/.cursor/mcp.json:

{
  "mcpServers": {
    "pinrag": {
      "command": "uvx",
      "args": ["--refresh", "pinrag"],
      "env": {
        "OPENROUTER_API_KEY": "your-openrouter-api-key-here",
        "PINRAG_PERSIST_DIR": "/absolute/path/to/your/pinrag-data"
      }
    }
  }
}

VS Code (GitHub Copilot): execute MCP: Open User Configuration na Paleta de Comandos (ou adicione .vscode/mcp.json em um workspace) e mescle este formato—a chave de nível superior é servers:

{
  "servers": {
    "pinrag": {
      "command": "uvx",
      "args": ["--refresh", "pinrag"],
      "env": {
        "OPENROUTER_API_KEY": "your-openrouter-api-key-here",
        "PINRAG_PERSIST_DIR": "/absolute/path/to/your/pinrag-data"
      }
    }
  }
}

Início Rápido

Modo servidor HTTP

Para clientes que falam MCP sobre HTTP (ex.: pinrag-cli com --server), execute:

pinrag server [--host 127.0.0.1] [--port 8765]

Isso inicia um endpoint MCP streamable-HTTP em http://<host>:<port>/mcp. O comando padrão pinrag stdio para editores permanece inalterado; pinrag server é aditivo. Conecte o pinrag-cli com --server http://127.0.0.1:8765/mcp.

Configurar o servidor MCP

Coloque chaves de API e quaisquer configurações do PinRAG no bloco env da entrada MCP. O servidor não carrega arquivos .env quando o editor o inicia.

Uso no chat

Ação	Ferramenta
Indexar arquivos, diretórios ou URLs	add_document_tool — paths obrigatório: lista de caminhos locais (PDFs, .txt de texto simples ou DiscordChatExporter, diretórios) ou URLs (vídeos do YouTube, URLs de playlists, repositórios GitHub, sites de documentação web; IDs de vídeo do YouTube sem URL são permitidos). tags opcional (um por caminho). Apenas para URLs do GitHub: branch, include_patterns, exclude_patterns.
Listar documentos indexados	list_documents_tool — retorna documents (IDs), total_chunks e filtro opcional tag. document_details pode incluir document_type, tags, contagens de páginas / mensagens / segmentos, títulos, bytes agregado e upload_timestamp quando presente nos metadados.
Consultar com filtros	query_tool — query obrigatório. Opcionais: document_id, tag, document_type, page_min / page_max (intervalos de PDF), response_style (thorough ou concise; deixe vazio para usar PINRAG_RESPONSE_STYLE).
Remover um documento	remove_document_tool — document_id obrigatório (valor exato de list_documents_tool).
Visualizar recursos (somente leitura)	No painel MCP, abra Resources e escolha pinrag://documents (documentos indexados) ou pinrag://server-config (configuração efetiva, incluindo PINRAG_VERSION).

Pergunte no chat: "Adicione /caminho/para/amiga-book.pdf com a tag AMIGA", "Indexe https://youtu.be/xyz e pergunte o que ele diz", "Indexe https://github.com/owner/repo e pergunte sobre o codebase" ou "Indexe https://docs.langchain.com/ e resuma suas APIs de memória". A IA invocará as ferramentas para você. As citações mostram números de página para PDFs, timestamps (ex.: t. 1:23) para YouTube, nomes de documentos para texto simples e exportações do Discord, rótulos de índice de chunk para GitHub e URLs de fonte para documentação web.

Indexação do GitHub

Indexe um repositório com add_document_tool e uma URL em paths, ex.: https://github.com/owner/repo, https://github.com/owner/repo/tree/branch ou github.com/owner/repo (esquema opcional).

Opções exclusivas do GitHub: branch, include_patterns / exclude_patterns — os padrões já favorecem arquivos comuns de texto e código e ignoram artefatos volumosos; use padrões quando precisar de arquivos fora desse conjunto. Arquivos acima de PINRAG_GITHUB_MAX_FILE_BYTES (padrão 512 KiB) são ignorados.

Autenticação: Defina GITHUB_TOKEN no env do MCP (ou no shell) para repositórios privados ou para reduzir limites de taxa em indexações grandes; execuções públicas pequenas geralmente funcionam sem isso. Use um PAT clássico ou de granularidade fina com acesso de leitura ao repositório; não há OAuth no PinRAG.

Indexação de documentação web

Aponte add_document_tool para qualquer URL de site de documentação, ex.: https://docs.langchain.com/, https://docs.crewai.com/ ou https://picocomputer.github.io/. O PinRAG descobre páginas via (em ordem) llms.txt / llms-full.txt (estilo Mintlify), sitemap.xml (incluindo dicas robots.txt Sitemap: e índices de sitemap aninhados) e, em seguida, um rastreamento BFS com escopo a partir da URL inicial.

Escopo: correspondência exata de host (sem subdomínios) mais prefixo de caminho derivado da semente—ex.: https://docs.example.com/guide/ indexa apenas páginas sob /guide/. Use a URL raiz do site para capturar toda a árvore de documentação.

Extração: respostas text/markdown (de caminhos rápidos llms.txt) passam direto; HTML passa por trafilatura com fallback BeautifulSoup + markdownify que limita o escopo a <main> / <article> / [role=main].

Limites e polidez: controlados por PINRAG_WEB_MAX_PAGES (padrão 200), PINRAG_WEB_MAX_DEPTH (5), PINRAG_WEB_MAX_PAGE_BYTES (1 MiB), PINRAG_WEB_CONCURRENCY (4), PINRAG_WEB_RATE_LIMIT_PER_HOST (2,0/seg) e PINRAG_WEB_RESPECT_ROBOTS (true). Alguns sites (ex.: páginas protegidas por Cloudflare) podem retornar 403 para clientes Python puros; isso é uma limitação conhecida.

Citações: chunks web carregam um campo de metadados source_url; as respostas citam URLs por página, e o document_id é <host><path_prefix> para que remove_document_tool / set_document_tag_tool operem no site inteiro de uma vez.

Indexação do YouTube e bloqueio de IP

Indexação pesada de transcrições—especialmente de IPs de nuvem ou de alto volume—pode retornar erros como "O YouTube está bloqueando solicitações do seu IP". Aponte youtube-transcript-api para um proxy via env do MCP (ou no seu shell):

PINRAG_YT_PROXY_HTTP_URL=http://user:pass@proxy.example.com:80
PINRAG_YT_PROXY_HTTPS_URL=http://user:pass@proxy.example.com:80

PINRAG_YT_PROXY_* afeta apenas a busca de transcrições; etapas do yt-dlp (títulos, playlists) não o utilizam. Proxies residenciais ou rotativos geralmente funcionam melhor do que IPs brutos de datacenter.

Quando alguns caminhos falham (ex.: alguns vídeos em uma playlist), add_document_tool inclui fail_summary com contagens agrupadas por blocked, disabled, missing_transcript e other.

Enriquecimento de visão no YouTube (opcional)

A indexação padrão é somente transcrição. Defina PINRAG_YT_VISION_ENABLED=true para adicionar legendas de visão para conteúdo na tela, alinhadas no tempo com a transcrição e divididas em chunks com metadados como has_visual, frame_count e visual_source.

PINRAG_YT_VISION_PROVIDER:

• openai (padrão) ou anthropic: download yt-dlp → frames baseados em cena → uma chamada multimodal por frame. Precisa de pinrag[vision], ffmpeg/ffprobe no PATH e OPENAI_API_KEY ou ANTHROPIC_API_KEY (instale o extra no mesmo ambiente de pinrag, ex.: uv sync --extra vision ou pip install 'pinrag[vision]').
• openrouter: uma solicitação OpenRouter por vídeo via video_url (padrão google/gemini-2.5-flash). OPENROUTER_API_KEY apenas—sem download, ffmpeg ou pinrag[vision]; escolha um modelo com capacidade de vídeo se você substituir PINRAG_YT_VISION_MODEL.

Operações: Re-indexe após alterar as configurações de visão. Para openai/anthropic, ajuste custo e timeouts com PINRAG_YT_VISION_MAX_FRAMES e PINRAG_YT_VISION_IMAGE_DETAIL=high opcional (texto pequeno mais claro, mais tokens). MCP stdio: o progresso do yt-dlp vai para stderr para que stdout permaneça limpo em JSON. Baixar vídeo pode violar os Termos de Serviço do YouTube ou regras locais—decisão sua. Docker: construa com BUILD_WITH_VISION=1 para ffmpeg + pinrag[vision] (veja Dockerfile).

Dicas

• pinrag não encontrado: o MCP herda seu PATH de login. Após pipx ou uv tool install, reinicie o editor e confirme which pinrag.
• PINRAG_PERSIST_DIR: Use um caminho absoluto estável no env do MCP (ex.: ~/.pinrag/chroma_db) para que o armazenamento vetorial não dependa do diretório de trabalho do processo do servidor.
• FlashRank: Instale pinrag[rerank] no mesmo ambiente da ferramenta (pipx install 'pinrag[rerank]' / uv tool install 'pinrag[rerank]'); os ajustes estão em Configuração.
• Visão no YouTube: Siga Enriquecimento de visão no YouTube para variáveis de ambiente e dependências; re-indexe após alterar as configurações de visão.
• pinrag://server-config: MCP Resources → esta URI para PINRAG_VERSION, LLM/embeddings/chunking efetivos e status de chave de API definida / não definida.

Configuração

O recurso MCP pinrag://server-config imprime PINRAG_VERSION (versão do pacote, não uma variável de ambiente que você define) e valores efetivos para as variáveis abaixo, além de quais chaves de API estão definidas. Use a tabela como referência completa de variáveis de ambiente.

Variáveis de ambiente:

Variável	Padrão	Descrição
LLM
Provedor e modelo
PINRAG_LLM_PROVIDER	openrouter	openrouter, openai, anthropic ou cerebras
PINRAG_LLM_MODEL	(padrão do provedor)	Quando não definido: OpenRouter openrouter/free, OpenAI gpt-4o-mini, Anthropic claude-haiku-4-5, Cerebras llama3.1-8b. Substitua por qualquer ID de modelo (ex.: OpenRouter anthropic/claude-sonnet-4-6, Cerebras gpt-oss-120b).
OpenRouter
PINRAG_OPENROUTER_MODEL_FALLBACKS	(não definido)	Slugs de modelos de fallback separados por vírgula, enviados como lista models do OpenRouter. O gateway tenta o próximo slug quando o principal (PINRAG_LLM_MODEL) falha (limites de taxa, indisponibilidade etc.). Use modelos gratuitos extras aqui para manter custo zero. Alias legado: PINRAG_LLM_MODEL_FALLBACKS.
PINRAG_OPENROUTER_SORT	(não definido)	provider.sort opcional — price, throughput ou latency. Quando não definido, o OpenRouter usa a seleção padrão de provedores. Prefira deixar isso não definido se você definir PINRAG_OPENROUTER_PROVIDER_ORDER para fixar um backend específico (evita sinais de roteamento conflitantes).
PINRAG_OPENROUTER_PROVIDER_ORDER	(não definido)	Nomes de provedores separados por vírgula para provider.order (tentados em sequência). Exemplo: Cerebras com PINRAG_LLM_MODEL=openai/gpt-oss-120b para preferir roteamento baseado em Cerebras. Use os rótulos exatos da lista de provedores do modelo no OpenRouter.
OPENROUTER_APP_URL	https://github.com/ndjordjevic/pinrag	Atribuição de aplicativo (HTTP-Referer). Substitua pela URL do seu site (veja atribuição de aplicativo do OpenRouter). O PinRAG copia isso para OPENROUTER_HTTP_REFERER no SDK Python do OpenRouter.
OPENROUTER_APP_TITLE	PinRAG	Título do aplicativo (X-Title). Substitua para rotular o uso no painel do OpenRouter. O PinRAG copia isso para OPENROUTER_X_OPEN_ROUTER_TITLE no SDK.
Chaves de API
OPENROUTER_API_KEY	(obrigatória ao usar OpenRouter para LLM, avaliadores ou visão do YouTube)	Obrigatória quando PINRAG_LLM_PROVIDER=openrouter, PINRAG_EVALUATOR_PROVIDER=openrouter ou visão do YouTube com PINRAG_YT_VISION_PROVIDER=openrouter.
OPENAI_API_KEY	(obrigatória para LLM OpenAI ou visão do YouTube com OpenAI)	Obrigatória quando PINRAG_LLM_PROVIDER=openai ou quando PINRAG_YT_VISION_ENABLED=true e PINRAG_YT_VISION_PROVIDER=openai.
OPENAI_BASE_URL	(opcional)	Substitui a URL base da API OpenAI (ex.: https://openrouter.ai/api/v1 com OPENAI_API_KEY definido como sua chave OpenRouter para visão ou outras chamadas compatíveis com OpenAI).
CEREBRAS_API_KEY	(obrigatória para LLM Cerebras)	Obrigatória quando PINRAG_LLM_PROVIDER=cerebras. Obtenha uma chave no console da nuvem Cerebras.
PINRAG_CEREBRAS_BASE_URL	https://api.cerebras.ai/v1	Substitui a URL base compatível com OpenAI para Cerebras (ex.: endpoints de inferência dedicados).
ANTHROPIC_API_KEY	(obrigatória para LLM Anthropic ou visão do YouTube com Anthropic)	Obrigatória quando PINRAG_LLM_PROVIDER=anthropic, PINRAG_EVALUATOR_PROVIDER=anthropic ou visão do YouTube com PINRAG_YT_VISION_PROVIDER=anthropic.
Embeddings
PINRAG_EMBEDDING_MODEL	nomic-embed-text-v1.5	ID do modelo Nomic local (via langchain-nomic). O primeiro uso baixa os pesos (~270 MB, em cache). Sem chave de API.
Armazenamento e fragmentação
PINRAG_PERSIST_DIR	chroma_db	Diretório do armazenamento vetorial Chroma (o padrão é relativo ao diretório de trabalho do processo do servidor, a menos que você defina um caminho absoluto; ex.: ~/.pinrag/chroma_db para um local fixo)
PINRAG_CHUNK_SIZE	1000	Tamanho do fragmento de texto (caracteres)
PINRAG_CHUNK_OVERLAP	200	Sobreposição de fragmentos (caracteres)
PINRAG_STRUCTURE_AWARE_CHUNKING	true	Aplica heurísticas de fragmentação cientes da estrutura para limites de código/tabelas
PINRAG_COLLECTION_NAME	pinrag	Nome da coleção Chroma. Coleção compartilhada única por padrão.
ANONYMIZED_TELEMETRY	False via setdefault quando não definido	Sinalizador de telemetria do Chroma. A configuração de logging do MCP do PinRAG chama os.environ.setdefault("ANONYMIZED_TELEMETRY", "False") para que vazio/não definido se comporte como opt-out; defina true em env se quiser a telemetria do Chroma ativada.
Recuperação
PINRAG_RETRIEVE_K	20	Tamanho do pool de recuperação quando o re-ranking está desativado. Quando o re-ranking está ativado, PINRAG_RERANK_RETRIEVE_K usa este valor se não definido, e os resultados são cortados para PINRAG_RERANK_TOP_N.
Recuperação pai-filho
PINRAG_USE_PARENT_CHILD	false	Defina como true para incorporar fragmentos pequenos e retornar fragmentos pai maiores (suportado para indexação de PDF, GitHub, YouTube e Discord — não para .txt simples). Requer reindexação.
PINRAG_PARENT_CHUNK_SIZE	2000	Tamanho do fragmento pai (caracteres) quando PINRAG_USE_PARENT_CHILD=true.
PINRAG_CHILD_CHUNK_SIZE	800	Tamanho do fragmento filho (caracteres) quando PINRAG_USE_PARENT_CHILD=true.
Re-ranking
PINRAG_USE_RERANK	false	Defina como true para ativar o re-ranking FlashRank: busque mais fragmentos, reavalie localmente, passe os N principais para o LLM. Requer pip install pinrag[rerank] e nenhuma chave de API.
PINRAG_RERANK_RETRIEVE_K	(herda PINRAG_RETRIEVE_K)	Fragmentos a buscar antes do FlashRank quando PINRAG_USE_RERANK=true. Se não definido, equivale a PINRAG_RETRIEVE_K (não um 20 fixo separado).
PINRAG_RERANK_TOP_N	10	Fragmentos passados ao LLM após o re-ranking quando PINRAG_USE_RERANK=true (limitado pelo tamanho da busca pré-re-ranking).
Multi-consulta
PINRAG_USE_MULTI_QUERY	false	Defina como true para gerar formulações alternativas da consulta do usuário via LLM, recuperar por variante e mesclar (união única). Melhora a recuperação para consultas curtas ou ambíguas.
PINRAG_MULTI_QUERY_COUNT	4	Número de consultas alternativas a gerar (padrão 4, máximo 10). A consulta original ainda é incluída na recuperação ao mesclar.
Estilo de resposta
PINRAG_RESPONSE_STYLE	thorough	Estilo de resposta RAG: thorough (detalhado) ou concise. Usado pelo alvo de avaliação e como padrão quando o MCP query omite response_style.
Notificações MCP
PINRAG_VERBOSE_LOGGING	false	Defina true para emitir notificações MCP detalhadas por fase para execução de ferramentas/recursos (detecção de formato, carregamento de transcrição, caminho/etapas de visão, upserts de fragmentos). O padrão mantém logs de ciclo de vida concisos de início/ok/erro.
Indexação GitHub
GITHUB_TOKEN	(opcional)	Token de acesso pessoal para a API do GitHub. Obrigatório para repositórios privados; aumenta os limites de taxa para repositórios públicos.
PINRAG_GITHUB_MAX_FILE_BYTES	524288 (512 KB)	Ignora arquivos maiores que isso ao indexar repositórios GitHub.
PINRAG_GITHUB_DEFAULT_BRANCH	main	Branch padrão quando não especificada na URL do GitHub.
Indexação de texto simples
PINRAG_PLAINTEXT_MAX_FILE_BYTES	524288 (512 KB)	Ignora arquivos .txt simples maiores que isso ao indexar.
Indexação de documentos web
PINRAG_WEB_MAX_PAGES	200	Máximo de páginas buscadas por execução de indexação web.
PINRAG_WEB_MAX_DEPTH	5	Profundidade máxima de rastreamento BFS a partir da URL inicial (ignorado para caminhos rápidos llms.txt / sitemap).
PINRAG_WEB_MAX_PAGE_BYTES	1048576 (1 MiB)	Ignora páginas cujo corpo de resposta exceda esse tamanho.
PINRAG_WEB_REQUEST_TIMEOUT	20	Tempo limite de HTTP por solicitação em segundos (conexão + leitura).
PINRAG_WEB_CONCURRENCY	4	Máximo de buscas simultâneas por host.
PINRAG_WEB_RATE_LIMIT_PER_HOST	2.0	Taxa de reabastecimento do token bucket (solicitações / segundo) por host.
PINRAG_WEB_USER_AGENT	PinRAGBot/<version> (+https://github.com/ndjordjevic/pinrag)	Cabeçalho HTTP User-Agent para indexação web. Alguns sites bloqueiam bots genéricos; substitua se necessário.
PINRAG_WEB_RESPECT_ROBOTS	true	true / false — respeita regras de desautorização robots.txt ao rastrear.
PINRAG_WEB_PREFER_LLMS_TXT	true	Tenta llms.txt / llms-full.txt antes de sitemap / BFS. Desative para forçar descoberta por sitemap ou rastreamento.
Proxy de transcrição do YouTube
PINRAG_YT_PROXY_HTTP_URL	(nenhum)	URL de proxy HTTP para buscas de transcrição (ex.: http://user:pass@proxy:80). Use quando o YouTube bloquear seu IP.
PINRAG_YT_PROXY_HTTPS_URL	(nenhum)	URL de proxy HTTPS para buscas de transcrição. Igual ao HTTP ao usar um proxy genérico.
Visão do YouTube (opcional)
PINRAG_YT_VISION_ENABLED	false	true / 1 / yes / on ativa o enriquecimento de tela para YouTube. openai / anthropic: requer pinrag[vision], ffmpeg no PATH e a chave de API correspondente. openrouter: requer apenas OPENROUTER_API_KEY (caminho nativo video_url; sem download local).
PINRAG_YT_VISION_PROVIDER	openai	openai, anthropic ou openrouter. Independente de PINRAG_LLM_PROVIDER (LLM RAG e visão podem usar provedores diferentes). Alias legado: PINRAG_VISION_PROVIDER.
PINRAG_YT_VISION_MODEL	(por provedor)	Se não definido: OpenAI gpt-4o-mini, Anthropic claude-sonnet-4-6, OpenRouter google/gemini-2.5-flash. Use um ID com capacidade de visão. Alias legado: PINRAG_VISION_MODEL.
PINRAG_YT_VISION_MAX_FRAMES	8	Somente caminho de download + quadros (openai / anthropic): limite de quadros-chave analisados após detecção de cena. Ignorado para openrouter (solicitação de vídeo única).
PINRAG_YT_VISION_MIN_SCENE_SCORE	27.0	Somente caminho de download + quadros: limite de AdaptiveDetector do PySceneDetect (maior → menos cortes). Ignorado para openrouter.
PINRAG_YT_VISION_IMAGE_DETAIL	low	Somente caminho de quadros OpenAI: low, high ou auto para image_url.detail. Ignorado para anthropic (quadros completos) e openrouter (video_url).
LangSmith (opcional)
LANGSMITH_TRACING	(desativado)	Defina true para enviar rastreamentos ao LangSmith. Requer LANGSMITH_API_KEY.
LANGSMITH_API_KEY	(nenhum)	Chave de API das Configurações → Chaves de API do LangSmith.
LANGSMITH_PROJECT	(padrão LangChain)	Nome do projeto para rastreamentos (ex.: pinrag).
LANGSMITH_ENDPOINT	API dos EUA (implícita)	Workspaces da UE: defina https://eu.api.smith.langchain.com para que os rastreamentos cheguem ao seu projeto da UE. Se sua conta usa eu.smith.langchain.com no navegador, você precisa disso. Workspaces da região dos EUA podem omitir (host de API padrão).
Avaliadores (LLM como juiz)
PINRAG_EVALUATOR_PROVIDER	openai	openai, anthropic ou openrouter — qual LLM executa os avaliadores LLM-como-juiz. Usado apenas durante execuções de avaliação (experimentos LangSmith).
PINRAG_EVALUATOR_MODEL	(padrão do provedor)	Modelo para avaliação de correção (ex.: gpt-4o, claude-sonnet-4-6, openrouter/free quando o provedor avaliador é OpenRouter). Com OpenRouter, o roteador gratuito padrão pode alternar modelos; os avaliadores usam esquema JSON estrito — defina um slug gratuito específico de openrouter.ai/models se precisar de saída estruturada estável. As variáveis de ambiente de roteamento OpenRouter abaixo também se aplicam aos avaliadores quando PINRAG_EVALUATOR_PROVIDER=openrouter.
PINRAG_EVALUATOR_MODEL_CONTEXT	(padrão do provedor)	Modelo para avaliação de fundamentação (contexto recuperado grande; ex.: gpt-4o-mini, claude-haiku-4-5, openrouter/free quando o provedor avaliador é OpenRouter). Mesma nota do OpenRouter que PINRAG_EVALUATOR_MODEL. Quando o provedor avaliador é OpenRouter, PINRAG_OPENROUTER_MODEL_FALLBACKS, PINRAG_OPENROUTER_SORT e PINRAG_OPENROUTER_PROVIDER_ORDER se aplicam ao cliente avaliador.

Reindexação ao alterar o modelo de embedding: Alterar PINRAG_EMBEDDING_MODEL requer reindexação; as dimensões do vetor devem corresponder ao modelo usado no momento da indexação (incluindo índices criados sob um embedding padrão mais antigo).

Reindexação ao ativar pai-filho: Definir PINRAG_USE_PARENT_CHILD=true requer reindexação; a nova estrutura (fragmentos filhos no Chroma, fragmentos pai no docstore) é criada apenas durante a indexação para tipos de documento suportados (não .txt simples).

Reindexação ao alternar a visão do YouTube: Ativar ou desativar PINRAG_YT_VISION_ENABLED, alterar PINRAG_YT_VISION_PROVIDER ou alterar modelo de visão / PINRAG_YT_VISION_IMAGE_DETAIL / limites de quadros requer reindexação dos documentos do YouTube afetados para que os fragmentos reflitam o novo comportamento.

Monitoramento e Observabilidade

Para métricas de desempenho de consultas (latência, tempo, uso de tokens) e depuração, use LangSmith. Defina LANGSMITH_TRACING=true e LANGSMITH_API_KEY no MCP env ou no seu shell; opcionalmente, defina LANGSMITH_PROJECT (veja a tabela acima). Se o seu workspace LangSmith estiver na região da UE (você usa eu.smith.langchain.com no navegador), você deve também definir LANGSMITH_ENDPOINT=https://eu.api.smith.langchain.com; sem isso, os traces podem não aparecer na implantação da UE. Contas da região dos EUA usam o host de API padrão e não precisam de LANGSMITH_ENDPOINT. Veja notes/langsmith-setup.md para mais detalhes.

Para introspecção do lado do MCP, defina PINRAG_VERBOSE_LOGGING=true para exibir eventos de fase detalhados em notifications/message (por exemplo, carregamento de transcrição do YouTube, se a visão é executada e marcos de upsert de chunks).

Múltiplos provedores e coleções

A dimensão do vetor é fixa por coleção Chroma e deve corresponder ao PINRAG_EMBEDDING_MODEL usado quando os chunks foram gravados. O id padrão nomic-embed-text-v1.5 é um modelo Nomic de 768-d; outro valor de PINRAG_EMBEDDING_MODEL pode implicar em um tamanho diferente—verifique a documentação desse modelo.

• Padrão: PINRAG_COLLECTION_NAME tem como padrão pinrag. Não altere PINRAG_EMBEDDING_MODEL para uma coleção existente sem reindexar em uma nova coleção (ou apagar a antiga); caso contrário, adições/consultas podem falhar com erros de dimensão de embedding.
• Coleções por modelo: Use um par estável de PINRAG_EMBEDDING_MODEL + PINRAG_COLLECTION_NAME (+ PINRAG_PERSIST_DIR se você isolar armazenamentos) para cada índice. Para consultar uma coleção, defina os mesmos valores de env usados ao indexá-la. Você pode indexar as mesmas fontes novamente sob outro par (altere env, reinicie o MCP se necessário, execute add_document_tool).
• Ferramentas MCP: Cada ferramenta usa config.get_persist_dir() e config.get_collection_name() por padrão; collection opcional em uma chamada de ferramenta substitui o nome da coleção para essa solicitação. list_collections_tool lista os nomes das coleções no diretório de persistência configurado (substituição opcional de persist_dir).

Referência MCP

Ferramentas, prompt e recursos somente leitura do servidor MCP pinrag (FastMCP("PinRAG")). Os resultados das ferramentas são objetos JSON que sempre incluem _server_version; com PINRAG_VERBOSE_LOGGING=true eles podem incluir _verbose_log.

add_document_tool retorna indexed, failed, contagens, persist_directory, collection_name e fail_summary quando qualquer caminho falhou. query_tool retorna answer e sources (cada entrada: document_id, page—página do PDF, frequentemente 0 para não-PDF—além de start opcional em segundos para YouTube).

query_tool

Pergunta em linguagem natural; filtros opcionais restringem a recuperação ("" / omita quando não usado):

Parâmetro	Descrição
query	Pergunta (obrigatório)
document_id	Limitar a este documento — referência exata de list_documents_tool, título da lista ou radical exclusivo do nome de arquivo PDF
page_min, page_max	Intervalo de páginas PDF inclusivo (deve passar ambos; uma página: mesmo valor duas vezes)
tag	Apenas chunks com esta tag
document_type	pdf, youtube, discord, github, plaintext ou web
response_style	thorough ou concise. Vazio (padrão do esquema) ou qualquer outra string → resolvido via PINRAG_RESPONSE_STYLE (veja server.py: apenas esses dois literais substituem o env).

Os filtros podem ser combinados. A lista sources usa page para PDFs e start (segundos) para YouTube; as respostas podem mostrar rótulos t. M:SS derivados de start. Citações do GitHub usam rótulos p. N no estilo índice de chunk no texto da resposta. Fontes de documentação web carregam um source_url por página.

Exemplo: "O que é OpenOCD? No documento Pico, apenas páginas 16–17" → query_tool(query="What is OpenOCD?", document_id="RP-008276-DS-1-getting-started-with-pico.pdf", page_min=16, page_max=17).

add_document_tool

Indexa locais (PDF, texto simples ou .txt do Discord, diretórios), YouTube (URL de vídeo, URL de playlist ou id simples), URLs do GitHub (esquema opcional) ou sites de documentação web (qualquer URL http(s)). paths agrupa itens de trabalho; um caminho com falha não reverte os outros. Persiste apenas em PINRAG_PERSIST_DIR / PINRAG_COLLECTION_NAME (sem parâmetros MCP para esses).

Parâmetro	Descrição
paths	Lista obrigatória: arquivos, diretórios, URLs ou ids de vídeo
tags	Opcional; um por entrada de paths, mesma ordem
branch	Apenas GitHub: substituição de branch
include_patterns	Apenas GitHub: lista de inclusão glob
exclude_patterns	Apenas GitHub: lista de exclusão glob

list_documents_tool

Retorna documents, total_chunks, persist_directory, collection_name e document_details (tags, títulos, contagens, bytes agregado quando presente, upload_timestamp, etc.). Se tag estiver definido, total_chunks conta apenas chunks com essa tag (não a coleção inteira).

Parâmetro	Descrição
tag	Opcional: apenas documentos que tenham esta tag

remove_document_tool

Exclui todos os chunks para document_id. Aceita a referência exata de list_documents_tool, o título da lista ou um radical exclusivo de nome de arquivo PDF.

Parâmetro	Descrição
document_id	Obrigatório — referência exata, título da lista ou radical exclusivo de PDF

set_document_tag_tool

Define ou substitui o tag em cada chunk indexado para um documento. Útil para adicionar ou corrigir uma tag após a indexação, sem reindexar. Mesmas regras de direcionamento de documento que remove_document_tool.

Parâmetro	Descrição
document_id	Obrigatório — referência exata, título da lista ou radical exclusivo de PDF
tag	Obrigatório — string de tag não vazia
collection	Substituição opcional (padrão: PINRAG_COLLECTION_NAME)

MCP prompt: use_pinrag

Texto de roteamento integrado: request é interpolado como a primeira linha; o restante lista quando usar cada ferramenta e seus parâmetros (corresponde a use_pinrag em server.py). Listado onde o cliente expõe prompts MCP (ex.: Cursor).

Parâmetro	Descrição
request	Objetivo opcional do usuário (pode ser vazio)

Recursos MCP

Recurso	Descrição
pinrag://documents	Listagem em texto simples para a coleção configurada do servidor (de format_documents_list)
pinrag://server-config	Despejo imprimível do env/config efetivo (inclui PINRAG_VERSION, variáveis operacionais chave, presença de chave de API)

Executando testes

A partir da raiz do repositório, instale os extras de desenvolvimento (ex.: uv sync --extra dev).

• Rápido (sem integration):
  uv run pytest tests/ -q -m "not integration"
  Ignora qualquer coisa marcada como integration em pyproject.toml (rede, chaves de API, ativos opcionais, MCP stdio). Qualquer teste que use a fixture sample_pdf_path recebe esse marcador automaticamente em tests/conftest.py, então o PDF de exemplo em data/pdfs/ só é necessário para a execução completa.

• Suíte completa:
  uv run pytest tests/ -q

  Segredos: Para testes MCP stdio, o env do subprocesso começa a partir do seu shell, então qualquer OPENAI_API_KEY / ANTHROPIC_API_KEY ausente é preenchido a partir de tests/.mcp_stdio_integration.env (copie de tests/mcp_stdio_integration.env.example; apenas essas chaves são lidas do arquivo—env já definido vence). Substitua o arquivo com PINRAG_MCP_ITEST_ENV_FILE. Após a mesclagem, test_mcp_stdio_repo.py exige OPENAI_API_KEY, e PINRAG_LLM_PROVIDER deve passar na verificação de credenciais (ex.: exporte OPENROUTER_API_KEY ao usar OpenRouter). test_mcp_stdio_pypi.py também exige uma chave OpenAI funcional.

  PDF / stdio: O PDF padrão é data/pdfs/sample-text.pdf (não está no git). Substitua com PINRAG_MCP_ITEST_PDF / PINRAG_MCP_ITEST_QUERY. Testes stdio precisam de uv em PATH, ou defina PINRAG_TEST_UV para o caminho do binário.

  Teste MCP PyPI: Marcado como pypi_mcp; pule com -m "not pypi_mcp" ou PINRAG_MCP_ITEST_SKIP_PYPI=1. Fixe a instalação com PINRAG_MCP_ITEST_PYPI_SPEC (padrão pinrag = mais recente no PyPI).

  Verboso: --log-cli-level=INFO.

O diretório data/ é ignorado pelo git—crie data/pdfs/ (e similares) localmente; nada sob data/ é commitado.

Licença

Licença MIT. Texto completo em LICENSE.