openai4s 0.1.0

A pure-stdlib hybrid Code-as-Action scientific research agent.

Open AI for Scientist

💸 Replicating Claude Science in two cuts or less

An open-source hybrid scientific research agent.
_{JSON tools orchestrate; persistent Python/R kernels do the science.}

English · 简体中文

---

[!TIP] Why "two cuts"? No pricey frontier-model key needed — OpenAI4S runs on Doubao (豆包) via the cheapest "Small" plan on Volcengine Ark (火山方舟): ¥9.9 / month (≈ US$1.4). Pick the ark provider in the UI and you get a Claude-Science-class agent for less than a cup of coffee.

_{Volcengine Ark · Agent Plan (Personal) — the entry Small tier is ¥9.9 / month.}

---

🧬 JSON orchestration, Code-as-Action science

OpenAI4S deliberately has two action planes. Provider-native JSON tool calls handle deterministic orchestration, permissions, metadata, external services, and human approval. Python/R Code-as-Action handles computation, exploration, analysis, simulation, and long-running scientific work in persistent kernels. Python cells can synchronously call the in-kernel host API while they run; R is an independent persistent analysis channel.

This is not a choice between tools and code: each does the job it is good at. Tool-only and conversational work can finish through the Engine-owned, strictly structured finalize_response action. Scientific cells keep the important host.submit_output(...) completion contract, including structured artifacts and metrics. host.submit_output is the only completion signal that can fire inside a Cell; a later sole finalize_response may still close the Engine after earlier Cells have run.

	JSON control plane	Python/R science plane
Best for	workflow, permissions, metadata, services	computation, analysis, simulation
Action unit	One ordered native-tool batch	One complete code cell
Composition	auditable schemas and resource policy	for, if, libraries; Python also has mid-cell Host RPC
State	append-only Action Ledger	kernel memory + versioned artifacts
Completion	Engine-owned finalize_response	Python: host.submit_output(...); R: no in-cell completion
Extending	named Tool subclass	import a library or load a Skill
# ReAct: ~14 round-trips (read → … → filter → sort → plot). OpenAI4S: one code cell. hits = [f for f in files if pattern in host.read_file(f)] top3 = sorted(hits, key=os.path.getsize, reverse=True)[:3] frames = [pd.read_csv(f) for f in top3] # a 100k-row DataFrame stays in the kernel... host.save_artifact(plot(frames)) # ...only "<DataFrame 100000×20>" hits context

---

📣 News

• 2026-07-06 🎉 Open-sourced — the pure-stdlib Code-as-Action engine, the scientific web app, 24 science Skills, and BYOC remote compute.

---

😮 Highlights

• 🧬 Hybrid action engine — class-based native JSON tools orchestrate while persistent Python/R kernels execute science. CLI and Web adapters start foreground language slots lazily, so tool/finalize routing itself does not spawn one; individual tools may still manage dedicated workers.
• 📒 Ledger-first runtime — action groups/events and terminal facts are append-only; execution attempts, generation lifecycle, usage, and completion records remain durable and reconstructable.
• 🐍 Pure-stdlib core — the engine and the web server are stdlib-only (http.server + hand-rolled WebSocket, no framework, no deps). The LLM client speaks OpenAI / Anthropic / Gemini over urllib alone.
• 🔌 One-line multi-provider — ark (doubao · glm · kimi · deepseek · minimax) plus official chatgpt · claude · gemini, behind a single host.llm; switch from the UI.
• 🖥️ Scientific workbench — live streaming, versioned artifacts, provenance, an Action Timeline surface, and a read-only-by-default Notebook. An explicit developer flag enables multiline Python/R input against the shared kernels.
• 🔐 Hardened local execution — strict child-environment allowlists, durable approvals, one-shot generation-bound host.bash capabilities, and OS sandbox adapters (Seatbelt on macOS, bubblewrap on Linux) with visible degraded/fail-closed modes.
• 🔬 32 bundled Skills — GPU/model science Skills (AlphaFold2 · ESMFold2 · Boltz · Chai-1 · OpenFold3 · ProteinMPNN · ESM-2 · Evo2 · Borzoi · scGPT · scVI · DiffDock …) + research-workflow Skills. Skills are recipes of code, not JSON schemas; user-authored Skills stay under the data directory and cannot shadow bundled trust.
• ☁️ BYOC remote compute — with a configured, reachable provider, dispatch GPU jobs via ssh:<alias> or the bundled NVIDIA NIM integration. General remote compute remains a Prototype surface; host.fold uses a strict no-fabrication policy.

