host

package
v0.10.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 1 Imported by: 0

Documentation

Overview

Package host defines the surface that an interpreted chat policy needs from its compiled driver. The policy code depends only on this interface; the driver constructs a concrete implementation and passes it into the policy's entrypoint, keeping transport details out of the policy.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ContextBuilder added in v0.10.0

type ContextBuilder interface {
	ContextFor(ctx context.Context, queryText string) []byte
}

ContextBuilder is the context-taking form of Host.Context. ctx is for any I/O building the messages array does (e.g. retrieval for a user-context block): an implementation hands it on, so that I/O can run under ctx's span, deadline and cancellation, and need not check ctx itself. Which I/O receives ctx is the implementation's, and ctx's deadline and cancellation stop that I/O only where the I/O honours them. It is separate from Host, as ContextSender is, so adding it breaks no existing Host implementation. An interpreted policy reaches it by type-asserting its host.Host, which works only if the consumer injects this symbol.

type ContextSender added in v0.9.0

type ContextSender interface {
	SendContext(ctx context.Context, contextWindow []byte, tier string) ([]byte, []byte, error)
	SendStreamContext(ctx context.Context, contextWindow []byte, tier string, onSegment func(string)) ([]byte, []byte, error)
}

ContextSender is the context-taking form of Host's Send and SendStream. ctx parents the span each model request produces and bounds the call: its deadline and cancellation apply, and the driver's own ceiling (300 s for driver.Host) still applies on top. ctx is a context.Context, not Host.Context(queryText), which returns the messages array; ContextBuilder is that method's ctx-taking form. ContextSender is separate from Host so that adding it breaks no existing Host implementation. An interpreted policy reaches it by type-asserting its host.Host, which works only if the consumer injects this symbol.

type Host

type Host interface {
	// Send takes the already-serialized `messages` array and a tier
	// ("fast" | "deep") and returns (content, reasoning, error). reasoning is
	// empty when the served model doesn't emit it.
	Send(contextWindow []byte, tier string) ([]byte, []byte, error)

	// SendStream streams the response, calling onSegment whenever a boundary
	// is reached (sentence/paragraph punctuation with enough accumulated
	// text). Returns the fully assembled (content, reasoning) when the stream
	// completes. onSegment is called on the goroutine of the caller —
	// implementations must not block it for long.
	SendStream(contextWindow []byte, tier string, onSegment func(string)) ([]byte, []byte, error)

	// SystemPrompt returns the current system prompt. The driver reloads it from
	// its backing file only when that file's modification time changes, so the
	// policy can call this every turn cheaply.
	SystemPrompt() string

	// Speak renders text to speech via the driver's TTS server and plays it,
	// using the given voice (e.g. "M1") and speed (0.7..2.0). The policy decides
	// whether to call it and with what settings; the driver owns synthesis and
	// playback. Best-effort: errors are the driver's to report and must not
	// break a turn.
	Speak(text []byte, voice string, speed float64) error

	// SpeakSync is like Speak but blocks until playback finishes, so callers can
	// play several clips in sequence without overlap (e.g. the /voicetest voice
	// comparison).
	SpeakSync(text []byte, voice string, speed float64) error

	// Remember appends a message (role "user" or "assistant") to the running
	// conversation history the driver keeps, so later turns can refer back to
	// earlier ones. This history is durable host state — it survives /reload.
	Remember(role string, content []byte)

	// Context returns the messages array to send: the current system prompt,
	// then any user-context block the driver was configured with, then the
	// remembered history, as a JSON array ready for Send. queryText is the
	// current turn's text, handed to that user-context provider so its block
	// can depend on it (e.g. retrieval keyed on the query); pass "" when there
	// is none. Which ctx that provider runs under is the implementation's;
	// ContextBuilder.ContextFor takes the ctx explicitly.
	Context(queryText string) []byte

	// Forget drops the most recently remembered message. The policy uses it to
	// roll back a user turn whose send failed, so history stays consistent (and
	// an over-large context doesn't wedge every subsequent turn).
	Forget()

	// CancelQueued drops all clips waiting in the speech queue without rendering
	// them. Any clip already being rendered plays to completion. Call alongside
	// Forget() so orphaned TTS segments from a failed streaming turn don't play
	// after the turn has been rolled back.
	CancelQueued()

	// LastAnswer returns the content of the most recent assistant message, or
	// empty if there is none. Used by "/repeat" with no modifier.
	LastAnswer() []byte

	// Clear discards all remembered history (the /clear command; also used by
	// /compact to swap the full history for a summary).
	Clear()
}

Host is the capability set the chat policy calls into. Today that's just LLM transport by tier — add methods here as the policy needs more from the driver.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL