Metadata-Version: 2.4
Name: nexus-mm-sdk
Version: 0.2.1
Summary: SDK for NEXUS-MM World Model - Complete Robot Intelligence Platform
Home-page: https://github.com/AfricaAI348/nexus-mm
Author: NEXUS-MM Team
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# NEXUS-MM SDK

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

## Install

```bash
pip install nexus-mm-sdk
```

Quick Start

```python
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

```python
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
