Неофициальный Python-клиент для alphaxiv: как мы нашли скрытый API и упаковали его в пакет

Если вы работаете с научными статьями, то наверняка знакомы с arXiv — основным репозиторием препринтов в области CS, математики и физики. alphaxiv — это надстройка над ним: платформа добавляет к каждой статье раздел для обсуждений и, что важнее для нас, AI-ассистента, который умеет отвечать на вопросы по содержанию конкретной статьи. Спросить про методологию, попросить объяснить формулу, уточнить, какие результаты получены на каком датасете — всё это прямо на странице статьи.

Проблема возникает, когда нужно выйти за пределы браузера. Допустим, вы хотите автоматически получать краткое изложение статей из свежей подборки, встроить ассистента в свой исследовательский пайплайн или подключить его к LLM-агенту. Официальной документации API у alphaxiv нет в публичном доступе — ни ссылки с сайта, ни упоминаний в блоге. Пакетов на PyPI на момент написания тоже не было. (UPD: смотрите актуальную информацию в последнем разделе)

Мы решили разобраться, как работает ассистент под капотом, и оформили результат в виде Python-пакета aurelle-py. В этой статье — как именно мы нашли API, что внутри, и как использовать пакет в своих проектах.

Как нашли API

Никакого реверс-инжиниринга здесь не было — только браузерные DevTools и 15 минут наблюдения.

Открываем страницу любой статьи на alphaxiv, жмём F12, переходим на вкладку Network и фильтруем по Fetch/XHR. Затем задаём вопрос через интерфейс «Ask AI» и смотрим, какой запрос уходит.

В списке появляется POST-запрос к api.alphaxiv.org/assistant/v2/chat. Открываем его — во вкладке Payload видим тело запроса, в Headers — заголовок авторизации, в Preview — SSE-поток в ответе. Всё что нужно, лежит на поверхности.

Заголовок авторизации выглядит так:

Authorization: Bearer <токен>

Токен — это не постоянный API-ключ, а короткоживущий JWT, который браузер получает от Clerk (сервис аутентификации, используемый alphaxiv). Это первая проблема для программного доступа: токен протухает. Однако оказалось, что alphaxiv поддерживает и постоянные ключи — они создаются в личном кабинете.

Ключ из личного кабинета работает точно так же, как браузерный JWT, и не имеет срока действия. Именно его aurelle-py использует в качестве основного способа авторизации.

Тело запроса, которое мы увидели в DevTools, выглядит примерно так:

{ "message": "Какие результаты были получены в области круглых тензоров в 2026 году?", "files": [], "llmChatId": null, "model": "aurelle-1", "thinking": false, "webSearch": "off", "parentMessageId": null, "paperVersionId": "some-version-uuid", "selectionPageRange": null, "assistantVariant": "paper" }

Поле model сразу привлекло внимание: aurelle-1. Это название нигде публично не упоминается — ни в блоге alphaxiv, ни в документации, ни в открытых источниках. По всей видимости, это внутреннее имя модели или её конфигурации. Для нас это просто строка, которую нужно передавать в каждом запросе.

Ответ приходит в формате Server-Sent Events — потоком событий, а не единым JSON.

Что внутри: эндпоинт, SSE и параметры

Эндпоинт и авторизация

Единственный эндпоинт, с которым работает ассистент:

POST https://api.alphaxiv.org/assistant/v2/chat Authorization: Bearer {AURELLE_API_KEY} Content-Type: application/json

Ключ создаётся в личном кабинете alphaxiv и передаётся в каждом запросе. Никакой дополнительной аутентификации не требуется.

Тело запроса

Разберём поля, которые реально влияют на поведение:

Формат ответа: Server-Sent Events

Ответ приходит не единым JSON, а потоком событий (Content-Type: text/event-stream). Каждое событие — отдельная строка вида:

