pwm-agent-core 1.0.0

PWM agent runtime (core): the AI4Science harness + pwm_agent_core facade that standalone PWM agent packages run on.

AI4Science CLI

Open-source contribution tool for Physics World Model (PWM).

Create, validate, package, and submit Principles, Specs, Benchmarks, and Solutions for verified AI4Science workflows — from your terminal.

Install (one line, no root / pipx / admin needed):

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/integritynoble/AI4Science/main/install.sh | bash

# Windows — in PowerShell (open "PowerShell" from the Start menu, NOT cmd.exe):
irm https://raw.githubusercontent.com/integritynoble/AI4Science/main/install.ps1 | iex

:: Windows — from Command Prompt (cmd.exe)? irm/iex are PowerShell-only, so wrap it:
powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/integritynoble/AI4Science/main/install.ps1 | iex"

Then run ai4science login — browser approval signs you in with PWM founder-served models (no API key, no Node) and drops you straight into a chat session (like Claude Code). The installer sets up an isolated environment under ~/.ai4science, puts the ai4science command on your PATH (works on locked-down HPC login nodes too), and needs only Python ≥ 3.10 — no git, no Node. Lean install without the agent: AI4SCIENCE_WITH_CLAUDE=0 curl … | bash. (Once published, pipx install "pwm-ai4science[claude]" also works.)

---

Getting started in 5 steps

1. Install — Linux/macOS below (Windows: see the one-liner above). Needs only Python ≥ 3.10; no git, no Node.

curl -fsSL https://raw.githubusercontent.com/integritynoble/AI4Science/main/install.sh | bash

Open a new terminal afterward (the installer adds ai4science to your PATH). If a command still isn't found, run export PATH="$HOME/.local/bin:$PATH".

2. Log in — and you're chatting. One step: on success it drops you straight into a session.

ai4science login        # browser approval → PWM founder-served models (no key, no Node)

Prefer your own LLM instead? ai4science login --provider anthropic|openai|gemini.

3. Use it. Start a session any time, or run a one-shot prompt:

ai4science                       # interactive chat session (like `claude`)
ai4science "summarize spec.md"   # one-shot question

Inside a session: ask questions, let it edit files (you confirm each change), /help for slash commands, /exit to leave.

4. Update to the latest build whenever you like:

ai4science update

5. Earn PWM by improving the agents. Using the agent costs PWM; the easiest way to earn it back is feedback. Inside any chat session:

/feedback the CASSI judge should accept .h5 inputs too

Useful feedback is rewarded instantly (an LLM scores its quality). You can also contribute tools/solutions that agents use on paid turns — those earn weekly for as long as they're used. Bootstrap a first balance by mining on physicsworldmodel.org. Full details in Earning PWM below.

---

1. What is AI4Science CLI?

ai4science is a session-style command-line tool (in the spirit of claude or codex) that helps you contribute reproducible scientific work to the Physics World Model (PWM) protocol. It's the user-facing product layer; PWM is the protocol, registry, and verification layer underneath.

Earning PWM — improve the agents

