Buckets:

hf-doc-build
/

doc-dev

Files

xet

hf-doc-build/doc-dev / openenv /pr_1040 /en /environments /pi.html

HuggingFaceDocBuilder

4 days ago

download

raw

39.9 kB

	<meta charset="utf-8" /><meta name="hf:doc:metadata" content="{"title":"Pi Environment for OpenEnv","local":"pi-environment-for-openenv","sections":[{"title":"In-process primitive (no HTTP)","local":"in-process-primitive-no-http","sections":[{"title":"Sandbox backend","local":"sandbox-backend","sections":[],"depth":3}],"depth":2},{"title":"Deployed env (HTTP)","local":"deployed-env-http","sections":[],"depth":2},{"title":"The MCP Tool: run_rollout","local":"the-mcp-tool-runrollout","sections":[],"depth":2},{"title":"Two Operating Modes","local":"two-operating-modes","sections":[],"depth":2},{"title":"Building the Docker Image","local":"building-the-docker-image","sections":[],"depth":2},{"title":"Environment Variables","local":"environment-variables","sections":[],"depth":2},{"title":"Project Structure","local":"project-structure","sections":[],"depth":2}],"depth":1}"/>
	<link href="/docs/openenv/pr_1040/en/_app/immutable/entry/start.CK4JueSy.js" rel="modulepreload">
	<link href="/docs/openenv/pr_1040/en/_app/immutable/chunks/CkC6bgMw.js" rel="modulepreload">
	<link href="/docs/openenv/pr_1040/en/_app/immutable/chunks/BSuxAqoA.js" rel="modulepreload">
	<link href="/docs/openenv/pr_1040/en/_app/immutable/entry/app.DS9dQXci.js" rel="modulepreload">
	<link href="/docs/openenv/pr_1040/en/_app/immutable/chunks/Ds_1Ru_R.js" rel="modulepreload">
	<link href="/docs/openenv/pr_1040/en/_app/immutable/chunks/BNiglU5n.js" rel="modulepreload">
	<link href="/docs/openenv/pr_1040/en/_app/immutable/chunks/DsnmJJEf.js" rel="modulepreload">
	<link href="/docs/openenv/pr_1040/en/_app/immutable/chunks/BAUKCucN.js" rel="modulepreload">
	<link href="/docs/openenv/pr_1040/en/_app/immutable/nodes/0.BYqDucrz.js" rel="modulepreload">
	<link href="/docs/openenv/pr_1040/en/_app/immutable/chunks/CR5HsSXT.js" rel="modulepreload">
	<link href="/docs/openenv/pr_1040/en/_app/immutable/nodes/29.D8djgbSv.js" rel="modulepreload">
	<link href="/docs/openenv/pr_1040/en/_app/immutable/chunks/C07d6Hje.js" rel="modulepreload">
	<!--t0ekmf--><meta name="hf:doc:metadata" content="{"title":"Pi Environment for OpenEnv","local":"pi-environment-for-openenv","sections":[{"title":"In-process primitive (no HTTP)","local":"in-process-primitive-no-http","sections":[{"title":"Sandbox backend","local":"sandbox-backend","sections":[],"depth":3}],"depth":2},{"title":"Deployed env (HTTP)","local":"deployed-env-http","sections":[],"depth":2},{"title":"The MCP Tool: run_rollout","local":"the-mcp-tool-runrollout","sections":[],"depth":2},{"title":"Two Operating Modes","local":"two-operating-modes","sections":[],"depth":2},{"title":"Building the Docker Image","local":"building-the-docker-image","sections":[],"depth":2},{"title":"Environment Variables","local":"environment-variables","sections":[],"depth":2},{"title":"Project Structure","local":"project-structure","sections":[],"depth":2}],"depth":1}"/><!---->
	<link href="/docs/openenv/pr_1040/en/_app/immutable/assets/0.tn0RQdqM.css" rel="modulepreload"> <!--[--><!--[0--><!--[--><!--[0--><!--[--><p></p> <div class="items-center shrink-0 min-w-[100px] max-sm:min-w-[50px] justify-end ml-auto flex" style="float: right; margin-left: 10px; display: inline-flex; position: relative; z-index: 10;"><div class="inline-flex rounded-md max-sm:rounded-sm"><button class="inline-flex items-center gap-1 h-7 max-sm:h-7 px-2 max-sm:px-1.5 text-sm font-medium text-gray-800 border border-r-0 rounded-l-md max-sm:rounded-l-sm border-gray-200 bg-white hover:shadow-inner dark:border-gray-850 dark:bg-gray-950 dark:text-gray-200 dark:hover:bg-gray-800" aria-live="polite"><span class="inline-flex items-center justify-center rounded-md p-0.5 max-sm:p-0 hover:text-gray-800 dark:hover:text-gray-200"><svg class="sm:size-3.5 size-3" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----></span> <span>Copy page</span></button> <button class="inline-flex items-center justify-center w-6 max-sm:w-5 h-7 max-sm:h-7 disabled:pointer-events-none text-sm text-gray-500 hover:text-gray-700 dark:hover:text-white rounded-r-md max-sm:rounded-r-sm border border-l transition border-gray-200 bg-white hover:shadow-inner dark:border-gray-850 dark:bg-gray-950 dark:text-gray-200 dark:hover:bg-gray-800" aria-haspopup="menu" aria-expanded="false" aria-label="Open copy menu"><svg class="transition-transform text-gray-400 overflow-visible sm:size-3.5 size-3 rotate-0" width="1em" height="1em" viewBox="0 0 12 7" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M1 1L6 6L11 1" stroke="currentColor"></path></svg><!----></button></div> <!--[-1--><!--]--></div><!----> <!--[0--><h1 class="relative group"><a id="pi-environment-for-openenv" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#pi-environment-for-openenv"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Pi Environment for OpenEnv</span></h1><!--]--><!----> <p><code>pi_env</code> runs the <a href="https://github.com/badlogic/pi-mono" rel="nofollow">Pi</a> coding agent
	inside an isolated <a href="https://huggingface.co/docs/huggingface_hub/package_reference/sandbox" rel="nofollow">Hugging Face sandbox</a> against any OpenAI-compatible LLM endpoint, optionally capturing per-token
	logprobs for GRPO training.</p> <p>It mirrors <code>opencode_env</code>: same two-layer design (an
	in-process harness primitive + a deployable HTTP env), same transparent-proxy
	logprob capture, same uniform <code>(instruction, setup, verify)</code> Task shape. The
	agent is Pi instead of OpenCode, and the default sandbox backend is Hugging
	Face instead of E2B.</p> <p>The env is <strong>task-agnostic</strong> — every rollout is configured at call-time
	with a uniform Task shape:</p> <ul><li><strong><code>instruction</code></strong> — prompt for the agent</li> <li><strong><code>setup</code></strong> — list of bash commands run <em>before</em> the agent (pip install,
	git clone, file downloads — anything you need staged in the sandbox)</li> <li><strong><code>verify</code></strong> — list of bash commands run <em>after</em> the agent (asserts,
	pytest invocations, score-file writes)</li></ul> <p>Reward = <code>passed_verify / total_verify</code> unless any <code>verify</code> command writes
	a float to <code>/root/logs/verifier/reward.txt</code> (override).</p> <!--[1--><h2 class="relative group"><a id="in-process-primitive-no-http" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#in-process-primitive-no-http"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>In-process primitive (no HTTP)</span></h2><!--]--><!----> <p>For trainers that drive a sandbox directly without an HTTP boundary — this is
	what loop-owning GRPO training uses. The primitive reuses the sandbox backend +
	proxy from <code>opencode_env</code>, so install it alongside <code>pi_env</code>:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-bash "><!---->pip install <span class="hljs-string">"openenv-opencode-env @ git+https://github.com/huggingface/OpenEnv.git#subdirectory=envs/opencode_env"</span><!----></pre></div><!----> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!----><span class="hljs-keyword">import</span> os
	<span class="hljs-keyword">from</span> pi_env <span class="hljs-keyword">import</span> PiConfig, PiSessionFactory, PiTask, HFSandboxBackend

	factory = PiSessionFactory(
	config=PiConfig(
	base_url=<span class="hljs-string">"https://api.openai.com/v1"</span>,
	api_key=os.environ[<span class="hljs-string">"OPENAI_API_KEY"</span>],
	model=<span class="hljs-string">"gpt-4o-mini"</span>,
	sandbox_home=<span class="hljs-string">"/root"</span>, <span class="hljs-comment"># HF sandbox execs as root</span>
	),
	sandbox_backend=HFSandboxBackend(image=<span class="hljs-string">"python:3.12"</span>),
	mode=<span class="hljs-string">"transparent_proxy"</span>, <span class="hljs-comment"># captures per-token logprobs</span>
	)
	session = factory.create(task=PiTask(instruction=<span class="hljs-string">"..."</span>))
	session.wait_for_completion()
	turns = session.fetch_proxy_trace() <span class="hljs-comment"># per-turn (tokens, logprobs)</span>
	session.close()<!----></pre></div><!----> <p>Pi is pointed at the endpoint via a <code>models.json</code> provider block written under <code>PI_CODING_AGENT_DIR</code> (<code>api: openai-completions</code>), then launched headless with <code>pi --print --no-session --mode json</code>. In <code>transparent_proxy</code> mode the
	in-sandbox proxy fronts <code>base_url</code>, injects <code>logprobs=true</code>, and writes each
	turn’s <code>(messages, completion_token_ids, per_token_logps)</code> to <code>proxy_trace.jsonl</code>.</p> <!--[2--><h3 class="relative group"><a id="sandbox-backend" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#sandbox-backend"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Sandbox backend</span></h3><!--]--><!----> <p><code>HFSandboxBackend</code> (from <code>opencode_env.sandbox</code>, shared with <code>opencode_env</code>)
	runs the agent in a Hugging Face sandbox. <code>image="python:3.12"</code> cold-installs
	Node 22 (bootstrapped) + the Pi CLI (<code>npm install -g @mariozechner/pi-coding-agent</code>)</p> <ul><li>the proxy’s Python deps on every rollout. For faster rollouts use the
	pre-baked image (Node + Pi + proxy deps already installed), built by CI from <code>hf_image/Dockerfile</code>:</li></ul> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!---->sandbox_backend=HFSandboxBackend(image=<span class="hljs-string">"ghcr.io/huggingface/openenv-pi-sandbox:latest"</span>)<!----></pre></div><!----> <p>Any backend satisfying the <code>SandboxBackend</code> / <code>SandboxHandle</code> / <code>BgJob</code> protocols in <code>opencode_env.sandbox.base</code> can be plugged in the same way.</p> <blockquote><p>The sandbox backend and interception proxy live in <code>opencode_env</code> for now;
	the plan is to consolidate both into <code>openenv.core</code> so <code>pi_env</code> and <code>opencode_env</code> share them without a cross-package import.</p></blockquote> <!--[1--><h2 class="relative group"><a id="deployed-env-http" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#deployed-env-http"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Deployed env (HTTP)</span></h2><!--]--><!----> <p>The deployed Space exposes:</p> <ul><li><strong>Web UI</strong> at <code>/web</code> — pick endpoint, write task, hit Run, watch live phase
	log + reward + logprobs.</li> <li><strong>MCP tool API</strong> at <code>/mcp</code> — programmatic <code>run_rollout</code> calls.</li> <li><strong>OpenAPI docs</strong> at <code>/docs</code>, <strong>health</strong> at <code>/health</code>.</li></ul> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-python "><!----><span class="hljs-keyword">import</span> os
	<span class="hljs-keyword">from</span> pi_env <span class="hljs-keyword">import</span> PiEnv

	<span class="hljs-keyword">with</span> PiEnv(base_url=<span class="hljs-string">"https://<user>-pi-env.hf.space"</span>) <span class="hljs-keyword">as</span> env:
	env.reset()
	result = env.run_rollout(
	endpoint=<span class="hljs-string">"openai"</span>, <span class="hljs-comment"># vllm \| openai \| hf_router</span>
	api_key=os.environ[<span class="hljs-string">"OPENAI_API_KEY"</span>], <span class="hljs-comment"># or set as a Space secret</span>
	instruction=(
	<span class="hljs-string">"Create binary_search.py exposing def binary_search(arr, target) -> int "</span>
	<span class="hljs-string">"that returns the index of target in arr, or -1 if absent."</span>
	),
	setup=[],
	verify=[
	<span class="hljs-string">"test -f /root/workdir/binary_search.py"</span>,
	<span class="hljs-string">"python -c \"import sys; sys.path.insert(0, '/root/workdir'); "</span>
	<span class="hljs-string">"import binary_search; "</span>
	<span class="hljs-string">"assert binary_search.binary_search([1,2,3], 2) == 1; print('OK')\""</span>,
	],
	task_id=<span class="hljs-string">"binary_search_v1"</span>,
	)
	<span class="hljs-built_in">print</span>(<span class="hljs-string">"reward:"</span>, result.reward)
	<span class="hljs-built_in">print</span>(<span class="hljs-string">"turns:"</span>, <span class="hljs-built_in">len</span>(result.proxy_turns))<!----></pre></div><!----> <!--[1--><h2 class="relative group"><a id="the-mcp-tool-runrollout" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#the-mcp-tool-runrollout"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>The MCP Tool: run_rollout</span></h2><!--]--><!----> <p>Single tool, two ways to specify the LLM endpoint:</p> <p><strong>Option A — endpoint shorthand (recommended)</strong>: pass <code>endpoint="vllm"</code> (or <code>"openai"</code> / <code>"hf_router"</code>). The server resolves <code>base_url</code>, <code>api_key</code>, and <code>model</code> from env vars + catalog defaults. Any explicit field overrides.</p> <p><strong>Option B — fully explicit</strong>: pass <code>base_url</code> + <code>api_key</code> + <code>model</code> directly.</p> <table><thead><tr><th>Arg</th><th>Type</th><th>Default</th><th>Notes</th></tr></thead><tbody><tr><td><code>endpoint</code></td><td><code>str</code></td><td><code>""</code></td><td>One of <code>"vllm"</code> / <code>"openai"</code> / <code>"hf_router"</code>.</td></tr><tr><td><code>base_url</code> / <code>api_key</code> / <code>model</code></td><td><code>str</code></td><td><code>""</code></td><td>Override / supply explicitly.</td></tr><tr><td><code>instruction</code></td><td><code>str</code></td><td>required</td><td>Prompt passed to <code>pi</code>.</td></tr><tr><td><code>setup</code></td><td><code>list[str]</code></td><td><code>[]</code></td><td>Bash commands run <strong>before</strong> the agent.</td></tr><tr><td><code>verify</code></td><td><code>list[str]</code></td><td><code>[]</code></td><td>Bash commands run <strong>after</strong> the agent.</td></tr><tr><td><code>task_id</code></td><td><code>str</code></td><td><code>""</code></td><td>Echoed back in result.</td></tr><tr><td><code>mode</code></td><td><code>str</code></td><td><code>"transparent_proxy"</code></td><td>Or <code>"black_box"</code> (no logprobs).</td></tr><tr><td><code>disable_thinking</code></td><td><code>bool \\| None</code></td><td><code>None</code> (catalog default)</td><td>Inject <code>chat_template_kwargs.enable_thinking=false</code>.</td></tr><tr><td><code>max_tokens_cap</code></td><td><code>int</code></td><td><code>4096</code></td><td>Per-turn <code>max_tokens</code> clamp.</td></tr><tr><td><code>top_logprobs</code></td><td><code>int</code></td><td><code>5</code></td><td>HF Router cap is 5; OpenAI 0–20; vLLM unbounded.</td></tr><tr><td><code>agent_timeout_s</code></td><td><code>float</code></td><td><code>600.0</code></td><td>Hard wall budget for one <code>pi</code> run.</td></tr><tr><td><code>image</code></td><td><code>str</code></td><td><code>""</code></td><td>HF sandbox image; blank → <code>python:3.12</code> (cold-installs Node + Pi).</td></tr></tbody></table> <p>Returns <code>RolloutResult</code> JSON with: <code>reward</code>, <code>setup_results[]</code>, <code>verify_results[]</code>, <code>proxy_turns[]</code>, <code>files{}</code>, <code>agent_log_tail</code>, <code>proxy_log_tail</code>, <code>wall_s</code>, <code>agent_exit_code</code>, <code>sandbox_id</code>, <code>error</code>.</p> <!--[1--><h2 class="relative group"><a id="two-operating-modes" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#two-operating-modes"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Two Operating Modes</span></h2><!--]--><!----> <table><thead><tr><th>Mode</th><th>What it does</th><th>Best for</th></tr></thead><tbody><tr><td><strong><code>transparent_proxy</code></strong> (default)</td><td>In-sandbox proxy at <code>localhost:7000</code> forwards Pi’s LLM calls to <code>base_url</code>, injects <code>logprobs=true</code>, captures per-turn <code>(messages, completion_tokens, logprobs)</code> to <code>proxy_trace.jsonl</code>.</td><td>GRPO / RL training, observability, top-k distillation.</td></tr><tr><td><strong><code>black_box</code></strong></td><td>No proxy. Pi talks straight to <code>base_url</code>.</td><td>Smoke tests, eval, SFT data collection.</td></tr></tbody></table> <!--[1--><h2 class="relative group"><a id="building-the-docker-image" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#building-the-docker-image"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Building the Docker Image</span></h2><!--]--><!----> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-bash "><!----><span class="hljs-built_in">cd</span> envs/pi_env

	openenv validate <span class="hljs-comment"># check pyproject.toml + openenv.yaml + server/app.py + uv.lock</span>
	openenv build -t pi-env <span class="hljs-comment"># builds the image (uses server/Dockerfile)</span>

	<span class="hljs-comment"># run locally with an HF token (Sandbox + Jobs access)</span>
	docker run -p 8000:8000 -e HF_TOKEN=hf_... pi-env<!----></pre></div><!----> <p>Or build directly:</p> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class="language-bash "><!---->docker build -t pi-env -f envs/pi_env/server/Dockerfile envs/pi_env<!----></pre></div><!----> <!--[1--><h2 class="relative group"><a id="environment-variables" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#environment-variables"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Environment Variables</span></h2><!--]--><!----> <table><thead><tr><th>Variable</th><th>Required</th><th>Purpose</th></tr></thead><tbody><tr><td><code>HF_TOKEN</code></td><td><strong>yes</strong> for any rollout</td><td>Hugging Face sandbox credentials.</td></tr><tr><td><code>MAX_CONCURRENT_ENVS</code></td><td>no</td><td>Env-instance pool size. Default <code>4</code>.</td></tr><tr><td><code>ENABLE_WEB_INTERFACE</code></td><td>no</td><td>Set <code>false</code> to disable the <code>/web</code> Gradio mount. Default <code>true</code>.</td></tr><tr><td><code>VLLM_URL</code> / <code>VLLM_API_KEY</code> / <code>VLLM_MODEL</code></td><td>for <code>endpoint="vllm"</code></td><td>OAI-compatible base URL (key defaults to <code>intercepted</code>).</td></tr><tr><td><code>OPENAI_API_KEY</code> / <code>OPENAI_BASE_URL</code> / <code>OPENAI_MODEL</code></td><td>for <code>endpoint="openai"</code></td><td>Standard OpenAI.</td></tr><tr><td><code>HF_ROUTER_API_KEY</code> / <code>HF_ROUTER_BASE_URL</code> / <code>HF_ROUTER_MODEL</code></td><td>for <code>endpoint="hf_router"</code></td><td>HF Router.</td></tr></tbody></table> <p>Pick <code>provider:</code> suffixes that actually return logprobs: <strong>Together / Nscale / Scaleway / SambaNova / Cerebras</strong>. Avoid Novita /
	Hyperbolic / Featherless (silent drop) and Groq (HTTP 400).</p> <!--[1--><h2 class="relative group"><a id="project-structure" class="header-link block pr-1.5 text-lg no-hover:hidden with-hover:absolute with-hover:p-1.5 with-hover:opacity-0 with-hover:group-hover:opacity-100 with-hover:right-full" href="#project-structure"><span><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 256"><path d="M167.594 88.393a8.001 8.001 0 0 1 0 11.314l-67.882 67.882a8 8 0 1 1-11.314-11.315l67.882-67.881a8.003 8.003 0 0 1 11.314 0zm-28.287 84.86l-28.284 28.284a40 40 0 0 1-56.567-56.567l28.284-28.284a8 8 0 0 0-11.315-11.315l-28.284 28.284a56 56 0 0 0 79.196 79.197l28.285-28.285a8 8 0 1 0-11.315-11.314zM212.852 43.14a56.002 56.002 0 0 0-79.196 0l-28.284 28.284a8 8 0 1 0 11.314 11.314l28.284-28.284a40 40 0 0 1 56.568 56.567l-28.285 28.285a8 8 0 0 0 11.315 11.314l28.284-28.284a56.065 56.065 0 0 0 0-79.196z" fill="currentColor"></path></svg><!----></span></a> <span>Project Structure</span></h2><!--]--><!----> <div class="code-block relative "><div class="absolute top-2.5 right-4"><button class="inline-flex items-center relative text-sm focus:text-green-500 cursor-pointer focus:outline-none transition duration-200 ease-in-out opacity-0 mx-0.5 text-gray-600 " title="code excerpt" type="button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M28,10V28H10V10H28m0-2H10a2,2,0,0,0-2,2V28a2,2,0,0,0,2,2H28a2,2,0,0,0,2-2V10a2,2,0,0,0-2-2Z" transform="translate(0)"></path><path d="M4,18H2V4A2,2,0,0,1,4,2H18V4H4Z" transform="translate(0)"></path><rect fill="none" width="32" height="32"></rect></svg><!----> <div class=" absolute pointer-events-none transition-opacity bg-black text-white py-1 px-2 leading-tight rounded font-normal shadow left-1/2 top-full transform -translate-x-1/2 translate-y-2 opacity-0 "><div class="absolute bottom-full left-1/2 transform -translate-x-1/2 w-0 h-0 border-black border-4 border-t-0" style="border-left-color: transparent; border-right-color: transparent;"></div> Copied</div><!----></button><!----></div> <pre class=" "><!---->pi_env<span class="hljs-symbol">/</span>
	├── README.md <span class="hljs-comment"># this file</span>
	├── openenv.yaml <span class="hljs-comment"># OpenEnv space spec</span>
	├── pyproject.toml <span class="hljs-comment"># deps + ``server`` entrypoint</span>
	├── __init__.py <span class="hljs-comment"># re-exports primitive + client + models</span>
	│
	├── client.py <span class="hljs-comment"># PiEnv(MCPToolClient)</span>
	├── models.py <span class="hljs-comment"># RolloutResult / RolloutTurn / PiState</span>
	│
	├── config.py <span class="hljs-comment"># PiConfig (primitive)</span>
	├── harness.py <span class="hljs-comment"># PiSession / PiSessionFactory (CLI-only)</span>
	├── pi_runtime.py <span class="hljs-comment"># models.json builder + install/run cmds</span>
	├── task.py <span class="hljs-comment"># PiTask</span>
	│
	└── server<span class="hljs-symbol">/</span>
	├── __init__.py
	├── app.py <span class="hljs-comment"># FastAPI factory; mounts Gradio at /web</span>
	├── pi_environment.py <span class="hljs-comment"># MCPEnvironment with single ``run_rollout`` tool</span>
	├── gradio_ui.py <span class="hljs-comment"># the /web Gradio Blocks UI</span>
	├── catalog.py <span class="hljs-comment"># endpoint shorthand resolver</span>
	└── Dockerfile <span class="hljs-comment"># multi-stage uv build (used by ``openenv build``)</span><!----></pre></div><!----> <p>The sandbox backend + interception proxy are imported from <code>opencode_env.sandbox</code>; <code>pi_env</code> ships no <code>sandbox/</code> of its own.</p> <a class="!text-gray-400 !no-underline text-sm flex items-center not-prose mt-4" href="https://github.com/huggingface/openenv/blob/main/docs/source/environments/pi.md" target="_blank"><svg class="mr-1" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" fill="currentColor" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 32 32"><path d="M31,16l-7,7l-1.41-1.41L28.17,16l-5.58-5.59L24,9l7,7z"></path><path d="M1,16l7-7l1.41,1.41L3.83,16l5.58,5.59L8,23l-7-7z"></path><path d="M12.419,25.484L17.639,6.552l1.932,0.518L14.351,26.002z"></path></svg><!----> <span><span class="underline">Update</span> on GitHub</span></a><!----> <p></p><!--]--><!----><!--]--><!--]--><!--]--> <!--[-1--><!--]--><!--]-->

	<script>
	{
	__sveltekit_fs5wv2 = {
	base: "/docs/openenv/pr_1040/en",
	assets: "/docs/openenv/pr_1040/en"
	};

	const element = document.currentScript.parentElement;

	Promise.all([
	import("/docs/openenv/pr_1040/en/_app/immutable/entry/start.CK4JueSy.js"),
	import("/docs/openenv/pr_1040/en/_app/immutable/entry/app.DS9dQXci.js")
	]).then(([kit, app]) => {
	kit.start(app, element, {
	node_ids: [0, 29],
	data: [null,null],
	form: null,
	error: null
	});
	});
	}
	</script>

Xet Storage Details

Size:: 39.9 kB
Xet hash:: 528f14e8842298b55f116e609a8b90a3bb27b051de0f55316ab9171d8de9363c

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.