Crate phytrace_sdk 

PhyTrace SDK for Rust

The PhyTrace SDK provides a comprehensive toolkit for integrating autonomous systems with the PhyWare data platform. It enables robots, autonomous vehicles, and other autonomous systems to capture telemetry data, normalize it to the PhyTrace Unified Data Model (UDM), and stream it to PhyCloud endpoints in real-time.

Features

• UDM Models: Strongly-typed Rust structs for all 23 UDM domains
• Event Builder: Fluent API for constructing UDM events
• Validation: Schema and business rule validation at the source
• Provenance: Cryptographic signing and chain-of-custody tracking
• Transport: HTTP (default), with gRPC/MQTT/WebSocket stubs for future
• Reliability: Edge buffering, retry with backoff, circuit breaker, batching
• Agent: High-level orchestrator for production deployments

Quick Start

use phytrace_sdk::{
    UdmEvent, SourceType, EventType,
    models::domains::{LocationDomain, MotionDomain},
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Build a UDM event using the fluent API
    let event = UdmEvent::new(SourceType::Amr)
        .with_event_type(EventType::TelemetryPeriodic)
        .with_location(LocationDomain {
            latitude: Some(41.8781),
            longitude: Some(-87.6298),
            heading_deg: Some(45.0),
            ..Default::default()
        })
        .with_motion(MotionDomain {
            speed_mps: Some(1.2),
            ..Default::default()
        });

    println!("Event ID: {}", event.event_id);
    Ok(())
}

Feature Flags

• http (default): Enables HTTP transport via reqwest
• grpc: Enables gRPC transport (future)
• mqtt: Enables MQTT transport (future)
• websocket: Enables WebSocket transport (future)

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      PhyTrace SDK (Rust)                        │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │   Models    │  │    Core     │  │  Transport  │              │
│  │  (UDM)      │→ │  (Builder,  │→ │  (HTTP,     │              │
│  │             │  │  Validate)  │  │   Mock)     │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
│         │                │                │                     │
│         └────────────────┼────────────────┘                     │
│                          ↓                                      │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    Reliability                          │    │
│  │  (Buffer, Retry, Circuit Breaker, Batch)                │    │
│  └─────────────────────────────────────────────────────────┘    │
│                          ↓                                      │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                  PhyTraceAgent                          │    │
│  │  (Orchestration, Config, Lifecycle)                     │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Re-exports

pub use agent::PhyTraceAgent;

pub use core::builder::EventBuilder;

pub use core::config::PhyTraceConfig;

pub use core::provenance::ProvenanceSigner;

pub use core::validation::validate_event;

pub use core::validation::ValidationLevel;

pub use core::validation::Validator;

pub use emitters::periodic::PeriodicEmitter;

pub use error::PhyTraceError;

pub use error::PhyTraceResult;

pub use models::enums::EventType;

pub use models::enums::OperationalMode;

pub use models::enums::OperationalState;

pub use models::enums::SafetyState;

pub use models::enums::SourceType;

pub use models::event::Provenance;

pub use models::event::UdmEvent;

pub use reliability::batch::BatchProcessor;

pub use reliability::buffer::FileBuffer;

pub use reliability::retry::RetryHandler;

pub use transport::http::HttpTransport;

pub use transport::mock::MockTransport;

pub use transport::traits::BatchResult;

pub use transport::traits::SendResult;

pub use transport::traits::Transport;

pub use transport::traits::TransportStats;

Modules

agent

PhyTrace Agent - The main SDK entry point.

core

Core SDK components: configuration, building, validation, provenance, license.

emitters

Event emitters for different emission patterns.

error

Error types for the PhyTrace SDK.

models

UDM data models including event envelope, domains, and enums.

reliability

Reliability layer: buffering, retry logic, and batching.

transport

Transport layer for sending events to the PhyWare platform.

Constants

SDK_VERSION

SDK version string

UDM_VERSION

UDM schema version supported by this SDK