Class Tryll::Client::TryllClient¶

ClassList > Tryll > Client > TryllClient

TCP session to the Tryll server. More...

#include <TryllClient.h>

Classes¶

Type	Name
struct	DebugCommandResult
struct	EmbeddedStorageInfo Result returned by `CreateEmbeddedStringStorage` variants.
struct	SessionConfig Per-model-kind session configuration.

Public Functions¶

Type	Name
AgentProxy	CreateAgent (const GraphDescription & graph, bool enableDiagnostics=false, std::optional< std::chrono::milliseconds > timeout=std::nullopt, bool maintainDialogueHistory=true, std::vector< AgentVariableDecl > variables={}) Blocking convenience wrapper over CreateAgentAsync .
AgentProxy	CreateAgent (const GraphDescription & graph, AgentCreateOptions options, std::optional< std::chrono::milliseconds > timeout=std::nullopt) Blocking CreateAgent overload using named options.
std::future< AgentProxy >	CreateAgentAsync (const GraphDescription & graph, bool enableDiagnostics=false, bool maintainDialogueHistory=true, std::vector< AgentVariableDecl > variables={}) Asynchronously create an agent with the given graph description.
std::future< AgentProxy >	CreateAgentAsync (const GraphDescription & graph, AgentCreateOptions options) Asynchronous CreateAgent overload using named options.
EmbeddedStorageInfo	CreateEmbeddedStringStorage (std::string_view name, std::string_view configPath, std::string_view embeddingModel={}, std::optional< std::chrono::milliseconds > timeout=std::nullopt) Create an `EmbeddedStringStorage` from a server-side config.
EmbeddedStorageInfo	CreateEmbeddedStringStorageFromStrings (std::string_view name, const std::vector< std::string > & strings, std::string_view embeddingModel, std::optional< std::chrono::milliseconds > timeout=std::nullopt) Create an `EmbeddedStringStorage` from inline strings.
void	CreateSession (const SessionConfig & cfg) Create the logical session for this connection (mandatory, one-shot).
void	CreateStringStorage (std::string_view name, const std::vector< std::string > & strings, std::chrono::milliseconds timeout=std::chrono::seconds{10}) Create a named `StringStorage` on the server from an inline list.
void	CreateStringStorageFromFile (std::string_view name, std::string_view filePath, ::Tryll::StringStorageKind kind=::Tryll::StringStorageKind_List, std::chrono::milliseconds timeout=std::chrono::seconds{10}) Create a named `StringStorage` on the server from a server-side file.
void	CreateStringStorageKeyed (std::string_view name, const std::vector< std::string > & keys, const std::vector< std::string > & values, ::Tryll::StringStorageKind kind=::Tryll::StringStorageKind_Map, std::chrono::milliseconds timeout=std::chrono::seconds{10}) Create a named `StringStorage` on the server from inline key/value pairs.
VoiceInput	CreateVoiceInput (VoiceInputConfig cfg, std::chrono::milliseconds timeout=std::chrono::seconds{30}) Blocking convenience wrapper over CreateVoiceInputAsync .
std::future< VoiceInput >	CreateVoiceInputAsync (VoiceInputConfig cfg) Asynchronously create a VoiceInput handle backed by the named STT model.
void	DestroyEmbeddedStringStorage (std::string_view name, std::chrono::milliseconds timeout=std::chrono::seconds{10}) Destroy a named `EmbeddedStringStorage` .
void	DestroyStringStorage (std::string_view name, std::chrono::milliseconds timeout=std::chrono::seconds{10}) Destroy a named `StringStorage` on the server.
void	DownloadModel (std::string_view modelName, DownloadProgressCallback onProgress=nullptr, std::chrono::milliseconds timeout=std::chrono::minutes{30}) Start downloading a model on the server and block until complete.
std::string	GetServerBuildConfig () const Server build configuration ("Debug" \| "Release" \| "Production"), from `ConnectionReady` .
std::string	GetServerExePath () const Canonical path of the server executable, advertised in `ConnectionReady` .
std::uint32_t	GetServerIdleTimeoutSeconds () noexcept const Server idle-shutdown grace period in seconds (0 when standalone), from `ConnectionReady` .
std::string	GetServerRunId () const Per-process server run id (UUID), from `ConnectionReady` .
std::string	GetServerVersion () const Server version string ( `Tryll::kVersion` ), from`ConnectionReady` .
std::uint64_t	GetSessionId () noexcept const Server-assigned session identifier.
bool	IsServerManaged () noexcept const True when the server runs in managed (idle-self-exit) mode, from `ConnectionReady` .
std::vector<::Tryll::ModelInfoT >	ListModels (std::chrono::milliseconds timeout=std::chrono::seconds{10}) Request the list of models known to the server for the session's engine.
void	LoadModel (std::string_view modelName, std::chrono::milliseconds timeout=std::chrono::minutes{5}) Explicitly load and pin a model into memory.
DebugCommandResult	SendDebugCommand (std::string_view command, std::string_view payload={}, std::chrono::milliseconds timeout=std::chrono::seconds{5}) Send a dev-only debug command to the server and report the outcome.
void	SetInferenceThrottle (float level) Report how hard the server should yield the GPU back to the game (the manual inference throttle knob).
void	Shutdown (std::chrono::milliseconds timeout=std::chrono::seconds{30}) Blocking convenience wrapper over ShutdownAsync .
std::future< void >	ShutdownAsync () Asynchronously shut down the connection.
	TryllClient (const TryllClient &) = default
	TryllClient (TryllClient &&) noexcept
