Metadata-Version: 2.4
Name: tau-sim
Version: 0.1.4
Summary: Tau-Sim — an LLM-assisted IDE for MuJoCo robotic simulation
Author: Tau Intelligence
License: Apache-2.0
Project-URL: Homepage, https://github.com/tau-intelligence/tau-sim
Project-URL: Source, https://github.com/tau-intelligence/tau-sim
Project-URL: Issues, https://github.com/tau-intelligence/tau-sim/issues
Keywords: mujoco,robotics,simulation,llm,reinforcement-learning,ide
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Environment :: Web Environment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.111
Requires-Dist: uvicorn[standard]>=0.30
Requires-Dist: pydantic>=2.7
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: mujoco>=3.2
Requires-Dist: numpy>=1.26
Requires-Dist: pillow>=10.3
Requires-Dist: openai>=1.40
Requires-Dist: google-generativeai>=0.7
Provides-Extra: train
Requires-Dist: stable-baselines3>=2.3; extra == "train"
Requires-Dist: gymnasium>=0.29; extra == "train"
Requires-Dist: torch>=2.2; extra == "train"

# tau-sim

LLM-assisted MuJoCo simulation IDE — runs in your browser, locally on
your laptop, or as a hosted demo. Edit MJCF / Python on the left, watch
episodes render live in the center, and ask any model (OpenRouter /
OpenAI / Gemini) to propose changes that appear as reviewable diffs.

Built by [Tau Intelligence](https://tau-intelligence.com/).

## Try it

### One command, anywhere with Python ≥ 3.10

```bash
uvx tau-sim     # or: pipx run tau-sim
```

That installs everything (FastAPI, MuJoCo, OSMesa-friendly bindings) in
an isolated environment and opens [http://127.0.0.1:7860](http://127.0.0.1:7860)
in your browser. Project files are stored under `~/.tau/projects/`.

If you've already got `uv`, you can also do:

```bash
uv tool install tau-sim
tau --help
```

### From source

```bash
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env       # (optional) configure default LLM provider
tau
```

### Frontend dev server

```bash
cd frontend
npm install
npm run dev      # http://localhost:5173 (proxies /api and /ws to :8000)
```

When developing the frontend separately, run the backend via
`uvicorn app.main:app --reload --port 8000` so the Vite proxy targets
the right port.

## Architecture

```
┌──────────────────────────┐         ┌──────────────────────────────┐
│ React + Vite + Monaco    │  HTTP   │ FastAPI                      │
│  - Editor (MJCF / Py)    │ ──────▶ │  /api/projects   (CRUD)      │
│  - Viewer (frames)       │         │  /api/chat       (LLM diff)  │
│  - Chat + Diff review    │ ◀────── │  /ws/sim/{id}    (frames)    │
│  - BYOK settings         │   WS    └──────────────┬───────────────┘
└──────────────────────────┘                        │
                                          ┌─────────▼────────┐
                                          │ subprocess sand- │
                                          │ box (cloud only) │
                                          └─────────┬────────┘
                                                    │
                                            ┌───────▼────────┐
                                            │ MuJoCo runner  │
                                            │ (offscreen GL) │
                                            └────────────────┘
```

## Deploy as a single container

The repo ships a multi-stage [`Dockerfile`](Dockerfile) that builds the
React app, installs MuJoCo + OSMesa, and serves the SPA + API + WS from
one FastAPI process on `$PORT` (default `7860`).

```bash
docker build -t tau-sim .
docker run --rm -p 7860:7860 tau-sim
# open http://localhost:7860
```

The container defaults to multi-tenant mode: each visitor gets a cookie
session, projects are stored under `/tmp/projects_data/<session>/`, and
user env code runs inside a subprocess sandbox with CPU + wall-clock
limits. For local single-user runs (your laptop), the `tau` CLI sets
`TAU_SINGLE_USER=1` automatically and disables the sandbox for speed.

### Hugging Face Spaces (free)

1. Create a new Space → SDK **Docker**.
2. Push this repo. Rename [`SPACE_README.md`](SPACE_README.md) to
   `README.md` at the Space root (or merge its YAML header into the
   existing README before pushing).
3. The Space builds the Docker image and exposes the app on its
   `*.hf.space` URL.

No API keys are baked into the image — users add their own via the
in-app Settings panel (stored only in their browser).

## Configuration (env vars)

| Variable | Default | Effect |
|---|---|---|
| `PROJECTS_DIR` | `~/.tau/projects` (CLI) / `/tmp/projects_data` (Docker) | Where project files live. |
| `MUJOCO_GL` | `egl` (CLI) / `osmesa` (Docker) | MuJoCo offscreen renderer. |
| `TAU_SINGLE_USER` | `0` (Docker) / `1` (CLI) | Disable cookie-based isolation. |
| `TAU_SANDBOX` | `0` (CLI) / `1` (Docker) | Run user env in subprocess with rlimits. |
| `TAU_CPU_LIMIT` | `60` | CPU seconds per episode (sandbox only). |
| `TAU_WALL_LIMIT` | `120` | Wall-clock seconds per episode (sandbox only). |
| `TAU_MEM_LIMIT_MB` | unset | Optional `RLIMIT_AS` cap. Don't set unless you've tested with numpy/MuJoCo. |
| `OPENROUTER_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` | unset | Optional server-side defaults; per-user BYOK overrides take precedence. |
| `GITHUB_TOKEN` | unset | Lifts menagerie-importer rate limit from 60/hr to 5000/hr. |

## Security note

`env.py` is executed by the backend whenever you press **Run**. The
default Docker deployment runs it in a subprocess with rlimits — that
protects CPU / disk / wall-clock but **not arbitrary syscalls or
network**. For real public exposure also run the container with
`--memory`, `--pids-limit`, and a no-egress network policy.

LLM-proposed diffs are never auto-applied; the user must click Apply.