{"type": "delta_output_text", "value": "The attention mechanism"} {"type": "delta_output_text", "value": " allows the model to..."} {"type": "tool_use", "toolUseId": "tu_01", "kind": "Answer PDF Queries", "content": "{}"} {"type": "tool_result_text", "toolUseId": "tu_01", "content": "{\"result\": \"...\"}"}

Три типа событий:

UUID созданной сессии приходит не в теле ответа, а в заголовке: llm-chat-id. Его нужно сохранить, чтобы передать в llmChatId следующего запроса.

Встроенные инструменты модели

При ответе на вопрос о статье модель самостоятельно выбирает, какие инструменты вызвать. Из наблюдений за реальными запросами удалось выявить пять:

Rate limit

alphaxiv ограничивает частоту запросов: 40 запросов в 60 секунд. При превышении лимита API возвращает HTTP 429, а в заголовках ответа передаёт информацию об ограничении:

ratelimit: limit=40, remaining=0, reset=60

aurelle-py при получении 429 немедленно выбрасывает RateLimitError с атрибутом reset_in — количество секунд до сброса счётчика.

Ограничения, выявленные опытным путём

Несколько вещей, которые не очевидны из структуры запроса, но важны на практике:

• Multi-turn без истории. llmChatId позволяет продолжать сессию, но parentMessageId API не возвращает — получить историю предыдущих сообщений через API невозможно, эндпоинты истории возвращают 404. Модель может не помнить начало разговора.

• assistantVariant="homepage" зависает. Этот вариант рассчитан на браузерный контекст с активной сессией. В программном клиенте запрос уходит, но ответа не приходит. Всегда используйте "paper".

• webSearch принимает только "off" и "full". Значение "on" не работает.

• Веб-поиск и paperVersionId несовместимы. Комбинация этих двух параметров может привести к тому, что запрос зависнет. Используйте что-то одно.

Что известно публично

Перед разработкой пакета мы проверили, нет ли уже готовых решений или хотя бы описания API в открытых источниках.
10 марта 2026 года alphaxiv опубликовал Claude Skill — интеграцию для работы со статьями прямо в Claude. Skill описывает два эндпоинта: резолвинг arXiv ID в внутренний versionId и получение структурированного обзора статьи. Это GET-запросы для готовых обзоров — интерактивный чат-эндпоинт там не упоминается.
В репозитории alphaXiv/feedback разработчики и пользователи обсуждают API в issues — но на уровне «хотим программный доступ», без спецификаций. Клиентских библиотек на PyPI или GitHub обнаружить не удалось.
При этом форма создания ключа в личном кабинете явно упоминает API — это и стало отправной точкой: раз ключи выдаются, значит, есть что вызывать.

Пакет aurelle-py

Результат исследования API оформлен в виде Python-пакета aurelle-py.

Установка

pip install aurelle-py

С поддержкой MCP-сервера:

pip install "aurelle-py[mcp]"

Структура пакета

src/aurelle/ ├── __init__.py # публичный API: AurelleClient, AsyncAurelleClient, типы ├── client.py # синхронный клиент ├── async_client.py # асинхронный клиент ├── models.py # Pydantic v2: ChatRequest, ChatResponse, StreamChunk, ToolUse ├── sse.py # парсер SSE-потока ├── exceptions.py # AurelleError, AuthError, RateLimitError, AurelleAPIError └── mcp/ └── server.py # MCP-сервер, точка входа aurelle-mcp

Ключевые архитектурные решения

Для синхронного и асинхронного клиентов выбран httpx — это избавило от необходимости тащить aiohttp как отдельную зависимость только ради async.

SSE-парсер вынесен в отдельный модуль. sse.py принимает итератор строк и ничего не знает об HTTP. Это позволяет тестировать логику разбора событий без сети — просто передавая список строк. Все 64 unit-теста работают без API-ключа и без сетевых запросов.

Если alphaxiv изменит формат запроса — получим понятную ошибку валидации на старте, а не загадочный сбой в рантайме. Поэтому входящий запрос и SSE-структуры описаны Pydantic v2 моделями.

