Неофициальный 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). Каждое событие — отдельная строка вида:

data: {"type": "delta_output_text", "value": "The attention mechanism"}
data: {"type": "delta_output_text", "value": " allows the model to..."}
data: {"type": "tool_use", "toolUseId": "tu_01", "kind": "Answer PDF Queries", "content": "{}"}
data: {"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%Claudeclaude_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-интеграцию.

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