xybrid run

Execute a hybrid pipeline on the current device.

Usage

xybrid run --config <path>
xybrid run --pipeline <name>
xybrid run --pipeline <name> --dry-run

Options

Option	Short	Description
`--config`	`-c`	Load a pipeline YAML file directly
`--pipeline`	`-p`	Look up `<name>.yml` under `examples/`
`--bundle`	`-b`	Run a `.xyb` bundle file directly
`--input-text`		Text input for text-based models (LLM, TTS)
`--input-audio`		Path to an audio file for audio-based models (ASR) — WAV, MP3, OGG, or FLAC
`--target`		Force model format (`onnx`, `coreml`, `tflite`); auto-detected if omitted
`--dry-run`		Simulate routing without execution
`--policy`		Load an additional policy bundle
`--trace`		Enable execution tracing with flame graph + LLM metrics output
`--trace-export`		Export the trace to a JSON file (Chrome trace format)

Behavior

Parses YAML into PipelineConfig
Runs policy → routing → execution loop
Prints stage latency and routing summaries

In dry-run mode, the CLI prints routing decisions and simulated outputs without invoking adapters.

Examples

Run from config file

xybrid run --config ./pipelines/voice-assistant.yaml

Run named pipeline

xybrid run --pipeline hiiipe

Looks for hiiipe.yml or hiiipe.yaml in:

xybrid-cli/examples/
./examples/

Dry run (simulate only)

xybrid run --pipeline hiiipe --dry-run

Output shows routing decisions without actual execution:

▶️ Stage: whisper-tiny@1.2 → would route to: local
▶️ Stage: gpt-4o-mini → would route to: integration
▶️ Stage: kokoro-82m@0.1 → would route to: local

With custom policy

xybrid run --pipeline hiiipe --policy ./policies/strict-privacy.yaml

Sample Output

▶️ Stage: whisper-tiny@1.2 → local
🎯 Routing: local (fast path)
⚙️ Execution complete (52ms)

▶️ Stage: gpt-4o-mini → integration
🎯 Routing: integration (OpenAI)
⚙️ Execution complete (340ms)

▶️ Stage: kokoro-82m@0.1 → local
🎯 Routing: local (fast path)
⚙️ Execution complete (89ms)

🎉 Pipeline complete (total 481ms)

Pipeline Format

The run command expects YAML pipelines:

name: "voice-assistant"
stages:
  - whisper-tiny@1.0
  - target: integration
    provider: openai
    model: gpt-4o-mini
  - kokoro-82m@0.1

Tracing LLM Inference

When --trace is passed and the pipeline includes an LLM stage, the CLI prints an additional metrics block after the output:

📊 LLM Trace:
------------------------------------------------------------
  TTFT                  : 412 ms
  Decode TPS            : 42.80 tok/s
  Prefill TPS           : 184.20 tok/s
  Wallclock TPS         : 38.10 tok/s
  Mean ITL              : 14.30 ms
  p95 ITL               : 28 ms
  Emitted chunks        : 64
  Tokens generated      : 64
  Finish reason         : stop
------------------------------------------------------------

These values are read from the output envelope's metadata, populated by the LLM adapter's streaming path. Non-LLM stages (ASR, TTS, embedding) do not emit these fields and the block is skipped.

xybrid run

On this page