Dream-RSI SDK · Beta

Bring your agent. Preserve verified quality. Account for every model request.

An independent, unofficial Python SDK inspired by Dream-RSI research. Maintained by TheAstrayDev, who is not a Google or Google DeepMind employee. This is a personal research initiative, not a commercial Google development, official SDK or endorsed product.

Python 3.11+ · zero core third-party dependencies · Apache-2.0 · version 0.3.0b3.

Install

python -m pip install --pre --upgrade dreamrsi==0.3.0b3

For a source checkout, install with python -m pip install -e ..

The package includes the Python API and the dreamrsi command. Publishing policy packages to GitHub additionally requires GitHub CLI (gh).

What's new 0.3.0b3

• Causal dream scoring: AttainmentObjective rewards earlier raw-quality attainment from recorded trajectories, without extra model requests. Complete batches and missing transitions count toward attempted work; quality/cost promotion gates remain independent.
• Explicit weight development: WeightUpdateMethod and optional TorchWeightBackend train a model copy, freshly validate both versions and support versioned checkpoints and rollback. Activation requires allow_weight_updates=True; the default SDK keeps model weights fixed.
• Reliable policy revisions: connection failures pause development after one attempt. Explicit resume retains trees, revision position and charged usage.
• Independent evidence: optional confirmation groups must each pass promotion. PolicyGuidance carries explicit corrections and provenance.
• Local model discovery: a single served llama.cpp model can be discovered explicitly with LlamaCppPolicyModel(model=None) and cached without hidden retries.

from dreamrsi import AttainmentObjective, DreamRSI

sdk = DreamRSI(
    agent=my_agent, evaluator=my_evaluator,
    objective=AttainmentObjective(
        probe_budget=8, quality_floor=0.0, quality_ceiling=1.0,
    ),
)

Supply your integrations and bounds appropriate to the raw-quality scale. Normalization is not a stopping certificate or the paper v2's full preference sweep. Enable the optional training backend with:

python -m pip install --pre "dreamrsi[training]==0.3.0b3"

Weight development needs a trainable model, explicit loss/quality functions and independent examples. It rejects any checked per-example quality loss and consumes a fresh validation group per attempt. The inference agent must read backend.model to use accepted weights. Old-model replay/champion state is invalidated. Training compute is not assumed free; an inference-only API or GGUF file does not expose trainable weights. See the working CPU example and weight guide and reliable development guide. This release makes no new LLM quality or all-in ROI claim.

Explore your search locally

Live Inspector makes recorded exploration visible in a local browser: animated active branches, node details, optional policy reasons, history playback and policy comparisons on recorded worlds. Pan, zoom and collapse branches; inspect raw quality and the preparation/application call ledger separately. Incomplete tokens and dollar usage stay unknown.

Try the interface without an API key:

dreamrsi watch --demo

The demonstration uses no LLM and is not a performance benchmark. Create a short runnable application and record your first tree:

dreamrsi init
python dreamrsi_app.py
dreamrsi watch

Replace the generated agent and evaluator with your integration. init refuses to overwrite an existing file. Attach LiveInspector() to an existing runtime with DreamRSI(..., inspector=inspector) and keep the context manager open during execution. The observer uses a local SQLite journal and does not steer search. Persistent policy memory remains a separate explicit integration.

dreamrsi doctor checks local setup; dreamrsi inspect FILE validates a policy/tree bundle. result.report() prints a concise per-run summary. Export a selected run as a self-contained HTML report with the viewer's Export report button or dreamrsi watch --export report.html.

No hosting, Node.js, CDN or additional runtime dependency is required. The server is read-only and binds to loopback. Capture can contain private task data; use include_content=False when appropriate and review reports before sharing them. Observer CPU/disk overhead can affect very tight time limits. The default StrictReplay comparison makes no agent/evaluator calls; custom components keep their own behavior. Comparisons do not promote policies or prove unseen-task quality.

See the Inspector guide, release notes and verification record. Existing quality protection and all-in accounting remain available below.

Quality protection and all-in accounting

QualityContract protects the supplied original policy's search and complete batches. Stop only when the best valid raw quality exactly reaches a proven task maximum. Unknown bounds continue the original search. The actual returned answer is selected by raw quality rather than a work-penalized composite score.

from dreamrsi import Budget, DreamRSI, EconomyPlan, QualityContract

rsi = DreamRSI(
    agent=my_agent,
    evaluator=my_evaluator,
    policy=my_original_policy,
    budget=Budget(model_calls=4),
    quality=QualityContract(id="exact-quality-v1", upper_bound=1.0),
    economy=EconomyPlan(baseline_calls_per_task=4, horizon=6),
)
result = await rsi.run(task)

Replace these application integrations. Use 1.0 only when it is a sound global bound for the feasible answer domain. Strict mode requires no policy training. Custom raw-quality extractors, local task-bound functions and an evaluated initial candidate are supported. Reference and SDK budgets and initial candidates must match. Use an otherwise identical contract with certified_stopping=False for the full reference, preserving quality metadata in both arms. The no-loss argument compares the same response trajectory, not independent stochastic runs or different time cutoffs.

