{"id":"bf4619d1-50a4-4259-aafa-233269d31b40","slug":"alphaxiv-py","kind":"skill","name":"alphaxiv-py","summary":"Python SDK and CLI for alphaXiv public research APIs","owner":"petroslamb","repoUrl":"https://github.com/petroslamb/alphaxiv-py","license":"MIT","licenseTier":"permissive","trust":"community","stars":8,"match":null,"fewStars":false,"format":"skill","createdAt":"2026-03-12T10:44:25.000Z","addedAt":"2026-10-21T16:58:00.548Z","logoUrl":"https://avatars.githubusercontent.com/u/1930167?u=c603924f462d1c6a4d6f8883deb52aa9c98ce3a4&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T14:46:07.621Z","sample":false,"url":"https://conduits.dev/tools/alphaxiv-py","language":"Python","transports":["stdio"],"install":{"pypi":"alphaxiv-py"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# alphaxiv-py\n\n`alphaxiv-py` is a Python SDK and CLI for alphaXiv.\n\nThis v1 release is intentionally public-first. It supports:\n\n- API-key auth via `ALPHAXIV_API_KEY` or a locally saved alphaXiv API key\n- optional browser-backed web login for authenticated CLI/API access when API-key writes are restricted\n- authenticated assistant chat for homepage and paper-scoped sessions\n- homepage search suggestions for papers, topics, and organizations\n- homepage feed/card retrieval with sort and filter support\n- bare and versioned arXiv ID resolution\n- paper metadata\n- public paper comments\n- paper full text\n- AI overview/blog payloads\n- overview status and translation availability\n- similar-paper recommendations\n- mentions/resources aggregation\n- podcast transcript retrieval\n- PDF URL lookup and download\n- authenticated folder listing\n- authenticated assistant URL metadata lookup\n- authenticated paper votes plus comment create, reply, delete, and upvote mutations\n- CLI context around a current paper and assistant session\n\nAuthenticated features use direct HTTP against `api.alphaxiv.org` with either an API-key bearer header or a browser-backed alphaXiv web session. The recommended setup is an alphaXiv API key exposed through `ALPHAXIV_API_KEY` or saved locally with `alphaxiv auth set-api-key`. If your account's API key can read authenticated metadata but cannot perform writes, run `alphaxiv auth login-web`; authenticated CLI commands prefer the saved web login when it is available. The client reads the current preferred model live from `GET /users/v3` and writes changes through `PATCH /users/v3/preferences`; it does not claim to know the full current model catalog.\n\n## Installation\n\n```bash\nuv add alphaxiv-py\n```\n\nor\n\n```bash\npip install alphaxiv-py\n```\n\nFor local development:\n\n```bash\nuv pip install -e .\n```\n\nOptional browser support for `alphaxiv auth login-web`:\n\n```bash\nuv sync --extra browser\nuv run playwright install chromium\n```\n\nOr from PyPI:\n\n```bash\npip install \"alphaxiv-py[browser]\"\nplaywright install chromium\n```\n\nRecommended auth setup:\n\n```bash\nexport ALPHAXIV_API_KEY=\"axv1_...\"\nalphaxiv assistant list\n```\n\nIf you prefer to save the key locally:\n\n```bash\nalphaxiv auth set-api-key --api-key \"$ALPHAXIV_API_KEY\"\n```\n\nIf assistant chat writes are restricted for your API key, save the alphaXiv web session too:\n\n```bash\nalphaxiv auth login-web\n```\n\nUse `auth login-web` as one-time setup for a persistent browser profile, not before every\nassistant command. After it succeeds, just use authenticated CLI commands normally and the CLI will\ntry to refresh the saved web session automatically from `ALPHAXIV_HOME/browser-profile`.\n\nIf someone keeps rerunning `auth login-web`, the usual problem is operational rather than\ntoken-lifetime alone:\n\n- `ALPHAXIV_HOME` changes between runs\n- the environment is ephemeral and does not keep `~/.alphaxiv`\n- `browser-profile` is being deleted or recreated\n- the underlying alphaXiv web session itself was signed out\n\nTell users to keep `ALPHAXIV_HOME` stable, keep `browser-profile`, and rerun `auth login-web`\nonly when the real web session is gone or they moved to a new machine or container.\n\nUsers create API keys in the alphaXiv web app. This package does not create or manage API keys remotely.\n\n## CLI Quick Start\n\nThe CLI is resource-first. The top-level surface is grouped into `auth`, `context`, `search`,\n`feed`, `paper`, `assistant`, `folders`, `guide`, `skill`, and `agent`.\n\n```bash\nexport ALPHAXIV_API_KEY=\"axv1_...\"\nalphaxiv auth set-api-key --api-key \"$ALPHAXIV_API_KEY\"\nalphaxiv auth status\nalphaxiv auth login-web\nalphaxiv guide research\nalphaxiv context use paper 2603.04379\nalphaxiv context show\nalphaxiv context show --json\nalphaxiv search all \"graph neural networks for molecules\"\nalphaxiv search papers \"graph neural networks for molecules\"\nalphaxiv search papers \"graph neural networks for molecules\" --json\nalphaxiv search organizations \"graph neural networks for molecules\"\nalphaxiv search topics \"graph neural networks\"\nalphaxiv assistant list\nalphaxiv assistant list --json\nalphaxiv assistant model\nalphaxiv assistant url-metadata https://github.com/PKU-YuanGroup/Helios\nalphaxiv assistant set-model \"Claude 4.6 Sonnet\"\nalphaxiv assistant start \"Find papers on agent frameworks\"\nalphaxiv assistant start --model \"GPT 5.4\" \"Find papers on agent frameworks\"\nalphaxiv assistant reply \"Focus on the most cited ones\"\nalphaxiv assistant history\nalphaxiv feed filters\nalphaxiv feed filters search \"agentic\"\nalphaxiv feed filters search \"agentic\" --json\nalphaxiv feed list --sort likes --limit 5\nalphaxiv feed list --organization MIT --source twitter --limit 5\nalphaxiv feed list --topic agentic-frameworks --organization Meta --limit 5\nalphaxiv paper show\nalphaxiv paper abstract\nalphaxiv paper summary\nalphaxiv paper summary --json\nalphaxiv paper comments list\nalphaxiv paper comments add --body \"Helpful note\"\nalphaxiv paper comments reply <comment-id> --body \"Thanks\"\nalphaxiv paper comments upvote <comment-id> --yes\nalphaxiv paper comments delete <comment-id> --yes\nalphaxiv paper similar --limit 5\nalphaxiv paper text --page 1\nalphaxiv paper vote --yes\nalphaxiv paper view --yes\nalphaxiv paper overview\nalphaxiv paper overview --machine\nalphaxiv paper overview-status\nalphaxiv paper resources\nalphaxiv paper resources --bibtex\nalphaxiv paper resources --transcript\nalphaxiv paper pdf url\nalphaxiv paper pdf download ./helios.pdf\nalphaxiv folders list --papers\nalphaxiv skill install\nalphaxiv skill status --scope all --json\nalphaxiv agent show codex\nalphaxiv context clear\nalphaxiv auth clear\nalphaxiv auth clear-web\n```\n\n`--json` is the stable machine-readable output mode for automation and agents.\n`--raw` stays available on selected commands when you want the backend-shaped payload for debugging.\nAuthenticated CLI commands prefer the saved web login when it is available, and otherwise fall back to API-key auth.\n\nLong-running assistant chats can become slower over time because `assistant reply` keeps extending\nthe same remote session. If a chat becomes sluggish and you do not need the whole thread active,\nstart a fresh chat with `alphaxiv assistant start \"...\"` and carry forward only the minimal recap\nor paper ids you still need. Use `alphaxiv assistant history` or `alphaxiv assistant list` to keep\nthe older session available for reference. This is the practical mitigation when the slowdown is\ncoming from accumulated chat state.\n\n## Python Quick Start\n\n```python\nimport asyncio\nimport os\n\nfrom alphaxiv import AlphaXivClient\n\n\nasync def main() -> None:\n    async with AlphaXivClient(api_key=os.environ[\"ALPHAXIV_API_KEY\"]) as client:\n        homepage = await client.search.homepage(\"graph neural networks for molecules\")\n        print(homepage.papers[0].paper_id, homepage.papers[0].title)\n\n        papers = await client.search.papers(\"graph neural networks for molecules\")\n        organizations = await client.search.organizations(\"graph neural networks for molecules\")\n        topics = await client.search.closest_topics(\"graph neural networks\")\n        print(papers[0].paper_id, organizations[0].name, topics[0])\n\n        filter_search = await client.explore.search_filters(\"agentic\")\n        print(filter_search.topics[:2], [item.name for item in filter_search.organizations[:2]])\n\n        cards = await client.explore.feed(\n            sort=\"most-stars\",\n            source=\"GitHub\",\n            topics=(\"agentic-frameworks\",),\n            limit=3,\n        )\n        print(cards[0].paper_id, cards[0].upvotes)\n\n        paper = await client.papers.get(\"2603.04379\")\n        print(paper.version.title)\n\n        comments = await client.papers.comments(\"2603.04379\")\n        print(comments[0].body if comments else \"no comments\")\n\n        full_text = await client.papers.full_text(\"2603.04379\")\n        print(full_text.pages[0].text[:200])\n\n        overview = await client.papers.overview(\"2603.04379\")\n        print(overview.summary.summary if overview.summary else overview.title)\n\n        status = await client.papers.overview_status(\"2603.04379\")\n        print(status.state, sorted(status.translations))\n\n        transcript = await client.papers.transcript(\"2603.04379\")\n        print(transcript.lines[0].speaker, transcript.lines[0].line[:80])\n\n        similar = await client.papers.similar(\"2603.04379\", limit=3)\n        print([card.paper_id for card in similar])\n\n        sessions = await client.assistant.list()\n        print(sessions[0].id, sessions[0].title)\n\n        metadata = await client.assistant.url_metadata(\"https://github.com/PKU-YuanGroup/Helios\")\n        print(metadata.title)\n\n        folders = await client.folders.list()\n        print(folders[0].name if folders else \"no folders\")\n\n        run = await client.assistant.ask(\"Find papers on agent frameworks\")\n        print(run.session_id, run.output_text[:120])\n\n\nasyncio.run(main())\n```\n\n`AlphaXivClient.from_saved_api_key()` loads `ALPHAXIV_API_KEY` first and then falls back to `~/.alphaxiv/api-key.json`.\n`AlphaXivClient.from_saved_browser_auth()` reuses the auth captured by `alphaxiv auth login-web`.\n`AlphaXivClient.from_saved_auth(prefer_browser=True)` prefers the saved web login and falls back to the saved API key.\n\n## Official alphaXiv MCP Server\n\nalphaXiv also provides an official MCP server for native MCP clients at:\n\n```text\nhttps://api.alphaxiv.org/mcp/v1\n```\n\nThe MCP server is a separate integration surface from this package. Use `alphaxiv-py` when you\nwant the Python SDK or CLI for direct API access, and use the MCP server when an MCP-capable client\nshould call alphaXiv research tools directly.\n\nThe endpoint uses Streamable HTTP. Interactive clients authenticate through OAuth in a browser;\nnon-interactive clients can instead send an alphaXiv API key as an `Authorization: Bearer <key>`\nheader. See the [official MCP documentation](https://www.alphaxiv.org/docs/mcp) for supported\nclients, setup instructions, and the available tools.\n\n## Agent Integrations\n\nThis repo ships agent-facing guidance in two forms:\n\n- built-in workflow guides through `alphaxiv guide ...`\n- packaged integrations installable through `alphaxiv skill ...`\n\nThe repo-root Codex skill is also published for discovery:\n\n- [Skill entry point](skills/alphaxiv/SKILL.md)\n- [Skill workflows](skills/alphaxiv/references/workflows.md)\n- [Skill command map](skills/alphaxiv/references/command-map.md)\n\nInstall the packaged integrations with the CLI:\n\n```bash\nalphaxiv skill install\nalphaxiv skill status --scope all\nalphaxiv skill show --target source\nalphaxiv agent show codex\n```\n\nSupported targets in this release:\n\n- Codex\n- Claude Code\n- OpenCode\n\n`skill install` defaults to user scope and installs all supported targets. Use\n`--scope project` to install into the current project instead.\n\n## LLM Agent Tips\n\nIf an agent is driving the CLI, the intended flow is:\n\n1. use `search` for keyword lookup\n2. use `feed` for recent or ranked discovery\n3. use `paper` to inspect one paper\n4. use `assistant` after retrieval for synthesis or follow-up reasoning\n5. use `context` when several commands target the same paper or chat\n\nOutput modes:\n\n- use `--json` for stable machine-readable command output\n- use `--raw` only when you need the backend-shaped payload for debugging\n\nHigh-confusion distinctions:\n\n- `paper abstract` = original abstract\n- `paper summary` = short AI digest\n- `paper overview` = long AI write-up\n- `paper text` = readable text extracted from the PDF\n- `paper pdf download` = actual PDF file\n\n## Docs\n\n- [CLI reference](docs/cli-reference.md)\n- [Python API](docs/python-api.md)\n- [Development](docs/development.md)\n- [Releasing](docs/releasing.md)\n- [API inventory](docs/api-inventory.md)\n\nTopic lookup (`search topics`, `search.closest_topics`, and `feed filters search`)\nsearches the bundled alphaXiv public category catalog by code or label, ignoring\ncase and punctuation. The upstream semantic closest-topic endpoint was retired;\nlookup now uses lexical matches, so an unmatched phrase returns no topics.\nThe catalog was verified against the website on 22 October 2026.\n\nThe public events endpoint may return an empty list when no events are listed.\nLive smoke tests accept that valid state while malformed response shapes still fail.\n"}