trampoline-ai/predict-rlm/rlm

Create a PredictRLM

Check for skill updates

Before planning or building, check whether the installed rlm skill has an update:

npx skills update rlm

Replace npx with pnpx, bunx, or the equivalent package runner in use. After an update, re-read the skill before continuing.

An RLM is a callable, pre-configured agent. It autonomously explores context, writes and executes code in a sandboxed REPL, calls tools, inspects results, and iterates until the task is done. Unlike a chat agent, an RLM is a function — you define its inputs, outputs, and tools, then call it from your code. It returns structured data, not chat messages.

Mental model

The caller supplies a DSPy signature. Its input and output fields are the function contract, and its docstring is the operating procedure. On each call:

1. PredictRLM prepares the typed inputs and acquires a sandboxed execution

session. The default backend is a stateful Python REPL running through Deno and Pyodide/WASM.

1. The outer LM reads the signature and strategy, then writes Python code

to inspect inputs, preserve intermediate state, branch, retry, and verify. Python variables persist across iterations of that call.

1. Sandbox code can use await predict(...) for focused sub-LM perception

or extraction. Each predict() call has its own context window and can use a typed DSPy signature, Pydantic schemas, and dspy.Image.

1. Sandbox code can also use packages and modules supplied by Skill objects,

call host-side tools for capabilities outside WASM, and access explicitly allowed network domains.

1. When the work is complete, the outer LM calls SUBMIT(...). PredictRLM

validates the declared outputs, synchronizes file outputs to the host, and returns a dspy.Prediction with the output fields and a structured trace.

The separation is deliberate: the outer LM owns planning and code execution; the sub-LM owns narrow understanding tasks; deterministic libraries and tools do the work they are better suited for. Large context stays in files, sandbox variables, and focused subcalls instead of accumulating in one prompt.