EconomyPlan recalculates preparation headroom from actual spending, historical costs and the unfinished deployment floor before each request. Completed-task counters survive recovery; measured strict payback uses actual deployment costs. Purpose-tagged ledgers count reported nested provider calls and failed requests. Unknown tokens/dollars remain unknown. The economic target does not truncate quality-preserving fallback search.

The sandbox now has finite small, balanced and large presets and JSON profile save/load. All supported language features remain enabled in each preset; individual limits and allowlists are configurable. A bounded validated-code cache keeps fresh execution state and checks. Local paired interpreter timings improved by 2.90x with one frontier node and 1.41x with eight; these are not model-call savings.

from dreamrsi import PolicySandbox, SandboxConfig

sandbox = PolicySandbox.from_preset("large", max_steps=2_000_000)
SandboxConfig.preset("large").save("sandbox.json")
sandbox = PolicySandbox.from_file("sandbox.json")

Raw-quality callbacks receive isolated records. Built-in stores atomically reserve holdouts, and nested source policies retain their sandbox profile during recovery.

Existing applications retain empirical policy development without a quality contract. Set preserve_policy=False explicitly to enable policy rewrites with the contract. Holdout evidence does not prove universal no-loss transfer.

The public PolicyDeveloper protocol, versioned schema rejection, legacy bundle checks and installed-wheel CLI/sandbox gates form the Beta integration surface. Nested certified artifacts require 0.3.0b1 or newer. See the Beta notes, quality proof and all-in guide.

Third-party policy and replay packages

Portable JSON bundles and GitHub-hosted package sharing transfer recorded experience. Community developers can distribute policy versions and recorded discovery trees; recipients import them into local SQLite memory with their own agent, quality metric, task-family contract and acceptance rules. These replay datasets contain observed search transitions, not model weights. Saved policies can avoid repeated development when they meet the recipient's quality floor; new tasks still run the recipient's agent.

dreamrsi list
dreamrsi install OWNER/REPOSITORY
dreamrsi save my-policy-pack --all
dreamrsi publish .dreamrsi/packages/exports/my-policy-pack.dreamrsi.json

Use a real package reference for OWNER/REPOSITORY. Export requires previously saved memory; publication requires GitHub CLI and creates a public repository. See the complete walkthrough for the diagram, executable integration example, and compatibility requirements.

Basic agent integration

from dreamrsi import Budget, DreamRSI

rsi = DreamRSI(
    agent=lambda task: task.upper(),
    evaluator=lambda answer: float(len(answer)),
    budget=Budget(model_calls=4),
)
result = rsi.run_sync("hello")
print(result.best)  # HELLO

This example demonstrates integration, not quality improvement. Stateful adapters support generate/evaluate/refine tasks. Replay uses recorded outcomes without new discovery calls. LLMPolicyDeveloper writes and iteratively rewrites executable source from measured feedback. Persistent champion reuse and recorded-history replay can avoid repeated development. Promotion uses independent validation and paired raw-quality/probe evidence. Broad end-to-end economics remain unverified; the narrow follow-up below has separate limits. The SDK includes configurable Docker-free policy interpreters, optional process execution, held-out validation, SQLite recovery and reported token/USD accounting.

Measured experiments

Latest local follow-up: real Bonsai Q2 answers and structural transfer

An isolated experimental Lasso module using the SDK's QualityContract hooks started with empty memory and eight new application tasks. Local Bonsai Q2 generated preparation and fallback answers; a mathematical active-pattern transfer made no model requests when exact rational KKT checks certified the new answer. This module is not included in the installed SDK and did not generate policy code.

Raw quality was equal or better on every paired task after a separate control repeat. The fresh campaign saved 37.5% of calls, including two preparation calls; four application tasks needed no LLM request. One baseline request timed out, so the original preregistered success flag remains false. The affected control was repeated separately, and all 28 actual calls are retained in accounting. Complete control token usage and dollar ROI remain unknown. Adding 12 earlier research calls gives 22 Dream-side calls; historical research has not paid back against this series's 16-call matched baseline.

This is a small two-feature Lasso follow-up, with two nonoptimal Dream answers. A conventional exact solver also needs zero LLM calls on these tasks. It does not prove universal SDK savings or an advantage over classical optimization. See the figure and verification record.

Earlier policy-development records remain available in the linked experiment documentation.

• Full documentation and roadmap
• Bonsai Q2 experiment
• GPT-6 Luna experiment
• Integration and recovery
• Sandbox configuration
• Issues
• Original Dream-RSI paper

Beta integration contracts are documented; pre-release APIs may still evolve. Generated source runs in a bounded Python-syntax subset, not arbitrary Python. External state isolation and remote cancellation require adapter support. Usage caps depend on accurate provider reports and ceilings. Research-scale performance and broad generalization remain unverified.