void	UnloadModel (std::string_view modelName, std::chrono::milliseconds timeout=std::chrono::seconds{30}) Unpin a previously pinned model.
TryllClient &	operator= (const TryllClient &) = default
TryllClient &	operator= (TryllClient &&) noexcept
	~TryllClient ()

Public Static Functions¶

Type	Name
TryllClient	Connect (std::string_view host, std::uint16_t port, std::chrono::milliseconds timeout=std::chrono::seconds{30}) Blocking convenience wrapper over ConnectAsync .
std::future< TryllClient >	ConnectAsync (std::string_view host, std::uint16_t port) Asynchronously connect and wait for `ConnectionReady` .
ConnectedSession	RunAndConnect (ManagedServerOptions serverOpts, std::chrono::milliseconds connectTimeout=std::chrono::seconds{30}) Spawn a local server and connect to it — recommended for single-process deployments where the client owns the server lifecycle.
std::future< ConnectedSession >	RunAndConnectAsync (Client::ManagedServerOptions serverOpts) Asynchronous variant of RunAndConnect .

Detailed Description¶

Copyable — all copies share the same underlying connection via shared_ptr. The connection stays open until the last copy goes out of scope or Shutdown is called.

Public Functions Documentation¶

function CreateAgent [1/2]¶

Blocking convenience wrapper over CreateAgentAsync .

AgentProxy Tryll::Client::TryllClient::CreateAgent (
    const GraphDescription & graph,
    bool enableDiagnostics=false,
    std::optional< std::chrono::milliseconds > timeout=std::nullopt,
    bool maintainDialogueHistory=true,
    std::vector< AgentVariableDecl > variables={}
)

Parameters:

graph Fully-built graph description.
enableDiagnostics When true, the server serialises per-node execution data into TurnComplete.debug_info for every turn. Off by default; enable for QA/eval pipelines.
timeout Maximum time to wait for CreateAgentResponse. Defaults to 30 seconds.
maintainDialogueHistory When true (default), the agent keeps its full dialogue history. When false, the history is discarded after each turn — a stateless agent, useful for technical/classification agents that should not store or project prior turns.
variables The agent's complete variable declaration. See CreateAgentAsync. Empty by default.

Returns:

AgentProxy bound to the new server-side agent.

Exception:

TryllError On validation failures, server-reported errors (e.g. GraphCompilationFailed when the graph references a model that has not been acquired), or timeout.

function CreateAgent [2/2]¶

Blocking CreateAgent overload using named options.

