Metadata-Version: 2.4
Name: echo_world
Version: 0.0.4
Summary: Preview — type a sentence, get a robot solving it in MuJoCo. Backend launching soon.
Project-URL: Homepage, https://echo.dev
Project-URL: Repository, https://github.com/echo-robots/echo_world
Project-URL: Issues, https://github.com/echo-robots/echo_world/issues
Author-email: Echo Robots <gal@echo-robots.com>
License: MIT
Keywords: llm,manipulation,mujoco,robot-learning,robotics,simulation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.0
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# echo_world

> **🚧 PREVIEW RELEASE — backend launching soon.**
> This package reserves the name and previews the API surface.
> The kernel at `api.echo.dev` is not live yet. Follow
> [@EchoRobots](https://x.com/EchoRobots) on X for the launch.

**The thin client for Echo — the kernel for the physical world.**

```bash
pip install echo_world
```

`.echo` is one file format that carries an entire physical world: the
CAD recipe, the kinematics, the materials, the affordances, the
solver state, the trajectories. The Echo kernel reads it back into a
live world that exports cleanly to STL, MJCF, URDF, glTF, USD, OBJ,
STEP. Every consumer projection comes from the same source.

`echo-world` is the thin Python client. The compute lives at
`api.echo.dev`. You don't install MuJoCo, you don't need a GPU, you
don't manage meshes — you author intent, the kernel does the rest.

## Three verbs, one file format

```python
import echo

# 1. CREATE an asset — a thing
beaker = echo.create("a 100mL pyrex beaker")
arm    = echo.create("a 6-DOF servo arm with a parallel gripper")
arm.save("adam_arm.echo")          # ~12 KB

# 2. COMPOSE a world — assets + scene + task
world = echo.compose(
    things  = [beaker, arm],
    layout  = "the arm sits on a wooden table, beaker is to its right",
    task    = "pick up the beaker",
)
world.save("scene.echo")           # ~18 KB

# 3. SOLVE a world — run the task, get a trajectory
result = echo.solve(world)
result.video_url                   # https://echo.dev/v/abc.mp4
result.trajectory.save("run.echo") # replayable; another `.echo` file
```

Or in one line, when the prompt fully describes the scene:

```python
result = echo.solve("Franka picks up a red ball off a wooden table")
print(result.video_url)
```

## What `.echo` carries

| | |
|---|---|
| Geometry | atoms with primitive types (Box, Cylinder, Mesh, Revolve, Sweep, …) and ops (Hole, Hollow, Fillet, …) |
| Kinematics | typed connections — bonds (HINGE, SLIDE, BALL, WELD), edges (curves) |
| Affordances | semantic tags on particles, faces, atoms (GRASP_FACE, PLACEMENT_TILE, HANDLE, …) |
| Materials | direct refs (PLA, ABS, glass, steel) — not free-form strings |
| State | atom poses, joint qpos, sim timestamp |
| Trajectories | replay buffers as state-deltas — million-step episodes in a few MB |

Everything else — meshes, kinematic chains, convex hulls, collision
patches, spatial relations — the kernel re-derives at load time.
That's why a robot manifest is ~10 KB instead of ~100 MB.

## Project to any consumer format

```python
m = echo.load("scene.echo")

m.export.stl()        # → STL bytes (slicer, 3D printer)
m.export.mjcf()       # → MJCF XML (MuJoCo)
m.export.urdf()       # → URDF + sibling meshes (ROS)
m.export.gltf()       # → glTF 2.0 (web, Three.js)
m.export.usd()        # → USD (Isaac Sim, Omniverse)
m.export.obj()        # → OBJ (Blender, Maya)
m.export.step()       # → STEP (CAD tools)
```

Same source, every export. Edit the recipe → every projection updates.

## Query a manifest

```python
arm = echo.load("adam_arm.echo")

arm.atom("j2").pose                          # typed Pose
arm.atom("j2").particles_by_tag("BEARING_SEAT")
arm.bond("j1_to_j2").qpos = 0.5
arm.sync()
arm.atom("j6").world_pose.position           # follows the joint update

arm.particles_by_tag("GRASP_CONTACT")        # all grasp surfaces
arm.affordances()                            # all named affordances
```

No string parsing, no XML grep. Typed attributes on a Pydantic graph.

## Solve from the shell

```bash
echo_world create "a 6-DOF servo arm with parallel gripper" -o arm.echo
echo_world compose --thing arm.echo --task "pick up the beaker"  -o scene.echo
echo_world solve scene.echo

# or one-shot
echo_world solve "Franka picks up a red ball off a wooden table"
#   video : https://echo.dev/v/abc123.mp4
#   .echo : https://echo.dev/m/abc123.echo
```

## Get an API key

Sign up at https://echo.dev — free tier includes daily solves and
unlimited reads.

```bash
export ECHO_API_KEY=ek-...
```

Or pass it explicitly:

```python
echo.Client(api_key="ek-...").solve(...)
```

## Why a hosted backend

The SDK is ~200 lines of HTTP. The kernel is on Echo's servers — that
means the same solver behavior for everyone, no local install of
MuJoCo / Isaac / OCCT, no GPU requirement, and every fix lands for
everyone the same minute. You author intent on your machine; the
kernel runs in ours.

## Status

`v0.0.4` — **preview**. The package reserves the name and shows the
API surface. The backend at `api.echo.dev` is not live yet — calls
will fail with a friendly preview message until the kernel launches.

Follow [@EchoRobots](https://x.com/EchoRobots) on X for the launch
date and the v0.1.0 release.

## License

MIT.