uv sync
cp .env.example .env

# 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'"

CUSTOM_SERVER_OFFLINE=1 uv run python -m custom_server.server

uv run pytest custom_server/tests agent/tests

### `find_foundational_citations` (кастомный)

|                              |                                                                                                                                                                                                                                                                                                             |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Назначение**               | Анализ графа цитирований: для заданной статьи ранжирует её собственные ссылки по количеству цитирований, чтобы выявить устоявшиеся работы, на которых она построена. Отличается от `search_arxiv_papers` — он анализирует список ссылок конкретной статьи, а не поиск по ключевым словам.                     |
| **Описание для модели**      | «Если передан arXiv ID одной статьи, вернуть её наиболее цитируемые ссылки — устоявшиеся предшествующие работы, на которых она строится. Использовать после выбора статьи для чтения, чтобы выявить стоящую за ней базовую литературу. Статья без записанных ссылок возвращает пустой список — это нормальный результат, а не ошибка." |
| **Вход**                     | `arxiv_id: str`, `max_results: int = 3` (1–3)                                                                                                                                                                                                                                                               |
| **Выход**                    | `list[{openalex_id, title, cited_by_count, publication_year}]`, отсортированный по `cited_by_count` по убыванию, первые `max_results`                                                                                                                                                                        |
| **Условия ошибки**           | `ValueError`, если `max_results` вне диапазона `[1, 3]`. `PaperNotFoundError`, если в OpenAlex нет записи для этого arXiv ID. Статья с нулевым числом ссылок возвращает `[]` — это корректный результат, а не ошибка.                                                                                           |
| **Побочные эффекты**         | Только чтение: один запрос статьи OpenAlex и один или более пакетных запросов works в OpenAlex (пакетами по 50 идентификаторов на запрос).                                                                                                                                                                      |
| **Пример**                   | `find_foundational_citations(arxiv_id="2005.14165", max_results=3)` → три наиболее цитируемые работы, на которые ссылается GPT-3.                                                                                                                                                                               |

### Obsidian Local REST API MCP (существующий, часть A)

Используется через вызовы инструментов на естественном языке агента PydanticAI (не как фиксированная функция-обёртка) для двух операций в потоке:

|                              |                                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Разрешение ссылки**        | Перед любым вызовом Obsidian `parse_prompt` просит агента PydanticAI (обычные рассуждения LLM, а не вызов MCP) определить название заметки, подразумеваемое свободным текстовым запросом пользователя. Если ничего не удаётся определить, поток останавливается со статусом "insufficient information" и Obsidian не вызывается.                                                                   |
| **Чтение**                   | Агент получает задание прочитать заметку с названием `note_title` (из `parse_prompt`) и вернуть её содержимое в виде обычного текста — эти данные попадают в `concept_text`, вход для извлечения ключевых слов и оценки релевантности.                                                                                                                                                              |
| **Запись**                   | Агенту предписывается создать/перезаписать заметку с названием `"{note_title} — Related Papers"` с markdown-содержимым, сформированным в `compose_note_content` — наблюдаемый эффект, замыкающий цикл между обоими MCP-серверами.                                                                                                                                                                   |
| **Условия ошибки**           | Остановленный плагин, неверный API-ключ или отсутствующая заметка проявляются как различимый сбой вызова инструмента со стороны MCP-сервера, а не молчаливый пустой результат.                                                                                                                                                                                                                |

## Обоснование решений

