Documentation
¶
Overview ¶
Package chatmodel defines common chat I/O types, context helpers, and parser interfaces used across the project.
Highlights
- ChatContext stores user/chat/run identifiers and metadata for flows.
- Input/Output models (`InputRequest`, `OutputResult`) implement `ContentProvider` to unify message handling.
- `OutputParser[T]` abstracts parsing LLM output into typed results.
Example: Create and propagate ChatContext
ctx := context.Background()
chat := NewChatContext("user-123", "", nil) // auto-generates ChatID + RunID
ctx = WithChatContext(ctx, chat)
// Later in a worker goroutine:
bg := NewFromContext(ctx) // preserves the ChatContext on a new background context
_ = bg
Example: Wrap user input/output
in := NewInputRequest("How is the weather in Paris?")
out := NewOutputResult("It’s 22°C and sunny in Paris today.")
_ = in.GetContent()
_ = out.GetContent()
Example: Use an OutputParser with an encoder (see encoding package for more)
type Weather struct { City string; TempC int }
parser, _ := encoding.NewTypedOutputParser(Weather{}, encoding.ModeJSONSchema)
_ = parser.GetFormatInstructions() // embed in prompt
res, _ := parser.Parse(`{"City":"Paris","TempC":22}`)
_ = res // *Weather
Index ¶
- Variables
- func GetActionID(ctx context.Context) string
- func NewChatID() string
- func NewFromContext(ctx context.Context) context.Context
- func SetChatID(ctx context.Context, chatID string) (context.Context, error)
- func Stringify(s any) string
- func ToBytes(s any) []byte
- func WithActionID(ctx context.Context, actionID string) context.Context
- func WithChatContext(ctx context.Context, chatCtx ChatContext) context.Context
- type BaseClarificationResult
- type ChatContext
- type ContentProvider
- type FewShotExample
- type FewShotExamples
- type IBaseResult
- type InputParser
- type InputRequest
- type MCPInputRequest
- type OutputParser
- type OutputResult
- type String
- type Stringer
Constants ¶
This section is empty.
Variables ¶
var ( // ErrFailedUnmarshalInput indicates input could not be parsed into the // expected request type; typically surfaced by InputParser or an output // parser handling tool inputs. ErrFailedUnmarshalInput = errors.New("failed to unmarshal input: check the schema and try again") // ErrFailedUnmarshalOutput indicates model output could not be parsed into // the expected typed result, often due to deviating from format // instructions. ErrFailedUnmarshalOutput = errors.New("failed to unmarshal output: check the schema and try again") )
var (
ErrInvalidChatContext = errors.New("invalid chat context")
)
Functions ¶
func GetActionID ¶ added in v0.18.137
GetActionID retrieves the Action ID from the context
func NewChatID ¶
func NewChatID() string
NewChatID generates a new chat ID using the flake ID generator.
func NewFromContext ¶ added in v0.5.26
NewFromContext returns new Background context with ChatContext from incoming context. This is useful for passing the chat context to the background context of a service.
func SetChatID ¶ added in v0.3.11
SetChatID updates the chat ID on the ChatContext already carried by ctx, so an inbound request can continue an existing conversation. Returns ErrInvalidChatContext when ctx carries no chat context.
Note that this mutates the shared ChatContext rather than deriving a new one.
func Stringify ¶
Stringify returns a string representation for values implementing `Stringer` or `ContentProvider`; otherwise it falls back to JSON marshaling.
func ToBytes ¶
ToBytes returns bytes for values implementing `Stringer` or `ContentProvider`, otherwise it returns the JSON-encoded bytes.
func WithActionID ¶ added in v0.18.137
WithActionID returns a new context with Action ID value. This is used to identify the action in the multi-step LLM flow.
func WithChatContext ¶
func WithChatContext(ctx context.Context, chatCtx ChatContext) context.Context
WithChatContext returns a new context with ChatContext value
Types ¶
type BaseClarificationResult ¶
type BaseClarificationResult struct {
Confidence string `` /* 161-byte string literal not displayed */
Clarification string `` /* 209-byte string literal not displayed */
Reasoning string `` /* 128-byte string literal not displayed */
}
BaseClarificationResult holds common clarification-related fields that result types can embed to encourage follow-up questions or provide confidence.
func (*BaseClarificationResult) SetClarification ¶ added in v0.3.14
func (b *BaseClarificationResult) SetClarification(clarification string)
SetClarification sets the clarification. AssistantTool uses this to hand a failure back to a calling assistant as recoverable data rather than an error.
func (*BaseClarificationResult) SetConfidence ¶ added in v0.3.14
func (b *BaseClarificationResult) SetConfidence(confidence string)
SetConfidence sets the confidence level. Satisfies IBaseResult.
func (*BaseClarificationResult) SetReasoning ¶ added in v0.3.14
func (b *BaseClarificationResult) SetReasoning(reasoning string)
SetReasoning sets the reasoning. Satisfies IBaseResult.
type ChatContext ¶
type ChatContext interface {
// GetUserID retrieves the user ID from the context.
// User ID is used to store message history for the user.
GetUserID() string
// GetChatID retrieves the chat ID from the context.
// Chat ID is used to store message history for the chat.
GetChatID() string
// SetChatID updates the chat ID in the context
SetChatID(id string)
// AppData returns immutable app data
AppData() any
// GetMetadata retrieves metadata by key
GetMetadata(key string) (value any, ok bool)
// SetMetadata sets metadata by key
SetMetadata(key string, value any)
// GetRunID returns the run ID for the chat
GetRunID() string
// SetRunID updates the run ID in the context
SetRunID(id string)
// GetOrgID retrieves the org ID from the context.
// This is also used in metrics and message history storage.
// Used by some providers to identify the organization for multi-tenant use cases.
GetOrgID() string
// SetOrgID updates the org ID in the context for multi-tenant use cases.
SetOrgID(id string)
}
ChatContext is the context for the LLM flow.
ChatID is the ID of the chat which is persisted across runs. RunID identifies a single run of the LLM flow, usually it's a random ID.
func GetChatContext ¶
func GetChatContext(ctx context.Context) ChatContext
GetChatContext retrieves the ChatContext from the context
func NewChatContext ¶
func NewChatContext(userID, chatID string, appData any) ChatContext
NewChatContext constructs a new ChatContext. If chatID is empty, a new one is generated. The returned context also gets a fresh RunID. AppData is stored as immutable payload and can be retrieved via AppData().
type ContentProvider ¶
type ContentProvider interface {
// GetContent gets the content of the message
GetContent() string
}
ContentProvider is an interface for providing content from a message.
type FewShotExample ¶
FewShotExample describes a single prompt/completion pair for few-shot prompting helpers found in the prompts package.
type FewShotExamples ¶
type FewShotExamples []FewShotExample
FewShotExamples is a collection of FewShotExample.
type IBaseResult ¶ added in v0.3.14
IBaseResult defines the common setters supported by result types that embed BaseClarificationResult.
type InputParser ¶ added in v0.3.14
type InputParser interface {
// ParseInput parses the input string and populates the struct fields.
ParseInput(input string) error
}
InputParser is an interface for parsing input strings into structured data.
type InputRequest ¶ added in v0.3.12
type InputRequest struct {
// Input is the message sent by the user to the assistant.
Input string `json:"input" yaml:"input" jsonschema:"title=Input,description=The message sent by the user to the assistant."`
}
InputRequest represents the input from the user to the AI assistant.
func NewInputRequest ¶ added in v0.3.12
func NewInputRequest(chatMessage string) *InputRequest
NewInputRequest constructs an InputRequest from a raw user message.
func (InputRequest) GetContent ¶ added in v0.3.16
func (o InputRequest) GetContent() string
GetContent returns the user input for use in chat history or logging.
func (InputRequest) JSONSchemaExtend ¶ added in v0.4.19
func (o InputRequest) JSONSchemaExtend(schema *jsonschema.Schema)
JSONSchemaExtend adds the title and description to the generated schema.
func (*InputRequest) ParseInput ¶ added in v0.3.14
func (o *InputRequest) ParseInput(input string) error
ParseInput decodes the request from raw JSON, tolerating the prose and code fences models add. Satisfies InputParser.
type MCPInputRequest ¶ added in v0.3.12
type MCPInputRequest struct {
ChatID string `json:"chatID" yaml:"chatID" jsonschema:"title=Chat ID,description=The unique identifier for the chat session."`
// Input is the message sent by the user to the assistant.
Input string `json:"input" yaml:"input" jsonschema:"title=Input,description=The message sent by the user to the assistant."`
}
MCPInputRequest represents the MCP input from the user to the AI assistant.
func (MCPInputRequest) JSONSchemaExtend ¶ added in v0.4.19
func (o MCPInputRequest) JSONSchemaExtend(schema *jsonschema.Schema)
JSONSchemaExtend adds the title and description to the generated schema.
func (*MCPInputRequest) ParseInput ¶ added in v0.3.14
func (o *MCPInputRequest) ParseInput(input string) error
ParseInput decodes the request from raw JSON, tolerating the prose and code fences models add. Satisfies InputParser.
type OutputParser ¶
type OutputParser[T any] interface { // Parse parses the output of an LLM call. // If the assistant fails to parse the input, it should return ErrFailedUnmarshalInput error. Parse(text string) (*T, error) // GetFormatInstructions returns a string describing the format of the output. GetFormatInstructions() string // Type returns the string type key uniquely identifying this class of parser Type() string }
OutputParser is an interface for parsing the output of an LLM call.
type OutputResult ¶ added in v0.3.12
type OutputResult struct {
// contains the markdown-enabled response generated by the chat assistant.
Content string `json:"content" yaml:"content" jsonschema:"title=Response Content,description=The content returned by assistant or tool."`
}
OutputResult represents the response generated by the chat assistant.
func NewOutputResult ¶ added in v0.3.12
func NewOutputResult(chatMessage string) *OutputResult
NewOutputResult constructs an OutputResult from a raw assistant message.
func (OutputResult) GetContent ¶ added in v0.3.12
func (o OutputResult) GetContent() string
GetContent returns the assistant/tool content for use in chat history or logging.
type String ¶ added in v0.2.10
type String struct {
// contains filtered or unexported fields
}
String is a simple string type that implements the ContentProvider interface.
func (String) GetContent ¶ added in v0.2.10
GetContent returns the underlying string content. Satisfies ContentProvider.
func (*String) ParseInput ¶ added in v0.3.14
ParseInput sets the string value from raw input. Satisfies InputParser.