Типизированные исключения. Вместо голого Exception — иерархия: AuthError на 401/403, RateLimitError на 429 (с атрибутом reset_in), AurelleAPIError на остальные 4xx/5xx. Это позволяет обрабатывать разные ситуации раздельно.

Sync и async с одинаковым интерфейсом. AurelleClient и AsyncAurelleClient предоставляют идентичные методы — chat(), stream(), ask_paper(). Можно переключиться между ними, заменив одну строку импорта.

Типы данных

@dataclass class ChatResponse: text: str # собранный текст ответа chat_id: str # UUID сессии (для multi-turn) tool_uses: list[ToolUse] raw_events: list[dict] @dataclass class StreamChunk: delta: str # фрагмент текста (пустой для tool-событий) event_type: str # "delta_output_text" | "tool_use" | "tool_result_text" @dataclass class ToolUse: tool_use_id: str kind: str # например, "Answer PDF Queries" content: str # JSON-строка с данными инструмента

Тесты

Пакет покрыт 74 тестами: 64 unit-теста и 10 интеграционных.

# Только unit-тесты — без API-ключа, работают офлайн pytest # Интеграционные тесты — требуют AURELLE_API_KEY pytest -m integration

Unit-тесты используют respx для мокирования httpx на уровне транспорта — реальные HTTP-запросы не уходят. Интеграционные тесты помечены @pytest.mark.timeout(120) и делают паузу между запросами, чтобы не упираться в rate limit.

Примеры использования

Простой вопрос к ассистенту

Базовый сценарий — задать вопрос и получить ответ:

from aurelle import AurelleClient with AurelleClient() as client: response = client.chat("В чём преимущество реализации расчётов с помощью круглых тензоров на современных GPU?") print(response.text) print(f"chat_id: {response.chat_id}") print(f"tool_uses: {len(response.tool_uses)}") Вывод:

Вопрос по конкретной статье

Удобный метод ask_paper() принимает arXiv ID и вопрос — ID статьи подставляется в сообщение автоматически:

from aurelle import AurelleClient with AurelleClient() as client: response = client.ask_paper( arxiv_id="math/0211159", question="Как мне это поможет в разработке ИИ-агентов??", ) print(response.text) Вывод:

Асинхронный клиент

import asyncio from aurelle import AsyncAurelleClient async def main(): async with AsyncAurelleClient() as client: response = await client.chat("Explain O(n²) attention complexity") print(response.text) async for chunk in client.stream("Помоги объяснить ребёнку доказательство math/0211159 ?"): print(chunk.delta, end="", flush=True) asyncio.run(main())

Веб-поиск и режим thinking

# Поиск по свежим статьям с привлечением веб-поиска response = client.chat("Найди лучший социполитический и ценностный бенчмарк для русского языка", web_search=True) # Режим «размышления» перед ответом response = client.chat("Какие актуальные подходы к дообучению LLM для задач устного счёта?", thinking=True)

Обработка ошибок

from aurelle.exceptions import RateLimitError, AuthError import time try: response = client.chat("Как мне написать такую же статью, как quant-ph/9904050 ?") except AuthError: print("Проверьте AURELLE_API_KEY") except RateLimitError as exc: print(f"Превышен rate limit. Повтор через {exc.reset_in}с") time.sleep(exc.reset_in or 60)

Подключение к Claude через MCP

aurelle-py включает MCP-сервер, который позволяет использовать alphaxiv-ассистента прямо в чате с Claude — без написания кода. Это, пожалуй, самый удобный сценарий для исследователя: спросить о статье можно прямо в процессе разговора с моделью.

Сервер предоставляет два инструмента:

Установка

pip install "aurelle-py[mcp]"

Claude Desktop

Добавьте в файл конфигурации:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{ "mcpServers": { "aurelle": { "command": "aurelle-mcp", "env": { "AURELLE_API_KEY": "your_key_here" } } } }