Usage is paid in PWM, and the primary way to earn PWM is improving the agents themselves: /feedback a problem or suggestion in any agent chat (an instant reward that refills a shrinking runway — ~19 turns, then 18, … floor 5 — unlocked only when your PWM is nearly used up after real usage), or contribute tools/solutions that agents use in paid turns (usage-weighted, earns weekly for as long as it's used). The six agent pools hold 4,000,000 PWM and pay out weekly via A_k = (M_pool − M(t)) × w_k / Σw_j — this can out-earn website mining by orders of magnitude. Bootstrap your first balance by mining on physicsworldmodel.org (≈2 PWM instantly at LLM-accept, your full A(t) share at founder promotion). Details: docs/AGENT_IMPROVEMENT_EARNING_METHOD.md · docs/AI4SCIENCE_USER_MANUAL.md.

The CLI runs locally in v0.1: nothing leaves your machine. You can:

• Create a four-layer contribution (Principle → Spec → Benchmark → Solution) from templates or examples.
• Validate the YAML front matter and required fields with Pydantic.
• Run the CASSI Physics Judge locally (deterministic Python, no LLM in the verdict path) and get a judge_report.json.
• Run a local Overseer review that combines validate + judge + claim-vs-results checks + suspicion scans.
• Package your submission into a self-contained .zip with a SHA256 certificate.
• Dry-run a submission so you can see exactly what would be sent before going live.

2. What is Physics World Model?

PWM is a four-layer protocol for verifiable AI-for-science:

Layer	Artifact	What it is
L1	Principle	A physical law as a first-class registry artifact (e.g. "Beer-Lambert Law for FRET").
L2	Spec	A formal six-tuple (Ω, E, B, I, O, ε) that fixes a problem instance from the principle.
L3	Benchmark	A reproducible task: dataset + metric + baseline + success threshold.
L4	Solution	A solver / AI-assisted submission against a benchmark, scored deterministically.

PWM's permanent moat is not the LLM, not the agent framework, and not the UI. It is the eight protocol assets that no replaceable worker can substitute for:

1. spec.md format
2. benchmark protocol
3. submission format
4. certificate format
5. deterministic Physics Judge
6. public registry
7. governance rules
8. token / reward economy

Claude Code, OpenAI Codex, Claude Agent SDK, OpenHands, and other agents are replaceable workers. They produce drafts; the deterministic Physics Judge produces verdicts.

3. Artifact hierarchy

L1 Principle  ──anchors→  L2 Spec  ──anchors→  L3 Benchmark  ──hosts→  L4 Solution

Each artifact is a Markdown file with a YAML front-matter block (between two --- lines). The front matter is the structured spec validated by ai4science validate and consumed by the Physics Judge. The body below the front matter is free prose.

4. Installation

One command, global (like npm install -g for Claude Code). The chat agent is included by default so ai4science is a Claude-Code-like session:

pipx install "pwm-ai4science[claude]"   # chat agent + deterministic CLI
ai4science                              # → start a chat session

Power the agent with ai4science login (PWM founder-served models — no key, no Node). Optional: the exact Claude Code engine (ai4science --mode claude) uses the claude CLI — npm install -g @anthropic-ai/claude-code then claude login (or set ANTHROPIC_API_KEY); without it, --mode claude falls back to the built-in engine.

The PyPI package is pwm-ai4science; the command is ai4science (same package-vs-command split as @anthropic-ai/claude-code → claude). Plain pip works too: pip install "pwm-ai4science[claude]".

Lean install (deterministic CLI only, no agent): pipx install pwm-ai4science.

Before the first PyPI release, install from GitHub (still one command):

pipx install "git+https://github.com/integritynoble/AI4Science.git"

Install a specific version or channel

The one-line installer takes flags (and matching env vars). It also downloads its own standalone Python if none ≥ 3.10 is present, so nothing else is needed on a fresh machine.

# Pin an exact release — Linux/macOS (accepts "0.6.26" or "v0.6.26")
curl -fsSL https://raw.githubusercontent.com/integritynoble/AI4Science/main/install.sh | bash -s -- --version 0.6.26

# Pick a channel:  --stable (default) | --rc | --dev (latest main)
curl -fsSL https://raw.githubusercontent.com/integritynoble/AI4Science/main/install.sh | bash -s -- --rc

# Windows — flags can't pass through `irm | iex`, so use the env var:
$env:AI4SCIENCE_VERSION="0.6.26"; irm https://raw.githubusercontent.com/integritynoble/AI4Science/main/install.ps1 | iex

Already installed? Switch lines without reinstalling: ai4science update --rc (or --stable / --dev). The same installer is mirrored at https://physicsworldmodel.org/install.sh and /install.ps1, and the website documents it at physicsworldmodel.org/start#install-version. Released tags: see Releases (latest stable v0.6.26).

From source (to modify / run tests): git clone … && pip install -e ".[dev]" && pytest. Full step-by-step for any OS incl. Windows: docs/INSTALL.md. Maintainers: docs/RELEASING.md.

5. Quickstart

Just like Claude Code, run the bare command to start an interactive session:

ai4science          # no arguments → drops you into a chat session (like `claude`)

(Run ai4science login first to power the agent — no key or Node required. If you're not logged in yet, ai4science prints a short getting-started panel. The deterministic commands below always work, offline.)

ai4science init cassi-demo          # creates a workspace seeded with the CASSI example
cd cassi-demo
ai4science status                   # show what's in the workspace
ai4science validate                 # parse + Pydantic-validate all four artifacts
ai4science judge cassi --submission .   # run the deterministic Physics Judge
ai4science overseer review --submission .
ai4science package                  # zip + SHA256 certificate
ai4science submit --dry-run         # show what would be submitted

After judge you'll find reports/judge_report.json. After overseer, reports/overseer_report.{md,json}. After package, an ai4science_submission_<timestamp>.{zip,manifest.json} pair.

Interactive REPL chat (Claude Code-like)

For a persistent conversation with the agent — preserves state across follow-ups, supports tool use with confirmation prompts, has slash commands:

ai4science chat                       # opens a REPL with --agent claude
ai4science chat --read-only           # text-only; no file edits
ai4science chat --yes                 # auto-approve all Edit/Write/Bash

Inside the session:

ai4science> What does spec.md currently declare for tolerance_epsilon?
[Claude reads the file and answers]

ai4science> Change it to 0.005 and update the table row too
[Claude proposes Edit(s); you confirm y/N for each unless --yes]

ai4science> /validate          # run deterministic validate without leaving
ai4science> /help              # list slash commands
ai4science> /exit              # leave

Slash commands: /help, /exit, /clear, /files, /validate, /judge, /status, /cost. The conversation state and the SDK's Read/Edit/Write/Bash tools are all preserved across turns within a session.

File @mentions

Reference any file in your workspace by typing @path/to/file inside a prompt. The file gets attached (read-only) to that turn, in both chat and one-shot modes:

# Chat session
ai4science> @code/run_solver.py — what's wrong with this solver?

# One-shot
ai4science --agent claude "@code/run_solver.py what's wrong here?"

Sandbox rules: absolute paths (@/etc/passwd), traversal (@../escape), and references to non-existent files are silently ignored — so writing about the @property decorator or someone's [e-mail] won't accidentally attach anything.

Image input

@-mention an image file (.png .jpg .jpeg .gif .webp) in chat and the agent sees it — useful for reconstructions, plots, optical diagrams:

ai4science> @recon.png — what artifacts do you see in this reconstruction?
ai4science> @psnr_curve.png does this look converged?

The image is attached as a multimodal content block (text files still inline as before); images over 5 MB are rejected.

Custom slash commands

Define reusable prompt templates as <name>.md files — like Claude Code's .claude/commands/. A file becomes /<name>:

.ai4science/commands/tighten.md     →  /tighten     (project)
~/.config/ai4science/commands/*.md  →  user-global commands

tighten.md:

Edit spec.md to change tolerance_epsilon to $ARGUMENTS (YAML + table row), then re-validate.

In a session, /tighten 0.004 expands the template (substituting $ARGUMENTS, or positional $1, $2…) and sends it as a turn. /commands lists what's available; project commands override user-global ones of the same name.

Plan mode

Sometimes you want a structured plan before any edits happen — what changes, where, in what order, with risks called out. Plan mode runs the agent with read-only tools and a planning-specific system prompt:

# One-shot plan
ai4science --agent claude --plan "Add a T2 benchmark tier with mild calibration drift"

# Whole-session plan mode in chat
ai4science chat --plan

# Single-turn plan inside a regular chat session
ai4science> /plan refactor the solver to use ADMM instead of GAP-TV

In plan mode:

• The agent can Read / Grep / Glob to investigate the workspace.
• The agent cannot Edit, Write, or run Bash — the SDK enforces this via permission_mode="plan".
• The system prompt asks for a structured plan with concrete file paths, actions, rationale, and risks.
• The output is a plan you review and approve — then re-run without --plan (or follow up in chat) to execute.

When mixing flags, the precedence is plan > read-only > tool-use — --plan always disables editing regardless of --yes.

Sub-agents

The main agent can delegate focused tasks to specialized PWM sub-agents (via the SDK's Task tool). Each sub-agent has its own system prompt and a restricted tool set, so it can't accidentally edit files the main agent didn't ask about.

Sub-agent	Tools	Job
physics-reviewer	Read, Grep, Glob	Critique a submission for physical realism — noise-model consistency, ε realism, claim plausibility under spec constraints
schema-validator	Read, Grep, Glob, Edit	Check YAML front matter against canonical PWM schemas and apply minimal-edit fixes for violations only
benchmark-architect	Read, Grep, Glob	Design a new L3 benchmark tier (T2 / T3 / ...) — produces a plan with success threshold calibrated against existing baselines

Sub-agents are on by default for --agent claude. Disable with --no-subagents. The main agent decides when to delegate based on each sub-agent's description.

PWM MCP tools

An in-process MCP server (built with claude-agent-sdk's create_sdk_mcp_server) exposes PWM-specific deterministic tools to the agent:

Tool	Purpose
pwm_validate	Run the deterministic ai4science validator and return a structured report
pwm_judge_cassi	Invoke the CASSI Physics Judge and return the same JSON as reports/judge_report.json
pwm_status	Workspace summary (artifacts, dirs, reports, config)
pwm_lookup_artifact	Read one canonical artifact file (principle / spec / benchmark / solution) with parsed YAML

All four tools are deterministic — no LLM under the hood. The PWM moat is preserved: the agent can call pwm_judge_cassi, but it cannot override the judge's output.

MCP is on by default. Disable with --no-mcp.

Multi-tier benchmarks

A single spec can have several benchmark tiers (T1 nominal, T2 mild drift, T3 adversarial...). Each tier is its own benchmark file:

my-cassi/
  principle.md
  spec.md
  benchmark.md         # T1 (canonical)
  benchmark_t2.md      # T2
  benchmark_t3.md      # T3
  solution.md

Artifacts are discovered by their artifact_type front-matter field, not by filename — so all benchmark tiers are picked up automatically:

ai4science validate                          # validates every tier file
ai4science judge cassi                        # judges benchmark.md (default)
ai4science judge cassi --benchmark benchmark_t2.md   # judges the T2 tier

Tier reports are written to reports/judge_report_<stem>.json (the canonical benchmark.md keeps reports/judge_report.json). The Benchmark schema has optional benchmark_id and tier fields so tier metadata has a canonical home. The PWM MCP tools (pwm_validate, pwm_status, pwm_judge_cassi) are all multi-tier aware too.

6. Prompt-first usage

Like claude or codex, you can invoke ai4science with a free-form English prompt in quotes:

ai4science "Help me create a CASSI spec and benchmark"
ai4science "Validate my PWM contribution and tell me what is missing"
ai4science "Prepare a solution submission for this benchmark"

Prompt routing is two-tier:

1. Utility prompts (validate / judge / package / submit / status / overseer) always dispatch to the deterministic command — an LLM adds nothing, and it costs you nothing. ai4science "validate my contribution" just runs validate.
2. Open-ended prompts (drafting, questions, edits) route to a real agent. By default the agent is auto: it picks the best available backend in order claude → codex → none. So if you have the Claude backend installed (pip install 'ai4science[claude]' + claude login), a bare ai4science "draft a CASSI principle" behaves like claude "…". If no agent is available, it falls back to the rule-based template router.

Override the auto-selection with --agent claude / --agent codex / --agent none, or set AI4SCIENCE_AGENT. Utility prompts stay deterministic regardless of agent.

Worked example: examples/draft_principle — a full four-layer PWM contribution (1D heat equation) drafted conversationally: L1 Principle → L2 Spec → L3 Benchmark → L4 Solution, ending in a runnable Crank-Nicolson solver that beats the benchmark threshold (~140×). Every artifact is agent-written, schema-valid, and the solver pipeline is reproducible.

7. Template-based usage

If you prefer explicit subcommands:

ai4science contribute principle    # creates principle.md from template
ai4science contribute spec
ai4science contribute benchmark
ai4science contribute solution

Each command writes the template into your CWD (without overwriting) and opens it in $EDITOR.

8. Validation and CASSI Judge

ai4science validate parses the YAML front matter in each artifact and validates it against Pydantic schemas:

• Required fields present
• Correct types
• Front matter well-formed

ai4science judge cassi runs four deterministic check families:

Check	What it verifies	v0.1 behavior
S1 — finite specifiability	spec.md exists, well-formed, every required field present and well-typed	pass / fail
S2 — Hadamard stability	Required physical parameters declared	warning (full proof not encoded in v0.1)
S3 — approximability	benchmark.md declares dataset, metrics, threshold, reproducibility command	pass / fail
S4 — certifiability	4 sub-checks: forward residual, noise consistency, Fourier consistency, spatial coherence	pass / fail / warning / not_available

The judge writes reports/judge_report.json and surfaces a silent_failure flag when S1 + S3 pass but an S4 check fails — exactly the "looks valid on paper, doesn't physically reproduce" pattern the protocol exists to catch.

The judge is deterministic Python with no LLM call in the verdict path. This is a hard rule of the protocol.

9. Agent providers: none, Claude, Codex

ai4science/agents/ ships three pluggable providers:

Provider	Status	When to use
none	✅ ships	Default. Prints instructions; no LLM call.
claude	🟡 stub	Phase A2 wires Claude Agent SDK (Anthropic family — contributor role)
codex	🟡 stub	Phase A2 wires OpenAI Codex CLI (OpenAI family — Overseer role)

The provider is configurable per workspace via .ai4science/config.yaml:

agent_provider: none   # 'none' | 'claude' | 'codex'

Hard rule: AI4Science (contributor) and AI Overseer must use different LLM families.

10. Security and sandboxing

When an agent provider actually runs (Phase A2+), these rules are non-negotiable:

• Agent workers may edit only the current contribution workspace.
• Agents must not modify hidden_tests/, judge/, locked benchmark files, or any parent PWM folders.
• Changed files are surfaced to the user before being accepted.
• The final scientific decision is never made by the LLM. It belongs to the deterministic Physics Judge.

11. Open source vs. governed by PWM

Asset	Open source (this repo, MIT)	Governed by PWM protocol
CLI surface (ai4science)	✅	—
Templates	✅	—
Pydantic schemas	✅	Format is governed; field set is canonical
CASSI Physics Judge v0.1	✅	Verdict format is canonical
Agent providers (none, claude, codex)	✅	—
spec.md / benchmark.md / submission format	✅ (reference impl)	PWM canonical
certificate format + hash scheme	✅ (reference impl)	PWM canonical
deterministic Physics Judge	✅ (CASSI v0.1)	PWM canonical (other domains via PWM)
public registry	—	PWM-operated
governance rules	—	PWM founders multisig
token / reward economy	—	PWM-operated

You can fork the CLI; you cannot fork the protocol.

11b. GPU compute providers (Phase 0)

The agent can dispatch a real solver run to a wallet-bound GPU provider and reward it for verified work. Design: docs/COMPUTE_PROVIDERS_DESIGN.md.

Why it's safe to use untrusted GPU: the deterministic Physics Judge re-verifies every result independently (recomputes A(x_hat) + the S1–S4 gates). A provider that returns fake or broken results fails S4 → earns nothing. Providers are verified, not trusted.

# Bind a GPU provider to a wallet (founder tier)
ai4science compute providers-add \
    --id founder-1-subgpu \
    --wallet 0x… \
    --endpoint ~/.ai4science/compute_jobs --tier founder

ai4science compute providers                      # list
ai4science compute dispatch -p founder-1-subgpu \ # send a job (file-inbox)
    --benchmark L3-003-001-001-T1
ai4science compute status <job_id> -p founder-1-subgpu
ai4science compute verify <job_id> -p founder-1-subgpu   # judge re-verifies → credit
ai4science compute credits                        # verified-job credits per wallet

On the GPU box, the provider runs the poller, which watches the inbox, runs dispatched solvers, and writes results back:

# On the sub-GPU host (executes dispatched code — only on a trusted host):
ai4science compute serve -p founder-1-subgpu --allow-exec        # poll forever
ai4science compute serve -p founder-1-subgpu --once --allow-exec  # cron-friendly

The poller acks each job, runs its run_command (cwd = the job's workspace), computes a content-addressed certificate_hash over the reconstruction, and writes job_<id>.result.json. Then compute verify runs the deterministic judge locally; a pass records one verified-job credit bound to the provider's wallet, a fail records zero. --allow-exec is a required safety gate (the poller refuses to execute dispatched code without it). Credits are unit-less in v1 — the PWM-per-credit conversion and on-chain settlement are platform-owned governance decisions; the CLI never moves tokens.

Full loop: dispatch (agent) → serve (GPU box runs the solver) → verify (judge → credit).

Try it locally (one machine, no GPU, never touches a real remote):

• examples/gitsync_compute — the full loop with the dispatcher and provider on separate git clones, exercising --git-sync (the real CPU↔Windows-GPU transport).
• examples/compute_demo — the same loop in-process (no git), as a single script.

Setting up a GPU box: see docs/SUBGPU_SETUP_WINDOWS.md for a step-by-step Windows + CUDA setup (install, wallet binding, shared-inbox options, Task Scheduler / NSSM service, and a test job).

12. Roadmap

v0.1 (this release) — local CLI with deterministic CASSI judge + agent stubs.

v0.2 — Phase A2 agent wiring: ClaudeAgent and CodexAgent call their respective SDKs.

v0.3 — Real submission flow: ai4science submit --for-real with cryptographic signing.

v0.4 — Additional domain judges (CT reconstruction, fluid dynamics, etc.).

v1.0 — Stable schema, public registry sync, multi-chain support.

13. License

MIT. The CLI is open source. The PWM protocol (registry, governance, judge specifications) is governed separately by the PWM organization.

---

Companion docs

• PWM AI4Science Product Strategy (2026-05-27)
• PWM AI Researcher + Overseer Architecture (2026-05-27)
• Hybrid Path Roadmap (2026-05-27)