NVlabs/SoL-Pi

⚡ SoL-Pi: Scaling Auto-Research Loops for Efficient Agent Harnesses

[!NOTE]

This repository contains the open-source version of SoL-Pi, a standalone extension for Pi. It is not an official distribution of Pi.

💡 TL;DR

Spend less without making the agent do less useful work.

SoL-Pi is a standalone extension for Pi that packages four reusable efficiency mechanisms discovered through scaled auto-research loops. It reduces repeated model turns, context replay, oversized observations, and unnecessary long-log reading while preserving the work and evidence an agent needs to finish a task.

SoL-Pi installs on top of an unmodified Pi release. Every mechanism is opt-in and disabled by default.

Introduction

Long-running coding agents accumulate repeated work. A file edit is often followed by a predictable validation command. Large tool results are replayed long after their first use. Completed subtasks remain in active context, and a frontier model may spend a full request reading a log when only a few lines affect the next decision.

SoL-Pi grew out of a broader question from our auto-research work: before scaling agent loops, can agents first make the harness itself more efficient? The search focused on constrained efficiency: reducing token traffic, inference work, and agent turns without stopping early, skipping verification, or hiding evidence.

The standalone release contains four mechanisms that survived that process. They operate at different parts of the harness and compose through Pi's public extension APIs.

What SoL-Pi Adds

| Area | Mechanism | What changes | |---|---|---| | Tools | Action Fusion | An edit or write can run its follow-up validation command in the same tool call. | | Observations | ObservationPack | Repeated large text results become stable handles with exact paged recall. | | Delegation | Evidence-Preserving Reducer | Long diagnostic logs become compact receipts only when every retained quotation matches the archived source. | | Context | Online Context Compact | Completed plan steps become candidate points for Pi's native compaction, subject to economic and window-pressure checks; after a successful compaction, Pi continues the task in a new turn. |

The mechanisms share four rules:

• No Pi patches. SoL-Pi imports public Pi APIs and does not vendor the Pi source tree.
• Explicit opt-in. A missing configuration leaves every mechanism disabled.
• Preserve evidence. Original observations remain available locally, and reducer failures leave the original result unchanged.
• Use Pi's runtime choices. Authentication, provider URLs, the main model, and shell behavior remain under Pi's control.

Technical Details and Core Insights

Read the SoL-Pi blog for a deeper look at the technical details, design rationale, and core insights behind SoL-Pi, including how auto-research led to the four efficiency mechanisms and how they work.

Paper

Read our paper: SoL-Pi: Recursively Scaling Auto-Research Loops for Efficient Agent Harness.

Getting Started

Requirements

• Node.js 22.19 or newer
• npm
• @earendil-works/pi-coding-agent 0.85.1

Install

Install the tested Pi release:

npm install --global @earendil-works/pi-coding-agent@0.85.1

Then install SoL-Pi directly from NVlabs/SoL-Pi:

pi install git:github.com/NVlabs/SoL-Pi

To install it only for the current project, use the project-local scope:

pi install git:github.com/NVlabs/SoL-Pi --local --approve

Configure

SoL-Pi uses a single effective configuration. With the official Pi distribution, it looks for a sol-pi.json file in the following locations, in order:

1. .pi/sol-pi.json in the current project, if the project is trusted and the file exists; 2. ~/.pi/agent/sol-pi.json otherwise.

If neither file exists, SoL-Pi uses its built-in defaults. The project-level configuration takes precedence over the user-level configuration; the two files are not merged.

The following conservative configuration enables only the two local mechanisms that make no additional model calls and do not stop an active run:

{
  "version": 1,
  "actionFusion": true,
  "observationPack": true,
  "evidencePreservingReducer": false,
  "onlineContextCompact": false,
  "cacheWriteReadRatio": 12.5
}

Enable additional mechanisms only after reviewing their configuration and security implications. SoL-Pi uses no dedicated environment variables; feature flags, the reducer provider/model route, and the compaction ratio are configured in sol-pi.json. See sol-pi.example.json for a template listing every key.

For the complete schema, see Configuration. Coding agents and automated environments should follow the canonical agent installation and configuration protocol, which describes an all-enabled configuration checked with scripts/check-sol-pi-config.mjs --require-all-enabled.

Storage and Security

ObservationPack and Evidence-Preserving Reducer store session-specific archives under:

/sol-pi//
├── observation-pack/
└── evidence-preserving-reducer/

They archive eligible source material in this directory. The archived copies remain local and are not automatically deleted when the Pi session ends.

Online Context Compact stores its state in Pi's session log. After a successful compaction, it starts a new turn and automatically continues the active task. Cancelling the run or exiting Pi does not trigger automatic continuation.

Evidence-Preserving Reducer may send eligible diagnostic-log content to its configured reducer model using Pi-managed authentication. Review SECURITY.md before enabling it. Do not enable remote reduction for logs that must remain local.

Documentation

| Document | Purpose | |---|---| | Configuration | Config search order, schema, defaults, and trust behavior | | Compatibility | Supported Pi APIs and standalone integration details | | Security | Local storage, remote reduction, and sensitive behavior | | Agent installation | Reproducible installation and all-enabled validation procedure |

Development

Install from the lockfile and run the complete source checks:

npm ci --ignore-scripts
npm run check
npm audit --audit-level=high
node scripts/check-pi-compat.mjs

npm run check covers TypeScript, the complete test suite, and package inspection. The development dependency set is pinned to Pi 0.85.1; runtime Pi packages remain peer dependencies so Pi owns their installation and upgrades.

Project Status

SoL-Pi is developed and maintained by NVIDIA as a standalone extension for Pi.

We welcome tested, Pi-compatible extension PRs that improve token efficiency and reduce token cost. Our team will help benchmark contributions, publish results on a regular reporting cycle, and credit authors of accepted PRs as Contributors. See CONTRIBUTING.md for details.

Acknowledgements

SoL-Pi builds on the public extension interfaces provided by Pi. Pi remains an independent upstream project and is not vendored into this repository.

License

SoL-Pi is released under the MIT License.

Star History