AgentProxy Tryll::Client::TryllClient::CreateAgent (
    const GraphDescription & graph,
    AgentCreateOptions options,
    std::optional< std::chrono::milliseconds > timeout=std::nullopt
)

function CreateAgentAsync [1/2]¶

Asynchronously create an agent with the given graph description.

std::future< AgentProxy > Tryll::Client::TryllClient::CreateAgentAsync (
    const GraphDescription & graph,
    bool enableDiagnostics=false,
    bool maintainDialogueHistory=true,
    std::vector< AgentVariableDecl > variables={}
)

Parameters:

graph Fully-built graph description.
enableDiagnostics When true, the server serialises per-node execution data into TurnComplete.debug_info for every turn. Off by default for zero overhead in production; enable for QA/eval pipelines.
maintainDialogueHistory See CreateAgent.
variables The agent's complete variable declaration — every variable it will ever have, with its initial value (the value's active alternative fixes the type for the agent's lifetime). Post-create writes to an undeclared name are rejected locally by AgentProxy::Variables without a wire round-trip. Empty by default.

Note:

The returned future completes when creation succeeds or fails definitively. A graph that references a model not yet acquired (see DownloadModel) fails fast with GraphCompilationFailed.

Returns:

Future yielding an AgentProxy bound to the new agent. Calling future::get() propagates any TryllError raised during validation or creation.

function CreateAgentAsync [2/2]¶

Asynchronous CreateAgent overload using named options.

std::future< AgentProxy > Tryll::Client::TryllClient::CreateAgentAsync (
    const GraphDescription & graph,
    AgentCreateOptions options
)

function CreateEmbeddedStringStorage¶

Create an EmbeddedStringStorage from a server-side config.

EmbeddedStorageInfo Tryll::Client::TryllClient::CreateEmbeddedStringStorage (
    std::string_view name,
    std::string_view configPath,
    std::string_view embeddingModel={},
    std::optional< std::chrono::milliseconds > timeout=std::nullopt
)

Path A: the server loads records and (optionally) an on-disk HNSW index described by a *.json config referencing a *.kb.json records file.

Parameters:

name Session-unique storage name.
configPath Server-side *.json path.
embeddingModel Optional catalog embedding-model name for cross-check; when non-empty must match the config's embedding_model.
timeout Maximum time to wait for the response; embedding large corpora is slow.

Returns:

EmbeddedStorageInfo with name, record count, and dimension.

Exception:

TryllError On server-reported errors (including InvalidStringStorageData when embeddingModel mismatches the config) or timeout.

function CreateEmbeddedStringStorageFromStrings¶

Create an EmbeddedStringStorage from inline strings.

EmbeddedStorageInfo Tryll::Client::TryllClient::CreateEmbeddedStringStorageFromStrings (
    std::string_view name,
    const std::vector< std::string > & strings,
    std::string_view embeddingModel,
    std::optional< std::chrono::milliseconds > timeout=std::nullopt
)

Path B: the server embeds strings in memory with the named embedding model; no on-disk index is written.

Parameters:

name Session-unique storage name.
strings Inline records to embed.
embeddingModel Catalog embedding-model name (required).
timeout Maximum time to wait; embedding is slow.

Returns:

EmbeddedStorageInfo with name, record count, and dimension.

Exception:

TryllError On server-reported errors or timeout.

function CreateSession¶

Create the logical session for this connection (mandatory, one-shot).

void Tryll::Client::TryllClient::CreateSession (
    const SessionConfig & cfg
)

Must be called exactly once after Connect and before CreateAgent or any model-management/storage/voice call — those are rejected with SessionNotReady until the session exists. A second call is rejected by the server with SessionAlreadyExists. On success the server-allocated session id becomes available via GetSessionId.

Exception:

TryllError On server-reported errors or timeout.

function CreateStringStorage¶

Create a named StringStorage on the server from an inline list.

void Tryll::Client::TryllClient::CreateStringStorage (
    std::string_view name,
    const std::vector< std::string > & strings,
    std::chrono::milliseconds timeout=std::chrono::seconds{10}
)

The storage may then be referenced by name in node params via string_storage (e.g. on CannedResponseNode or RegexGuardrailNode). Must be called before CreateAgent on any graph that references this storage name.

