arXiv Research-Concept Companion

Un agente de estudio-compañero de IA/ML (tarea de KSE Agentic Lab). Lee una nota de resumen de conceptos de tu bóveda de Obsidian, encuentra artículos relacionados de arXiv, puntúa cada uno según su relevancia temática e impacto de citas ajustado por edad, encuentra los artículos bien establecidos en los que se basa un candidato superviviente y escribe los hallazgos de vuelta en la bóveda.

• Servidor MCP existente (Parte A): Obsidian Local REST API MCP.

• Servidor MCP personalizado (Parte B): custom_server/ — aplicación FastMCP, 3 herramientas sobre las APIs públicas de arXiv y OpenAlex (sin autenticación).

• Agente: agent/ — un Agent de PydanticAI (respaldado por OpenRouter) que mantiene ambas conexiones MCP como conjuntos de herramientas, orquestado por una máquina de estados de LangGraph.

Requisitos previos

• Python 3.12+, uv.

• Una clave de API de OpenRouter.

• Obsidian con el plugin de la comunidad Local REST API instalado y en ejecución, y un servidor MCP que se comunique con él (cualquier implementación de MCP de Obsidian Local REST API — el comando de lanzamiento es configurable, ver más abajo).

Related MCP server: arxiv-mcp

Instalación

uv sync
cp .env.example .env

Rellena .env:

Ejecución

Dos procesos independientes, que comparten un proyecto uv:

# process 1 — the custom MCP server (arXiv + OpenAlex)
uv run python -m custom_server.server

# process 2 — the agent (connects to both MCP servers), driven by a free-text prompt
uv run python -m agent.graph "Find papers related to my 'Transformers Concept Note'"

agent/graph.py lanza custom_server/server.py como subproceso stdio, por lo que el proceso 2 no necesita que el proceso 1 ya esté en ejecución — los dos comandos anteriores solo demuestran que cada uno se puede iniciar de forma independiente.

El prompt no es un título de nota literal — el primer paso del agente (parse_prompt) utiliza una llamada LLM para identificar a qué nota de Obsidian se refiere el prompt. Si no puede identificar una, la ejecución se detiene inmediatamente e imprime "Información insuficiente: no se nombró ninguna nota o página de Obsidian en el prompt." sin tocar Obsidian. Si la nota que encuentra no produce suficientes palabras clave de concepto (menos de min_keywords, por defecto 2), la ejecución se detiene después de leerla e imprime un mensaje similar de "información insuficiente" en lugar de buscar en arXiv.

Modo sin conexión / reproducción

El servidor personalizado llama a tres APIs de red en vivo (arXiv, OpenAlex, OpenRouter). Al establecer CUSTOM_SERVER_OFFLINE=1, sus herramientas se sirven desde fixtures grabados en custom_server/fixtures/ en su lugar — no se requiere acceso a la red ni OPENROUTER_API_KEY. Útil para una demo/defensa sin red fiable, o para iteración rápida.

CUSTOM_SERVER_OFFLINE=1 uv run python -m custom_server.server

Lo que está cubierto: search_arxiv_papers (un feed de búsqueda grabado, servido para cualquier consulta — ver limitación abajo), y score_paper_relevance / find_foundational_citations para dos artículos grabados, GPT-3 (2005.14165) y ResNet (1512.03385).

Limitaciones conocidas:

• search_arxiv_papers es agnóstico a la consulta en modo sin conexión — siempre devuelve el mismo feed grabado independientemente del texto de la consulta.

• score_paper_relevance y find_foundational_citations solo reconocen los dos artículos grabados anteriores. Un arxiv_id no grabado lanza PaperNotFoundError (el mismo error que produciría un fallo real de OpenAlex); un título de artículo no grabado pasado a score_paper_relevance lanza FixtureNotFoundError — distinguible, no una respuesta incorrecta silenciosa.

Para regenerar o ampliar los fixtures: uv run python -m custom_server.fixtures.record vuelve a obtener las respuestas grabadas de arXiv/OpenAlex (ambas APIs públicas, sin autenticación) y sobrescribe los archivos JSON/XML en custom_server/fixtures/. Para añadir un nuevo artículo, añade sus dos llamadas httpx.get a record.py y una entrada correspondiente a relevance_scores.json (escrita a mano — no es salida real de OpenRouter, ya que grabar su respuesta cruda de chat-completion no vale la pena por la fragilidad del formato de cable; los campos estructurados {relevance, novelty, rationale} se reproducen directamente a través de un FunctionModel de PydanticAI).

Pruebas

uv run pytest custom_server/tests agent/tests

Todas las llamadas de red (arXiv, OpenAlex, OpenRouter) están simuladas; no hay tráfico en vivo durante las pruebas.