---

🎬 Demo

Live API workflow — from UniProt / RCSB to a 3D structure & report	Real-data analysis — human insulin INS (P01308): from UniProt / RCSB to a reproducible report
Visual artifact editing — “raise the confidence cutoff to 75” in one line	Annotation-driven chart editing — lasso a region & recolor the legend
Plan-mode research — artemisinin & paclitaxel solubility prediction	Protein engineering — from sequence to ranked mutants & structural rationale

---

⚡ Quickstart

git clone https://github.com/PKU-YuanGroup/OpenAI4S && cd OpenAI4S
./setup.sh     # one-time: build the environment with uv
./start.sh     # launch the web UI at http://127.0.0.1:8760/

setup.sh creates the lightweight control .venv with uv. For the comprehensive Python + R scientific kernels, install a Conda-family manager (micromamba, mamba, or conda) and run ./setup.sh --with-kernel-envs instead. Existing kernel environments can be synchronized with ./setup.sh --update-kernel-envs; updates do not prune user-installed packages. start.sh launches the daemon + web UI. No API key is needed to boot — set your model in the UI (Customize → Models). One-shot without the UI: uv run openai4s run "Compute the mean of [4,8,15,16,23,42] and submit it." -v.

macOS app (no toolchain required)

Apple Silicon users can skip the checkout entirely: download OpenAI4S-<version>-macos-arm64.dmg from the latest release, drag it to Applications, and launch. The image embeds its own Python plus the default kernel science stack — numpy · pandas · scipy · matplotlib · scikit-learn · rdkit (cheminformatics) · scanpy and the single-cell stack · umap · numba · biopython — so the first launch needs no network and no pip. Data lives in ~/.openai4s.

The build is ad-hoc signed but not notarized, so Gatekeeper refuses it the first time. On macOS 15+, open it once, then allow it under System Settings → Privacy & Security → Open Anyway; on macOS 12–14, right-click the app → Open → Open. Either way, xattr -dr com.apple.quarantine /Applications/OpenAI4S.app also clears it.

The CLI ships inside the app — symlink it if you want it on your PATH:

sudo ln -sf /Applications/OpenAI4S.app/Contents/Resources/runtime/bin/openai4s /usr/local/bin/openai4s
openai4s setup        # only if you want the R kernel: needs micromamba/mamba/conda

The R kernel is not bundled (it needs a conda environment). On Intel Macs and Linux, install from PyPI (pip install openai4s) instead.

---

📚 Documentation

The canonical bilingual documentation is published at openai4s.org/docs. Its public source and issue tracker live in Nobody-Zhang/openai4s-docs; the links below point to the code-adjacent copies kept with this repository.

doc	what's inside
Architecture	the hybrid action router, Action Ledger, host RPC, and lazy kernels
Backend extension guide	where new Tool classes, host services, repositories, and session behaviour belong
Skills	the 32 bundled Skills + how to write your own
Remote compute	BYOC GPU jobs, host.fold, auto-provisioning
Web app	UI features, Action Timeline, read-only Notebook, artifacts, and implementation status
Jupyter adapter	optional standalone Python/R KernelSpecs, install commands, and compatibility limits
Configuration	model providers, env vars, conda envs, CLI
Security	defense-in-depth safety layers & remote-access notes

---

