Skip to content

Python SDK Quickstart

Get up and running with PhyTrace in 5 minutes.

Installation

pip install phytrace-sdk

Step 1: Create Agent Configuration

Create a phytrace-agent.yaml file:

agent:
  id: "agent-my-robot-001"

source:
  id: "robot-001"
  type: "amr"
  fleet_id: "warehouse-fleet"
  site_id: "site-nyc-01"
  organization_id: "org-acme-corp"

transport:
  primary:
    type: "http"
    endpoint: "https://api.phycloud.io/v1/events"
    api_key_env: "PHYCLOUD_API_KEY"

telemetry:
  periodic:
    interval_ms: 100   # 10 Hz
    domains:
      - location
      - motion
      - power
      - operational

reliability:
  buffer:
    enabled: true
    path: "/tmp/phytrace-buffer"
    max_size_mb: 512
  retry:
    max_retries: 5
    backoff_base_ms: 100

Step 2: Set Your API Key

export PHYCLOUD_API_KEY="your-api-key-here"

Step 3: Run the Agent

Option A: Using the Agent class

import asyncio
from phytrace import PhyTraceAgent

async def main():
    agent = PhyTraceAgent.from_config("phytrace-agent.yaml")
    await agent.start()

    # Agent runs, collecting and streaming telemetry...
    # Stop when done:
    await agent.stop()

asyncio.run(main())

Option B: Manual event building

import asyncio
from phytrace import UDMEventBuilder, EventType, SourceType

async def main():
    event = (
        UDMEventBuilder(source_id="robot-001", source_type=SourceType.AMR)
        .with_event_type(EventType.TELEMETRY_PERIODIC)
        .with_location(latitude=41.8781, longitude=-87.6298, heading_deg=45.0)
        .with_motion(speed_mps=1.2, angular_velocity_yaw_dps=5.5)
        .with_power(battery_soc_pct=78.5, is_charging=False)
        .with_operational(mode="autonomous", task_id="task-001")
        .build()
    )

    print(event.model_dump_json(indent=2))

asyncio.run(main())

Step 4: Test with Mock Transport

from phytrace.transport.mock import MockTransport

transport = MockTransport()
agent = PhyTraceAgent(transport=transport)
await agent.emit(event)

# Verify
assert len(transport.sent_events) == 1

Next Steps