Parameters:

name Session-unique storage name.
strings Inline list of strings to store.
timeout Maximum time to wait for the response.

Exception:

TryllError On server-reported errors or timeout.

function CreateStringStorageFromFile¶

Create a named StringStorage on the server from a server-side file.

void Tryll::Client::TryllClient::CreateStringStorageFromFile (
    std::string_view name,
    std::string_view filePath,
    ::Tryll::StringStorageKind kind=::Tryll::StringStorageKind_List,
    std::chrono::milliseconds timeout=std::chrono::seconds{10}
)

When kind is List (default), filePath must point to a newline-delimited *.txt file. When kind is Map or Multimap, filePath must point to a *.json array of {id, text} objects (where id is the key and text is the value).

Parameters:

name Session-unique storage name.
filePath Server-side path to the source file.
kind Storage kind; defaults to List.
timeout Maximum time to wait for the response.

Exception:

TryllError On server-reported errors, missing file, or timeout.

function CreateStringStorageKeyed¶

Create a named StringStorage on the server from inline key/value pairs.

void Tryll::Client::TryllClient::CreateStringStorageKeyed (
    std::string_view name,
    const std::vector< std::string > & keys,
    const std::vector< std::string > & values,
    ::Tryll::StringStorageKind kind=::Tryll::StringStorageKind_Map,
    std::chrono::milliseconds timeout=std::chrono::seconds{10}
)

kind must be Map or Multimap. For Map, all keys must be unique. For Multimap, duplicate keys are allowed. Both keys and values must be non-empty and the same length.

Parameters:

name Session-unique storage name.
keys Ordered list of keys.
values Ordered list of values (one per key).
kind Map (default) or Multimap.
timeout Maximum time to wait for the response.

Exception:

TryllError On server-reported errors or timeout.

function CreateVoiceInput¶

Blocking convenience wrapper over CreateVoiceInputAsync .

VoiceInput Tryll::Client::TryllClient::CreateVoiceInput (
    VoiceInputConfig cfg,
    std::chrono::milliseconds timeout=std::chrono::seconds{30}
)

Parameters:

cfg Configuration (see VoiceInputConfig).
timeout Maximum time to wait for the server's response.

Returns:

A move-only VoiceInput handle.

Exception:

TryllError On server-reported errors (e.g. SttModelLoadFailed) or timeout.

function CreateVoiceInputAsync¶

Asynchronously create a VoiceInput handle backed by the named STT model.

std::future< VoiceInput > Tryll::Client::TryllClient::CreateVoiceInputAsync (
    VoiceInputConfig cfg
)

Parameters:

cfg Configuration including model name, input audio format, and VAD params.

Returns:

Future yielding a move-only VoiceInput handle. Calling future::get() propagates any TryllError.

function DestroyEmbeddedStringStorage¶

Destroy a named EmbeddedStringStorage .

void Tryll::Client::TryllClient::DestroyEmbeddedStringStorage (
    std::string_view name,
    std::chrono::milliseconds timeout=std::chrono::seconds{10}
)

Nodes that already hold the storage via shared_ptr keep it alive; this call only drops the session-level name mapping.

Parameters:

name Name passed to one of the Create variants.
timeout Maximum time to wait for the response.

Exception:

TryllError On server-reported errors or timeout.

function DestroyStringStorage¶

Destroy a named StringStorage on the server.

void Tryll::Client::TryllClient::DestroyStringStorage (
    std::string_view name,
    std::chrono::milliseconds timeout=std::chrono::seconds{10}
)

Nodes that already hold the storage via shared_ptr keep it alive; this call only drops the session-level name mapping.

Parameters:

name Name passed to CreateStringStorage or CreateStringStorageFromFile.
timeout Maximum time to wait for the response.

Exception:

TryllError On server-reported errors or timeout.

function DownloadModel¶

Start downloading a model on the server and block until complete.

void Tryll::Client::TryllClient::DownloadModel (
    std::string_view modelName,
    DownloadProgressCallback onProgress=nullptr,
    std::chrono::milliseconds timeout=std::chrono::minutes{30}
)

