Skip to content

Getting Started

This guide will help you verify your first policy with BotManifold in under 5 minutes.

Prerequisites

  • Python 3.10 or higher
  • pip (or uv) package manager
  • A text editor

Step 1: Install the SDK

pip install botmanifold

Step 2: Create Your Policy

Create a file called policy.py:

import numpy as np

def policy(observation: dict) -> np.ndarray:
    """
    Your robot control policy.

    Args:
        observation: Dictionary containing:
            - robot_state: Current robot joint positions/velocities
            - object_positions: XYZ positions of objects in the scene
            - target_positions: Where objects should be placed

    Returns:
        action: 7D numpy array [x, y, z, roll, pitch, yaw, gripper]
            - x, y, z: End-effector velocity (-1 to 1)
            - roll, pitch, yaw: Rotation velocity (-1 to 1)
            - gripper: Gripper command (-1 = close, 1 = open)
    """
    # Get robot position
    robot_pos = observation['robot_state'][:3]

    # Get object positions
    objects = observation['object_positions']

    if len(objects) == 0:
        # No objects, stay still
        return np.zeros(7)

    # Find the nearest object
    distances = [np.linalg.norm(robot_pos - obj) for obj in objects]
    nearest_idx = np.argmin(distances)
    target = objects[nearest_idx]

    # Calculate direction to target
    direction = target - robot_pos
    distance = np.linalg.norm(direction)

    if distance > 0.01:
        direction = direction / distance

    # Create action
    action = np.zeros(7)
    action[:3] = direction * 0.5  # Move toward target
    action[6] = 1.0 if distance > 0.05 else -1.0  # Open gripper if far, close if near

    return action

Step 3: Package Your Policy

Create a zip file containing your policy:

zip policy.zip policy.py

Multiple Files

If your policy uses multiple files or dependencies, include them all in the zip. The entry point must be policy.py with a policy() function.

Step 4: Verify Your Policy (Primary)

from botmanifold import BotManifoldClient

client = BotManifoldClient(api_key="bm_...")

# Verify policy safety
report = client.verify.run("policy.zip", scenario="messy_room")
print(f"Verdict: {report.verdict}")
print(f"Score: {report.score}")

Option B: Web UI

  1. Go to botmanifold.com/arena/submit
  2. Select a scenario (e.g., "Messy Room Challenge")
  3. Drag and drop your policy.zip
  4. Click "Submit Policy"

Option C: REST API

curl -X POST https://api.botmanifold.com/verify \
  -H "Authorization: Bearer $BOTMANIFOLD_API_KEY" \
  -F "policy=@policy.zip" \
  -F "scenario=messy_room"

Step 5: Watch the Results

After submission, your policy enters a queue:

  1. Queued: Waiting for a simulation worker
  2. Running: Simulation in progress
  3. Judging: AI evaluates the result
  4. Completed: Results available

You'll see:

  • Video: Recording of your robot performing the task
  • Verdict: SAFE, UNSAFE, or ERROR
  • Score: Composite safety and performance score
  • Details: Episode-level breakdown with safety and progress scores

Next Steps

Troubleshooting

"Policy function not found"

Ensure your zip file contains policy.py with a function named policy:

def policy(observation: dict) -> np.ndarray:
    ...

"Import error"

Only standard library and numpy are available in ZIP upload mode. If you need other dependencies, include them in your zip file. Alternatively, use botmanifold serve to run a policy server with full dependency access.

"Timeout"

Policies have a time limit per step (typically 100ms). Optimize your code or simplify your approach.

Need help? Check the FAQ or open an issue.