agent library

Public entry point for the Syni agent layer — install lifecycle, model management, persona binding, and chat orchestration over the local runtime.

The host SDK (synheart_core) consumes this and wraps it with the four-authority gate + HSI context builder, re-exposing it as Synheart.syni. App developers should depend on synheart_core, not package:syni directly.

Classes

SyniAgent
Orchestrates an installed, persona-bound Syni: install lifecycle, model management, and chat over the local runtime worker isolate.
SyniAttemptDiagnostic
One generation attempt's failure.
SyniChatDelta
An incremental token chunk emitted during generation.
SyniChatEvent
One event in a streaming chat response. Discriminated union over incremental deltas and the final structured response.
SyniChatFinal
The final parsed response. Always emitted exactly once at the end of a successful stream.
SyniChatResponse
A completed Syni response.
SyniCloudConfig
SyniCloudModel
A server-side model — runs in the Syni cloud. serviceModelId is the id the service routes to internally; the client never needs the provider/model details.
SyniFallbackDiagnostics
Root-cause context for a fallback. prompt / rawOutput are populated only when the runtime ran with capture_diagnostics enabled (a debug opt-in); they carry user + HSI data, so treat them as sensitive.
SyniGenerationProfile
Per-turn inference controls. Omitted values retain the runtime preset.
SyniInferenceMetric
Typed view over the runtime's telemetry snapshot (syni_telemetry_json).
SyniInstalled
Successfully installed. The runtime engine has loaded the model and is ready to receive chat calls.
SyniInstaller
Downloads + verifies a model (GGUF + its tokenizer.json sibling). Emits progress via the supplied callback. Returns the final on-disk model path.
SyniInstallFailed
Install failed. reason is human-readable; cause is the underlying exception when available.
SyniInstalling
Install in progress. progress is in [0.0, 1.0]; stage explains which sub-step is running.
SyniInstallState
SyniLocalModel
An on-device model — runs via the candle runtime. spec is what SyniAgent.install needs to download + load it.
SyniModelCatalog
Fetches + caches the Syni model catalog from the Syni cloud GET /v1/models.
SyniModelOption
One entry in the Syni model catalog — a local (on-device GGUF) or cloud (server-side) model. The two are peers: the client's router picks among them using optimizedFor tags, requires constraints, and the active execution mode.
SyniModels
V1 model catalog. Replace with a server-signed manifest fetched from the remote model catalog once that exists. Pinned SHA-256 values come from the HuggingFace LFS x-linked-etag header, which is the underlying file's SHA-256 for LFS-stored objects.
SyniModelSpec
SyniNotInstalled
No model downloaded, no persona bound. Default state.
SyniPersona
SyniRuntimeCapabilities
SyniSpecPersona
Loads a SyniPersona from a bundled syni-spec JSON asset.
SyniTaskContract
Host-owned task contract for one turn. This is stable app intent, not text authored by the user, so the SDK places it at system authority.
SyniTurnDelta
Text the model has just written. The runtime's own chunking: a token or a few; concatenate them in order.
SyniTurnEvent
An event from SyniAgent.turnStream.
SyniTurnFinal
The finished turn, exactly once, last.
SyniTurnMessage
SyniTurnProvenance
SyniTurnRequest
Versioned, authority-aware turn request.
SyniTurnResult
Completed typed turn plus routing and native provenance information.

Enums

SyniExecutionMode
Where a chat call should run.
SyniInstallStage
SyniResponseKind
Which EngineResponse variant the runtime returned.
SyniTurnBackend
SyniTurnMessageRole
Role of one prior conversational turn. System policy is deliberately not a dialogue role; it is supplied separately on SyniTurnRequest.systemPolicy.

Exceptions / Errors

SyniCloudException
SyniInstallException
SyniRuntimeError
Thrown when the runtime, model, or inference call fails.
SyniSpecPersonaException