nexus-mm-sdk 0.2.1

SDK for NEXUS-MM World Model - Complete Robot Intelligence Platform

NEXUS-MM SDK

Python SDK for the NEXUS-MM World Model — complete robot intelligence platform with 16 modules and 30+ functions.

Install

pip install nexus-mm-sdk

Quick Start

from nexus_sdk import NexusRobot

robot = NexusRobot()

# Surface risk decision
decision = robot.decide(action="move_forward", surface="ice", speed=0.8)
print(f"Action: {decision.action}, Risk: {decision.risk}")
# Output: Action: stop, Risk: 0.95

Complete Example

from nexus_sdk import NexusRobot

robot = NexusRobot()

# 1. Check if backend is alive
print(robot.health())

# 2. Ask for a safety decision
d = robot.decide("move_forward", "ice", 0.8)
print(f"Decision: {d.action}, Risk: {d.risk}")

# 3. Simulate dropping a glass
r = robot.simulate_physics({"material": "glass", "mass": 0.3}, height=1.5, surface="tile")
print(f"Simulation: {r}")

# 4. Test a material
r = robot.test_material("steel", height=2.0, force=200)
print(f"Material test: {r}")

# 5. Plan a safe route
r = robot.plan_route("entrance", "exit", dangers=["oil_spill", "rubble"])
print(f"Route: {r}")

# 6. Track an object
robot.track_object("box_1", {"x": 0, "y": 0, "z": 1})
r = robot.query_object("box_1")
print(f"Object exists: {r}")

# 7. Predict cause and effect
r = robot.predict_cause("push", {"type": "cup"})
print(f"Cause prediction: {r}")

# 8. Check if robot fits through gap
r = robot.can_fit(gap_width=0.6, gap_height=1.2)
print(f"Can fit: {r}")

# 9. Solve a tool problem
r = robot.solve_tool("reach_high", distance=2.0)
print(f"Tool solution: {r}")

# 10. Predict stack stability
r = robot.predict_stack([
    {"mass": 2, "base_area": 0.04, "height": 0.1},
    {"mass": 1, "base_area": 0.02, "height": 0.1}
])
print(f"Stack stable: {r}")

# 11. Train a robot habit
r = robot.train_habit("home_to_charger", "living_room", "charging_station", repetitions=10)
print(f"Habit trained: {r}")

# 12. Send command to hardware
r = robot.send_command({"action": "motor", "speed": 50, "direction": "forward"})
print(f"Command sent: {r}")

# 13. Train from real outcome
r = robot.train(
    predicted={"simulation_type": "falling_object", "will_break": True},
    actual={"actually_broke": False}
)
print(f"Learning: {r}")

Full API Reference

Core

Function Description robot.decide(action, surface, speed) Robot safety decision robot.health() Backend health check robot.version() API version

Physics

Function Description robot.simulate_physics(object, height, surface) Simulate dropping objects robot.test_friction(surface, weight) Test surface friction robot.test_grip(surface, grip_force) Test grip on surface

Materials

Function Description robot.test_material(material, height, force) Drop + stress test a material robot.discover_material(material) Discover new material properties robot.list_materials() List all known materials

Strategy

Function Description robot.plan_route(start, goal, dangers) Plan optimal route around dangers

Brain

Function Description robot.analyze_scenario(scenario) Full integrated scenario analysis

Memory

Function Description robot.get_memory() Get everything NEXUS has learned robot.get_memory_status() Memory system status

Spatial Tracking

Function Description robot.track_object(object_id, position) Start tracking an object robot.update_object(object_id, position) Update object position robot.mark_occluded(object_id) Mark object as hidden from view robot.query_object(object_id) Check if object still exists robot.can_fit(gap_width, gap_height, angle) Check if robot fits through gap

Causal Engine

Function Description robot.predict_cause(action, target) Predict what happens if you act robot.learn_cause(action, target, predicted, actual) Learn from real outcome

Tool Solver

Function Description robot.solve_tool(goal, distance, height) Find right tool for task

Stability

Function Description robot.predict_stack(objects) Predict if stack will remain stable robot.can_add_to_stack(stack, new_object) Check if item can be added

Automaticity

Function Description robot.set_destination(destination, reason) Set robot's destination robot.train_habit(route, from, to, repetitions) Train a habit to automaticity robot.execute_habit(route) Execute an automatic route robot.set_mode(mode) Switch "conscious" / "automatic" robot.get_automaticity_status() Get all habits and their strength

Hardware

Function Description robot.send_command(command) Send command to Arduino/ESP32

Robot Training

Function Description robot.train(predicted, actual) Learn from real robot outcomes

Supported Surfaces

tile, ice, carpet, concrete, wet_floor, mud, gravel, sand, rubble, debris, oil_spill, snow, grass, rocky, water, ash

Supported Materials

glass, ceramic, steel, rubber, wood, plastic, aluminum, copper, ice, fabric, concrete, carbon_fiber

License

MIT License — NEXUS-MM Team