AIR SDK

The AIR SDK is a Python client for the AIR platform — a suite of AI assistant tools for scientific research. It gives you programmatic access to AI-assisted pipeline steps (idea generation, literature search, methods, data analysis, paper writing, peer review) as well as a set of standalone tools you can use independently.

Key capabilities:

AI-assisted research pipeline — use AI assistants for idea generation, literature search, methods development, data analysis, paper writing, and review as a connected workflow or individual steps
Local code execution — the results, one_shot, and deep_research methods coordinate an AI agent on the backend while all generated code runs locally on your machine in an isolated virtual environment
VLM image review — optionally enable vision-language model feedback to iteratively improve generated plots
File sync — push local data files to a project and pull generated outputs (plots, LaTeX, reports) back to disk after each step
Standalone AI tools — extract keywords (UNESCO, AAS, AAAI), download and summarise arXiv papers, enhance text with paper context, run OCR on PDFs (local or remote), or get an AI review of a paper PDF
Model flexibility — use cloud models (Gemini, GPT, Claude) or self-hosted open-source models via vLLM

Installation

pip install ai-research

Quick Start

import os
import air

client = air.AIR(
    api_key=os.environ["AIR_API_KEY"],
    base_url=os.environ.get("AIR_BASE_URL", "http://localhost:8000"),
)

# Standalone tools
keywords = client.keywords("dark matter and lensing", n=5, kw_type="aas")
enhanced = client.enhance("My analysis references https://arxiv.org/abs/1706.03762")
ocr_result = client.ocr("paper.pdf")  # local or server-side PDF

# One-shot task (code runs locally)
result = client.one_shot(
    "Generate synthetic data and plot a ROC curve",
    agent="engineer",
    work_dir="./output",
)

# Deep research (multi-step planning + execution)
result = client.deep_research(
    "Fit a Cox model to survival data and write a data guide",
    max_plan_steps=2,
    plan_instructions="1. engineer, 2. researcher.",
    work_dir="./output",
)

# Full research pipeline
project = client.create_project("my-research", data_description="We study...")
idea = project.idea()
literature = project.literature()
methods = project.methods()
results = project.results(max_steps=2, work_dir="./output")
paper = project.paper(journal="AAS", add_citations=True)
review = project.review()
project.pull_files()

Configuration

Set environment variables, or pass them directly to the constructor:

Variable	Description	Default
`AIR_API_KEY`	API key (`air_k1_...`)	required
`AIR_BASE_URL`	Backend URL	`http://localhost:8000`
`AIR_LOCAL_DIR`	Local root for `pull_files` / auto-pull	`~/ai-scientist`
`AIR_WORK_DIR`	Local root for code execution (`results`, `one_shot`, `deep_research`)	`~/ai-scientist`

Available Models

Examples of models that can be used across the SDK:

Model	Notes
`gemini-3.1-flash-lite-preview`	Fast, cheapest — good default
`gemini-3.1-pro-preview`	Stronger reasoning
`gemini-2.5-flash`	Good for paper writing
`gpt-5-nano`	Fast, good quality
`gpt-5.2`	Strongest OpenAI model
`claude-sonnet-4-6`	Strong all-round
`gpt-oss-120b`	Self-hosted via vLLM, free

API Reference

`AIR` class

Method	Description
`health()`	Check backend status
`keywords(text, n, kw_type)`	Extract keywords (UNESCO, AAS, or AAAI)
`arxiv(text)`	Download arXiv papers from URLs in text
`enhance(text)`	Enhance text with context from referenced papers
`ocr(file_path)`	OCR a PDF (local file or server path)
`review(file_path, ...)`	Standalone paper review with Skepthical (local or server PDF)
`one_shot(task, *, model, agent, enable_vlm_review, ...)`	One-shot task with local code execution
`deep_research(task, *, adaptive_planning, enable_vlm_review, ...)`	Multi-step research with planning and local code execution
`create_project(name, data_description)`	Create a project
`get_project(name)`	Get existing project
`list_projects()`	List all projects
`delete_project(name)`	Delete a project

`Project` class

Method	Description
`idea(default_model, critic_model, idea_iterations)`	Generate research idea
`literature(timeout, max_iterations)`	Run literature search
`methods(default_model, critic_model)`	Develop methods
`results(max_steps, max_attempts, engineer_model, researcher_model, ...)`	Run analysis with local code execution
`paper(journal, add_citations, default_model)`	Write paper
`review(...)`	Run review
`get_file(path)`	Read a project file
`list_files()`	List all project files
`write_file(path, content)`	Write a file
`pull_files(key_only, iteration)`	Download project files locally
`push_files(local_path, remote_path)`	Upload local files to project
`delete()`	Delete the project

Examples

The examples/ directory contains runnable scripts covering all features:

Script	Description
`00_manage_projects.py`	List and delete projects
`01_health_check.py`	Backend health check
`02a-c_keywords_*.py`	Keyword extraction (UNESCO, AAS, AAAI)
`03a_ocr_arxiv.py`	OCR an arXiv paper
`03b_ocr_local.py`	OCR a local PDF
`04_enhance.py`	Enhance text with arXiv context
`05a-d_idea_*.py`	Idea generation (quantum, psychology, chemical eng., oncology)
`06_literature_coral.py`	Literature search (marine biology)
`07a-e_methods_*.py`	Methods development (quantum, zoology, psychology, chemical eng., oncology)
`08a_one_shot_engineer.py`	One-shot code generation
`08b_one_shot_researcher.py`	One-shot writing task
`08c_one_shot_vlm.py`	One-shot with VLM image review
`08d_one_shot_researcher_oss.py`	One-shot with self-hosted OSS model
`09_deep_research_biostatistics.py`	Deep research (biostatistics)
`10_pipeline_oscillator.py`	Full pipeline: idea → literature → methods → results
`11_paper_oscillator.py`	Paper writing from existing project
`12_review.py`	Standalone paper review

Docs

pip install ai-research[docs]
mkdocs serve --livereload

Tests

pytest tests
pytest tests/ -m "not slow"  # skip slow tests

Metadata

Release files for ai-research 0.1.43

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ai-research 0.1.43
File	Size	Uploaded	Provenance
ai_research-0.1.43.tar.gz	732.2 kB	Jul 2, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for ai-research 0.1.43
File	Interpreter	ABI	Platform	Reset
ai_research-0.1.43-py3-none-any.whl 30.5 kB Jul 2, 2026 Without provenance	Python 3	none	any	Details

Total release size: 762.7 kB

Release files / ai_research-0.1.43.tar.gz

Download URL	ai_research-0.1.43.tar.gz
Size	732.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`08a6656a9b706c00891cdc7880c8b9e23c2e5d610cf31171d530d0308a149e07`
BLAKE2b-256 checksum How to use checksums	`ab28e8e696c22d89fc3af06cf82612d4c609d2d3d471e3d7f342800cf4c3e3da`
Upload date	Jul 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Release files / ai_research-0.1.43-py3-none-any.whl

Download URL	ai_research-0.1.43-py3-none-any.whl
Size	30.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4abc654f221bb3ec1b2941bdaf0bd5c9dd46f3a054fb50f16e79fb8b1d54623b`
BLAKE2b-256 checksum How to use checksums	`3738f982d0467c1f1642c93c1ffb1b73a7f0af1ea5ba5daa0f81fde71a4eecbc`
Upload date	Jul 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Security for ai-research 0.1.43

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.