* **Почему Obsidian:** заданию нужен существующий MCP-сервер, из которого агент и читает, и пишет. Собственные концепт-заметки студента — естественный вход «что я уже знаю», а запись отобранных работ обратно наглядно замыкает цикл в хранилище.
* **Почему arXiv + OpenAlex вместо сайта за логином:** изначально рассматривавшиеся расписание KSE и материалы Moodle требуют личного входа, что противоречит правилу задания о публичных API. arXiv и OpenAlex открыты, не требуют аутентификации и напрямую поддерживают область «релевантность + влияние».
* **Почему релевантность оценивает LLM, а не эмбеддинги:** у OpenRouter нет эндпотинга эмбеддингов (проверено по живому списку моделей), поэтому приложение `score_paper_relevance` использует вызов PydanticAI со структурированным выводом его на структуру: вместо векторной близости — переиспользуя те учётос данные для модели, которые уже всё равно нужны проекту.
* **Почему `find_foundational_citations` — не «искать ещё раз с OpenAlex»:** берёт список ссылок конкретной статьи и ранжирует его по влиянию цитиований — тот же вид контролируемого сравнения показателей, что и примеры из самой задачи; ответственная и обработка у него отдельная, отличная от поиска по ключевым словам в `search_arxiv_papers`.
* **Фильтрация — это обычный Python, а не 4-й инструмент:** фильтр по порогу релевантности вместе с `impact_pass` в `agent_candidates_node` из `агент/graph.py` — детерминированная постобработка уже оценённых данных, а не новая предметная логика; инструмент был бы просто обёрткой вокруг `if`.
* **Компромиссы / ограничения:** режим офлайна/воспроизведения кастомного сервера (см. «Offline / replay mode» выше) покрывает две записанные статьи и независящий от запроса поиск arXiv — а не универсальную запись/воспроизведение произвольных запросов. Собственные вызовы Obsidian и OpenRouter в `agent/` этим режимом не затрагиваются и по-прежнему требуют живого доступа. Пороги оценки влияния/релевантности — значения `.env`, а не параметры, изменяемые во время выполнения без перезапуска.

## Отложено (отмечено, не снято)

* Открытие жёстко заданных порогов как более богатой конфигурации времени выполнения, чем `.env`.

## Демо / чек-лист защиты

* [ ] `uv run python -m custom_server.server` запускается автономно; `list_tools` сырого MCP-клиента показывает все 3 инструмента.
* [ ] `uv run pytest custom_server/tests agent/tests` — все тесты зелёные, сеть мокирована.
* [ ] `CUSTOM_SERVER_OFFLINE=1 uv run python -m custom_server.server` запускается и обслуживает все 3 вызова инструмента без живого сетевого доступа и API-ключей (см. «Offline / replay mode»).
* [ ] Завести в демо-хранилище заметку с кратким описанием концепта (например, "attention mechanisms"), названную, например, "Transformers Concept Note".
* [ ] `uv run python -m agent.graph "Find papers related to my 'Transformers
      Concept Note'"` — полный живой прогон: определяет ссылку на заметку, читает
  заметку, ищет в arxiv, оценивает кандидатов, фильтрует, находит
  ключевые цитирования, записывает `"<note> — Related Papers"` в обратною сторону —
  в хранилище.
* [ ] Показать обе MCP-связи, формирующие итоговый результат: (противопоставя) внешней заметкой-записью цитируются данные из arXiv/OpenAlex (кастомный сервер) и содержимое исходной концепт-заметки (Obsidian).
* [ ] Демонстрация «недостаточно информации»: запустить с запросом, который не упоминает заметку (например, `"What's a transformer?"`) — показать, что агент останавливается и печатает
  "Not enough information..." без вызова Obsidian. Затем привести близко
  записи с почти пустым содержимым — показать, что он останавливается после читания
  записи, до обращения к arXiv.
* [ ] Демонстрация сбоя, Obsidian: остановить затычку Local REST API plugin (или использовать неверный
  `OBSIDIAN_API_KEY` / несуществующий разметкий заголовок) — показать инициализацию
  уагента выдаст различимую ошибку, а не молчаливый пустой результат.
* [ ] Демонстрация сбоя, кастомный сервер: вызвать `search_arxiv_papers` с
  недопустимой категорией, или `find_foundational_citations` для arXiv ID,
  отсутствующего в OpenAlex — показать `ValueError` / `PaperNotFoundError`
  соответственно, в отличие от корректного пустого результата.