После перезапуска Claude Desktop в чате появятся два новых инструмента.

Claude Code

Создайте файл .mcp.json в корне проекта:

{ "mcpServers": { "aurelle": { "type": "stdio", "command": "aurelle-mcp", "env": { "AURELLE_API_KEY": "your_key_here" } } } }

Важный момент: .mcp.json читается только при запуске, поэтому после создания или изменения файла нужно перезапустить Claude Code.

Ограничения

Multi-turn без полноценной истории. llmChatId позволяет продолжать сессию, передавая UUID из предыдущего ответа. Однако parentMessageId в ответах не возвращается, а эндпоинты истории чата отдают 404. Модель может не удерживать контекст начала разговора.

assistantVariant="homepage" зависает. Этот вариант, судя по всему, рассчитан на браузерный контекст. В программном клиенте ответа не приходит. Для всех запросов используется "paper".

webSearch и paperVersionId лучше не совмещать. При одновременной передаче обоих параметров запрос может зависнуть. Стоит использовать что-то одно в зависимости от задачи.

API недокументирован. Всё описанное выше получено наблюдением за реальными запросами и может измениться без предупреждения. Рекомендуется фиксировать версию пакета и проверять работоспособность после обновлений alphaxiv.

Заключение

Пакет доступен на GitHub и в PyPI — если работаете с arXiv и хотите встроить alphaxiv-ассистента в свои скрипты или агентные пайплайны, попробуйте. Будем рады обратной связи.

Надеемся, что alphaxiv со временем опубликует официальную документацию API и, возможно, собственный клиент — это сделает интеграцию надёжнее и избавит от необходимости опираться на результаты наблюдений за браузерным трафиком.

UPD — день публикации

Пока статья готовилась к выходу, картина успела дополниться. Фиксируем для полноты.

Документация API всё-таки существует. По адресу api-dev.alphaxiv.org работает Scalar UI с полной OpenAPI 3.0 спецификацией — 190 эндпоинтов, включая весь Assistant API. URL нигде публично не упоминался до 12 марта 2026 года, не индексируется ни одной поисковой системой (Wayback Machine не имеет ни одного снапшота, site:api-dev.alphaxiv.org даёт ноль результатов). Обнаружить его можно было только в исходном коде стороннего проекта.

Параллельный запуск. В тот же день, 13 марта 2026, на PyPI появился пакет alphaxiv_cat — автосгенерированный SDK из той же OpenAPI-спецификации с помощью Stainless, покрывающий все 190 эндпоинтов платформы. Мы не знали о его существовании: репозитории AlphaxivCat были созданы за четыре часа до нашего исследования.

Чем aurelle-py отличается от alphaxiv_cat:

• Написан вручную для внутренних задач, не сгенерирован

• MCP-сервер. aurelle-mcp — единственная из двух библиотек с готовой интеграцией для Claude Desktop и Claude Code. alphaxiv_cat не реализует MCP, несмотря на то что в самом API alphaxiv есть нативный /mcp/v1 эндпоинт.

• Структурированный SSE. alphaxiv_cat возвращает Stream[object] из чат-эндпоинта — без парсинга типов событий. aurelle-py разбирает поток на delta_output_text, tool_use, tool_result_text и возвращает типизированные ChatResponse и StreamChunk.

• Фокус на исследовательском сценарии. ask_paper(arxiv_id, question) — одна строка вместо ручной сборки параметров. Явные предупреждения об известных ограничениях API (multi-turn, зависания при совмещении параметров) — то, чего нет в автосгенерированной документации.

Проекты занимают разные ниши: alphaxiv_cat — полный SDK для всей платформы, aurelle-py — специализированный клиент для AI-ассистента с акцентом на LLM-интеграцию.

Над статьёй работали: Аничков Егор, Ершов Даниил, Боловцов Сергей