Platform Core

Reference CLI Client

The client module is two things: a command-line reference client for the conversation protocols, and the library of client-side I/O building blocks that the bridge reuses.

The CLI client is the quickest way to hold a real conversation with an engine from a terminal — including audio — which makes it the tool of choice for verifying a protocol change, a new voice or an agent’s behaviour without a mobile or web client in the way.

Building and Running

The module builds an executable fat jar:

./gradlew :promethist-client:shadowJar
java -jar client/build/libs/promethist-client-*-all.jar -k agent:default

Options are -name value pairs; a value may contain spaces (everything up to the next - argument belongs to it).

Options

Option Default Meaning

-k

empty

Pipeline key, e.g. agent:acme-support. See The Pipeline Key.

-u

http://localhost:9010

Engine base URL. For the Socket.IO transport the port is substituted automatically.

-st

io

Transport: io for Socket.IO (port 9011, namespace /socket/io/pipeline) or web for the plain WebSocket (port 9010, /socket/pipeline/{key}).

-m

text

Mode: text (type your turns), asr (local speech recognition) or upstream (stream microphone audio to the engine).

-i

#ready when a key is given

Input sent immediately after the connection opens.

-d

the host’s MAC address

Device identifier; sent as X-Device-Id prefixed with client:. Pass random for a fresh device on every run, which is how to test the first-time-user experience.

-l

en-US

Locale, sent as Accept-Language.

-z

Europe/Prague

Time zone, sent as X-Time-Zone.

-ef

— (server default TEXT)

Element format: TEXT, JSON or MSGPACK, applied to both directions.

-auth

—

Value of the Authorization header, e.g. Bearer <token>.

-isr, -osr

provider defaults

Input and output sample rate in Hz.

-om

raw PCM

Output media type; wav switches the client to the WAV player.

-rp

—

Realtime provider override, sent as X-Realtime-Provider.

-ol

false

Request output logs from the engine (X-Output-Logs).

-du

false

Duplex mode: keep streaming microphone audio even while the agent is speaking, instead of only while listening.

-de

false

Disable the echo prefix, so the output is plain text — useful when piping the client into another program.

Typing exit, quit, bye, end or stop ends the conversation.

Modes

text

Reads lines from standard input and sends each as a turn, appending a sentence separator when missing. The simplest way to exercise an agent’s dialogue.

asr

Captures the microphone and runs speech recognition locally, sending the recognized text as a turn. Recognition only runs while the client is in the listening state, so the agent’s own speech is not transcribed.

upstream

Streams raw microphone audio to the engine and lets the engine recognize it — the mode that matches what a real voice client does, and therefore the one to use when testing recognition, barge-in and latency.

In all modes the agent’s speech items are played back through the audio player, and the client tracks a Sleeping / Listening / Responding state from the incoming commands: an interim transcript resets playback (barge-in), #exit returns to listening.

The echo prefix on each line shows the time and the current state, for example [14:03:21.184/L], and the client reports when an output element arrives more than 250 ms after the engine produced it — a quick way to spot latency problems.

Client I/O Library

These classes are also used by the bridge, so they are part of the module’s contract rather than internal to the CLI.

Class Purpose

OkHttpSocket

Plain WebSocket transport over OkHttp.

SocketIO

Socket.IO transport.

Relay, RelayClient

Client side of the relay protocol, used to reach a device through the relay service — see Modules.

Microphone

Microphone capture in the platform’s audio format.

AudioPlayer, RawAudioPlayer, WavAudioPlayer

Playback of raw PCM and WAV audio, with a reset used for barge-in.

ClientSpeechRecognizer, ClientSpeechHandler

Local speech recognition for asr mode.

Camera, Webcam, NoCamera, Vision

Camera capture abstraction for multimodal input.

ImageViewer

A simple window for displaying images — what the bridge uses for local playback of a test run.

InetInterface

Resolves the host’s network interface, providing the default device identifier.