Metadata-Version: 2.4
Name: utrompulse
Version: 0.2.1
Summary: High-fidelity OpenTelemetry (OTel) bridge for MuJoCo. Industrial-grade observability for agentic robotics.
Requires-Python: >=3.11
Requires-Dist: mcap-protobuf-support>=0.1.0
Requires-Dist: mcap>=1.1.1
Requires-Dist: mujoco>=3.1.0
Requires-Dist: opentelemetry-api>=1.24.0
Requires-Dist: opentelemetry-exporter-otlp>=1.24.0
Requires-Dist: opentelemetry-sdk>=1.24.0
Requires-Dist: pydantic>=2.7.0
Description-Content-Type: text/markdown

# utrompulse (v0.2.0)

A high-performance, asynchronous telemetry framework for MuJoCo simulations. `utrompulse` decouples physics computation from observability I/O, providing semantically labeled telemetry via OpenTelemetry (OTLP) and local binary logging (MCAP).

## Key Features

* **Zero-Blocking Architecture:** High-frequency state extraction (<50μs) to preserve physics determinism.
* **Semantic Instrumentation:** Automatically maps raw `mjData` indices to human-readable XML joint and actuator names.
* **Multiplexed Transports:** Simultaneously stream to live OTLP backends (Jaeger) and local disk (MCAP/Foxglove).
* **Real-Time Safety:** Implements a Head-Dropping Circular Buffer to ensure telemetry freshness without memory overflows.

## Architecture

`utrompulse` utilizes an air-gapped dispatcher model to isolate the simulation thread:

1.  **ModelInstrument:** Inspects the `mjModel` at runtime to create a semantic name-to-index map.
2.  **ZeroBlockingHook:** Captures state snapshots and pushes them into a thread-safe circular queue.
3.  **PulseExporter:** A background daemon that broadcasts snapshots to all registered `BaseTransport` backends.

## Installation

Ensure you have Python 3.11+ and `uv` installed.

```bash
git clone [https://github.com/mustafa-5493/UtromPulse.git](https://github.com/mustafa-5493/UtromPulse.git)
cd UtromPulse
uv sync
```

## Usage

Modern usage involving semantic mapping and multiple transport outputs:

```python
import mujoco
from utrompulse.bridge.mujoco_hook import ZeroBlockingHook
from utrompulse.bridge.instrumentation import ModelInstrument
from utrompulse.telemetry.otel_exporter import PulseExporter
from utrompulse.transports.otlp import OTLPTransport
from utrompulse.transports.mcap import MCAPTransport

# 1. Load Model
model = mujoco.MjModel.from_xml_path("robot.xml")
data = mujoco.MjData(model)

# 2. Initialize Instrumentation & Hook
instrument = ModelInstrument(model)
hook = ZeroBlockingHook(max_queue_size=5000)

# 3. Configure Transports (Live + Local)
transports = [
    OTLPTransport(endpoint="http://localhost:4317"),
    MCAPTransport(output_path="recording.mcap")
]

# 4. Start Exporter
exporter = PulseExporter(telemetry_queue=hook.telemetry_queue, transports=transports)
exporter.start()

try:
    while True:
        mujoco.mj_step(model, data)
        # Capture state with semantic labels
        hook.capture_state(step=data.time, data=data, instrument=instrument)
finally:
    exporter.stop()
```

## Observability Backends

### Live Tracing (Jaeger)
Run Jaeger with OTLP support:
```bash
docker run -d --name jaeger -p 16686:16686 -p 4317:4317 jaegertracing/all-in-one:latest
```
Access the UI at `http://localhost:16686` to view semantically labeled spans (e.g., `joint.left_hip_pitch`).

### Offline Analysis (Foxglove)
The `MCAPTransport` generates a `.mcap` file. Drag and drop this file into [Foxglove Studio](https://foxglove.dev/) to visualize high-frequency joint data, control signals, and system jitter offline.