System Architecture

Xyrom OS is organized into five layers: Hardware, Safety Runtime, Agent Runtime, Cloud Control, and Developer Platform.

┌─────────────────────────────────────────────────────┐
│         Developer Platform / SDK / Docs             │
├─────────────────────────────────────────────────────┤
│     Cloud Control Plane / Fleet / Evals / Telemetry │
├─────────────────────────────────────────────────────┤
│  Agent Runtime / Planner / Memory / World Model     │
├─────────────────────────────────────────────────────┤
│  Robot Runtime / Safety / Skills / HAL / State      │
├─────────────────────────────────────────────────────┤
│  OEM Hardware / Sensors / Actuators / Controllers   │
└─────────────────────────────────────────────────────┘

Zone A — Robot Edge (always-on)

Hardware adapter, safety runtime, emergency stop. Runs on robot compute. Real-time safe.

Zone B — Edge Agent

Skill executor, local planner, world model, trace buffer. Operates without cloud connectivity.

Zone C — Cloud

LLM planner, fleet management, telemetry aggregation, operator console. Cloud services.

API Surfaces

Xyrom OS currently exposes multiple API surfaces. The public gateway base URL is https://api.xyromos.com/v0, while fleet and licensing workflows use their own authenticated product APIs.

Python SDK

The official Python SDK for Xyrom OS. Supports Python 3.10+.

Installation

pip install xyrom-os-sdk

Authentication

from xyrom_os_sdk import XyromClient

client = XyromClient(
    api_url="https://api.xyromos.com/v0",
    api_key="xos_your_api_key_here"
)

Portal Task Management

# Fleet/task APIs are exposed through the authenticated fleet portal surface
portal = XyromClient(api_url="https://portal.xyromos.com/api", api_key="your-portal-key")

task = portal.tasks.create(
    org_id="museum-corp",
    robot_id="tron1-001",
    goal={"goal_kind": "patrol_area", "zone": "main-floor"},
    priority="medium"
)

print(task["task_id"])
print(task["task_state"])

Skill Registration

from xyrom_os_sdk.skills import SkillContract, SkillParameter

# Define a skill
skill = SkillContract(
    skill_id="my_custom_skill",
    version="1.0.0",
    description="My custom robot skill",
    parameters=[
        SkillParameter(name="target", type="string", required=True),
        SkillParameter(name="speed", type="float", default=0.5),
    ],
    preconditions=["robot.battery_pct > 20", "robot.status == 'active'"],
    timeout_sec=120
)

# Register it
client.skills.register(skill)

Telemetry Streaming

for event in client.telemetry.stream("tron1-001"):
    print(f"[{event.timestamp}] {event.metric}: {event.value}")

Building OEM Adapters

Adapters (`.aoa` packages) connect robot hardware to Xyrom OS. They implement the Hardware Abstraction Layer (HAL).

Adapter Package Structure

my_robot_adapter/
├── manifest.yaml          # Adapter metadata and capabilities
├── adapter.py             # Main HAL implementation
├── sensors.py             # Sensor bridge
├── actuators.py           # Actuator wrappers
├── safety_hooks.py        # Safety policy hooks
└── tests/
    └── test_adapter.py

manifest.yaml

id: com.example.my-robot
name: My Robot Adapter
version: 1.0.0
platform: my-robot-v2
xyrom_api: ">=0.5.0"
capabilities:
  - navigation
  - manipulation
  - camera
  - lidar
safety_class: B2

adapter.py

from xyrom_os_sdk.hal import BaseAdapter, SensorData, ActuatorCommand

class MyRobotAdapter(BaseAdapter):
    def connect(self, config: dict) -> bool:
        # Initialize hardware connection
        return True

    def get_sensor_data(self) -> SensorData:
        # Read from hardware
        return SensorData(...)

    def send_command(self, cmd: ActuatorCommand) -> bool:
        # Send to hardware
        return True

    def emergency_stop(self) -> bool:
        # Implement E-STOP
        return True

Skill Contracts

Skills are typed behavioral contracts. They define what a robot can do, under what conditions, and with what parameters.

Skill YAML Contract

skill_id: navigate_to
version: 1.0.0
description: Navigate robot to a named location
category: navigation
author: Xyrom OS Core Team

parameters:
  destination:
    type: string
    required: true
    description: Named location from site map
  speed:
    type: float
    default: 0.5
    min: 0.1
    max: 1.0
    description: Navigation speed (m/s)

preconditions:
  - robot.battery_pct > 15
  - robot.status == "active"
  - site.location_exists(params.destination)

outcomes:
  success:
    - robot.location == params.destination
  failure:
    - code: OBSTACLE_BLOCKED
    - code: LOCATION_NOT_FOUND
    - code: LOW_BATTERY

timeout_sec: 120
safety_class: B1
requires_approval: false

Implementing a Skill

from xyrom_os_sdk.skills import SkillExecutor, SkillContext, SkillResult

class NavigateToSkill(SkillExecutor):
    skill_id = "navigate_to"

    async def execute(self, ctx: SkillContext) -> SkillResult:
        dest = ctx.params["destination"]
        speed = ctx.params.get("speed", 0.5)

        ctx.log(f"Navigating to {dest} at speed {speed}")

        # Execute navigation
        result = await ctx.robot.navigate(
            location=dest,
            speed=speed,
            on_progress=ctx.report_progress
        )

        if result.success:
            return SkillResult.success({"arrived_at": dest})
        else:
            return SkillResult.failure(result.error_code)

Tutorials

Community

API Keys

Sandbox Environment

Test your integration against a simulated Xyrom OS environment. No real hardware needed.

My Published Adapters