Upload folder using huggingface_hub

README.md

@@ -18,6 +18,15 @@ short_description: OpenCode coding agent in an E2B sandbox with logprob capture
 an isolated [E2B](https://e2b.dev) sandbox against any OpenAI-compatible
 LLM endpoint, optionally capturing per-token logprobs for GRPO training.
 
+**🚀 Try it live**: [`AdithyaSK/opencode-env`](https://huggingface.co/spaces/AdithyaSK/opencode-env)
+
+The deployed Space exposes:
+
+- **Web UI** at [`/web`](https://adithyask-opencode-env.hf.space/web) — pick endpoint, write task, hit Run, watch live phase log + reward + logprobs.
+- **MCP tool API** at [`/mcp`](https://adithyask-opencode-env.hf.space/mcp) — programmatic `run_rollout` calls.
+- **OpenAPI docs** at [`/docs`](https://adithyask-opencode-env.hf.space/docs).
+- **Health** at [`/health`](https://adithyask-opencode-env.hf.space/health).
+
 The env is **task-agnostic** — every rollout is configured at call-time
 with a uniform Task shape:
 
@@ -33,41 +42,81 @@ a float to `/home/user/logs/verifier/reward.txt` (override).
 
 ## Quick Start
 
-### As a deployed env (HTTP / MCP)
+### Async (default — talk to the deployed Space)
+
+```python
+import asyncio
+import os
+from opencode_env import OpenCodeEnv
+from opencode_env.client import _extract_text
+from opencode_env.models import RolloutResult
+
+
+async def main():
+    SPACE = "https://adithyask-opencode-env.hf.space"
+
+    async with OpenCodeEnv(base_url=SPACE) as env:
+        await env.reset()
+
+        # The MCP tool returns JSON; deserialize via the typed model.
+        raw = await env.call_tool(
+            "run_rollout",
+            endpoint="openai",                          # vllm | openai | hf_router
+            api_key=os.environ["OPENAI_API_KEY"],       # or set as a Space secret
+            instruction=(
+                "Create binary_search.py exposing def binary_search(arr, target) -> int "
+                "that returns the index of target in arr, or -1 if absent. Use a "
+                "relative path."
+            ),
+            setup=[],
+            verify=[
+                "test -f /home/user/workdir/binary_search.py",
+                "python -c \"import sys; sys.path.insert(0, '/home/user/workdir'); "
+                "import binary_search; "
+                "assert binary_search.binary_search([1,2,3], 2) == 1; print('OK')\"",
+            ],
+            template="opencode-rl",                     # prebaked E2B template
+            task_id="binary_search_v1",
+        )
+        result = RolloutResult.model_validate_json(_extract_text(raw))
+
+        print("reward:", result.reward)
+        print("turns:", len(result.proxy_turns))
+        print("files:", list(result.files.keys()))
+        print("wall:", result.wall_s, "s")
+
+
+asyncio.run(main())
+```
+
+Expected output (~20s with the prebaked template):
+
+```
+reward: 1.0
+turns: 3
+files: ['/home/user/workdir/binary_search.py', ...]
+wall: 19.8 s
+```
+
+### Sync wrapper
 
 ```python
 import os
 from opencode_env import OpenCodeEnv
 
-with OpenCodeEnv(base_url="http://localhost:8000") as env:
+# .sync() returns a synchronous wrapper around the async client.
+with OpenCodeEnv(base_url="https://adithyask-opencode-env.hf.space").sync() as env:
     env.reset()
-    result = env.run_rollout(
-        endpoint="openai",                      # shorthand → server resolves
-        instruction=(
-            "Create binary_search.py exposing def binary_search(arr, target) -> int "
-            "that returns the index of target in arr, or -1 if absent. Use a "
-            "relative path."
-        ),
-        setup=[],
-        verify=[
-            "test -f /home/user/workdir/binary_search.py",
-            "python -c \"import sys; sys.path.insert(0, '/home/user/workdir'); "
-            "import binary_search; "
-            "assert binary_search.binary_search([1,2,3], 2) == 1\"",
-        ],
-        task_id="binary_search_v1",
-        template="opencode-rl",                 # prebaked E2B template
-    )
-    print("reward:", result.reward)
-    print("turns:", len(result.proxy_turns))
-    print("files:", list(result.files.keys()))
+    # MCP tools are reachable via env.call_tool(...) / env.step(...) sync-wrapped.
+    # See the async example above for the full run_rollout signature.
 ```
 
-The Space-deployed variant works the same — point `base_url` at
-`https://<user>-opencode-env.hf.space` and set the relevant secrets in
-the Space settings.
+Point `base_url` at `http://localhost:8000` to talk to a local container
+instead of the public Space.
+
+### In-process primitive (no HTTP)
 
-### As an in-process primitive
+For trainers that want to drive a sandbox directly without an HTTP boundary:
 
 ```python
 import os
@@ -83,7 +132,7 @@ factory = OpenCodeSessionFactory(
         model="gpt-4o-mini",
     ),
     sandbox_backend=E2BSandboxBackend(),
-    mode="transparent_proxy",                   # or "black_box"
+    mode="transparent_proxy",                   # captures per-token logprobs
 )
 session = factory.create(task=OpenCodeTask(instruction="..."))
 session.wait_for_completion()