application call
    -> DSPy signature: inputs + strategy + outputs
    -> outer LM <-> stateful sandbox REPL
                     |-> predict() -> sub-LM
                     |-> skill packages and modules
                     `-> host-side tools
    -> validated dspy.Prediction + trace

Core API

A minimal typed RLM has a signature, a configured PredictRLM, and a normal sync or async call:

The signature class docstring is the model instruction prompt passed to the outer LM. It is not merely developer documentation: put the RLM's workflow, decision rules, verification steps, and completion criteria there. Changing the docstring changes the model's runtime behavior.

import dspy
from pydantic import BaseModel, Field
from predict_rlm import CtxStr, File, PredictRLM
from predict_rlm.skills import pdf
class Analysis(BaseModel):
    summary: str = Field(description="Grounded summary of the documents")
    risks: list[str] = Field(description="Material risks supported by the documents")
class AnalyzeDocuments(dspy.Signature):
    """Inspect the documents, apply the criteria, and return a grounded analysis.
    Survey the files first. Extract only relevant evidence with focused
    predict() calls, verify important claims, then submit the typed result.
    """
    documents: list[File] = dspy.InputField(desc="Documents to inspect")
    criteria: CtxStr = dspy.InputField(desc="Criteria the outer LM must see in full")
    analysis: Analysis = dspy.OutputField(desc="Evidence-grounded analysis")
rlm = PredictRLM(
    AnalyzeDocuments,
    lm="openai/gpt-5.4",
    sub_lm="openai/gpt-5.1",
    skills=[pdf],
    max_iterations=30,
)
result = await rlm.acall(
    documents=[File(path="report.pdf")],
    criteria="Cover obligations, deadlines, and material risks.",
)
print(result.analysis.summary)

Use rlm(...) for a synchronous call and await rlm.acall(...) for an asynchronous call. Both return a dspy.Prediction; each declared output is available as an attribute such as result.analysis.

The main constructor surface is:

• signature — a DSPy signature class or compact string signature;
• lm — the outer LM that writes code;
• sub_lm — the LM behind the built-in predict() tool;
• skills — reusable instructions, PyPI packages, sandbox modules, and tools;
• tools — sync or async host callables exposed inside the sandbox;
• allowed_domains — the sandbox network allowlist, empty by default;
• max_iterations, max_llm_calls, and max_output_chars — execution budgets;
• output_dir — host collection root for declared File outputs;
• verbose and debug — human-readable run output and lifecycle diagnostics.

Use File or list[File] for large file inputs and generated artifacts. Use CtxStr for a direct string input, such as a rubric, whose full runtime value must be added to the outer LM prompt as well as exposed as a Python variable. Use a Skill when the sandbox needs reusable instructions, packages, modules, or bundled tools. Use tools= directly for specific host-side actions such as authenticated APIs, databases, native libraries, or host filesystem access.

Runtime kernel and extension model

Most RLMs should use only signatures, File, CtxStr, Workspace, skills, and host tools. Extend the kernel only when the workflow needs a new typed boundary, resource lifecycle, execution substrate, or correctness-critical event stream. Do not reach for a custom adapter merely because a signature uses a Pydantic model.

At construction, PredictRLM resolves direct options and RuntimeContribution module factories into one immutable RuntimeSpec: instructions, adapters, tools, packages, exactly one execution backend, event sinks, validators, and tool operations. Module factories run once at construction. Every invocation then creates a fresh RunContext for mutable state, prepared inputs, bindings, output reservations, cleanup callbacks, and evidence status.

Kernel lifecycle and ownership

construction
  direct options + RuntimeContribution modules
      -> immutable RuntimeSpec
 
invocation
  prepare typed inputs and output requirements
      -> compile path and artifact claims
      -> open adapter-owned resources
      -> validate requirements and acquire one ExecutionSession
      -> bind inputs and reserve outputs
      -> apply invocation-local prompt contributions
      -> run generated-code attempts
           -> after_execution durability hooks
      -> materialize submitted outputs while the session is active
      -> finalize input adapters in reverse order
      -> finalize and release the kernel-owned session
      -> run remaining LIFO RunContext cleanup

The ownership boundaries are strict:

• Adapters declare requirements and destinations before session acquisition.
• The ExecutionBackend creates the invocation-scoped ExecutionSession.
• Adapters may use supported backend or session capabilities, but never acquire,

finalize, or release the session.

• Mutable provider clients, leases, baselines, and retry state belong in the

invocation's PreparedInput or RunContext, never on a shared adapter.

• Sandbox destination overlaps fail before generated code runs.
• Adapter resources finalize on success, failure, setup failure, and

cancellation. Framework-owned session finalization still runs after adapter errors.

Choose the smallest extension point

Use the first boundary that can express the requirement:

1. Signature docstring or `CtxStr` — task strategy or invocation-specific

criteria the outer LM must read.

1. `Skill` — reusable outer-LM instructions plus sandbox packages,

importable Python modules, or bundled host tools.

1. `tools=` — a narrow sync or async host callable. Use this for native

libraries, credentials, APIs, databases, and host filesystem access. Return plain JSON-like data or Pydantic values that can be normalized at the transport boundary.

1. `File`, `Workspace`, or an existing adapter — ordinary copied files,

generated files, or a mutable directory. Prefer these built-ins over a new type.

1. `InputAdapter` with `PreparedInput.path()`, `.paths()`, or `.glob()` — a

custom typed input can first be materialized as host paths. The kernel owns destination normalization, overlap checks, copying or explicit mounting, backend requirements, and the model-visible sandbox paths.

1. Full `InputAdapter` lifecycle — an external resource needs a provider

lease, live handle, per-attempt synchronization, or a custom session capability that cannot be represented as host paths.

1. `OutputAdapter` — a custom output needs a reserved destination and

provider-specific materialization while the session is still active.

1. `RuntimeContribution` through `modules=` — several host-side extensions

belong together and should compose as one reusable construction-time unit.

1. `EventSink` through `events=` — a consumer needs ordered lifecycle events

during the run. Use prediction.trace for the completed trajectory and prediction.evidence for the separate completed lifecycle log.

1. `ExecutionBackend` through `execution=` — only for a genuinely new

sandbox or execution substrate. Use sandbox_backend="jspi" or "sbx" for maintained backends.

interpreter= is a compatibility bridge for older CodeInterpreter-shaped integrations, not the root extension contract. New session-native integrations must implement ExecutionBackend and use execution=.

Input adapters

An InputAdapter[T] selects signature fields through value_type and turns the caller's value into model-visible data and runtime requirements. Adapter instances are construction-time objects and may serve concurrent calls, so keep them immutable or concurrency-safe.

Use the current lifecycle names and responsibilities:

• prepare(field, value, ctx) -> PreparedInput runs before backend acquisition.

It receives no backend or session. Return declarative paths, artifacts, sandbox-root reservations, metadata, requirements, and input instructions.

• open(field, prepared, ctx, backend) may acquire an adapter-owned client or

lease after all inputs are prepared but before a session exists. Store the handle in ctx.state under an adapter-owned key.

• bind(field, prepared, ctx, session) -> BoundInput runs after acquisition.

Use it only when the default artifact mounting is insufficient; return the final value and bindings visible to generated code.

• append_prompt(prompt, field, prepared, ctx) -> str may add invocation-local

context to the outer action and forced-extraction prompts after binding. It must not mutate the canonical PredictRLM.signature.

• after_execution(field, prepared, ctx, session, result, error) runs after

each completed generated-code attempt. Use it for durability or sync work, including changes made before that attempt raised an error.

• finalize(field, prepared, ctx, session, error) performs the final save and

releases adapter-owned resources. Opened adapters finalize once in reverse order; session is None if acquisition failed.

For the common path case, implement only prepare():

class S3FileAdapter(InputAdapter[S3File]):
    name = "s3-file"
    value_type = S3File
    async def prepare(self, field, value, ctx) -> PreparedInput:
        local_path = await materialize_s3(value.uri, ctx=ctx)
        return PreparedInput.path(
            local_path,
            instructions=(f"{field.name} is available at its sandbox path.",),
        )