Progress frames are delivered via onProgress on the reader thread (invoked synchronously, so keep the callback fast and non-blocking).

Parameters:

modelName Catalog model name from models.json.
onProgress Optional per-chunk progress callback.
timeout Maximum time to wait for DownloadComplete.

Exception:

TryllError On server-reported errors, a DownloadComplete reporting failure, or timeout.

function GetServerBuildConfig¶

Server build configuration ("Debug" | "Release" | "Production"), from ConnectionReady .

std::string Tryll::Client::TryllClient::GetServerBuildConfig () const

function GetServerExePath¶

Canonical path of the server executable, advertised in ConnectionReady .

std::string Tryll::Client::TryllClient::GetServerExePath () const

Use this to verify the session connected to the intended build. Empty when the server predates the identity fields.

function GetServerIdleTimeoutSeconds¶

Server idle-shutdown grace period in seconds (0 when standalone), from ConnectionReady .

std::uint32_t Tryll::Client::TryllClient::GetServerIdleTimeoutSeconds () noexcept const

function GetServerRunId¶

Per-process server run id (UUID), from ConnectionReady .

std::string Tryll::Client::TryllClient::GetServerRunId () const

function GetServerVersion¶

Server version string ( Tryll::kVersion ), fromConnectionReady .

std::string Tryll::Client::TryllClient::GetServerVersion () const

function GetSessionId¶

Server-assigned session identifier.

std::uint64_t Tryll::Client::TryllClient::GetSessionId () noexcept const

Returns:

The session_id received in CreateSessionResponse (0 before CreateSession has completed).

function IsServerManaged¶

True when the server runs in managed (idle-self-exit) mode, from ConnectionReady .

bool Tryll::Client::TryllClient::IsServerManaged () noexcept const

function ListModels¶

Request the list of models known to the server for the session's engine.

std::vector<::Tryll::ModelInfoT > Tryll::Client::TryllClient::ListModels (
    std::chrono::milliseconds timeout=std::chrono::seconds{10}
)

Parameters:

timeout Maximum time to wait for ListModelsResponse.

Returns:

Catalog entries, one per known model.

Exception:

TryllError On server-reported errors or timeout.

function LoadModel¶

Explicitly load and pin a model into memory.

void Tryll::Client::TryllClient::LoadModel (
    std::string_view modelName,
    std::chrono::milliseconds timeout=std::chrono::minutes{5}
)

The model stays in memory until UnloadModel is called, regardless of whether any agents are using it.

Parameters:

modelName Catalog model name from models.json.
timeout Maximum time to wait; loading is slow for large GGUFs.

Exception:

TryllError If the model cannot be resolved or loaded, or on timeout.

function SendDebugCommand¶

Send a dev-only debug command to the server and report the outcome.

DebugCommandResult Tryll::Client::TryllClient::SendDebugCommand (
    std::string_view command,
    std::string_view payload={},
    std::chrono::milliseconds timeout=std::chrono::seconds{5}
)

The server handles this only in non-Production builds with debug_commands.enabled. command is a verb (e.g. "crash"); for crash, payload is the mode token (nullderef / abort / throw / stackoverflow / fastfail; empty defaults to nullderef).

Waits up to timeout for one of: the connection dropping (a fatal verb succeeded → disconnected), an ErrorResponse (e.g. the channel is disabled → errorCode set), or a DebugCommandResponse (acknowledged). Does not throw on a server error — inspect the returned struct instead.

function SetInferenceThrottle¶

Report how hard the server should yield the GPU back to the game (the manual inference throttle knob).

void Tryll::Client::TryllClient::SetInferenceThrottle (
    float level
)

Fire-and-forget: no response, no error surfaced locally. Never sent automatically — a session that never calls this runs unthrottled, identically to a client on an older protocol version.

Parameters:

level 0 = full speed (default), 1 = maximum yielding. Clamped server-side; out-of-range values do not throw here.

function Shutdown¶

Blocking convenience wrapper over ShutdownAsync .

