Documentation
¶
Overview ¶
Package output provides stream-first routing of LLM output to typed sinks.
Use Route or RouteAgent to tee a niro.Stream into a sink so that response text, thinking/reasoning, tool calls, and custom frames are dispatched as they arrive without buffering. The same stream is still forwarded to the caller so existing consumers see identical frames in the same order.
Agent identity ¶
RouteAgent injects the agent name into the context passed to every callback. Retrieve it with AgentFromContext. This allows sinks to attribute frames to the correct agent even when multiple agents stream in parallel through the same sink.
Sinks ¶
Set only the callback fields you need. Nil callbacks are skipped. Return a non-nil error from any callback to abort the stream.
Convention for thinking: providers emit niro.KindCustom frames with Custom.Type "thinking" or "reasoning" and Data as string (or incremental). Route calls OnThinking for those; Sink.OnText is used for normal response text.
Index ¶
- func AgentFromContext(ctx context.Context) string
- func ContextWithAgent(ctx context.Context, agent string) context.Context
- func Route(ctx context.Context, src *niro.Stream, sink *Sink) *niro.Stream
- func RouteAgent(ctx context.Context, src *niro.Stream, sink *Sink, agent string) *niro.Stream
- type Sink
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AgentFromContext ¶
AgentFromContext returns the agent name stored by ContextWithAgent (or "").
func ContextWithAgent ¶
ContextWithAgent returns a child context carrying the agent name.
func Route ¶
Route tees src into sink and returns a new stream that forwards all frames in order. Equivalent to RouteAgent(ctx, src, sink, "").
func RouteAgent ¶
RouteAgent tees src into sink with agent attribution. If agent is non-empty, the context passed to every callback carries the agent name (retrievable via AgentFromContext) and Sink.OnAgentStart is called before the first frame. Frames are dispatched to the sink's callbacks (by kind and, for KindCustom, by Type) as they are read; then the frame is emitted to the returned stream. Single-pass, no extra buffering — stream-first for minimal latency.
If any sink callback returns a non-nil error, the returned stream is closed with that error. OnEnd is called when the source stream is exhausted without error (sink sees usage there).
Types ¶
type Sink ¶
type Sink struct {
// OnAgentStart is called once at the beginning of routing when an agent name is
// provided via [RouteAgent]. Use it to log or display which agent is about to stream.
OnAgentStart func(ctx context.Context, agent string) error
// OnText is called for each [niro.KindText] frame (main assistant response for the user).
OnText func(ctx context.Context, text string) error
// OnThinking is called for [niro.KindCustom] frames with Type "thinking" or "reasoning".
// Use to show extended thinking / reasoning in the UI.
OnThinking func(ctx context.Context, text string) error
// OnToolCall is called for each [niro.KindToolCall] frame (e.g. to show "Using tool X" in UI).
OnToolCall func(ctx context.Context, call *niro.ToolCall) error
// OnToolResult is called for each [niro.KindToolResult] frame (tool execution result). Use to show or log tool output.
OnToolResult func(ctx context.Context, result *niro.ToolResult) error
// OnCustom is called for other [niro.KindCustom] frames (e.g. handoff, summaries).
OnCustom func(ctx context.Context, typ string, data any) error
// OnEnd is called when the stream ends successfully (after last frame, before close).
// Usage is the accumulated usage; resp may be nil when the provider didn't set metadata.
OnEnd func(ctx context.Context, usage niro.Usage, resp *niro.ResponseMeta) error
}
Sink receives LLM output as it streams. All fields are optional; nil callbacks are not called. Implementations should be fast and non-blocking; dispatch heavy work to another goroutine.
Source Files