proteus-evolve 0.1.0

Self-evolution for any agent harness.

Plug in. Evolve. Measure.

Quick Start • Harnesses • How It Works • The Episode Loop • Onboard Your Harness • Recipes • Bring a Benchmark • Add a Measurement • Environments • Measurement

Plug in any agent harness × any model, let it rewrite its own harness over many context-fresh episodes, and measure how the harness changes — under a goal, many goals, or no goal at all.

Named for the sea-god who changes shape at will: Proteus watches a harness reshape itself, and gives you the ruler to measure the change.

🔭 Why Proteus is different

Agent self-improvement is moving from the weights to the harness — the prompts, memory, skills, tools, and control loop the model runs on. Recent systems evolve a harness to raise a benchmark score. Proteus asks a different, complementary question: what does a self-evolving harness actually do, and does an initial condition leave a permanent mark?

Three things set it apart from every existing harness-evolution system:

1. Harness-agnostic. Others evolve harnesses built from their own primitives. Proteus evolves yours: implement one small HarnessAdapter and your agent — the bundled offline minimal harness (the CLI default), DeepSeek Harness, Pi, Aki, or your own — plugs into the same framework, sandbox, and measurement.
2. Goal and no-goal, with visible or hidden evaluators. Others hard-code a single regime: one benchmark verifier, agent blind to the score, goal mandatory. Proteus spans the space — no-goal | one goal | many goals, and evaluators the agent either sees (in the observe phase) or never sees. No-goal, unpressured evolution is a first-class mode.
3. A measurement instrument, not just a score. Others report task pass-rates. Proteus ships the ruler for the harness itself: structural distance between harness states (per surface, path length), a crystallization / swap test (remove the disposition, read the harness back), and behavioural distance with a permutation test (the action-preference statistic). Every condition is read with the same ruler.

🚀 60-second demo (no API key, no Docker)

pip install proteus-evolve  # no model SDK; Python 3.10 adds only a TOML compatibility package

The bundled minimal harness runs fully offline, so you can see the whole pipeline before wiring up a real agent:

proteus run --harness minimal \
    --arm neutral --arm review:notes --arm review:tools \
    --seeds 4 --episodes 8 --out runs/demo
proteus measure --harness minimal --out runs/demo

arm              seeds       notes       tools   (mean units built)
neutral              4         3.5         4.0
review_notes         4        13.0         0.0
review_tools         4         3.8         8.0

behavioural R (between/within arms, last episode): 3.075  p=0.0150

An installed action preference measurably shifts what the harness grows — and the same measure reads a no-goal run and a goal run identically.

🧩 Harnesses in the box

dsh and pi are the source-evolving third-party integrations. At seed time each adapter extracts the pinned harness's real TypeScript source into harness/src/; every later phase boots that copy, rebuilding it when its content changes. The source is therefore a measured, snapshotted loop surface alongside instructions, notes, tools, and skills. The adapters still leave the upstream repositories untouched: they arrange the run copy, launch one prepared container per phase, and parse the harness's own session logs.

🏗️ How it works

flowchart LR
    U["Run config<br/>harness × model<br/>goal + evaluators<br/>arms + seeds"] --> F["Proteus framework<br/>assemble phase prompts"]
    F --> A["HarnessAdapter<br/>run one episode"]
    A --> H["harness/<br/>evolving, snapshotted subject"]
    A --> T["task/<br/>optional benchmark workspace<br/>outside the snapshot"]
    A --> L["native harness logs"]
    L --> E["evaluators<br/>hidden or observe-visible"]
    E --> S["selection + snapshot<br/>accept or preserve-and-restore"]
    S --> F

Every seed runs N context-fresh episodes; only files cross the episode boundary. One episode is four phases:

observe  →  propose  →  act  →  reflect

• observe — take stock; if you configured a visible evaluator, its score on the last episode is shown here.
• propose — list ways to improve your own harness.
• act — carry one out by editing the harness (the goal, if any, is announced here).
• reflect — decide what to keep.

The framework owns everything that is not the harness (prompts, goal text, evaluator routing, snapshotting, selection, measurement). The adapter owns everything that is (how the four phases actually execute). That split is what makes Proteus harness-agnostic.

The core objects

Action preference

An action preference is installed as a Disposition and is guaranteed removable, so the crystallization test can take it away and read what the harness built on its own:

from proteus.core import review, record, NEUTRAL
review("memory")     # each phase: review your memory, act or not
record("tools")      # keep your tools current as you work
NEUTRAL              # the control, F0 — no perturbation

Goals and evaluators