void Tryll::Client::TryllClient::Shutdown (
    std::chrono::milliseconds timeout=std::chrono::seconds{30}
)

Parameters:

timeout Maximum time to wait for a graceful close.

Exception:

TryllError On timeout; socket errors during shutdown are suppressed.

function ShutdownAsync¶

Asynchronously shut down the connection.

std::future< void > Tryll::Client::TryllClient::ShutdownAsync ()

Pending requests are cancelled with TryllError. Idempotent.

Returns:

Future completing when the socket is closed.

function TryllClient [1/3]¶

Tryll::Client::TryllClient::TryllClient (
    const TryllClient &
) = default

function TryllClient [2/3]¶

Tryll::Client::TryllClient::TryllClient (
    TryllClient &&
) noexcept

function UnloadModel¶

Unpin a previously pinned model.

void Tryll::Client::TryllClient::UnloadModel (
    std::string_view modelName,
    std::chrono::milliseconds timeout=std::chrono::seconds{30}
)

Freed immediately if no active contexts reference it; freed lazily when the last one is destroyed.

Parameters:

modelName Catalog model name previously pinned with LoadModel.
timeout Maximum time to wait for the ack.

Exception:

TryllError On timeout.

function operator=¶

TryllClient & Tryll::Client::TryllClient::operator= (
    const TryllClient &
) = default

function operator=¶

TryllClient & Tryll::Client::TryllClient::operator= (
    TryllClient &&
) noexcept

function ~TryllClient¶

Tryll::Client::TryllClient::~TryllClient ()

Public Static Functions Documentation¶

function Connect¶

Blocking convenience wrapper over ConnectAsync .

static TryllClient Tryll::Client::TryllClient::Connect (
    std::string_view host,
    std::uint16_t port,
    std::chrono::milliseconds timeout=std::chrono::seconds{30}
)

Parameters:

host Hostname or IP of the Tryll server.
port TCP port.
timeout Maximum time to wait for ConnectionReady.

Returns:

A connected TryllClient (no session yet — call CreateSession next).

Exception:

TryllError On connection failure, timeout, or a failed connection handshake.

function ConnectAsync¶

Asynchronously connect and wait for ConnectionReady .

static std::future< TryllClient > Tryll::Client::TryllClient::ConnectAsync (
    std::string_view host,
    std::uint16_t port
)

The returned client is connected but has no session yet — call CreateSession before creating agents or issuing other requests.

Parameters:

host Hostname or IP of the Tryll server.
port TCP port the server is listening on.

Returns:

Future yielding a connected TryllClient. Calling future::get() propagates any TryllError raised during the handshake.

function RunAndConnect¶

Spawn a local server and connect to it — recommended for single-process deployments where the client owns the server lifecycle.

static ConnectedSession Tryll::Client::TryllClient::RunAndConnect (
    ManagedServerOptions serverOpts,
    std::chrono::milliseconds connectTimeout=std::chrono::seconds{30}
)

Equivalent to calling ManagedServer::Start followed by Connect, with correct cleanup if Connect throws. The returned ConnectedSession owns both the server process and the TCP session; on destruction it shuts the client down first, then terminates the server.

Parameters:

serverOpts Server launch options. serverOpts.exe is required.
connectTimeout Maximum time to wait for ConnectionReady after the server's TCP port becomes reachable.

Returns:

A ConnectedSession ready to use.

Exception:

TryllError If the server cannot be started, the TCP ready-probe times out, or the session handshake fails.

function RunAndConnectAsync¶

Asynchronous variant of RunAndConnect .

static std::future< ConnectedSession > Tryll::Client::TryllClient::RunAndConnectAsync (
    Client::ManagedServerOptions serverOpts
)

Spawns a std::async task that calls RunAndConnect internally. Useful when the calling thread must not block during startup.

Parameters:

serverOpts Server launch options.

Returns:

Future yielding a ConnectedSession. Calling future::get() propagates any TryllError from the launch or handshake.

The documentation for this class was generated from the following file C:/_tryll/_monorepo3/tryll/clients/cpp/include/tryll/TryllClient.h