PinRAG

PinRAG

Resumen

PinRAG es para cuando quieres aprender sobre algo y tus materiales están dispersos: PDFs y libros electrónicos, repositorios de GitHub, videos de YouTube, discusiones de Discord y notas simples. Indexas esos materiales en un índice RAG compartido y luego haces preguntas desde Cursor, VS Code (GitHub Copilot) o cualquier asistente compatible con MCP y obtienes respuestas con citas que apuntan a páginas, marcas de tiempo, archivos o hilos.

Internamente es Generación Aumentada por Recuperación construida con LangChain y expuesta como un servidor MCP (Protocolo de Contexto de Modelo): agrega documentos desde el editor, consulta con lenguaje natural, lista o elimina lo que indexaste. Las entradas admitidas incluyen PDFs, archivos de texto locales y directorios, exportaciones de Discord, YouTube (transcripción desde URL, lista de reproducción o ID) y URLs de repositorios de GitHub. Para YouTube puedes agregar opcionalmente visión para que el código en pantalla, los diagramas y el texto de la interfaz se fusionen con la transcripción en los mismos fragmentos—consulta Enriquecimiento de visión de YouTube.

Características

• Indexación multi-formato — PDF (.pdf), archivos o directorios locales, texto plano (.txt), exportación de Discord (.txt), YouTube (URL de video o lista de reproducción, o ID de video), repositorio de GitHub (URL), sitios de documentación web (URL)
• Visión de YouTube opcional — Desactivada por defecto. Cuando está habilitada, ejecuta un modelo de visión (OpenAI, Anthropic o video nativo de OpenRouter) y fusiona el contexto estructurado en pantalla con la transcripción para que los fragmentos RAG contengan nombres de código, etiquetas y diagramas buscables—no solo el habla. El modo OpenRouter evita la descarga local de ffmpeg/video; openai/anthropic usan fotogramas clave de escenas y requieren pinrag[vision] + ffmpeg (consulta Enriquecimiento de visión de YouTube)
• RAG con citas — Las respuestas citan el contexto de la fuente: página del PDF, marca de tiempo de YouTube, nombre del documento para texto plano y Discord, índice del fragmento para repositorios de GitHub, URL de origen para documentación web
• Etiquetas de documentos — Etiqueta documentos al momento de indexar (p. ej. AMIGA, PI_PICO) para búsqueda filtrada
• Filtrado de metadatos — query_tool admite document_id, tag, document_type, page_min/page_max de PDF y response_style (exhaustivo o conciso)
• Herramientas MCP — add_document_tool, query_tool, list_documents_tool, remove_document_tool, set_document_tag_tool, list_collections_tool; collection opcional en herramientas anula PINRAG_COLLECTION_NAME para esa llamada
• Recursos MCP — pinrag://documents (documentos indexados) y pinrag://server-config (variables de entorno y configuración); haz clic en el panel MCP de Cursor para verlos
• Prompt MCP — use_pinrag (parámetro: solicitud) para consultar, indexar, listar o eliminar documentos
• LLM configurable — OpenRouter (predeterminado, enrutador openrouter/free gratuito), OpenAI, Anthropic o Inferencia Cerebras (API compatible con OpenAI); se configura mediante PINRAG_LLM_PROVIDER y PINRAG_LLM_MODEL en env de MCP o en tu shell
• Embeddings locales — Nomic (PINRAG_EMBEDDING_MODEL, nomic-embed-text-v1.5 predeterminado); sin clave API; la primera ejecución descarga los pesos del modelo (~270 MB, en caché)
• Opciones de recuperación y fragmentación — Fragmentación consciente de la estructura (activada por defecto); re-clasificación FlashRank opcional, expansión de múltiples consultas y fragmentos padre-hijo para PDFs (consulta Configuración)
• Observabilidad — Notificaciones de herramientas MCP (ctx.log) más seguimiento opcional de LangSmith
• Construido con — LangChain, Chroma; OpenRouter, OpenAI, Anthropic, FlashRank opcionales

Instalación

Agrega PinRAG como servidor MCP en tu editor. Instala uv y asegúrate de que uvx esté en tu PATH—eso ejecuta PinRAG desde PyPI sin un pip install previo.

Cursor: agrega esto bajo mcpServers en ~/.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): ejecuta MCP: Open User Configuration desde la Paleta de Comandos (o agrega .vscode/mcp.json en un espacio de trabajo), luego fusiona esta forma—la clave de nivel superior es 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"
      }
    }
  }
}

Inicio rápido

Modo servidor HTTP

Para clientes que hablan MCP sobre HTTP (p. ej. pinrag-cli con --server), ejecuta:

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

