Open Science Agent

open-science-agent is a coding-agent CLI built for reproducible, auditable agentic open science.

All agentic operations are stored to disk and Git.

For example, one short tool-using session produces an inspectable sequence:

agent-session/events/
├── 00000001-….json  system_message
├── 00000002-….json  user_message
├── 00000003-….json  tool_called
├── 00000004-….json  tool_completed
└── 00000005-….json  assistant_response

The design is fully aimed ay open and reproducible computational work: every retained semantic decision is an immutable, reviewable Git commit. This makes an agent's work independently inspectable and auditable. Also, the durable traces provide a native memory system that can be exploited by agents across different sessions.

open-science-agent uses AgentKnit for model/tool execution and recovery.

Install

Python 3.11 or newer is required. AgentKnit is pinned to a tested commit.

python -m pip install '.[dev]'

Run

The default model is Z.ai glm-5.1; its credential is read from the local keyring entry z.ai / api_key and is never archived.

open-science-agent run "List the files and explain this project" \
  --session-dir sessions/demo --cwd .

Use an OpenAI-compatible endpoint with an environment-variable credential:

open-science-agent run "Review this repository" \
  --session-dir sessions/review --cwd . \
  --model my-model --endpoint https://api.example/v1 --key-env EXAMPLE_API_KEY

Pass --resume with the same --session-dir to continue a session. With no prompt, run reads one prompt per stdin line; /exit ends the session.

Session archive

Every semantic event is fsynced, written as one pretty-printed JSON file, and immediately committed to a Git repository in the selected session directory:

sessions/demo/
├── .git/
├── .gitignore
└── agent-session/
    ├── events/       # one immutable, Git-tracked JSON file per semantic event
    └── native/       # AgentKnit recovery journal and snapshot, Git-ignored

The Git-facing trace has only system_message, user_message, assistant_response, tool_called, tool_completed, and runtime_error records. Tool-only assistant responses are represented only as tool_called. Each record is an immutable, pretty-printed JSON file and one Git commit.

The native journal retains recovery-only boundaries such as turn start/end; it is excluded from Git so an appended JSONL prefix never consumes a new Git blob on every event. Raw SSE callbacks and request-attempt echoes are omitted.

Inspect recovered state or render the archived conversation:

open-science-agent inspect sessions/demo
open-science-agent transcript sessions/demo

Durability and privacy

Session folders are created with owner-only permissions. Prompts, tool input, and tool output can contain sensitive content, so protect or delete them as appropriate. A record is acknowledged only after flush and fsync. This does not make bytes still in provider/kernel buffers durable, nor reverse an external side effect after a process crash.

Development

python -m pytest -q

GitHub Actions runs this test suite on Python 3.13.