Documentation
¶
Overview ¶
Package chatclient provides direct, optional conveniences around the minimal chat protocols and model capabilities defined by Core. Client.Output applies a provider-neutral OutputFormat and strictly decodes naturally completed text. Other completion reasons remain identifiable as OutputCompletionError. Typed output has only a terminal value; callers that need transport deltas use StreamClient.Stream with a required streaming dependency.
NewToolMiddleware covers the deliberately small direct-use path: it advertises a frozen executable Tool set, validates one returned call batch, executes it serially, and performs one follow-up model call. Further tool rounds, retries, concurrency, approval, and durable execution belong to Agent.
Example ¶
package main
import (
"context"
"fmt"
"github.com/Tangerg/scope/core/chat"
"github.com/Tangerg/scope/core/chatclient"
)
func main() {
model := chat.ModelFunc(func(context.Context, *chat.Request) (*chat.Response, error) {
return textResponse("Hello from the model"), nil
})
client, err := chatclient.New(model, chatclient.Config{})
if err != nil {
panic(err)
}
request, err := chat.NewRequest(chat.NewUserMessage(chat.NewTextPart("Hello")))
if err != nil {
panic(err)
}
request.Options.Model = "example"
response, err := client.Call(context.Background(), request)
if err != nil {
panic(err)
}
fmt.Println(response.Text())
}
func textResponse(text string) *chat.Response {
message := chat.NewAssistantMessage(chat.NewTextPart(text))
return &chat.Response{Output: &chat.Output{
Message: &message,
FinishReason: chat.FinishReasonStop,
}}
}
Output: Hello from the model
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNilModel rejects a client whose only required capability is absent. ErrNilModel = errors.New("chatclient: nil model") // ErrNilClient identifies use of a zero-value Client. ErrNilClient = errors.New("chatclient: nil client") )
var ( // ErrInvalidOutputFormat identifies a format that cannot define one request // contract and terminal decoder. ErrInvalidOutputFormat = errors.New("chatclient: invalid output format") // ErrInvalidOutput identifies a response that cannot be decoded under the // requested contract. ErrInvalidOutput = errors.New("chatclient: invalid output") )
var ErrInvalidTemplate = errors.New("chatclient: invalid template")
ErrInvalidTemplate identifies a prompt template that cannot render a valid request.
var ( // ErrInvalidToolMiddleware identifies an executable set or request that // cannot satisfy the middleware's single-batch ownership contract. ErrInvalidToolMiddleware = errors.New("chatclient: invalid tool middleware") )
var ErrNilStreamer = errors.New("chatclient: nil streamer")
ErrNilStreamer rejects a missing streaming dependency at construction.
Functions ¶
func NewToolMiddleware ¶
func NewToolMiddleware(executables ...tool.Tool) (chat.CallMiddleware, error)
NewToolMiddleware keeps direct Client usage useful for one model-requested Tool batch. It advertises a frozen Tool set and validates every invocation before executing any Tool. The accepted batch executes serially, followed by one model call. Runtime failures do not roll back completed Tools. Further rounds and execution policy remain outside this boundary. Only FinishReasonToolCalls authorizes execution; other outcomes pass through.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is an immutable, concurrency-safe composition of chat capabilities and middleware. It does not make an underlying model concurrency safe; callers must still follow the model's concurrency contract.
Call accepts ordinary chat.Request values and snapshots requests before middleware or provider execution. Streaming has its own required capability and construction boundary in StreamClient.
func (Client) Output ¶
func (c Client) Output[T any](ctx context.Context, req *chat.Request, format OutputFormat[T]) (T, error)
Output asks the provider to enforce format, then strictly decodes naturally completed text. Refusal and other non-successful completion reasons return OutputCompletionError. Media and tool requests cannot become typed values. Output never repairs JSON or injects format instructions into the prompt.
Example ¶
package main
import (
"context"
"fmt"
"github.com/Tangerg/scope/core/chat"
"github.com/Tangerg/scope/core/chatclient"
)
func main() {
type answer struct {
Value int `json:"value"`
}
model := chat.ModelFunc(func(context.Context, *chat.Request) (*chat.Response, error) {
return textResponse(`{"value":42}`), nil
})
client, err := chatclient.New(model, chatclient.Config{})
if err != nil {
panic(err)
}
request, err := chat.NewRequest(chat.NewUserMessage(chat.NewTextPart("What is six times seven?")))
if err != nil {
panic(err)
}
result, err := client.Output(context.Background(), request, chatclient.JSON[answer]())
if err != nil {
panic(err)
}
fmt.Println(result.Value)
}
func textResponse(text string) *chat.Response {
message := chat.NewAssistantMessage(chat.NewTextPart(text))
return &chat.Response{Output: &chat.Output{
Message: &message,
FinishReason: chat.FinishReasonStop,
}}
}
Output: 42
type Config ¶
type Config struct {
CallMiddleware []chat.CallMiddleware
}
Config supplies synchronous middleware. The first entry is the outermost wrapper. New consumes the slice during construction and does not retain it.
type JSONSchemaConfig ¶ added in v0.13.0
JSONSchemaConfig supplies the stable identity of a schema derived from T.
type OutputCompletionError ¶ added in v0.15.0
type OutputCompletionError struct {
FinishReason chat.FinishReason
Refusal string
}
OutputCompletionError preserves a provider outcome that cannot become the requested typed value. It unwraps to ErrInvalidOutput; callers may inspect FinishReason and Refusal without parsing an error message.
func (*OutputCompletionError) Error ¶ added in v0.15.0
func (o *OutputCompletionError) Error() string
func (*OutputCompletionError) Unwrap ¶ added in v0.15.0
func (*OutputCompletionError) Unwrap() error
type OutputFormat ¶
type OutputFormat[T any] struct { // contains filtered or unexported fields }
OutputFormat couples a provider-neutral request contract with the decoder for its complete response. Pass one to Client.Output.
func JSON ¶
func JSON[T any]() OutputFormat[T]
JSON selects provider-native JSON output and rejects unknown object members when decoding T.
func JSONSchema ¶
func JSONSchema[T any](config JSONSchemaConfig) (OutputFormat[T], error)
JSONSchema returns a result format coupled to the named contract derived from T.
func Text ¶
func Text() OutputFormat[string]
Text selects provider-native text output without post-processing.
type StreamClient ¶ added in v0.17.0
type StreamClient struct {
// contains filtered or unexported fields
}
StreamClient owns a required streaming capability and its middleware chain. It is immutable; concurrent use requires a concurrency-safe Streamer. It does not implement chat.Model or require an unused synchronous capability.
func NewStreamClient ¶ added in v0.17.0
func NewStreamClient(streamer chat.Streamer, config StreamConfig) (StreamClient, error)
NewStreamClient rejects absent streaming dependencies before any work starts.
func (StreamClient) Stream ¶ added in v0.17.0
func (s StreamClient) Stream(ctx context.Context, request *chat.Request) iter.Seq2[*chat.ResponseDelta, error]
Stream snapshots the request at invocation. Provider work remains lazy until iteration; stopping iteration synchronously releases the provider resources.
Example ¶
package main
import (
"context"
"fmt"
"iter"
"github.com/Tangerg/scope/core/chat"
"github.com/Tangerg/scope/core/chatclient"
)
func main() {
streamer := chat.StreamerFunc(func(context.Context, *chat.Request) iter.Seq2[*chat.ResponseDelta, error] {
return func(yield func(*chat.ResponseDelta, error) bool) {
if !yield(delta("Hello ", ""), nil) {
return
}
yield(delta("stream", chat.FinishReasonStop), nil)
}
})
client, err := chatclient.NewStreamClient(streamer, chatclient.StreamConfig{})
if err != nil {
panic(err)
}
request, err := chat.NewRequest(chat.NewUserMessage(chat.NewTextPart("Hello")))
if err != nil {
panic(err)
}
for response, streamErr := range client.Stream(context.Background(), request) {
if streamErr != nil {
panic(streamErr)
}
fmt.Print(response.Text())
}
fmt.Println()
}
func delta(text string, reason chat.FinishReason) *chat.ResponseDelta {
return &chat.ResponseDelta{Parts: []chat.PartDelta{chat.NewTextDelta(text)}, FinishReason: reason}
}
Output: Hello stream
type StreamConfig ¶ added in v0.17.0
type StreamConfig struct {
Middleware []chat.StreamMiddleware
}
StreamConfig supplies streaming middleware. The first entry is the outermost wrapper. NewStreamClient consumes the slice without retaining it.
type Template ¶
type Template struct {
// contains filtered or unexported fields
}
Template is an immutable, parsed prompt template safe for concurrent use. Parsing fails on missing map keys instead of emitting placeholder text; Require inspects the complete parse tree, including pipelines and branches. Root field references such as $.Query are recognized alongside .Query. Message projections validate the rendered protocol value and preserve media order without retaining per-render variables in Template.
Example ¶
package main
import (
"fmt"
"github.com/Tangerg/scope/core/chatclient"
)
func main() {
prompt, err := chatclient.ParseTemplate("Explain {{.Topic}} in one sentence.")
if err != nil {
panic(err)
}
message, err := prompt.UserMessage(struct{ Topic string }{Topic: "Go interfaces"})
if err != nil {
panic(err)
}
fmt.Println(message.Text())
}
Output: Explain Go interfaces in one sentence.
func ParseTemplate ¶
ParseTemplate rejects templates whose variable paths or functions could make rendering depend on ambient state.
Source Files
Directories