Esto inicia un endpoint MCP HTTP transmisible en http://<host>:<port>/mcp. El comando pinrag stdio predeterminado para editores no cambia; pinrag server es aditivo. Conecta pinrag-cli con --server http://127.0.0.1:8765/mcp.

Configurar el servidor MCP

Coloca las claves API y cualquier configuración de PinRAG en el bloque env de la entrada MCP. El servidor no carga archivos .env cuando el editor lo inicia.

Uso en el chat

Acción	Herramienta
Indexar archivos, directorios o URLs	add_document_tool — paths requerido: lista de rutas locales (PDFs, .txt de texto plano o DiscordChatExporter, directorios) o URLs (videos de YouTube, URLs de listas de reproducción, repositorios de GitHub, sitios de documentación web; se permiten IDs de video de YouTube sin formato). tags opcional (uno por ruta). Solo para URLs de GitHub: branch, include_patterns, exclude_patterns.
Listar documentos indexados	list_documents_tool — devuelve documents (IDs), total_chunks y filtro tag opcional. document_details puede incluir document_type, etiquetas, recuentos de páginas / mensajes / segmentos, títulos, bytes agregado y upload_timestamp cuando esté presente en los metadatos.
Consultar con filtros	query_tool — query requerido. document_id, tag, document_type, page_min / page_max opcionales (rangos de PDF), response_style (thorough o concise; deja vacío para usar PINRAG_RESPONSE_STYLE).
Eliminar un documento	remove_document_tool — document_id requerido (valor exacto de list_documents_tool).
Ver recursos (solo lectura)	En el panel MCP, abre Resources y elige pinrag://documents (documentos indexados) o pinrag://server-config (configuración efectiva, incluido PINRAG_VERSION).

Pregunta en el chat: "Agrega /ruta/al/libro-amiga.pdf con la etiqueta AMIGA", "Indexa https://youtu.be/xyz y pregunta qué dice", "Indexa https://github.com/owner/repo y pregunta sobre el código base" o "Indexa https://docs.langchain.com/ y resume sus APIs de memoria". La IA invocará las herramientas por ti. Las citas muestran números de página para PDFs, marcas de tiempo (p. ej. t. 1:23) para YouTube, nombres de documentos para texto plano y exportaciones de Discord, etiquetas de índice de fragmentos para GitHub y URLs de origen para documentación web.

Indexación de GitHub

Indexa un repositorio con add_document_tool y una URL en paths, p. ej. https://github.com/owner/repo, https://github.com/owner/repo/tree/branch o github.com/owner/repo (esquema opcional).

Opciones solo de GitHub: branch, include_patterns / exclude_patterns — los valores predeterminados ya favorecen archivos de texto y código comunes y omiten artefactos voluminosos; usa patrones cuando necesites archivos fuera de ese conjunto. Se omiten archivos de más de PINRAG_GITHUB_MAX_FILE_BYTES (512 KiB predeterminado).

Autenticación: Configura GITHUB_TOKEN en env de MCP (o en el shell) para repositorios privados o para reducir los límites de tasa en índices grandes; las ejecuciones públicas pequeñas a menudo funcionan sin ello. Usa un PAT clásico o de grano fino con acceso de lectura al repositorio; no hay OAuth en PinRAG.

Indexación de documentación web

Apunta add_document_tool a cualquier URL de sitio de documentación, p. ej. https://docs.langchain.com/, https://docs.crewai.com/ o https://picocomputer.github.io/. PinRAG descubre páginas mediante (en orden) llms.txt / llms-full.txt (estilo Mintlify), sitemap.xml (incluidos los consejos robots.txt Sitemap: y los índices de mapas de sitio anidados), luego un rastreo BFS con alcance desde la URL semilla.

Alcance: coincidencia exacta de host (sin subdominios) más prefijo de ruta derivado de la semilla—p. ej. https://docs.example.com/guide/ solo indexa páginas bajo /guide/. Usa la URL raíz del sitio para capturar todo el árbol de documentación.

Extracción: las respuestas text/markdown (de rutas rápidas de llms.txt) pasan; el HTML pasa por trafilatura con un respaldo de BeautifulSoup + markdownify que se limita a <main> / <article> / [role=main].

Límites y cortesía: controlados por PINRAG_WEB_MAX_PAGES (200 predeterminado), 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) y PINRAG_WEB_RESPECT_ROBOTS (true). Algunos sitios (p. ej. páginas protegidas por Cloudflare) pueden devolver 403 a clientes de Python puro; esa es una limitación conocida.

Citas: los fragmentos web llevan un campo de metadatos source_url; las respuestas citan URLs por página, y el document_id es <host><path_prefix> para que remove_document_tool / set_document_tag_tool operen en todo el sitio a la vez.

Indexación de YouTube y bloqueo de IP