🗺️ Roadmap

• Ship the next-generation workbench foundation: branch activation and append-only Revert/Undo projections, verified recovery with explicit Partial/Failed state, dependency-level stale propagation, durable delegation, quarantined portable Session packages, checkpointed plan/review/memory state, and dedicated 2D chemistry/genome/sequence/MSA/LaTeX renderers. Arbitrary in-memory namespace objects are deliberately not serialized; recovery remains Partial unless a safe recipe can rebuild and verify them, and Fork is offered only on records that carry a proven checkpoint mapping, so older history returns 409.
• Add stronger Linux isolation beyond bubblewrap where available (for example seccomp) and expand packaged sandbox smoke coverage.
• Keyless web_search beyond DuckDuckGo (rate-limit resilience).
• More BYOC providers (Modal / SLURM) beyond SSH + NVIDIA NIM.
• A public benchmark of end-to-end scientific workflows.
• Local GPU model serving so structure/design Skills run without remote compute.

---

💡 Contributing

OpenAI4S is a community effort to keep the Code-as-Action paradigm open.

Before opening a PR, please read CONTRIBUTING.md — it defines branch naming, the PR checklist (.github/pull_request_template.md), code ownership (.github/CODEOWNERS), review & release policy, and the offline-test policy.

Development setup

Requires Python ≥ 3.10 and uv.

git clone https://github.com/PKU-YuanGroup/OpenAI4S && cd OpenAI4S
./setup.sh                          # uv sync --locked --extra science + pre-commit hook
./setup.sh --with-kernel-envs       # optional: full Python + R kernel stacks
uv run pytest                       # offline test suite (LLM mocked)
uv run pre-commit run --all-files   # format + lint everything

Style is enforced by pre-commit — black, isort (--profile black), and ruff, pinned in .pre-commit-config.yaml. Runtime deps: the core is zero-dependency (pure stdlib); the optional science extra pins numpy>=1.24 · pandas>=2.0 · matplotlib>=3.7.

What we welcome

• New Skills — a SKILL.md (+ optional kernel.py) under skills/ — recipes of code, not schemas.
• New providers — a wire adapter under openai4s/llm/providers/ plus its provider definition and registry entry, or a BYOC compute provider.
• Engine & UI — the core is pure stdlib and readable; the web app is framework-free.

Keep the core dependency-free, guard optional science imports behind try/except ImportError, and make sure uv run pytest and uv run pre-commit run --all-files pass before opening a PR.

---

👍 Acknowledgement & related work

• Claude Science (Anthropic) — the closed reference architecture whose Code-as-Action design, persistent kernel, host-RPC protocol, and safety layers OpenAI4S independently reproduces in open source.
• CodeAct — "Executable Code Actions Elicit Better LLM Agents" — code as a unified action interface.
• ReAct — "Synergizing Reasoning and Acting in Language Models" — the tool_use baseline this project departs from.
• The science Skills stand on ColabFold / AlphaFold, ESM, OpenFold, Boltz, Chai, ProteinMPNN, DiffDock, Evo2, Borzoi, scGPT, scVI-tools and open data services (NCBI, UniProt, RCSB PDB, EBI, OpenAlex, Crossref).

---

🔒 License

Released under the MIT License — see LICENSE.

---

✨ Star history

---

✏️ Citing

@software{openai4s2026,
  title  = {OpenAI4S: An Open-Source Code-as-Action Scientific Research Agent},
  author = {OpenAI4S contributors},
  year   = {2026},
  url    = {https://github.com/PKU-YuanGroup/OpenAI4S},
  note   = {Open AI for Scientist — a pure-stdlib reproduction of the Code-as-Action paradigm}
}

🤝 Community contributors

_{Auto-generated from the GitHub contributors graph by scripts/update_contributors.py (Contributors workflow).}

---

_{OpenAI4S · code is the action, the kernel is the environment. · 简体中文 · Friend Link https://linux.do}