from proteus.core import EvaluatorSpec, GoalConfig, Visibility

GoalConfig.no_goal()                                    # unpressured evolution
GoalConfig.of(text="Become more reliable.")             # stated goal, no evaluator
GoalConfig.of(
    text="Become more reliable.",
    evaluators=(EvaluatorSpec("reliability", my_eval,
                              visibility=Visibility.OBSERVE),),
)                                                       # agent sees the score next episode
GoalConfig.of(text="Pursue A and B together.",
              evaluators=(EvaluatorSpec("a", eval_a),
                          EvaluatorSpec("b", eval_b)),
              selection="accept_reject")               # outer loop rejects regressions

An evaluator is any callable (trace, ctx) -> EvalResult; bring a benchmark verifier, an LLM judge, or one of the built-ins (proteus.core.evaluators).

Sandbox

from proteus.sandbox import SandboxConfig, DockerSandbox
DockerSandbox(SandboxConfig(network="none"))    # no egress
DockerSandbox(SandboxConfig(network="host",     # needs an LLM endpoint
                            env_passthrough=("OPENAI_API_KEY",),
                            mem_limit="4g"))

A self-editing agent writes and runs its own code, so an application-level file sandbox cannot contain it — Proteus runs real harnesses in a container whose filesystem holds the harness and nothing else.

🔌 Onboard your harness

The input is a repository — a git URL or local path:

proteus env scaffold --from https://github.com/org/their-harness --name theirs --ref v1.2.0
proteus env build theirs             # pinned image, resolved sha recorded in the manifest
# write the adapter (7 methods), then:
proteus check --harness mypkg.theirs_adapter:TheirsHarness --episode
proteus run   --harness mypkg.theirs_adapter:TheirsHarness --arm neutral ...

proteus check machine-verifies the contract (removable disposition via fingerprint round-trip, snapshot-ability, trace shape). The full guide: docs/ADAPTERS.md.

📦 Prepared environments

environments/ contains two environment shapes. Manifest-backed environments pair a Dockerfile or prebuilt image with environment.toml; the built-in dsh-src/ and pi-src/ images are instead built from pinned upstream source checkouts, because the image must contain the exact source and toolchain that the adapter later extracts and rebuilds. In both shapes evolving state lives in mounts, never in a per-run image. Conventions: environments/README.md; design notes: docs/ENVIRONMENTS.md.

📏 Measurement

from proteus.measure import distance, stream, crystallize

• distance — structural distance per surface (added / dropped / revised), path length (proteus measure --travel).
• stream — behavioural distance (frequency / order / procedure) and the between/within permutation test R.
• crystallize — mount an evolved state under a neutral disposition and test whether it reads back as its own endpoint (two-stage fidelity + arm-shift).

To add a per-episode measurement evaluator, a post-run statistic, or an adapter-native counter, see docs/MEASUREMENTS.md. The guide covers their different contracts, artifact boundaries, CLI/report integration, statistical rules, and tests.

📤 Outputs

Every run's primary artifact is its evolution history as a git repository — one commit per episode. Keep it local, browse it, or push it wherever you like (never automatic):

proteus repo export runs/demo/runs/run-<id> my-evolution   # normal repo, `git log` = the trajectory
proteus repo push   runs/demo/runs/run-<id> git@github.com:you/my-evolution.git

Every sweep also ships a live tracking page — per-run progress, per-surface growth curves, evaluator scores — updating while the sweep runs:

proteus watch --out runs/demo          # http://localhost:8300/report.html

Tracking data (condition labels, hidden scores) lives at the sweep level, outside run roots, so the evolving agent can never read its own condition.

📊 Status

v0.1 (research preview). Working today: the offline minimal harness; the live llm harness; pinned, source-evolving DeepSeek Harness and Pi adapters with exact-tree boot, rebuild caching, viability gates, turn budgets, and task mounts; the Aki research adapter; local, Polyglot, and SWE-bench task integrations; resume-safe sweeps; the full measurement, audit, reliability, report, and repository-export paths; and adapter/environment tooling. CI covers Python 3.10–3.14. The separate release-smoke workflow runs two episodes across the public release set (minimal, llm, dsh, pi), exercises the benchmark path, and requires both container harnesses to edit their own source and boot the edit; releases use pinned upstream versions, while the weekly upstream canary is advisory. As a cross-implementation check, Proteus's behavioural ruler applied to the research runs independently reproduces their headline dynamics: arms separate at episode 1 (R = 1.63) and converge by episode 30 (R = 0.93).

📖 Citation

See CITATION.cff. A paper reference will be added when the preprint is public.

License

MIT.