La indexación con muchas transcripciones—especialmente desde IPs de nube o de alto volumen—puede devolver errores como "YouTube está bloqueando solicitudes desde tu IP". Apunta youtube-transcript-api a un proxy mediante env de MCP (o tu 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_* afecta solo la obtención de transcripciones; los pasos de yt-dlp (títulos, listas de reproducción) no lo usan. Los proxies residenciales o rotativos suelen funcionar mejor que las IPs de centros de datos sin procesar.

Cuando algunas rutas fallan (p. ej. algunos videos en una lista de reproducción), add_document_tool incluye fail_summary con recuentos clave por blocked, disabled, missing_transcript y other.

Enriquecimiento de visión de YouTube (opcional)

La indexación predeterminada es solo transcripción. Configura PINRAG_YT_VISION_ENABLED=true para agregar subtítulos de visión para el contenido en pantalla, alineados en el tiempo con la transcripción y fragmentados con metadatos como has_visual, frame_count y visual_source.

PINRAG_YT_VISION_PROVIDER:

• openai (predeterminado) o anthropic: descarga de yt-dlp → fotogramas basados en escenas → una llamada multimodal por fotograma. Necesita pinrag[vision], ffmpeg/ffprobe en PATH y OPENAI_API_KEY o ANTHROPIC_API_KEY (instala el extra en el mismo entorno que pinrag, p. ej. uv sync --extra vision o pip install 'pinrag[vision]').
• openrouter: una solicitud de OpenRouter por video mediante video_url (predeterminado google/gemini-2.5-flash). OPENROUTER_API_KEY solamente—sin descarga, ffmpeg ni pinrag[vision]; elige un modelo con capacidad de video si anulas PINRAG_YT_VISION_MODEL.

Operaciones: Re-indexa después de cambiar la configuración de visión. Para openai/anthropic, ajusta el costo y los tiempos de espera con PINRAG_YT_VISION_MAX_FRAMES y PINRAG_YT_VISION_IMAGE_DETAIL=high opcional (texto pequeño más claro, más tokens). MCP stdio: el progreso de yt-dlp va a stderr para que stdout permanezca limpio en JSON. Descargar video puede violar los Términos de Servicio de YouTube o las reglas locales—tu decisión. Docker: compila con BUILD_WITH_VISION=1 para ffmpeg + pinrag[vision] (consulta Dockerfile).

Consejos

• pinrag no encontrado: MCP hereda tu PATH de inicio de sesión. Después de pipx o uv tool install, reinicia el editor y confirma which pinrag.
• PINRAG_PERSIST_DIR: Usa una ruta absoluta estable en env de MCP (p. ej. ~/.pinrag/chroma_db) para que el almacén de vectores no dependa del cwd del proceso del servidor.
• FlashRank: Instala pinrag[rerank] en el mismo entorno de herramientas (pipx install 'pinrag[rerank]' / uv tool install 'pinrag[rerank]'); los ajustes están en Configuración.
• Visión de YouTube: Sigue Enriquecimiento de visión de YouTube para entorno y dependencias; re-indexa después de cambiar la configuración de visión.
• pinrag://server-config: MCP Resources → esta URI para PINRAG_VERSION, LLM/embeddings/fragmentación efectivos y estado de clave API configurada / no configurada.

Configuración

El recurso MCP pinrag://server-config imprime PINRAG_VERSION (versión del paquete, no una variable de entorno que configures) y los valores efectivos de las variables a continuación, además de qué claves API están configuradas. Usa la tabla como referencia completa de entorno.

Variables de entorno:

Variable	Valor por defecto	Descripción
LLM
Proveedor y modelo
PINRAG_LLM_PROVIDER	openrouter	openrouter, openai, anthropic o cerebras
PINRAG_LLM_MODEL	(predeterminado del proveedor)	Cuando no se establece: OpenRouter openrouter/free, OpenAI gpt-4o-mini, Anthropic claude-haiku-4-5, Cerebras llama3.1-8b. Se puede sobrescribir con cualquier ID de modelo (p. ej., OpenRouter anthropic/claude-sonnet-4-6, Cerebras gpt-oss-120b).
OpenRouter
PINRAG_OPENROUTER_MODEL_FALLBACKS	(sin establecer)	Lista de slugs de modelos de respaldo separados por comas enviados como la lista models de OpenRouter. La puerta de enlace intenta el siguiente slug cuando el principal (PINRAG_LLM_MODEL) falla (límites de tasa, tiempo de inactividad, etc.). Usa modelos gratuitos adicionales aquí para mantener el costo en cero. Alias heredado: PINRAG_LLM_MODEL_FALLBACKS.
PINRAG_OPENROUTER_SORT	(sin establecer)	provider.sort opcional — price, throughput o latency. Cuando no se establece, OpenRouter usa su selección de proveedor predeterminada. Prefiere dejarlo sin establecer si configuras PINRAG_OPENROUTER_PROVIDER_ORDER para fijar un backend específico (evita señales de enrutamiento conflictivas).
PINRAG_OPENROUTER_PROVIDER_ORDER	(sin establecer)	Nombres de proveedores separados por comas para provider.order (probados en secuencia). Ejemplo: Cerebras con PINRAG_LLM_MODEL=openai/gpt-oss-120b para preferir enrutamiento respaldado por Cerebras. Usa etiquetas exactas de la lista de proveedores del modelo en OpenRouter.
OPENROUTER_APP_URL	https://github.com/ndjordjevic/pinrag	Atribución de la aplicación (HTTP-Referer). Sobrescribe con la URL de tu sitio (consulta atribución de aplicaciones de OpenRouter). PinRAG copia esto en OPENROUTER_HTTP_REFERER para el SDK de Python de OpenRouter.
OPENROUTER_APP_TITLE	PinRAG	Título de la aplicación (X-Title). Sobrescribe para etiquetar el uso en el panel de OpenRouter. PinRAG copia esto en OPENROUTER_X_OPEN_ROUTER_TITLE para el SDK.
Claves de API
OPENROUTER_API_KEY	(requerida al usar OpenRouter para LLM, evaluadores o visión de YouTube)	Requerida cuando PINRAG_LLM_PROVIDER=openrouter, PINRAG_EVALUATOR_PROVIDER=openrouter o visión de YouTube con PINRAG_YT_VISION_PROVIDER=openrouter.
OPENAI_API_KEY	(requerida para LLM de OpenAI o visión de YouTube con OpenAI)	Requerida cuando PINRAG_LLM_PROVIDER=openai, o cuando PINRAG_YT_VISION_ENABLED=true y PINRAG_YT_VISION_PROVIDER=openai.
OPENAI_BASE_URL	(opcional)	Sobrescribe la URL base de la API de OpenAI (p. ej., https://openrouter.ai/api/v1 con OPENAI_API_KEY configurado con tu clave de OpenRouter para visión u otras llamadas compatibles con OpenAI).
CEREBRAS_API_KEY	(requerida para LLM de Cerebras)	Requerida cuando PINRAG_LLM_PROVIDER=cerebras. Obtén una clave en la consola en la nube de Cerebras.
PINRAG_CEREBRAS_BASE_URL	https://api.cerebras.ai/v1	Sobrescribe la URL base compatible con OpenAI para Cerebras (p. ej., endpoints de inferencia dedicados).
ANTHROPIC_API_KEY	(requerida para LLM de Anthropic o visión de YouTube con Anthropic)	Requerida cuando PINRAG_LLM_PROVIDER=anthropic, PINRAG_EVALUATOR_PROVIDER=anthropic o visión de YouTube con PINRAG_YT_VISION_PROVIDER=anthropic.
Embeddings
PINRAG_EMBEDDING_MODEL	nomic-embed-text-v1.5	ID del modelo local Nomic (a través de langchain-nomic). La primera ejecución descarga los pesos (~270 MB, en caché). Sin clave de API.
Almacenamiento y fragmentación
PINRAG_PERSIST_DIR	chroma_db	Directorio del almacén de vectores Chroma (el valor predeterminado es relativo al directorio de trabajo del proceso del servidor a menos que establezcas una ruta absoluta; p. ej., ~/.pinrag/chroma_db para una ubicación fija)
PINRAG_CHUNK_SIZE	1000	Tamaño del fragmento de texto (caracteres)
PINRAG_CHUNK_OVERLAP	200	Superposición de fragmentos (caracteres)
PINRAG_STRUCTURE_AWARE_CHUNKING	true	Aplica heurísticas de fragmentación conscientes de la estructura para límites de código/tablas
PINRAG_COLLECTION_NAME	pinrag	Nombre de la colección de Chroma. Una única colección compartida por defecto.
ANONYMIZED_TELEMETRY	False a través de setdefault cuando no se establece	Indicador de telemetría de Chroma. La configuración de registro MCP de PinRAG llama a os.environ.setdefault("ANONYMIZED_TELEMETRY", "False") para que vacío/sin establecer se comporte como exclusión voluntaria; establece true en env si deseas activar la telemetría de Chroma.
Recuperación
PINRAG_RETRIEVE_K	20	Tamaño del grupo de recuperación cuando el reordenamiento está desactivado. Cuando el reordenamiento está activado, PINRAG_RERANK_RETRIEVE_K recurre a este valor si no se establece, luego los resultados se recortan a PINRAG_RERANK_TOP_N.
Recuperación padre-hijo
PINRAG_USE_PARENT_CHILD	false	Establece en true para incrustar fragmentos pequeños y devolver fragmentos padre más grandes (compatible con indexación de PDF, GitHub, YouTube y Discord, no con .txt simple). Requiere reindexación.
PINRAG_PARENT_CHUNK_SIZE	2000	Tamaño del fragmento padre (caracteres) cuando PINRAG_USE_PARENT_CHILD=true.
PINRAG_CHILD_CHUNK_SIZE	800	Tamaño del fragmento hijo (caracteres) cuando PINRAG_USE_PARENT_CHILD=true.
Reordenamiento
PINRAG_USE_RERANK	false	Establece en true para habilitar el reordenamiento FlashRank: obtén más fragmentos, vuelve a puntuar localmente, pasa los N principales al LLM. Requiere pip install pinrag[rerank] y no necesita clave de API.
PINRAG_RERANK_RETRIEVE_K	(hereda PINRAG_RETRIEVE_K)	Fragmentos a obtener antes de FlashRank cuando PINRAG_USE_RERANK=true. Si no se establece, equivale a PINRAG_RETRIEVE_K (no un 20 codificado por separado).
PINRAG_RERANK_TOP_N	10	Fragmentos pasados al LLM después del reordenamiento cuando PINRAG_USE_RERANK=true (limitado por el tamaño de obtención previo al reordenamiento).
Multi-consulta
PINRAG_USE_MULTI_QUERY	false	Establece en true para generar formulaciones alternativas de la consulta del usuario mediante LLM, recuperar por variante y fusionar (unión única). Mejora la recuperación para consultas breves o ambiguas.
PINRAG_MULTI_QUERY_COUNT	4	Número de consultas alternativas a generar (predeterminado 4, máximo 10). La consulta original aún se incluye en la recuperación al fusionar.
Estilo de respuesta
PINRAG_RESPONSE_STYLE	thorough	Estilo de respuesta RAG: thorough (detallado) o concise. Usado por el objetivo de evaluación y como predeterminado cuando el MCP query omite response_style.
Notificaciones MCP
PINRAG_VERBOSE_LOGGING	false	Establece true para emitir notificaciones MCP detalladas por fase para la ejecución de herramientas/recursos (detección de formato, carga de transcripción, ruta/pasos de visión, inserciones de fragmentos). El valor predeterminado mantiene registros de ciclo de vida concisos de inicio/ok/error.
Indexación de GitHub
GITHUB_TOKEN	(opcional)	Token de acceso personal para la API de GitHub. Requerido para repositorios privados; aumenta los límites de tasa para repositorios públicos.
PINRAG_GITHUB_MAX_FILE_BYTES	524288 (512 KB)	Omite archivos más grandes que esto al indexar repositorios de GitHub.
PINRAG_GITHUB_DEFAULT_BRANCH	main	Rama predeterminada cuando no se especifica en la URL de GitHub.
Indexación de texto plano
PINRAG_PLAINTEXT_MAX_FILE_BYTES	524288 (512 KB)	Omite archivos .txt planos más grandes que esto al indexar.
Indexación de documentos web
PINRAG_WEB_MAX_PAGES	200	Máximo de páginas obtenidas por ejecución de indexación web.
PINRAG_WEB_MAX_DEPTH	5	Profundidad máxima de rastreo BFS desde la URL semilla (ignorado para rutas rápidas de llms.txt / sitemap).
PINRAG_WEB_MAX_PAGE_BYTES	1048576 (1 MiB)	Omite páginas cuyo cuerpo de respuesta exceda este tamaño.
PINRAG_WEB_REQUEST_TIMEOUT	20	Tiempo de espera HTTP por solicitud en segundos (conexión + lectura).
PINRAG_WEB_CONCURRENCY	4	Máximo de obtenciones concurrentes por host.
PINRAG_WEB_RATE_LIMIT_PER_HOST	2.0	Tasa de recarga del token-bucket (solicitudes / segundo) por host.
PINRAG_WEB_USER_AGENT	PinRAGBot/<version> (+https://github.com/ndjordjevic/pinrag)	Encabezado HTTP User-Agent para indexación web. Algunos sitios bloquean bots genéricos; sobrescribe si es necesario.
PINRAG_WEB_RESPECT_ROBOTS	true	true / false — respeta las reglas de exclusión de robots.txt al rastrear.
PINRAG_WEB_PREFER_LLMS_TXT	true	Intenta llms.txt / llms-full.txt antes de sitemap / BFS. Desactiva para forzar el descubrimiento por sitemap o rastreo.
Proxy de transcripción de YouTube
PINRAG_YT_PROXY_HTTP_URL	(ninguno)	URL del proxy HTTP para obtenciones de transcripción (p. ej., http://user:pass@proxy:80). Úsalo cuando YouTube bloquee tu IP.
PINRAG_YT_PROXY_HTTPS_URL	(ninguno)	URL del proxy HTTPS para obtenciones de transcripción. Igual que HTTP al usar un proxy genérico.
Visión de YouTube (opcional)
PINRAG_YT_VISION_ENABLED	false	true / 1 / yes / on habilita el enriquecimiento en pantalla para YouTube. openai / anthropic: necesita pinrag[vision], ffmpeg en PATH y la clave de API correspondiente. openrouter: necesita solo OPENROUTER_API_KEY (ruta nativa de video_url; sin descarga local).
PINRAG_YT_VISION_PROVIDER	openai	openai, anthropic o openrouter. Independiente de PINRAG_LLM_PROVIDER (el LLM RAG y la visión pueden usar diferentes proveedores). Alias heredado: PINRAG_VISION_PROVIDER.
PINRAG_YT_VISION_MODEL	(por proveedor)	Si no se establece: OpenAI gpt-4o-mini, Anthropic claude-sonnet-4-6, OpenRouter google/gemini-2.5-flash. Usa un ID capaz de visión. Alias heredado: PINRAG_VISION_MODEL.
PINRAG_YT_VISION_MAX_FRAMES	8	Solo ruta de descarga + fotogramas (openai / anthropic): limita los fotogramas clave analizados después de la detección de escenas. Ignorado para openrouter (solicitud de video única).
PINRAG_YT_VISION_MIN_SCENE_SCORE	27.0	Solo ruta de descarga + fotogramas: umbral de AdaptiveDetector de PySceneDetect (más alto → menos cortes). Ignorado para openrouter.
PINRAG_YT_VISION_IMAGE_DETAIL	low	Solo ruta de fotogramas de OpenAI: low, high o auto para image_url.detail. Ignorado para anthropic (fotogramas completos) y openrouter (video_url).
LangSmith (opcional)
LANGSMITH_TRACING	(desactivado)	Establece true para enviar trazas a LangSmith. Requiere LANGSMITH_API_KEY.
LANGSMITH_API_KEY	(ninguno)	Clave de API de LangSmith Configuración → Claves de API.
LANGSMITH_PROJECT	(predeterminado de LangChain)	Nombre del proyecto para trazas (p. ej., pinrag).
LANGSMITH_ENDPOINT	API de EE. UU. (implícita)	Espacios de trabajo de la UE: establece https://eu.api.smith.langchain.com para que las trazas lleguen a tu proyecto de la UE. Si tu cuenta usa eu.smith.langchain.com en el navegador, necesitas esto. Los espacios de trabajo de la región de EE. UU. pueden omitirlo (host de API predeterminado).
Evaluadores (LLM como juez)
PINRAG_EVALUATOR_PROVIDER	openai	openai, anthropic o openrouter — qué LLM ejecuta los evaluadores LLM-como-juez. Se usa solo durante ejecuciones de evaluación (experimentos de LangSmith).
PINRAG_EVALUATOR_MODEL	(predeterminado del proveedor)	Modelo para calificación de corrección (p. ej., gpt-4o, claude-sonnet-4-6, openrouter/free cuando el proveedor evaluador es OpenRouter). Con OpenRouter, el enrutador gratuito predeterminado puede rotar modelos; los evaluadores usan un esquema JSON estricto—establece esto a un slug gratuito específico de openrouter.ai/models si necesitas salida estructurada estable. Las variables de entorno de enrutamiento de OpenRouter a continuación también se aplican a los evaluadores cuando PINRAG_EVALUATOR_PROVIDER=openrouter.
PINRAG_EVALUATOR_MODEL_CONTEXT	(predeterminado del proveedor)	Modelo para calificación de fundamentación (contexto recuperado grande; p. ej., gpt-4o-mini, claude-haiku-4-5, openrouter/free cuando el proveedor evaluador es OpenRouter). Misma nota de OpenRouter que PINRAG_EVALUATOR_MODEL. Cuando el proveedor evaluador es OpenRouter, PINRAG_OPENROUTER_MODEL_FALLBACKS, PINRAG_OPENROUTER_SORT y PINRAG_OPENROUTER_PROVIDER_ORDER se aplican al cliente evaluador.

Reindexación al cambiar el modelo de embedding: Cambiar PINRAG_EMBEDDING_MODEL requiere reindexación; las dimensiones del vector deben coincidir con el modelo usado en el momento de la indexación (incluidos los índices creados bajo un embedding predeterminado más antiguo).

Reindexación al habilitar padre-hijo: Establecer PINRAG_USE_PARENT_CHILD=true requiere reindexación; la nueva estructura (fragmentos hijos en Chroma, fragmentos padre en docstore) se crea solo durante la indexación para tipos de documentos compatibles (no .txt simple).

Reindexación al alternar visión de YouTube: Activar o desactivar PINRAG_YT_VISION_ENABLED, cambiar PINRAG_YT_VISION_PROVIDER, o cambiar el modelo de visión / PINRAG_YT_VISION_IMAGE_DETAIL / límites de fotogramas, requiere reindexar los documentos de YouTube afectados para que los fragmentos reflejen el nuevo comportamiento.

Monitoreo y Observabilidad

Para métricas de rendimiento de consultas (latencia, tiempos, uso de tokens) y depuración, usa LangSmith. Configura LANGSMITH_TRACING=true y LANGSMITH_API_KEY en MCP env o en tu shell; opcionalmente configura LANGSMITH_PROJECT (consulta la tabla anterior). Si tu espacio de trabajo de LangSmith está en la región de la UE (usas eu.smith.langchain.com en el navegador), debes configurar también LANGSMITH_ENDPOINT=https://eu.api.smith.langchain.com; sin ello, los traces pueden no aparecer en la implementación de la UE. Las cuentas de la región de EE. UU. usan el host de API predeterminado y no necesitan LANGSMITH_ENDPOINT. Consulta notes/langsmith-setup.md para más detalle.

Para introspección del lado de MCP, configura PINRAG_VERBOSE_LOGGING=true para mostrar eventos de fase detallados en notifications/message (p. ej., carga de transcripciones de YouTube, si se ejecuta visión y hitos de inserción de chunks).

Múltiples proveedores y colecciones

La dimensión vectorial es fija por colección de Chroma y debe coincidir con el PINRAG_EMBEDDING_MODEL usado al escribir los chunks. El id predeterminado nomic-embed-text-v1.5 es un modelo Nomic de 768-d; otro valor de PINRAG_EMBEDDING_MODEL puede implicar un tamaño diferente—consulta la documentación de ese modelo.

• Predeterminado: PINRAG_COLLECTION_NAME por defecto es pinrag. No cambies PINRAG_EMBEDDING_MODEL para una colección existente sin reindexar en una colección nueva (o borrar la anterior); de lo contrario, las adiciones/consultas pueden fallar con errores de dimensión de embeddings.
• Colecciones por modelo: Usa un par estable de PINRAG_EMBEDDING_MODEL + PINRAG_COLLECTION_NAME (+ PINRAG_PERSIST_DIR si aíslas almacenes) para cada índice. Para consultar una colección, configura los mismos valores de entorno que usaste al indexarla. Puedes indexar las mismas fuentes nuevamente bajo otro par (cambia env, reinicia MCP si es necesario, ejecuta add_document_tool).
• Herramientas MCP: Cada herramienta usa config.get_persist_dir() y config.get_collection_name() por defecto; el collection opcional en una llamada de herramienta anula el nombre de la colección para esa solicitud. list_collections_tool lista los nombres de colecciones en el directorio de persistencia configurado (anulación opcional de persist_dir).

Referencia de MCP

Herramientas, prompt y recursos de solo lectura del servidor MCP pinrag (FastMCP("PinRAG")). Los resultados de las herramientas son objetos JSON que siempre incluyen _server_version; con PINRAG_VERBOSE_LOGGING=true pueden incluir _verbose_log.

add_document_tool devuelve indexed, failed, conteos, persist_directory, collection_name y fail_summary cuando alguna ruta falla. query_tool devuelve answer y sources (cada entrada: document_id, page—página de PDF, a menudo 0 para no-PDF—más start opcional en segundos para YouTube).

query_tool

Pregunta en lenguaje natural; los filtros opcionales limitan la recuperación ("" / omite cuando no se use):

Parámetro	Descripción
query	Pregunta (obligatoria)
document_id	Limitar a este documento — ref exacta de list_documents_tool, título de lista o tallo único de nombre de archivo PDF
page_min, page_max	Rango de páginas PDF inclusivo (deben pasarse ambos; una página: mismo valor dos veces)
tag	Solo chunks con esta etiqueta
document_type	pdf, youtube, discord, github, plaintext o web
response_style	thorough o concise. Vacío (el predeterminado del esquema) o cualquier otra cadena → resuelto vía PINRAG_RESPONSE_STYLE (consulta server.py: solo esos dos literales anulan el entorno).

Los filtros se pueden combinar. La lista sources usa page para PDFs y start (segundos) para YouTube; las respuestas pueden mostrar etiquetas t. M:SS derivadas de start. Las citas de GitHub usan etiquetas de estilo índice de chunk p. N en el texto de la respuesta. Las fuentes de sitios web llevan un source_url por página.

Ejemplo: "¿Qué es OpenOCD? En el doc de Pico, páginas 16–17 solamente" → 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 locales (PDF, .txt de texto plano o Discord, directorios), YouTube (URL de video, URL de lista de reproducción o id simple), URLs de GitHub (esquema opcional) o sitios de documentación web (cualquier URL http(s)). paths procesa elementos de trabajo en lotes; una ruta fallida no revierte las demás. Persiste solo en PINRAG_PERSIST_DIR / PINRAG_COLLECTION_NAME (sin parámetros MCP para esos).

Parámetro	Descripción
paths	Lista obligatoria: archivos, directorios, URLs o ids de video
tags	Opcional; uno por entrada de paths, mismo orden
branch	Solo GitHub: anulación de rama
include_patterns	Solo GitHub: lista de inclusión glob
exclude_patterns	Solo GitHub: lista de exclusión glob

list_documents_tool

Devuelve documents, total_chunks, persist_directory, collection_name y document_details (etiquetas, títulos, conteos, bytes agregado cuando está presente, upload_timestamp, etc.). Si tag está configurado, total_chunks cuenta solo chunks con esa etiqueta (no toda la colección).

Parámetro	Descripción
tag	Opcional: solo documentos que tengan esta etiqueta

remove_document_tool

Elimina cada chunk para document_id. Acepta la ref exacta de list_documents_tool, el título de la lista o un tallo único de nombre de archivo PDF.

Parámetro	Descripción
document_id	Obligatorio — ref exacta, título de lista o tallo único de PDF

set_document_tag_tool

Establece o reemplaza el tag en cada chunk indexado para un documento. Útil para agregar o corregir una etiqueta después de indexar, sin reindexar. Mismas reglas de selección de documento que remove_document_tool.

Parámetro	Descripción
document_id	Obligatorio — ref exacta, título de lista o tallo único de PDF
tag	Obligatorio — cadena de etiqueta no vacía
collection	Anulación opcional (predeterminado: PINRAG_COLLECTION_NAME)

Prompt de MCP: use_pinrag

Texto de enrutamiento integrado: request se interpola como la primera línea; el resto lista cuándo usar cada herramienta y sus parámetros (coincide con use_pinrag en server.py). Se muestra donde el cliente expone prompts de MCP (p. ej., Cursor).

Parámetro	Descripción
request	Objetivo de usuario opcional (puede estar vacío)

Recursos de MCP

Recurso	Descripción
pinrag://documents	Listado en texto plano para la colección configurada del servidor (de format_documents_list)
pinrag://server-config	Volcado imprimible de env/config efectivo (incluye PINRAG_VERSION, variables operativas clave, presencia de clave API)

Ejecución de pruebas

Desde la raíz del repositorio, instala extras de desarrollo (p. ej., uv sync --extra dev).

• Rápido (sin integration):
  uv run pytest tests/ -q -m "not integration"
  Omite cualquier cosa marcada como integration en pyproject.toml (red, claves API, activos opcionales, MCP stdio). Cualquier prueba que use el fixture sample_pdf_path obtiene ese marcador automáticamente en tests/conftest.py, por lo que el PDF de muestra bajo data/pdfs/ solo se necesita para la ejecución completa.

• Suite completa:
  uv run pytest tests/ -q

  Secretos: Para pruebas de MCP stdio, el entorno del subproceso comienza desde tu shell, luego cualquier OPENAI_API_KEY / ANTHROPIC_API_KEY faltante se completa desde tests/.mcp_stdio_integration.env (copia de tests/mcp_stdio_integration.env.example; solo esas claves se leen del archivo—el entorno ya configurado gana). Anula el archivo con PINRAG_MCP_ITEST_ENV_FILE. Después de la fusión, test_mcp_stdio_repo.py requiere OPENAI_API_KEY, y PINRAG_LLM_PROVIDER debe pasar su verificación de credenciales (p. ej., exporta OPENROUTER_API_KEY cuando uses OpenRouter). test_mcp_stdio_pypi.py también requiere una clave de OpenAI funcional.

  PDF / stdio: El PDF predeterminado es data/pdfs/sample-text.pdf (no en git). Anula con PINRAG_MCP_ITEST_PDF / PINRAG_MCP_ITEST_QUERY. Las pruebas de stdio necesitan uv en PATH, o configura PINRAG_TEST_UV con la ruta del binario.

  Prueba de MCP PyPI: Marcada como pypi_mcp; omite con -m "not pypi_mcp" o PINRAG_MCP_ITEST_SKIP_PYPI=1. Fija la instalación con PINRAG_MCP_ITEST_PYPI_SPEC (predeterminado pinrag = último en PyPI).

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

El directorio data/ está en gitignore—crea data/pdfs/ (y similares) localmente; nada bajo data/ se confirma.

Licencia

Licencia MIT. Texto completo en LICENSE.