Contratos de herramientas (Parte C)

search_arxiv_papers (personalizado)

score_paper_relevance (personalizado)

find_foundational_citations (personalizado)

Obsidian Local REST API MCP (existente, Parte A)

Se usa mediante las llamadas a herramientas en lenguaje natural del agente PydanticAI (no una función envoltorio fija) para dos operaciones en el flujo:

Justificación del diseño

• Por qué Obsidian: la tarea necesita un servidor MCP existente del que el agente tanto lea como escriba. Las notas de conceptos propias de un estudiante son una entrada natural de "lo que ya sé", y escribir los supervivientes de vuelta cierra el bucle visiblemente en la bóveda.

• Por qué arXiv + OpenAlex en lugar de un sitio con muro de inicio de sesión: las fuentes consideradas originalmente (horario KSE/Moodle) requieren ambas inicio de sesión personal, lo que la regla de API pública de la tarea descarta. arXiv y OpenAlex son públicos, sin autenticación, y respaldan directamente el dominio de "relevancia + impacto".

• Por qué la relevancia la juzga un LLM, no embeddings: OpenRouter no tiene endpoint de embeddings (verificado contra su catálogo de modelos en vivo), por lo que score_paper_relevance usa una llamada de salida estructurada de PydanticAI en lugar de similitud vectorial — reutilizando la única credencial de modelo que el proyecto ya necesita.

• Por qué find_foundational_citations no es "buscar de nuevo con OpenAlex": toma la lista de referencias de un artículo específico y la ordena por impacto de citas, el mismo tipo de comparación de indicadores controlada que usan los ejemplos de la propia tarea — responsabilidad y procesamiento distintos de la búsqueda por palabras clave search_arxiv_papers.

• El filtrado es Python simple, no una 4ª herramienta: el umbral de relevancia + filtro impact_pass en filter_candidates_node de agent/graph.py es post-procesamiento determinista sobre datos ya puntuados, no lógica de dominio nueva — una herramienta sería solo indirección alrededor de un if.

• Compensaciones / limitaciones: el modo offline/replay del servidor personalizado (ver "Modo offline / replay" más arriba) cubre dos artículos registrados y una búsqueda de arXiv independiente de la consulta — no una grabación/reproducción general de consultas arbitrarias. Las llamadas propias de agent/ a Obsidian y OpenRouter no se ven afectadas por él y siguen requiriendo acceso en vivo. Los umbrales de impacto/relevancia son valores de .env, no ajustables en tiempo de ejecución por solicitud.

Diferido (marcado, no descartado)

• Exponer los umbrales codificados como configuración de ejecución más rica más allá de .env.

Lista de verificación para demostración / defensa

• uv run python -m custom_server.server se inicia de forma independiente; un cliente MCP crudo con list_tools muestra las 3 herramientas.

• uv run pytest custom_server/tests agent/tests — todo en verde, red simulada.

• CUSTOM_SERVER_OFFLINE=1 uv run python -m custom_server.server se inicia y sirve las 3 llamadas a herramientas sin red en vivo ni claves API requeridas (ver "Modo offline / replay").

• Siembra una nota de demostración en la bóveda con un resumen de concepto (p. ej. "mecanismos de atención"), titulada p. ej. "Nota de concepto sobre Transformers".

• uv run python -m agent.graph "Find papers related to my 'Transformers Concept Note'" — ejecución completa en vivo: resuelve la referencia de la nota, lee la nota, busca en arXiv, puntúa candidatos, filtra, encuentra citas fundacionales, escribe "<nota> — Related Papers" de vuelta en la bóveda.

• Muestra ambas conexiones MCP alimentando la salida final: la nota de escritura cita tanto datos de arXiv/OpenAlex (servidor personalizado) como el contenido de la nota de concepto original (Obsidian).

• Demostración de información insuficiente: ejecuta con una consulta que no nombre ninguna nota (p. ej. "What's a transformer?") — muestra que el agente se detiene e imprime "Not enough information..." sin llamar a Obsidian. Luego ejecuta contra una nota con contenido casi vacío — muestra que se detiene después de leer la nota, antes de llamar a arXiv.

• Demostración de fallo, Obsidian: detén el plugin Local REST API (o usa una OBSIDIAN_API_KEY incorrecta / un título de nota inexistente) — muestra que el agente presenta un error distinguible, no un resultado vacío silencioso.

• Demostración de fallo, servidor personalizado: llama a search_arxiv_papers con una categoría inválida, o a find_foundational_citations con un ID de arXiv ausente en OpenAlex — muestra ValueError / PaperNotFoundError respectivamente, distinto de un resultado vacío válido.